## Summary
The canonical failure sentence `Error calling LLM
(<category>[@<provider>]): <detail>` was built in eleven places and
bounded in none, and every reader treated it as a sentence for a person:
the gateway handed a channel the vendor's whole body (for an auth
failure that is a masked key and the account URL it was rejected for; a
rejected-request body can quote the prompt back and run past Telegram's
split), the loop wrote the same body into the marker the model reads on
its next turn and into `turn_ended.reason`, and cron (since #675) stores
it as the job's `last_error`. Only the one-shot CLI had a 200-character
cut and a per-category wording.
One constructor now builds the sentence (`canonical_llm_error` in
`raven/providers/base.py`) and cuts the detail to 200 characters after
the verdict has been taken, so a needle deep in a rejected-request body
still decides the category; the untouched body stays on the call record.
A category table (`llm_error_summary`) gives every bucket the classifier
can reach one sentence with no vendor text. `TurnFailed` gains an
in-process `reported` flag, set by the Lane when the runner worded the
failure itself, and the gateway's reply to a channel reads: a canonical
failure -> the category sentence; a reported non-canonical failure ->
its own words, bounded; a crash -> the canned sentence. The marker a
broken turn leaves is worded for its two readers: the model-facing text
names the category, `turn_ended.reason` keeps the provider's account for
whoever diagnoses it. A crash's text is bounded by a kernel-local
constant so `raven.spine` still imports nothing from `raven.providers`.
Folded in: the cut-stream exit in `streaming.py` now spends the
verdict's retryability when a thought had already reached a wired
reasoning callback (the rule the exits beside it hold since #673), and
the gateway pops a read-back conversation's stored reply on every exit
so a failed cron run cannot hand its submitter the previous run's text.
This reverses the choice #666 made to send a channel the provider's own
sentence.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_error_classification.py tests/test_gateway_spine.py tests/test_agent_loop_broken_turn.py \
tests/test_cli_agent_commands.py tests/test_agent_loop_stream.py tests/test_agent_loop_llm_error_patience.py \
tests/test_spine_scheduler.py tests/test_spine_scheduler_lane.py tests/test_core_cron_stack.py tests/test_spine_events.py -q
uv run pytest tests -q --ignore=tests/integration
uv run ruff check . && uv run ruff format --check . && uv run lint-imports
```
Live check with an isolated agent home, `raven serve` and a
playwright-driven page, against local fake endpoints. (1)
OpenAI-compatible endpoint answering 401 with a masked key and the
account URL: `raven agent -m hi` still prints the vendor reason and the
`Fix:` line and exits 1; the page shows the red failed-turn row; the
persisted `turn_ended.reason` is exactly 200 characters ending in `...`
(this failure raises, so it takes the crash path and gets the kernel
bound). (2) The same endpoint answering 500 with a 5000-character body:
the persisted reason is again 200 characters. (3) Anthropic Messages
endpoint that streams two text deltas and then sends an `error` event
with a 5000-character message (an error response, so the canonical
path): the page row reads `Error calling LLM (server@anthropic):
overloaded_error: Overloaded: ...`, `turn_ended.reason` is the head plus
200 characters of detail (238 in total), and the model-facing marker
text reads `(turn failed: The provider returned a server error
(anthropic). The runtime log has the provider's own account.)`. (4) The
same endpoint cutting the stream without a terminal event: the row reads
the unchanged short canonical sentence. The channel reply is covered by
tests/test_gateway_spine.py, which drives a real DeliveryHub through a
fake channel.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
(CONTEXT.md entries updated in this change; no user-facing doc describes
channel error wording)
## Risk
- A channel reader gets the failure's category and endpoint (for example
`The provider rejected the credentials (openrouter). The runtime log has
the provider's own account.`) instead of the vendor's sentence; a
single-user deployment loses detail it could only get from the chat, a
group stops seeing key fragments and account URLs.
- Every canonical failure sentence is cut to 200 characters of detail
with a trailing `...`, on the page, in the TUI, in `turn_ended.reason`,
in cron's `last_error` and in the CLI line; the full body stays on the
call record and in the runtime log. A long `invalid_request` tail that
the page used to show in full is now cut.
- The marker text the model reads back after a failed turn names the
category instead of quoting the vendor; the model's visible history
changes.
- With a wired reasoning callback (web, TUI) a stream cut after its
thought is no longer retried by the loop's ladder unless
`llmRetryAfterOutput` is on.
- `TurnFailed` has a new in-process field; an out-of-tree consumer
constructing it positionally with five arguments would now set it.
- Rollback: the gateway commit alone restores the vendor sentence to
channels; the other commits stand on their own.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
Two halves of one incident, on 2026-09-20. A Raven-Design run (an ACP
sub-agent) stalled on its model stream; the parent conversation was told
`turn_failed (code -32099)` and nothing else, diagnosed it as an npm
crash and restarted the run. Behind that, the same run had written
58,675 `agent_thought_chunk` frames, one per reasoning token, averaging
5.7 characters. Every frame is a synchronous write plus flush on the
client's pipe, so when the client (the gateway, frozen by a synchronous
`find`, PR #566) stopped reading, the server blocked on that write too.
**Thought chunks are coalesced.** `UpdateTranslator` (the ACP server's
outbound sink, `raven/acp/updates.py`) now holds consecutive
`thinking.delta` updates per session and sends them as one
`agent_thought_chunk` when:
- a 200ms window closes (a loop timer, `THOUGHT_COALESCE_WINDOW_S`), or
- the held text reaches 512 characters (`THOUGHT_COALESCE_MAX_CHARS`),
or
- anything that has to follow them arrives: a chunk of the answer, a
tool call, a latch or an ending event, the session's release, the turn
slot being dropped, or the connection closing.
Order on the wire is kept: held text always precedes whatever released
it, and a delegated agent's thought (a different `_meta` target) never
joins the main agent's held text. The thresholds are measured, not
chosen: replaying the incident's frame log, 200ms/512 gives 4,333 frames
(13.5x fewer); a 100ms window gives 6,210; a 1,024-character cap changes
nothing (4,331), so the window is what does the work. The median gap
between consecutive thought frames in that log was 0.34ms, the p90 92ms.
`agent_message_chunk` (the answer itself) is not coalesced: a reader
watches it stream, and its frame count was 79.
**A failed turn names what failed.** (Second round: the class is
prefixed only when the message does not already open with it, so an SDK
error that names itself does not stutter; and `StreamIdleTimeoutError`
is classified by type, as `stream_idle_timeout`, before any substring
branch can read the budget in its message as a 429 or a 500.)
`Lane._run_turn` built `TurnFailed(error=str(exc))`, and `str()` of
asyncio's bare `TimeoutError` is empty, so the ACP translator's `_error`
had only the wire message to show. `describe_failure(exc)` now carries
the exception class and its message when it has one (`ValueError: boom`,
`TimeoutError`). And the stall itself is named at the source: the
per-chunk idle `wait_for` in `LiteLLMProvider.chat_stream` raises
`StreamIdleTimeoutError(idle=...)`, a `TimeoutError` subclass (so every
`except TimeoutError` arm and retry verdict keeps applying, the same
argument `FirstByteTimeoutError` makes) whose message reads `the model
stream sent nothing for 180s (bound stream_idle_timeout=180s)`.
Not changed: the frame writer is still a blocking write on the loop.
Fewer frames make the stall far less likely, they do not make it
impossible; moving the write off the loop would change the ordering
guarantee `UpdateTranslator`'s docstring states and is not attempted
here. The other providers' idle watchdogs (the Responses and Anthropic
SSE paths) still raise a bare `TimeoutError`; they now surface as
`TimeoutError` through `describe_failure` rather than as nothing, and
giving them the same message is a follow-up.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
At head b6097ead:
```
uv run pytest tests/test_acp_updates.py tests/test_spine_scheduler_lane.py tests/test_litellm_provider_timeout.py -q -n 0
# 233 passed
uv run pytest <24 test files across acp, spine, providers, rpc spine, subagent acp> -q
# 1048 passed (before the last test was added)
uv run pytest -q --ignore=tests/integration
# 23791 passed, 110 skipped at head b6097ead, in a throwaway worktree with COLORTERM=truecolor
make lint-python lint-imports lint-types lint-deps # all pass
make check-source-language check-large-files # exit 0 (COMMIT_RANGE=origin/main..HEAD)
```
Revert-to-red, each production file (pair) reverted to `origin/main` on
its own with the tests kept:
```
raven/acp/updates.py reverted 6 failed
raven/spine/scheduler.py reverted 2 failed
raven/providers/{first_byte,litellm_provider}.py reverted 1 failed
```
Mutation, each mutant applied alone, control restored between runs:
```
no flush before an update that must follow the thoughts 3 failed
window timer never armed 2 failed
512-character cap disabled 1 failed
different speakers merged into one chunk 1 failed
release_session keeps the held text 1 failed
close keeps the held text 1 failed
end_turn keeps the held text 1 failed (0 before the second commit added its test)
describe_failure drops the class name 2 failed
idle stall re-raised as a bare TimeoutError 1 failed
control (nothing mutated) 230 passed
```
Second round (267 tests across `test_acp_updates.py`,
`test_spine_scheduler_lane.py`, `test_error_classification.py`):
```
the three files reverted to the first-round head 4 failed
idle stall classified by substring 3 failed
describe_failure always prefixes 1 failed
settle_turn keeps the held text 1 failed
sliding window (timer re-armed per chunk) 1 failed
control 267 passed
```
The two guard clauses the first round's mutation pass showed could not
decide the flush (`or result.latch`, `or _ends_the_stream(event)`) were
dropped rather than tested; the comment says why.
One existing test changed: `test_reasoning_arrives_as_a_thought_chunk`
asserted a lone thought went out immediately; it now sends two thoughts
and an answer chunk and asserts one thought frame precedes the answer,
which is the ordering rule this PR adds.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (CHANGELOG
`Unreleased / Fixed`, two entries)
## Risk
User-visible behaviour changes:
- An ACP client sees reasoning text arrive in bursts of up to 200ms or
512 characters instead of per token, so the first thought token of a
turn arrives up to 200ms later than before. Answer text, tool calls and
endings are unchanged and never reordered relative to the thoughts that
preceded them.
- Every failure event (`error` on the wire, `turn_failed` in ACP) now
starts with the exception class, e.g. `ValueError: boom` where it read
`boom`. A client matching the old text exactly would need to match the
suffix.
- The mid-stream idle stall in the LiteLLM path raises
`StreamIdleTimeoutError` instead of a bare `TimeoutError`. It is a
`TimeoutError`, so `except TimeoutError` behaves as before;
`classify_error` names it `stream_idle_timeout` (retryable, fallback)
where it used to say `network`, and `_NON_AUTH_HINTS` has no entry for
it, so the CLI renders its error line alone, as it does for
`first_byte_timeout`.
Rollback: revert the squash commit. No stored data or wire schema
changes; the coalescer is process-local state.
- [x] Security impact considered (held text is the model's own
reasoning, already on this channel; `redact` is applied where it was
before, in the failure text)
- [x] Backward compatibility considered (frame shapes unchanged and
schema-validated in the tests; exception hierarchy preserved)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## 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
## 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
## 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
## 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
## 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
## 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
## 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).
## 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).
## 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
## Summary
Reported as "deliver_files is broken". It is not: **the tool never ran.**
Every `deliver_files` call on one install was refused before dispatch -- five in a row in a single session -- and nothing was ever delivered:
```
Error: Invalid parameters for tool 'deliver_files': files should be array
```
What the model sent was the array, spelled as a string:
```json
{"files": "[{\"path\": \"...poster.png\", \"title\": \"...\"}]", "message": "..."}
```
`cast_params` already forgives that spelling for every scalar type -- `"3"` for an integer, `"true"` for a boolean -- and did not for arrays or objects, which are exactly the types a model is most likely to stringify.
## Type
- [x] Fix
- [ ] Feature
## The edge of the forgiving is the design
When the value is a string, try `json.loads`, and take the result **only if it is the type the schema asked for**. A string that is not JSON, or is JSON of the wrong shape, is returned unchanged so the validator still names the real problem -- the point is to widen what is accepted, not to swallow a type error.
**Nothing here can raise.** Turning "your argument has the wrong type" into a traceback would be worse than the refusal it replaces, so the parse is wrapped and failure falls through.
**A `type: "string"` field is never parsed.** JSON is ordinary text in a message body or a file's content, and replacing it would hand the tool something it never asked for. Two independent things prevent it today (the string branch returns before the parse is reached, and the parse only wins on a type match), which is why the case pinning it is a tripwire rather than a load-bearing assertion -- said so in its own docstring rather than left to look like coverage.
## Not just deliver_files
Six built-in tools declare an array or object parameter and were all exposed:
| tool | parameter |
|---|---|
| `deliver_files` | `files` |
| `ask_user` | `questions` |
| `image_generate` | `images` |
| `message` | `media` |
| `create_playbook` | `skills` |
| `video_generate` | `params` |
The same failure was already seen from the other side: `acp_client/acp_agent.py` records `update_task_state` and `operations should be array` from a real dispatch.
## Verification
```
make lint-python ruff check + ruff format --check, 1850 files
make lint-imports 9 contracts kept, 0 broken
pytest tests/ 19,699 passed, 7 failed (all pre-existing, see below)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots -- no user-facing string
**End to end, through the real tool**, with the exact payload that failed five times in production:
```
files sent as: str -> [{"path": ".../poster.png", "title": "..."}]
returned: Delivered 1 file(s): poster.png (72 B).
still "should be array": False
registered in the store: True
```
Twelve cases, five mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the whole branch (the old behaviour) | 3 |
| raise instead of falling through on a parse failure | 5 |
| accept the parse whatever type it yielded | 1 |
| do not re-cast the parsed value, so items are not cast | 1 |
| widen the tuple to include `string` | **survived -- unreachable** |
The last is worth stating rather than hiding: that mutation cannot change behaviour, because the `type == "string"` branch returns earlier and the type check would refuse the result anyway. I also tried moving the new block above that branch, alone and combined with widening the tuple, and neither reddens anything either. The invariant holds by construction; the case that documents it says so.
**Pre-existing failures, checked against the base.** 7 failed in the full run, all in `tests/test_security_network.py` (`test_a_redirect_to_a_dangerous_address_is_refused` and siblings). Running that file alone on this same tree gives 4 -- the count is order-dependent -- and the change touches only `raven/agent/tools/params.py` plus a new test file, neither of which `raven/security/network.py` imports. The failures are the box's resolver: it returns poisoned answers roughly half the time, which I measured separately (`en.wikipedia.org` came back as `2001::1` on 3 of 6 lookups). Not introduced here, and worth someone's attention on its own.
## Risk
- [x] Security impact considered -- widens what reaches a tool's own validation, not what bypasses it. A parsed value is still validated against the same schema, and a parse that yields the wrong type is refused exactly as before
- [x] Backward compatibility considered -- a call that worked before takes the identical path; the new branch is reached only by a `str` where an array or object is declared, which previously always failed
- [x] Rollback path is clear -- single-commit revert
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over `git diff origin/main...HEAD`.
- **1 (a write location moved)** -- nothing moved; a branch was added to an existing dispatch on `target_type`. Grepped every caller of `cast_params`: the registry is the only one, and it runs `validate_params` right after, which is the reader this affects.
- **2 (a value with several entry points)** -- the cast is the single funnel every tool argument passes through, which is why the fix belongs here and not in `deliver_files`.
- **3 (a guard)** -- checked both directions: what it wrongly lets through (JSON of the wrong type, non-JSON text -- both refused, with cases) and what it wrongly refuses (a real list, unaffected, with a case).
- **4 (tests)** -- five mutations above, one honestly reported as unreachable. Failing-ID sets diffed against the base rather than counts.
- **6 (stale text)** -- the module docstring enumerated what is coerced ("a string that should be an integer"); it now names arrays and objects too. Grepped the tracked tree for other statements of the rule: none.
- **9 (error handling)** -- the new path adds one way to end and it is caught: `json.loads` raises `ValueError` on bad text and `TypeError` on a non-string, and both fall through to the untouched value.
- **11** -- `git ls-files | grep -c node_modules` is 0; the commit-message gate was run, not eyeballed.
Not applicable, with reasons: **3b, 3c, 3d, 3e** (no tool schema produced, no state moved, one lane, no assertion lost its symbol); **4b, 4c, 4d** (no platform branch, no shell, no rendered number); **5, 5b** (no dependency; `json` is stdlib and already imported across this package); **6b, 6c** (no backup, no generated artifact); **7, 7b** (nothing on disk); **8** (no asset, no secret); **10** (no prompt text).
## Deliberately not fixed
The error text still ends with `[Analyze the error above and try a different approach.]`, and the model plainly did not -- it sent the same shape five times. A message naming the expected spelling (`files must be a JSON array, not a string containing one`) would give it something to act on. That is a change to the registry's error surface, affects every tool, and deserves its own argument.
## Moved from !594
Opened on a compliant source branch. AGENTS.md 2.1 asks for a 3-5 word snake_case description and the previous branch had seven; GitLab cannot change an existing merge request's source branch, so the change moves rather than the name.
Same commits, rebased onto `c2a9768f`. Both code findings from the review on !594 are already in them -- `RecursionError` caught with its regression case, and the implementation comment reduced to the two non-obvious reasons. Nothing else changed, so that review carries.
## Summary
Overhaul the interactive `raven trajectory` browser end to end, fixing
every
issue from real-terminal testing:
- Navigation: every screen opens with a help area under its title (page
purpose plus "[Key] function" hotkey hints, rendered in a new readable
help color). Esc walks one level up (action -> attempt -> session); on
the
top-level session screen Esc stays put and quitting is Ctrl+C only,
which
prints a single exit notice. Esc inside a running action cancels just
that
action through a dedicated exception at the action boundary, so the back
sentinel can never reach a conversion or the data layer; a cancelled
report keeps its pre-confirm bundle-and-pin side effects (the existing
declined-report contract). Back/Exit menu entries are gone; answered
prompts erase themselves and navigation is echoed as breadcrumb lines
with markup-escaped untrusted text.
- Tables: the session list is TITLE | ATTEMPTS | LAST ACTIVITY and the
attempt list is # | STARTED | TURNS | SPANS | VERDICT | PIN | MERGED |
PREVIEW with green check cells. Time cells keep the year. The layout is
budgeted per screen build from the live terminal width (row indent, a
safety margin, and inter-column gaps are all part of the math); PREVIEW
drops as a whole column when it no longer fits, and below the dynamic
minimum width the tightest layout is kept while the renderer clips
overlong lines at the terminal edge. Every dynamic cell passes a
single-line sanitization gate before width math (verdict sidecars only
guarantee a non-empty string), cells are measured and truncated by
terminal display width (CJK is 2 cells), and fixed column widths always
fit their headers.
- Space preview: Space on an attempt row prints that attempt's per-turn
input/output previews, collected in the same snapshot scan and sorted by
a fully-stringified key so ordering never follows log source order (the
table PREVIEW cell derives from the same sorted collection). Any key,
arrow keys included, returns with the cursor kept on the row; the waiter
passes the terminal's CPR reply through to the renderer instead of
treating it as a keypress, and Ctrl+C keeps the browser-wide cancel.
- Merge hotkey: with two or more attempts, m/M opens the multi-select
merge
(advertised in the help line; the old "Merge attempts" menu entry is
gone). The checkbox screen carries its own help line for toggle,
confirm,
and cancel. A single attempt neither binds nor advertises the key.
- Theme and feel: new success (green check) and help (readable hint
text)
colors in both palettes, all WCAG AA on their backgrounds; a lone ESC is
flushed after 50ms instead of prompt_toolkit's 0.5s default, removing
the
laggy Esc feel.
The data layer is untouched: changes are confined to
raven/cli/trajectory_browse.py, raven/cli/_theme.py, and their tests.
The
id-taking subcommands (raven trajectory save/list/...) behave as before.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `COLORTERM=truecolor uv run pytest tests/test_cli_theme.py
tests/test_cli_trajectory_browse.py
tests/test_cli_trajectory_commands.py -q` -> 220 passed
- `COLORTERM=truecolor uv run pytest tests/ --ignore=tests/integration
-q` -> 6917 passed; the 10 failed + 20 errors are the pre-existing
environment-dependent set, identical file-by-file on a clean main
checkout (cron, everos server, config loader, tracing viewer)
- `uv run ruff check` and `uv run ruff format --check` on the four
touched files -> clean
- PTY smoke on a CPR-answering pseudo terminal at 100 and 58 columns:
full flow (preview, merge cancel, action screen, staged Esc backout,
Ctrl+C quit) and the narrow-width degradation contract
- New coverage includes real pipe-input key-binding tests (Esc on all
four prompt kinds, Space/m/M hits, waiter key paths with CPR
pass-through), table budget/clipping boundaries at the computed minimum
width, and corrupt verdict/timestamp corpora
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- The interactive browser's look and key protocol change wholesale (that
is
the point of this PR): Esc no longer quits from the top level (Ctrl+C
does), Back/Exit entries are gone, and lists render as tables. The
machine-facing subcommands and the trajectory data layer are untouched.
- Rollback: revert the squash commit; the browser returns to the
previous
interaction wholesale, no data migration involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## Summary
A DAG node that reports it could not accomplish its task suspends and asks the agent what
to do. Until now the answer could only be `continue` (send a correction and let the node
retry) or `abandon` (fail it and skip its dependents). Both keep the graph the agent
committed to at dispatch. When the plan itself is what turned out to be wrong, neither
helps: the agent's only recourse was to cancel the run and submit a fresh graph, which
throws away every node that had already succeeded.
This adds a third decision, `replan`. The agent hands `resolve_dag_node` a replacement node
list, the run being answered winds down, and a new run starts from that list, referencing
the wound-down run's completed nodes by id.
**Chained runs, not an in-place splice.** Node ids are claimed per conversation at
`store.init`, and every read-back path takes a run's structure from its `graph.json`.
Splicing would have to claim ids mid-run, rewrite that file into a cumulative graph, and
keep dropped nodes in it so they do not vanish from the record. Chaining instead lands on
the cross-run reference machinery that already exists for naming an earlier run's completed
node, and leaves both runs individually readable.
Decisions a later reader will want the reasons for:
- **A completed node is referenced, never re-declared.** Name it in `depends_on` and read it
with `{{ <id>.output }}`. Its id belongs to the old run permanently, so re-declaring it is
refused.
- **The adjudicated node is given up on.** No attempt budget crosses runs, because carrying
one would require node identity to span ids that must differ.
- **In-flight nodes are cancelled, not drained.** A replan is a statement that the remaining
plan is wrong; letting nodes finish work the new graph does not want spends dispatches on
output nobody reads.
- **A replan ends the adjudication round for every node suspended alongside it**, answered or
not. Several nodes can be waiting for the agent at once, and a sibling's answer can no longer
change a graph that is being replaced. Waiting for one is not merely wasted: on a run bound to
a live turn the wait carries no deadline, and the lane that would answer the sibling is the
same one parked in `resolve_dag_node` waiting for this run to finalize, so both wait without a
bound. Nodes left unanswered are recorded as superseded rather than as having timed out --
they were never asked.
- **The successor passes the same preflight a submitted graph does** -- the confirmation gate
and the hourly dispatch charge included. A replan therefore costs one unit of the same
hourly quota, and if the original graph was confirmed by the user, so is its successor.
- **No replan cap.** The hourly dispatch quota is the only mechanical bound; see Risk.
Persistence keeps the two runs separate. The successor is saved as its own run with its own
directory and `graph.json`; the run it replaces gains a reserved `replan` key on its own
`graph.json` recording the decision, the successor's id, and whether it started. An
interrupted hand-off is recorded as started `false` with a reason, so a reader never sees
nodes pointing at a successor the file does not admit was attempted.
Both front ends learn about the link through a new `dag.run_replanned` wire event. It is
emitted the moment the desk accepts the decision, before the answered run is awaited. That
timing is forced by the two front ends disagreeing: one pins a run's state by id and keeps
it, so a link arriving at any time lands; the other resolves a card through a live index
keyed by run id and drops that entry when the run completes. An event emitted after the
successor starts arrives after that drop and resolves to nothing, while a unit test that
never plays those frames passes -- code that looks done and does nothing. The durable record
still waits for the outcome: a live hint may be optimistic, an audit may not.
Design and the decisions behind it are in `docs/specs/2026-09-04-dag-replan-design.md`,
including a "deliberately out of scope" section.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on the rebased tree, at the head this description is written against.
- `make test-python` -- 18711 passed, 1 failed, 67 skipped, in 188.18s.
The one failure is `test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
which this branch does not touch and does not cause; see Risk for how that was established.
- `make lint-python` -- clean (ruff check and ruff format --check).
- `make check-source-language` -- clean.
- `make check-large-files` -- clean.
- `npm run type-check --prefix ui-tui` -- clean.
- `npm test --prefix ui-tui -- dagRun.test` -- 24 passed.
- `npm test --prefix ui-web -- src/features/transcript` -- 130 passed.
- `npm run lint:i18n --prefix ui-tui` -- generated catalogue up to date.
- The four suites exercising the changed code, run together under xdist as CI runs them:
438 passed.
Every new guard was sabotage-verified rather than assumed: the change it exists to catch was
reintroduced, the test was watched to go red with the assertion it was written for, and the
source was restored byte for byte. That includes the three defects found only by reviewing the
branch whole, after every individual task had passed its own review -- a replan landing while
the runner was parked was recorded as an abandonment, a foreground run whose turn had been
released announced its own wind-down as a raw dataclass, and a replan left the round waiting on
the siblings it had just made irrelevant.
The last of those has no deadline in the code under test to end it, so its regression drives the
real wait under `asyncio.timeout` and fails on the clock rather than hanging the suite: without
the guard, `TimeoutError` in 5.98s.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
**Behaviour change, opt-in.** `resolve_dag_node` gains a `replan` value and a `nodes`
parameter. The two existing decisions are untouched, and a caller that never sends `replan`
sees no change. Rolling back is reverting the branch: nothing migrates, and a `graph.json`
carrying a `replan` key stays readable to every reader of that file, all of which read named
keys rather than iterating.
**A replan chain is bounded only by the hourly dispatch quota.** That was deliberate -- a
count cap would have to guess how many corrections a task deserves. Each hop costs one unit
of the same quota a fresh graph costs, and each writes its own run directory, so a long
chain leaves one directory per hop with no TTL and no reclaim path. That matches how run
directories already accumulate; it is not made worse per run, only reachable more often.
**Known gaps, deliberately not closed here.** The bound foreground lane's silence is now an
explicit check rather than an eviction accident, but has no test -- reaching it needs a
released tray and a foreground turn to release it. The link record is written after the
successor is submitted or refused as invalid, so a cancellation raised inside the submission
still escapes both guards; the remaining window is documented where it happens.
`prepare_replan` refuses a graph that fails validation, but a backend IO error or a
non-object `graph.json` propagates rather than refusing cleanly -- no state is corrupted,
since that runs before the node is answered and the node stays waiting. The successor does
not draw under the tool row that spawned it in the web UI, for the reason given in the spec's
out-of-scope section; the link event still lands, so the replan itself is visible.
**The one failing test is not this branch's.** Established two ways rather than asserted:
every input it reads is byte-identical to the base
(`git diff --stat origin/main...HEAD -- raven/cli/ raven/config/ tests/test_cli_doctor_commands.py`
is empty), and the failure is console width plus path length, not code. Under xdist at the
default width it fails; serially at the default width it passes; under xdist with
`COLUMNS=200` it passes. xdist inserts a worker directory into the temp path and narrows the
captured console, and between them rich wraps the path across the substring the assertion
looks for.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
A DAG node that reports it could not accomplish its task suspends and asks the agent what
to do. Until now the answer could only be `continue` (send a correction and let the node
retry) or `abandon` (fail it and skip its dependents). Both keep the graph the agent
committed to at dispatch. When the plan itself is what turned out to be wrong, neither
helps: the agent's only recourse was to cancel the run and submit a fresh graph, which
throws away every node that had already succeeded.
This adds a third decision, `replan`. The agent hands `resolve_dag_node` a replacement node
list, the run being answered winds down, and a new run starts from that list, referencing
the wound-down run's completed nodes by id.
**Chained runs, not an in-place splice.** Node ids are claimed per conversation at
`store.init`, and every read-back path takes a run's structure from its `graph.json`.
Splicing would have to claim ids mid-run, rewrite that file into a cumulative graph, and
keep dropped nodes in it so they do not vanish from the record. Chaining instead lands on
the cross-run reference machinery that already exists for naming an earlier run's completed
node, and leaves both runs individually readable.
Decisions a later reader will want the reasons for:
- **A completed node is referenced, never re-declared.** Name it in `depends_on` and read it
with `{{ <id>.output }}`. Its id belongs to the old run permanently, so re-declaring it is
refused.
- **The adjudicated node is given up on.** No attempt budget crosses runs, because carrying
one would require node identity to span ids that must differ.
- **In-flight nodes are cancelled, not drained.** A replan is a statement that the remaining
plan is wrong; letting nodes finish work the new graph does not want spends dispatches on
output nobody reads.
- **A replan ends the adjudication round for every node suspended alongside it**, answered or
not. Several nodes can be waiting for the agent at once, and a sibling's answer can no longer
change a graph that is being replaced. Waiting for one is not merely wasted: on a run bound to
a live turn the wait carries no deadline, and the lane that would answer the sibling is the
same one parked in `resolve_dag_node` waiting for this run to finalize, so both wait without a
bound. Nodes left unanswered are recorded as superseded rather than as having timed out --
they were never asked.
- **The successor passes the same preflight a submitted graph does** -- the confirmation gate
and the hourly dispatch charge included. A replan therefore costs one unit of the same
hourly quota, and if the original graph was confirmed by the user, so is its successor.
- **No replan cap.** The hourly dispatch quota is the only mechanical bound; see Risk.
Persistence keeps the two runs separate. The successor is saved as its own run with its own
directory and `graph.json`; the run it replaces gains a reserved `replan` key on its own
`graph.json` recording the decision, the successor's id, and whether it started. An
interrupted hand-off is recorded as started `false` with a reason, so a reader never sees
nodes pointing at a successor the file does not admit was attempted.
Both front ends learn about the link through a new `dag.run_replanned` wire event. It is
emitted the moment the desk accepts the decision, before the answered run is awaited. That
timing is forced by the two front ends disagreeing: one pins a run's state by id and keeps
it, so a link arriving at any time lands; the other resolves a card through a live index
keyed by run id and drops that entry when the run completes. An event emitted after the
successor starts arrives after that drop and resolves to nothing, while a unit test that
never plays those frames passes -- code that looks done and does nothing. The durable record
still waits for the outcome: a live hint may be optimistic, an audit may not.
Design and the decisions behind it are in `docs/specs/2026-09-04-dag-replan-design.md`,
including a "deliberately out of scope" section.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on the rebased tree, at the head this description is written against.
- `make test-python` -- 18711 passed, 1 failed, 67 skipped, in 188.18s.
The one failure is `test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
which this branch does not touch and does not cause; see Risk for how that was established.
- `make lint-python` -- clean (ruff check and ruff format --check).
- `make check-source-language` -- clean.
- `make check-large-files` -- clean.
- `npm run type-check --prefix ui-tui` -- clean.
- `npm test --prefix ui-tui -- dagRun.test` -- 24 passed.
- `npm test --prefix ui-web -- src/features/transcript` -- 130 passed.
- `npm run lint:i18n --prefix ui-tui` -- generated catalogue up to date.
- The four suites exercising the changed code, run together under xdist as CI runs them:
438 passed.
Every new guard was sabotage-verified rather than assumed: the change it exists to catch was
reintroduced, the test was watched to go red with the assertion it was written for, and the
source was restored byte for byte. That includes the three defects found only by reviewing the
branch whole, after every individual task had passed its own review -- a replan landing while
the runner was parked was recorded as an abandonment, a foreground run whose turn had been
released announced its own wind-down as a raw dataclass, and a replan left the round waiting on
the siblings it had just made irrelevant.
The last of those has no deadline in the code under test to end it, so its regression drives the
real wait under `asyncio.timeout` and fails on the clock rather than hanging the suite: without
the guard, `TimeoutError` in 5.98s.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
**Behaviour change, opt-in.** `resolve_dag_node` gains a `replan` value and a `nodes`
parameter. The two existing decisions are untouched, and a caller that never sends `replan`
sees no change. Rolling back is reverting the branch: nothing migrates, and a `graph.json`
carrying a `replan` key stays readable to every reader of that file, all of which read named
keys rather than iterating.
**A replan chain is bounded only by the hourly dispatch quota.** That was deliberate -- a
count cap would have to guess how many corrections a task deserves. Each hop costs one unit
of the same quota a fresh graph costs, and each writes its own run directory, so a long
chain leaves one directory per hop with no TTL and no reclaim path. That matches how run
directories already accumulate; it is not made worse per run, only reachable more often.
**Known gaps, deliberately not closed here.** The bound foreground lane's silence is now an
explicit check rather than an eviction accident, but has no test -- reaching it needs a
released tray and a foreground turn to release it. The link record is written after the
successor is submitted or refused as invalid, so a cancellation raised inside the submission
still escapes both guards; the remaining window is documented where it happens.
`prepare_replan` refuses a graph that fails validation, but a backend IO error or a
non-object `graph.json` propagates rather than refusing cleanly -- no state is corrupted,
since that runs before the node is answered and the node stays waiting. The successor does
not draw under the tool row that spawned it in the web UI, for the reason given in the spec's
out-of-scope section; the link event still lands, so the replan itself is visible.
**The one failing test is not this branch's.** Established two ways rather than asserted:
every input it reads is byte-identical to the base
(`git diff --stat origin/main...HEAD -- raven/cli/ raven/config/ tests/test_cli_doctor_commands.py`
is empty), and the failure is console width plus path length, not code. Under xdist at the
default width it fails; serially at the default width it passes; under xdist with
`COLUMNS=200` it passes. xdist inserts a worker directory into the temp path and narrows the
captured console, and between them rich wraps the path across the substring the assertion
looks for.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Three seams an unattended agent needs, none of them deck-specific.
An outer retry ladder for a model call that comes back retryable after the provider's own seconds-long ladder gave up: `llmErrorRetryDelays` (default 15, 30, 60 seconds; an explicit `[]` turns it off) and `llmRetryAfterOutput`, which stays off so a person watching a stream never sees the words twice and can be turned on for a client that is a machine. One measured run had 62 minutes and 23.8M tokens of work behind it when a 40-second gateway outage ended the turn; another had two hours behind it when a mid-stream disconnect ended it with nothing published. The streaming path takes the same ladder, so a reconnect that fails past the first attempt no longer raises out of the loop.
A call refused for carrying too many image tokens is asked again with the images dropped rather than failing the turn: the newest image-bearing message first, then every one of them.
`read_file` names what a path is when it cannot be read (a URL, a host-like string, a directory), so a model that passed a link where a path belongs is told that instead of "no such file".
## Type
- [x] Feature
## Verification
`uv run pytest tests -q -k "llm_error_patience or agent_loop_stream or filesystem_tools or error_classification or two_tier_ledger or web_providers or dag_adjudication"` -> 180 passed. Full touched surface on this stack: 3603 passed, 9 skipped. `uv run ruff check raven/ tests/test_agent_loop_llm_error_patience.py` clean; pre-commit passed on the commit.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Defaults keep today's behaviour: the ladder is off for a stream that already produced output, and the image-stripping retry only fires on a refusal that names the image budget. `llmErrorRetryDelays: []` restores the old immediate failure. Rollback is reverting this commit; nothing else depends on the two new config rows.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
litellm stamps its default 500 on connect failures, so the status-code
server bucket claimed them first: a local apiBase typo read as
"provider-side error; retry later or switch models", pointing the user at
the wrong fix. The unambiguous connect indicators (class names plus
cannot-connect / connection-refused messages) now outrank the status
check, and the network hint names the provider apiBase alongside
connectivity. Recovery behaviour is unchanged -- both buckets retry and
fall back -- only the category and the hint move.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
Three more commits landed on the trunk during the review round, so the branch
stopped fast-forwarding again. Merged rather than rebased for the same reason as
before: a rebase flattens the v0.1.12 merge commit and costs the ancestry this
whole branch exists to establish.
One conflict, additive: tests/test_cli_gateway_commands.py had a _risk_banner
group added on this branch and a gateway-shutdown ordering test added on the
trunk. Both kept.
ui-tui/src/rpc/generated.ts merged automatically. Since it is a generated file,
its result was checked rather than assumed: `npm run lint:rpc` reports it in sync
with rpc-schema/openrpc.json, which merged alongside it.
Verification:
uv run pytest 9018 passed, 33 skipped, 13 deselected
uv run ruff check all checks passed
uv run ruff format --check 1022 files already formatted
npx vitest run 99 files, 1265 tests passed
npx tsc --noEmit clean
npm run lint:rpc schema and codegen in sync
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Installing one of the sub-agents that ship under `subagents/` required a running
raven: each folder's `install.py` registered its entry through
`PUT /raven/subagents`, so both the web service and the gateway had to be up. On a
machine that has just cloned the repository, neither is.
The installer now writes `subagents.thirdParty` in the host raven's config
directly, through `raven.config.update_subagents` - the supported write path,
which validates the entry against the schema, replaces the entry sharing its name,
refuses a list that would hold duplicates, and replaces the file atomically. Hand-editing the JSON gets none of that, and a
half-written config is one raven will not start on. That module is importable only
from the host raven's environment, which is rarely the interpreter running the
installer, so it is reached in a subprocess resolved from the shebang of `raven`
on `PATH` (or `RAVEN_PYTHON`, or `--raven-python`). The installer therefore stays
standard-library only and runs under a bare `python3`.
What the file write costs is hot-apply: a running raven holds the roster it read
at startup, so the installer prints a restart instruction and the guide says the
same. `--endpoint` is gone; `--config` and `--raven-python` are new.
Two additions on top:
- `subagents/install.sh` does the whole install for every folder, or the ones
named: builds each checkout's venv, scaffolds `.env` from its template, then
registers. It refuses to register a folder whose api key is still blank, so a
half-configured agent never reaches the roster, and exits non-zero while
anything still needs attention. It discovers the checkout by its lone
`pyproject.toml` and derives the key prefix from the folder name, so a new
folder needs no edit in the script.
- `subagents/README.md` is the directory-level guide: what a folder is made of,
the install steps, what the installer does and does not do, how to remove an
agent, what a new folder has to satisfy, and what never gets committed.
`subagents/*` stays excluded by default. Only the folders that were already
tracked are whitelisted, plus those two new files by name; a folder holding a
docker image tar or a private checkout is unaffected. The change also drops a
sentence that pointed a published README at an unpublished sibling folder.
The pre-install backup is written before the config is touched, holds the list as
it sits on disk rather than a schema round-trip of it (loading coerces an `openai`
entry's `readsLocalFiles` away, so a validated copy would restore something the
user never wrote), and is at mode 600 because another entry among the others can
carry its own api key. A backup that cannot be written stops the install with the
config untouched, rather than going missing after a config that already changed.
`install.sh` reads the api key the way the launcher does, first non-empty match
wins, so the two cannot disagree about a `.env` that sets it twice. It expands its
argument array through `${args[@]+...}`, since an empty array under `set -u` is an
unbound-variable error before bash 4.4 - the stock `/bin/bash` on macOS. A relative
`--config` is made absolute at parse time, because `install.py` runs with each
folder as its cwd and would otherwise resolve the path once per folder.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
The branch touches 12 files: `.gitignore` and 11 under `subagents/`. Nothing under
`raven/` or `tests/`, and `testpaths = ["tests"]`, so no unit test collects any of
it.
```
uv run pytest -q 8237 passed, 46 skipped, 13 deselected in 170s
uv run ruff check --no-force-exclude subagents/raven-code/install.py All checks passed
uv run ruff format --check --no-force-exclude subagents/raven-code/install.py 1 file already formatted
bash -n subagents/install.sh clean
python3 scripts/check_commit_messages.py origin/main..HEAD exit 0
python3 scripts/check_large_files.py origin/main..HEAD exit 0
```
`subagents/` is excluded in `[tool.ruff] extend-exclude`, so the two ruff commands
above need `--no-force-exclude` to reach the file at all.
End-to-end on a freshly provisioned host with no `raven`, no `uv`, and Python 3.10:
cloned the repository, installed `uv`, built the venvs, ran the installer twice and
spawned one agent for real.
- Installer on a clean clone with no keys: three checkout venvs built, three `.env`
files scaffolded at mode 600, stopped at the key gate for all three, exit 1. The
host config's mtime was unchanged and no backup file was written, so nothing
half-configured reached the roster.
- Same host with keys filled in: all three entries `replaced` in a config that
already held 8 third-party sub-agents, and all 8 survived. Each backup was mode
600 and held the full 8-entry list. `load_config()` then listed all 8, so the
written entry is valid to the runtime and not only to the writer.
- The resolved `command` of each entry pointed at the clone's own path, confirming
the placeholders resolve against the installer's location rather than the machine
that built the folder.
- One real spawn answered correctly in 22s.
- Before that, on a machine with no `raven` on `PATH`, the installer reported
`no raven on PATH; pass --raven-python ...` and recorded the folder as failed.
Probes for the fixed defects: a config seeded with `readsLocalFiles: true`
on disk produced a backup recording `false` before the fix and `true` after; a
`.env` setting the key twice with an empty second line made the shell installer
refuse an agent the launcher would run, and both now agree; an interpreter stub
printing non-JSON now yields `cannot read the writer's output` instead of a
traceback; a `--config` whose parent is a regular file makes the config write fail
with the backup already on disk, which is what shows the backup precedes it; and a
run with no flags at all registers against a scratch `HOME`, which is the path the
empty-array expansion used to break on bash before 4.4.
Proving the backup ordering took two attempts. Making the folder unwritable with
`chmod 555` proved nothing, because this runs as root and root ignores mode bits -
a trap the repository's own skipped test records. The failing-config probe above is
the one that holds.
- [ ] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
The first box is deliberately unchecked: there is no unit test covering this tree,
because pytest does not collect it. The end-to-end run above is the evidence
offered in its place. The unit suite was run anyway, on the rebased tree, and
reported no failures at all - so there are no failing ids to diff against the
target branch.
## Risk
**Behaviour change.** An install no longer takes effect immediately. Anyone
following the old flow will see the agent appear only after raven or the gateway
restarts; the installer's last line and the guide both say so. `--endpoint` no
longer exists, so a caller passing it gets an argparse error rather than a silent
fallback.
**Not reproduced, environment-dependent.** On the test host, the provider's model
listing answered 200 while inference answered
`403 This model is not available in your region.`, which the launcher reports as a
run that exits 0 having committed no answer - it reads like a launcher bug and is
not one. Exporting the site proxy fixed it, and the guide now records both that and
the fact that a missing EverOS degrades rather than fails.
**Security.** The pre-write backup can contain another entry's api key, so it is
written at mode 600 and is covered by the existing ignore rules. Keys stay in each
folder's `.env` at mode 600; the tracked `config.json` files hold none. The
installer no longer sends the entry list over a loopback HTTP service.
**Rollback.** Revert the commit: the previous installer talked to the RPC and needs
nothing else restored. Entries already written stay valid either way, since the
schema did not change.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.12 becomes a real ancestor: the next sync starts from v0.1.12
instead of v0.1.11, and the eventual contribution back to GitHub can still tell
our commits from the upstream ones it already has.
Cost this round: 54 conflict hunks over 31 files, against 19 over 14 for
v0.1.11. The growth is ours, not upstream's -- 33 commits landed on the trunk in
the six days since the last sync, and they concentrate in the three files the
sync notes already name as hot (agent/loop/main.py, cli/tui_commands.py,
config/schema.py).
Notable conflict resolutions:
* agent/loop/streaming.py keeps our extracted stream_llm_call and grafts
upstream's one real addition into it: the truncation verdict
(upstream_finish_reason, flag_truncation, and the two LLMResponse fields).
Comparing function bodies against the merge base was what showed aclosing()
and the structured error classification were already there, not new.
* agent/loop/main.py splits an 87-line block that upstream left empty: two
helpers moved into upstream's new loop/failure_streak.py and had to go, four
with live call sites outside the block had to stay. Taking the block whole in
either direction was wrong.
* _dispatch_backend_store takes upstream's detached-task architecture and keeps
our memory-failure tracking inside the task body. The shared tail after the
hunk reads `e`, which upstream's `except Exception:` does not bind, and
drain_backend_stores already had three merged-in callers.
* context_engine/segments/render.py merges two dimensions into identity_text:
our work_dir split and upstream's routed model id. The shared body already
reads names from both sides.
* agent/tools/registry.py keeps both unparseable-argument mechanisms. They sit
at different layers on purpose -- RunMeta comes from a provider on the
non-streaming path, RAW_ARGUMENTS_KEY from the loop on the streaming one.
Nine breakages git merged cleanly and never flagged. This is the shape the
change fails in, and it is worth recording in full:
* The three vendored builds under subagents/ carry a copy of the pre-rename
raven/tui_rpc/ tree, so rename detection sent upstream's 50 lines of
tui_rpc changes into a dead copy instead of raven/rpc/. Only one of the four
files conflicted; the other three were silent.
* subagent/backends/raven_loop.py holds the tool loop we extracted from the
subagent manager, so upstream's run_meta argument never reached it.
* AgentDefaults.max_tokens: upstream dropped it for a dynamic
send_max_tokens(). Both make_provider sites merged onto the new scheme;
providers/resolving_provider.py did not, because upstream has no such file.
* ResolvingProvider never forwarded wire_model_id. Only upstream's own
invariant test catches that class, and the cost is a silently mis-sized
request (16384 against 4096 for one gpt-4o).
* CronService.add_job kept our body but took upstream's signature, losing
`deliver` from both the parameter list and CronPayload while two RPC methods
still pass it, and leaving a call to the _arm_timer scheme upstream replaced
with a wake Event.
* rpc/bootstrap.py still called make_on_cron_job positionally after the
signature narrowed.
* update_everos lost _EVEROS_CONFIG for a root-lookup family, and gained an
ownership gate over its write primitives.
* SessionInitInfo never declared config_notices, in the model or the schema,
while methods/session.py returns it and our own TUI already reads it through
a hand-written type intersection. Both are strict, so a config migration
would have made session.create fail validation in production.
* tests/test_skill_hub_tools.py keyed a fixture under the "local" router
namespace rather than a real registry layer, which upstream's new assertion
exists to refuse.
Also fixed while here: the rich Style cache poisoning that the ci branch
documents as a known crutch (one pinned color_system), and the coverage
baseline's 29 stale raven/tui_rpc/ paths. The baseline totals are still
upstream's own numbers and should be regenerated separately.
Verification, on macOS with a non-root runner:
uv run pytest 8888 passed, 33 skipped, 13 deselected
uv run ruff check all checks passed
uv run ruff format --check 1017 files already formatted
npx vitest run 99 files, 1265 tests passed
npx tsc --noEmit clean, TurnEvent exhaustiveness included
npm run lint:rpc schema and codegen in sync
make check-large-files exit 0
rpc-schema/openrpc.json is the source of truth here, so ui-tui/src/rpc/
generated.ts was regenerated rather than hand-resolved. Nothing under
subagents/ changed.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Adds direct chat with a sub-agent instance: talking to one of the instances a
session has spawned, without that exchange entering the main agent's context.
The TUI gets the feature end to end; the web UI then gets the same thing on the
same runtime.
**The runtime.** A direct turn runs on its own lane (`session#agent/handle`)
rather than the session's, so several instances answer at once while the main
agent keeps its own serial lane, and direct turns draw on a separate
concurrency pool so a user is never queued behind them. Direct turns are not
cancellable: `turn.cancel` keeps meaning the main agent's turn on both
surfaces. Each turn writes a record (`prompt.md` / `out.md` / `meta.json`), and
the main agent learns only that the exchange happened, through a handoff block.
**Sub-agent replies over ACP.** Three separate causes were losing most of a
reply. Raven answered every agent-initiated request with `method not found`,
including `session/request_permission`, and the codex adapter turns any error
from that request into a cancel -- so a turn died as soon as the agent asked to
run something. Raven now approves, choosing among the options the agent offered
by their protocol kind. A stop reason other than `end_turn` was returned as a
finished answer, so a truncated reply read as a complete one; it now carries a
notice. And several messages in one turn were joined with no boundary, so a
preamble, its tool calls and the answer ran together as one paragraph.
**Instance visibility.** A failed resume deleted the whole registry row, which
took the instance off the strip for the length of the turn recovering it, and
permanently if that turn failed; it now drops only the stale binding. A
capability snapshot whose fingerprint no longer matched was discarded, which
defaulted the agent to *stateless* -- editing an agent's `env` silently cost it
resume, its chip, and the `instance` parameter in the spawn schema. Its
capabilities are now kept and flagged, while its verdict is not, so the
`/subagents` row asks for a re-test.
**Working directory.** A direct chat was the one sub-agent dispatch that
supplied none, so it fell back to agent home and ran its commands against
raven's own memory instead of the user's checkout.
**The web UI.** Two wiring gaps came first, both silent: the browser's
dispatcher registered neither instance method, and the web channel never built
the map that tags an event with its addressee, so nothing a client could
demultiplex on was ever sent. The service then routes on that tag at the push
rather than at the read, because the main reply and a direct turn share one
subscription and two consumers on one queue would each swallow the other's
events -- including a `message.complete`, which would end the wrong turn. A
direct turn's events are published out of band; feeding them into the reply
stream is not an option, since that stream is one reply per turn.
Decisions and their measurements are recorded in `docs/specs/`. Notably, the
vendored AgentScope tree is *not* edited, which is a decision rather than an
omission: making a direct chat a real reply would mean re-keying a blocking
per-session lock that guards message storage and tool-call state as well as the
reply loop, and rendering reuse was obtained without it.
## Type
- [x] Feature
## Verification
- `uv run pytest -q` -- 8021 passed, 36 skipped. The one deselected failure,
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`, fails the
same way on `origin/main` in a clean worktree, so this introduces none.
- `uv run ruff check raven/ tests/ ui-webui/service/` -- clean;
`uv run ruff format --check` -- 957 files already formatted.
- Web service: `python -m pytest ui-webui/service/tests -q` -- 13 passed.
- Frontend: `pnpm lint` -- 0 errors, 18 warnings, each one also present before
this change; `pnpm build` -- succeeds; `tsc --noEmit` -- clean.
- Every fix here was checked by reverting it and watching its test go red. Two
tests that passed either way were rewritten after that check exposed them.
- End to end against a running gateway: a direct chat sent through the new web
route completed twice, each leaving a record whose `out.md` held the exact
reply asked for, and the history route returned those turns afterwards.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The last box is unchecked: the terms are defined in `CONTEXT.md` and the designs
in `docs/specs/`, but no end-user documentation or screenshots were produced.
## Risk
**Approving sub-agent permission requests is a widened trust boundary and the
main thing to review here.** An ACP sub-agent that asks to run something now
gets a yes, and the codex preset is configured for its most permissive mode --
wider than the `-a never` the cli transport used. It is unattended by
construction: a dispatch has no operator and no surface that could render a
prompt, so the alternatives were approving or refusing, and refusing leaves the
agent unable to do the work. Rolling back is per-agent config, or reverting
`raven/agent/acp/permissions.py` to restore the refusal.
Two known gaps, neither reachable today, both stated rather than fixed:
- The web UI's event consumer has no `target` guard of its own. The two
surfaces use disjoint session keys and the browser never sends a target, so a
direct turn cannot reach it; a caller that sent one on a `web:` session would
see a sub-agent's reply rendered as the main agent's. Fixing it would widen
this into unrelated files.
- Direct-chat record directories have no TTL and no count cap, like the spawn
and DAG trees beside them. Reclaiming them would also start deleting audit
trails that intentionally outlive session deletion, which is its own change.
Behaviour changes worth naming: a direct chat under a sandbox whose volumes do
not cover the working directory now fails where it used to run quietly in agent
home, matching what the main path already does; and a partial reply now carries
a `[raven]` notice, so anything parsing a sub-agent's reply verbatim sees it.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Stacked on the REPL retirement (#329); retargets automatically as the
chain merges. Provider authentication failures used to reach the user
as a raw exception dump - the exception class name printed twice, the
provider's JSON error body rendered as if it were the agent's reply,
the process exited 0, and the memory query-rewrite layer echoed the
same failure once more. A zero-credential first run pointed at hand
editing config.json and never mentioned the guided path.
Changes:
- Provider errors carry the existing error classification through to
the CLI instead of being stringified into content. The one-shot path
renders an auth failure as two lines (Error: API key invalid
(openrouter 401). / Fix: raven provider test openrouter or raven
onboard) and exits 1 via an exit-code seam that survives the
delivery-hub worker boundary, where a plain typer.Exit would be
swallowed.
- The raw JSON error body and the duplicated exception prefix are
stripped from the canonical message; the retry ladder and failover
semantics are untouched.
- The query-rewrite failure echo drops to debug (it already falls back
to plain retrieval).
- Both zero-credential raise sites in check_provider_credentials append
"Or run raven onboard for guided setup." to the existing remedy line.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_cli_helpers.py
tests/test_cli_agent_commands.py -x`: 48 passed.
- Full suite (no -x): 6232 passed / 2 failed, both pre-existing on main
(the image-block test and the order-dependent theme test).
- Live sandbox with a fake OpenRouter key (real 401): before - bare
exception double-write, JSON body, exit 0, rewrite warning; after - the
two-line message, exit 1, zero AuthenticationError occurrences.
Zero-config sandbox now prints the onboard line and exits 1.
- Each change landed only after a test reproducing the old behavior
failed against the unmodified base.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Scripts that relied on a zero exit code from a failed one-shot turn
will now see exit 1; that is the point of the fix. Revert the branch to
roll back.
## Related Issues
N/A - no tracked GitHub issues (internal v0.1.11 usability review).
---------
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.11 becomes a real ancestor: the next sync then starts from
v0.1.11 instead of the July fork point, and the eventual contribution back to
GitHub can tell our commits from the upstream ones it already has.
Notable conflict resolutions, 19 hunks over 14 files:
* providers/litellm_provider.py takes upstream's wire_model delegation. Both
sides had fixed the same gateway-prefix bug; upstream moved the logic into
providers/wire.py and deleted _canonicalize_explicit_prefix, so keeping our
call would reference a method that no longer exists.
* cli/onboard_commands.py takes upstream's three-way file split. Our only
change to that file was _NON_CREDENTIAL_CHANNEL_FIELDS, ported to its new
home in cli/onboard_channels.py.
* agent/loop/main.py keeps our stream reconnect loop and grafts upstream's
terminal error-delta handling into it; takes upstream's _route_result_images
helper, which also covers the no-vision case our inline version did not, and
keeps our read_skill/use_skill reporting; takes upstream's ordering that
routes before assembly, since assembly decides whether an attachment is
inlined as a picture, while keeping our per-session model override.
* agent/subagent/manager.py keeps our backend dispatch and spawn history, and
threads the provider/model pair spawn snapshots into backend.run so a live
/model switch reaches subagents. The SubagentBackend protocol gained the
pair as optional keywords, travelling per call for the same reason workspace
already does.
Three breakages git merged cleanly and never flagged:
* web_rpc/methods_config.py imported six EverOS symbols from onboard_commands,
which upstream moved to onboard_everos.
* tui_rpc/methods/turn.py passed a single directory to _resolve_path, whose
third parameter we had changed to a tuple. Left as it was, an attachment was
dropped in silence whenever restrict_to_workspace is on.
* config/schema.py carried a second configuredness rule next to the one
upstream routes through providers.auth, so routing bypassed the
endpoints-first check and read a flat key that no request would use. It now
delegates, with include_external for parity with list_providers.
Verification: uv run ruff check passes; uv run pytest reports 6823 passed and
4 failed. All four fail on origin/main as well (one theme assertion, three
channel QR cases) and are left for a separate fix. Upstream's own 53 changed
test files pass, and so do our 85, which is what pins both sides' semantics
through these resolutions.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
Land the accumulated core development from the ravenx workspace as a
single change on top of origin/main. It covers the gateway web-app RPC
channel, pluggable sub-agent execution backends with third-party CLI
and OpenAI-API presets, the sub-agent DAG subsystem and its TUI
surface, vendor-aware provider resolution, the deliverable token store
and the deliver_files tool, and the skill tool gating rework.
The web UI itself is deliberately excluded. ui-webui/ and
start_webapp.sh land separately, together with the lint ignores and the
third-party notice that reference them, because the repository asset
policy for that tree has to be settled first.
Condensed from 68 commits whose history predates this repository's
linear-trunk rule; the three-way merge against origin/main applied
without conflicts.
A follow-up commit fixes a stale assertion that arrived with the import:
read_local_body grew hub-shaped metadata and its test still described
the older four-key return.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Closes out the provider path in one PR: the provider module redesign,
every
open issue and backlog item that lives on the identity / connection /
routing / capability axes, and multi-endpoint failover as a new feature.
78 commits, one problem per commit, rebased onto current main.
Redesign (base): four provider decisions were implemented outside
`raven/providers/` and had drifted copies -- wire form, credential
grammar,
pin resolution, price/window ladder, cache dialect. Each now has one
owning
module the surfaces call.
Fixes on that base, most visible first:
- The context window walks one ladder (explicit config > the model's
real
window > documented fallback). Previously the config default 65536 fed
trimming and budgets raw, so a 200k-window model lost two thirds of its
context every turn; an unresolvable window now renders the gauge's empty
state instead of a number that is nobody's. Construction and /model
switches resolve without touching the network, and a switch parked
behind
a running turn re-resolves the window at adoption, not at the RPC call.
- A provider without real streaming (azure, codex) no longer renders
upstream errors as normal assistant text: the terminal stream delta
carries the classification and joins the same recovery path the
non-streaming call uses. Both classify their non-200 from the live
status
code (shared ProviderHTTPError) instead of regex-guessing the rendered
text, which also removes the bare "404" substring match that misfiled a
400 whose body happened to embed one.
- Codex SSE failures keep their structured code, so an overloaded
backend
is retried instead of classified unknown.
- Orphan `</think>` recovery (backends launched without their reasoning
parser) is gated to the backend shapes that produce it, so ordinary
content mentioning the tag is never cut.
- Fallback hops are vetoed when both identities are certain and disagree
(previously a cross-vendor hop went out under the wrong key, or silently
to the wrong backend on a shared model name); the knn path dispatches
each hop to its own endpoint and inherits model_overrides through the
rotor.
- User model_overrides win over shipped extra_body defaults, and the
merge
no longer drops user keys behind a gateway.
- The credential gate, the reader and the builder answer one way: a
spec's
shipped default address satisfies the gate exactly when the reader would
serve it (custom runs on a bare key again, azure still demands its
address), endpoint entries inherit the flat api_base/extra_headers per
field, and every display face -- provider list, endpoint list, the TUI
picker -- reports the same resolved view, secrets redacted
(extra_headers
values included, on the flat section field too).
- The vision probe stops joining operator-chosen names against the
vendor
catalog: it reads through the TUI's lazy proxy to see the Azure
transport, treats an explicit-selection gateway (custom) as
caller-chosen, and the background catalog warm is no longer suppressed
for the life of the process by a stale on-disk table.
- Skill forge rewriter/gate follow the configured agent model (the only
auxiliary LLM calls that did not).
- The onboarding wizard refuses the six litellm vendors a bare API key
cannot configure, with the actual requirement named, instead of writing
a section that 401s forever.
- The OAuth handoff replays a signal swallowed mid-login, so a SIGHUP no
longer leaves a headless TUI.
New feature -- multi-endpoint failover (several accounts on one vendor):
- `providers.<name>.endpoints` (label / apiKey / apiBase / extraHeaders)
with `endpointStrategy: sticky | round_robin`; the three credential
spellings (explicit list, Gemini api_key_list, flat fields) resolve
through one reader with strict precedence and no key merging.
- `EndpointRotorProvider` rotates and fails over with per-endpoint
cooldown
(30s doubling to 300s, process-local state); auth failures rotate --
another account's key is exactly what a dead key needs -- while
endpoint-agnostic failures return immediately. Streams rotate only
before the first delta, so tokens are never replayed.
- Managed from `raven provider endpoint add|remove|list` and the TUI
model
picker; the session footer names the active endpoint. Write faces refuse
a keyless endpoint for key-credential providers (local deployments keep
their legitimate keyless shape); invalid sections fail loudly instead of
being read as empty and overwritten.
- Verified live twice: the rotor directly, and the full stack from a
config file through make_provider (a dead key 401s, cools, fails over,
answers). The first live run caught the auth-rotation gap the mocks
could not.
Also in this PR: the onboarding wizard split (5069 -> 3000 lines, pure
moves with every migrated monkeypatch target mutation-checked),
CONTEXT.md
terms (Provider Endpoint, window ladder), benchmark alignment
(pinchbench
now prices through the shared ladder instead of a private drifted copy),
and the model picker reads the config twice per open instead of twice
per
provider row.
Reviewed adversarially across three external rounds and four internal
panel rounds on two model families: 24 before-merge findings raised in
total, every one either fixed with a mutation-verified test or refuted
with executed evidence (one reviewer finding was withdrawn after a
945-case main-parity sweep); final verdicts RATIFY. The rebase also
adopted the review notes left on #282/#285 that landed on this code:
image-capability verdicts are invalidated on a provider switch, and a
parked switch logs its park and its adoption.
Known follow-ups, named in the review thread (issues to follow): the
fallback routing loop contradicts the registry's explicit-selection note
for `custom` (pre-existing on main), the remaining bare status
substrings
in classify_error (429/5xx, pre-existing), per-hop identity rebuilding
for
fallback chains, and the pre-existing SessionInfo shape mismatch.
## Type
- [x] Feature
- [ ] Fix
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/ -q` -- 6128 passed, 33 skipped, run after the
rebase onto current main; the provider-path test files additionally
re-run under an empty HOME with identical results.
- `make lint-python` clean; commit messages pass commitlint and
scripts/check_commit_messages.py across all 78 commits.
- `cd ui-tui && npm run lint && npx tsc --noEmit && npx vitest run` --
86
files, 982 tests passed; `npm run gen:rpc -- --check` in sync.
- Live probes (OpenRouter, tiny max_tokens): rotor failover and
full-stack
assembly failover, both passing; logs kept locally.
- Fixes are pinned by deletion mutations that turn a named test red;
review rounds ran 22 such mutations and the two survivors were
themselves fixed (one dead guard deleted, one vacuous test replaced).
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible behavior changes: `contextWindowTokens` unset now resolves
to
the model's real window (explicit values are fully respected and no
longer
overridden); the context gauge shows an empty state when the window is
unknown; azure/codex upstream errors surface as errors instead of
assistant text; the wizard refuses six key-only-unconfigurable vendors
with the real requirement named; `custom` with only an apiKey starts
again
(as on main) and the picker no longer demands an address the gate does
not; key-credential providers refuse keyless endpoints at write time and
`endpoint add --api-key` becomes optional for local deployments;
endpoint
keys and extra_headers values are redacted in `provider get`/`list` and
over RPC; a model switch logs when it parks behind a running turn and
when
it adopts. Rollback is a straight revert of the squash commit; no data
migration is involved (config additions are opt-in fields).
## Related Issues
Fixes#124, fixes#234, fixes#155, fixes#152, fixes#254, fixes#151,
fixes#143, fixes#144, fixes#197. References #281 (not reproducible on
current or reported code; the api_key forwarding it suspected is now
pinned
by regression tests), #119 (already fixed by #116; remaining item is the
installer redirect, not provider code).
---------
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
## Change description
> Whole-repo lint + pre-commit convention, CONFIG ONLY (no source
reformat in this PR). Python (ruff) and TypeScript (eslint + prettier)
share a 120-col margin via the committed pre-commit gate. This upgrades
main's existing basic ruff setup and adds the TS lint stack (none
existed on main).
>
> What this PR adds:
> - ruff: line-length 120; security rules
S101/S105/S106/S107/S506/S605/S607; policy per-file-ignores (tests +
accepted CLI deferred-imports + product asserts + N818, each commented);
ruff pinned <0.16.
> - eslint/prettier: shared base (`eslint.base.mjs` +
`prettier.config.mjs`); ui-tui extends it with React rules, bridge with
a Node-only config; hermes-ink vendor and generated RPC types excluded.
> - pre-commit: keeps main's hooks (conventional-commit,
detect-private-key, etc.), adds a top-level exclude and 4 local
eslint/prettier hooks; bumps the pre-commit dev dep.
> - 2 lint-surfaced fixes: PlannerContext import (F821) in the sentinel
runner; lower-cased file-local cron-heartbeat constants (N806).
(raven/config/raven.py's F821 was already fixed on main.)
>
> Sequencing: config only. `ruff check` is intentionally red on ~307
auto-fixables (I001/F401/F541/E701/E702); a SEPARATE reformat branch
runs `ruff --fix` + `ruff format` + eslint/prettier --fix to clear them
(100% auto-resolvable, zero manual). Enforcement (pre-commit install /
CI) turns on only after the reformat lands, so do not expect a green
tree from this PR alone.
>
> CLI-owned files (the reformat and several per-file-ignores touch
`raven/cli/*`) are under review by the CLI team. Judgment items (TS
no-explicit-any, no-unused-expressions, S101 convert-vs-keep, N818
rename, C90, mypy) are deferred to v2.
## Type of change
- [ ] Bug fix
- [x] New feature
- [ ] Document
- [x] Others
## Related issues (if there is)
> none
## Checklists
### Development
- [ ] Lint rules pass locally
- [ ] Application changes have been tested thoroughly
- [ ] Automated tests covering modified code pass
> config-only: `ruff check` is red on auto-fixables by design (the
reformat branch clears them); eslint/prettier configs load in both
ui-tui and bridge.
### Security
- [x] Security impact of change has been considered
- [ ] Code follows company security practices and guidelines
> Only dependency change is the dev-only pre-commit tool plus the ruff
pin; the detect-private-key hook from main is retained.
### Code review
- [x] Pull request has a descriptive title and context useful to a
reviewer
- [ ] Pull request linked to JIRA ticket when applicable
---------
Co-authored-by: Sheng Zhao <sheng.zhao@evermind.ai>
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>