## Summary
Reported as "deliver_files is broken". It is not: **the tool never ran.**
Every `deliver_files` call on one install was refused before dispatch -- five in a row in a single session -- and nothing was ever delivered:
```
Error: Invalid parameters for tool 'deliver_files': files should be array
```
What the model sent was the array, spelled as a string:
```json
{"files": "[{\"path\": \"...poster.png\", \"title\": \"...\"}]", "message": "..."}
```
`cast_params` already forgives that spelling for every scalar type -- `"3"` for an integer, `"true"` for a boolean -- and did not for arrays or objects, which are exactly the types a model is most likely to stringify.
## Type
- [x] Fix
- [ ] Feature
## The edge of the forgiving is the design
When the value is a string, try `json.loads`, and take the result **only if it is the type the schema asked for**. A string that is not JSON, or is JSON of the wrong shape, is returned unchanged so the validator still names the real problem -- the point is to widen what is accepted, not to swallow a type error.
**Nothing here can raise.** Turning "your argument has the wrong type" into a traceback would be worse than the refusal it replaces, so the parse is wrapped and failure falls through.
**A `type: "string"` field is never parsed.** JSON is ordinary text in a message body or a file's content, and replacing it would hand the tool something it never asked for. Two independent things prevent it today (the string branch returns before the parse is reached, and the parse only wins on a type match), which is why the case pinning it is a tripwire rather than a load-bearing assertion -- said so in its own docstring rather than left to look like coverage.
## Not just deliver_files
Six built-in tools declare an array or object parameter and were all exposed:
| tool | parameter |
|---|---|
| `deliver_files` | `files` |
| `ask_user` | `questions` |
| `image_generate` | `images` |
| `message` | `media` |
| `create_playbook` | `skills` |
| `video_generate` | `params` |
The same failure was already seen from the other side: `acp_client/acp_agent.py` records `update_task_state` and `operations should be array` from a real dispatch.
## Verification
```
make lint-python ruff check + ruff format --check, 1850 files
make lint-imports 9 contracts kept, 0 broken
pytest tests/ 19,699 passed, 7 failed (all pre-existing, see below)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots -- no user-facing string
**End to end, through the real tool**, with the exact payload that failed five times in production:
```
files sent as: str -> [{"path": ".../poster.png", "title": "..."}]
returned: Delivered 1 file(s): poster.png (72 B).
still "should be array": False
registered in the store: True
```
Twelve cases, five mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the whole branch (the old behaviour) | 3 |
| raise instead of falling through on a parse failure | 5 |
| accept the parse whatever type it yielded | 1 |
| do not re-cast the parsed value, so items are not cast | 1 |
| widen the tuple to include `string` | **survived -- unreachable** |
The last is worth stating rather than hiding: that mutation cannot change behaviour, because the `type == "string"` branch returns earlier and the type check would refuse the result anyway. I also tried moving the new block above that branch, alone and combined with widening the tuple, and neither reddens anything either. The invariant holds by construction; the case that documents it says so.
**Pre-existing failures, checked against the base.** 7 failed in the full run, all in `tests/test_security_network.py` (`test_a_redirect_to_a_dangerous_address_is_refused` and siblings). Running that file alone on this same tree gives 4 -- the count is order-dependent -- and the change touches only `raven/agent/tools/params.py` plus a new test file, neither of which `raven/security/network.py` imports. The failures are the box's resolver: it returns poisoned answers roughly half the time, which I measured separately (`en.wikipedia.org` came back as `2001::1` on 3 of 6 lookups). Not introduced here, and worth someone's attention on its own.
## Risk
- [x] Security impact considered -- widens what reaches a tool's own validation, not what bypasses it. A parsed value is still validated against the same schema, and a parse that yields the wrong type is refused exactly as before
- [x] Backward compatibility considered -- a call that worked before takes the identical path; the new branch is reached only by a `str` where an array or object is declared, which previously always failed
- [x] Rollback path is clear -- single-commit revert
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over `git diff origin/main...HEAD`.
- **1 (a write location moved)** -- nothing moved; a branch was added to an existing dispatch on `target_type`. Grepped every caller of `cast_params`: the registry is the only one, and it runs `validate_params` right after, which is the reader this affects.
- **2 (a value with several entry points)** -- the cast is the single funnel every tool argument passes through, which is why the fix belongs here and not in `deliver_files`.
- **3 (a guard)** -- checked both directions: what it wrongly lets through (JSON of the wrong type, non-JSON text -- both refused, with cases) and what it wrongly refuses (a real list, unaffected, with a case).
- **4 (tests)** -- five mutations above, one honestly reported as unreachable. Failing-ID sets diffed against the base rather than counts.
- **6 (stale text)** -- the module docstring enumerated what is coerced ("a string that should be an integer"); it now names arrays and objects too. Grepped the tracked tree for other statements of the rule: none.
- **9 (error handling)** -- the new path adds one way to end and it is caught: `json.loads` raises `ValueError` on bad text and `TypeError` on a non-string, and both fall through to the untouched value.
- **11** -- `git ls-files | grep -c node_modules` is 0; the commit-message gate was run, not eyeballed.
Not applicable, with reasons: **3b, 3c, 3d, 3e** (no tool schema produced, no state moved, one lane, no assertion lost its symbol); **4b, 4c, 4d** (no platform branch, no shell, no rendered number); **5, 5b** (no dependency; `json` is stdlib and already imported across this package); **6b, 6c** (no backup, no generated artifact); **7, 7b** (nothing on disk); **8** (no asset, no secret); **10** (no prompt text).
## Deliberately not fixed
The error text still ends with `[Analyze the error above and try a different approach.]`, and the model plainly did not -- it sent the same shape five times. A message naming the expected spelling (`files must be a JSON array, not a string containing one`) would give it something to act on. That is a change to the registry's error surface, affects every tool, and deserves its own argument.
## Moved from !594
Opened on a compliant source branch. AGENTS.md 2.1 asks for a 3-5 word snake_case description and the previous branch had seven; GitLab cannot change an existing merge request's source branch, so the change moves rather than the name.
Same commits, rebased onto `c2a9768f`. Both code findings from the review on !594 are already in them -- `RecursionError` caught with its regression case, and the implementation comment reduced to the two non-obvious reasons. Nothing else changed, so that review carries.
## Summary
Overhaul the interactive `raven trajectory` browser end to end, fixing
every
issue from real-terminal testing:
- Navigation: every screen opens with a help area under its title (page
purpose plus "[Key] function" hotkey hints, rendered in a new readable
help color). Esc walks one level up (action -> attempt -> session); on
the
top-level session screen Esc stays put and quitting is Ctrl+C only,
which
prints a single exit notice. Esc inside a running action cancels just
that
action through a dedicated exception at the action boundary, so the back
sentinel can never reach a conversion or the data layer; a cancelled
report keeps its pre-confirm bundle-and-pin side effects (the existing
declined-report contract). Back/Exit menu entries are gone; answered
prompts erase themselves and navigation is echoed as breadcrumb lines
with markup-escaped untrusted text.
- Tables: the session list is TITLE | ATTEMPTS | LAST ACTIVITY and the
attempt list is # | STARTED | TURNS | SPANS | VERDICT | PIN | MERGED |
PREVIEW with green check cells. Time cells keep the year. The layout is
budgeted per screen build from the live terminal width (row indent, a
safety margin, and inter-column gaps are all part of the math); PREVIEW
drops as a whole column when it no longer fits, and below the dynamic
minimum width the tightest layout is kept while the renderer clips
overlong lines at the terminal edge. Every dynamic cell passes a
single-line sanitization gate before width math (verdict sidecars only
guarantee a non-empty string), cells are measured and truncated by
terminal display width (CJK is 2 cells), and fixed column widths always
fit their headers.
- Space preview: Space on an attempt row prints that attempt's per-turn
input/output previews, collected in the same snapshot scan and sorted by
a fully-stringified key so ordering never follows log source order (the
table PREVIEW cell derives from the same sorted collection). Any key,
arrow keys included, returns with the cursor kept on the row; the waiter
passes the terminal's CPR reply through to the renderer instead of
treating it as a keypress, and Ctrl+C keeps the browser-wide cancel.
- Merge hotkey: with two or more attempts, m/M opens the multi-select
merge
(advertised in the help line; the old "Merge attempts" menu entry is
gone). The checkbox screen carries its own help line for toggle,
confirm,
and cancel. A single attempt neither binds nor advertises the key.
- Theme and feel: new success (green check) and help (readable hint
text)
colors in both palettes, all WCAG AA on their backgrounds; a lone ESC is
flushed after 50ms instead of prompt_toolkit's 0.5s default, removing
the
laggy Esc feel.
The data layer is untouched: changes are confined to
raven/cli/trajectory_browse.py, raven/cli/_theme.py, and their tests.
The
id-taking subcommands (raven trajectory save/list/...) behave as before.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `COLORTERM=truecolor uv run pytest tests/test_cli_theme.py
tests/test_cli_trajectory_browse.py
tests/test_cli_trajectory_commands.py -q` -> 220 passed
- `COLORTERM=truecolor uv run pytest tests/ --ignore=tests/integration
-q` -> 6917 passed; the 10 failed + 20 errors are the pre-existing
environment-dependent set, identical file-by-file on a clean main
checkout (cron, everos server, config loader, tracing viewer)
- `uv run ruff check` and `uv run ruff format --check` on the four
touched files -> clean
- PTY smoke on a CPR-answering pseudo terminal at 100 and 58 columns:
full flow (preview, merge cancel, action screen, staged Esc backout,
Ctrl+C quit) and the narrow-width degradation contract
- New coverage includes real pipe-input key-binding tests (Esc on all
four prompt kinds, Space/m/M hits, waiter key paths with CPR
pass-through), table budget/clipping boundaries at the computed minimum
width, and corrupt verdict/timestamp corpora
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- The interactive browser's look and key protocol change wholesale (that
is
the point of this PR): Esc no longer quits from the top level (Ctrl+C
does), Back/Exit entries are gone, and lists render as tables. The
machine-facing subcommands and the trajectory data layer are untouched.
- Rollback: revert the squash commit; the browser returns to the
previous
interaction wholesale, no data migration involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
raven.evolver was 13.6k lines with no importer in the runtime and its own
entry point: a tool that drives raven against a benchmark, not a part of what
raven ships. It becomes evolver/ beside raven/ in the checkout, still imports
raven as a library (config, providers, skill_forge catalog, atomic_io), and is
no longer in the wheel. The runtime may not import it back: a fifth
import-linter contract says so (the package is external to the linter's root,
so external packages are now included in the graph) and a test says the same
to pytest. Its tests, the appworld bench adapters, the specs and the README
follow the new address; the Makefile lints it with the rest.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
Three more commits landed on the trunk during the review round, so the branch
stopped fast-forwarding again. Merged rather than rebased for the same reason as
before: a rebase flattens the v0.1.12 merge commit and costs the ancestry this
whole branch exists to establish.
One conflict, additive: tests/test_cli_gateway_commands.py had a _risk_banner
group added on this branch and a gateway-shutdown ordering test added on the
trunk. Both kept.
ui-tui/src/rpc/generated.ts merged automatically. Since it is a generated file,
its result was checked rather than assumed: `npm run lint:rpc` reports it in sync
with rpc-schema/openrpc.json, which merged alongside it.
Verification:
uv run pytest 9018 passed, 33 skipped, 13 deselected
uv run ruff check all checks passed
uv run ruff format --check 1022 files already formatted
npx vitest run 99 files, 1265 tests passed
npx tsc --noEmit clean
npm run lint:rpc schema and codegen in sync
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Installing one of the sub-agents that ship under `subagents/` required a running
raven: each folder's `install.py` registered its entry through
`PUT /raven/subagents`, so both the web service and the gateway had to be up. On a
machine that has just cloned the repository, neither is.
The installer now writes `subagents.thirdParty` in the host raven's config
directly, through `raven.config.update_subagents` - the supported write path,
which validates the entry against the schema, replaces the entry sharing its name,
refuses a list that would hold duplicates, and replaces the file atomically. Hand-editing the JSON gets none of that, and a
half-written config is one raven will not start on. That module is importable only
from the host raven's environment, which is rarely the interpreter running the
installer, so it is reached in a subprocess resolved from the shebang of `raven`
on `PATH` (or `RAVEN_PYTHON`, or `--raven-python`). The installer therefore stays
standard-library only and runs under a bare `python3`.
What the file write costs is hot-apply: a running raven holds the roster it read
at startup, so the installer prints a restart instruction and the guide says the
same. `--endpoint` is gone; `--config` and `--raven-python` are new.
Two additions on top:
- `subagents/install.sh` does the whole install for every folder, or the ones
named: builds each checkout's venv, scaffolds `.env` from its template, then
registers. It refuses to register a folder whose api key is still blank, so a
half-configured agent never reaches the roster, and exits non-zero while
anything still needs attention. It discovers the checkout by its lone
`pyproject.toml` and derives the key prefix from the folder name, so a new
folder needs no edit in the script.
- `subagents/README.md` is the directory-level guide: what a folder is made of,
the install steps, what the installer does and does not do, how to remove an
agent, what a new folder has to satisfy, and what never gets committed.
`subagents/*` stays excluded by default. Only the folders that were already
tracked are whitelisted, plus those two new files by name; a folder holding a
docker image tar or a private checkout is unaffected. The change also drops a
sentence that pointed a published README at an unpublished sibling folder.
The pre-install backup is written before the config is touched, holds the list as
it sits on disk rather than a schema round-trip of it (loading coerces an `openai`
entry's `readsLocalFiles` away, so a validated copy would restore something the
user never wrote), and is at mode 600 because another entry among the others can
carry its own api key. A backup that cannot be written stops the install with the
config untouched, rather than going missing after a config that already changed.
`install.sh` reads the api key the way the launcher does, first non-empty match
wins, so the two cannot disagree about a `.env` that sets it twice. It expands its
argument array through `${args[@]+...}`, since an empty array under `set -u` is an
unbound-variable error before bash 4.4 - the stock `/bin/bash` on macOS. A relative
`--config` is made absolute at parse time, because `install.py` runs with each
folder as its cwd and would otherwise resolve the path once per folder.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
The branch touches 12 files: `.gitignore` and 11 under `subagents/`. Nothing under
`raven/` or `tests/`, and `testpaths = ["tests"]`, so no unit test collects any of
it.
```
uv run pytest -q 8237 passed, 46 skipped, 13 deselected in 170s
uv run ruff check --no-force-exclude subagents/raven-code/install.py All checks passed
uv run ruff format --check --no-force-exclude subagents/raven-code/install.py 1 file already formatted
bash -n subagents/install.sh clean
python3 scripts/check_commit_messages.py origin/main..HEAD exit 0
python3 scripts/check_large_files.py origin/main..HEAD exit 0
```
`subagents/` is excluded in `[tool.ruff] extend-exclude`, so the two ruff commands
above need `--no-force-exclude` to reach the file at all.
End-to-end on a freshly provisioned host with no `raven`, no `uv`, and Python 3.10:
cloned the repository, installed `uv`, built the venvs, ran the installer twice and
spawned one agent for real.
- Installer on a clean clone with no keys: three checkout venvs built, three `.env`
files scaffolded at mode 600, stopped at the key gate for all three, exit 1. The
host config's mtime was unchanged and no backup file was written, so nothing
half-configured reached the roster.
- Same host with keys filled in: all three entries `replaced` in a config that
already held 8 third-party sub-agents, and all 8 survived. Each backup was mode
600 and held the full 8-entry list. `load_config()` then listed all 8, so the
written entry is valid to the runtime and not only to the writer.
- The resolved `command` of each entry pointed at the clone's own path, confirming
the placeholders resolve against the installer's location rather than the machine
that built the folder.
- One real spawn answered correctly in 22s.
- Before that, on a machine with no `raven` on `PATH`, the installer reported
`no raven on PATH; pass --raven-python ...` and recorded the folder as failed.
Probes for the fixed defects: a config seeded with `readsLocalFiles: true`
on disk produced a backup recording `false` before the fix and `true` after; a
`.env` setting the key twice with an empty second line made the shell installer
refuse an agent the launcher would run, and both now agree; an interpreter stub
printing non-JSON now yields `cannot read the writer's output` instead of a
traceback; a `--config` whose parent is a regular file makes the config write fail
with the backup already on disk, which is what shows the backup precedes it; and a
run with no flags at all registers against a scratch `HOME`, which is the path the
empty-array expansion used to break on bash before 4.4.
Proving the backup ordering took two attempts. Making the folder unwritable with
`chmod 555` proved nothing, because this runs as root and root ignores mode bits -
a trap the repository's own skipped test records. The failing-config probe above is
the one that holds.
- [ ] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
The first box is deliberately unchecked: there is no unit test covering this tree,
because pytest does not collect it. The end-to-end run above is the evidence
offered in its place. The unit suite was run anyway, on the rebased tree, and
reported no failures at all - so there are no failing ids to diff against the
target branch.
## Risk
**Behaviour change.** An install no longer takes effect immediately. Anyone
following the old flow will see the agent appear only after raven or the gateway
restarts; the installer's last line and the guide both say so. `--endpoint` no
longer exists, so a caller passing it gets an argparse error rather than a silent
fallback.
**Not reproduced, environment-dependent.** On the test host, the provider's model
listing answered 200 while inference answered
`403 This model is not available in your region.`, which the launcher reports as a
run that exits 0 having committed no answer - it reads like a launcher bug and is
not one. Exporting the site proxy fixed it, and the guide now records both that and
the fact that a missing EverOS degrades rather than fails.
**Security.** The pre-write backup can contain another entry's api key, so it is
written at mode 600 and is covered by the existing ignore rules. Keys stay in each
folder's `.env` at mode 600; the tracked `config.json` files hold none. The
installer no longer sends the entry list over a loopback HTTP service.
**Rollback.** Revert the commit: the previous installer talked to the RPC and needs
nothing else restored. Entries already written stay valid either way, since the
schema did not change.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.12 becomes a real ancestor: the next sync starts from v0.1.12
instead of v0.1.11, and the eventual contribution back to GitHub can still tell
our commits from the upstream ones it already has.
Cost this round: 54 conflict hunks over 31 files, against 19 over 14 for
v0.1.11. The growth is ours, not upstream's -- 33 commits landed on the trunk in
the six days since the last sync, and they concentrate in the three files the
sync notes already name as hot (agent/loop/main.py, cli/tui_commands.py,
config/schema.py).
Notable conflict resolutions:
* agent/loop/streaming.py keeps our extracted stream_llm_call and grafts
upstream's one real addition into it: the truncation verdict
(upstream_finish_reason, flag_truncation, and the two LLMResponse fields).
Comparing function bodies against the merge base was what showed aclosing()
and the structured error classification were already there, not new.
* agent/loop/main.py splits an 87-line block that upstream left empty: two
helpers moved into upstream's new loop/failure_streak.py and had to go, four
with live call sites outside the block had to stay. Taking the block whole in
either direction was wrong.
* _dispatch_backend_store takes upstream's detached-task architecture and keeps
our memory-failure tracking inside the task body. The shared tail after the
hunk reads `e`, which upstream's `except Exception:` does not bind, and
drain_backend_stores already had three merged-in callers.
* context_engine/segments/render.py merges two dimensions into identity_text:
our work_dir split and upstream's routed model id. The shared body already
reads names from both sides.
* agent/tools/registry.py keeps both unparseable-argument mechanisms. They sit
at different layers on purpose -- RunMeta comes from a provider on the
non-streaming path, RAW_ARGUMENTS_KEY from the loop on the streaming one.
Nine breakages git merged cleanly and never flagged. This is the shape the
change fails in, and it is worth recording in full:
* The three vendored builds under subagents/ carry a copy of the pre-rename
raven/tui_rpc/ tree, so rename detection sent upstream's 50 lines of
tui_rpc changes into a dead copy instead of raven/rpc/. Only one of the four
files conflicted; the other three were silent.
* subagent/backends/raven_loop.py holds the tool loop we extracted from the
subagent manager, so upstream's run_meta argument never reached it.
* AgentDefaults.max_tokens: upstream dropped it for a dynamic
send_max_tokens(). Both make_provider sites merged onto the new scheme;
providers/resolving_provider.py did not, because upstream has no such file.
* ResolvingProvider never forwarded wire_model_id. Only upstream's own
invariant test catches that class, and the cost is a silently mis-sized
request (16384 against 4096 for one gpt-4o).
* CronService.add_job kept our body but took upstream's signature, losing
`deliver` from both the parameter list and CronPayload while two RPC methods
still pass it, and leaving a call to the _arm_timer scheme upstream replaced
with a wake Event.
* rpc/bootstrap.py still called make_on_cron_job positionally after the
signature narrowed.
* update_everos lost _EVEROS_CONFIG for a root-lookup family, and gained an
ownership gate over its write primitives.
* SessionInitInfo never declared config_notices, in the model or the schema,
while methods/session.py returns it and our own TUI already reads it through
a hand-written type intersection. Both are strict, so a config migration
would have made session.create fail validation in production.
* tests/test_skill_hub_tools.py keyed a fixture under the "local" router
namespace rather than a real registry layer, which upstream's new assertion
exists to refuse.
Also fixed while here: the rich Style cache poisoning that the ci branch
documents as a known crutch (one pinned color_system), and the coverage
baseline's 29 stale raven/tui_rpc/ paths. The baseline totals are still
upstream's own numbers and should be regenerated separately.
Verification, on macOS with a non-root runner:
uv run pytest 8888 passed, 33 skipped, 13 deselected
uv run ruff check all checks passed
uv run ruff format --check 1017 files already formatted
npx vitest run 99 files, 1265 tests passed
npx tsc --noEmit clean, TurnEvent exhaustiveness included
npm run lint:rpc schema and codegen in sync
make check-large-files exit 0
rpc-schema/openrpc.json is the source of truth here, so ui-tui/src/rpc/
generated.ts was regenerated rather than hand-resolved. Nothing under
subagents/ changed.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Adds direct chat with a sub-agent instance: talking to one of the instances a
session has spawned, without that exchange entering the main agent's context.
The TUI gets the feature end to end; the web UI then gets the same thing on the
same runtime.
**The runtime.** A direct turn runs on its own lane (`session#agent/handle`)
rather than the session's, so several instances answer at once while the main
agent keeps its own serial lane, and direct turns draw on a separate
concurrency pool so a user is never queued behind them. Direct turns are not
cancellable: `turn.cancel` keeps meaning the main agent's turn on both
surfaces. Each turn writes a record (`prompt.md` / `out.md` / `meta.json`), and
the main agent learns only that the exchange happened, through a handoff block.
**Sub-agent replies over ACP.** Three separate causes were losing most of a
reply. Raven answered every agent-initiated request with `method not found`,
including `session/request_permission`, and the codex adapter turns any error
from that request into a cancel -- so a turn died as soon as the agent asked to
run something. Raven now approves, choosing among the options the agent offered
by their protocol kind. A stop reason other than `end_turn` was returned as a
finished answer, so a truncated reply read as a complete one; it now carries a
notice. And several messages in one turn were joined with no boundary, so a
preamble, its tool calls and the answer ran together as one paragraph.
**Instance visibility.** A failed resume deleted the whole registry row, which
took the instance off the strip for the length of the turn recovering it, and
permanently if that turn failed; it now drops only the stale binding. A
capability snapshot whose fingerprint no longer matched was discarded, which
defaulted the agent to *stateless* -- editing an agent's `env` silently cost it
resume, its chip, and the `instance` parameter in the spawn schema. Its
capabilities are now kept and flagged, while its verdict is not, so the
`/subagents` row asks for a re-test.
**Working directory.** A direct chat was the one sub-agent dispatch that
supplied none, so it fell back to agent home and ran its commands against
raven's own memory instead of the user's checkout.
**The web UI.** Two wiring gaps came first, both silent: the browser's
dispatcher registered neither instance method, and the web channel never built
the map that tags an event with its addressee, so nothing a client could
demultiplex on was ever sent. The service then routes on that tag at the push
rather than at the read, because the main reply and a direct turn share one
subscription and two consumers on one queue would each swallow the other's
events -- including a `message.complete`, which would end the wrong turn. A
direct turn's events are published out of band; feeding them into the reply
stream is not an option, since that stream is one reply per turn.
Decisions and their measurements are recorded in `docs/specs/`. Notably, the
vendored AgentScope tree is *not* edited, which is a decision rather than an
omission: making a direct chat a real reply would mean re-keying a blocking
per-session lock that guards message storage and tool-call state as well as the
reply loop, and rendering reuse was obtained without it.
## Type
- [x] Feature
## Verification
- `uv run pytest -q` -- 8021 passed, 36 skipped. The one deselected failure,
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`, fails the
same way on `origin/main` in a clean worktree, so this introduces none.
- `uv run ruff check raven/ tests/ ui-webui/service/` -- clean;
`uv run ruff format --check` -- 957 files already formatted.
- Web service: `python -m pytest ui-webui/service/tests -q` -- 13 passed.
- Frontend: `pnpm lint` -- 0 errors, 18 warnings, each one also present before
this change; `pnpm build` -- succeeds; `tsc --noEmit` -- clean.
- Every fix here was checked by reverting it and watching its test go red. Two
tests that passed either way were rewritten after that check exposed them.
- End to end against a running gateway: a direct chat sent through the new web
route completed twice, each leaving a record whose `out.md` held the exact
reply asked for, and the history route returned those turns afterwards.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The last box is unchecked: the terms are defined in `CONTEXT.md` and the designs
in `docs/specs/`, but no end-user documentation or screenshots were produced.
## Risk
**Approving sub-agent permission requests is a widened trust boundary and the
main thing to review here.** An ACP sub-agent that asks to run something now
gets a yes, and the codex preset is configured for its most permissive mode --
wider than the `-a never` the cli transport used. It is unattended by
construction: a dispatch has no operator and no surface that could render a
prompt, so the alternatives were approving or refusing, and refusing leaves the
agent unable to do the work. Rolling back is per-agent config, or reverting
`raven/agent/acp/permissions.py` to restore the refusal.
Two known gaps, neither reachable today, both stated rather than fixed:
- The web UI's event consumer has no `target` guard of its own. The two
surfaces use disjoint session keys and the browser never sends a target, so a
direct turn cannot reach it; a caller that sent one on a `web:` session would
see a sub-agent's reply rendered as the main agent's. Fixing it would widen
this into unrelated files.
- Direct-chat record directories have no TTL and no count cap, like the spawn
and DAG trees beside them. Reclaiming them would also start deleting audit
trails that intentionally outlive session deletion, which is its own change.
Behaviour changes worth naming: a direct chat under a sandbox whose volumes do
not cover the working directory now fails where it used to run quietly in agent
home, matching what the main path already does; and a partial reply now carries
a `[raven]` notice, so anything parsing a sub-agent's reply verbatim sees it.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
A session that asked the agent to write a terminal game produced 15 tool
failures, 11 of them from one root cause, and burned 51% of its output
budget re-sending the same payload. Output was capped far below what the
model could produce, the resulting truncation was reported as a missing
required field, and the model's most reasonable answer to that message
was to send the same oversized call again.
### The ceiling
`chat_stream` declared literal defaults for `max_tokens`, `temperature`
and `reasoning_effort`, and the agent loop calls it with
messages/tools/model only, so those literals shadowed the configured
values on every streaming turn. Lifting the shadow exposed what it had
been hiding: `agents.defaults.maxTokens` defaulted to 8192 for every
model and onboarding wrote it into the user's config, where it was
indistinguishable from a number the user chose. No single number works
-- claude-sonnet-4 emits 64000 and gpt-4o 16384, while models below 8192
reject the larger value. The setting is retired; an old config carrying
the key is ignored rather than rejected, so no migration is needed.
What replaced it went through two shapes. It first resolved a ceiling
per model and sent it on every request. It now sends nothing unless a
caller pins one: the field is optional in the OpenAI-compatible shape
and required only by Anthropic's Messages API, whose LiteLLM
transformation supplies it. Measured by intercepting the outgoing body,
an Anthropic request built without one goes out at 64000 on both
response paths, and LiteLLM's number matches what this repo would have
computed on all 26 rows it files under that provider, since both read
the same table. Volunteering a number meant carrying a copy of LiteLLM's
routing knowledge -- which vendor speaks which API -- and keeping the
copy aligned; the surveyed agents (LiteLLM, OpenClaw, opencode,
hermes-agent) do not have that problem because each protocol adapter
owns its own required fields.
The catalogue is still read, for the budget and to bound an explicit
pin, and it is not always right: 984 of the pinned LiteLLM's 3040 rows
report `max_output_tokens` at or above `max_input_tokens` -- the window
filed as the ceiling. `openrouter/anthropic/claude-sonnet-4.5`, the id
this repo documents as an example, reports 1000000 where Anthropic
allows 64000. Such a row is treated as no answer, and only when it is at
least as large as the fallback that replaces it, which is what keeps the
rule safe: the replacement is then never larger than what the row
claimed, where an unconditional version raises 252 small rows past their
real ceiling.
### Detecting a cut
Two pieces of evidence, and neither is arithmetic.
**The upstream says so** -- `finish_reason == "length"`. Reliable when
it speaks and never waited on: measured through openrouter, gpt-4o
answers a ceiling hit with `"tool_calls"`, a positive claim of success,
in 4 of 4 probes. It under-reports rather than over-reports.
**The last call's arguments did not parse.** Generation is sequential,
so a cut leaves nothing after it: a repair on the last call means the
turn ended while writing it, and a repair on any earlier call cannot be
that. Measured over four realistic argument blobs, every one of 323 cut
points that drops a field leaves JSON that will not parse, because JSON
is only complete once the object closes and closing it means nothing was
lost.
An earlier shape compared output tokens against the ceiling the request
carried. That comparison is why the request and the check had to agree
on both a number and a model id, and it broke at one call site or
another six times on this branch. No surveyed agent carries such a
comparison. Removing it is what let the decision stop reading the
catalogue at all.
Facts and readings are kept apart. `run_meta` records that the arguments
were repaired and that nothing followed the call; that the turn ran out
of room is a reading of those two and lives in the sentence the model
reads, which offers both causes under their own conditions and says
outright that nothing distinguishes them. It is marked `[incomplete
arguments]`, not `[truncated]`, which is a claim only the upstream can
earn. `truncation_hint` keeps its meaning -- advice for a confirmed cut
-- and the ambiguous case reads `incomplete_hint`, phrased as the
consequent of a condition. A guard fails any tool answering one and not
the other.
Both signals reach every transport: azure was already calling
`json_repair` and dropping the fact, and codex wrapped unparsed text as
`{"raw": ...}`, which stayed dispatchable and made the model read a
schema complaint about a field it had sent.
### A truncated call is not dispatched at all
Originally out of scope as "a call whose fields all validate still
executes, writing a half-file". Running the branch showed the boundary
is worse: `mode` is optional on `write_file`, so a cut landing before it
falls back to `overwrite` and silently replaces what an earlier append
wrote, then reports success. Validation cannot see this -- the call is
well-formed. The refusal moves ahead of validation, and it is wired at
every loop that dispatches, not only the main one: `SubagentManager` and
the curator computed the verdict and dropped it.
`write_file` gained `mode=append` so a file too long for one call has a
second move; `overwrite` stays the default. An append with empty content
is refused rather than treated as a no-op -- that is what a call cut off
before its content field looks like.
### The budget
`reserved_output` was a configured 8192 and is now the model's own
output ceiling, bounded only by the window. Requests do not name a
ceiling, so the one that applies is whatever the vendor or LiteLLM fills
in, and the prompt has to fit beside it: reserving a share of the window
instead lets a prompt reach 150000 of a 200000 window against a reply
allowed 64000, and the sum is refused at request time. `classify_error`
reads that refusal as `should_compress`, but `_emergency_shrink` only
elides `role="tool"` bodies and gates its retry on having elided
something, so a session grown on conversation gets no retry.
### Downstream effects of a cut-off turn
- **Think-tag debris.** A turn cut inside an inlined reasoning block
arrives as a lone closing tag; three patterns matched only bare
spellings, missing both the namespaced form vendors emit (`<mm:think>`)
and the orphan tag, which let a complete think block reach the user as
if the reasoning were the answer.
- **Failure-streak misfires.** The loop-break nudge fired after N
consecutive failures of the same *tool* regardless of whether they were
the same *failure*. It keys on (tool, failure class) now, and the
truncated and ambiguous classes get their own wording -- "change
approach: a different tool" is advice `write_file` cannot take.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/
6373 passed, 43 skipped, 1 failed
uv run ruff check raven/ tests/
All checks passed!
uv run ruff format --check raven/ tests/
829 files already formatted
```
The one failure is
`test_cli_theme::test_bold_accent_renders_styled_not_bare`, pre-existing
and unrelated: it passes alone and fails when its file runs as a whole,
on this branch and on a clean checkout of the base alike.
**Live reproduction.** Run against a real backend
(openrouter/anthropic/claude-sonnet-4-5) with the ceiling pinned low
enough to force truncation, on the task the original incident used:
| | before | after |
| --- | --- | --- |
| iterations | 40 (hit the cap) | **4** |
| bytes written | 0 | **6213** |
| file parses | n/a | **yes**, 218 lines |
| model's closing line | "sorry, I hit a technical limit" | "done!" |
The before run is the incident in miniature: forty `write_file({"path":
"snake.py"})` calls with the content withheld, each carrying exactly
twenty characters of arguments while the first eight were billed 1200
output tokens each. That run also exercised a design decision argued
only on paper: turn 2 emitted two calls, the first landed 2934 bytes and
the second was cut -- marking only the last call of a turn is what let
the first execute.
**Measurements the design rests on**, each reproducible from the
checkout:
| Claim | How it was checked |
|---|---|
| A cut that drops a field always leaves unparseable JSON | 323 cut
positions across four argument blobs, 0 missed |
| gpt-4o reports a ceiling hit as `tool_calls` | 4 of 4 probes through
openrouter |
| The catalogue files windows as ceilings | 984 of 3040 rows; 252 would
be raised by an unconditional rule |
| LiteLLM supplies Anthropic's `max_tokens` when we omit it | outgoing
body intercepted at the HTTP handler; 64000 on both paths |
| LiteLLM's number matches ours where it knows the model | 26 of 26 rows
under `litellm_provider == "anthropic"`, 0 disagreements |
| MiniMax, marked as speaking Anthropic's API here, is routed
OpenAI-shaped | `/v1/chat/completions`, field absent |
**Regression detection.** This class of defect does not turn a suite
red; it makes the suite unable to see the behaviour. For each change the
implementation was reverted while keeping its tests, and the new cases
confirmed to fail first. Assertions land on outgoing request bodies,
returned messages, the serialized assistant message, and file contents
on disk -- not on whether a call happened. Several cases exist
specifically because a first attempt drove a stub rather than the
assembly: a stub provider builds no request body, and stubbing the
id-resolution hook on one manufactures the agreement a real provider has
to earn.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
**`agents.defaults.maxTokens` is gone.** A config still carrying it is
ignored, not rejected, so nothing breaks and no file needs editing --
but a user who set a low value to cap cost will find it no longer has an
effect. There is no replacement setting.
**Requests no longer carry an output ceiling.** Replies are bounded by
whatever the vendor applies rather than by a number this repo chose,
which is longer than the old 4096 on every model and reaches installs
that never configured anything. For a model LiteLLM's table does not
know, its Anthropic fallback is 4096 where this branch would have sent
16384; that caps a reply shorter than the model could produce, which the
truncation machinery absorbs -- the call is refused, the model is told
to continue in pieces, and the work completes over more turns.
**Less history fits in a turn.** The budget reserves the model's full
output ceiling, where it reserved a configured 8192 before. On
`anthropic/claude-opus-4-5` that is 64000 of a 200000 window; on
`z-ai/glm-4.6`, 131000 of 202800. Long sessions compact sooner. The
alternative is a prompt the reply cannot coexist with.
**`write_file` gained a parameter.** Additive: `mode` is optional and
defaults to the existing behaviour.
**A truncated tool call is no longer executed.** Previously it ran
whenever its required fields happened to have arrived. The cost when the
refusal is wrong is one retry.
**Error text the model reads changed.** Anything parsing tool errors by
string match will see different wording, and a new `[incomplete
arguments]` marker alongside `[truncated]`.
`registry.execute` gained one keyword-only parameter with a default.
Truncation metadata rides beside the arguments rather than inside them,
so it reaches neither the tool nor the assistant message. Rollback is a
straight revert of the branch; nothing persists state and no data
migration 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: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Port the harness self-evolution framework onto Raven and grow it into a
runnable, benchmark-pluggable stack: a budget-bounded loop that
diagnoses
failing trajectories, designs candidate patches as real git commits,
screens
them cheaply, confirms survivors, and promotes only what passes three
verification gates -- with a sealed test set for an honest
generalisation
number.
- **Evolution machinery** (`raven/evolver/`): orchestrator state machine
(seven-step funnel), three verification gates (infra validity, beacon
attribution, paired significance), sealed-test runner with retention,
git-backed candidate tree, judge, taxonomy, activation ledger.
- **AppWorld bench** (`benchmarks/appworld/`): agent_cli, batch scorer
with trial-level resume and an infra-rerun ladder, plus the evolve glue
(designer, diagnosis, adapter, Gate0 precheck with real-generation
probing).
- **Unified entry**: `python -m raven.evolver
{check,run,status,finalize}`
drives cold start -> rounds -> terminate -> unseal as a resumable state
machine. Config drift and unseal one-wayness are mechanized in run meta;
benches plug in via a documented contract
(`docs/specs/evolve-bench-contract.md`).
- **Designer feedback**: inert-death loop (pruned_inert status, per-WHY
history, gentle decay) so unreachable triggers teach the next attempt.
- **Launch hygiene**: `check` runs the bench Gate0 precheck, so a dead
subject endpoint fails at check time instead of at cold start; ephemeral
eval/edit worktrees live under `work_dir/tmp` and hard-kill leftovers
are
swept on the next launch of the same run.
- **Docs**: SOP translation (internal details redacted), SOP-to-code
map,
bench plugin contract, and a user README with security notes and known
limitations.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_evolver_launch.py
tests/test_evolver_launch_e2e.py -q`
-> 56 passed (config, guards, trial-level idempotency, interrupt ->
resume ->
finalize with a fake bench, check precheck pass/fail, worktree sweep).
- `uv run ruff check` on all touched files -> no new findings versus
base
(one S607 partial-path git call matching the file's existing idiom).
- Real AppWorld end-to-end through the unified entry, from a fresh
config
written by following the README user path: `check` -> `run --smoke` (~16
min:
cold start on 3 tasks, one full round with real diagnose/design, a real
1-line candidate commit, focused probe + confirm, promoted with an
honest
`credited=False` Gate-b verdict) -> termination.
- Real `check` both ways: live subject endpoint -> `bench precheck: OK`;
config pointed at a dead (NXDOMAIN) endpoint -> exit 1 at check time
with
an actionable `subject endpoint unreachable` message.
- The bench placement (repo-root `benchmarks/`, outside the wheel,
matching
this directory's decoupling convention) was verified with a second real
smoke: all three phases ran against a checkout of this layout, worktree
evals resolved `python -m benchmarks.appworld.batch` from the checkout,
and the designer wrote its candidate to the new whitelist path
(`benchmarks/appworld/agent_cli.py`) as a real commit.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Security: this system has an LLM edit and execute code. Candidate edits
are
constrained to a per-bench path whitelist, an immutable kernel protects
the
measurement surface (the evolver itself and the scorer), and the README
documents the threat model plus the recommendation to run evolutions in
an
isolated environment. Backward compatibility: purely additive -- new
packages
plus one optional `BenchBundle.precheck` field; nothing existing changes
behavior. Rollback: revert the branch; no migrations, no config changes
to
existing features.
## Related Issues
N/A
---
Reviewer notes:
- Exercised at smoke scale only: a full-size run (90 tasks x K=3,
multi-round,
hours) and the sealed-test unseal/retention path on a real benchmark are
covered by tests but not yet by a production run; the README states this
under "Status and known limitations".
- One bench ships today (AppWorld, built-in scorer line); a
framework-line
example (external scorer) is planned as a follow-up.
---------
Co-authored-by: Ethan Wang <ethan.wang@evermind.ai>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
Co-authored-by: Elliot Chen <2340896+cyfyifanchen@users.noreply.github.com>