24 Commits

Author SHA1 Message Date
Tchen-data
f178990780
fix: give the renderer a Han face rather than hoping the host has one (#668)
## Summary

Chinese in a deck came out as boxes (or as nothing) in the preview
panel, the delivery thumbnail, the template gallery, and the pages the
model renders to check its own work. LibreOffice reports success and the
PDF is well formed, so nothing flagged it.

Why, per platform:

- **Linux**: apt's `libreoffice` brings no CJK face.
- **macOS**: the system already ships Han faces (Songti, STHeiti,
Hiragino Sans GB, PingFang). Since 26.8 the macOS build renders headless
through a bundled fontconfig (`--enable-headless
--without-system-fontconfig` in `distro-configs/LibreOfficeMacOSX.conf`)
that looks for `/usr/local/etc/fonts/fonts.conf`, which an Apple Silicon
Mac does not have; without it that fontconfig lists 0 fonts, and a face
in `~/Library/Fonts` or a per-user fontconfig file is ignored. That is
why installing a font on a Mac never helped, and why the Macs that
worked had a CJK face copied into `LibreOffice.app` by hand.
openai/codex#32968 reports the same symptom from Codex's own
headless-only LibreOfficeDev build, whose fontconfig carries a
`/@..._OOO/etc/fonts` prefix; the cask build looks in
`/usr/local/etc/fonts`, so that thread's workaround is not the one
needed here.

What the PR does (the net diff; earlier commits on the branch tried
render-time detection, environment injection and then an
installer-written fontconfig file, and the later commits replace them):

1. **Linux font.** The LibreOffice offer installs `libreoffice
fonts-noto-cjk`. Where that did not run and `fc-list :lang=zh` is empty,
a pinned Noto Sans SC (size and sha256 checked before it is put in
place) goes into `~/.local/share/fonts` and `fc-cache` is rerun.
2. **macOS: the Mac's own faces, linked into LibreOffice's profile.**
LibreOffice always reads the `user/fonts` folder of the profile it runs
with. `office.link_han_faces(profile)` links Songti, STHeiti, Hiragino
Sans GB and PingFang (found under `AssetsV2` each time, so a link a
macOS update left dangling is replaced) into `profile/user/fonts`.
`office.to_pdf` does it for its throwaway profile (preview panel,
delivery thumbnail, template covers, ppt engine), the design engine for
its two profiles, and `ExecTool` for LibreOffice's default profile,
which the model's own `soffice --convert-to` uses. No download, no
password, nothing written outside the user's home, and it reaches users
who upgrade without rerunning `install.sh`.
3. **LibreOffice on a Mac without Homebrew.** This used to be a warning
and no preview at all. The installer now fetches the release dmg
(26.8.0, sha256 pinned per arch, from the stable directory and then the
archive), mounts it read-only, copies `LibreOffice.app` into
`/Applications` or `~/Applications`, never over an existing app, and
writes a two-line `~/.local/bin/soffice` launcher the way the cask does.
A failed `brew install` falls back to it too.
4. **Finding it.** `office.find_soffice` falls back to the launcher
inside `LibreOffice.app` in either Applications folder when nothing is
on PATH; the design engine now asks the same resolver.
5. **Stale renders.** The pdf-preview and deck-template cover cache keys
mix in `office.RENDER_GENERATION` (3), which retires every picture drawn
before this change. The Linux font step also clears both caches whenever
it installs a face.

Removed relative to earlier revisions: `raven/utils/fonts.py`
(`render_env`, `han_face`, `can_draw_han`, `host_han_faces`,
`install_hint`; several were never called), the exec-environment
wrapping, the ppt-engine face lookup, and the installer's sudo-written
`/usr/local/etc/fonts/fonts.conf`.

Known limits:

- A `soffice` run with a profile raven did not prepare (a caller passing
its own `-env:UserInstallation`) gets no faces on a Mac.
- A `deck.pdf` rendered beside a deck before the fix is still preferred
by the viewer until the deck is re-rendered or touched.
- Verified on macOS 15.7.1 arm64, and by review on macOS 26.5 arm64
(LibreOffice 26.8.0.3 from the cask); macOS 14 and Intel Macs have not
been run.

## Type

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

## Verification

macOS 15.7.1 arm64, LibreOffice 26.8.0.3 run from the stock dmg (no CJK
face in its bundle), fontconfig handed an empty configuration (so no
`fonts.conf` of any kind), HOME pointed at an empty directory:

- `main`: the model's own `soffice --convert-to` (default profile, after
building an `ExecTool`), `pdf_preview.pdf_for` / `png_for`, the ppt
engine's `to_pdf` and the design engine's `LibreOfficeBackend` each
embedded only Carlito and LinuxLibertineG (`pdffonts`).
- This branch: the same four paths each embedded PingFangSC, STHeitiSC
and STSongti-SC; the default profile held links to the five faces.
- No-Homebrew path, with PATH stripped of `/opt/homebrew`, an empty HOME
and a read-only Applications folder: the step downloaded the dmg,
matched its digest, installed into `~/Applications` (`codesign --verify
--deep --strict` valid, `spctl --assess` accepted) and wrote the
launcher; a second run downloaded nothing.
- Linux (container with every CJK face hidden): the font step downloaded
Noto Sans SC and the render embedded NotoSansSC; a second run did
nothing.
- `uv run --frozen --all-extras pytest -q tests/test_utils_office.py
tests/test_install_script.py
tests/test_design_engine_rendering_office.py
tests/test_rpc_deck_templates.py tests/test_shell_background.py
tests/test_ppt_engine_render_service.py`: 142 passed, 1 skipped.
- `uv run --frozen lint-imports`: 10 kept, 0 broken. `ruff check` /
`ruff format --check` on the changed files: clean. `shellcheck -s sh
install.sh`: no new findings. `scripts/check_source_language.py`: pass.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no docs
describe this step)

## Risk

- [x] Security impact considered: the dmg and the font are checked
against pinned sha256 digests before use; the macOS change only creates
symlinks under LibreOffice profiles in the user's home, never replaces a
real file there, and runs no privileged command.
- [x] Backward compatibility considered: Linux hosts that already have a
CJK face are untouched; on a Mac, a profile that already holds its own
fonts keeps them. The cache-key bump costs one re-render.
- [x] Rollback path is clear for risky changes: deleting the links in
`~/Library/Application Support/LibreOffice/4/user/fonts` returns
LibreOffice to its previous behaviour; reverting the PR restores the old
installer.

User-visible: a Mac without Homebrew downloads about 300 MB of
LibreOffice once; nothing asks for a password.

## Related Issues

N/A

---------

Co-authored-by: litong <litong02@shanda.com>
Co-authored-by: Claude (claude-opus-4-6) <noreply@anthropic.com>
Co-authored-by: KT <74288668+0xKT@users.noreply.github.com>
2026-09-23 19:10:53 +08:00
Ethan Wang
78e41b2f8d
feat(*): a playbook mode that takes many rounds (#499)
## Summary

A third playbook mode. A `mode: stint` playbook declares roles instead
of nodes, and the driver compiles one sub-agent graph per round, so a
stint is not a sibling of a `dag` run but a layer over it: one fan-out
is one graph, and many rounds are one graph each. Thirty rounds is
thirty graphs on the shared dispatch path, which is what makes the
validation, the dispatch budget, the approval gate and the detached-run
bookkeeping the ones already there rather than a second set.

The stint is a file. Nothing depends on the process that started it
still being alive: a gateway restart, a machine restart, or a `raven
playbook stints resume` all pick it up, and the resume is node-granular,
so a round that died with two roles done re-runs the third.

**One noun, singular and plural.** The mode is `mode: stint`; one run of
such a
playbook is a stint, with its own id, checkout and record; the plural is
the
command family and the RPC namespace. `round` keeps its own meaning as
the unit
inside -- one pass of every role -- and `stage` as one role's turn in
it, so
"the stint is on round 7 of 30" says three different things with three
different
words. The whole surface sits under `raven playbook`: `stints` answers
what has
run on this machine, `stint` acts on one project's layout and the
backlog its
roles share.

**Handover is files, not a conversation.** Every role opens a fresh
conversation each round, which is a decision rather than a limitation:
which instance serves which role changes, processes restart, transcripts
get compacted. What a role learned this round reaches the next one only
by being written down. That makes the journal the contract -- an
append-only file, windowed by recent rounds and by characters, because a
forty-round journal would otherwise fill the prompt it exists to inform.

**The boundary is three layers.** `owns` and `appends` are declared in
the playbook, rendered into the role's prompt from the same declaration
the enforcement reads, measured by the role's own checks, and undone
afterwards with the file the role wrote kept under `violations/`.
Declaring without telling is a trap; telling without undoing is a
suggestion; and the undo reads the stage's own commits as well as the
worktree, because a role that commits a stray write disappears from the
working tree and a boundary any role can step around by committing is
not one. Nothing refuses a write before it lands: a charter narrows a
role's tools only where the playbook declares a `playbook:` block, and
`owns` is not derived into one, so the shipped playbook's roles have no
tool gate and the undo is the boundary rather than its backstop.

Two shapes the boundary cannot hold are refused where they are written
rather than left to surface as violations in round four:

- **Two roles that can run at once where either is enforced.** They
share one checkout, so the first judged is graded against the difference
the whole tree shows and quarantines the other's work. Observed before
it was refused: two roles with disjoint `owns`, each writing only what
it owned, and the first judged came back as `dev-a wrote 1 path(s) it
may not write: src/b/work.py`, with that file gone. The message names
both ways out, because which one is right is the author's call. What
would make it work is a checkout per concurrent role, which is a merge
problem, not a validation rule.
- **`enforce.read: hard`.** It reaches the guard text, which then tells
the role that reads outside its paths are refused at the tool gate, and
no gate refuses one. The wording stays in `rounds_prompt` for whoever
wires the gate; until then the grade is not offered.

**Checks come before any model's opinion.** `verify[]` runs real
commands, and a failure goes back to the role that caused it with the
failure text, up to `maxHandbacks`. When that budget runs out the round
records the failure and carries on rather than failing the node: a
failed node skips every role downstream, and a failed build is exactly
what the reviewer downstream has to see.

**One approval, and it names what it is approving.** The whole stint is
confirmed once, at the start, and the text states the round budget and
every command the stint may run -- a playbook is a distribution unit, so
a file somebody handed you does not get to run shell thirty times on one
unexamined yes. Every round is charged against the hourly dispatch
budget like any graph; a round the budget turns down pauses the stint
rather than failing it, and `stints resume` takes it up once the
allowance recovers. From the CLI the same approval is put to the
terminal, and with no terminal to ask at the run is refused rather than
approved on nobody's behalf.

A stint works a checkout of its own, cut from the project's head, so
hours of its commits do not collide with the conversation that started
it. `stop.maxRounds` defaults to 10 and is capped at 99. `stop.until`
lets a role end a stint early by reporting a marker on a line of its own
-- a whole line, so a role quoting the marker mid-sentence does not end
the plan -- and only a terminal role is told the marker, because a role
that knows how to stop the stint has a reason to reach for it.

**Surfaces.** `raven playbook stints
list/get/extend/pause/stop/resume/sweep/answer`, where `resume` and
`extend` are relayed to the raven serving the page when one is up, so a
round runs in the process that owns the conversation;
`playbooks.stints.*` RPC methods, the read-only ones reading the record
off disk so opening the page does not cost what a dispatch costs; a
Stint tab on the playbook page showing the roles, what each owns, the
checks with their full commands, and what carries between rounds; and a
Runs tab listing every stint with its standing, how far into its budget
it is, each round's checks and what was undone, with pause, stop and
resume.

`raven playbook stint` lays a project out for one. The shipped playbook
is `rounds`: a planner, a builder and a verifier, on any project that
has a specification. `init` writes `.stint/`: a guard file per role, the
shared prose, and a link to the project's own specification, chosen by
two sieves -- the file name first, then how much of the document says
something is required, so an empty `SPEC.md` stub does not send thirty
rounds off a blank page. `task`, `ask` and `confirm` work the backlog
the roles share.

New package `raven/stint/` carries the parts a stint needs that are not
the playbook: the record, its checkout, the ownership grades, the
journal window and the check runner. `CONTEXT.md`, `CHANGELOG.md` and
the two `docs-site` repo-layout tables gain their rows; `README.md` is
not touched.

Three unrelated changes ride along. Two are the same shape -- a web
change that does not show:

- `index.html` went out with no caching header, so browsers fell back to
heuristic freshness and served a rebuilt page from cache without asking,
which reads exactly like a server that never picked the change up.
`no-cache` keeps the entry and revalidates; the ETag still saves the
transfer.
- `make ui` is one target for the two-step page build, because running
only vite leaves the served one-file page unchanged with nothing to say
so.

The third is `raven agent` (`raven/cli/agent_commands.py`):
`--message-file` reads the prompt from a file, `--permission-mode` picks
the tier for the run, and `--no-markdown` prints a soft-wrapped `Text`
rather than a markdown render; 92 lines of tests in
`tests/test_cli_agent_commands.py`.

Designed and deliberately not built, so a reviewer knows where the edges
are: a checkout per concurrent role with each role merging itself in
when it is judged (`docs/plans/2026-09-18-stint-acceptance.md`), and the
backlog-writing round zero. `raven playbook stint confirm` records a
person's word on the plan and nothing in the rounds path reads the flag
yet, which that document also says.

## Type

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

## Verification

```
uv run ruff check --no-cache raven evolver agents plugins-dist tests scripts
uv run ruff format --check --no-cache raven evolver agents plugins-dist tests scripts
uv run lint-imports
make lint-types
make lint-ui
make lint-tui
uv run pytest -q
uv run python scripts/check_commit_messages.py main..HEAD
uv run python scripts/check_source_language.py main..HEAD
uv run python scripts/check_large_files.py main..HEAD
```

Ruff clean over 2,004 files. Import contracts: 10 kept, 0 broken. `ty`
clean, which caught one real defect on the way in: `StintStore.list`
shadowed the builtin for every annotation after it in the class body, so
`-> list[StintRecord]` on it and on `live()` resolved to the method. The
UI gates include the generated-file drift checks (`gen:check`,
`lint:rpc`, `lint:i18n`) and both type-checks; eslint reports 23
warnings and 0 errors, none of them in a file this branch touches. `make
lint-bridge` was not run: this checkout has no `bridge/node_modules`,
and nothing here touches `bridge/`.

Suite: the whole `uv run pytest -q` runs in CI as four shards, and every
shard is green at this head, with the import-cycle budget (44 modules,
the same as `main`), the coverage gate and the three content gates over
the commit range. Locally the suites this branch touches are run per
change; the full run is CI's.

Behaviour, driven rather than asserted:

- A stray write by a concurrent role was reproduced end to end before
the validation refused the shape: `dev-b's own file still there after
dev-a was judged: False`, `violations recorded against dev-a: ['dev-a
wrote 1 path(s) it may not write: src/b/work.py']`.
- The check runner's timeout kills the process group, not just the
direct child. Proved as a regression guard: red with `process.kill()`,
green with the group teardown.
- The round budget refuses rather than wrapping: extending a real stint
past the ceiling answered `that would give it a budget of 104, and 99 is
the most any stint may have`, and the file was not written.
- The spec picker's two sieves, over a real project: `KEPT docs/PRD.md |
weight 12`, `dropped SPEC.md | len 12 | weight 0`, `dropped notes.md |
len 868 | weight 0`.
- Only a terminal role is told the stop marker: `planner=False
builder=False verifier=True` on the shipped example.
- The shipped example is discoverable with no user layer: `listed:
['rounds']`, `origin: builtin`.

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

## Risk

Additive. `mode: stint` is a new value; `dag` and `prompt` playbooks
load, validate, dispatch and report exactly as before, and the sections
the new mode reads are withheld from the generator's emit schema, so no
generated playbook can reach them. That withholding is pinned by a test
that fails when a section is added to the spec without being added to
the refusal.

Nothing outside the new mode changes behaviour: `spawn` and the DAG path
keep the per-session in-memory dispatch window they have on `main`.

A plan runs shell from `verify[]`. It is gated on the approval, the
approval text lists every command, and a playbook carrying `verify`
cannot be generated -- only written by hand or shipped. The builtin
layer ships exactly one playbook, `rounds`, pinned by name in a test,
for that reason: withheld from the generator and not shipped either, the
mode would be reachable only by transcribing YAML out of prose.

Rollback is a revert of the merge commit. A plan's on-disk record is
under the sub-agent history root and is read by nothing else; nothing
else's on-disk shape changes.

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

## Related Issues

N/A

---------

Co-authored-by: Ethan Wang <ethan.wang@evermind.ai>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-09-23 12:24:08 +08:00
0xKT
ab8eb7d498 fix(ppt-engine): give a page box the names it promises and rasterise one at a time
## Summary

Three defects a live twenty-page run surfaced, each of which cost whole pages.

`PageBox` said in its own docstring that it reads the same as `ppt_layout.Box`, and `Box`
answers to `.x` and `.y` as well as `.w` and `.h`. `PageBox` answered to two of the four.
A build helper read `round(b.y, 3)` once, in the one place it used for every page, and all
twenty pages failed to draw with `'PageBox' object has no attribute 'y'`. `Box` was given
the same pair after the same crash; the promise was the part that did not travel.

`_check_cut_out` asked its argument for `.name`, and the spelling the skill documents is
`replace_picture(shape_at(slide, n), str(FIGURES / image), fit)`. Every other branch takes
that string -- the ones that open the file hand it to PIL, which does -- so the only thing
that refused it was the warning that exists to explain a mistake. It raised
`'str' object has no attribute 'name'` over the top of the explanation and took the page
with it.

Rasterising now has a gate of its own, and it is one. `pdf()` spends its time in a
LibreOffice subprocess with a profile of its own, so width there costs nothing and buys
wall clock; `pages_of` spends its time in pypdfium2, in a worker thread of this process,
against a library that keeps state per process rather than per document. One gate for both
put them under the same number and let the second run concurrently with itself: over a
nine-template reference set, six of the nine PDFs failed to open with
`PDFium: Data format error` while every one of the nine opened when read one at a time, and
an earlier run on the same path took SIGSEGV. `pages_of` answers a failed read with an
empty dict, so the cost was a reference sheet quietly short of two thirds of its pages
rather than anything that looked like an error.

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

Commands run on this branch, rebased onto main:

```
uv run --frozen pytest tests/ -k ppt -q
uv run --frozen pytest tests/test_ppt_engine_template.py -q \
  -k "page_box_answers or cut_out_warning_survives or rasterising_runs_one_at_a_time"
uv run --frozen ruff check plugins-dist/ppt-engine/raven_ppt/services/template/compose.py \
  plugins-dist/ppt-engine/raven_ppt/stages/_views.py
```

The three added tests were each confirmed to fail without the source change. The
concurrency one asserts on how many rasterisations are in flight -- the property -- rather
than on the width of a semaphore, which is one way to get it, and its stub renderer carries
the real signatures on purpose: a stub that shapes itself to the caller agrees with a call
the engine cannot make.

## Risk

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

Two added properties and one widened type annotation are additive. The third change
narrows rasterising to one at a time while leaving conversion as wide as it was, so a deck
whose pages are read after conversion takes slightly longer in exchange for reading all of
them; reverting the commit restores the shared gate.

## Related Issues

N/A
2026-09-11 07:22:24 +00:00
Tchen
94ed54b78d fix(ppt-engine): give a page box the names it promises and rasterise one at a time
## Summary

Three defects a live twenty-page run surfaced, each of which cost whole pages.

`PageBox` said in its own docstring that it reads the same as `ppt_layout.Box`, and `Box`
answers to `.x` and `.y` as well as `.w` and `.h`. `PageBox` answered to two of the four.
A build helper read `round(b.y, 3)` once, in the one place it used for every page, and all
twenty pages failed to draw with `'PageBox' object has no attribute 'y'`. `Box` was given
the same pair after the same crash; the promise was the part that did not travel.

`_check_cut_out` asked its argument for `.name`, and the spelling the skill documents is
`replace_picture(shape_at(slide, n), str(FIGURES / image), fit)`. Every other branch takes
that string -- the ones that open the file hand it to PIL, which does -- so the only thing
that refused it was the warning that exists to explain a mistake. It raised
`'str' object has no attribute 'name'` over the top of the explanation and took the page
with it.

Rasterising now has a gate of its own, and it is one. `pdf()` spends its time in a
LibreOffice subprocess with a profile of its own, so width there costs nothing and buys
wall clock; `pages_of` spends its time in pypdfium2, in a worker thread of this process,
against a library that keeps state per process rather than per document. One gate for both
put them under the same number and let the second run concurrently with itself: over a
nine-template reference set, six of the nine PDFs failed to open with
`PDFium: Data format error` while every one of the nine opened when read one at a time, and
an earlier run on the same path took SIGSEGV. `pages_of` answers a failed read with an
empty dict, so the cost was a reference sheet quietly short of two thirds of its pages
rather than anything that looked like an error.

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

Commands run on this branch, rebased onto main:

```
uv run --frozen pytest tests/ -k ppt -q
uv run --frozen pytest tests/test_ppt_engine_template.py -q \
  -k "page_box_answers or cut_out_warning_survives or rasterising_runs_one_at_a_time"
uv run --frozen ruff check plugins-dist/ppt-engine/raven_ppt/services/template/compose.py \
  plugins-dist/ppt-engine/raven_ppt/stages/_views.py
```

The three added tests were each confirmed to fail without the source change. The
concurrency one asserts on how many rasterisations are in flight -- the property -- rather
than on the width of a semaphore, which is one way to get it, and its stub renderer carries
the real signatures on purpose: a stub that shapes itself to the caller agrees with a call
the engine cannot make.

## Risk

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

Two added properties and one widened type annotation are additive. The third change
narrows rasterising to one at a time while leaving conversion as wide as it was, so a deck
whose pages are read after conversion takes slightly longer in exchange for reading all of
them; reverting the commit restores the shared gate.

## Related Issues

N/A
2026-09-11 07:22:24 +00:00
gloryfromca
201293cf1c refactor(sandbox): the sandbox is told where its state lives
## Summary

`raven/sandbox/_runtime.py` read `raven.config.paths.get_sandbox_dir` to find the boxlite home, while `raven/config/schema.py` imports `raven.sandbox.config` for `SandboxConfig` -- a two-edge cycle between the two packages. An executor asking the configuration layer where its own data lives is the inverted half of that pair: it can be told instead.

`get_boxlite_runtime` now takes the home. `BoxliteExecutor` and `SandboxDebugServer` take a `sandbox_home` and pass it down. `build_executor` takes `sandbox_dir` -- the resolver, normally `get_sandbox_dir` -- and calls it only inside the boxlite branch.

The resolver rather than an already-resolved path, because resolving one creates the directory and `none` is the default backend: an eager path would leave every install a boxlite home it never uses. That laziness has a test, and the test goes red if the resolve moves above the branch.

`SandboxConfig` gains no field. Its model carries an alias generator, so a field there would become a user-writable knob in `config.json`, and a resolved runtime path is not a declaration. Five production call sites pass the resolver, all in packages that already import `raven.config`, so no new edge appears.

Measured on `origin/main` in the same environment, before -> after: packages in cycles 18 -> 17, mutual pairs 13 -> 12 (`config <-> sandbox` is gone), modules in cycles 42 -> 42. The ratchet ceilings in `tests/test_import_cycle_budget.py` are deliberately left where they are.

## Type

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

## Verification

- `uv run pytest tests/test_sandbox_unit.py tests/test_sandbox_debug_server.py tests/test_agent_loop_workdir.py tests/test_cli_sandbox_commands.py tests/test_playbook_mcp.py tests/test_subagent_manager.py tests/test_import_cycle_budget.py -q` -> 336 passed
- `uv run lint-imports` -> 9 kept, 0 broken
- `uv run ruff check raven/ tests/` -> All checks passed
- `uv run ruff format --check` on the touched files -> already formatted
- `make check-source-language` -> exit 0
- The laziness guard was mutation-checked: moving `sandbox_dir("boxlite")` above the backend branch turns `test_the_sandbox_home_stays_unresolved_for_a_backend_that_has_none` red; reverting turns it green
- The integration suites under `tests/integration/` are updated to pass the real `get_sandbox_dir("boxlite")`, but were not executed here (they need a real VM)

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

## Risk

No behaviour change on the boxlite path: the same directory reaches the same runtime, and the memo cache is still keyed on it. On the `none` path the directory is no longer created, which is the intended difference. Any caller that constructs an executor without the new argument fails at call time with a `TypeError`, not silently. Rollback is a revert of the single commit.

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

## Related Issues

N/A
2026-09-11 07:19:34 +00:00
Handsome-wzw
7b45527b5b fix(tools): an array sent as its own JSON is still an array
## Summary

Reported as "deliver_files is broken". It is not: **the tool never ran.**

Every `deliver_files` call on one install was refused before dispatch -- five in a row in a single session -- and nothing was ever delivered:

```
Error: Invalid parameters for tool 'deliver_files': files should be array
```

What the model sent was the array, spelled as a string:

```json
{"files": "[{\"path\": \"...poster.png\", \"title\": \"...\"}]", "message": "..."}
```

`cast_params` already forgives that spelling for every scalar type -- `"3"` for an integer, `"true"` for a boolean -- and did not for arrays or objects, which are exactly the types a model is most likely to stringify.

## Type

- [x] Fix
- [ ] Feature

## The edge of the forgiving is the design

When the value is a string, try `json.loads`, and take the result **only if it is the type the schema asked for**. A string that is not JSON, or is JSON of the wrong shape, is returned unchanged so the validator still names the real problem -- the point is to widen what is accepted, not to swallow a type error.

**Nothing here can raise.** Turning "your argument has the wrong type" into a traceback would be worse than the refusal it replaces, so the parse is wrapped and failure falls through.

**A `type: "string"` field is never parsed.** JSON is ordinary text in a message body or a file's content, and replacing it would hand the tool something it never asked for. Two independent things prevent it today (the string branch returns before the parse is reached, and the parse only wins on a type match), which is why the case pinning it is a tripwire rather than a load-bearing assertion -- said so in its own docstring rather than left to look like coverage.

## Not just deliver_files

Six built-in tools declare an array or object parameter and were all exposed:

| tool | parameter |
|---|---|
| `deliver_files` | `files` |
| `ask_user` | `questions` |
| `image_generate` | `images` |
| `message` | `media` |
| `create_playbook` | `skills` |
| `video_generate` | `params` |

The same failure was already seen from the other side: `acp_client/acp_agent.py` records `update_task_state` and `operations should be array` from a real dispatch.

## Verification

```
make lint-python    ruff check + ruff format --check, 1850 files
make lint-imports   9 contracts kept, 0 broken
pytest tests/       19,699 passed, 7 failed (all pre-existing, see below)
```

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots -- no user-facing string

**End to end, through the real tool**, with the exact payload that failed five times in production:

```
files sent as:            str -> [{"path": ".../poster.png", "title": "..."}]
returned:                 Delivered 1 file(s): poster.png (72 B).
still "should be array":  False
registered in the store:  True
```

Twelve cases, five mutations, each killing at least one:

| mutation | red |
|---|---|
| drop the whole branch (the old behaviour) | 3 |
| raise instead of falling through on a parse failure | 5 |
| accept the parse whatever type it yielded | 1 |
| do not re-cast the parsed value, so items are not cast | 1 |
| widen the tuple to include `string` | **survived -- unreachable** |

The last is worth stating rather than hiding: that mutation cannot change behaviour, because the `type == "string"` branch returns earlier and the type check would refuse the result anyway. I also tried moving the new block above that branch, alone and combined with widening the tuple, and neither reddens anything either. The invariant holds by construction; the case that documents it says so.

**Pre-existing failures, checked against the base.** 7 failed in the full run, all in `tests/test_security_network.py` (`test_a_redirect_to_a_dangerous_address_is_refused` and siblings). Running that file alone on this same tree gives 4 -- the count is order-dependent -- and the change touches only `raven/agent/tools/params.py` plus a new test file, neither of which `raven/security/network.py` imports. The failures are the box's resolver: it returns poisoned answers roughly half the time, which I measured separately (`en.wikipedia.org` came back as `2001::1` on 3 of 6 lookups). Not introduced here, and worth someone's attention on its own.

## Risk

- [x] Security impact considered -- widens what reaches a tool's own validation, not what bypasses it. A parsed value is still validated against the same schema, and a parse that yields the wrong type is refused exactly as before
- [x] Backward compatibility considered -- a call that worked before takes the identical path; the new branch is reached only by a `str` where an array or object is declared, which previously always failed
- [x] Rollback path is clear -- single-commit revert

## Related Issues

N/A

## Swept

`mr-review-patterns` pre-submit sweep, over `git diff origin/main...HEAD`.

- **1 (a write location moved)** -- nothing moved; a branch was added to an existing dispatch on `target_type`. Grepped every caller of `cast_params`: the registry is the only one, and it runs `validate_params` right after, which is the reader this affects.
- **2 (a value with several entry points)** -- the cast is the single funnel every tool argument passes through, which is why the fix belongs here and not in `deliver_files`.
- **3 (a guard)** -- checked both directions: what it wrongly lets through (JSON of the wrong type, non-JSON text -- both refused, with cases) and what it wrongly refuses (a real list, unaffected, with a case).
- **4 (tests)** -- five mutations above, one honestly reported as unreachable. Failing-ID sets diffed against the base rather than counts.
- **6 (stale text)** -- the module docstring enumerated what is coerced ("a string that should be an integer"); it now names arrays and objects too. Grepped the tracked tree for other statements of the rule: none.
- **9 (error handling)** -- the new path adds one way to end and it is caught: `json.loads` raises `ValueError` on bad text and `TypeError` on a non-string, and both fall through to the untouched value.
- **11** -- `git ls-files | grep -c node_modules` is 0; the commit-message gate was run, not eyeballed.

Not applicable, with reasons: **3b, 3c, 3d, 3e** (no tool schema produced, no state moved, one lane, no assertion lost its symbol); **4b, 4c, 4d** (no platform branch, no shell, no rendered number); **5, 5b** (no dependency; `json` is stdlib and already imported across this package); **6b, 6c** (no backup, no generated artifact); **7, 7b** (nothing on disk); **8** (no asset, no secret); **10** (no prompt text).

## Deliberately not fixed

The error text still ends with `[Analyze the error above and try a different approach.]`, and the model plainly did not -- it sent the same shape five times. A message naming the expected spelling (`files must be a JSON array, not a string containing one`) would give it something to act on. That is a change to the registry's error surface, affects every tool, and deserves its own argument.

## Moved from !594

Opened on a compliant source branch. AGENTS.md 2.1 asks for a 3-5 word snake_case description and the previous branch had seven; GitLab cannot change an existing merge request's source branch, so the change moves rather than the name.

Same commits, rebased onto `c2a9768f`. Both code findings from the review on !594 are already in them -- `RecursionError` caught with its regression case, and the implementation comment reduced to the two non-obvious reasons. Nothing else changed, so that review carries.
2026-09-09 15:42:36 +00:00
forrestjgq
f01231fef6 fix(cli): overhaul trajectory browser interaction ux (#379)
## Summary

Overhaul the interactive `raven trajectory` browser end to end, fixing
every
issue from real-terminal testing:

- Navigation: every screen opens with a help area under its title (page
  purpose plus "[Key] function" hotkey hints, rendered in a new readable
help color). Esc walks one level up (action -> attempt -> session); on
the
top-level session screen Esc stays put and quitting is Ctrl+C only,
which
prints a single exit notice. Esc inside a running action cancels just
that
action through a dedicated exception at the action boundary, so the back
  sentinel can never reach a conversion or the data layer; a cancelled
  report keeps its pre-confirm bundle-and-pin side effects (the existing
  declined-report contract). Back/Exit menu entries are gone; answered
  prompts erase themselves and navigation is echoed as breadcrumb lines
  with markup-escaped untrusted text.
- Tables: the session list is TITLE | ATTEMPTS | LAST ACTIVITY and the
  attempt list is # | STARTED | TURNS | SPANS | VERDICT | PIN | MERGED |
PREVIEW with green check cells. Time cells keep the year. The layout is
  budgeted per screen build from the live terminal width (row indent, a
safety margin, and inter-column gaps are all part of the math); PREVIEW
  drops as a whole column when it no longer fits, and below the dynamic
  minimum width the tightest layout is kept while the renderer clips
  overlong lines at the terminal edge. Every dynamic cell passes a
  single-line sanitization gate before width math (verdict sidecars only
  guarantee a non-empty string), cells are measured and truncated by
terminal display width (CJK is 2 cells), and fixed column widths always
  fit their headers.
- Space preview: Space on an attempt row prints that attempt's per-turn
input/output previews, collected in the same snapshot scan and sorted by
a fully-stringified key so ordering never follows log source order (the
  table PREVIEW cell derives from the same sorted collection). Any key,
arrow keys included, returns with the cursor kept on the row; the waiter
  passes the terminal's CPR reply through to the renderer instead of
  treating it as a keypress, and Ctrl+C keeps the browser-wide cancel.
- Merge hotkey: with two or more attempts, m/M opens the multi-select
merge
  (advertised in the help line; the old "Merge attempts" menu entry is
gone). The checkbox screen carries its own help line for toggle,
confirm,
  and cancel. A single attempt neither binds nor advertises the key.
- Theme and feel: new success (green check) and help (readable hint
text)
colors in both palettes, all WCAG AA on their backgrounds; a lone ESC is
flushed after 50ms instead of prompt_toolkit's 0.5s default, removing
the
  laggy Esc feel.

The data layer is untouched: changes are confined to
raven/cli/trajectory_browse.py, raven/cli/_theme.py, and their tests.
The
id-taking subcommands (raven trajectory save/list/...) behave as before.

## Type

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

## Verification

- `COLORTERM=truecolor uv run pytest tests/test_cli_theme.py
tests/test_cli_trajectory_browse.py
tests/test_cli_trajectory_commands.py -q` -> 220 passed
- `COLORTERM=truecolor uv run pytest tests/ --ignore=tests/integration
-q` -> 6917 passed; the 10 failed + 20 errors are the pre-existing
environment-dependent set, identical file-by-file on a clean main
checkout (cron, everos server, config loader, tracing viewer)
- `uv run ruff check` and `uv run ruff format --check` on the four
touched files -> clean
- PTY smoke on a CPR-answering pseudo terminal at 100 and 58 columns:
full flow (preview, merge cancel, action screen, staged Esc backout,
Ctrl+C quit) and the narrow-width degradation contract
- New coverage includes real pipe-input key-binding tests (Esc on all
four prompt kinds, Space/m/M hits, waiter key paths with CPR
pass-through), table budget/clipping boundaries at the computed minimum
width, and corrupt verdict/timestamp corpora

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

## Risk

- The interactive browser's look and key protocol change wholesale (that
is
  the point of this PR): Esc no longer quits from the top level (Ctrl+C
  does), Back/Exit entries are gone, and lists render as tables. The
machine-facing subcommands and the trajectory data layer are untouched.
- Rollback: revert the squash commit; the browser returns to the
previous
  interaction wholesale, no data migration involved.

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

## Related Issues

N/A

---------

Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-05 23:58:20 +08:00
0xKT
2f862d8ca2 feat(build): RAVEN_WHEEL_SLIM switch for a headless cloud wheel
## What

Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.

## Why

The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.

## Behavior on slim installs

- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.

## Verified

- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
2026-09-05 17:09:13 +00:00
hylarucoder
c703db6ffd feat(build): RAVEN_WHEEL_SLIM switch for a headless cloud wheel
## What

Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.

## Why

The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.

## Behavior on slim installs

- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.

## Verified

- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
2026-09-05 17:09:13 +00:00
0xKT
a671fdddcf refactor(agent): the AgentLoop constructor takes five wiring bundles and nothing else
The constructor kept a **legacy shim that folded forty-odd flat keyword names
into the wiring bundles field by field. Production stopped using it when the
entrances moved to bundles; fifty-five test files had not. Every one of those
call sites (and the helpers that forward **kw to the loop) now constructs the
bundle it means, ToolWiring / SubagentWiring / EngineWiring / TurnPolicy /
HostWiring, so a wiring field has one address in the tests as in the code. The
shim, its field-to-bundle map's private name and the docstring that promised
the old names go; resolve_wiring only fills in the default bundles.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-30 03:52:45 +08:00
0xKT
08596d7ba8 refactor(*): shape-only consumers import the provider papers from contracts
raven.providers.base defines the LLMProvider adapters subclass (retry,
sanitizing, classification, tracing) on top of the paper of the same name in
raven.contracts.llm_provider, and re-exports the paper's other shapes. Ninety
files imported from the base; only the adapters and the test fakes that
subclass it need the machinery. The forty-odd modules that merely type against
the shapes (the context engine, the sentinel, the assembly stacks, the
sub-agent backends, the consolidator) now import them from the paper, so the
dependency they declare is the one they have. The base keeps its name and its
re-exports for the modules that extend it.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-30 03:42:59 +08:00
Handsome-wzw
9a87470fdf fix(rpc): turn.started is a turn event, and says so on all three sides
## Summary

Found while investigating the first row of Dizhan's `子智能体功能与显示问题` doc (*回注内容过程中未正常显示,刷新后才会正常显示*). This is not that bug's fix, but it is a real defect on the same wire, and it is the one that explains why "前后端接线没有约定好" was a fair thing to say.

**`turn.started` is not in the `TurnEvent` union — on either side.** It has a schema component, it has a Pydantic model, and neither is reachable from the union that `tests/test_rpc_schema_match.py` walks. The 290-test contract guard has never looked at this event.

So it drifted the first time anyone touched it. `05957452` (judge a dag node) taught `announce_dag_exception` to emit:

```python
mark = {"kind": "dag", "label": run_id, "status": "exception", "run_id": run_id, "node_id": node_id}
```

while `TurnStartedEvent.payload.delegated` still declared `status: enum ["ok","error"]` with `additionalProperties: false`, and `TurnStartedPayload` had **no `delegated` field at all** under `extra="forbid"`. Verified with `jsonschema` against the published contract before changing anything:

```
Additional properties are not allowed ('node_id' was unexpected)
```

That commit did carry `exception` into `TranscriptDelegated` and `SubagentDeliveredEvent` — two of the three places this status lives. The third is the one no test covers.

**It does not crash today**, and I want to be exact about that: `SubscriptionEmitter.emit` pushes a raw dict with no validation, and the page reads only the fields it knows. But the contract test's own docstring says what the cost is — *"both sides declare `additionalProperties: false` / `extra="forbid"`, so a consumer validating against the schema rejects the whole event, not just the unknown field"*. Losing this event loses the boundary that advances the workspace turn counter and draws the delegated row.

## What this does

- `TurnStartedEvent` joins the `TurnEvent` union, in `openrpc.json` and in `raven/rpc/models.py`, so the existing sweep covers it from now on.
- The schema's `delegated.status` gains `exception`; `node_id` is declared.
- `TurnStartedPayload` gains `delegated` as a typed model (`TurnStartedDelegated`), three-valued status included.
- Both generated TypeScript clients regenerated.
- A new test drives **the exact marker `manager.py` builds** through both validators, so the next status or field fails here instead of in a client nobody is watching.

## One thing the union surfaced

`ui-tui` never handled `turn.started`. Its exhaustiveness check said so the moment the variant existed. It draws the delegated row from `subagent.delivered`, which the page deliberately ignores in favour of this event — the two mark different moments: **submitted** versus **started**.

Left as it is, with an explicit `case 'turn.started'` saying why. Moving that surface onto the truer moment changes when the TUI draws the row, which is a product change, not a contract fix.

## Verification

- New test red before the fix, by construction: adding the variant to the union alone reds `test_schema_match_turn_event_discriminated_union` and `..._payload_fields` (schema/pydantic drift), which is how the gap was proved.
- Mutation checks, each reverting one thing:

| reverted | reds |
|---|---|
| `exception` out of the schema enum | 1 |
| `node_id` out of the schema | 1 |
| `delegated` off the Pydantic payload | 2 |

- `uv run pytest -q` — **12900 passed**, 50 skipped, 5 failed; the same five pre-existing on `origin/main` (four `test_security_network.py` NAT64 cases, one `test_doctor_answers_where_the_memories_are`), reproduced on an untouched merge-base worktree.
- `uv run ruff check` / `ruff format --check` on `raven tests scripts` — both clean (both halves of `make lint-python`).
- `ui`: `gen:check` 147 methods, `type-check` clean, `npx vitest run` 89 files / **1225 passed**.
- `ui-tui`: `type-check` clean, `lint:rpc` in sync, `lint:i18n` up to date, `npm test` 138 files / **1990 passed**.
  - Worth recording: with `ui-tui/node_modules` symlinked from another checkout the suite reports 82 failed / 59 failed — and reports **the same numbers on an untouched `origin/main`**. It is the symlink, not the branch. Ran `npm ci` in the worktree to get a trustworthy number.
- `scripts/commit_lint` — no errors.
- `git ls-files | grep -c node_modules` — 0.

## Type

- [x] Fix

## Risk

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

Widening a contract to match what the runtime already emits: every payload valid before is valid now. No emit site changes, no behaviour changes. The one code change outside the schema and the models is an explicit no-op branch in `ui-tui`. Rollback is a revert.
2026-08-28 12:51:10 +00:00
forrestjgq
8ecfae3e0c test(tracing): isolate span emission into per-test tmp dirs (#371)
## Summary

Unit tests were leaking tracing spans into the real `~/.raven/traces`
store. Tracing is on by default and `trace.span()` calls are embedded in
library code (agent loop, subagents, TUI RPC), so any test exercising
those paths emitted spans with fabricated session keys (`session-a`,
`weixin:c`, `tui:default`, ...). Those spans then surfaced as phantom
sessions in `raven trajectory`, while the TUI `/sessions` list (which
reads the real session store) stayed clean.

This PR adds an autouse fixture in `tests/conftest.py` that:

- redirects `RAVEN_TRACING_DIR` to a per-test tmp directory, and
- resets the lazy module-level `TraceStore` cache
(`raven.tracing.spans._store`) around each test, since it pins the
directory resolved at first emit.

Key decisions:

- Only the directory is redirected, not the enabled switch, so the suite
keeps exercising the real emission path with zero behavior change; leaks
land in tmp instead.
- This centralizes the setenv-plus-cache-reset pattern that 8
tracing/trajectory test files already perform manually. Those tests keep
working: their own `monkeypatch.setenv` runs after the fixture and wins,
and they already reset the cache themselves.
- Existing phantom sessions come from archived span logs written before
this fix; the fixture only prevents new leaks. One archive file mixes a
real session with test keys, so cleanup needs line-level filtering and
is left out of scope.

## Type

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

Test-suite hygiene (`test` commit type).

## Verification

- `uv run pytest tests/test_tracing_api.py
tests/test_trajectory_store.py tests/test_trajectory_bundle.py
tests/test_trajectory_replay.py tests/test_trajectory_redact.py
tests/test_cli_tracing_commands.py tests/test_cli_trajectory_commands.py
tests/test_cli_trajectory_browse.py -q`: 308 passed, 1 failed
(`test_viewer_health_true_for_our_viewer`, fails identically on
unmodified `main`, environment-specific)
- `uv run pytest tests/test_agent_loop_run_emit.py
tests/test_subagent_manager.py tests/test_tui_rpc_turn_send.py
tests/test_deep_research_tool.py tests/test_agent_loop_approval.py -q`:
109 passed; the real `~/.raven/traces` log did not grow during the run
- Positive check: running `tests/test_agent_loop_run_emit.py` with
`--basetemp` shows the previously leaked session keys (`cli:c`, `tg:c`,
`weixin:c`) now land in per-test tmp dirs
- `uv run pytest tests/ --ignore=tests/integration -q`: 6837 passed, 11
failed, 20 errors; the same failure set reproduces on unmodified `main`
(environment-specific: cron/tz, everos server, theme, config loader,
viewer health), zero regressions from this change
- `uv run ruff check tests/conftest.py` and `uv run ruff format --check
tests/conftest.py`: both pass

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

Docs box left blank: test-only change, no user-facing docs affected.

## Risk

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

Test-only change; no production code touched. One known interaction:
`RAVEN_TRACING_DIR` takes precedence over `RAVEN_HOME`, so a future test
that fakes `RAVEN_HOME` and expects traces under it must also set
`RAVEN_TRACING_DIR` itself. Rollback: revert the single commit.

## Related Issues

N/A

Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-28 19:21:16 +08:00
arelchan
7c33c4133a fix(rpc): let the viewer open the files a turn actually wrote
## Summary

A delivered artifact could not be opened from the page: the file viewer answered
403 and the transcript drew "Raven is confined to the workspace, so this file
cannot be opened here" over a delivery card it had just rendered.

The viewer's state-directory fence exempts the workspace subtree, on the stated
grounds that the default workspace lives inside raven's home and denying it
would refuse every file the agent itself wrote. Since agent home and the working
directory were split apart, a turn no longer writes there: it writes in
`~/.raven/tmp/<channel>`, a sibling of the workspace, inside the same state root
and outside the carve-out. So the fence denied exactly what the carve-out exists
to allow, one directory over, for every artifact produced since that split.

This exempts the working-directory root alongside the workspace, using the same
containment test in the same direction, so a working-directory root that happens
to sit above raven's home earns no exemption. `config.json`, `oauth/` and
`serve.json` are siblings of both and stay refused, which is what the fence is
for.

Worth noting for a reviewer: the bytes were already reachable. `/files/download`
serves a delivered file by token with no path fence, so this was never a
security boundary for deliveries -- only a viewer that refused to render what
the same page could already download.

## Type

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

## Verification

- `uv run pytest tests/test_rpc_transport.py tests/test_rpc_files.py tests/test_rpc_knowledge.py tests/test_rpc_console.py -q` -> 123 passed
- `uv run ruff check` and `uv run ruff format --check` on both changed files -> clean
- Both new assertions were mutation-checked, each against its own mutation:
  - narrowing the carve-out back to the workspace alone reds
    `test_the_turn_working_directory_is_exempt_from_the_state_dir_fence` only (1 failed, 3 passed)
  - dropping the containment-direction guard reds
    `test_a_working_directory_root_that_contains_the_state_root_earns_no_exemption`
    and the pre-existing state-dir test (2 failed, 2 passed)
- Against the real reporting case: the two files that were answering 403
  (`~/.raven/tmp/tui/*.md`, `*.pptx`) now resolve, while `~/.raven/config.json`
  and `~/.raven/serve.json` still raise PermissionError.

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

## Risk

- Widens what the file viewer will render by exactly one subtree: the directory
  turns work in. Everything the fence was written to protect (provider keys in
  `config.json`, the OAuth token store, `serve.json`) sits beside that subtree,
  not inside it, and stays refused -- pinned by the tests above.
- `fs.list` / `fs.reveal` share the function but pass the session's working
  directory as the root, which their own containment check already bounds, so
  their behaviour is unchanged.
- Rollback is a one-line revert of the exemption tuple.

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

## Related Issues

N/A
2026-08-28 04:57:29 +00:00
LivXue
4e35a5d627 fix(tui): show the copy-on-select confirmation as a transient notice (#366)
## Summary

PR #360 reports every copy-on-select write as a permanent transcript
line, so a
reading session that drags through the transcript piles up "copied N
characters" rows under the conversation. The confirmation splits by what
the
line is for: the unbounded terse repeats become a transient notice
rendered
above the input box -- one line that replaces itself on every new copy
and
clears after 3 seconds -- while the first copy of a session keeps its
path
caveat in the transcript. The caveat is the answer a user comes looking
for
after a paste comes up empty minutes later, and it cannot pile up
because it
is once per session by construction.

The reporter still owns the per-session caveat tally and now returns
`{ text, firstOfSession }` so the caller can route the caveat to the
transcript and the repeats to the notice. A new `copyNoticeStore` holds
the
single notice; `showCopyNotice` keeps one dismiss timer, clearing any
pending
one before arming the next, so an earlier deadline can never clear a
newer
notice. `/copy` is deliberately untouched: an explicit command's answer
still
belongs in the transcript, and it cannot stack on its own.

## Type

- [x] Fix

## Verification

Run from `ui-tui/` at branch head, in a fresh worktree of `github/main`.
Dependencies came from `npm ci` in `ui-tui/` and in the hermes package;
the
hermes package's own `node_modules` holds only esbuild, so the ink
render
tests run against one react copy (two copies break every hook call).

```
npx vitest run --no-file-parallelism
  Test Files  93 passed (93)
  Tests  1084 passed | 13 skipped (1097)

npm run type-check
  clean, exit 0

npm run lint
  22 problems (0 errors, 22 warnings)

npx prettier --check src/app/copyNoticeStore.ts src/__tests__/copyNotice.test.tsx
  src/__tests__/clipboard.test.ts src/app/useMainApp.ts
  src/components/appLayout.tsx src/lib/clipboard.ts
  All matched files use Prettier code style!

python3 -m scripts.check_commit_messages github/main..HEAD
  exit 0
```

The 22 lint warnings are the baseline, not new: 22 before the branch and
22
after, none in a file this branch touches. The suite is run with
`--no-file-parallelism` deliberately: the ink render tests fail under
default
worker parallelism at this suite size, and no CI job runs them.

Suites that exercise the changed code directly:
`src/__tests__/copyNotice.test.tsx`
(7 cases), `src/__tests__/clipboard.test.ts` (30 cases, the 3 reporter
cases
updated to the new return shape).

New tests were proved load-bearing rather than assumed:

- Removing the notice render line in `appLayout.tsx` makes the render
test
  fail (content and placement above the input box).
- Removing the pending-timer clear in `showCopyNotice` makes the
re-shown-notice test fail: the earlier 3s deadline then clears the newer
  notice.
- The dismissed-notice case now shows a notice first, and removing
  `dismissCopyNotice`'s atom clear turns it red (review fix).

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

No doc change. `ui-tui/CONTEXT.md` has no clipboard or selection entry,
and
"copy notice" continues the existing "notice" vocabulary of
`copyResultNotice`
/ `copyOnSelectNotice`, so nothing new is coined.

## Risk

Behaviour change: the per-drag copy confirmation is now transient and
above
the input box instead of a permanent transcript line, and the first copy
of a
session lands one transcript line, exactly as on `main`. Reverting the
branch
restores the #360 behaviour; no data or on-disk format is involved.

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

## Related Issues

N/A

---------

Co-authored-by: Claude (deepseek-v4-pro) <noreply@anthropic.com>
2026-08-25 14:27:24 +08:00
gloryfromca
df9a7d7f37 chore(*): merge upstream v0.1.13 into the gitlab trunk
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.13 becomes a real ancestor: the next sync starts from v0.1.13
instead of v0.1.12, and the eventual contribution back to GitHub can still tell
our commits from the upstream ones it already has.

Cost this round: 51 conflict hunks over 27 files, against 54 over 31 for
v0.1.12. The hunks were the cheap half. Upstream's #284 moves the model and
provider from process-wide state to a per-session binding, and the trunk had 230
commits standing on the old shape.

What git reported as a clean merge and was not
---------------------------------------------

Fourteen upstream-changed paths do not exist here, because we renamed or moved
them since v0.1.12. Rename detection found none of them, so their changes were
merged into paths nothing reads, silently:

* raven/tui_rpc/* -> raven/rpc/* (renamed in ce526ad5). Nine files, including
  question_broker.py, whose whole #354 rewrite was lost, and methods/config.py,
  methods/model.py, methods/session.py, models.py and errors.py. Each was
  replayed by three-way merge against dd82f52c. The three test modules were
  rebased function by function onto upstream's version instead, after a
  three-way merge spliced assertions into the wrong tests.
* raven/agent/tools/mcp.py -> raven/mcp/client.py. Carried the release-blocking
  fix, and is handled in the commit that follows this one.
* ui-tui/rpc-schema/openrpc.json -> rpc-schema/openrpc.json.

Decisions
---------

Follow upstream wherever the two disagree about provider and model:

* providers/pin.py is gone, so a bare model id is refused instead of derived.
  A model id does not name whose credential serves it, and the derivation
  walked a list -- with two vendors configured, which one pays came down to
  their order in it. rpc/methods/config.py now requires the provider.
* ModelSwitchInTurnError (-32009) is gone with it. A session switch lands on
  that session's next turn, so there is nothing to refuse mid-turn.
* AgentLoop.refresh_context_window and the LazyProvider on_built wiring are
  gone: the window rides on the binding now.
* The skill gate no longer forwards an unpaired pin.

Keep ours where the trunk is ahead, and graft upstream's behaviour into it:

* raven/agent/subagent/backends/raven_loop.py is the live sub-agent path, so
  manager.py's inline loop stays retired and the web_search gate from #312
  applies there.
* skill_hub/client.py keeps the public zip limits the skillhub RPC path imports,
  and takes upstream's query-string cap.
* ask_user keeps our JSON-string normalizers and feeds them into upstream's
  batch contract, so a batch validated by _prepare is one _normalize_questions
  has already coerced.
* The chat view composes both filters: hideIntroAfterFirstTurn drops the cover,
  visibleRows still hands the view to a direct chat.

Tests removed, not repaired
---------------------------

Eight tests covered mechanisms this merge deletes, and one of them hung rather
than failed:

* seven in test_agent_loop_model_switch.py over AgentLoop._pending_provider,
  the switch-parking mechanism #284 replaced with per-session bindings. Its
  replacement arrives with upstream as test_agent_loop_session_model.py.
* test_a_refusal_during_a_turn_keeps_its_own_code in test_acp_methods.py, whose
  error class no longer exists.

Baseline: the pipeline for 01d39e58, this merge's base, is green, so nothing
here can be charged to a pre-existing failure.

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-25 16:12:43 +08:00
Handsome-wzw
a1d5b24de3 feat(agent): withhold web_search without a key, and make tool capabilities visible (#312)
## Summary

A WeChat user asked for a recommendation and the bot answered "the web
search
tool is not configured here". That sentence was not the model's own
phrasing --
it was the tool's error text, relayed outward. `web_search` needs a
Serper key
and that deployment has never had one, but the tool was registered
unconditionally, so on every search-shaped question the model saw it,
reached
for it, and passed the setup error on to whoever was in the chat.

Withholding the tool fixes that and creates a second problem: an
unregistered
tool is invisible. Nothing in a running Raven then says the capability
exists at
all -- the model is never offered it, no document lists it, and `raven
doctor`
reports on providers and memory but has never mentioned tools. The only
way to
learn that web search is one account and one edit away was to read the
source.

This does both halves, because either alone leaves a real gap: the
deployer is
told what this install can and cannot do, and the model is still not
offered a
tool it cannot run.

### Withholding the unusable tool

`web_search` is gated on a resolved key, in the main loop and in the
sub-agent
surface (`subagent/manager.py`) -- a sub-agent that reaches for a search
it
cannot run reports the failure to its caller, and that text lands in the
parent
turn, the same leak one level down.

The gate asks the tool, not the config. `WebSearchTool.api_key` resolves
at call
time from the constructor value *or* `SERPER_API_KEY`, so reading
`tools.web.search.apiKey` alone would withdraw a working tool from any
deploy
that exports the variable and configures nothing.

The tool's error message also hard-coded `~/.raven/config.json` while
the
gateway runs with `--config` elsewhere, so following it meant editing a
file the
process never reads. It names the path actually in force now. That text
is
reachable only if the key disappears after registration, which is
exactly why it
should be right: it is the message for the case the gate cannot cover.

### Three rules, and nowhere to read them

Registration is decided per family, each a different shape:

| family | rule |
|---|---|
| `web_search` | a resolved key, asked of the built tool |
| `web_fetch` | nothing -- always registered, a key only improves
extraction |
| media x3 | an `api_key` *or* a `model`, either counting as configured
|

For media those are two questions, not one. A section naming only a
model is
registered, because a model alone counts as asking for the tool, and
then every
call returns a missing-key error. Whether a capability is *offered* and
whether
it *works* come apart there, and a report treating them as one fact
ticks a
capability that cannot run.

Each rule is defensible where it sits. What is missing is anywhere to
read them.
Providers had the same sprawl once and answered it with
`providers.auth`: a
declarative table plus `credential_status` as the single authority, with
an AST
invariant enforcing that authority, because six surfaces had answered
the same
question six ways and each looked reasonable alone. Tools never got the
equivalent.

### What this adds

**Each tool answers for itself,** twice where the questions differ.
`WebSearchTool.is_configured` reads the config value *or*
`SERPER_API_KEY`,
because those are two sources and only the tool consults both. The media
base
answers `is_configured` on a model *or* a key -- which is what stops an
OpenRouter credential set for chat from silently switching on three
tools that
bill per call -- and answers `has_key` separately on the chain it
actually
resolves at call time: its own section, the borrowed provider key, then
`OPENROUTER_API_KEY`. Both rules live with the credential they read.

**`capabilities.py` describes the five** for a human deciding what to
set up:
what each does in one line, how much work it is (nothing / reuse a
credential
you already have / obtain an account), where the key goes, where to get
one, and
what it costs. It rules on nothing -- `is_configured` and
`has_credential` both
ask the tools -- so it cannot become a second opinion.

**`raven doctor` grows a section**, listing every capability configured
or not,
ordered by how much the deployer has to do:

```
(markers render as a green check and a yellow bang; spelled [ok] and [!] here to
keep this description ASCII, since it becomes the squash commit body)

Tool capabilities
  web_fetch:       [ok] Read a web page the agent already has the URL for
  image_generate:  [ok] Generate an image  (borrowed: providers.openrouter.apiKey)
  text_to_speech:  [!] Generate speech from text
                   no key resolves; calls will fail
                   set: tools.media.speech.apiKey
                   or env: OPENROUTER_API_KEY
  video_generate:  -  Generate a video
                   switch on: tools.media.video.model
                   key: reusing providers.openrouter.apiKey
                   Billed per call; needs prepaid OpenRouter credit.
  web_search:      -  Search the web
                   set: tools.web.search.apiKey
                   or env: SERPER_API_KEY
                   key from: https://serper.dev
  2 capability(s) available but not set up; the agent is not offered them.
```

Three deliberate details.

Naming the credential is load-bearing in both directions. A row that
cannot
distinguish a reused credential from a missing one sends someone to
create an
account they already have -- and a row that claims a reuse with nothing
to reuse
is worse, because acting on it means setting a model, getting a
registered tool,
and watching every call fail on a credential they were told they had. So
the
reuse line prints only when a key is genuinely there to pick up, and a
capability already in that broken state says so outright instead of
showing a
satisfied tick.

The credential is named at the path that holds it. For the media family
`config_path` names the *model*, so reusing it as the key source pointed
the
deployer at a line with no credential in it.

And each fact is on its own line rather than in a sentence, because the
terminal
wraps a long line mid-path and a config key broken across two rows
cannot be
copied, which is the only thing that row is for.

Nothing here moves the exit code, including the warned row. An install
without
image generation is a choice, not a fault, and a doctor that fails on it
teaches
people to ignore doctor. The half-finished one is arguable -- the memory
section
does exit non-zero for a role the user configured that the server could
not
build -- but that failure is silent where it happens, recall just
returning
nothing, whereas this one returns an error string to the model on every
call.
Say the word and it becomes an exit code instead.

### Not in this change

Registration still lives in `AgentLoop`. Having it read the table is the
point
of this shape and removes the last duplicate reader, but it edits
`agent/loop/main.py`, which is under active change, and it is worth
doing on its
own once that settles. Until then the table is a description, and the
tests
below are what keep it honest.

`deep_research` is deliberately absent: it is moving to the sub-agent
surface
and its tool is going away.

## Type

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

Mixed on purpose: the first commit is a fix and the rest are the feature
it
made necessary. Splitting them would land a change that hides a
capability
without landing the one that makes it discoverable.

## Verification

```
make lint                                            exit 0
make build                                           exit 0
npm run test --prefix ui-tui                         969 passed, 13 skipped
uv run --all-extras pytest -q                        6186 passed, 35 skipped, 1 failed
uv run pytest tests/test_tool_capabilities.py \
              tests/test_cli_doctor_commands.py \
              tests/test_agent_loop_web_tools.py     64 passed
uv run --extra dev ruff check raven tests scripts    All checks passed
uv run --extra dev ruff format --check               828 files already formatted
npx commitlint --from origin/main --to HEAD          exit 0
scripts/check_commit_messages.py origin/main..HEAD   exit 0
```

The one failure is
`test_read_file_image.py::test_an_attachment_that_cannot_be_
read_costs_a_note_not_the_turn`, and it is not from this branch: it
fails the
same way on `main` at `1cb604a` with these commits absent. The case
makes a file
unreadable with `chmod 000`, which does not block a root user, so it
fails for
anyone running the suite as root and passes in CI. This branch does not
touch
that file or the code under it.

The capability tests drive a real `AgentLoop` and compare what it
registered
against what the table predicts, rather than asserting the table against
itself.
The gated set is derived -- tools present once credentials are supplied,
absent
without -- so a sixth gated tool whose author forgets the table fails
here rather
than going unnoticed.

That last claim was false when first written, and the last commit is
what makes
it true. The fixture listing the media tools by hand never switched a
fourth one
on, so a new one never joined the gated set and the assertion held over
an
already-incomplete table. #305, which adds a MiniMax voice-clone tool,
is that
case: merged against this branch the assertion passed. Read from
`MediaGenConfig` instead, it fails and names the tool -- `gated but
undeclared:
['voice_clone']`.

Which means whichever of the two lands second turns this red,
deliberately. The
fix is one table entry, and it needs the rule that PR settles:
`voice_clone`
counts as configured on `api_key or api_base or model` in
`effective_media_config` while registration still gates on `api_key or
model`,
so an `apiBase`-only install with no MiniMax key is configured by one
rule and
withheld by the other. That is the divergence this table exists to make
visible,
and it is worth resolving there rather than papering over here.

Fifteen mutations, each caught:

```
the web_search gate removed from the main loop    3 failed
the same gate removed from the sub-agent surface  1 failed
media rule reads only the key                     7 failed
web_search rule reads only the config             1 failed
a tool removed from the table                     6 failed
the doctor section not rendered                   6 failed
doctor lists only configured tools                4 failed
unconfigured treated as a failure                17 failed
the reuse line is printed unconditionally         1 failed
the key source falls back to the model path       3 failed
a keyless registered capability is not flagged    1 failed
has_key always answers yes                        1 failed
has_credential collapses into is_configured       1 failed
the credential chain drops OPENROUTER_API_KEY     3 failed
the reuse check ignores the environment           3 failed
```

Four of those tests exist only because a mutation pass found the earlier
versions insufficient, and the last rounds are why the shape changed. A
media
case that sets both a model and an OpenRouter key proves nothing about
the "or
model" half: the borrow fills the key in, so a rule reading only the key
still
answers correctly. The case that pins it has nothing to borrow.

The sub-agent case is the same argument applied to the second call site:
with
the gate present only in the main loop, every test above still passes,
because
nothing was watching what the sub-agent surface registers.

More usefully, mutating `has_key` to always answer yes changed no test
at all in
the first version, which said the ruling was not load-bearing: the
doctor was
inferring "no credential" from an *empty source string* rather than from
the
tool's answer, so a fourth credential source would have been reported as
a
missing one. `has_credential` is now its own fact, asked of the tools,
and that
mutation fails.

Separately, autouse fixtures clear `SERPER_API_KEY` and
`OPENROUTER_API_KEY`,
without which several of these pass for the wrong reason on any machine
where a
developer exported one.

Rendering was checked against a real config in six states -- nothing
set, a
provider key present, a model with nothing to borrow, a tool with its
own key, a
model plus a borrowable key, and an exported variable as the only source
--
rather than only asserted on.

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

## Risk

One behaviour change: `web_search` is no longer offered to the model
when no key
resolves. That is the fix. A deployment that has a key, in config or in
the
environment, is unaffected; one that has none was getting an error
string in
place of an answer.

The rest is additive. No other registration logic changed, so which
tools an
agent is offered is otherwise exactly what it was; `is_configured` moved
the
existing predicates onto the tools without altering them, and the
mutation
results above are what pins that. `has_key` and `_resolve_key` are new
names for
the chain `api_key` already resolved -- the property calls the extracted
one, so
callers see the same answers.

`raven doctor` gains a section and no new exit code. Its zero-network
guarantee
holds: the table reads config and environment only.

Two allowlist entries were added to
`test_only_the_auth_module_decides_configuredness_from_a_key`, argued in
place:
`subagent/manager.py`, which asks the built tool whether a key resolved
so an
unusable search is withheld, and `capabilities.py`, which reads keys to
*report*
-- which source supplied one, and whether one is there to reuse. Both
ruling
halves are delegated to the tools, whose files were already listed.

Rollback is a revert. Nothing is written and no configuration is read
differently.

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

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-25 10:05:58 +08:00
arelchan
82eea1dd20 fix(ui): show Raven logo as page favicon
## Summary

- Declare the existing Raven application logo as the served page favicon.
- Copy the logo into the packaged page assets so installed builds render the same branding.

## Type

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

## Verification

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

- `npm test --prefix ui` - 32 test files and 528 tests passed.
- `npm run type-check --prefix ui` - passed.
- `npm run build --prefix ui` - passed.
- `python3 ui/build.py` - built the page and copied the Raven logo asset.
- `node ui/scripts/check-page.mjs` - passed.
- `make check-large-files` - passed.

## Risk

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

Low risk. The change only adds favicon metadata and packages an existing application asset. Reverting the two source changes restores the prior browser-default icon.

## Related Issues

N/A
2026-08-23 11:11:06 +00:00
gloryfromca
56858acbce fix(*): report an invalid memory identity as the config error it is (#350)
## Summary

An identity EverOS cannot accept becomes a directory segment on its
write path, so `EverosBackend.start()` rejects it. The rejection carried
the one message a user can act on -- it names the key and the accepted
pattern -- and no surface delivered it as one. Three of the four call
sites fold the raise into `logger.exception`; under the TUI loguru is
file-only, so there an invalid identity turned memory off with nothing
on screen. The fourth, in `import_commands._build_and_run`, is not
wrapped at all, so the `ValueError` escaped as a bare traceback. Where
it was visible it was a traceback, which is not a thing a user reads as
"edit this key".

The state machine then told the user the opposite of the truth.
`start()` died before assigning a state, so `_state` stayed `UNKNOWN`,
which is not in `_NEVER_HAD_MEMORY`; every `store()` after it counted a
dropped write, and the session ended with:

```
1 turn(s) were not written to long-term memory because the memory service was
unavailable.
```

The service was fine. That sends the user to debug a server that never
broke.

**The change.** Catch the `ValueError` in `start()`, give it a
`BAD_IDENTITY` state, and file that state with the other two the user
must fix themselves:

- terminal, so a stray probe cannot promote it to `READY`;
- never-had-memory, so no dropped-write count and no outage wording;
- the message goes to stderr, matching what the unconfigured-LLM and
missing-binary paths beside it already do.

Two things came out of running it rather than reading it:

1. **The message needs escaping.** It quotes the accepted-character
class, and rich reads `[a-zA-Z0-9_.@+-]` as a markup tag and eats it,
leaving the user the pattern `^+$` to match their id against. The test
now pins the full class.
2. **`raven import` had the same defect on its own gate.** It kept the
outage wording and pointed at the server log, which holds nothing about
a config error. It now names the config keys instead.

Before / after, same config (`memory.userId: "bad/id"`), same command:

```
- 1 turn(s) were not written to long-term memory because the memory service was
- unavailable.

+ Long-term memory is off: memory.userId='bad/id' is not accepted by EverOS: it
+ becomes a directory segment on the write path, so it must match
+ ^[a-zA-Z0-9_.@+-]+$ and must not be '.' or '..'.
+ Fix memory.userId / memory.agentId in your config.json, then start a new session.
```

## Type

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

## Verification

Re-run after rebasing onto `d35e398c`, the current `main`.

```
uv run pytest tests/test_everos_backend.py tests/test_cli_import_commands.py \
              tests/test_everos_plugin_discovery.py -q
162 passed

uv run pytest -q
1 failed, 6478 passed, 43 skipped, 13 deselected

uv run ruff check <the four touched files>            All checks passed
uv run ruff format --check <the four touched files>   4 files already formatted
```

The one failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`. It
is pre-existing on this base: checked out `d35e398c` in a clean worktree
and ran `uv run pytest tests/test_cli_theme.py` there, same failure, 1
failed / 44 passed. It passes in isolation and fails when the file runs
as a whole, so it is order-dependent, and it is unrelated to anything
here. That file is untouched by this change.

Manual check, sandbox `RAVEN_HOME`, `memory.userId: "bad/id"`, `raven
agent -m "hi"`: prints the block quoted above, and the session no longer
ends with the dropped-write line.

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

## Risk

Terminal-only wording plus one new enum member. No config, schema, or
protocol change; an identity that was accepted before is accepted now,
on the same code path. The only behaviour change for a valid setup is
none.

For an invalid identity the turn behaves as it did -- memory off, turn
completes -- and only what the user is told changes. Rollback is
reverting the single commit.

`ServiceState.BAD_IDENTITY` is new. Every consumer was checked:
`raven/cli/import_commands.py` (handled here) and
`tests/test_everos_plugin_discovery.py` (reads `READY` only).
`_may_spawn` allowlists `UNKNOWN` via `_SPAWNABLE_STATES`, so a new
member is non-spawnable without a change.

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

## Related Issues

Fixes #271

Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-20 14:41:45 +08:00
arelchan
feacba682c refactor(ui): the session rail becomes a react island
## Summary

The session rail (left sidebar) becomes a React island: `ui/src/features/rail/` with types, a plain external store (draw/skeleton/markNew/remove/rename, fold state on the `raven.gui.grpfold` localStorage key), the Row/Group/RailApp components with classes and DOM shape copied byte-for-byte from the legacy renderer, and 13 tests.

Key decisions:
- `SESS`/`cur` stay shared page globals: ten demo/live files write them (including whole-array rebinds), so the island owns no rows. It reads through `DS.sessions.snapshot()`, a closure over the rebindable bindings, re-read on every `drawList()`.
- Island actions go out through 9 new optional bridge verbs (`drawList, setCur, openSession, removeSession, renameTitle, dropDraft, pinPersist, openCron, navState`), each one a guarded one-liner in 155-bridge.js and late-bound so live rebinds keep winning.
- `plainTitle` moved into the bundle and is republished as `window.plainTitle` for its 6 legacy callers (same pattern as `cronExprHuman`).
- Shrink: demo/050-rail.js 222 -> 16 lines; live/010-boot-guard.js raw-DOM skeleton painter became one `RavenIslands.rail.skeleton()` call; live/030-sessions.js untouched (already renderer-free, its helpers are read by other domains).
- Pre-existing bug left as-is: live/080-overrides' rename persist wrapper queries `#title input` after the h1 swap and throws today; the island reproduces the demo DOM dance exactly rather than patching another domain in this MR.

Ratchet: 57 -> 57 (the strands touching this domain remain demo-declared/live-assigned by design; nothing new added).

Note: pipelines are currently red project-wide with `ci_quota_exceeded` (shared-runner minutes exhausted). Local gates below are the same commands CI runs; the pipeline should be retried once quota recovers.

Review round: the fake shell handed `markNew` an empty nav and a folded More group, so both of its branches were dead in every test -- exactly the part of the port that changed shape (`Object.keys(NAV_OF)` to `nav.pages`, `$('#' + p)` to `getElementById`, `MORE_ROWS[i][0]` to `nav.morePages[i]`). Two cases added with the real nav: a module page up marks its own rail button over the new-task row, and an open More group puts the mark on the row whose page is up while the parent gives it up and takes it back when folded. Both fail against a wrong port.

## Type

- [x] Refactor

## Verification

- `npm run --prefix ui type-check` clean
- `npm test --prefix ui` 49/49 (13 new rail tests)
- `npm run --prefix ui build` (223.95 kB IIFE) and `python3 ui/build.py` (1,094,616 bytes)
- `node ui/scripts/check-page.mjs` OK; `node ui/scripts/count-shared-globals.mjs` 57/57
- `uv run pytest tests/test_ui_language_repaint.py` 9/9
- Stub browser pass (`?stub=1`): DOM byte-compared to legacy (.grp/.sess shapes, aria-current moves, fold persistence, search, pin+persist, delete+undo toast, rename via top bar, running mark lifecycle, More flyout marks, zh/en repaint)
- Live pass against a throwaway gateway (temp RAVEN_HOME, dummy keys, nonce auth): boot shows exactly 6 skeleton rows with the legacy width formula while `data-counts="pending"` holds, then the real list swaps in; draft's first send creates a real session; two-session switching moves a single mark; second boot renders with no mock flash
- Not exercised live: a successful provider turn and parked done/err badges (needs a real key); covered by unit tests and the stub replay

## Risk

User-visible behavior is intended to be identical; the rail DOM shape and class names are unchanged. Rollback is reverting the single commit.

## Related Issues

N/A
2026-08-20 06:17:21 +00:00
arelchan
e32f4b6034 fix(*): keep migration notices off stdout, and stop planting defaults (#346)
## Summary

Three follow-ups from #341, which fixed a retired `contextWindowTokens:
65536` capping every upgraded install at 64k. Two are its loose ends;
the third is the reason it happened at all.

**The notice no longer prints on stdout.** #341 drains config-migration
notices in the `run()` wrapper so every command tells the user, which
caught the two whose stdout is a machine-readable document: `raven
doctor --json` and `raven import --json`, both advertised for
automation. Reproduced -- a config still carrying the retired pin makes
`doctor --json` emit JSON with a sentence after it, and `jq` refuses the
result. Moved to stderr, where the rest of this class of message already
goes (the `ConfigReadError` branch a few lines up in the same wrapper,
and the loader's malformed-config warning). That fixes any future
`--json` command without it having to know this exists, which
allow-listing the two would not. The window is narrow -- the migration
fires once per install -- but the run it can spoil is a first run after
upgrading, and a CI job is exactly the caller not watching.

**`raven doctor` gains a Config section and a `--fix`.** The premise
changed while building it: the migrations run at load, so by the time
this command looks, nothing is pending -- they already happened,
silently, one launch ago. What is left for a person to ask about is what
Raven deliberately will not decide for them. So it reports a
`contextWindowTokens` pinned below what the configured model holds, and
names what rides on it: the per-turn history budget, when the Curator
starts paying for a slow path, and when memory consolidation archives.
`--fix` removes the pin.

Reported without `--fix`, never written: that pin is a real
configuration for a local model or an endpoint served smaller than the
catalogue thinks, and the flag is the user saying which case theirs is.
The write carries the file mode across (config.json holds
`providers.*.apiKey`) and uses a per-PID temp name -- the same rules the
loader's migration writer follows.

One check rather than two. A config naming no provider is the other
thing worth asking about, but it reads differently on either side of the
explicit-provider rule in #284, so it belongs to that change; a model
that routes to nothing is already reported above it.

**The bootstrap stops writing every default into the user's config.**
This is the cause of the bug #341 cured. `save_config` dumped the whole
`Config()`, so a new install started life with eight kilobytes of
settings its owner had never heard of and, worse, with that day's
defaults frozen into their file -- after which a default we improve
never reaches anyone who already has one. `contextWindowTokens: 65536`
got onto disk exactly this way.

It now writes only what differs from the defaults. Lossless on reload,
since a value equal to its default reloads as that default. A fresh
config drops from 7,985 bytes to 2, and to 634 once the extension blocks
are seeded -- what is left is the handful of lines someone actually
chose, which is also a config they can read.

That third one is the only change here with a broad blast radius, and it
has one visible consequence, which is an improvement: the onboarding
picker used to lead with the schema's default model, because the
bootstrap had written it into the config and the wizard read it back as
"the current model" -- a value nobody had chosen, offered as though
somebody had. With nothing written, the wizard leads with the provider's
own recommendation instead. The test that pinned the old list now pins
the new one and says why.

## Type

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

## Verification

```
pytest tests/                       6650 passed, 1 failed, 33 skipped
                                    (tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare,
                                    which fails identically on github/main when its file runs
                                    together and passes alone on both)
ruff check raven/ tests/            All checks passed
ruff format                         clean
```

Driven by hand as well as by tests, each against a throwaway home:

```
doctor --json on a fossil config   stdout parses as JSON again; the notice is on stderr
doctor    (pin 65536, model 1M)    reports the pin and what is sized against it
doctor --fix                       pin removed, file still 0600, a second run reports nothing
save_config on a fresh Config()    2 bytes; 634 after the extension blocks are seeded
```

New cases cover the stderr split, both doctor paths including the mode
preservation, and the save round-trip keeping every value the user
chose.

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

## Risk

The bootstrap change alters what every new install's config file looks
like: nearly empty instead of a full dump. Existing configs are
untouched -- nothing rewrites them -- and both shapes load identically,
so the risk is confined to anyone reading `config.json` as documentation
of what can be set. `raven doctor` and the schema remain the answer to
that question.

The onboarding picker's default moves from the schema default to the
provider's recommendation, as described above.

`doctor --fix` writes only when asked, and only removes a key.
Everything else here is output routing.

Rollback: revert the commits. Nothing persists a new format, so a
reverted build reads every config written under this one.

## Related Issues

N/A

---------

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-18 18:55:29 +08:00
LivXue
32f8044e86 feat(*): direct chat with a sub-agent instance, in the TUI and the web UI
## 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
2026-08-17 02:52:57 +00:00
Elliot Chen
9bc959d7c5 docs: redesign README around benchmark proof (#280)
## Summary

- Reframe the README around benchmark evidence, onboarding, Deep
Research, and Tracing.
- Restore the main branch's opening product capability overview before
the benchmark evidence.
- Keep the table of contents removed and place the native Markdown
benchmark table directly after the introduction.
- Remove outbound links from the three benchmark row labels while
preserving the reported results and supporting context.
- Synchronize the English and Chinese READMEs around the same structure,
spacing, and Back to top section boundaries.
- Place the GitHub User Content onboarding recording directly below the
benchmark table in both READMEs, using the same bare attachment URL.
- Reduce duplicate capability, gateway, status, and ecosystem copy while
preserving concise architecture and command references.
- Document current runtime behavior for the six-step onboarding flow,
MiroThinker-backed research delivery, and local trace storage.

## Type

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

## Verification

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

Commands and results:

- `.venv/bin/pre-commit run --files README.md README.zh-CN.md` - passed
all applicable hooks.
- `git diff --check origin/main...HEAD` - passed.
- `make check-large-files` - passed.
- `git merge-tree --write-tree HEAD origin/main` - passed with no
conflicts.
- README structure assertions - passed: no table of contents, no
benchmark-label links, and four matching Back to top boundaries in each
language.
- Confirmed both READMEs use the same 33378-byte GitHub User Content
hero banner; benchmark evidence is native Markdown.
- Confirmed the 1179517-byte onboarding MP4 round-trips from GitHub User
Content with SHA-256
124024e6d64c23b3e314aa6136d9e0d922f57ded97a830a5c97cd1323cb2c57f and
renders with controls below Benchmarks in both languages.
- `uv run pytest --tb=short -q` - 6130 passed, 33 skipped, and one local
Python 3.14 ANSI color assertion failed; the GitHub Python 3.12 unit job
passed.

## Risk

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

This is a low-risk documentation-only change. Rollback requires
reverting the README commits; externally hosted user-content assets can
remain unreferenced without affecting repository size.

## Related Issues

N/A
2026-08-12 21:02:13 +08:00
LivXue
14e270f8e6 feat(*): split agent home from the working directory and record sub-agent calls
## Summary

`workspace` meant two things at once: the agent's global home (user memory,
skills, transcripts, memory store, Skill Hub cache) and the directory a turn
reads and writes files in. This splits them, and gives each half a layout that
matches how it is used.

This MR was opened once before against a per-session design and withdrawn for
requirement alignment. What lands here is the aligned design: the gateway's
unit of isolation is the **channel**, not the conversation, and per-conversation
storage is the session's own directory under `sessions/`.

**Working directory.** `raven tui` and `raven agent` work in the launch
directory, so the agent operates on the checkout you started it in; its
bookkeeping stays under that directory's `.raven/`. `raven gateway` gives each
channel one directory, set by `channels.<name>.workspace` next to that
channel's credentials (`gateway.web.workspace` for web) and defaulting to
`~/.raven/tmp/<channel>`. The default is derived from agent home rather than
`$HOME`, so `--home` keeps an isolated instance isolated.

**Session storage.** A conversation's transcript and a new metadata directory
now sit together under one group: the slugged launch directory on tui/agent,
the channel name on the gateway. The slug reproduces the scheme Claude Code
uses for `~/.claude/projects/`, transliterated from the shipped implementation
rather than inferred: each non-alphanumeric character becomes one `-` (so `_`
folds too), and past 200 characters the slug is truncated with a hash of the
whole path. Terminal conversations stop piling up under `cli/` and `tui/` with
nothing tying them to the project they were about. The slug is a bucket, not an
identity -- the launch directory is recorded in `Session.metadata`.

**Sub-agent history.** Both ways of delegating now record what they were asked
and what they answered, under `sessions/<group>/<id>/subagents/`. `spawn` wrote
no file at all before - its reply went into the conversation and nowhere else,
so a sub-agent that failed left only a log line. Failed, aborted and cancelled
calls are recorded too, and the prompt is written before dispatch, so a call
that never returns still shows what was asked. DAG run directories move here
from `<workdir>/.ravenx_dag/`.

The mechanism is a per-turn `ContextVar` bound by `AgentLoop.run_turn`.
Components running inside the turn read it; anything that outlives a turn
(sub-agents, DAG runs) captures the directory as data at spawn, marked by an
explicit `follow_binding=False`. That distinction is load-bearing: an
`asyncio.Task` inherits the binding at creation, so a re-read appears to work
and then silently follows the wrong directory once the two diverge.

### Layout

```
~/.raven/workspace/sessions/<group>/
|-- <session_id>.jsonl            transcript
`-- <session_id>/subagents/
    |-- spawn/<call_id>/          prompt.md, out.md or error.md, meta.json
    `-- mas_dag/<run_id>/         graph.json, manifest.json, <node>.*.md

~/.raven/tmp/<channel>/           gateway working directory (default)
<launch dir>/.raven/              tui/agent bookkeeping
```

### Breaking changes

- `--workspace/-w` no longer sets agent home; `--home` takes over that meaning.
  A script passing an absolute path to `-w` keeps running but silently shares
  the default agent home; one passing a relative path now exits with a
  parameter error, because a working directory must be absolute.
- Gateway sessions no longer run in the agent-home root.
- DAG run directories moved; existing `.ravenx_dag/` is neither read nor
  migrated.
- A working directory may not be agent home, anything inside its
  memory/skills/session subtrees, or any directory containing agent home.

### Defects fixed from the previous round of review

- The DAG read side resolved run directories against agent home while writes
  followed the turn binding, so a per-session run was unreadable the moment it
  was written: the graph never restored and no node detail ever opened. The
  read path is now derived from agent home plus the session key, which reads
  correctly between turns when nothing is bound. `raven.subagents.dag.node`
  gained the `session_key` it never carried.
- `validate_override` accepted an ancestor of agent home. `~/.raven` is the
  instance data directory, and the per-turn checkpoint runs `add -A` over the
  working directory, so pointing a session there would have committed
  `config.json` and `oauth/` into a shadow git repo.
- Dot-only session-key segments escaped their own root: `safe_filename` leaves
  `..` intact, which is fine for `<chat_id>.jsonl` but not for a bare directory
  name.

### Defects fixed from the second round of review

- `channels.<name>.workspace` reached the resolver unvalidated, while every
  other way of naming a working directory goes through `validate_override`.
  Agent home itself, a protected subtree and a relative path were all accepted,
  and the per-turn `add -A` would then have run over `user_memory/` and
  `sessions/` -- the shape the ancestor check exists to prevent, reachable
  through a different door. The field is settable from the web UI's channels
  form, and the mount check only refuses an out-of-mount directory when the
  executor is sandboxed, which the default backend is not.
- The default channel root is a sibling of agent home, which resolves to the
  system `/tmp` when the home sits directly under the filesystem root:
  `--home /workspace`, a common container mount, put every channel in a shared,
  world-writable, reboot-cleared directory.
- `key_from_path` derived the channel from the parent directory, which under
  project grouping is a slugged path no session key can match. The sentinel
  producers call it on every file they scan before reading it, so for them that
  fallback is the primary path.
- The slug was inferred from three directory names and got repeated separators
  and trailing slashes wrong. It is now transliterated from the reference
  implementation: replacement is per character rather than per run, and past
  200 characters the slug is truncated with a base36 hash of the whole path.
  The tests carry the reference algorithm rather than importing ours, so drift
  fails them.
- The slug is deliberately still not collision-free (`/srv/a_b` and `/srv/a/b`
  produce one segment, in the reference too), so the launch directory is now
  recorded in `Session.metadata["project_dir"]` -- the reference solves this
  the same way, by writing `cwd` on every transcript entry. Nothing is scoped
  by group today, so a collision is currently invisible; the metadata is
  written now so it is already there if `--continue` is ever scoped to the
  project.
- The sub-agent history directory is append-only with no expiry, no cap and no
  reclaim path but deleting the session. DAG runs dominate its volume, because
  a node's rendered prompt inlines its dependencies' full output. Now stated in
  `CHANGELOG.md`, `CONTEXT.md` and the design doc; bounding it is deliberately
  a separate change.

## Type

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

## Verification

- `uv run pytest -q -p no:randomly` on this branch rebased onto `2178707` ->
  5 failed, 6034 passed. The same command on `origin/main` at `2178707` in a
  separate worktree -> 5 failed, 5898 passed. The two failure sets are
  identical test ids: 0 introduced, 0 fixed. Those 5 are environmental or
  pre-existing (three `test_channels_qr_*` assert a PNG prefix with no skip
  guard for the optional `qrcode` extra, plus a theme test and an onboard
  test). GitLab's server-side rebase produced tree `eccdc91c`, byte-identical
  to the tree these numbers were measured on.
- `ruff check` over `raven tests scripts` -> clean. `ruff format --check` ->
  one file, `tests/test_web_rpc_config.py`, which reproduces on `origin/main`
  at `2178707`; it arrived with the everos memory config page and is left for
  its author rather than fixed in an unrelated MR.
- `pnpm tsc -b --noEmit --force` in `ui-webui/frontend` -> exit 0.
- `pnpm eslint` on the changed frontend files -> 0 errors, 1 warning
  (`react-hooks/exhaustive-deps` in `ChatViewport.tsx`), pre-existing on
  `origin/main`.
- `npx vitest run` in `ui-tui` -> 1005 passed; 2 failures (`modelPicker`,
  `theme`) reproduce on the baseline and pass in isolation, so they are
  suite-order sensitive, not from this branch.
- Each of the three fixed defects was mutation-checked: reverting the fix makes
  exactly the new assertions fail and nothing else.
- Manual: the web app was served from an earlier revision of this branch and
  driven through real turns; that run is what found the checkpoint defect
  already fixed in this branch.

One commit here is a rebase seam rather than this branch's own work:
`test(subagents): pass run_root in the dag test that arrived with the preset
config`. The preset-config change landed on `main` with a test calling
`run_dag` under the old signature, which this branch splits into `workdir` and
`run_root`. Neither side is wrong alone and the rebase is textually clean, so
the break only appears with both on one tree.

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

## Risk

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

The override validator rejects relative paths, agent home, its
memory/skills/transcript subtrees, and any ancestor of agent home. Under a
sandbox, a directory outside the mount root is refused before it is created
rather than silently escaping. No filename in the history trees is derived from
a sub-agent's output, only from ids raven mints.

Backward compatibility: nothing on disk is migrated. A session whose transcript
predates project grouping keeps its file - `_get_session_path` falls back to an
existing `sessions/*/<id>.jsonl`, so resuming by id still continues the real
transcript instead of opening an empty one beside it. `list_sessions(channel=)`
and `find_most_recent_chat_id` now filter on the session key rather than the
parent directory, which no longer names the channel.

Known cost: each distinct working directory grows its own shadow-git repository
once a checkpoint runs there, and the cache is never evicted. Bounded by the
channel count, not the chat count. Noted in `CONTEXT.md` and the design doc.

Rollback is a revert of this squash commit; there is no configuration switch to
disable the split.

## Related Issues

N/A

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-12 02:51:42 +00:00