25 Commits

Author SHA1 Message Date
Tong Li
0a1a711123
feat(*): add bounded Python diagnostics after code edits (#967)
## Summary

Raven-Code reports Python syntax errors after file edits but misses
unresolved names and equivalent feedback after shell edits. Add advisory
Pyflakes F821/F822/F823 checks to the existing tool result; optional
F401 notices remain off by default. No additional model call or code
execution is involved.

```text
write_file / edit_file
  -> inspect final source, compare with a baseline that can be read and analyzed
  -> retain syntax warnings; suppress existing name findings
exec
  -> require checkpoint visibility for the working directory
  -> read the changed files from the host's write record for the command
  -> ask visibility in batches of 256, select at most 8, check up to 4 concurrently
  -> append ordered diagnostics, preserving exit status and file metadata
```

Existing syntax failures remain visible after unrelated edits and
identical rewrites. A baseline that cannot be read, parsed or analyzed
is marked unknown; overwriting non-UTF-8 source still checks the known
replacement. Source nested too deeply for the parser or checker, and a
changed file that cannot be read, report diagnostics unavailable for
that file rather than passing as clean. Every check reads a file as the
bytes Python runs: text a write or edit stores is checked as its UTF-8
bytes, the content it replaced included, and a file from disk as its
bytes, each decoded as Python decodes source, by its coding declaration
or as UTF-8. Bytes that do not decode are reported as a syntax error at
the line where decoding stops, so a declaration the written text cannot
satisfy is reported however the file was changed. Noqa comments are read
as Ruff reads them, including after other comment directives and never
inside string literals: a file-level `ruff: noqa` / `flake8: noqa`
counts only on a line of its own, and a marker counts only when codes
follow its colon or, with no colon, whitespace, another comment or the
end of the comment follows it. Unlike Ruff, which takes the first
directive in a comment, every directive in it counts. The seeded tool
guide gives the syntax note's own advice. With no checkpoint or no
visibility verdict, exec diagnostics do not inspect changed file
contents; direct file checks remain available.

Pyflakes is imported when the tool face loads, not by whichever check
first needs it: imported lazily, its cold import fell inside that
check's one-second wait, and on a slow Windows runner the one test that
paid it reported diagnostics unavailable for a plain syntax error.
Private workers bound reads and checks to four active jobs per process.
Saturated capacity rejects new work without queuing, and
timeout/cancellation retains each slot until the actual work finishes.
Name checks are capped at 256 KiB of source and the syntax check at 2
MiB, and a check skipped for size says so in one line. Findings are
capped at eight per file, and exec diagnostic text at 6,000 characters
plus omission notices.

Runtime changes stay inside the Raven-Code code-flow plugin, except for
one fix to `CheckpointService.trackable`, the visibility verdict that
exec diagnostics and the host's exec write record both rely on. On
macOS, git precomposes a file name it reads off the disk before matching
an ignore rule, but takes the paths `trackable` sends to `git
check-ignore --stdin` as written. A file stored with a decomposed (NFD)
name under a `.gitignore` rule written precomposed (NFC) is therefore
left out of the checkpoint, yet main vouches for it, so the write
record's diff carries its text, and exec diagnostics would quote its
source lines to the model. Nor is git's precomposition NFC: it composes
only neighbouring characters, by Unicode 3.2's table, and reorders
nothing, so a name whose combining marks are out of canonical order
comes out as neither the name as given nor its NFC. `trackable` now asks
about each name as given, as NFC and in git's macOS spelling, and
withholds it when any spelling is ignored. Other shared
file/shell/snapshot implementations are unchanged.

Raven-Code has no separate dependency manifest, so Pyflakes uses the
existing root dependencies. It is the only added package; uv normalized
existing lockfile markers without changing other package versions.

## Type

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

## Verification

- **Before:** on main, Raven-Code's file tools report Python syntax
errors only, and its exec reports nothing about the Python files a
command changed. On macOS, main's `CheckpointService.trackable` vouches
for a file stored as `secret_cafe` + U+0301 + `.py` under the rule
`secret_caf` + U+00E9 + `.py`: the user's own git ignores it and the
checkpoint's staged tree leaves it out, yet its text reaches the exec
write record's stored diff.
- **After:** on macOS 26.6.2 / arm64 with Apple Git 2.54.0, the command
below passes 364 tests on Python 3.12.13 and on 3.14.6. The full default
suite on 3.12.13 has 32283 passed, 169 skipped, 20 failed and 3 errors
over 22 test ids: 21 of them also fail on the exact base in the same
environment, and the other, a remote process-tree cancel test that
missed its deadline under the suite's load, passes when run alone. Tests
cover actual worker overlap, retained capacity after
timeout/cancellation, host-tool isolation, hidden-file quotas,
visibility batching through the host's write-record wiring, baseline
handling, parser-limit failures, the size bounds and their skip notes,
undecodable bytes placed where decoding stops, coding declarations in
written and edited text, the baseline read staying on a worker, the
checker loaded with its module, the file each unavailable note names,
comment directives and their marker boundary, the tool guide's agreement
with the syntax note, portable commands in paths with spaces/non-ASCII
characters, and the checkpoint's verdict on decomposed names and on
names git spells as neither given nor NFC, held against its own staged
tree. Removing any of the three spellings from the query fails the cases
that pin it, as does removing the marker boundary, the parser-limit
report, the unknown-baseline handling, the syntax check past the
name-check bound and the decoding report, checking written text as its
stored bytes, the worker around the baseline read, loading the checker
with its module, or the file name in an unavailable note; restoring the
guide's earlier advice fails its agreement test. git's macOS spelling is
what libiconv's UTF-8-MAC conversion returns, which git precomposes
with: composing neighbours by Unicode 3.2's table reproduced it for all
281,928 names built from every decomposable character's decomposition
(reordered, partly composed, or with a mark added), and across 784,220
further mixed names and pairs no name was spelled outside the three
asked; the same held under Python 3.13 and 3.14. The decomposed-name
check asserts the macOS outcome only where git precomposes names, so it
also passes with `core.precomposeunicode = false` set through
`GIT_CONFIG_GLOBAL`. Across 102 noqa comment variants the reported lines
match Ruff 0.15.12, except the three that hold several directives in one
comment. Through the real `AgentLoop`, code-flow tool face,
`CodeExecutor` and checkpoint, with the working directory under `/tmp`,
under `$TMPDIR` and in a path with spaces and CJK characters, exec
diagnostics report created, modified and decomposed-name files, follow
`working_dir`, report an undecodable file at the line where decoding
stops, a syntax error past 256 KiB and a skip past 2 MiB, and withhold
`.gitignore`d files, including decomposed names and names git spells as
neither given nor NFC; across repeated runs on both interpreters, a file
near the 256 KiB cap is checked in 52-135 ms (117-128 ms against a
baseline), the syntax of a file near 2 MiB in 318-371 ms, and 600
ignored files plus one visible file take 73-90 ms with the event loop
held at most 20 ms. At this head CI passes the unit suite on
Linux/Python 3.12 (32619 tests over four shards), and its two Windows
steps pass the diagnostic files on native Windows/Python 3.13: 122
file/worker tests, and 27 exec diagnostic tests with 17 pre-existing
executor tests deselected; the symlink fixture skips only where the host
cannot create links.

```sh
env -u SERPER_API_KEY -u RAVEN_MIRRORED_SERPER_API_KEY uv run --no-sync pytest tests/test_agents_code_diagnostic_workers.py tests/test_agents_code_tools_plugin.py tests/test_agents_code_flow_exec.py tests/test_agents_code_flow_plugin.py tests/test_agents_code_flow_read_state.py tests/test_agents_code_launcher.py tests/test_workdir_snapshot.py tests/test_shell_command_writes.py tests/test_runtime_checkpoint.py tests/test_trajectory_upload.py::test_blocked_upload_hits_the_deadline -o addopts= -q --tb=short --maxfail=3
uv run --no-sync ruff check raven/agent/loop/checkpoint.py agents/raven-code/plugins/code-flow/code_flow/tools agents/raven-code/plugins/code-flow/code_flow/config.py tests/test_runtime_checkpoint.py tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py tests/test_agents_code_diagnostic_workers.py
uv run --no-sync ty check raven/agent/loop/checkpoint.py agents/raven-code/plugins/code-flow/code_flow/tools agents/raven-code/plugins/code-flow/code_flow/config.py
uv run --no-sync lint-imports
uv run --no-sync ruff format --check raven/agent/loop/checkpoint.py agents/raven-code/plugins/code-flow/code_flow/tools agents/raven-code/plugins/code-flow/code_flow/config.py tests/test_runtime_checkpoint.py tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py
```

Native Windows CI commands:

```sh
uv run --frozen --python 3.13 --no-sync pytest tests/test_agents_code_diagnostic_workers.py tests/test_agents_code_tools_plugin.py -q -n 0 --tb=short
uv run --frozen --python 3.13 --no-sync pytest tests/test_agents_code_flow_exec.py -k test_exec_ -q -n 0 --tb=short
```

Ruff, format and type checks passed; all 10 import contracts kept; the
commit-message, large-file and source-language checks pass over the
branch. The launcher tests unset inherited search API keys to keep the
expected tool list deterministic.

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

## Risk

Scope: Raven-Code's enabled code-flow tool face; installing Pyflakes
does not activate checks in other agents. The change is reversible and
never fixes/removes code or rolls back edits. Static diagnostics can
need judgment for dynamic names, target Python versions, and project
lint configuration; only explicit noqa directives are honored. Passing
diagnostics do not replace tests.

The `trackable` fix reaches every exec write record, not only
Raven-Code: a file whose name, as given, as NFC or in git's macOS
spelling, matches an ignore rule keeps its counts and loses its diff and
removal body. Where git matches another of those spellings, as off macOS
for a decomposed name under a precomposed rule, the checkpoint stores
the file but it is still withheld; its counts remain.

Exec diagnostics now require an active checkpoint. Noninteractive runs
using the default interactive checkpoint policy must explicitly enable
checkpoints to receive this feedback. Visibility is checked in batches
of up to 256 files and stops once eight visible files are found; each
batch holds the event loop while the host resolves its paths, about 130
ms for a full batch on native Windows. Each file-check wait is one
second, and post-command diagnostics have a three-second wait budget;
past it, or when they fail as a whole, they are dropped and the
command's result is kept. These are caller budgets, not hard I/O
deadlines: running OS reads and inherited synchronous host callbacks
cannot be forcibly interrupted. Private worker capacity remains bounded.
Between 256 KiB and 2 MiB only syntax is checked: near 2 MiB that took
0.3-0.4 s and about 190 MiB here, up to four checks run at once, and on
slower hardware such a check can outlast the one-second wait and report
diagnostics unavailable. Python's GIL means concurrency does not promise
a CPU speedup.

Windows CI exercises the diagnostics layer with the real native
DirectExecutor. The existing CodeExecutor environment probe uses POSIX
quoting and already fails on Windows at the base; this PR neither
changes that probe nor claims end-to-end compatibility for it. Symlink
setup is skipped only if the host cannot create the fixture.

Disable `pythonLint` for syntax-only feedback, `execPythonDiagnostics`
for no post-command checks, or `pythonSyntaxNote` for no diagnostics,
under `plugins.config["code-flow"].tools`. The PR can also be reverted
as a unit.

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

## Related Issues

N/A

---------

Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-10-18 20:21:04 +08:00
KT
a7f0502be0
ci(*): make the idle ceiling a gate and take the last waits out (#428)
## Summary

Follow-up to #413, from a measured look at what was left: a CI shard now
spends 72 s on fixed cost (22 s environment, 48 s collection and worker
start) against 82 s of tests, the four shards are within 15 s of each
other, and 70 unmarked tests were still over the 2 s wall-clock ceiling
on CI against 42 on a laptop because CPU-bound work runs three to four
times slower there. This PR makes the ceiling a gate that is portable
across machines, takes the remaining waits out, precompiles bytecode so
the workers stop doing it four times, and fixes two product waits the
same investigation surfaced.

- `test(*)`: the ceiling judges idle time instead of wall clock, where
idle is the wall clock minus every CPU second spent on the test's
behalf, the reaped children's included (`os.times`). A test waiting on a
production sleep or a process that answers nothing waits the same
seconds on every machine; a test that computes for 2 s here and 7 s on
CI, or drives a browser or eight spawned workers, is not the problem.
The numbers ride on the teardown report so the xdist controller can
judge them; options are `--idle-ceiling` / `--idle-ceiling-strict`. The
fixture that shortens production ladders takes in the ACP cancel settle
(5 s) and the gateway delivery grace (2 s); the CLI agent tests stub the
one-shot command's unconditional 2 s hand-off grace; the rpc subagent
tests no longer spawn a login shell or probe a real endpoint over the
network; three literal timeouts shrink where the stub never answers
anyway. What is left over the ceiling carries a marker: seven real
LibreOffice renders and two tests that wait on a process answering
nothing carry `slow`, two whose assertion is the wait itself carry
`production_timing`.
- `ci(*)`: every shard runs with `--idle-ceiling-strict` (on the make
line, not in `addopts`: the Windows job runs `--noconftest`). Bytecode
precompilation was tried and dropped, the numbers are below; the
workflow is otherwise unchanged from #413.
- `test(agent)`: a heartbeat test asked for five beats of the fifteen
its intervals should produce in a 0.6 s window, and a loaded runner
delivered three. It reads the two gaps instead, which the load cannot
invert: the wait before the first beat is one interval, the wait after
it is the other. Older than the gate that surfaced it; nothing here
touches the registry.
- `perf(ppt-engine)`: `MeasuredWidth.width` remembers measured widths
(bounded, oldest key out); a 15-slide template's QA gates made 1848
freetype calls over 162 distinct keys. Importing `text_metrics` first
raised on a circular import through `template.capacity`; capacity now
imports the module and resolves the name at call time.
- `perf(*)`: `raven gateway` and `raven web` start the litellm import on
a daemon thread at boot, so saving a key from the settings page no
longer waits three to five seconds on it.
- `fix(providers)`: one thread at a time initialises litellm. It raises
three logger levels for the duration of the import and puts the captured
values back after, which holds only while one thread is doing it; a
second caller arriving inside that window captures WARNING as the level
to restore, and litellm's DEBUG and INFO stop reaching the file sink
until a restart. The window was narrow while every import sat on a
startup path and is ordinary now that a server warms it in the
background, so the two callers share a module lock. The strict-mode
warm-up also runs before the fixtures that redirect the home, and
publishing the OAuth token directories created them, so it warms under a
temporary home.

## Type

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

## Verification

Whole suite, `uv run --frozen --all-extras pytest -q` (macOS, 4
workers), before and after the waits came out and with the ceiling
strict:

| run | result | idle list |
|---|---|---|
| main after #413 | 22052 passed, 43 skipped in 219.41 s | 39 over 2 s
wall clock |
| this branch, `--idle-ceiling` warning | 22057 passed, 43 skipped in
210.20 s | 14 over 2 s idle, all real render or subprocess, now marked |
| this branch, `--idle-ceiling-strict` | 22058 passed, 43 skipped in
204.89 s, exit 0 | none |

The ceiling is three seconds, placed from the suite's own distribution
rather than guessed. Unmarked tests over one second of idle, measured
across the whole suite:

| idle | tests | what they are |
|---|---|---|
| 1.00-1.19 s | 19 | a test that sets a one second timeout and lets it
expire |
| 1.2-1.3 s | 3 | a subprocess handshake |
| 1.5-1.6 s | 3 | an ACP turn interrupted after 0.8 s, and two like it |
| above 1.6 s | 0 | the renders above this line all carry a marker |

A runner stretches that 1.6 s to about 2.2 s, which is how a two second
line failed two shards over tests waiting exactly as long as they meant
to. Three seconds sits in the gap the population leaves, and stays under
every ladder this guards against: the shortest constant the audit found
was a three second grace, the rest run 5, 15, 30 and 60 seconds.

What the metric separates, measured on this suite: a test that sleeps 5
s reports `4.96s idle of 5.02s`; a test that drives a headless browser
for 13 s reports under 0.8 s; six `raven doctor` subprocesses report 1.2
s where wall clock said 4.2 s; eight spawned processes contending for a
lock report under 0.8 s where wall clock said 3.6 s.

Files touched by the product changes and the new markers (`uv run
--frozen --all-extras pytest -q tests/test_litellm_setup.py
tests/test_cli_gateway_commands.py tests/test_cli_serve_commands.py
tests/test_ppt_engine_assets_fonts.py
tests/test_ppt_engine_template_capacity.py
tests/test_cli_doctor_commands.py tests/test_ppt_engine_end_to_end.py
tests/test_ppt_engine_render_service.py tests/test_rpc_model.py`): `434
passed, 2 skipped in 33.39s`, none over 1 s idle. `python -c "import
raven_ppt.services.assets.text_metrics"` in a fresh interpreter:
ImportError before, imports after.

Test-side speedups, measured per test: the ten CLI agent tests 2.0-4.4 s
to 0.05-0.36 s; the three rpc subagent tests 1.4-2.6 s to 0.01-0.02 s;
the rpc save-key test 2.2-2.8 s to 0.03 s; the two ACP probe tests 2.1 s
to 0.2 s.

Bytecode precompilation, seconds from the start of the pytest step to
the first test, per shard, over three runs of this workflow:

| what was compiled | shard 1 | shard 2 | shard 3 | shard 4 | mean |
install step |
|---|---|---|---|---|---|---|
| nothing (#413) | 52.7 | 46.5 | 45.9 | 46.0 | 47.8 | 3-4 s |
| site-packages and checkout | 39.8 | 39.3 | 35.6 | 45.5 | 40.1 | 12-17
s |
| checkout only | 55.5 | 50.1 | 44.4 | 53.8 | 51.0 | 3-4 s |

Compiling site-packages is the half that moved the number and it cost
more in the install step than it returned. Compiling the checkout alone
is inside the noise of doing nothing: the four workers share one `.pyc`
cache, so the first to import a module writes it for the rest, and most
of what a laptop measures as cold compilation is pytest rewriting test
files through a cache `compileall` cannot fill. Both are gone; the
comment in the workflow records it.

The reworked heartbeat assertion was checked against the bug it guards
by making the registry keep its first interval for every beat: one beat
arrives in the window and the assertion fails on it.

The diff gate is reproduced locally against `origin/main` after a full
`make coverage`: `Diff coverage: 100.00% (12/12 executable changed
lines)`. The two warm-up calls in the serving boot coroutines carry a
no-cover pragma naming the test that pins them, because those coroutines
bind a port and serve until they are killed.

The lock is checked against the race it closes: with it taken away, a
test that holds the first caller inside the import and starts a second
fails on `[30, 30, 30] == [20, 20, 20]`. A strict session under a clean
HOME now leaves no `.raven` behind.

`make lint-python` clean.

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

## Risk

- The ceiling is now a gate on CI. A new test that waits more than 2 s
without `slow` or `production_timing` turns its shard red; the summary
names the test and the marker to use. A local run stays warning-only.
- A subprocess that does real work is charged to the test that reaped
it, so only a real wait trips the gate. A strict session imports litellm
up front, because its 1.7 s of file opens would otherwise land on
whichever test in the shard imports it first.
- The litellm warm-up runs on a daemon thread at server boot only; unit
tests never reach either boot path (their source is pinned instead), and
a failed import is logged, not raised.
- The width memo returns the same floats; the cap evicts the oldest key.
The capacity import change resolves the same name one step later.
- Rollback: revert the PR; every change is additive or a marker.

- [x] Security impact considered (no security surface touched)
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-16 14:51:50 +08:00
0xKT
8716ec525c feat(docker): run raven in a docker container and make a first run configurable from the page
## Summary

Two things arrive together because the second is what made the first usable.

**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.

**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.

Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.

## Type

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

## Verification

Commands run on the branch head, with their results:

- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean

Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.

The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.

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

## Risk

Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:

- nginx rewrites the `Origin` header, because the engine accepts only an Origin
  naming its own loopback port and no browser reaching a published port can send
  one. This drops a defence-in-depth layer. The session cookie is
  SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
  ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
  every page load, so anyone who can reach the published port is signed in. It
  is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
  deployment reachable from elsewhere. These are two settings that must agree,
  and nothing warns when they do not.

Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).

Rollback is by revert; nothing here migrates state or changes an on-disk format.

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

## Related Issues

N/A
2026-09-11 03:27:52 +00:00
KevinHuSh
4a4a3fe15b feat(docker): run raven in a docker container and make a first run configurable from the page
## Summary

Two things arrive together because the second is what made the first usable.

**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.

**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.

Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.

## Type

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

## Verification

Commands run on the branch head, with their results:

- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean

Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.

The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.

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

## Risk

Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:

- nginx rewrites the `Origin` header, because the engine accepts only an Origin
  naming its own loopback port and no browser reaching a published port can send
  one. This drops a defence-in-depth layer. The session cookie is
  SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
  ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
  every page load, so anyone who can reach the published port is signed in. It
  is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
  deployment reachable from elsewhere. These are two settings that must agree,
  and nothing warns when they do not.

Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).

Rollback is by revert; nothing here migrates state or changes an on-disk format.

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

## Related Issues

N/A
2026-09-11 03:27:52 +00:00
0xKT
9c965e2470 fix(rpc): anchor the file viewer's state-dir fence on agent home, not the session workdir
## Summary

The web file viewer refused every file a sub-agent's DAG node writes, and said the
wrong thing about why. Clicking such a report answered `403`, which the page renders
as "Raven is confined to the working directory" -- while `restrict_to_workspace` was
off and the real refusal came from the state-directory fence.

`/file` resolves a request against the session's working directory when the page names
a session. It also handed that directory to `in_state_dir` in the role that function
reserves for agent home. The fence derives its two exemptions from that argument -- the
workspace itself, and the per-channel working-directory root beside it -- so with the
session's directory in home's place the exemptions covered `~/.raven/tmp/<channel>` and
a sibling that does not exist. Everything the DAG runner writes under
`~/.raven/workspace/sessions/` then read as raven's own state and was refused, which is
the same defect the workspace exemption exists to prevent, one directory over. A
node's report was drawn on the shelf as a delivery and would not open.

`resolve_readable` now keeps the two roles apart. The caller's workspace still anchors
relative paths and the `restrict_to_workspace` fence; the state-directory fence is
anchored on `cfg.workspace_path`, and the session's directory is passed alongside it
through a new variadic parameter that adds to what the fence exempts rather than
replacing what it derives. A session pinned to a directory under the state root
therefore keeps its files, and every exemption -- derived or added -- is held to the
same direction check, so the state root itself and its ancestors still earn none.
`serve.json` and `config.json` stay refused on every path tested.

`_resolve_inside`, which backs `fs.list` and `fs.read`, carried the same substitution.
Its containment check hid the symptom, so nothing had surfaced there yet; it is
anchored the same way now, because the fence's contract is that the viewer, the `fs.*`
panel and `fs.reveal` answer alike for a given file.

## Type

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

## Verification

Commands and results, all at the branch head after rebasing onto `main`:

```console
$ uv run pytest tests/test_rpc_transport.py tests/test_rpc_console.py tests/test_rpc_knowledge.py -q
147 passed in 2.84s

$ uv run pytest tests/test_rpc_files.py tests/test_utils_office.py -q
33 passed in 2.70s

$ make lint-python          # ruff check + ruff format --check
exit 0

$ make lint-imports
Contracts: 9 kept, 0 broken.

$ make lint-ui
exit 0

$ make check-source-language
exit 0

$ uv run python scripts/check_commit_messages.py origin/main..HEAD
exit 0
```

Two regression tests were added next to the existing state-directory fence cases:

- the session-workdir call reads a node's report under the sessions tree and still
  refuses `serve.json`;
- a session pinned to a directory under the state root keeps serving its own files,
  while one pinned at the state root itself does not.

The first was proved load-bearing by reverting the fix and re-running it, which failed
with `PermissionError: ... is inside raven's state directory` on the report path. The
second is unchanged by the fix and is there to pin the behaviour the change must not
lose.

Behaviour was also checked against the running gateway's own files, on the real paths:
with the session's working directory supplied, a node's report resolves and both
`serve.json` and `config.json` raise `PermissionError`.

Known gaps, disclosed rather than worked around:

- `make lint-tui` and `make lint-bridge` do not pass in this environment. The first
  reports `src/i18n/messages.generated.ts` stale, the second `tsc: not found`. Both fail
  identically on a clean `main` worktree, and this change touches neither `ui-tui/` nor
  `bridge/`.
- No browser check. The refusal and the fix were exercised through the resolver and the
  gateway's own file paths, not through a rebuilt page bundle.

## Risk

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

The fence's decisions are unchanged except for the one it was getting wrong. Nothing
that was refused before this change becomes readable, apart from the session-directory
subtree the fence was never meant to refuse: the added exemption is bounded by the same
direction check as the derived ones, so no ancestor of raven's state root and not the
root itself can ride it. The credential files were re-checked as refused on every path
the tests and the live probe cover.

`in_state_dir` gains a variadic parameter with no required argument, so existing calls
keep compiling and keep their previous meaning. Both in-tree callers were updated in
this change; there are no others.

Rollback is reverting the commit. The change is three files of resolver logic plus its
tests, with no migration, no stored state and no wire-format change.

## Related Issues

N/A
2026-09-11 03:26:58 +00:00
userName20260323
236f66af24 fix(rpc): anchor the file viewer's state-dir fence on agent home, not the session workdir
## Summary

The web file viewer refused every file a sub-agent's DAG node writes, and said the
wrong thing about why. Clicking such a report answered `403`, which the page renders
as "Raven is confined to the working directory" -- while `restrict_to_workspace` was
off and the real refusal came from the state-directory fence.

`/file` resolves a request against the session's working directory when the page names
a session. It also handed that directory to `in_state_dir` in the role that function
reserves for agent home. The fence derives its two exemptions from that argument -- the
workspace itself, and the per-channel working-directory root beside it -- so with the
session's directory in home's place the exemptions covered `~/.raven/tmp/<channel>` and
a sibling that does not exist. Everything the DAG runner writes under
`~/.raven/workspace/sessions/` then read as raven's own state and was refused, which is
the same defect the workspace exemption exists to prevent, one directory over. A
node's report was drawn on the shelf as a delivery and would not open.

`resolve_readable` now keeps the two roles apart. The caller's workspace still anchors
relative paths and the `restrict_to_workspace` fence; the state-directory fence is
anchored on `cfg.workspace_path`, and the session's directory is passed alongside it
through a new variadic parameter that adds to what the fence exempts rather than
replacing what it derives. A session pinned to a directory under the state root
therefore keeps its files, and every exemption -- derived or added -- is held to the
same direction check, so the state root itself and its ancestors still earn none.
`serve.json` and `config.json` stay refused on every path tested.

`_resolve_inside`, which backs `fs.list` and `fs.read`, carried the same substitution.
Its containment check hid the symptom, so nothing had surfaced there yet; it is
anchored the same way now, because the fence's contract is that the viewer, the `fs.*`
panel and `fs.reveal` answer alike for a given file.

## Type

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

## Verification

Commands and results, all at the branch head after rebasing onto `main`:

```console
$ uv run pytest tests/test_rpc_transport.py tests/test_rpc_console.py tests/test_rpc_knowledge.py -q
147 passed in 2.84s

$ uv run pytest tests/test_rpc_files.py tests/test_utils_office.py -q
33 passed in 2.70s

$ make lint-python          # ruff check + ruff format --check
exit 0

$ make lint-imports
Contracts: 9 kept, 0 broken.

$ make lint-ui
exit 0

$ make check-source-language
exit 0

$ uv run python scripts/check_commit_messages.py origin/main..HEAD
exit 0
```

Two regression tests were added next to the existing state-directory fence cases:

- the session-workdir call reads a node's report under the sessions tree and still
  refuses `serve.json`;
- a session pinned to a directory under the state root keeps serving its own files,
  while one pinned at the state root itself does not.

The first was proved load-bearing by reverting the fix and re-running it, which failed
with `PermissionError: ... is inside raven's state directory` on the report path. The
second is unchanged by the fix and is there to pin the behaviour the change must not
lose.

Behaviour was also checked against the running gateway's own files, on the real paths:
with the session's working directory supplied, a node's report resolves and both
`serve.json` and `config.json` raise `PermissionError`.

Known gaps, disclosed rather than worked around:

- `make lint-tui` and `make lint-bridge` do not pass in this environment. The first
  reports `src/i18n/messages.generated.ts` stale, the second `tsc: not found`. Both fail
  identically on a clean `main` worktree, and this change touches neither `ui-tui/` nor
  `bridge/`.
- No browser check. The refusal and the fix were exercised through the resolver and the
  gateway's own file paths, not through a rebuilt page bundle.

## Risk

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

The fence's decisions are unchanged except for the one it was getting wrong. Nothing
that was refused before this change becomes readable, apart from the session-directory
subtree the fence was never meant to refuse: the added exemption is bounded by the same
direction check as the derived ones, so no ancestor of raven's state root and not the
root itself can ride it. The credential files were re-checked as refused on every path
the tests and the live probe cover.

`in_state_dir` gains a variadic parameter with no required argument, so existing calls
keep compiling and keep their previous meaning. Both in-tree callers were updated in
this change; there are no others.

Rollback is reverting the commit. The change is three files of resolver logic plus its
tests, with no migration, no stored state and no wire-format change.

## Related Issues

N/A
2026-09-11 03:26:57 +00:00
LivXue
f2d76abce8 fix(*): retire the trunk output-drop pin and the claims it held
## Summary

`tests/test_agents_code_flow_exec.py` carried a pin on trunk's `DirectExecutor`
dropping a timed-out command's output. That was one of the reasons the code flow
replaced the executor, and the pin's own docstring said what should happen to
it: "pinned so a trunk fix can retire it". The trunk fix landed, the pin
asserted the opposite of the truth, and `main` went red.

**`main` is no longer red.** While this sat in review, a separate change
replaced the pin with `test_trunks_executor_preserves_output_on_timeout`. That
resolved the breakage and is the version kept here; this branch was rebased onto
it rather than carrying a competing test. What remains is what that replacement
did not cover:

- **Why the fork exists on that axis.** The replacement asserts the new fact in
  one line and says nothing about what still separates the two executors. Trunk
  signals a kill through the stderr line and `exit_code` and nothing more, while
  `CodeExecResult` also flags `timed_out` and renders `TIMED_OUT_NOTE`, which
  tells the model its output is a fragment rather than a whole run. That
  difference is now asserted and explained where the pin used to sit.
- **Three prose claims that are still false on `main`.** Both module docstrings
  advertise "the fork's three fixes" and describe trunk waiting on
  `communicate()` and losing the buffered output, in the present tense; the exec
  factory's docstring lists partial output as a difference. Each is corrected to
  say what is true now and what is left.

The fork's drain now duplicates trunk's. That is noted in the docstring as the
fork owners' call, because nothing depends on which of the two performs it and
this change should not spend itself on that. No code is removed and no behaviour
changes.

## Type

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

## Verification

- `pytest tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py
  tests/test_sandbox_unit.py tests/test_agents_oncall_flow_hooks.py` -- 183 passed
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0

Mutation, to show the added assertions are load-bearing rather than decorative:

```
trunk discards partial stdout again   -> 1 failed   (the inherited assertions)
fork stops rendering TIMED_OUT_NOTE   -> 2 failed   (the added pair)
```

One mutation deliberately reported because it did **not** bite. An earlier
revision asserted only that trunk's rendering lacks `TIMED_OUT_NOTE`. Making
trunk emit a partial-output note in its own wording left the file green, because
the constant is matched verbatim -- and that form of assertion is equally
satisfied by a fork that stopped marking anything at all. Both sides are now
measured in one run, so the absence reads as a difference rather than as a
feature nobody has; removing the fork's append is what the second mutation
above does.

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

Left unchecked: no user-facing document describes either executor's timeout
behaviour. The three corrected texts are module and factory docstrings. The
model-facing half was checked separately and needed nothing -- the `timeout`
parameter description says a command that hits its limit "is killed and the
output it produced so far comes back marked partial", which is still true of
this tool.

## Disclosed

Four failures in `tests/test_ppt_engine_build_tool.py` appear in a wider
selection and are **not** from this change. They reproduce at the `main` tip in
a worktree holding none of it, and the cause is local layout rather than code:
`raven_ppt` resolves to the primary checkout's `plugins-dist/ppt-engine`, which
sits at an older revision than a fresh worktree's tests. Not investigated
further here.

How the red reached `main` is worth stating, since the cause was process rather
than code. The executor fix was pushed and then rebased onto a `main` that had
gained the pin in the meantime; the rebase surfaced the collision, and the merge
landed on the pre-rebase head before the rebase was pushed. Rebasing before the
push, as the contribution rules require, would have surfaced it while that
merge request was still open.

## Risk

No behaviour change: assertions added to an existing test, three docstrings
corrected, no production statement altered and no code removed. The duplicated
drain in the fork's executor is left exactly as it is.

Rollback is a revert of the two commits. `main` stays green either way, since
the breakage itself was resolved separately; what a revert costs is the stated
difference between the two executors and the accuracy of the three docstrings.

## Related Issues

N/A
2026-09-11 02:45:09 +00:00
0xKT
7a0b5dd311 feat(acp): a prompt is held open while the agent sleeps on an armed wake, and takes a steer
## Summary

An on-call agent submits a job, arms a wake and ends its turn saying so; the wake runs a later turn on the session on its own clock. Over ACP that turn's `end_turn` read as "finished" to the caller: a DAG judging its node spent every continuation on "still watching, wake at 13:13" while the job ran fine (ar-r4, 2026-09-08), and the main agent re-dispatched the work by hand. ACP has no stop reason for "waiting". Replaces the closed !573: **no DAG code changes**, no new node status. The node is `running` because a turn is genuinely in flight.

- **The signal.** The loop-hooks paper gains one key the ACP layer reads for itself: `acp_meta["raven.holdTurn"]` (`{"untilMs", "why"}`). oncall-flow files it at the send fire when the window's campaign is claimed, not concluded, and has one pending wake -- read the same way the owner's answer pulls that wake forward. No campaign, a wake that stood down, or a concluded campaign files nothing and the turn ends as before.
- **The hold** (`raven/acp/methods.py`). A turn that ended `end_turn` with the key filed is not answered. One `tool_call` stands for the wait (its title names the campaign and the next look), with a `tool_call_update` heartbeat every `HOLD_HEARTBEAT_S` (60 s) so a client that clocks liveness by frames sees the agent alive while its model sleeps. The turn slot is reopened with no id to correlate on, so whichever turn ends next on the session -- the wake's, a steer's -- settles it, and the handler decides again from that turn's stash. A wake that arms again keeps the hold; a turn ending with nothing pending answers `end_turn`; a cancel answers `cancelled` as before. The key itself is not passed to the client.
- **Steer.** `_raven/session/steer` is served and advertised under `agentCapabilities._meta` as `raven.steer` (the names raven's own client already uses). Accepted while a prompt is open on the session, held or running: the text is shown on the wire as the person's own line, then sent with `turn.send`'s new `busy: "inject"`. Answers `injected` / `no_turn`.
- **Wire.** `turn.send` gains the optional `busy` param (`const "inject"`): an ordinary send on an idle lane, `BusyPolicy.INJECT` into the running turn otherwise -- the merge a channel's mid-turn message already gets (`gateway_commands.py`). No slot is bound for an injected message; the running turn keeps the lane's. `openrpc.json` and both generated clients moved together.

What raven's client side already does, unchanged: the DAG stall watcher resets on any frame (the heartbeat keeps it quiet, and a stopped heartbeat raises the existing stall notice after ten minutes); a sub-agent process that dies fails the request and the node takes its ordinary path; the pool's `_responsive` treats a prompt in flight as busy.

## Review round 1 (2026-09-09, on !600, superseded by this MR)

- **`busy: inject` reads the scheduler's lane state too.** `is_turn_active` knows only the turns `turn.send` started; an armed wake is submitted to the scheduler directly (`make_on_session_wake`) and never binds that map, so a steer during a running wake queued a second turn and answered `injected`. `turn.send` now asks `Scheduler.has_inflight(lane)` as well, and merges (`BusyPolicy.INJECT`) when either record says the lane is running. Pinned: `test_busy_inject_merges_into_a_wake_the_real_scheduler_is_running` -- the reviewer's reproduction on the real `Scheduler`, a turn submitted the way `make_on_session_wake` submits one; with the lane check bypassed it reads `pending=1, inject_mailbox=0`, with it `(1, 0)` in the mailbox and the running turn drains the text.
- Branch renamed to snake_case and both commits carry the `Co-authored-by: Claude (<model-id>)` trailer, per AGENTS.md §2–3; that is why this MR replaces !600 rather than continuing it.

## Review round 2 (2026-09-10)

- **A wake re-armed during its own run survives the writeback.** `CronService._writeback_locked` reloaded the store after the run and, for a one-shot with `delete_after_run`, overwrote the id with the finished run's state and removed it -- but the turn the wake ran had just called `schedule_wake` under the same key, so the id now named the *next* look. It vanished, and the held prompt had nothing left to settle it. A stored job under the fired id whose `at` schedule the run never had is treated as the new wake it is: claim cleared, run recorded, schedule kept, not deleted. Pinned on the real service: `test_a_wake_re_armed_during_its_own_run_survives_the_writeback` (reads `[]` without the fix, the reviewer's state) and the unchanged one-shot deletion beside it. Cron, proactive, sentinel and on-call suites: 968 passed.

## Review round 3 (2026-09-10)

- **An undrained inject stays visible and cancellable.** `busy: inject` dropped the scheduler's handle; when the host turn ended past its last drain, the spine's fallback ran the text as a turn nothing owned -- `turn.cancel` a no-op, no `message.start`. The handle is now kept per lane under an id minted for the text; `turn.cancel` / `session.interrupt` reach it when the active slot is empty (mailbox, queued fallback, or running); and when the fallback turn starts, the RPC sink (`on_turn_start`, wired from bootstrap) binds the lane to it and opens it on the wire with the person's words. `turn.send` answers the inject's own id. Pinned through `build_rpc_spine` with the reviewer's shape (a loop that drains once, an inject after it): `test_an_undrained_inject_runs_as_a_turn_the_surface_can_see_and_cancel` and `test_a_pending_inject_can_be_cancelled_before_it_merges_or_falls_back`; both read the reviewer's state (`turn_ids` empty, cancel finding nothing) with the fix bypassed.
- **Line ceiling.** The contract comment is five lines; `raven/contracts` is 2,519 against 2,520, one line of headroom on the current `main` (2,514).
- Non-blocking items taken: `SchedulerDrainingError` on the inject path exits as `turn_failed`; the title is announced before the hold; the steer constants sit below the cancel constant's docstring; three edges pinned (a held prompt settled by a wake turn's uncorrelated ending through `send_frame`, the hold key never in the client's `_meta`, `raven.toolName` on the wait row).
- Focused suite (reviewer's list plus the touched files): 948 passed on Python 3.12.

## Review round 4 (2026-09-10)

- **Every pending inject is kept, per lane and per id.** One replaceable record per lane kept only the newest steer; two steers after the host's last drain fall back in turn, and the first started unowned while a cancel took out the second. The record is now `lane -> {inject id: (handle, text)}` in arrival order: each fallback promotes its own handle, and a cancel with no active turn reaches the oldest pending one -- the one the spine runs next. Pinned: `test_two_undrained_injects_each_get_their_own_turn_promoted_and_cancelled` (both promoted with their own ids and `message.start`, cancelled one after the other; runner saw all three turns). Focused suite: 949 passed.

## Type

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

## Verification

```
uv run pytest tests/test_acp_methods.py tests/test_acp_protocol.py tests/test_rpc_turn_send.py \
  tests/test_rpc_schema_match.py tests/test_acp_updates.py tests/test_acp_server.py -q      # 766 passed
uv run pytest tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_actions.py \
  tests/test_agents_oncall_flow_budget.py tests/test_agents_oncall_flow_readings.py \
  tests/test_agents_oncall_flow_escalation_tools.py -q                                       # 99 passed
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents        # clean
uv run lint-imports                                                                          # 9 kept, 0 broken
cd ui-tui && npm run lint:rpc && npx tsc --noEmit; cd ui-web && npm run gen:check && npx tsc --noEmit   # in sync, clean
```

New tests: `TestHeldTurn` (held across an armed wake, held again on a re-arm, heartbeat on the wait call, cancel while held, a non-`end_turn` stop is not held; every frame validated against the ACP schema), `TestSteer` (advertised, `no_turn` when idle, a held prompt takes the words as a turn with `busy: inject`, refusals), `busy: inject` on a busy and an idle lane in `test_rpc_turn_send.py`, and the plugin's hold stamping through the real `CronService` grant (filed with a pending wake; not filed without one, after the wake stands down, or once the campaign concluded).

Not done: no end-to-end run of a real on-call wake through a held prompt yet -- unit tests only.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (the hold is invisible to a person except as a "waiting for ..." tool row)

## Risk

- [x] Backward compatibility considered: a turn that files no `raven.holdTurn` is answered exactly as before; `busy` is optional and absent from every existing caller; the steer method and capability are additive.
- [x] Rollback path is clear: revert the two commits.

A held prompt holds one `max_concurrent_subagents` slot (default 8) for the wait's duration on the caller's side; raised in config if it bites.

## Related

Replaces !573 (closed). Follows !518 (stall notice) and !520 (unprompted-turn route; a wake that runs under a held prompt no longer takes it for DAG nodes).
2026-09-11 02:37:55 +00:00
silverLXT
83aac42909 feat(acp): a prompt is held open while the agent sleeps on an armed wake, and takes a steer
## Summary

An on-call agent submits a job, arms a wake and ends its turn saying so; the wake runs a later turn on the session on its own clock. Over ACP that turn's `end_turn` read as "finished" to the caller: a DAG judging its node spent every continuation on "still watching, wake at 13:13" while the job ran fine (ar-r4, 2026-09-08), and the main agent re-dispatched the work by hand. ACP has no stop reason for "waiting". Replaces the closed !573: **no DAG code changes**, no new node status. The node is `running` because a turn is genuinely in flight.

- **The signal.** The loop-hooks paper gains one key the ACP layer reads for itself: `acp_meta["raven.holdTurn"]` (`{"untilMs", "why"}`). oncall-flow files it at the send fire when the window's campaign is claimed, not concluded, and has one pending wake -- read the same way the owner's answer pulls that wake forward. No campaign, a wake that stood down, or a concluded campaign files nothing and the turn ends as before.
- **The hold** (`raven/acp/methods.py`). A turn that ended `end_turn` with the key filed is not answered. One `tool_call` stands for the wait (its title names the campaign and the next look), with a `tool_call_update` heartbeat every `HOLD_HEARTBEAT_S` (60 s) so a client that clocks liveness by frames sees the agent alive while its model sleeps. The turn slot is reopened with no id to correlate on, so whichever turn ends next on the session -- the wake's, a steer's -- settles it, and the handler decides again from that turn's stash. A wake that arms again keeps the hold; a turn ending with nothing pending answers `end_turn`; a cancel answers `cancelled` as before. The key itself is not passed to the client.
- **Steer.** `_raven/session/steer` is served and advertised under `agentCapabilities._meta` as `raven.steer` (the names raven's own client already uses). Accepted while a prompt is open on the session, held or running: the text is shown on the wire as the person's own line, then sent with `turn.send`'s new `busy: "inject"`. Answers `injected` / `no_turn`.
- **Wire.** `turn.send` gains the optional `busy` param (`const "inject"`): an ordinary send on an idle lane, `BusyPolicy.INJECT` into the running turn otherwise -- the merge a channel's mid-turn message already gets (`gateway_commands.py`). No slot is bound for an injected message; the running turn keeps the lane's. `openrpc.json` and both generated clients moved together.

What raven's client side already does, unchanged: the DAG stall watcher resets on any frame (the heartbeat keeps it quiet, and a stopped heartbeat raises the existing stall notice after ten minutes); a sub-agent process that dies fails the request and the node takes its ordinary path; the pool's `_responsive` treats a prompt in flight as busy.

## Review round 1 (2026-09-09, on !600, superseded by this MR)

- **`busy: inject` reads the scheduler's lane state too.** `is_turn_active` knows only the turns `turn.send` started; an armed wake is submitted to the scheduler directly (`make_on_session_wake`) and never binds that map, so a steer during a running wake queued a second turn and answered `injected`. `turn.send` now asks `Scheduler.has_inflight(lane)` as well, and merges (`BusyPolicy.INJECT`) when either record says the lane is running. Pinned: `test_busy_inject_merges_into_a_wake_the_real_scheduler_is_running` -- the reviewer's reproduction on the real `Scheduler`, a turn submitted the way `make_on_session_wake` submits one; with the lane check bypassed it reads `pending=1, inject_mailbox=0`, with it `(1, 0)` in the mailbox and the running turn drains the text.
- Branch renamed to snake_case and both commits carry the `Co-authored-by: Claude (<model-id>)` trailer, per AGENTS.md §2–3; that is why this MR replaces !600 rather than continuing it.

## Review round 2 (2026-09-10)

- **A wake re-armed during its own run survives the writeback.** `CronService._writeback_locked` reloaded the store after the run and, for a one-shot with `delete_after_run`, overwrote the id with the finished run's state and removed it -- but the turn the wake ran had just called `schedule_wake` under the same key, so the id now named the *next* look. It vanished, and the held prompt had nothing left to settle it. A stored job under the fired id whose `at` schedule the run never had is treated as the new wake it is: claim cleared, run recorded, schedule kept, not deleted. Pinned on the real service: `test_a_wake_re_armed_during_its_own_run_survives_the_writeback` (reads `[]` without the fix, the reviewer's state) and the unchanged one-shot deletion beside it. Cron, proactive, sentinel and on-call suites: 968 passed.

## Review round 3 (2026-09-10)

- **An undrained inject stays visible and cancellable.** `busy: inject` dropped the scheduler's handle; when the host turn ended past its last drain, the spine's fallback ran the text as a turn nothing owned -- `turn.cancel` a no-op, no `message.start`. The handle is now kept per lane under an id minted for the text; `turn.cancel` / `session.interrupt` reach it when the active slot is empty (mailbox, queued fallback, or running); and when the fallback turn starts, the RPC sink (`on_turn_start`, wired from bootstrap) binds the lane to it and opens it on the wire with the person's words. `turn.send` answers the inject's own id. Pinned through `build_rpc_spine` with the reviewer's shape (a loop that drains once, an inject after it): `test_an_undrained_inject_runs_as_a_turn_the_surface_can_see_and_cancel` and `test_a_pending_inject_can_be_cancelled_before_it_merges_or_falls_back`; both read the reviewer's state (`turn_ids` empty, cancel finding nothing) with the fix bypassed.
- **Line ceiling.** The contract comment is five lines; `raven/contracts` is 2,519 against 2,520, one line of headroom on the current `main` (2,514).
- Non-blocking items taken: `SchedulerDrainingError` on the inject path exits as `turn_failed`; the title is announced before the hold; the steer constants sit below the cancel constant's docstring; three edges pinned (a held prompt settled by a wake turn's uncorrelated ending through `send_frame`, the hold key never in the client's `_meta`, `raven.toolName` on the wait row).
- Focused suite (reviewer's list plus the touched files): 948 passed on Python 3.12.

## Review round 4 (2026-09-10)

- **Every pending inject is kept, per lane and per id.** One replaceable record per lane kept only the newest steer; two steers after the host's last drain fall back in turn, and the first started unowned while a cancel took out the second. The record is now `lane -> {inject id: (handle, text)}` in arrival order: each fallback promotes its own handle, and a cancel with no active turn reaches the oldest pending one -- the one the spine runs next. Pinned: `test_two_undrained_injects_each_get_their_own_turn_promoted_and_cancelled` (both promoted with their own ids and `message.start`, cancelled one after the other; runner saw all three turns). Focused suite: 949 passed.

## Type

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

## Verification

```
uv run pytest tests/test_acp_methods.py tests/test_acp_protocol.py tests/test_rpc_turn_send.py \
  tests/test_rpc_schema_match.py tests/test_acp_updates.py tests/test_acp_server.py -q      # 766 passed
uv run pytest tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_actions.py \
  tests/test_agents_oncall_flow_budget.py tests/test_agents_oncall_flow_readings.py \
  tests/test_agents_oncall_flow_escalation_tools.py -q                                       # 99 passed
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents        # clean
uv run lint-imports                                                                          # 9 kept, 0 broken
cd ui-tui && npm run lint:rpc && npx tsc --noEmit; cd ui-web && npm run gen:check && npx tsc --noEmit   # in sync, clean
```

New tests: `TestHeldTurn` (held across an armed wake, held again on a re-arm, heartbeat on the wait call, cancel while held, a non-`end_turn` stop is not held; every frame validated against the ACP schema), `TestSteer` (advertised, `no_turn` when idle, a held prompt takes the words as a turn with `busy: inject`, refusals), `busy: inject` on a busy and an idle lane in `test_rpc_turn_send.py`, and the plugin's hold stamping through the real `CronService` grant (filed with a pending wake; not filed without one, after the wake stands down, or once the campaign concluded).

Not done: no end-to-end run of a real on-call wake through a held prompt yet -- unit tests only.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (the hold is invisible to a person except as a "waiting for ..." tool row)

## Risk

- [x] Backward compatibility considered: a turn that files no `raven.holdTurn` is answered exactly as before; `busy` is optional and absent from every existing caller; the steer method and capability are additive.
- [x] Rollback path is clear: revert the two commits.

A held prompt holds one `max_concurrent_subagents` slot (default 8) for the wait's duration on the caller's side; raised in config if it bites.

## Related

Replaces !573 (closed). Follows !518 (stall notice) and !520 (unprompted-turn route; a wake that runs under a held prompt no longer takes it for DAG nodes).
2026-09-11 02:37:55 +00:00
0xKT
8eb69f59f2 fix(providers): honour the declared output ceiling, retry differently, record a failed call
## Summary

A model call that returned nothing used to end a turn, and nothing in the record said why.
This branch closes that in five parts, all on the host runtime.

- **The output ceiling is the model's, not ours.** `resolve_max_output_tokens` takes the
  figure the model declares instead of a repo default, reserves it against the id the
  request actually goes out under, and counts cached prompt tokens toward the window so a
  cached prefix stops looking free. One call is given 64k of room and says so on the wire;
  the transcript summary budget goes to 32k. Two small output pins keep deliberate
  headroom, and the commit says why they do not move.
- **A retry has to ask a different question.** An empty completion previously repeated the
  same request and got the same answer. The ladder now descends by **what a rung sends**
  rather than by its label, the transcript summary is no longer asked to think, and the
  empty-completion retry differs from the call it replaces.
- **Time to first byte is bounded.** `llmFirstByteTimeout` applies on the direct adapters
  as well as through the gateway, a bound of zero means off rather than a bound at the
  total, and the guard's deadline is distinguished from a strategy's own `TimeoutError` so
  a fallback answers for the right one.
- **An effort travels as an effort.** `glm` is out of `inferred_protocol`'s Anthropic prefix
  tuple and the hand-written `_THINKING_BUDGETS` table is deleted, so a label reaches the
  vendor as a label rather than as a token count this repo invented. Measured on the wire
  before the change: 42 calls produced 261,980 characters of reasoning against a budget of
  1024 that the route discarded, while our own `max_tokens` went out on every call because
  that transport requires the field.
- **The record says what was asked and what came back.** A failed call is visible in the
  turn and readable in the record; the reasoning count is kept; a failure's headers are
  recorded as the failure's, not as a stream's server; `llm.input` gains a `generation`
  block and the span gains `llm.request.*`, with a test pinning that no credential appears
  in either. `llm.request_bytes` is documented as an estimate instead of claiming to be
  the wire. A frozen turn is stopped rather than nudged once.

## Type

- [x] Fix
- [x] Feature

## Verification

- `uv run --frozen pytest` over the full suite: **20354 passed**, with 6 failures and 20
  errors that are this box lacking `/usr/share/zoneinfo` -- all in `test_cron_tool.py` and
  `test_cli_cron_commands.py`, which this branch does not touch. Reproduced with the
  identical signature on a clean detached `origin/main` worktree, and CI ships tzdata, so
  its `tests` job is the authoritative check. Gated on `set -o pipefail` and
  `${PIPESTATUS[0]}`.
- `make lint-python` exit 0; `lint-imports` 9 kept, 0 broken.
- Contract pins re-derived against current `main` rather than carried over:
  `CONTRACTS_VERSION` **17** (main is 16), the digest from one run of the pinning test, and
  `CONTRACTS_LINE_CEILING` **2_791** against 2771 actual. 34 pinning tests pass.
- The request shape verified on real captured bodies rather than inferred: after the change
  a deck call is `POST /v1/chat/completions` carrying `reasoning: {"effort": ...}` at the
  top level, the configured temperature, and **no** `max_tokens`; before it, the same call
  was `POST /v1/messages` carrying `thinking: {"type": "enabled", "budget_tokens": 1024}`.

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

## Risk

The routing change moves every `glm` model from the native Anthropic Messages transport to
LiteLLM chat. That changes which client serves the deck agent and the host default model,
so it is the one item here worth a real run before it is relied on. Measured consequences
on a live deck: no truncations, no length-stops, no empty completions and no retries across
40 calls, and prompt-cache read rates in the same band as the Messages route -- `glm` takes
no `cache_control` breakpoints on either transport because OpenRouter caches it
automatically, so caching is unaffected. A provider that needs an Anthropic-compatible
address can still name `protocol: "anthropic"` explicitly, and a test pins that route.

Rollback is per part: each of the five is its own commit range, and the routing change is a
single line in `raven/providers/protocol.py`.

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

## Related Issues

N/A
2026-09-11 02:37:37 +00:00
Tchen
3f1453d5fe fix(providers): honour the declared output ceiling, retry differently, record a failed call
## Summary

A model call that returned nothing used to end a turn, and nothing in the record said why.
This branch closes that in five parts, all on the host runtime.

- **The output ceiling is the model's, not ours.** `resolve_max_output_tokens` takes the
  figure the model declares instead of a repo default, reserves it against the id the
  request actually goes out under, and counts cached prompt tokens toward the window so a
  cached prefix stops looking free. One call is given 64k of room and says so on the wire;
  the transcript summary budget goes to 32k. Two small output pins keep deliberate
  headroom, and the commit says why they do not move.
- **A retry has to ask a different question.** An empty completion previously repeated the
  same request and got the same answer. The ladder now descends by **what a rung sends**
  rather than by its label, the transcript summary is no longer asked to think, and the
  empty-completion retry differs from the call it replaces.
- **Time to first byte is bounded.** `llmFirstByteTimeout` applies on the direct adapters
  as well as through the gateway, a bound of zero means off rather than a bound at the
  total, and the guard's deadline is distinguished from a strategy's own `TimeoutError` so
  a fallback answers for the right one.
- **An effort travels as an effort.** `glm` is out of `inferred_protocol`'s Anthropic prefix
  tuple and the hand-written `_THINKING_BUDGETS` table is deleted, so a label reaches the
  vendor as a label rather than as a token count this repo invented. Measured on the wire
  before the change: 42 calls produced 261,980 characters of reasoning against a budget of
  1024 that the route discarded, while our own `max_tokens` went out on every call because
  that transport requires the field.
- **The record says what was asked and what came back.** A failed call is visible in the
  turn and readable in the record; the reasoning count is kept; a failure's headers are
  recorded as the failure's, not as a stream's server; `llm.input` gains a `generation`
  block and the span gains `llm.request.*`, with a test pinning that no credential appears
  in either. `llm.request_bytes` is documented as an estimate instead of claiming to be
  the wire. A frozen turn is stopped rather than nudged once.

## Type

- [x] Fix
- [x] Feature

## Verification

- `uv run --frozen pytest` over the full suite: **20354 passed**, with 6 failures and 20
  errors that are this box lacking `/usr/share/zoneinfo` -- all in `test_cron_tool.py` and
  `test_cli_cron_commands.py`, which this branch does not touch. Reproduced with the
  identical signature on a clean detached `origin/main` worktree, and CI ships tzdata, so
  its `tests` job is the authoritative check. Gated on `set -o pipefail` and
  `${PIPESTATUS[0]}`.
- `make lint-python` exit 0; `lint-imports` 9 kept, 0 broken.
- Contract pins re-derived against current `main` rather than carried over:
  `CONTRACTS_VERSION` **17** (main is 16), the digest from one run of the pinning test, and
  `CONTRACTS_LINE_CEILING` **2_791** against 2771 actual. 34 pinning tests pass.
- The request shape verified on real captured bodies rather than inferred: after the change
  a deck call is `POST /v1/chat/completions` carrying `reasoning: {"effort": ...}` at the
  top level, the configured temperature, and **no** `max_tokens`; before it, the same call
  was `POST /v1/messages` carrying `thinking: {"type": "enabled", "budget_tokens": 1024}`.

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

## Risk

The routing change moves every `glm` model from the native Anthropic Messages transport to
LiteLLM chat. That changes which client serves the deck agent and the host default model,
so it is the one item here worth a real run before it is relied on. Measured consequences
on a live deck: no truncations, no length-stops, no empty completions and no retries across
40 calls, and prompt-cache read rates in the same band as the Messages route -- `glm` takes
no `cache_control` breakpoints on either transport because OpenRouter caches it
automatically, so caching is unaffected. A provider that needs an Anthropic-compatible
address can still name `protocol: "anthropic"` explicitly, and a test pins that route.

Rollback is per part: each of the five is its own commit range, and the routing change is a
single line in `raven/providers/protocol.py`.

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

## Related Issues

N/A
2026-09-11 02:37:37 +00:00
0xKT
cfe806a6e0 feat(cli): onboard spends one real search on the web_search key
## Summary

The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.

- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.

Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.

## Type

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

## Verification

```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
  tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py    410 passed
make lint-python                                                     clean
make check-source-language                                           exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD     exit 0
```

Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.

Not verified: a live run against a real vendor key.

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

User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.

## Related Issues

N/A
2026-09-11 02:35:44 +00:00
userName20260323
62aefbd1e5 feat(cli): onboard spends one real search on the web_search key
## Summary

The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.

- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.

Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.

## Type

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

## Verification

```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
  tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py    410 passed
make lint-python                                                     clean
make check-source-language                                           exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD     exit 0
```

Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.

Not verified: a live run against a real vendor key.

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

User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.

## Related Issues

N/A
2026-09-11 02:35:44 +00:00
0xKT
cf9a0a8b5a chore(*): a cyclomatic complexity ceiling that only stops the untestable
## Summary

Ruff carried no complexity rule, so nothing bounded the number of paths through
a function. This adds `C901` with a ceiling chosen to stop the untestable and
nothing else.

**What the number means.** Cyclomatic complexity is the count of linearly
independent paths through a function, which makes it the floor on how many cases
a suite needs to walk them all. A body with a hundred of them has paths nobody
will ever write a case for, and those paths are first executed in production.
That is the failure this rule prevents; it is not a style preference.

Two properties of the metric matter for reading the numbers below. A nested
function's score is counted into its enclosing function as well as reported on
its own, so an outer function with no branches of its own scores one more than
the inner function it holds. And Ruff reports `C901` only when the score is
*greater* than `max-complexity`, so a function at exactly 40 passes a ceiling of
40 and needs no suppression.

**Where 40 comes from.** The measured distribution, not McCabe's recommendation
of 10:

| max-complexity | functions flagged |
|---|---|
| 10 | 253 |
| 25 | 26 |
| 30 | 17 |
| **40** | **9** |
| 50 | 5 |

Ten would flag 253 functions and be switched off within the week. Forty is not a
claim that 39 is fine -- it is where a function stops being complex and starts
being untestable. Tightening later means lowering the number, which is a
reviewed edit to `pyproject.toml`.

**The nine over the ceiling.** Each carries a `noqa: C901` naming its actual
score. Seven are in `raven/`, two in the oncall-flow plugin under `agents/`:

```
100  raven/agent/loop/turn_path.py                             _run_agent_loop
 87  raven/cli/gateway_commands.py                             register
 86  raven/cli/gateway_commands.py                             gateway
 69  agents/raven-oncall/.../oncall_flow/tools/ops.py           execute
 68  raven/cli/gateway_commands.py                             run
 54  agents/raven-oncall/.../oncall_flow/tools/ops.py           execute
 47  raven/agent/loop/turn_path.py                             _process_message
 46  raven/config/loader.py                                    _migrate_config
 41  raven/agent/loop/turn_path.py                             _run_turn
```

A tenth suppression sits on `benchmarks/proactivity_eval/runners/_common/longrun_adapters.py`
(`tick_to`, 41). `benchmarks/` is outside `PYTHON_LINT_TARGETS` and so outside
CI, but inside what the pre-commit Ruff hook sees on a changed file -- marking it
means the gate does not ambush whoever next edits that adapter.

**Nine entries, fewer distinct problems.** In `gateway_commands.py` the three
are nested inside each other at indent 0, 4 and 8: `run` at 68 is the body,
`gateway` adds its own branches on top, and `register` contributes about one. In
`turn_path.py` the three are sibling methods, but `_run_turn` holds ten nested
callbacks (`on_token`, `on_tool`, `on_progress` and so on) which is most of its
41. The one that is a large body by itself is `_run_agent_loop`: 1134 lines with
only two nested functions, so its 100 is its own.

Per-function rather than per-file, on purpose: a whole-file ignore on
`gateway_commands.py` would let a new 80-path function in the same file through,
while these entries do not. The score is in the comment so the debt is visible
where the code is, not parked in a config file.

Nothing has to be refactored to land this. Normal work is undisturbed unless
someone writes a forty-one-path function.

**Why the PLR09xx rules are left out.** They count arguments (230 occurrences
here), branches (125), statements (78) and returns (81). All four are proxies
for what `C901` measures directly, so adding them would report one fact four
times and bury the signal under 230 argument-count warnings.

## Type

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

Other: a lint gate plus the `noqa` entries that let it land green. No runtime
code changes; every production edit is an end-of-line comment.

## Verification

Verified against the lint roster read out of the Makefile
(`PYTHON_LINT_TARGETS = raven evolver agents plugins-dist tests scripts`) rather
than a chosen subset, and then against the whole tree. The first revision of
this MR checked only `raven/` and went red in CI on the two `agents/` functions;
that is what the roster-wide check exists to prevent.

```
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
    raven evolver agents plugins-dist tests scripts
All checks passed!

$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache .
All checks passed!

$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
    --extend-select RUF100 raven evolver agents plugins-dist tests scripts
(no unused C901 directive)

$ uv run --frozen --python 3.12 --extra dev ruff format --check \
    raven evolver agents plugins-dist tests scripts
1886 files already formatted

$ uv run --frozen --python 3.12 pytest tests/ -q -k "turn_path or gateway or loader or console or config_precedence"
511 passed, 19 skipped

$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.

$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```

The 19 skips are pre-existing and environmental: `test_provider_resolution_invariants.py`
skips its gateway-only cases when no gateway is configured.

Checked in the failing direction, since a gate never seen red is not known to
work. A fresh forty-branch function appended to `config/loader.py` is reported,
and the `noqa` on `_migrate_config` in the same file keeps holding rather than
being swallowed by it:

```
raven/config/loader.py:1088:5: C901 `_probe_over_ceiling` is too complex (41 > 40)
Found 1 error.
```

The probe was reverted. Note for the reviewer: reverting that file also reverted
its `noqa`, which the roster-wide check caught immediately.

One entry was removed after review rather than kept: `settings_usage` scores
exactly 40, which a ceiling of 40 does not flag, so its suppression was dead.
`--extend-select RUF100` reports such a directive as unused, and keeping it would
have defeated the documented tightening path -- lowering the number later would
have left that function exempt with nothing to show it.

The production diff is comment-only and can be read as such:

```
-    async def _run_agent_loop(
+    async def _run_agent_loop(  # noqa: C901 (cc 100: pre-existing, above the ceiling)
```

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

No user-facing surface changes.

## Risk

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

No behaviour change: every production edit is an end-of-line comment, and the
diff can be verified as such. The risk this carries is a false sense of
coverage, which is why the rationale in `pyproject.toml` states what the ceiling
does not mean. Two limits of the metric are worth a reviewer knowing: it does
not see nesting depth (five sequential `if`s and five nested ones both score 6),
and in Ruff's implementation boolean operators, ternaries and comprehension
conditions do not count at all. It is a filter for the untestable, not a
readability score.

Rollback is reverting the commits. Loosening instead of reverting is a one-line
change to `max-complexity`, which is the intended escape if the gate turns out
to obstruct real work.

## Related Issues

N/A
2026-09-11 02:35:31 +00:00
gloryfromca
4f94ad43cc chore(*): a cyclomatic complexity ceiling that only stops the untestable
## Summary

Ruff carried no complexity rule, so nothing bounded the number of paths through
a function. This adds `C901` with a ceiling chosen to stop the untestable and
nothing else.

**What the number means.** Cyclomatic complexity is the count of linearly
independent paths through a function, which makes it the floor on how many cases
a suite needs to walk them all. A body with a hundred of them has paths nobody
will ever write a case for, and those paths are first executed in production.
That is the failure this rule prevents; it is not a style preference.

Two properties of the metric matter for reading the numbers below. A nested
function's score is counted into its enclosing function as well as reported on
its own, so an outer function with no branches of its own scores one more than
the inner function it holds. And Ruff reports `C901` only when the score is
*greater* than `max-complexity`, so a function at exactly 40 passes a ceiling of
40 and needs no suppression.

**Where 40 comes from.** The measured distribution, not McCabe's recommendation
of 10:

| max-complexity | functions flagged |
|---|---|
| 10 | 253 |
| 25 | 26 |
| 30 | 17 |
| **40** | **9** |
| 50 | 5 |

Ten would flag 253 functions and be switched off within the week. Forty is not a
claim that 39 is fine -- it is where a function stops being complex and starts
being untestable. Tightening later means lowering the number, which is a
reviewed edit to `pyproject.toml`.

**The nine over the ceiling.** Each carries a `noqa: C901` naming its actual
score. Seven are in `raven/`, two in the oncall-flow plugin under `agents/`:

```
100  raven/agent/loop/turn_path.py                             _run_agent_loop
 87  raven/cli/gateway_commands.py                             register
 86  raven/cli/gateway_commands.py                             gateway
 69  agents/raven-oncall/.../oncall_flow/tools/ops.py           execute
 68  raven/cli/gateway_commands.py                             run
 54  agents/raven-oncall/.../oncall_flow/tools/ops.py           execute
 47  raven/agent/loop/turn_path.py                             _process_message
 46  raven/config/loader.py                                    _migrate_config
 41  raven/agent/loop/turn_path.py                             _run_turn
```

A tenth suppression sits on `benchmarks/proactivity_eval/runners/_common/longrun_adapters.py`
(`tick_to`, 41). `benchmarks/` is outside `PYTHON_LINT_TARGETS` and so outside
CI, but inside what the pre-commit Ruff hook sees on a changed file -- marking it
means the gate does not ambush whoever next edits that adapter.

**Nine entries, fewer distinct problems.** In `gateway_commands.py` the three
are nested inside each other at indent 0, 4 and 8: `run` at 68 is the body,
`gateway` adds its own branches on top, and `register` contributes about one. In
`turn_path.py` the three are sibling methods, but `_run_turn` holds ten nested
callbacks (`on_token`, `on_tool`, `on_progress` and so on) which is most of its
41. The one that is a large body by itself is `_run_agent_loop`: 1134 lines with
only two nested functions, so its 100 is its own.

Per-function rather than per-file, on purpose: a whole-file ignore on
`gateway_commands.py` would let a new 80-path function in the same file through,
while these entries do not. The score is in the comment so the debt is visible
where the code is, not parked in a config file.

Nothing has to be refactored to land this. Normal work is undisturbed unless
someone writes a forty-one-path function.

**Why the PLR09xx rules are left out.** They count arguments (230 occurrences
here), branches (125), statements (78) and returns (81). All four are proxies
for what `C901` measures directly, so adding them would report one fact four
times and bury the signal under 230 argument-count warnings.

## Type

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

Other: a lint gate plus the `noqa` entries that let it land green. No runtime
code changes; every production edit is an end-of-line comment.

## Verification

Verified against the lint roster read out of the Makefile
(`PYTHON_LINT_TARGETS = raven evolver agents plugins-dist tests scripts`) rather
than a chosen subset, and then against the whole tree. The first revision of
this MR checked only `raven/` and went red in CI on the two `agents/` functions;
that is what the roster-wide check exists to prevent.

```
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
    raven evolver agents plugins-dist tests scripts
All checks passed!

$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache .
All checks passed!

$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
    --extend-select RUF100 raven evolver agents plugins-dist tests scripts
(no unused C901 directive)

$ uv run --frozen --python 3.12 --extra dev ruff format --check \
    raven evolver agents plugins-dist tests scripts
1886 files already formatted

$ uv run --frozen --python 3.12 pytest tests/ -q -k "turn_path or gateway or loader or console or config_precedence"
511 passed, 19 skipped

$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.

$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```

The 19 skips are pre-existing and environmental: `test_provider_resolution_invariants.py`
skips its gateway-only cases when no gateway is configured.

Checked in the failing direction, since a gate never seen red is not known to
work. A fresh forty-branch function appended to `config/loader.py` is reported,
and the `noqa` on `_migrate_config` in the same file keeps holding rather than
being swallowed by it:

```
raven/config/loader.py:1088:5: C901 `_probe_over_ceiling` is too complex (41 > 40)
Found 1 error.
```

The probe was reverted. Note for the reviewer: reverting that file also reverted
its `noqa`, which the roster-wide check caught immediately.

One entry was removed after review rather than kept: `settings_usage` scores
exactly 40, which a ceiling of 40 does not flag, so its suppression was dead.
`--extend-select RUF100` reports such a directive as unused, and keeping it would
have defeated the documented tightening path -- lowering the number later would
have left that function exempt with nothing to show it.

The production diff is comment-only and can be read as such:

```
-    async def _run_agent_loop(
+    async def _run_agent_loop(  # noqa: C901 (cc 100: pre-existing, above the ceiling)
```

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

No user-facing surface changes.

## Risk

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

No behaviour change: every production edit is an end-of-line comment, and the
diff can be verified as such. The risk this carries is a false sense of
coverage, which is why the rationale in `pyproject.toml` states what the ceiling
does not mean. Two limits of the metric are worth a reviewer knowing: it does
not see nesting depth (five sequential `if`s and five nested ones both score 6),
and in Ruff's implementation boolean operators, ternaries and comprehension
conditions do not count at all. It is a filter for the untestable, not a
readability score.

Rollback is reverting the commits. Loosening instead of reverting is a one-line
change to `max-complexity`, which is the intended escape if the gate turns out
to obstruct real work.

## Related Issues

N/A
2026-09-11 02:35:31 +00:00
0xKT
02ea26aa6f refactor(permissions): the shell command policy seats where it is enforced
## Summary

`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.

The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.

Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.

Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.

This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.

## Type

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

## Verification

```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.

$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
    tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
    tests/test_permissions_gate.py tests/test_acp_server.py \
    tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s

$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s

$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
    raven/acp/server.py raven/agent/tools/shell.py
All checks passed!

$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```

The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.

Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.

Effect on the dependency graph:

```
permissions -> agent edges     1  ->  0
mutually importing pairs      14  ->  13
packages in an import cycle   22  ->  22   (unchanged)
```

The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.

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

No user-facing surface changes.

## Risk

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

This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.

No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.

## Related Issues

N/A
2026-09-11 02:35:05 +00:00
gloryfromca
c01af5faa3 refactor(permissions): the shell command policy seats where it is enforced
## Summary

`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.

The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.

Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.

Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.

This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.

## Type

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

## Verification

```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.

$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
    tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
    tests/test_permissions_gate.py tests/test_acp_server.py \
    tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s

$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s

$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
    raven/acp/server.py raven/agent/tools/shell.py
All checks passed!

$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```

The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.

Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.

Effect on the dependency graph:

```
permissions -> agent edges     1  ->  0
mutually importing pairs      14  ->  13
packages in an import cycle   22  ->  22   (unchanged)
```

The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.

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

No user-facing surface changes.

## Risk

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

This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.

No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.

## Related Issues

N/A
2026-09-11 02:35:05 +00:00
0xKT
3262294989 fix(rpc): a watched sub-agent relay turn can approve an ask-tier tool
## Summary

When a DAG node fails, the sub-agent's report opens a turn in the user's own conversation (origin `SUBAGENT`). The asker already bound in that turn whenever a surface was watching the conversation, so the person could answer `ask_user` there and pick "continue". The approval responder, however, bound only for `USER` turns, so the `resolve_dag_node` call that acts on that answer was refused in the same turn as "this turn is not interactive". The run ended on the person's own decision: the node could be neither continued nor abandoned from the TUI or the WebUI.

The fix binds the approval responder on the gate the asker already used: a `USER` turn always, a `SUBAGENT` relay when its conversation has a live watcher, every other origin never. One expression, shared by both bindings, in `RpcTurnRunner.run`.

The gateway's channel runner (`GatewayTurnRunner`) is deliberately left as it is: a channel session has no watched-signal to gate on, and widening there would turn an abandoned-channel question from an instant decline into a stall, as its own comment says.

## Type

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

## Verification

- `uv run pytest tests/test_rpc_spine.py tests/test_agent_loop_approval.py tests/test_shell_approval.py tests/test_permissions*.py -q`: 361 passed. Two new cases: a `SUBAGENT` turn in a watched conversation reaches the responder and the gated tool runs; the same turn with nobody watching is still refused as not interactive.
- Reverse check: with the spine change reverted, the watched-relay case fails on the gated tool not running.
- `make lint-python`: clean.
- `uv run --all-extras pytest -q` (before rebase): 20150 passed, 4 failed, 165 skipped. The 4 failures (`test_agent_loop_token_budget`, `test_agents_code_launcher`, `test_agents_oncall_launcher`, `test_ppt_engine_image_search`) fail identically with this change reverted and again on the rebased head; none of them imports `raven.rpc.spine`. Pre-existing on `main`.

End to end, no permission override in the config, host started from this branch, port owner start time checked against the last code change:

| Frontend | Flow | Result |
|---|---|---|
| TUI (`raven tui --dev`) | run a playbook whose carried server is down -> node fails -> host calls `resolve_dag_node continue` -> approval overlay "Approve this action: resolve_dag_node {...}" -> key 1 -> tool runs -> attempt-2 dispatched | pass (before the fix the same step ended in "This call requires user approval (ask tier), but this turn is not interactive") |
| WebUI (`raven serve`) | same flow -> approval sheet "Approve this action: resolve_dag_node {...}" -> "Allow once" -> tool runs (the model chose abandon this time, so no second attempt; the point under test is that the approval reaches the person and the gated tool executes) | pass |

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs exist for the approval gate)

## Risk

- Permission semantics: an ask-tier tool called in a sub-agent relay turn now reaches the person watching the conversation instead of being refused. It still fails closed with nobody watching (`has_subscribers` false), on timeout, and on every other origin. This is the same reachability rule the asker has had since the relay widening; approval was the one binding that had not followed it.
- Backward compatibility: `USER` and `CRON` turns are unchanged. The channel gateway runner is unchanged.
- Rollback: revert the squash commit; no data or config involved.

## Related Issues

N/A
2026-09-10 18:07:37 +00:00
gloryfromca
86651393ca fix(rpc): a watched sub-agent relay turn can approve an ask-tier tool
## Summary

When a DAG node fails, the sub-agent's report opens a turn in the user's own conversation (origin `SUBAGENT`). The asker already bound in that turn whenever a surface was watching the conversation, so the person could answer `ask_user` there and pick "continue". The approval responder, however, bound only for `USER` turns, so the `resolve_dag_node` call that acts on that answer was refused in the same turn as "this turn is not interactive". The run ended on the person's own decision: the node could be neither continued nor abandoned from the TUI or the WebUI.

The fix binds the approval responder on the gate the asker already used: a `USER` turn always, a `SUBAGENT` relay when its conversation has a live watcher, every other origin never. One expression, shared by both bindings, in `RpcTurnRunner.run`.

The gateway's channel runner (`GatewayTurnRunner`) is deliberately left as it is: a channel session has no watched-signal to gate on, and widening there would turn an abandoned-channel question from an instant decline into a stall, as its own comment says.

## Type

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

## Verification

- `uv run pytest tests/test_rpc_spine.py tests/test_agent_loop_approval.py tests/test_shell_approval.py tests/test_permissions*.py -q`: 361 passed. Two new cases: a `SUBAGENT` turn in a watched conversation reaches the responder and the gated tool runs; the same turn with nobody watching is still refused as not interactive.
- Reverse check: with the spine change reverted, the watched-relay case fails on the gated tool not running.
- `make lint-python`: clean.
- `uv run --all-extras pytest -q` (before rebase): 20150 passed, 4 failed, 165 skipped. The 4 failures (`test_agent_loop_token_budget`, `test_agents_code_launcher`, `test_agents_oncall_launcher`, `test_ppt_engine_image_search`) fail identically with this change reverted and again on the rebased head; none of them imports `raven.rpc.spine`. Pre-existing on `main`.

End to end, no permission override in the config, host started from this branch, port owner start time checked against the last code change:

| Frontend | Flow | Result |
|---|---|---|
| TUI (`raven tui --dev`) | run a playbook whose carried server is down -> node fails -> host calls `resolve_dag_node continue` -> approval overlay "Approve this action: resolve_dag_node {...}" -> key 1 -> tool runs -> attempt-2 dispatched | pass (before the fix the same step ended in "This call requires user approval (ask tier), but this turn is not interactive") |
| WebUI (`raven serve`) | same flow -> approval sheet "Approve this action: resolve_dag_node {...}" -> "Allow once" -> tool runs (the model chose abandon this time, so no second attempt; the point under test is that the approval reaches the person and the gated tool executes) | pass |

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs exist for the approval gate)

## Risk

- Permission semantics: an ask-tier tool called in a sub-agent relay turn now reaches the person watching the conversation instead of being refused. It still fails closed with nobody watching (`has_subscribers` false), on timeout, and on every other origin. This is the same reachability rule the asker has had since the relay widening; approval was the one binding that had not followed it.
- Backward compatibility: `USER` and `CRON` turns are unchanged. The channel gateway runner is unchanged.
- Rollback: revert the squash commit; no data or config involved.

## Related Issues

N/A
2026-09-10 18:07:36 +00:00
0xKT
81c823519c test(*): the import cycles among subpackages may not reach further
## Summary

These are aggregate ceilings on how far import cycles reach, not a proof that no
cycle was deepened: an edge added between two members of the existing component
leaves every total unmoved, and that case is left to the contracts and to review.
The module docstring says so too.

`acyclic_siblings` is the import-linter contract that would forbid import cycles
among raven's top-level subpackages outright. It is not in `pyproject.toml`
because it is BROKEN: **18 of the 40 top-level subpackages sit in a single
strongly connected component**. Added as a gate it would paint CI red on arrival
and be switched off within the week.

This states the same rule as a budget instead of an absolute. Three ceilings, set
to what the tree measures today, and they may only go down:

```
PACKAGES_IN_CYCLES_CEILING = 18
MUTUAL_PAIRS_CEILING = 13
MODULES_IN_CYCLES_CEILING = 42
```

This branch carries the vocabulary refactor (MR 610) underneath it, because the
ceilings are the numbers that hold once that lands. If 610 merges first this
becomes a single-commit change; either way the ceilings match the tree the guard
runs against.

A change that draws a package or a module into a cycle for the first time, or
makes a new pair import each other, fails here. An edge added between two
members of the existing component does not: every total stays put, and that
case is left to the contracts and to review. Unpicking one lowers a ceiling,
which is a reviewed edit to the test file rather than a drive-by -- the same
shape `tests/test_kernel_budget.py` already uses, and for the same reason its
docstring gives.

Three numbers, because each is blind where another sees. Mutual pairs (a imports
b and b imports a) are the edges people actually add, and the failure message
names them. A cycle three packages long shows up in no pair at all, so a
component measure carries the general case.

The third exists because the package measure is an artifact of granularity as
much as of design. Collapsing a package to one node turns "config's writer
reaches agent, which reaches config's loader" into a cycle even where no module
imports itself back; measured per module, 42 of 635 modules sit in a cycle
rather than 18 of 40 packages. The two answer different questions -- whether a
package can be lifted out on its own, and whether a reader has a real knot to
walk around -- and they move independently: the refactor underneath took the
package count from 22 to 18 while moving the module count by three.

The numbers were still moving while this was written. `agent <-> permissions`
became the fourteenth mutual pair during the drafting, on a `permissions`
package that had just arrived. Nothing reported it, because nothing was
watching -- which is the case for pinning them.

`grimp` becomes an explicit dev dependency rather than staying a transitive one
through import-linter, since a test now imports it directly.

This changes no production code and unpicks no cycle. It fixes the number in
place so that the unpicking, when it happens, is not undone by the next branch.

### Both graph options are chosen, not defaulted

`exclude_type_checking_imports` is read out of `[tool.importlinter]` rather than
hardcoded, so the guard measures the same graph the contracts are checked
against. Without it, `gateway` counts as cyclic on a type-checking-only import
and the module count moves by three -- the guard would have been ratcheting a
graph no contract enforces.

`cache_dir=None` because grimp's default is a shared `.grimp_cache` that
outlives a branch switch. A guard whose job is to report the graph of the
checked-out tree must not serve one an earlier revision left behind: a stale hit
turns it red or green for reasons absent from the diff. Building fresh costs
about a second.

## Type

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

Other: an architecture guard, in the shape of a budget. Closest to `test`, which
is the commit type used.

## Verification

```
$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py -q
4 passed in 1.06s

$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py \
    tests/test_kernel_closure.py tests/test_kernel_budget.py -q
10 passed in 1.51s

$ uv run --frozen --python 3.12 lint-imports
Contracts: 8 kept, 0 broken.

$ uv run --frozen --python 3.12 --extra dev ruff check tests/test_import_cycle_budget.py
All checks passed!

$ uv run --frozen --python 3.12 --extra dev ruff format --check tests/test_import_cycle_budget.py
1 file already formatted

$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```

Checked in the failing direction once per ceiling, since a gate that has never
been seen red is not known to work.

Making `utils` import the subagent presets trips the two package ceilings and
leaves the module count untouched -- which is the granularity point above, seen
from the failing side:

```
AssertionError: 23 subpackages are inside an import cycle, over the ceiling of 18
AssertionError: 15 pairs of subpackages import each other, over the ceiling of 13
```

Making `utils.text` and `importer.skills.hermes` import each other is a real
module-level cycle, and trips the third:

```
AssertionError: 45 modules are inside an import cycle, over the ceiling of 42
```

Both probes were reverted; the diff carries only the guard, the ceilings and the
dependency line.

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

No user-facing surface changes.

## Risk

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

No runtime behaviour change. The guard reads the import graph and asserts three
counts; it adds about a second to the suite. All three ceilings are met on
arrival,
so nothing that exists today is blocked. Rollback is reverting the one commit.

The known limit of a count-based ratchet is the one the coverage ratchet already
carries: a change that closes one cycle and opens another leaves the totals
unmoved and passes. Naming the pairs in the failure message is what makes that
visible in review when it matters.

## Related Issues

N/A
2026-09-10 17:23:40 +00:00
gloryfromca
231a31c641 test(*): the import cycles among subpackages may not reach further
## Summary

These are aggregate ceilings on how far import cycles reach, not a proof that no
cycle was deepened: an edge added between two members of the existing component
leaves every total unmoved, and that case is left to the contracts and to review.
The module docstring says so too.

`acyclic_siblings` is the import-linter contract that would forbid import cycles
among raven's top-level subpackages outright. It is not in `pyproject.toml`
because it is BROKEN: **18 of the 40 top-level subpackages sit in a single
strongly connected component**. Added as a gate it would paint CI red on arrival
and be switched off within the week.

This states the same rule as a budget instead of an absolute. Three ceilings, set
to what the tree measures today, and they may only go down:

```
PACKAGES_IN_CYCLES_CEILING = 18
MUTUAL_PAIRS_CEILING = 13
MODULES_IN_CYCLES_CEILING = 42
```

This branch carries the vocabulary refactor (MR 610) underneath it, because the
ceilings are the numbers that hold once that lands. If 610 merges first this
becomes a single-commit change; either way the ceilings match the tree the guard
runs against.

A change that draws a package or a module into a cycle for the first time, or
makes a new pair import each other, fails here. An edge added between two
members of the existing component does not: every total stays put, and that
case is left to the contracts and to review. Unpicking one lowers a ceiling,
which is a reviewed edit to the test file rather than a drive-by -- the same
shape `tests/test_kernel_budget.py` already uses, and for the same reason its
docstring gives.

Three numbers, because each is blind where another sees. Mutual pairs (a imports
b and b imports a) are the edges people actually add, and the failure message
names them. A cycle three packages long shows up in no pair at all, so a
component measure carries the general case.

The third exists because the package measure is an artifact of granularity as
much as of design. Collapsing a package to one node turns "config's writer
reaches agent, which reaches config's loader" into a cycle even where no module
imports itself back; measured per module, 42 of 635 modules sit in a cycle
rather than 18 of 40 packages. The two answer different questions -- whether a
package can be lifted out on its own, and whether a reader has a real knot to
walk around -- and they move independently: the refactor underneath took the
package count from 22 to 18 while moving the module count by three.

The numbers were still moving while this was written. `agent <-> permissions`
became the fourteenth mutual pair during the drafting, on a `permissions`
package that had just arrived. Nothing reported it, because nothing was
watching -- which is the case for pinning them.

`grimp` becomes an explicit dev dependency rather than staying a transitive one
through import-linter, since a test now imports it directly.

This changes no production code and unpicks no cycle. It fixes the number in
place so that the unpicking, when it happens, is not undone by the next branch.

### Both graph options are chosen, not defaulted

`exclude_type_checking_imports` is read out of `[tool.importlinter]` rather than
hardcoded, so the guard measures the same graph the contracts are checked
against. Without it, `gateway` counts as cyclic on a type-checking-only import
and the module count moves by three -- the guard would have been ratcheting a
graph no contract enforces.

`cache_dir=None` because grimp's default is a shared `.grimp_cache` that
outlives a branch switch. A guard whose job is to report the graph of the
checked-out tree must not serve one an earlier revision left behind: a stale hit
turns it red or green for reasons absent from the diff. Building fresh costs
about a second.

## Type

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

Other: an architecture guard, in the shape of a budget. Closest to `test`, which
is the commit type used.

## Verification

```
$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py -q
4 passed in 1.06s

$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py \
    tests/test_kernel_closure.py tests/test_kernel_budget.py -q
10 passed in 1.51s

$ uv run --frozen --python 3.12 lint-imports
Contracts: 8 kept, 0 broken.

$ uv run --frozen --python 3.12 --extra dev ruff check tests/test_import_cycle_budget.py
All checks passed!

$ uv run --frozen --python 3.12 --extra dev ruff format --check tests/test_import_cycle_budget.py
1 file already formatted

$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```

Checked in the failing direction once per ceiling, since a gate that has never
been seen red is not known to work.

Making `utils` import the subagent presets trips the two package ceilings and
leaves the module count untouched -- which is the granularity point above, seen
from the failing side:

```
AssertionError: 23 subpackages are inside an import cycle, over the ceiling of 18
AssertionError: 15 pairs of subpackages import each other, over the ceiling of 13
```

Making `utils.text` and `importer.skills.hermes` import each other is a real
module-level cycle, and trips the third:

```
AssertionError: 45 modules are inside an import cycle, over the ceiling of 42
```

Both probes were reverted; the diff carries only the guard, the ceilings and the
dependency line.

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

No user-facing surface changes.

## Risk

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

No runtime behaviour change. The guard reads the import graph and asserts three
counts; it adds about a second to the suite. All three ceilings are met on
arrival,
so nothing that exists today is blocked. Rollback is reverting the one commit.

The known limit of a count-based ratchet is the one the coverage ratchet already
carries: a change that closes one cycle and opens another leaves the totals
unmoved and passes. Naming the pairs in the failure message is what makes that
visible in review when it matters.

## Related Issues

N/A
2026-09-10 17:23:40 +00:00
daoxize1
8cfba673d4 fix(agent): use model classification for design routing
## Change description

Remove keyword-based routing between Raven-Design and Raven-PPT. A task mentioning PPT, slides or a .pptx file now reaches the host model's classifier instead of selecting PPT through a regular expression. This also prevents keyword matching from overriding a request such as 'Do not make a PPT; make a poster'.

Existing instance bindings still take priority, so a follow-up continues on the implementation that owns its session. Classification still reads the authored task, not inlined file contents. Missing, invalid or failed classification retains the existing behavior of running on Design.

Remove the route match field and its unused file-reference filter. Update the manifest, generated schema, documentation and tests together.

Verification:

- `uv run --no-sync pytest tests/test_subagent_routing_backend.py tests/test_subagent_registry.py tests/test_subagent_vendored_agents.py tests/test_agents_design_launcher.py tests/test_agent_schemas.py tests/test_subagent_manager.py -q -n0`: 294 passed.
- `uv run --no-sync ruff check raven/agent/subagent/backends/routing.py raven/agent/subagent/registry.py raven/agent/subagent/manager.py raven/config/schema.py tests/test_subagent_routing_backend.py tests/test_subagent_vendored_agents.py tests/test_agents_design_launcher.py`: passed.
- `PYTHONPATH=. UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD`: passed.
- `PYTHONPATH=. uv run --no-sync python scripts/check_commit_messages.py origin/main..HEAD`: passed.
- `npx --no-install commitlint --from origin/main --to HEAD --config commitlint.config.cjs`: passed.
- `git diff --cached --check`: passed before committing.

Tests use a simulated classifier to verify routing, instance affinity, authored-task handling and schema consistency. Real-model classification accuracy and end-to-end deck generation have not been tested for this revision.

Risk and rollback: new tasks that previously matched keywords now require a classifier call, adding latency and API usage. Classification can still choose the wrong implementation. No credentials or permissions change. Revert this change to restore keyword routing.

## Type of change

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

## Related issues (if there is)

N/A

## Checklists

### Development

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

Real-model classification and end-to-end generation were not tested, so the application-level checkbox remains open.

### Security

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

### Code review

- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [ ] Merge request linked to JIRA ticket when applicable

No related JIRA ticket was supplied. This change does not alter the UI.
2026-09-10 16:44:36 +00:00
0xKT
139110d9e0 refactor(config): the sub-agent name vocabulary seats below both sides
## Summary

`raven.config` and `raven.agent` imported each other. config validated sub-agent
declarations against tables living in `raven.agent.subagent`; the agent package
reads config for its shapes and paths. Both sides deferred their import into a
function body to keep module init off the cycle, which is what kept it invisible
to everything except a graph walk.

The validation needs the **vocabulary**, not the behaviour: which names are
legal, never what those names run. Only membership was ever read at the two call
sites -- `command`, `description`, `kind` and `readyTimeoutMs` were not. So the
names move down to `raven/config/agent_names.py` and the tables stay where they
are:

- **config owns what is legal** -- `BUILTIN_AGENT_NAMES`, `LEGACY_AGENT_ALIASES`,
  `THIRD_PARTY_PRESET_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`.
  Pure data and pure string functions, no IO.
- **`raven.agent.subagent` owns what it does** -- the preset table with its
  commands, transports and timeouts is untouched.

`builtin_agents` re-exports the moved names, so its eight consumers (`registry`,
`rpc.methods.subagents`, `manager`, `spawn_tool`,
`context_engine.segments.identity`) are not touched at all.

### Why the check did not move up instead

Moving the validation later, rather than moving the data down, would also break
the cycle and would cost nothing in cohesion. It was rejected because the check
is deliberately at parse time. It runs as a `@model_validator(mode="after")` on
all three sub-agent transports, on both paths that build a model from a dict
(`load_config` reading the file, and `update_subagents` validating before an
atomic write). Its own docstring names what it catches: a hand-edited
`preset: "hermes"` on an unrelated entry, which would otherwise both dodge the
reserved-name guard and hide the real Hermes preset from the Presets group.
An invalid row would become constructible, and every later reader would treat it
as valid.

### The cost, and the pin

The split spells one name set in two places. A preset added to
`THIRD_PARTY_SUBAGENT_PRESETS` without its key added to the vocabulary would ship
and then be refused by the schema meant to accept it, with nothing reporting the
mismatch. `tests/test_subagent_name_vocabulary.py` pins both sets equal in both
directions, and does the same for the seed table against the reserved names.

## Type

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

## Verification

```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.

$ uv run --frozen --python 3.12 pytest \
    tests/test_subagent_name_vocabulary.py tests/test_subagent_builtin_agents.py \
    tests/test_update_subagents.py tests/test_subagent_registry.py \
    tests/test_subagent_acp.py tests/test_rpc_subagents.py tests/test_kernel_closure.py -q
350 passed in 13.91s

$ uv run --frozen --python 3.12 --extra dev ruff check <the five changed files>
All checks passed!

$ uv run --frozen --python 3.12 --extra dev ruff format --check <the five changed files>
5 files already formatted

$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```

Both the contract run and the test run above were repeated after rebasing onto
the current main, since this one touches production code.

Every call site of every moved symbol was enumerated before the edit
(`BUILTIN_AGENT_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`,
`GENERIC_AGENT`, `LEGACY_AGENT_ALIASES`, `THIRD_PARTY_SUBAGENT_PRESETS`) and the
re-export is what keeps them all valid.

Effect on the dependency graph, measured before and after:

```
config -> agent edges          2  ->  0
packages in an import cycle   22  ->  19   (out of 40)
mutually importing pairs      14  ->  13
```

The three packages that leave the cycle were only ever pulled in through this
one pair.

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

No user-facing surface changes.

## Risk

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

No behaviour change: the same names, the same validation, the same failure
messages. The reserved-name guard and the preset provenance check both still run
at parse time on all three transports. Backward compatibility is why
`builtin_agents` re-exports rather than relocating its public surface, and why
`LEGACY_AGENT_ALIASES` moves intact -- stored records under the old lowercase
name still resolve.

Rollback is reverting the one commit. The risk this leaves behind is the
two-spellings drift, which is why the equality pin ships in the same commit
rather than as a follow-up.

## Related Issues

N/A
2026-09-10 16:19:11 +00:00
gloryfromca
aa026fd566 refactor(config): the sub-agent name vocabulary seats below both sides
## Summary

`raven.config` and `raven.agent` imported each other. config validated sub-agent
declarations against tables living in `raven.agent.subagent`; the agent package
reads config for its shapes and paths. Both sides deferred their import into a
function body to keep module init off the cycle, which is what kept it invisible
to everything except a graph walk.

The validation needs the **vocabulary**, not the behaviour: which names are
legal, never what those names run. Only membership was ever read at the two call
sites -- `command`, `description`, `kind` and `readyTimeoutMs` were not. So the
names move down to `raven/config/agent_names.py` and the tables stay where they
are:

- **config owns what is legal** -- `BUILTIN_AGENT_NAMES`, `LEGACY_AGENT_ALIASES`,
  `THIRD_PARTY_PRESET_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`.
  Pure data and pure string functions, no IO.
- **`raven.agent.subagent` owns what it does** -- the preset table with its
  commands, transports and timeouts is untouched.

`builtin_agents` re-exports the moved names, so its eight consumers (`registry`,
`rpc.methods.subagents`, `manager`, `spawn_tool`,
`context_engine.segments.identity`) are not touched at all.

### Why the check did not move up instead

Moving the validation later, rather than moving the data down, would also break
the cycle and would cost nothing in cohesion. It was rejected because the check
is deliberately at parse time. It runs as a `@model_validator(mode="after")` on
all three sub-agent transports, on both paths that build a model from a dict
(`load_config` reading the file, and `update_subagents` validating before an
atomic write). Its own docstring names what it catches: a hand-edited
`preset: "hermes"` on an unrelated entry, which would otherwise both dodge the
reserved-name guard and hide the real Hermes preset from the Presets group.
An invalid row would become constructible, and every later reader would treat it
as valid.

### The cost, and the pin

The split spells one name set in two places. A preset added to
`THIRD_PARTY_SUBAGENT_PRESETS` without its key added to the vocabulary would ship
and then be refused by the schema meant to accept it, with nothing reporting the
mismatch. `tests/test_subagent_name_vocabulary.py` pins both sets equal in both
directions, and does the same for the seed table against the reserved names.

## Type

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

## Verification

```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.

$ uv run --frozen --python 3.12 pytest \
    tests/test_subagent_name_vocabulary.py tests/test_subagent_builtin_agents.py \
    tests/test_update_subagents.py tests/test_subagent_registry.py \
    tests/test_subagent_acp.py tests/test_rpc_subagents.py tests/test_kernel_closure.py -q
350 passed in 13.91s

$ uv run --frozen --python 3.12 --extra dev ruff check <the five changed files>
All checks passed!

$ uv run --frozen --python 3.12 --extra dev ruff format --check <the five changed files>
5 files already formatted

$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```

Both the contract run and the test run above were repeated after rebasing onto
the current main, since this one touches production code.

Every call site of every moved symbol was enumerated before the edit
(`BUILTIN_AGENT_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`,
`GENERIC_AGENT`, `LEGACY_AGENT_ALIASES`, `THIRD_PARTY_SUBAGENT_PRESETS`) and the
re-export is what keeps them all valid.

Effect on the dependency graph, measured before and after:

```
config -> agent edges          2  ->  0
packages in an import cycle   22  ->  19   (out of 40)
mutually importing pairs      14  ->  13
```

The three packages that leave the cycle were only ever pulled in through this
one pair.

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

No user-facing surface changes.

## Risk

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

No behaviour change: the same names, the same validation, the same failure
messages. The reserved-name guard and the preset provenance check both still run
at parse time on all three transports. Backward compatibility is why
`builtin_agents` re-exports rather than relocating its public surface, and why
`LEGACY_AGENT_ALIASES` moves intact -- stored records under the old lowercase
name still resolve.

Rollback is reverting the one commit. The risk this leaves behind is the
two-spellings drift, which is why the equality pin ships in the same commit
rather than as a follow-up.

## Related Issues

N/A
2026-09-10 16:19:10 +00:00
TongLi31
2eb13a22a2 feat(agents): migrate raven-code tools and coding guidance
## Summary

Raven-Code gains a product-owned coding tool set and engineering guidance. The code-flow plugin supplies read_file, write_file, edit_file, list_dir, glob, todo, and exec through the host's existing plugin interfaces. It adds long-line read limits, explicit non-overlapping occurrence edits, Python syntax feedback, brace globbing with visible partial/error results, persistent checklists, and execution timeout/output reporting. All implementation changes are under agents/raven-code; raven/, other agent implementations, and both UIs have no diff.

Read-before-edit checks use records isolated by Raven-Code runtime and conversation. A successful read or full write establishes a record; appending to unseen or stale existing content does not grant editing permission. Fresh ACP sessions have distinct keys and separate records/checklists. Resuming an existing session restores its plan, and session deletion clears its product state. Tool binding covers user and subagent turns, including runs with flow guidance disabled.

Repository AGENTS.md, CLAUDE.md, and CONTEXT.md enter system context through Raven-Code's existing before_iteration hook. User queries, persisted transcripts, and /new and /help command handling stay intact. Each candidate is resolved and read only if it remains inside the resolved working directory, including absolute names, parent traversal, and symlink targets. Contained aliases are read once. The hook preserves the host system prefix, replaces its own addition on repeated iterations, and sizes it against the remaining prompt allowance with tools, pending checklist restoration, and the active model's reply ceiling counted. Truncation is explicit. The product uses existing hook and observer interfaces; no shared runtime extension or new command interception is added. The launcher seeds model-specific coding conduct, independently switchable engineering discipline, the product identity, and tool guidance. Untouched managed prompt copies refresh across upgrades while operator edits are preserved. Workspace and execution settings follow host configuration, including when rendering an already rendered configuration. One-shot CLI hosting defaults permissions to full because it cannot answer approval prompts; explicit permission configuration wins, and ACP hosting keeps the host default.

Completion verification gates and the code-verifier plugin are outside this change.

## Type

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

## Verification

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

- `uv run --frozen --python 3.12 --extra dev pytest tests/test_agents_code*.py tests/test_agent_hook*.py tests/test_context_engine_factory.py tests/test_kernel_budget.py tests/test_agents_research_tools.py tests/test_contracts_two_tier_ledger.py tests/test_l4_entrances.py tests/test_core_runtime_swap.py tests/test_acp_methods.py tests/test_context_scent.py tests/test_skill_hub_policy.py -q --tb=short`: 723 passed after rebasing onto current main. Coverage includes real ACP session creation and product-state isolation, real AgentLoop command dispatch and model-visible message roles, repository containment, user/subagent and concurrent-session binding, append behavior, permission propagation, tool schemas, prompt migration, and runtime contracts. Ordinary text mentioning /new reaches the provider; only the host's exact command form takes its existing command branch. Hook tests cover repeated/deep-copied contexts, token limits, host-prefix preservation, and checklist failure isolation.
- `make lint-python`: passed, including Ruff formatting across 1,899 Python files.
- `uv run --frozen --python 3.12 lint-imports`: 9 contracts kept, 0 broken.
- `make check-large-files check-source-language`, `git diff --check origin/main...HEAD`, and `uv run --frozen --python 3.12 python scripts/check_commit_messages.py origin/main..HEAD`: passed.
- The title and description pass the repository's canonical PR checkers. No frontend sources, generated RPC artifacts, or dependency lockfiles changed. Rebase comparison preserves all eight commits; the only file touched by both the feature and intervening main changes is CONTEXT.md, in separate domain entries. Tests for main's updated skill policy are included above.

Earlier full-suite validation, before the final read-state, repository-instruction, and hook changes, used `uv run --frozen --python 3.12 --extra dev pytest -q --tb=short`. Clean main reported 20,241 passed, 6 failed, 20 errors, and 212 skipped. The candidate reported 20,392 passed, 7 failed, 20 errors, and 212 skipped on each of two runs. Both checkouts used Python 3.12.13 and identical versions of all 212 installed distributions. The 6 cron failures and 20 cron errors had identical test IDs. The additional failure differed between candidate runs:

- `test_a_thin_dataset_card_falls_back_to_the_metadata_the_table_needs`: an intermittent `KeyError: served_url` in unchanged research tooling. The module passed all 82 tests separately on both checkouts and in the final targeted run. A controlled main-only DNS response reproduces the symptom; the original failure's cause remains unconfirmed.
- `test_doctor_answers_where_the_memories_are`: the temporary-directory path caused terminal wrapping inside `mem-root`, breaking the unchanged assertion. The original test reproduces on main with a 30-character `--basetemp`; shorter paths pass on both checkouts.

The full suite was not rerun after the final read-state, repository-instruction, and hook changes, and is not claimed green. Validation ran on Linux; no macOS/Windows execution, live-model run, or prompt-cache cost measurement was performed.

## Risk

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

The workspace fence remains opt-in and uses the host's path enforcement. Read-before-edit is session-local editing discipline, not a file lock or an atomic concurrency guarantee. Runtime restart requires a fresh read. Full overwrite retains its existing behavior; reading before overwrite remains model guidance rather than a new hard restriction. The exec replacement is offered only when the configured sandbox backend is none; otherwise the host's exec remains active.

Automatic repository-instruction loading always enforces containment, independently of the optional file-tool workspace fence. Injection runs after host history selection and does not evict transcript messages to make room. If even the truncation/concurrency notice cannot fit beside the reply allowance, the turn reports insufficient context instead of making a model call. The added repository text is not promoted into the host's stable cache prefix. New tasks use new session IDs. The host's in-place /new command retains its session key and clears the transcript without clearing separate Raven-Code todo/read state. This existing command behavior is preserved; the product does not add refusal messages or a reset callback. Resuming a session intentionally retains its plan, and deleting it removes its saved plan. Large exec output is retained under the agent home's exec-output directory without a new TTL or count cap; files can be removed manually. Operator-edited prompt copies may require manual updates.

Set plugins.config.code-flow.tools.enabled to false to restore the host tool set. CODE_PROJECT_FILES=off disables repository instruction loading; CODE_CONDUCT=off and CODE_CONDUCT_DISCIPLINE=off control guidance independently. Reverting the change restores the previous product behavior.

## Related Issues

N/A
2026-09-10 12:42:53 +00:00