70 Commits

Author SHA1 Message Date
Dizhan Xue
f135c33ec8
fix(subagent): start agents on windows from a stored launch command (#864)
## Summary

Stored Windows launch commands were parsed with POSIX rules, which
removed backslashes from unquoted interpreter and launcher paths. Launch
consumers now share platform-aware parsing and quoting, while retaining
compatibility with single-quoted absolute paths saved by older callers.

- Read legacy single-quoted drive, UNC, and absolute POSIX path tokens
on Windows, including path values after `=` and the quote concatenation
emitted for apostrophes inside a path. Decode only that token so
neighboring native Windows arguments keep their backslashes and literal
apostrophes. Launch and readiness use the same compatibility decoder.
- Preserve quoted paths in discovery and stale-row checks. Escaped
quotes, CR/LF separators on POSIX, and arguments made only of
backslashes no longer hide or merge a launcher path.
- Share substitution across discovery, registration, scaffold smoke
checks, generated installers, and all five shipped installers. Older
Raven versions without the resolver refuse unsupported spaced command
paths before registration, while keeping plain paths and separately
passed working directories supported.
- Quote Raven's own ACP executable and forwarded config path for the
launch platform. Resolve bare programs on the child's PATH in directory
order, preferring executables within each directory. ACP may resolve
configured batch shims; prompt-bearing CLI and Kimi calls retain their
lookup restriction.

## Type

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

## Verification

Checked on native Windows using an existing uv environment, with the
source imported from the reviewed checkout and `PYTHONUTF8=1`.

```text
uv run --no-sync python -m pytest tests/test_utils_commands.py tests/test_subagent_vendored_agents.py tests/test_subagent_builtin_agents.py tests/test_subagent_registry.py tests/test_subagent_third_party.py::test_cli_backend_preserves_stored_windows_path_quotes tests/test_subagent_host_env.py::test_acp_launch_preserves_stored_windows_path_quotes tests/test_subagent_probe.py::test_windows_probes_find_a_legacy_single_quoted_program -q -x -n 0
```

Result: 292 passed. This covers a real CLI child launched through the
backend, ACP spawn arguments, CLI/ACP availability probes, and
existing/missing launcher checks, with both legacy and native quoting
controls.

The final 25 added cases were also run in an isolated process with the
previously published parser: 12 failed and 13 passed. Four isolated
mutations were caught: disabling compatibility (8 failures), removing
the launch quote guard (1), removing the readiness quote guard (1), and
using POSIX parsing for the entire Windows command (15). A seeded
50,000-case check through the native producer and both consumers
reported no argv or readiness-token mismatches.

Whole-branch checks:

```powershell
$prFiles = @(git diff --name-only origin/main...HEAD -- '*.py')
uv run --no-sync ruff check @prFiles
uv run --no-sync ruff format --check @prFiles
$production = @($prFiles | Where-Object { $_ -notlike 'tests/*' })
uv run --no-sync ty check @production
uv run --no-sync lint-imports
uv run --no-sync pre-commit run --from-ref origin/main --to-ref HEAD
uv run --no-sync python scripts/check_commit_messages.py origin/main..HEAD
uv run --no-sync python scripts/check_source_language.py origin/main...HEAD
uv run --no-sync python scripts/check_large_files.py origin/main...HEAD
git diff --check origin/main...HEAD
```

All passed: 24 Python files passed Ruff checks; production type checks
passed; all 10 import contracts were kept. The pinned commitlint CLI
also passed over the full branch range. The final documentation-only
follow-up changes no executable behavior.

Limits: a broader Windows selection stopped after 283 passing tests at
`test_cli_probe_reports_the_resolved_absolute_path`, whose bare POSIX
shell fixture is not resolved as a Windows executable. This is not
counted as a passing suite. The ACP regression checks the arguments
delivered to process creation; it does not claim to verify the existing
POSIX-only process-group shutdown path on Windows. The local Docker
daemon was unavailable, so no new local Linux or macOS run is claimed.
The full repository suite and a live WebUI dispatch were not run locally
for this revision.

The pre-submit sweep covered the complete branch diff, all command
producers and consumers, native/legacy quoting boundaries, installer
fallbacks, failure paths, test strength, layer contracts, repository
gates, and these disclosed verification limits.

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

No screenshot update applies. Parser docstrings describe the legacy-path
compatibility and how to preserve literal quotes.

## Risk

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

Compatibility applies to single-quoted absolute path tokens, including
path values after `=`; it does not enable general POSIX shell syntax on
Windows. Non-path apostrophes remain literal. To preserve literal single
quotes around path-looking data, quote the entire argument with native
double quotes. Existing stored path tokens are read compatibly without
rewriting configuration; newly generated commands keep native quoting.

POSIX launch parsing is unchanged. Readiness preserves foreign
absolute-path spellings and checks launcher existence; it is not a
general command validator. Older installers reject paths their Raven
version cannot represent before changing the roster.

ACP batch shims execute configured server arguments through cmd.exe.
Prompt-bearing CLI and Kimi calls do not opt into batch lookup. A CLI
agent installed only as an npm shim still needs an explicit executable
path. Reverting the squash commit restores the prior behavior.

## Related Issues

#880

---------

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
Co-authored-by: Codex <noreply@openai.com>
2026-10-11 23:04:06 +08:00
Dizhan Xue
2ab0658852
fix(*): name the missing credential when an agent cannot inherit (#862)
## Summary

Follow-up to #841, which lets an agent inherit an OAuth-backed host
model. Since #841 a launcher refuses when the host's selected model
cannot authenticate, but the refusal still said the host config had no
provider key to inherit from. That is untrue in the case #841 made
reachable: the host holds an OpenRouter key while its selected model is
OpenAI Codex with no sign-in.

- `inherit_refusal(config, host)` in `raven/config/product_render.py`
  returns the `MissingCredentialsError` summary for the binding
  `inherit_llm` checks, or `""` when it would inherit. `inherit_llm`
  keeps answering a refusal with `""`, the value every launcher branches
  on, scaffolded copies outside this repository included. Both now run
  on two private helpers, so the inherited binding is composed in one
  place. A non-string `agents.defaults.model` with no provider now
  reaches `Config` validation instead of `split_model_id`, so
  `host_can_lend_a_key` answers False where it raised `AttributeError`
  past its except clause.
- The four keyed launchers and the `raven agents new` template print
  that reason and keep the `<KEY> is not set` prefix the scaffold smoke
  check matches; raven-design appends it to its own sentence. All six
  look `inherit_refusal` up with `getattr` and, on an older raven that
  lacks it, refuse with the same sentence without the reason: a folder
  the template generates is never refreshed when raven changes
  version, and a home tree a newer wheel copied out also serves an
  older checkout.
- An agent is spawned with the login shell's environment, and with
  raven's own environment only when that shell cannot be captured, so
  a `CHATGPT_TOKEN_DIR` or `CHATGPT_AUTH_FILE` set only in the host
  process does not normally reach it. This PR documents that rather
  than forwarding the variables: the spawn path adds the host's
  `RAVEN_HOME` when one is set, and with it unset both sides normally
  resolve `~/.raven`, so the default token location is shared; a
  custom override can live in the login profile or the agent's stored
  row `env`. `agents/README.md` and the `host_can_lend_a_key` and
  `host_config` docstrings say so, and the `host_can_lend_a_key`
  docstring says why setup can still offer an inheritance the launcher
  refuses -- the agent's environment and config are not the host's --
  and names the routes, among them a `RAVEN_HOME` from the login
  profile or from the agent's stored row. Three older texts in files
  this PR edits, which said the launcher inherits `RAVEN_HOME`, say
  instead that it normally shares the host's home.
- CHANGELOG records the clearer refusal.

Checked and deliberately left as is:

- `inherit_llm`'s docstring moved below the new helpers verbatim, apart
  from the pointer to `inherit_refusal`, so it keeps its older wording;
  `git diff --color-moved` shows the move.
- The smoke check in `raven agents new` still matches the old "no
  provider key to inherit from" text, because scaffolded copies in
  users' homes keep printing it.
- `MissingCredentialsError.remedy` is not appended: every summary this
  check raises carries its own command or is answered by the launcher's
  closing "configure a provider in the host raven", and the generic
  remedy is multi-line.
- A malformed host provider section still ends a launcher with a
  validation traceback, exactly as before; the call that raises it
  moved into a helper unchanged.
- The same unconditional `RAVEN_HOME` claim also sits in
  `raven/agent/subagent/role.py`, twice in `CONTEXT.md` and in
  `docs-site/docs/oncall.md` with its Chinese twin. None is in a file
  this PR edits, and all predate it; they are left for a separate
  change.

## Type

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

## Verification

Targeted, on the head:

```
uv run --frozen --python 3.12 --all-extras pytest -q -p no:randomly tests/test_config_product_render.py tests/test_subagent_vendored_agents.py tests/test_agents_design_launcher.py tests/test_cli_agents_commands.py tests/test_cli_smoke.py tests/test_agent_schemas.py
```

382 passed, 2 skipped. Deleting each construct this PR adds turns that
run red: the non-string guard (2 failed), the empty-summary fallback
(1), `inherit_refusal` reading its `config` (1), and, in each of the
six launchers, the reason and the parentheses around it (1 each; 2
for the template and for raven-design) and the `getattr` lookup (1
each, when replaced by a direct attribute read). The same run passes
(382 passed, 2 skipped)
with provider API keys exported and `CODEX_HOME` and
`CHATGPT_TOKEN_DIR` pointing at a fake sign-in, so the refusal tests
do not depend on the machine lacking credentials.

Full suite:

```
env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy -u no_proxy uv run --frozen --python 3.12 --all-extras pytest -q -p no:randomly
```

2 failed, 27580 passed, 115 skipped. Both failures also fail at the
base, 3632e6040, on this machine and touch nothing here:

`test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
(an npm elsewhere on PATH leaks past the fixture) and
`test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
(the run is root, which reads a file the test made unreadable). The
proxy is unset because five unrelated provider tests fail when the
shell carries this machine's proxy.

Lint and gates: `ruff check` and `ruff format --check` over the twelve
changed Python files, `ty check` over the eight non-test ones, and
`lint-imports` (10 kept, 0 broken) are clean;
`scripts/check_commit_messages.py origin/main..HEAD`, `commitlint
--from origin/main --to HEAD`, `scripts/check_source_language.py
origin/main...HEAD` and `scripts/check_large_files.py
origin/main...HEAD` exit 0.

Rendered refusals, the first from a host with an OpenRouter key and an
unsigned Codex model, the second from `raven agents new demo-agent` in
a home with no key:

```
error: CODE_API_KEY is not set and the host's model cannot be inherited (openai_codex needs a sign-in -- run `raven provider login openai-codex`); put the key in <agent dir>/.env (see .env.example), export it, or configure a provider in the host raven
error: DEMO_AGENT_API_KEY is not set and the host's model cannot be inherited (no provider is configured yet -- run `raven onboard` for guided setup); put the key in <agent dir>/.env (see .env.example), export it, or configure a provider in the host raven
```

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

## Risk

- The refusal wording changes for raven-code, raven-oncall,
  raven-research, raven-ppt, raven-design and the scaffold template; a
  script matching the old "no provider key to inherit from" text stops
  matching for these launchers.
- The launchers and the template now reach `render.inherit_refusal`
  through `getattr`, because each can meet a raven that predates it: a
  folder `raven agents new` generated is never refreshed, and the
  packaged tree is re-copied on a version change only in the wheel
  shape, so a home tree a newer wheel copied out also serves an older
  checkout. Every other function they call exists back to v0.2.0, and
  on such a raven they refuse without the reason.
- No secret reaches the message: a summary names a provider and a
  command, never a key value.
- Rollback: revert the squash commit; nothing is stored or migrated.

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

## Related Issues

#841

---------

Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-10-08 16:54:03 +08:00
arelchan
9c1cdaed97
feat: let raven read and change its own configuration (#833)
## Summary

Raven can now read and change its own configuration through one tool,
`raven_config`, instead of telling the user to open Settings or editing
`config.json` with file tools. The same path lets it connect preset
sub-agents and diagnose the ones that do not answer, and asks the user
only for what needs them (a key, a sign-in, a paid model).

**The tool and its catalog**
- `raven_config` actions: `describe` (every setting with its value, or a
search), `get`, `set` (one path, or several under one confirmation),
`unset`, `add` (connect presets, several at once), `test`, `restart`
(reload or restart once pending changes are gathered). `session.model`
switches only the current conversation.
- `raven/config/self_surface.py` is the catalog: 14 sections, about 93
settings, each with its value kind, its writer, and when a change takes
effect (next turn, at once, reload, restart, memory server, or inert).
Writes go through the RPC methods the settings page already uses
(`SELF_CONFIG_METHODS` allowlist), so the page and the agent share one
validation path. `tests/test_config_self_surface.py` holds every entry
against the schema and every next-turn claim against a real reader.
- A refused sub-agent comes back with one next step per refusal kind (9
Raven fixes itself, 5 the user does), with stop rules: no hunting for
keys, no credential stores, no restarting another app's services, stop
after three commands that explain nothing.
- `subagents.add` stays preset-only: every execution field comes from
the preset. Presets can be named by display name, an add can pin a model
the agent lists, and a model pick on an unmeasured agent reads the
handshake menu first.
- The companion skill `raven-self-config` describes the whole flow; its
description is injected every turn, the body is read on demand.

**Approval**
- Reads run unasked. Every write asks by default, on a dedicated config
card (what changes, before and after, when it takes effect, a sensitive
note). A grant for the session never carries a change.
- In a turn someone is at, full access, the user's allow rule, and smart
mode's reviewer let a change through; the reviewer never approves a
sensitive setting. Sensitivity is declared by the owner: catalog entries
(approval mode and review model, workspace confinement, sandbox, deny
patterns, disabled tools, MCP servers switched on, skill blocklist and
auto-install, provider endpoints, web and media proxies, remote
machines, workspace path, lent keys, sub-agent descriptions) and each
channel adapter's spec (who may instruct Raven, whether a channel is on,
where its credentials and traffic go, encryption). The gate and the tool
read a call the same way: one value decoder, one path spelling, one
channel field lookup, an object value judged field by field; a path the
tool does not write is refused at the gate, and a call naming one
setting twice is refused. A value is secret when the schema, the channel
spec or the catalog says so, a credential-named env entry, any header,
or a credential inside a URL. The reviewer's instruction counts the
agent's own non-security settings as ordinary work. Unattended turns
(cron and other scheduled runs, no one to answer) are refused; a channel
user who can answer an approval is attended.

**Secrets**
- A key never travels through a tool call. The agent names the secret
with an empty value and a credential card of its own
(`credential.request` / `submit` / `skip` / `pending` / `closed`) takes
it; the host writes it through the handler that owns it and the model
learns only saved or skipped. Channel secrets use the same card. A call
that only asks for keys goes straight to the card. Enabled on page
surfaces only.
- Tool output is scrubbed of the values Raven holds
(`config/held_secrets.py`, including JSON-escaped spellings and URL
credentials) and dotfile reads under home are redacted, once, inside
`ToolRegistry.execute`, so the trace span, the page's diffs, the
sentinel and both agent loops get the scrubbed copy. What a sub-agent
says is scrubbed where it is kept: transcripts, call labels, closing
text, the output a later DAG node renders, error records, announces, the
ACP frame journal, probe details. A key pasted into the chat is refused.
- Lent keys: an ACP sub-agent row can name Raven providers (`lendKeys`)
whose key it is started with. The row stores the provider name; each
start (the spawn path and the capability probe) reads the key into the
variable the preset reads (`presets.LENDABLE_KEYS`, Pi only for now), so
it never reaches the model and follows a rotated key. Verified live: Pi
refused without it, answered with Raven's OpenRouter key, and its row
reads connected and tested with a 398-model menu.

**Page**
- Config card and credential card; the model and permission chips
refresh after the agent changes them; the transcript names
`raven_config` calls by what they did.
- Agents page: the note on a refused connect, a failed test, or a check
that found a problem offers "Hand it to Raven" on its title line; it
opens a new conversation with a prompt naming the agent and the reason,
not sent. A connected row whose check found a problem now shows one head
line and an amber note in the body (shaped like a failure's) instead of
the check's English sentence folded under the head.

**Other**
- Memory LLM left unset follows the main model (EverOS restarts when the
main model moves).
- Reload and restart wait for page turns in flight too.
- `plugin` points agents and chat apps at `raven_config`; `cron` names
the missing `message`; a GNU `timeout` shim on hosts without one,
accepting only the durations the permission gate parses (one shared
definition); read-only package-manager subcommands allow.
- Contracts: `CONTRACTS_VERSION` 35 (this branch's credential types plus
main's `FileWrite`) with the surface repinned; paper-tier line ceiling
3,700 (measured 3,682) with its review note. `CONTEXT.md` defines the
self-configuration surface and lent key.

## Type

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

## Verification

- `uv run pytest -q -n auto`: 27187 passed, 3 failed. The 3 fail on this
machine regardless of this branch:
`test_rpc_files::test_a_host_without_libreoffice_says_so` (LibreOffice
is installed here),
`test_simulation_scenario::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`
and
`test_simulation_suite::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`.
`schemas/subagent.schema.json` is regenerated for `lendKeys`;
`test_import_cycle_budget` holds (the capability probe takes the launch
env from its caller rather than importing the agent layer).
- `make lint-ui` (gen:check, eslint, tsc): pass; the 4 eslint warnings
are in files this branch does not touch.
- `npx vitest run` in `ui-web`: 3116 passed; `check-css`,
`check-class-namespace`, `check-page` OK.
- `npm run lint:i18n`, `lint:rpc`, `type-check` in `ui-tui`: pass.
- `uv run ruff check` and `ruff format --check` on every changed Python
file, and `lint-imports` (10 contracts kept): pass.
- In a browser against a local gateway: credential card save, skip,
replace and reload replay; the value appears in no session, trace or
log. Agents page link opens a new task with the prompt filled and
unsent; sent, the agent reads the self-config skill and calls
`raven_config` first, and for Pi offers Raven's key before a sign-in.
- Smart-mode reviewer, run against the real model: 7 ordinary config
changes allowed; `sed` or `write_file` on Raven's config, reading an SSH
key, and `curl | sh` escalated.

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

## Risk

- Behaviour changes: the agent can now change settings and connect
sub-agents after the user confirms (or unasked under full access, and
under smart mode for non-sensitive settings). Lending gives a sub-agent
Raven's key for a provider after an explicit, sensitive confirmation;
what it spends is billed to that key.
- Memory: a memory LLM left unset now follows the main model, so
long-term memory starts working after the upgrade for anyone who never
pinned one, extracting on the main model and billed to the main
provider's key, and EverOS restarts when the main model changes. To keep
it off, set `memory.backend` to null; to keep it on a different model,
pin one of its own.
- Backward compatible: new config fields are optional, and both probe
fingerprints include `lendKeys` only when set, so recorded verdicts and
menus survive. A `config.json` written with `lendKeys` will not load on
an older build (`extra=forbid`).
- Rollback: revert this PR; nothing is migrated. To switch the feature
off without a revert, add `raven_config` to `tools.disabledTools`.

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

## Related Issues

N/A

---------

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-10-03 12:14:04 +08:00
silverLXT
afa469d4ac
refactor(*): one registry reader and one writer, and the coding agent can add a machine (#690)
## Why

In a research -> code -> oncall chain run on 2026-09-22, Raven-Code
called
`exec(machine="conn_cpu_32c")` and got "No connection is registered", on
a home
whose `connections.json` listed seven machines. It then read
host/port/key out
of the config and ran a raw `ssh root@<ip> -p <port> -i ~/.ssh/id_rsa`,
putting
the way in into the transcript.

Two gaps:

1. **Read side.** `raven.ops.connections.store_path()` looked only
beside the
instance's own config. A sub-agent runs on a rendered config in its own
state
directory, so it looked in an empty directory. The host already hands
every
sub-agent `RAVEN_HOME`; the registry just was not looked for there. Only
the
on-call launcher worked around this (it sets `RAVEN_CONNECTIONS`
itself).
2. **Write side.** `ops_connection_add` (#545) lived in the on-call
plugin. In the
usual chain the coding agent runs first, meets the empty registry first,
and
   had no way to take the owner's answer.

## What changes

- `store_path()`: env var -> `raven_home()/connections.json` if it
exists ->
beside the config if THAT exists -> the home (where a first add lands).
An
  install that kept its own list beside its config keeps working.
- New `raven/ops/connection_add.py`: `probe`, `ssh_defaults`,
`parse_probe`,
`write`, `write_ssh_alias`, and `ASK_OWNER` (the questions relayed to
the owner).
The tool calls these functions directly; `raven ops connection add` (the
terminal command for a person) calls the same ones, so the logic exists
once.
- New `raven/agent/tools/connection_add.py`: `ops_connection_add` as a
trunk tool,
**opt-in** via `tools.connectionAdd` (on in raven-code and raven-oncall,
off in
  the other three products, whose pinned tool faces are unchanged).
- `raven.ops.transport.make_ssh_runner(identities_only=)` +
`ISOLATE_IDENTITY`,
moved from the plugin: a key the tool picked itself is probed with that
key
  alone (see #545 review).
- On-call plugin: `oncall_flow/connections.py` imports trunk's reader
instead of
keeping a hand-aligned copy (758 -> 212 lines); keeps only campaign
lookups
(`get`, `display_name`, `resolve_into`, `describe`). Its own tool file,
  factory and manifest row are removed.
- Raven-Code guide (`TOOLS_CODE.md`) gains when to leave this computer:
write
here; verify where the software is; ask the owner for a machine only
when
installing the software here is wrong (GPU, memory) or heavy (compiled
solver,
toolchain, long download); never ssh from an address in the task
statement.
- `SHOWN` made public in `raven.ops.connections` (the plugin may not
import an
  underscored trunk name; `_SHOWN` stays as an alias).
- Docs: `docs-site/docs/oncall.md` / `oncall.zh.md` updated for the new
lookup
  and the tool.

## Not in scope

- The pre-dispatch registry gate removed in a44664d1b is NOT restored.
Where a
job runs is still decided inside the agent that runs it; this only makes
that
  agent find the owner's registry and able to add to it.
- #552 (exec refuses a typed ssh to a registered machine) is
complementary: it
only fires once the registry is visible, which this makes true for
Raven-Code.

## Tests

- `tests/test_ops_connection_add.py` (moved from the plugin suite,
patches trunk
modules), including the ssh `-G` measurement that only the candidate key
is
  offered under isolation.
- Five new cases in `tests/test_ops_connections.py` for the lookup
order.
- Plugin parity tests replaced by an identity pin (the plugin's names
ARE trunk's
  objects).
- Code launcher face ledger gains a machine lane; oncall face unchanged.
- Full suite: see CI.

@LivXue -- review requested: this touches `raven/ops` and the
`RAVEN_CONNECTIONS`
handoff described in a44664d1b.

Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>

Generated with Claude Code (https://claude.com/claude-code)

---------

Co-authored-by: xiaotian.luo <xiaotian.luo@thetahealth.ai>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-24 18:36:28 +08:00
Zuyi Zhou
34ed138cc7
fix(plugins): a plugin that fails to load no longer takes every other plugin with it (#703)
## Summary

One plugin that failed to activate dropped every plugin.
`PluginRegistry.activate` raised on the first plugin whose factory would
not import (or whose contribution name collided), and
`build_plugin_registry` (`raven/core/plugin_stack.py`) answered by
returning an empty registry. A single broken user plugin therefore
silently removed research-flow, ppt-engine, design-engine, the memory
backend and the bundled playbook tools, with one stderr warning as the
only trace. Reproduced with two mock plugins under a scratch
`RAVEN_HOME`: `aa-broken` (factory raises `ImportError`) beside
`zz-good`; before this change the registry came back with `activated:
[]`, after it with `design-engine, everos-memory, playbook, ppt-engine,
zz-good` activated and `aa-broken` named as failed.

Changes:

- **Per-plugin activation** (`raven/plugins/registry.py`). Each admitted
plugin activates on its own. One that fails is rolled back whole (no
partial contribution in any table, and the `sys.path` entry
`_ensure_importable` appended for it is withdrawn), recorded as a
`PluginActivationFailure` (`activation_failures()`), and the plugins
after it still activate. In a name conflict the plugin activated first
(discovery order, by id) keeps the name and the other is recorded as
failed. A module `__getattr__` that raises something other than
`AttributeError` is now a recorded failure rather than an uncaught
crash.
- **Said to the user** (`plugin_stack.build_plugin_registry`,
`runtime.build_runtime`). Each failure is one notice naming the plugin,
its cause and the `plugins.disabled` escape, through the host's notifier
(`HostWiring.notify`), else stderr - the same channel the
missing-memory-backend notice already uses. When the configured memory
backend belongs to a plugin that failed, the memory notice names that
plugin and its cause instead of "no installed plugin provides it".
- **`raven plugins`** shows a `failed` status and the cause under the
table (the command called `activate` directly and previously crashed on
such a plugin).
- **Agents smoke check** (`raven/cli/agents_commands.py`) matched the
old log line "plugin activation failed", which no longer exists; it now
reads the shared `PLUGIN_FAILURE_MARKER`, and its test prints the notice
the real producer writes, so the two cannot drift.
- **Sub-agents inherit the host's opt-outs**
(`product_render.write_rendered`, `inherit_plugin_opt_outs`). A product
engine inherits `RAVEN_HOME`, so it scans the host's `<home>/plugins`
and the shared interpreter's entry points, but it read
`plugins.disabled` only from its own rendered config; a plugin disabled
on the host came back in every product. Every render now merges the
host's list after the product's own. The product's own engine plugin
never travels (`own_plugins=`, passed by all five launchers and the
scaffold): the PPT agent is `ppt-engine`, and a host turning it off for
its own agent is not a request to run the PPT agent without it. A
contract test reads every launcher's `write_rendered` call and requires
it to name its `*_PLUGIN_ID`.
- `CONTEXT.md` (Plugin Registry) and
`docs-site/docs/building-plugin{,.zh}.md` describe the new behaviour.

Not in this PR: the Web UI plugin list (`ext.list`) is discovery-only
and does not show a failed plugin; adding it is a wire change
(`ExtListResult`, openrpc, generated TS, the page) and is left for a
follow-up. The TUI, gateway and `raven agent` hosts show the notice
through their notifiers; the rpc stack (serve/acp) prints it to stderr,
which is also what the agents smoke check reads.

## Type

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

## Verification

**Rebased**: head 7cd000dbc on origin/main 8ee5ae0d8, without conflicts.
`git range-diff` shows every commit replayed unchanged. The branch's own
test files rerun at this head: 395 passed. Numbers elsewhere in this
description are from earlier heads.

Head b4d51aee8, rebased onto origin/main 6551f8259 after #698 and #708
merged. #698 conflicted in `raven/config/product_render.py` and
`tests/test_config_product_render.py`: both PRs added a function at the
same spot (`inherit_host_denials` there, `inherit_plugin_opt_outs` here)
and a call in `write_rendered`. The resolution keeps both functions and
all their tests; `write_rendered` now reads `host_config()` once and
passes it to both. #708 touches none of these files. At this head:

```
COLORTERM=truecolor uv run --frozen --python 3.12 --all-extras pytest -q -p no:cacheprovider
  25948 passed, 109 skipped
uv run --frozen --python 3.12 --all-extras pytest -q tests/test_config_product_render.py
  44 passed
ruff check / ruff format --check / make lint-imports lint-deps lint-types / git diff --check origin/main...HEAD
check_source_language.py origin/main...HEAD / make check-commits / check-large-files
  all clean
cd ui-tui && npm run lint:rpc && npm run type-check && npm test
  144 files, 2106 passed
```

The earlier `TUI checks` failure (run 35834019105, head 5fc374035) was
`newInstancePicker.test.tsx > quick-selects by the number it printed`.
This PR changes nothing under `ui-tui/`; the test passed 5 of 5 runs
locally at this head and in the full ui-tui run above.

The numbers below are from the earlier heads and are kept for the
record.

```
uv run --frozen --python 3.12 --extra dev ruff check raven evolver agents plugins-dist tests scripts
  All checks passed
uv run --frozen --python 3.12 --extra dev ruff format --check raven evolver agents plugins-dist tests scripts
  2083 files already formatted
make lint-imports && make lint-deps && make lint-types
  Contracts: 10 kept, 0 broken / No dependency issues found / All checks passed
git diff --check origin/main...HEAD
  clean
COLORTERM=truecolor make coverage        (full suite, head before rebasing onto 7fdf296f4)
  25847 passed, 109 skipped
COVERAGE_BASE_REF=origin/main make coverage-diff
  Diff coverage: 100.00% (71/71 executable changed lines)
PYTHONPATH=. uv run --frozen --python 3.12 --extra dev python scripts/check_source_language.py origin/main...HEAD
  exit 0
make check-commits
  pass
git merge-tree --write-tree HEAD origin/main
  clean
```

After rebasing onto 7fdf296f4 (its two new commits touch none of these
files), the touched suites at this head:

```
COLORTERM=truecolor uv run --frozen --python 3.12 --all-extras pytest -q tests/test_plugin_*.py tests/test_core_plugin_stack.py tests/test_cli_plugin_commands.py tests/test_cli_agents_commands.py tests/test_cli_tui_commands.py tests/test_config_product_render.py tests/test_agents_*launcher*.py tests/test_everos_plugin_discovery.py tests/test_release_plugin_list.py tests/test_cli_gateway_commands.py
  727 passed
uv run --frozen --python 3.12 --all-extras pytest -q tests/test_subagent_vendored_agents.py tests/test_rpc_subagents.py tests/test_subagent_acp.py
  452 passed
```

Revert-to-red, one production file restored to origin/main at a time
with the tests kept:

```
raven/plugins/registry.py        -> 2 errors (plugin_stack imports PluginActivationFailure)
raven/core/plugin_stack.py       -> 6 failed
raven/core/runtime.py            -> 1 failed (build_runtime hands the host's notifier to the registry)
raven/config/product_render.py   -> 42 failed
raven/cli/agents_commands.py     -> 1 failed (smoke reds a handshake whose plugin did not load)
raven/cli/plugin_commands.py     -> 1 failed (failed row and escaped cause)
agents/raven-ppt/run.py          -> 2 failed (engine exemption, launcher contract)
```

Ten existing tests pinned "activation raises" (`test_plugin_registry`,
`test_plugin_bootstrap`, and the conflict tests for tools, hooks, tool
gates and session observers). They now assert the new contract instead:
the later plugin is recorded with the same reason text, the earlier one
keeps the name, and nothing of the loser is registered. Two stubs in
`test_cli_tui_commands.py` took `build_plugin_registry(cfg)` and now
accept the `notify` keyword.

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

## Risk

- A plugin conflict used to disable all plugins; it now keeps the plugin
that activates first and skips the other with a notice. Two plugins
contributing the same name therefore run with one of them instead of
none.
- A product sub-agent now starts with the host's `plugins.disabled`
merged into its config (its own engine excepted). A plugin that was
disabled on the host but relied on inside a product stops loading there;
the remedy is to enable it on the host.
- `PluginRegistry.activate` no longer raises `PluginConflictError` /
`PluginFactoryImportError`; the only in-tree callers were
`assemble_plugin_registry` and `raven plugins`. The exception classes
stay exported.
- Security: the change only narrows what loads. A failed plugin's
directory leaves sys.path, and the inherited opt-outs can only remove
plugins from a product, never add one.
- Rollback: revert the squash commit.

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

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-23 22:41:21 +08:00
zhanghui
db9adde64c
feat(*): fold a large tool catalog by default, with the meta-pair reserved (#616)
## Summary

Make progressive tool disclosure safe to ship on, then ship it on.

`tools.toolSearch.enabled` now defaults to true. Below the compaction
threshold
that costs a deploy nothing (the strategy drops `tool_search` from every
request
while the catalog fits); above it, most schemas are withheld and reached
through
`tool_search` / `tool_call`, so context stops scaling with tool count
and an MCP
connect stops moving the prompt-cache prefix.

Two things had to land first, and both are here:

1. **The meta-pair is reserved from `tools.disabledTools`.** Their
absence from an
array is how the fold reads "this request has no search route", and it
answers
by shipping every schema. So an off switch there did not slim a folded
request,
it unfolded it -- mid-turn, since the switch is read once per assembled
array.
A measured turn went from 12 tools to 61 between two model calls,
discarding
the whole cached prefix. They join the MCP resource and prompt
meta-tools as
names the loop owns for its lifetime; `tools.toolSearch.enabled` speaks
for
both. The settings page needs no change: `ext.list` already reports them
as
   builtin and the page draws a fixed control for those.
2. **A folded request names the connected MCP servers whose schemas it
withheld.**
The runtime context named a server only while it awaited authorization
or was
still connecting, so a connected one read as nothing at all and a model
that
did not think to search reported a capability it held as missing. One
line per
server, counting the tools this turn's array carries and the fold
removes --
not the manager's registered count, which includes a switched-off tool
that
   search filters out and an always-visible one whose schema is present.

Knock-on changes: the four packaged agents drop their now-inert disable
rows, so
`tool_call` joins their faces and the ledger tests record it; each pins
`toolSearch.enabled` to false, which keeps a curated face off the fold.
The
strategy also stops assuming the array's shape -- replay feeds recorded
arrays
back through the same chain, and a corrupt recording used to end the
turn with a
TypeError instead of reaching replay's own backstop.

This replaces #609, which was cut from the pre-rebuild main. The commits
are the
same four plus one test fixture adjustment; the only dropped hunk is an
edit to
`ui-web/src/live/090-extensions.js`, which the frontend rebuild deleted
and whose
behaviour the rebuilt settings page already has.

## Type

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

## Verification

Run on the branch tip, against github/main at 52eb09b25:

- `uv run --frozen --python 3.12 --extra dev pytest -q` with
SERPER_API_KEY unset:
  24325 passed, 121 skipped, 0 failed.
- `uv run ruff check raven/ tests/` and `ruff format --check` on every
touched
  Python file: clean.
- Both new guards were reverse-verified: with the reservation removed
`test_disabled_tools_cannot_withhold_the_meta_tools` fails; with the
notice
  filter removed

`test_the_count_is_what_the_fold_withholds_not_what_the_server_registered`
  fails.
- Note for reviewers: the packaged-agent face tests read SERPER_API_KEY
from the
environment despite being hermetic, so `web_search` joins the face and
they fail
on a machine that has one. That predates this branch and is untouched
here.

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

## Risk

User-visible: a deploy whose catalog passes
`tools.toolSearch.compactionThreshold`
(50 by default) now sends most tool schemas only on demand. A config
file that
spells `enabled: false` keeps today's behaviour with no action. Rollback
is that
one setting, or `compactionThreshold` raised past the catalog size.

Also user-visible: `tools.disabledTools` entries naming `tool_search` or
`tool_call` stop taking effect and are reported once at startup, and the
four
packaged agents now offer `tool_call`.

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

## Related Issues

Replaces #609. N/A otherwise.

---------

Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-09-22 14:05:27 +08:00
Zuyi Zhou
a40e911ddb
fix(agent): bound every tree walk and take it off the event loop (#566)
## Summary

On 2026-09-20 one `find` call froze the whole gateway for 2h21m. The
model asked for `find(pattern="**/gps_trilateration/index.html",
path="/Users/admin")`, and `FindTool` ran `Path.glob` synchronously on
the event loop, filtered the noise directories only after walking them,
and had no deadline. The registry's 300s ceiling is an
`asyncio.wait_for`, which cannot preempt synchronous code, so every
session and every subagent on the gateway stopped until the walk came
back (`gateway.log`: `Tool result: find duration=8476519ms`). `list_dir`
with `recursive=true` had the same shape through `rglob`.

The fix gives the three tree-walking tools one walk,
`raven.agent.tools.tree_walk`, with these bounds:

- noise directories (`node_modules`, `.git`, ...) are pruned before they
are entered, not filtered afterwards -- the pruning tests spy on
`os.scandir` and assert the noise directory is never opened;
- the walk yields one entry at a time and checks a 20s wall-clock budget
(the value grep's fallback already used) before every entry, so whatever
the caller does with one entry -- the `stat` per `find` match, the read
per grep file -- is covered by the check on the next. The budget cannot
be overrun by one large or slow directory: the probe with eight matches,
a 30ms stat each and a 50ms budget returns 2 matches and the notice.
When the budget is hit, `find` and `list_dir` append a `PARTIAL result:
... traversal budget ...` clause to their trailer, and a deadline that
fires before any match is not reported as a clean `No files found` /
`Directory is empty`;
- every caller runs the walk in `asyncio.to_thread`, so the loop keeps
serving other sessions while the walk runs. Cancelling the thread does
not stop the worker, which is why the deadline lives inside the walk.
The pure-Python `grep` fallback already had the prune and the deadline;
it moves onto the shared walk and off the loop with the others.

`find` matches each path component with `fnmatch.translate`, with a
component that is exactly `**` spanning any number of components; the
matcher is a position-set simulation (`_advance`), linear in components
times segments, so a pattern carrying many `**` cannot make one match
call slow. A pattern's leading literal components decide where the walk
starts: `src/**/*.py` begins inside `src` and never lists a sibling of
it, a pattern that is all literal (`src/lib/c.py`, `src/lib`) names
exactly one path and answers without a walk, and the prefix itself is a
match when the rest of the pattern can match nothing (`src/**` still
lists `src/`). It answers exactly what `Path.glob` answered for the same
pattern: pinned by a parametrized oracle test over twenty-seven patterns
on a fixture and nineteen on a fixture with links (a directory link out
of the tree, a link cycle, a file link, a noise directory beneath a
link), and checked by hand against `Path.glob` over `raven/` for 27
patterns including bracket edge cases and trailing slashes, 0
mismatches. Two deliberate differences: a trailing `**` also lists files
beneath its prefix (3.12's `Path.glob` listed only directories there),
and a pattern with `..` or a leading `/` is refused instead of followed,
since a pattern must not reach outside the directory the fence resolved.
A trailing slash keeps `Path.glob`'s directory-only meaning (`*/`,
`src/**/`). A symbolic link to a directory is entered where a single
component names or matches it and never under `**`, which is how
`Path.glob` read a pattern: `*/util/helper.py` reaches through a linked
`vendor`, `**/helper.py` does not, and a link cycle is entered once per
component the pattern spends on it, so `*/*/*/b.py` enters `src/loop ->
src` twice and stops. The walker asks its caller per link (`follow`),
`find` answers from the pattern and hands the link positions of a path
to the matcher so `**` cannot claim them, and `list_dir` and the grep
fallback never ask, staying as `rglob` and `os.walk` left them. A third
deliberate difference from the merge base: a noise directory inside a
pattern's literal prefix (`node_modules/*.js`, `src/node_modules/*.js`)
is walked, since the pattern asked for it, where `Path.glob`'s filter
dropped it; one met below the prefix is pruned as before
(`*/node_modules/*.js` answers nothing), `list_dir` on such a path lists
it, and the `find`, `list_dir` and code-flow `glob` descriptions state
that rule instead of an unconditional "skipped". Review found an earlier
wording of the two `find` descriptions one component short ("except one
the pattern starts with"), while the oracle helper already pruned below
the prefix; the sentences now say what the helper checks, and the oracle
has the `src/node_modules` shape on both sides.

The raven-code `glob` tool (`agents/raven-code/.../tools/search.py`)
parses trunk `find` output line by line and strips the trailer before
merging brace alternatives. It learns the new clause, so a cut-short
child is reported as cut short rather than as a tree that lacks the
files; its `is_notice` grammar covers the new line so it is never pasted
into a listing as a path. The code-flow tool guide
(`prompts/TOOLS_CODE.md`), the wrapper's description and its `limit`
parameter told the model that a PARTIAL `glob` result means "raise
`limit` or narrow the pattern"; a traversal-budget PARTIAL is now a
result `glob` can return and a higher limit does nothing for it, so all
three now tell the two notices apart. The seeded copy of the guide
refreshes through the receipt `seed_guide` keeps beside it, so no legacy
digest is added.

Fixed in passing, and now pinned: recursive `list_dir` filtered `rglob`
results on the components of the absolute path, so a workspace beneath a
directory named `build`, `dist`, `venv` or another noise name listed as
"Directory ... is empty" (reproduced at the merge base under
`<tmp>/build/proj`; this head lists it). The shared walk prunes below
the listed path only; `find` and the grep fallback already did.

Not changed: the 20s value. It is the budget grep's fallback already ran
under; this PR does not re-measure it, it makes it hold for every entry
of every walk.

## Type

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

## Verification

At head 8dade176, on origin/main at d50a13c1 (nine commits: the walk,
the grep pin, the changelog, the per-entry budget with the prefix start,
the literal-directory case, the symbolic-link reading with the
noise-prefix wording, the noise-name-above-the-path pin, the guide
wording, and the prefix-rule wording; `git range-diff` against bb836988:
all nine replayed `=` onto the moved main, which conflicted only at the
changelog anchor and touches no file this PR touches):

```
uv run pytest tests/test_file_search_traversal_guard.py tests/test_agents_code_tools_plugin.py \
  tests/test_search_tools.py tests/test_tools_workdir.py tests/test_tool_registry_execute.py tests/test_filesystem_tools.py -q
# 203 passed
COLORTERM=truecolor uv run --frozen --python 3.12 --all-extras pytest -q --ignore=tests/integration   # in a throwaway worktree
# 24652 passed, 110 skipped in 382.30s (0:06:22) at head 8dade176, in a throwaway worktree with COLORTERM=truecolor
uv run pytest tests/test_agents_code_launcher.py tests/test_agents_code_tools_plugin.py -q   # the guide's seeding and wording tests, the glob wrapper
# 119 passed
make lint-python lint-imports lint-types lint-deps          # all pass
git diff --check origin/main...HEAD                         # clean
scripts/check_source_language.py origin/main...HEAD         # exit 0
scripts/check_large_files.py origin/main...HEAD             # exit 0
git merge-tree --write-tree HEAD origin/main                # clean
```

Revert-to-red, with the tests kept (101 tests in
`test_file_search_traversal_guard.py` +
`test_agents_code_tools_plugin.py`):

```
the three production files reverted to the previously reviewed head (fd5663ee)   19 failed
file_search.py + filesystem.py reverted to origin/main, tree_walk.py removed      collection error
```

Mutation, each mutant applied alone, control restored between runs:

```
deadline checked once per directory (the reviewed placement)   10 failed
walk starts at the root instead of the pattern's prefix          2 failed
trailing slash matches files too                                 4 failed
a pattern naming one file still walks                            1 failed
the prefix itself is never a match                               7 failed
a pattern naming one directory walks beneath it                  1 failed
control (nothing mutated)                                      101 passed
```

From the first review round (still holding at this head): find without
`to_thread` 1 failed; list_dir without `to_thread` 1 failed; grep
fallback without `to_thread` 1 failed; pruning removed 6 failed; fork
drops the PARTIAL clause 1 failed.

Fourth round, the symbolic-link reading
(`test_file_search_traversal_guard.py` +
`test_agents_code_tools_plugin.py`, 128 tests, `-n 0`; a mutant that
lets `**` sweep a link, or forgets the link positions, re-enters the
cycle until the OS refuses the path and answers paths `Path.glob` never
did):

```
baseline                                                 128 passed
MUTANT  ** may sweep a link                                8 failed   (7 oracle cases, and the link the pattern ends at is opened)
MUTANT  find never asks to enter a link                    6 failed   (the six oracle patterns that pass through a link)
MUTANT  a link is entered even when the pattern ends at it 1 failed   (scandir spy on **/vendor)
MUTANT  ancestor links forgotten (links_of empty)          1 failed   (a cycle case answers a path Path.glob never did)
MUTANT  the walker consults follow but never enters        7 failed
MUTANT  each followed root gets a fresh deadline           9 failed   (every deadline test, and the walker's one-budget test)
REVERT  production files to reviewed head d67184c8         7 failed
CONTROL restored                                         128 passed
```

Revert-to-red for the noise-name pin: with
`raven/agent/tools/filesystem.py` at the merge base and the test kept,
`test_a_noise_name_above_the_searched_path_hides_nothing` fails on the
`Directory ... is empty` answer (1 failed); at this head it passes. The
`agents/**` change is two prose strings and a guide line, outside the
coverage gate's `raven/**` and `plugins-dist/**` pathspecs; the guide's
name-list test and its seeding tests (`test_agents_code_launcher.py`)
cover the file.

The prefix rule is pinned by mutation, the other policy (prune a noise
directory inside the prefix) against the two guard files (131 tests, `-n
0`):

```
baseline                                                 131 passed
MUTANT  a noise directory inside the prefix is pruned    5 failed
      test_find_matches_what_path_glob_matched[node_modules/**/*.py], test_find_matches_what_path_glob_matched[node_modules/*/], test_find_matches_what_path_glob_matched[node_modules/*/d.py], test_find_matches_what_path_glob_matched[node_modules/x/d.py], test_find_matches_what_path_glob_matched[src/node_modules/*.py]
CONTROL restored                                         131 passed
```

The symlink oracle is the reviewer's own test shape over a fixture with
links: `vendor -> outside/real`, `src/loop -> src`, `alias.py -> a.py`,
a `node_modules` beneath the link; 19 patterns, 0 mismatches against
`Path.glob` on 3.12, plus a scandir spy pinning that `**/vendor` never
opens the link, a walker test pinning that the default walk yields a
link and does not enter it while a `follow`ed link is walked after the
tree under one deadline, and a `list_dir` and grep test pinning
`rglob`/`os.walk` parity through a link.

- [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` entry)

## Risk

User-visible behaviour changes, all in tool output the model reads:

- `find` and `list_dir` (recursive) can now return a partial listing
with a `PARTIAL result` clause in the trailer where they previously
either returned everything or hung. The clause tells the model the
absence of a match is not conclusive and to narrow the search.
- A path-prefixed `find` pattern spends its budget only inside its
prefix, so on a large tree it finds what a root-anchored walk used to
miss.
- `find` refuses patterns containing `..` or starting with `/` with an
`Error running find:` line; `Path.glob` used to raise on the second and
could climb on the first.
- `find` with a trailing `**` lists files as well as directories beneath
the prefix; a trailing `/` lists directories only, as before.
- `find` reaches through a symbolic link to a directory where a literal
or single-wildcard component names or matches it, as it did at the merge
base; the earlier revisions of this PR had lost that and returned a
clean miss with no notice. `**` never enters a link, as before.
- A noise directory inside a `find` pattern's literal prefix, or named
as the `list_dir` path, is walked: `find('node_modules/*.js')` and
`find('src/node_modules/*.js')` answer its files and
`list_dir('node_modules', recursive=true)` lists it, where the merge
base answered nothing and "empty". One met below the prefix is pruned as
before. Both descriptions state the rule.
- Recursive `list_dir` on a workspace beneath a directory named like a
noise directory (`/tmp/build/proj`) lists it instead of answering "is
empty".
- The code-flow `glob` description, its `limit` parameter and the tool
guide tell a limit cut from a traversal-budget PARTIAL; the notices
themselves are unchanged.
- `list_dir` flat listings are unchanged; the empty-directory message is
unchanged.

Rollback: revert the squash commit. The new module has no other
consumers, and no state or schema is involved.

- [x] Security impact considered (a pattern can no longer climb out of
the fenced directory via `..`; a directory link is entered exactly where
`Path.glob` entered it at the merge base, one non-`**` component, and
never under `**`, so the fence's reach is what it was and not wider;
`list_dir` and grep never enter one)
- [x] Backward compatibility considered (the fork's trailer grammar is
extended, not changed; existing fork tests pass unchanged)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-22 10:59:01 +08:00
zhanghui
4623f2256e fix(*): keep archiving, fix the usage counts, and start conversations in smart mode (#585)
## Summary

Three reports from acceptance testing, one branch. All three were
reproduced on a
real host before anything was changed, and the fixes were walked through
the same
host afterwards.

**Archiving did not hold, and the archive page did not show it.** Three
separate
causes:

- `session.archive` persisted by saving the whole session, which
rewrites the
metadata record from that process's copy of it. A page and a terminal
over one
home are two managers over one file: the other one had loaded the
conversation
before the archive, so its copy carried no `archived` key, and its next
save of
anything spoke for a flag it had never seen. The verb now appends the
one key,
the way the auto-archive pass already did. `append_metadata_patch`
reports
whether the patch reached a file, which is what lets the verb answer
`pending`
  truthfully.
- The rail read that `pending` as a success, so a conversation with no
transcript
  yet left the rail although nothing had reached the disk.
- The archive page asked `session.list` for fewer channels than the rail
lists, so
  an archived scheduled run was invisible there and unreachable here.

**The usage page reported no data.** It read its range two ways. Calls,
cost and
the per-model table came from the daily telemetry files, dated per day;
the tool
table was topped up by reading session transcripts, and a transcript
counted as
in-range when its file mtime was. A conversation touched recently
therefore handed
the range every tool call it had ever made while its model calls, dated
per day,
stayed outside it -- thousands of tool calls beside no model calls at
all, which
reads as a page that failed to load. Telemetry has carried a row per
tool call for
a while, so the transcript fallback only ever covered older
conversations; dropping
it leaves one source and one reading of the range.

**A conversation now starts in the smart permission mode.** `ask`
stopped the agent
on every mutation, and a prompt answered by reflex is not a gate. Smart
is not the
weaker setting it sounds like: builtin denials and user deny rules hold
in every
mode, the reviewer speaks only for the ask tier, and a reviewer that
cannot run
leaves the call at the same prompt `ask` would have shown.

**Shared by the first two:** opening the settings dialog reloads the
config
snapshot, and neither the archive list nor the usage totals come from
it. Nothing
dropped them, so a dialog opened once held its first answers for the
life of the
page. Both are now cleared on open, which their own lazy loads already
key off.

**What this does not close.** `save` rewrites the whole metadata record
from one
process's copy of it, and this branch changes who can do that rather
than whether
it can be done. Archiving no longer erases what another writer added;
five other
verbs still can (pin, rename, the per-conversation model and permission
mode, the
ACP usage owner), and so does the turn path, which saves on every
message and is
the one a user actually hits. So a conversation archived from one client
and then
typed into from another still comes back.

Closing that needs `save` to stop speaking for keys it never touched,
and removal
is currently expressed by omission -- unpin, `title_auto` and
`output_limit_turn_at`
each delete a key by not writing it, so a merge on save would resurrect
them. They
have to become explicit false values first. That work is a round of its
own rather
than a fourth topic on this branch.

The ACP hosting pins the ask tier rather than inheriting the new
default: the
person there is in an editor watching an agent work on their checkout,
and the
prompt is how they see each write before it lands. The four other
products carry no
permissions block and were written as things raven dispatches rather
than things a
person drives, so they follow trunk.

## Type

- [x] Fix
- [x] Feature

## Verification

Backend, after the rebase:

```
uv run pytest tests/test_rpc_session.py tests/test_rpc_settings.py \
  tests/test_rpc_config.py tests/test_config_live.py \
  tests/test_rpc_contract_shapes.py tests/test_session_manager.py -q
# 498 passed

uv run ruff check raven tests          # All checks passed
uv run ruff format --check raven tests # 1636 files already formatted
make check-source-language             # pass
make check-large-files                 # pass
```

Frontends, after the rebase:

```
cd ui-web && npx vitest run            # 189 files, 2592 passed
cd ui-web && npx tsc --noEmit          # clean
cd ui-tui && npx vitest run            # 144 files, 2074 passed
cd ui-tui && npm run type-check        # clean
```

Every new or changed case was checked against the base revision with the
fix
removed, by restoring the file from HEAD rather than stashing, and the
files were
compared byte for byte afterwards:

| Case | On base |
|---|---|
| `test_archiving_keeps_a_key_another_writer_added` | fails: the foreign
`pinned` key is gone after the archive |
| `test_usage_counts_a_tool_call_on_the_day_it_was_recorded` | fails: a
transcript touched today adds two tool calls the range never saw |
| `opening again clears what the pages fetched for themselves` | fails:
both fields survive the reopen |
| `says it failed when the call answers that nothing was persisted` |
fails: `pending` is read as a success |
| `archived lists the archived sessions of every channel the rail shows`
| fails: the call carries no channels |

Real host, `raven serve` on a temporary `RAVEN_HOME` with real provider
credentials,
driven through the built page:

| Check | Before | After |
|---|---|---|
| Archive a conversation from the rail, then reopen Settings > Archive |
the list still shows the previous answer | the conversation is at the
top of the list |
| Telemetry rows on disk vs the usage page's call count, dialog reopened
without a page reload | 13 on disk, 12 on the page | 13 and 13 |
| Tool table against the `tool_call` rows for the range | inflated by
whole transcripts | `exec` 4, the number of rows |
| A fresh page with no `permissions` key in the config and no stored
pick | chip reads "ask" | chip reads "smart" |
| `mkdir -p /tmp/...` through `exec` on that host | approval dialog,
directory not created | reviewed and allowed, directory created |

The last row is the pair that makes the check able to fail: the same
command was
run with `permissions.mode` set to `ask`, and it stopped at the prompt.

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

## Risk

The permission default is the user-visible change: an install that has
never
written `permissions.mode` moves from being asked about every mutation
to having
the reviewer speak for the ask tier. Denials and deny rules are
unaffected, and a
reviewer that cannot run still leaves the call at the prompt. Anyone who
wants the
old behaviour writes `permissions.mode: "ask"`, and rolling the default
back is the
one literal in `PermissionsConfig.mode` plus the three places that
repeat it where
they cannot read it.

Usage numbers will change for anyone whose home has conversations older
than the
day telemetry started carrying tool rows: their tool counts drop to what
the range
actually saw. That is the point of the change, but it will look like a
loss.

`append_metadata_patch` gained a return value. The existing caller
ignores it, so
nothing else moves.

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

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-09-22 01:05:18 +08:00
Tong Li
608cedf180
feat(browser): give the model the shared browser, and a desktop MCP server to reach (#578)
## Summary

The browser existed on every side except the model's: `raven/browser`
drives a
Chromium the panel streams over CDP, and `browser.*` RPC gives the
reader hands
on it, but `raven/agent/tools/` had no browser tool at all -- a model
asked to
open a page had nothing to call. This registers eight `browser_*` tools
over
that same driver, with no MCP hop, so the page the model drives is the
page the
panel shows and a human can take the keyboard mid-task.

Desktop control reuses `macos-mcp` through the MCP client that was
already
there; the only new code for it is a market catalog entry.

What the tools add beyond the driver:

- **Reading back.** Every acting call returns the page as it is
afterwards
(url, title, the actionable refs, the visible text), so the next call
can be
aimed without a separate read. `browser_screenshot` is the one that
costs an
  image and is asked for on purpose; it goes out as an image block.
- **Who is acting.** Each call names an owner -- the sub-agent run in
flight,
else the conversation -- and the driver binds that owner to a tab. Two
agents
work in two tabs, neither can activate or close the other's, and a popup
a
click opens becomes the opener's tab. A reader's own clicks carry no
owner:
they are stamped, and the owner's next readback says the user touched
the
  browser, once.
- **Permissions.** Reading and navigating default to allow, on the
`web_fetch`
  reasoning (opening a page is a GET the agent could already make, and
`raven.browser.policy` refuses what a GET must not reach). Clicking,
typing
and pressing ask, keyed by site rather than by ref, so one approval
covers a
  site for the conversation.
- **Config.** `tools.browser.headfulOnAgentUse` pops the shared browser
out
into a real window on the model's first use. Off by default: a server
has no
  desktop to pop into.

The tool surface grew, so the `reserved_tools` tripwire moved:
descriptions
were trimmed first (~1270 to ~1090 tokens) and the bound raised from
6000 to
7400 against a measured 7115, with the trade written beside it. The
schemas are
only present where the browser extra is installed; without playwright
the tools
report themselves unconfigured and never reach the request.

No ui-web changes are in this PR. The web UI side of this work (a
browser pane
in the desk, a per-tab miniature, docking) is written against surfaces
that
`refactor/ui_web_architecture` removes, so it waits for that branch to
land.

## Type

- [x] Feature

## Verification

- `uv run pytest tests/ -q` -> 23755 passed, 121 skipped, 1 failed. The
failure
is
`test_cli_onboard_commands::test_clearing_does_not_disturb_a_key_the_user_exported_themselves`,
which reads the developer's own shell environment and fails the same way
on
  an unmodified `main` in this checkout.
- `uv run pytest tests/integration/test_browser_tools_real_web.py -q` ->
6
  passed against a real Chromium and a local form: fill and submit, a
screenshot arriving as an image block, two owners in two tabs with
neither
able to take the other's, a read leaving the front tab where the last
actor
put it, a `target=_blank` popup landing its opener on the new tab, and a
scripted model driving `AgentLoop`'s default tools end to end -- the
gate
asking once for the site, the grant covering the click that follows, and
the
  panel's `browser.frame` returning the page the model left.
- `uv run ruff check raven tests`, `uv run ruff format --check raven
tests`,
`uv run lint-imports`, `make check-source-language`, `make
check-large-files`
  -> clean.
- Desktop side exercised by hand through raven's own MCP client, over
stdio and
  over streamable-http with a bearer token: launch Calculator, read its
accessibility tree, click 2 + 3 =, read the result back. Screenshots
arrive
  as image blocks.

Not verified: the desktop flow was driven by a script rather than by a
model in
the loop; sub-agents that run in their own process (the ACP and cli
lanes) have
their own `Browser` singleton and are not given these tools; Windows and
Linux
desktop executors were not chosen.

## Risk

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

Notes. The acting verbs sit on the ask tier by default and a grant is
scoped to
a site and a conversation, so an approved click on one host does not
carry to
another. Navigation goes through the existing outbound policy. The
desktop MCP
server runs locally under `uvx` and needs macOS Accessibility and Screen
Recording grants, which the operating system asks for itself; the
catalog entry
is opt-in like every other market entry. Nothing here changes an
existing
default: without the browser extra the tools are absent, and with it the
only
new always-on cost is the tool schema.

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-21 20:28:04 +08:00
ypflll
dbe259f6d7
refactor(*): close out the participant contract the five plugins now write (#495)
## Summary

#469 gave a bundled sub-agent nine verbs in place of six hook phases.
Reviewing it turned up a
list of things the contract said but did not yet do, and this PR closes
that list. No behaviour
change is intended: the point is that the same seam becomes something a
role can replace and
something a generated judgement can enter.

**1. The roles are named apart from the verbs, and `observe` is gone.**
`ActionModule.review`
and the participant's `review` were two different things a line apart.
The four delegating role
methods now say what they do -- they ask -- and the verbs keep their own
names, so `ask_review`
asks `review`. `observe` is removed: a verb with no return value decides
nothing and can only
keep state a participant is forbidden to keep. `outbound` says on its
own docstring that it is
the one verb with no role seat, and `StepView` gains `phase`, so a verb
asked at two moments
reads which one it is rather than inferring it from whichever other
field happens to be set
(`tools_ran` becomes a property derived from it, so the two cannot
disagree).

**2. The three verbs the seat was applying itself get a seat.**
`system_addendum`, `archive` and
`select_tools` were rendered straight onto the hook decision, so each
was the one judgement in
the set with nowhere to compose two participants, nowhere to vet what
came back, and nothing a
replacement role could decide. They join the other four:
`MemoryModule.ask_system_addendum` / `ask_archive` and
`CapabilityModule.ask_select_tools`. The
seat is not the point where narrowing takes effect -- `select` still is,
and the registry still
adjudicates every call -- so a participant narrows after the product has
spoken and never instead
of it.

**3. A participant answers with plain data.** `review`, `intake` and
`system_addendum` returned
host classes (`Verdict`, `Intake`) and `salvage` returned `Any`.
`Accept`, `Resample`, `End` and
`Intake` are now builders returning plain mappings, the host reads one
back with `read_verdict` /
`read_intake`, and an answer it cannot read is silence rather than a
refusal. That is what makes
the third invariant real and what lets a judgement compiled from source
answer the same verbs a
plugin does -- it can build a `dict`; it cannot build a host class.

**4. A dispatch's judgements are a participant.** `judge` was the one
verb a role answered by
reading the dispatch's own `checks` and `code` for itself. A Charter now
enters as a participant
like any other, `ActionModule.ask_judge` takes the list, and the merge
is a veto so the first
refusal decides. The participant list becomes the only route an external
judgement takes, which
is the thing step four needs: a judgement generated for one dispatch
joins the same list without
a second way in.

**5. The rename.** `AgentConduct` is `AgentParticipant`,
`contracts/agent_conduct.py` is
`contracts/participant.py`, `agent/hook/conduct.py` is
`agent/hook/participant.py`, and
`agent/harness/conducts.py` is `agent/harness/participants.py`.
"Conduct" was already taken in
this tree -- raven-code's Coding Conduct prompts are a different thing
-- and a reader hitting both
had no way to tell them apart. The rename was done symbol by symbol, not
by search and replace,
for exactly that reason.

**7. Review (LivXue, at 3a1bf07c).** The `judge` disclosure had reached
two of its four homes;
the other two are `ActionModule.ask_judge` on the paper and
`DefaultAction.ask_judge`, and they
survived because they phrase the claim without naming any symbol the
earlier fix touched. The test
meant to pin that claim could not fail for the reason it was written --
it asserted the refusal
rather than the argument, and built a `ParticipantHook` it dropped --
and now asserts what the
registry hands the role, mutation-checked by wiring a participant
through. `compose_judge`
exploded a one-sentence `str` refusal into one refusal per character,
because `str` satisfies
`Sequence[str]` structurally; `charter_code.run_judge` coerced it where
this composition used to
live and the handling did not move with it. Two records corrected: the
type-only
`raven.contracts` -> `raven.agent` edge, the first in the tree and the
price of moving `Verdict`
and `Intake` off the paper, is now written beside the import contract it
bends rather than left to
be discovered; and the ledger entry for the 3,200 -> 3,410 bump is
restored to the names and count
it was written with. Not taken: reading `step.phase` at
`research_flow/flow.py:1000` -- the gate
chain's phase vocabulary and `StepView.phase` coincide on
`after_iteration` only, and that call
site wants `before_execute_tools`, which is the key `_phase` dispatches
on.

**6. What the paper was claiming and not doing.** Read back over the
seam afterwards rather than
over the diff. ``judge`` read as though a plugin's override were asked
ahead of a dispatch's own
rules; it is not, and cannot be as written, because the party that asks
the verb is
``ToolRegistry.execute``, which is not the hook chain and holds no
handle on this turn's
participants. The merge order is real; nothing puts a plugin in the
list. Wiring one through is a
turn-scoped register this change does not add, and it would start
refusing calls that run today,
so it is named on the paper and pinned by a test instead.
``max_iterations`` had lost its
docstring to the property inserted between the field and the string
documenting it. No executable
line moves in this commit: the module's AST, docstrings stripped, is
identical to its parent's.

CONTEXT.md's entry is rewritten to the end state, including the two
kinds of role method, the two
verbs that are exceptions, and the note that the Coding Conduct prompts
are unrelated.

One item from the same list is deliberately not here: a `planning.*`
block on the dispatch
parameters. It is not a contract closeout but a new model-facing field,
and it needs the
generator's schema and prompt to move with it.

Contract papers: `participant.py` and `harness.py` are both factory-loop
tier, so the
contract-tier digest and `CONTRACTS_VERSION` do not move.
`CONTRACTS_LINE_CEILING` 3,440 to
3,470 to 3,500 to 3,540 to 3,550 to 3,570, each bump with its own review
paragraph in
`tests/test_kernel_budget.py`. The chain was recomputed after rebasing
onto #410, which added
seven lines to `loop_hooks.py` inside the old headroom and left one
commit here with one line of
it; every "Measured at" figure in that file is the count at that commit.

## Type

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

## Verification

Gates, run at each of the seven commits:

```
uv run ruff check --no-cache raven evolver agents plugins-dist tests scripts
uv run ruff format --check --no-cache raven evolver agents plugins-dist tests scripts
uv run lint-imports
uv run pytest -q
npx commitlint --from origin/main --to HEAD --config commitlint.config.cjs
uv run python scripts/check_commit_messages.py origin/main..HEAD
uv run python scripts/check_source_language.py origin/main..HEAD
uv run python scripts/check_large_files.py origin/main..HEAD
```

Import contracts: 10 kept, 0 broken. The suite is green: the failures
this machine shows are the
same ones it shows on an unmodified `main` in the same worktree layout
(missing browser and
optional packages), and this branch adds none.

Behaviour preservation. The oracle is the hook seam itself. `main` and
this branch were run under
the same scripted provider, outputs normalised for nonces and temp
paths, then byte-compared.
Four scenarios, all identical:

- the five-plugin hook seam, every phase's decision and metadata per
iteration (23,840 bytes)
- a whole turn with no playbook: host turn, spawned sub-agent, tool
calls and refusals
- a playbook-on worker lane in process, including the charter refusals
- six window-shrink scenarios

This is the seam the change is about, and identical output across it is
what "no behaviour
change" means here -- it is not a claim about paths the four scenarios
do not reach.

Two claims had no assertion anywhere and now do. ``phase``, and the
``tools_ran`` derived from
it, are what three of the five bundled plugins branch on -- ppt on its
close, oncall on its
counter, research on which gate runs -- and a mistyped phase string at
one of the six call sites
would have changed what they do with a green suite. The read-only test
now also covers
``mode_overlay``, the one frozen field it skipped. All three assertions
were mutation-checked:
mislabelling a phase, deriving ``tools_ran`` from the wrong one, and
dropping the freeze each
turn exactly their own test red.

New tests, each written against a claim the contract now makes rather
than against the code:
a participant cannot write through the `StepView` it is shown; an answer
the host cannot read is
silence, not a refusal; a participant that answers with a mapping it
built itself is understood;
every verb with a seat goes through its role rather than around it,
asserted as a set so a new
verb that bypasses its role fails; two seats in one chain each keep one
addendum; two turns in
flight keep their own participants; a bound role decides what a
participant's verdict does; a
plugin's own judgement speaks before the dispatch's, and a silent
participant lets the next one
speak.

Real model, Sonnet 4.5 through OpenRouter, on this branch: a query
generates a playbook, two
sub-agents are instantiated and run, each writes its `summary.md` under
its own fence, and both
results are announced back to the originating session.

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

## Risk

For plugin authors: the six-phase `AgentHook` is untouched and a plugin
shipping one keeps
working. A plugin written against #469's `AgentConduct` needs the new
names and, if it answered
with `Verdict` or `Intake`, the builders instead -- the five bundled
plugins are ported here and
are the worked examples.

One verb narrowed, and silently for a plugin that used the width.
`salvage` was annotated
`Any | None` and `compose_salvage` returned whatever was not None; it is
now `str | None` and only
a non-empty string is taken. A third-party plugin that salvages with a
reply object rather than
text stops being heard rather than raising -- which is the third
invariant working as written, and
worth knowing before upgrading. The narrowing is deliberate: `salvage`
answers the text a turn
sends when it produced none, and `Any` was not a contract.

For anyone replacing a harness role: the four delegating methods are
renamed and four more are
added, so a replacement written against #469 needs them. `bind()` names
the missing member at
assembly rather than failing inside a turn.

Rollback is a revert of the merge commit. Nothing persisted on disk
changes shape.

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

## Related Issues

Follows #468 and #469.

Generated with Claude Code (https://claude.com/claude-code)

---------

Co-authored-by: yao pengfei <yaopengfei@shanda.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-09-20 11:36:35 +08:00
Tong Li
f633127ef4
fix(raven-code): serve the skill route its menu advertises, and remember like the fleet (#493)
## What

Two defects in the shipped `agents/raven-code` profile, both inherited
from the retired vendored twin's comparison hygiene and both silent at
runtime.

**The skill route was advertised but dead.** Trunk's skills are
pull-discovery: a name+description menu rides the user envelope, and its
footer tells the model, verbatim, *"Read one with read_skill(id); search
differently with find_skill"* (`raven/context_engine/scent.py`).
raven-code kept `read_skill`, `use_skill` and `find_skill` in its
disable rows, so the menu taught a route that answered "unknown tool" --
while the router still ran, retrieval still happened, and every body it
fetched was dropped unread, with nothing logged to say so. All three
tools register off the skill registry alone
(`raven/agent/loop/wiring.py`); a Hub endpoint only adds their `hub/`
branch, and `hub` itself stays disabled.

**Memory was double-off.** design, oncall, ppt and research all ship
`memory.backend: "everos"`; raven-code alone shipped backend `null`
**plus** the `everos-memory` plugin opt-out -- the one shipped agent
that could not remember. The identity was already `raven-code` in all
three places (`memory.userId/agentId`, the plugin slice,
`subagent.json`); only the two off-switches go.

The redundant `skillForge` block goes too: its two knobs
(`rewriteEnabled`/`llmGateEnabled`) are only built under push discovery
(`factory.py`), which no shipped agent runs, and the other four agents
carry no such block.

**Review follow-up (second commit):** enabling everos-memory also offers
the plugin's `understand_media` tool through the entry-point lane, which
the hermetic face fixture cannot see -- an unledgered 14th tool in
production. Same remedy as the playbook rows that board past the fixture
the same way: the disable row is the pin, and `PLUGIN_LANE_WITHHELD`
puts the lane on the ledger. raven-research holds the same line; design,
oncall and ppt serve the tool deliberately.

## Fleet posture after this change

| | everos | read/use/find_skill | skillForge block |
|---|---|---|---|
| design / oncall / ppt / research | on | design serves all three | none
|
| **raven-code (before)** | **double-off** | **all three disabled** |
explicit false/false |
| **raven-code (after)** | on | all three served | none |

## Tests

The tool face moves on its ledger, not by luck
(`tests/test_agents_code_launcher.py`): `SKILL_LANE_TOOLS` joins the
face arithmetic, `find_skill` leaves `TRUNK_NEW_WITHHELD` (five stay
withheld), `PLUGIN_LANE_WITHHELD` pins the plugin lane, and the everos
posture test is rewritten from *stays-factory-off* to *ships-on*. The
face itself is hermetically rebuilt from the render: 13 tools = the
previous 10 + the three skill tools, verified by name and schema.

- `tests/test_agents_code_launcher.py`: 70 passed
- reviewer's set (`test_agents_code_launcher` +
`test_agent_loop_skill_tools` + `test_context_scent` +
`test_everos_plugin_discovery`): 110 passed
- ruff check + format: clean

---------

Co-authored-by: litong <238663200+TongLi31@users.noreply.github.com>
2026-09-18 17:32:55 +08:00
ypflll
6d8c36385b
refactor(*): let a sub-agent write a conduct instead of six hook phases (#469)
## Summary

Follows #468 (merged as `869ad78a`), which moved the charter reads and
the window's mid-turn shrinking onto the harness roles. This branch is
rebased onto `main` and carries only its own three commits.

A sub-agent's product logic was an `AgentHook` subclass: six phase
methods over a fourteen-field context it could write, with the turn's
own state kept in the context's free-form `metadata` dict. Surveyed
before this change, the five bundled plugins had 71 phase methods, 42 of
them doing real work, reading fourteen context fields and using six
decision fields. Every one of them fits a small set of verbs. This PR
makes those verbs the contract, in three commits.

**1. A sub-agent writes a conduct instead of six hook phases.** New
factory-loop-tier paper `contracts/agent_conduct.py`: `AgentConduct`
with nine optional verbs (`intake`, `select_tools`, `advise`,
`system_addendum`, `review`, `salvage`, `outbound`, `archive`,
`observe`), answered against a read-only `StepView` of fourteen fields,
with `Intake` and `Verdict` (Accept / Resample / End) as the answers and
a `ConductFactory` because the host builds one conduct per turn.

It sits beside `loop_hooks` rather than replacing it. The six phases
remain the loop's *timing* contract: when the loop asks, in what order,
what a refusal does. This is the *judgement* contract: given one step,
what does this agent say about it. `ConductHook` seats one in the other,
so a plugin that still ships a plain `AgentHook` keeps working and the
composite's ordering, merging and rollback are untouched.

All five bundled plugins are ported: design-engine, ppt-engine,
code-flow, oncall-flow and research-flow. Research keeps its six-phase
gate chain: the gates now subclass a plugin-private `Gate` and read a
`GateCtx` the conduct builds from its `StepView` and its own
turn-private facts, so six thousand lines of gate bodies did not move
and its wrappers still see the cross-gate state they read.

The turn's conduct and the system-message addendum it splices live in
the turn's own `metadata` dict, not on the hook: one hook instance
serves every turn a process runs, and a system turn can overlap a user
one on the same chain.

**2. The conducts seat on the roles.** `MemoryModule.intake`,
`PlanningModule.advise`, `ActionModule.review` and
`ActionModule.salvage` each take this turn's conducts, so a replaced
role decides what a plugin's judgement does rather than the seat
deciding it. The composition rules live in
`raven/agent/harness/conducts.py`: the first non-Accept verdict wins,
advice joins in order, the first salvage wins, an intake threads the
text through each conduct. `run_turn` binds the harness for the turn the
way it binds the model, and the seat falls back to the same rules when
nothing is bound, which is how a plugin test drives a hook directly.

Contract papers: the conduct paper is factory-loop tier, so the
contract-tier digest and `CONTRACTS_VERSION` do not move with it.
`CONTRACTS_LINE_CEILING` 3,200 to 3,420, each bump with its own review
paragraph in `tests/test_kernel_budget.py`.

**3. What the review found.** Eleven threads, all resolved in the third
commit. The ones that changed behaviour rather than prose:
`CodeFlowHook` kept its `rolls_back_iterations = False` (inheriting
`True` from the new base had it hold every reply behind the draft gate
instead of streaming); `StepView` now publishes deep-frozen nested
values, since freezing only the outer tuple left a conduct able to write
through to `ctx.messages`; a turn's conducts are collected at the role
boundary, so a replaced role sees one batch of the turn's judgements
rather than one call per seat; an addendum is located by its own text
rather than a saved offset, which two conducts appending system text
used to shift out from under each other; `Planning` and `Action` gained
binders, so a replacement role missing a new member is named at assembly
rather than swallowed by the composite's `except Exception`.
`CONTEXT.md` carries the Agent Conduct term and the Agent Hook entry no
longer describes what this PR replaces.

## Type

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

## Verification

Gates. CI runs these at the branch tip (17 pass, 1 skipped -- the
skipped row is the disabled Claude Mention workflow). Locally, at each
of the three commits:

```
uv run ruff check --no-cache raven evolver agents plugins-dist tests scripts
uv run ruff format --check --no-cache raven evolver agents plugins-dist tests scripts
uv run lint-imports
uv run pytest -q
npx commitlint --from origin/main --to HEAD --config commitlint.config.cjs
uv run python scripts/check_commit_messages.py origin/main..HEAD
uv run python scripts/check_source_language.py origin/main..HEAD
uv run python scripts/check_large_files.py origin/main..HEAD
```

Import contracts: 10 kept, 0 broken at each of the three commits. The
suite is green at each, and no commit adds a failure that `main` does
not already show on this machine (this checkout has the heavy extras
uninstalled, so the local run carries failures `main` carries too -- CI
is the authority, and it is green). The loop's own e2e files, which the
default selection leaves out, were run too (charter, playbook,
truncation, direct chat, fallback chain, ACP stdio): no new failure.

Behaviour preservation. The oracle for this change is the hook seam
itself: all five plugins driven through every phase of a multi-iteration
turn under the same scripted provider, recording each phase's decision
and the observers it files. Outputs normalised for nonces and temp
paths, then byte-compared.

Re-run after the review fixes at the branch tip `81e6f423` (all three
commits), against `main` at `c65c2059`:

| scenario | bytes |
| --- | --- |
| five-plugin hook seam | 23,840 == 23,840 |
| a whole turn with no playbook (host turn, spawned sub-agent, tool
calls and refusals) | 12,821 == 12,821 |
| six window-shrink scenarios | 133,371 == 133,371 |

These cover the tip, not each commit separately. The seam comparison is
the one that matters most for the third commit: its first fix changed
`rolls_back_iterations` for code-flow, which decides whether replies
stream or are held, and the seam oracle records the decision at every
phase, so an unintended change there shows as a diff rather than as
silence.

A unit test proves the seat is a real decision point rather than a
pass-through: with a lenient Action role bound, a conduct's Resample is
not applied, and Planning's advice and Memory's intake are what the loop
receives.

Real model, Sonnet 4.5 through OpenRouter, at the branch tip:

- playbook on, in-process lane: two workers, each receives the charter
(3 checks), writes its file, finishes; 26 recorded model calls
- playbook on, ACP fork lane: the charter prompt crosses the process
boundary (the fork answers ZEBRA where the task text says PONG, so the
brief reached the forked model through Memory), and a charter check
blocks `write_file` to `notes/hi.txt` against a `pathPrefix: out/` rule
- Raven-Research, a fork running the full gate chain: `plain-first:
escalated_tool`, then `sufficiency-gate: released on the pages at
iteration 4 after 2 searches / 2 pages`

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

## Risk

No user-visible behaviour change is intended, and the hook-seam
comparison is byte-identical on every phase it covers.

For plugin authors: the six-phase `AgentHook` is unchanged and a plugin
shipping one keeps working. `ConductHook` is an adapter that seats a
conduct in that same chain.

For anyone replacing a harness role: the role protocols gain `intake`,
`advise`, `review` and `salvage`, so a replacement written against the
old protocol needs them.

Rollback is a revert of the merge commit. Nothing persisted on disk
changes shape.

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

## Related Issues

N/A

---------

Co-authored-by: yao pengfei <yaopengfei@shanda.com>
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-18 14:37:11 +08:00
xfng-sd
b58cda36a2
fix(*): pin line endings to lf so windows checkouts pass the byte gates (#457)
## Summary

A Windows checkout of this repo with the default `core.autocrlf=true`
rewrites every
text file to CRLF, and two byte-exact gates in `ui-web` then fail on a
tree that is
byte-identical to the one CI passes on Linux:

- the boot-order and open-conversation node tests slice their source on
`"\n}\n"`,
which never matches a CRLF file, so the sliced function comes out empty
and 9 tests
  fail with `ReferenceError`;
- `gen-rpc-client --check` compares its own LF output against the file
on disk and
  reports permanent drift in `src/rpc/generated.ts`.

`.gitattributes` pins the checkout filter so the working tree matches
what the
repository already stores. The repository stores LF today, so this adds
no
renormalization diff: `git add --renormalize .` over the whole tree
stages nothing
beyond the two files in this PR. Only the checkout filter changes.

`ui-web/build.py` is the other half of the same defect. It assembled the
page under
Python's default newline translation, so `dist/index.html` came out CRLF
on Windows
even from an LF source tree, and `check-page.mjs` could no longer
extract the script
payloads (its `<script>\n` anchor needs the LF to be the next byte).
That artifact
ships inside the wheel, so it must not depend on which platform
assembled it.

## Type

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

## Verification

Run on Windows 11 with `core.autocrlf=true`, in a clean worktree cut
from `main`:

- `git add --renormalize .` after the change stages nothing (confirms no
  renormalization diff);
- `file ui-web/src/rpc/generated.ts` reports CRLF on `main` and LF after
a forced
  re-checkout on this branch;
- `npm run gen:check` (ui-web): `generated.ts matches the contract (178
methods)`;
- `npx vitest run` (ui-web): 108 files, 1836 tests passed;
- `npm run --prefix ui-web build && python ui-web/build.py`:
`dist/index.html` is LF;
- `node ui-web/scripts/check-page.mjs`: `OK (1,482,975 bytes, 3 scripts
parse)`;
- `node ui-web/scripts/count-shared-globals.mjs`, `check-css.mjs`,
  `check-class-namespace.mjs`: all OK.

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

## Risk

No runtime behaviour changes for users on Linux or macOS, where the
checkout already
produced LF. On Windows the working tree stops being rewritten to CRLF,
so a
contributor with existing local checkouts may see one large
renormalization touch on
the next checkout; the committed bytes do not move. The built
`dist/index.html` is now
LF on every platform, which is what the Linux-built wheel already
shipped.

Rollback is deleting `.gitattributes` and dropping the `newline=""`
argument in
`ui-web/build.py`.

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

## Related Issues

N/A

---------

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

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

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

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

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

## Type

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

## Verification

Commands run on the branch head, with their results:

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

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

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

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

## Risk

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

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

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

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

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

## Related Issues

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

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

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

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

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

## Type

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

## Verification

Commands run on the branch head, with their results:

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

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

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

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

## Risk

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

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

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

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

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

## Related Issues

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

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

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

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

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

## Type

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

## Verification

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

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

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

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

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

$ make lint-ui
exit 0

$ make check-source-language
exit 0

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

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

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

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

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

Known gaps, disclosed rather than worked around:

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

## Risk

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

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

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

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

## Related Issues

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

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

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

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

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

## Type

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

## Verification

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

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

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

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

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

$ make lint-ui
exit 0

$ make check-source-language
exit 0

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

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

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

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

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

Known gaps, disclosed rather than worked around:

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

## Risk

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

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

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

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

## Related Issues

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

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

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

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

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

## Type

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

## Verification

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

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

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

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

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

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

## Disclosed

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

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

## Risk

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

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

## Related Issues

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

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

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

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

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

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

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

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

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

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

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

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

## Type

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

## Verification

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

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

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

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

## Risk

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

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

## Related

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

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

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

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

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

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

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

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

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

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

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

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

## Type

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

## Verification

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

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

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

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

## Risk

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

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

## Related

Replaces !573 (closed). Follows !518 (stall notice) and !520 (unprompted-turn route; a wake that runs under a held prompt no longer takes it for DAG nodes).
2026-09-11 02:37:55 +00:00
0xKT
cfe806a6e0 feat(cli): onboard spends one real search on the web_search key
## Summary

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

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

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

## Type

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

## Verification

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

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

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

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

## Risk

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

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

## Related Issues

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

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

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

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

## Type

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

## Verification

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

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

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

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

## Risk

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

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

## Related Issues

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Type

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

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

## Verification

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

No user-facing surface changes.

## Risk

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

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

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

## Related Issues

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Type

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

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

## Verification

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

No user-facing surface changes.

## Risk

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

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

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

## Related Issues

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

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

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

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

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

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

## Type

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

## Verification

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

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

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

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

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

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

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

Effect on the dependency graph:

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

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

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

No user-facing surface changes.

## Risk

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

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

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

## Related Issues

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

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

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

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

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

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

## Type

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

## Verification

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

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

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

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

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

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

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

Effect on the dependency graph:

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

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

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

No user-facing surface changes.

## Risk

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

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

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

## Related Issues

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

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

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

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

## Type

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

## Verification

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

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

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

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

## Risk

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

## Related Issues

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

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

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

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

## Type

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

## Verification

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

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

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

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

## Risk

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

## Related Issues

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

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

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

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

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

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

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

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

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

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

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

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

### Both graph options are chosen, not defaulted

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

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

## Type

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

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

## Verification

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

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

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

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

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

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

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

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

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

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

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

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

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

No user-facing surface changes.

## Risk

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

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

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

## Related Issues

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

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

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

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

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

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

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

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

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

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

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

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

### Both graph options are chosen, not defaulted

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

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

## Type

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

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

## Verification

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

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

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

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

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

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

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

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

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

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

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

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

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

No user-facing surface changes.

## Risk

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

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

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

## Related Issues

N/A
2026-09-10 17:23:40 +00:00
0xKT
139110d9e0 refactor(config): the sub-agent name vocabulary seats below both sides
## Summary

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

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

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

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

### Why the check did not move up instead

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

### The cost, and the pin

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

## Type

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

## Verification

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

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

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

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

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

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

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

Effect on the dependency graph, measured before and after:

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

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

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

No user-facing surface changes.

## Risk

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

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

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

## Related Issues

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

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

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

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

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

### Why the check did not move up instead

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

### The cost, and the pin

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

## Type

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

## Verification

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

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

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

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

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

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

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

Effect on the dependency graph, measured before and after:

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

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

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

No user-facing surface changes.

## Risk

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

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

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

## Related Issues

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

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

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

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

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

## Type

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

## Verification

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

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

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

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

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

## Risk

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

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

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

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

## Related Issues

N/A
2026-09-10 12:42:53 +00:00
Handsome-wzw
7b45527b5b fix(tools): an array sent as its own JSON is still an array
## Summary

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

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

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

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

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

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

## Type

- [x] Fix
- [ ] Feature

## The edge of the forgiving is the design

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

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

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

## Not just deliver_files

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

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

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

## Verification

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

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

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

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

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

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

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

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

## Risk

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

## Related Issues

N/A

## Swept

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

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

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

## Deliberately not fixed

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

## Moved from !594

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

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

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

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

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

## Type

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

## Verification

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

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

## Risk

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

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

## Related Issues

N/A

---------

Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-05 23:58:20 +08:00
0xKT
28299e5f0e fix(*): relays on the page lane, live direct chats reported, continuation heads cut
## Summary

Four sub-agent orchestration defects found on 2026-09-08 while running the research
sub-agent from the TUI and the page; all share one root, the host loop not seeing what
its sub-agents are doing right now.

1. A sub-agent's result relay into a page session ran on the gateway spine while the
   page's own turns to that session ran on the RPC spine, so a relay and a user turn ran
   at once: the same tool calls were drawn twice and the result delivered twice, and
   `turn.send`'s one-turn-per-session guard saw neither. The RPC stack now exposes its
   turn scheduler (`RpcStack.turn_scheduler`, surfaced on `PageMount.submit`), and
   `raven.gateway.submit_router.route_submit` hands turns whose conversation carries
   the page prefix (`tui:`) to the page lane and everything else to the gateway lane.
   The sub-agent manager and the deep-research submit both take the routed callable;
   a gateway without a page keeps the gateway submit unchanged.

2. The watch-work judgement (one model call on a turn's first look) was paid on relay
   and sentinel turns, whose "last user message" is the runtime's re-injected report,
   and ran unbounded: one relay turn spent 1229 seconds in it on a reasoning runaway.
   The turn's origin now reaches the loop; a re-injected origin (SUBAGENT, SENTINEL)
   reads as no request, and the judgement is cut at 60 seconds and treated as no
   verdict. CRON and heartbeat turns are deliberately still judged: their text is the
   owner's own instruction.

3. The direct-chat handoff recorded a turn only when it landed, so an instance the user
   was mid-conversation with rendered to the main agent as "no turns yet"; the model
   read that as free and spawned onto it. The handoff now reads the manager's live
   direct turns (`live_direct_turns`) and renders an answering instance with the time
   it began answering (handle lock held) and a line saying it is the user's conversation. The spawn that lands
   behind such a turn no longer writes `running` before it holds the handle lock (it
   stays the `pending` it was announced as), and no longer takes over the instance's
   live view: `activity.watching_instance` registers only when the slot is free and
   pops only what it registered, so the direct chat's steps stay on screen and the
   spawn's appear once it runs.

4. When reasoning ran to the model's output ceiling with no content and the
   empty-response recovery fed it back as a prefill, the continuation opened on the
   rest of the cut thought and that fragment streamed and was stored as the head of the
   answer. `cut_reasoning_head` drops an opening fragment that starts in lowercase or
   whitespace and ends at the first sentence or line boundary within 200 characters;
   `ContinuationGate` holds streamed deltas until the same rule can decide, so what the
   reader sees matches what the session stores. Only a continuation after
   ceiling-cut reasoning (`finish_reason == "length"`) is treated this way.

Decisions worth knowing:

- The `tui:` prefix is spelled in `raven.gateway.submit_router` and as
  `RoutingQuestionBroker`'s default; the layer contract keeps `raven.gateway` from
  importing `raven.rpc`, so a test holds the two equal instead of one importing the
  other.
- The gateway wiring has no import seam, so its test pins the source of the mounted
  block, the same way the neighbouring cron-partition test does.
- The `subagent.status` payload shape is unchanged; only the `running` frame's timing
  moved (after the handle lock). The page's spawn card reads identity from `pending`
  and the record id from `running`, both still present.
- A CJK boundary class in the head-cut regex is spelled as escapes because the
  source-language gate reads the literal marks as non-English source.

Review round 1 (all findings non-blocking, all taken):

- The lane key is now one definition, `raven.spine.conversation_id`; the scheduler's
  method, the rpc spine and the submit router call it, and the router test pins the
  identity and compares against the scheduler's method instead of literals.
- The loop's wiring of the handoff to the manager's live turns has its own test (a bare
  `DirectChatHandoff()` went green before).
- `activity.live_instances_of` is gone: nothing called it.
- The watch-work judgement now reads any exception as no verdict, not only a timeout.
  The enclosing handler already kept the turn alive, but left the verdict unset, so a
  failing judgement was paid again on every path-touching tool call; the comment that
  claimed a raise was handled is corrected.
- A direct chat's start time is stamped once the handle lock is held, not when the slot
  is claimed, so a chat queued behind another holder is not reported as answering.
- The continuation cut deliberately leaves a continuation that opens directly on CJK
  whole (no case, so no mid-sentence signal); the comment and a test now say that the
  CJK stops end an admitted fragment rather than open one.

## Type

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

## Verification

```
uv run pytest tests -q -p no:cacheprovider -n 8 --ignore=tests/integration
  -> 7 failed, 19705 passed, 153 skipped. The same 7 fail on a detached origin/main
     worktree through the same interpreter (doctor memories path 1, NAT64 resolution 4,
     design-engine rendering 2): 0 introduced.
uv run pytest tests/test_agent_loop_empty_recovery.py tests/test_watch_work.py \
  tests/test_gateway_submit_router.py tests/test_subagent_activity.py \
  tests/test_subagent_handoff.py tests/test_subagent_direct_chat.py \
  tests/test_rpc_bootstrap.py tests/test_cli_gateway_page.py tests/test_cli_gateway_commands.py
  -> 279 passed (before round 1); round 1 adds 5 tests and removes 1, see the pipeline
uv run ruff check raven tests; uv run ruff format --check raven tests   -> clean
uv run lint-imports                                                       -> 9 kept, 0 broken
make check-source-language                                                -> exit 0
scripts/check_commit_messages.py origin/main..HEAD                        -> exit 0
```

Red-checked (fix reverted, test goes red, fix restored): activity.py alone reverted
-> `a second lane never unseats the first`; the spawn-path hunk of manager.py alone reverted
-> `['pending', 'running'] == ['pending']`; turn_path.py alone reverted -> the continuation
test sees the `Lagg in an token` head. Round 1: the handoff wiring test goes red on a bare
`DirectChatHandoff()`; the queued-direct-chat test goes red with the stamp back on the slot;
the raising-judgement test goes red with the narrow catch (two calls instead of one). The other new tests fail without their change by
construction (missing symbol or signature), which proves less and is noted as such.

Live check of the shipped page: the served `ui-web/dist` bundle booted under happy-dom in
stub and live mode against a gateway running this branch, desk mounted, no console
errors; `subagents.list` and `subagents.instances` answer as before.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (CHANGELOG, CONTEXT.md
      Handoff Block)

## Risk

- A relay into a page session now waits behind the page's running turn on that session
  instead of running beside it. That is the intended serialisation; the cost is latency
  on a relay while a long page turn runs.
- A judgement that takes over 60 seconds is dropped and the turn runs unwatched for
  that turn only; before, the same turn hung. No configuration knob: the bound is a
  class attribute.
- The head cut only runs on the continuation after a ceiling-cut prefill. A
  continuation whose intended answer begins with a lowercase word and a full stop within
  200 characters would lose that first clause; the test file names the shapes kept.
- Rollback: revert the squash commit. No persisted format changes.

- [x] Security impact considered (no new surface; routing stays in-process)
- [x] Backward compatibility considered (payload shapes unchanged; a gateway without a
      page mount is unaffected)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-09 06:25:28 +00:00
userName20260323
50ad9377bd fix(*): relays on the page lane, live direct chats reported, continuation heads cut
## Summary

Four sub-agent orchestration defects found on 2026-09-08 while running the research
sub-agent from the TUI and the page; all share one root, the host loop not seeing what
its sub-agents are doing right now.

1. A sub-agent's result relay into a page session ran on the gateway spine while the
   page's own turns to that session ran on the RPC spine, so a relay and a user turn ran
   at once: the same tool calls were drawn twice and the result delivered twice, and
   `turn.send`'s one-turn-per-session guard saw neither. The RPC stack now exposes its
   turn scheduler (`RpcStack.turn_scheduler`, surfaced on `PageMount.submit`), and
   `raven.gateway.submit_router.route_submit` hands turns whose conversation carries
   the page prefix (`tui:`) to the page lane and everything else to the gateway lane.
   The sub-agent manager and the deep-research submit both take the routed callable;
   a gateway without a page keeps the gateway submit unchanged.

2. The watch-work judgement (one model call on a turn's first look) was paid on relay
   and sentinel turns, whose "last user message" is the runtime's re-injected report,
   and ran unbounded: one relay turn spent 1229 seconds in it on a reasoning runaway.
   The turn's origin now reaches the loop; a re-injected origin (SUBAGENT, SENTINEL)
   reads as no request, and the judgement is cut at 60 seconds and treated as no
   verdict. CRON and heartbeat turns are deliberately still judged: their text is the
   owner's own instruction.

3. The direct-chat handoff recorded a turn only when it landed, so an instance the user
   was mid-conversation with rendered to the main agent as "no turns yet"; the model
   read that as free and spawned onto it. The handoff now reads the manager's live
   direct turns (`live_direct_turns`) and renders an answering instance with the time
   it began answering (handle lock held) and a line saying it is the user's conversation. The spawn that lands
   behind such a turn no longer writes `running` before it holds the handle lock (it
   stays the `pending` it was announced as), and no longer takes over the instance's
   live view: `activity.watching_instance` registers only when the slot is free and
   pops only what it registered, so the direct chat's steps stay on screen and the
   spawn's appear once it runs.

4. When reasoning ran to the model's output ceiling with no content and the
   empty-response recovery fed it back as a prefill, the continuation opened on the
   rest of the cut thought and that fragment streamed and was stored as the head of the
   answer. `cut_reasoning_head` drops an opening fragment that starts in lowercase or
   whitespace and ends at the first sentence or line boundary within 200 characters;
   `ContinuationGate` holds streamed deltas until the same rule can decide, so what the
   reader sees matches what the session stores. Only a continuation after
   ceiling-cut reasoning (`finish_reason == "length"`) is treated this way.

Decisions worth knowing:

- The `tui:` prefix is spelled in `raven.gateway.submit_router` and as
  `RoutingQuestionBroker`'s default; the layer contract keeps `raven.gateway` from
  importing `raven.rpc`, so a test holds the two equal instead of one importing the
  other.
- The gateway wiring has no import seam, so its test pins the source of the mounted
  block, the same way the neighbouring cron-partition test does.
- The `subagent.status` payload shape is unchanged; only the `running` frame's timing
  moved (after the handle lock). The page's spawn card reads identity from `pending`
  and the record id from `running`, both still present.
- A CJK boundary class in the head-cut regex is spelled as escapes because the
  source-language gate reads the literal marks as non-English source.

Review round 1 (all findings non-blocking, all taken):

- The lane key is now one definition, `raven.spine.conversation_id`; the scheduler's
  method, the rpc spine and the submit router call it, and the router test pins the
  identity and compares against the scheduler's method instead of literals.
- The loop's wiring of the handoff to the manager's live turns has its own test (a bare
  `DirectChatHandoff()` went green before).
- `activity.live_instances_of` is gone: nothing called it.
- The watch-work judgement now reads any exception as no verdict, not only a timeout.
  The enclosing handler already kept the turn alive, but left the verdict unset, so a
  failing judgement was paid again on every path-touching tool call; the comment that
  claimed a raise was handled is corrected.
- A direct chat's start time is stamped once the handle lock is held, not when the slot
  is claimed, so a chat queued behind another holder is not reported as answering.
- The continuation cut deliberately leaves a continuation that opens directly on CJK
  whole (no case, so no mid-sentence signal); the comment and a test now say that the
  CJK stops end an admitted fragment rather than open one.

## Type

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

## Verification

```
uv run pytest tests -q -p no:cacheprovider -n 8 --ignore=tests/integration
  -> 7 failed, 19705 passed, 153 skipped. The same 7 fail on a detached origin/main
     worktree through the same interpreter (doctor memories path 1, NAT64 resolution 4,
     design-engine rendering 2): 0 introduced.
uv run pytest tests/test_agent_loop_empty_recovery.py tests/test_watch_work.py \
  tests/test_gateway_submit_router.py tests/test_subagent_activity.py \
  tests/test_subagent_handoff.py tests/test_subagent_direct_chat.py \
  tests/test_rpc_bootstrap.py tests/test_cli_gateway_page.py tests/test_cli_gateway_commands.py
  -> 279 passed (before round 1); round 1 adds 5 tests and removes 1, see the pipeline
uv run ruff check raven tests; uv run ruff format --check raven tests   -> clean
uv run lint-imports                                                       -> 9 kept, 0 broken
make check-source-language                                                -> exit 0
scripts/check_commit_messages.py origin/main..HEAD                        -> exit 0
```

Red-checked (fix reverted, test goes red, fix restored): activity.py alone reverted
-> `a second lane never unseats the first`; the spawn-path hunk of manager.py alone reverted
-> `['pending', 'running'] == ['pending']`; turn_path.py alone reverted -> the continuation
test sees the `Lagg in an token` head. Round 1: the handoff wiring test goes red on a bare
`DirectChatHandoff()`; the queued-direct-chat test goes red with the stamp back on the slot;
the raising-judgement test goes red with the narrow catch (two calls instead of one). The other new tests fail without their change by
construction (missing symbol or signature), which proves less and is noted as such.

Live check of the shipped page: the served `ui-web/dist` bundle booted under happy-dom in
stub and live mode against a gateway running this branch, desk mounted, no console
errors; `subagents.list` and `subagents.instances` answer as before.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (CHANGELOG, CONTEXT.md
      Handoff Block)

## Risk

- A relay into a page session now waits behind the page's running turn on that session
  instead of running beside it. That is the intended serialisation; the cost is latency
  on a relay while a long page turn runs.
- A judgement that takes over 60 seconds is dropped and the turn runs unwatched for
  that turn only; before, the same turn hung. No configuration knob: the bound is a
  class attribute.
- The head cut only runs on the continuation after a ceiling-cut prefill. A
  continuation whose intended answer begins with a lowercase word and a full stop within
  200 characters would lose that first clause; the test file names the shapes kept.
- Rollback: revert the squash commit. No persisted format changes.

- [x] Security impact considered (no new surface; routing stays in-process)
- [x] Backward compatibility considered (payload shapes unchanged; a gateway without a
      page mount is unaffected)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-09 06:25:28 +00:00
daoxize1
5ee8a14f43 feat(rpc): attribute and filter usage by task
## Change description

Attach session and root-task identifiers to usage records. Propagate ownership through ACP child agents and asynchronous tool execution so recorded child usage can be attributed to its parent task.

Add a task selector to the usage settings page, including task titles and an all-tasks view. Prevent stale requests from replacing the selected task's results. Historical records without task identifiers remain visible only in the aggregate view.

Include usage recorded by child agents and the built-in image tool in the owning task. Extend the usage RPC schema and generated clients, and bump the contract version for the root-task field.

Validation:

- `uv run pytest tests/test_token_wise_usage_tracker.py tests/test_rpc_contract_shapes.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_rpc_schema_match.py tests/test_kernel_budget.py tests/test_contracts_two_tier_ledger.py tests/test_media_gen_tool.py -x`: 498 passed.
- `npm --prefix ui-web test -- --run src/features/settings/SettingsPage.test.tsx`: 46 passed.
- `npm --prefix ui-web run type-check`: passed.
- `make lint-python`, `make check-source-language check-large-files`, and `git diff --check`: passed.
- Both repository commit-message checks passed.

## Type of change

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

## Related issues (if there is)

N/A

## Checklists

### Development

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

### Security

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

### Code review

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

No related JIRA ticket was supplied.
2026-09-09 04:15:30 +00:00
daoxize1
135312987b feat(rpc): attribute and filter usage by task
## Change description

Attach session and root-task identifiers to usage records. Propagate ownership through ACP child agents and asynchronous tool execution so recorded child usage can be attributed to its parent task.

Add a task selector to the usage settings page, including task titles and an all-tasks view. Prevent stale requests from replacing the selected task's results. Historical records without task identifiers remain visible only in the aggregate view.

Include usage recorded by child agents and the built-in image tool in the owning task. Extend the usage RPC schema and generated clients, and bump the contract version for the root-task field.

Validation:

- `uv run pytest tests/test_token_wise_usage_tracker.py tests/test_rpc_contract_shapes.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_rpc_schema_match.py tests/test_kernel_budget.py tests/test_contracts_two_tier_ledger.py tests/test_media_gen_tool.py -x`: 498 passed.
- `npm --prefix ui-web test -- --run src/features/settings/SettingsPage.test.tsx`: 46 passed.
- `npm --prefix ui-web run type-check`: passed.
- `make lint-python`, `make check-source-language check-large-files`, and `git diff --check`: passed.
- Both repository commit-message checks passed.

## Type of change

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

## Related issues (if there is)

N/A

## Checklists

### Development

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

### Security

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

### Code review

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

No related JIRA ticket was supplied.
2026-09-09 04:15:30 +00:00
0xKT
231b270dd7 refactor(*): the vendored subagents tree retires and agents/ is the one home
## Summary

Retires the vendored fork tree (`subagents/`, ~7,500 files) and makes `agents/` the one home for the five agent products. The products were already thin launchers that render a config and exec the installed raven's own `raven acp`; this PR removes the frozen fork checkouts they replaced, migrates every consumer, and keeps the A/B verification power as byte snapshots.

Key decisions:

- **A side becomes a record.** The fork trees are deleted; the files the parity guards compare against live on as byte snapshots under `tests/fixtures/vendored_fork/` (added to ruff's exclude so a record can never be reformatted). The research flow's oracle is the fork's frozen measurement (`research_parity_probe.json`), a constant by construction.
- **Config floors v6 and v7.** Stored roster rows that pointed into the retired tree are migrated in place (floor six): rows whose folder maps to a shipped product are re-aimed at `agents/`, fork-era rows that cannot be re-aimed are left untouched and reported, unparseable rows get a fix-by-hand notice. Verdict-driven, path-root anchored, with a stamped sidecar so each pass runs once.
- **The research product reclaims its name (floor seven).** The `-NG` suffix existed only to coexist with the fork's own row, so it retires with the fork: registered `Raven-Research-NG` rows rename to `Raven-Research` on load; if a fork-era row still holds the name, the advisory repeats and the stamp holds at floor six, so the rename completes on a later load once the name frees (never two rows under one name). Display name only -- the machine id `raven-research-ng` (state root, ACP home, everos identity, the `RESEARCH_NG_*` variables) is a stable key and stays. The v6 name gate maps the research folder to None (never re-aim): the fork's research rows were cli-kind on a different flow, and after the rename a name match would select exactly the rows the gate exists to refuse.
- **Guards retire with their subject.** The vendored-invariant and vendored-subagents guard suites, their Makefile/pre-commit/CI hooks, and the fork-era install stage in `install.sh` are removed. The external-consumer tripwire now derives the promised surface from the five product installers and the charter's uninstall recipe (`add_third_party_subagent` and `remove_third_party_subagent` today) instead of restating a list that goes stale; the fork-era pin count (eight names) retired with its consumers, and `get_third_party_subagents` stays only as a courtesy to fork-era installer copies already carried into raven homes.
- **Wheel and sdist slim down.** The wheel force-includes `agents/` file-by-file from the git index (filled-in `.env` files are refused). The sdist shrinks 93.2 MB -> 2.76 MB (-97%).
- **Docs speak one era.** AGENTS.md, CONTEXT.md, README, CHANGELOG, the demo READMEs, and the RPC field descriptions (models.py -> openrpc.json -> both generated clients) describe the product tree in the present and the fork in the past.

## Type

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

## Verification

- Controlled A/B on a clean bench, same machine and env fingerprint, at the current pair: base 19,938 passed / 137 skipped / 0 failed vs branch 19,796 / 137 / 0, skip roster identical line by line. The -142 delta equals the collection delta and reconciles file by file: -159 across the twelve retired or trimmed test files, +9 floor-six migration tests, +8 floor-seven tests. The branch diff is fingerprint-stable across rebases (`git patch-id --stable` verified pairwise), so the reconciliation transfers to later bases. A second fingerprint (dev worktree env) shows 19,555 / 148 / 2 at the final tip; the 2 are `test_design_engine_rendering_outcome` renders hitting a local playwright-home quirk -- on the clean bench both sides skip them identically ("no system chromium"), and the branch does not touch that file.
- `uv run pytest tests/integration/test_research_subagent_smoke.py -m integration`: 2 passed (the smoke now drives the migrated product launcher end to end).
- `make lint-python` (ruff check + format), `make lint-imports` (tail line: `Contracts: 9 kept, 0 broken.` -- the ninth contract landed on main mid-branch), `make check-large-files`: all green.
- `npm run lint:rpc --prefix ui-tui` and `npm run gen:check --prefix ui-web`: generated clients in sync with `rpc-schema/openrpc.json`.
- `bash -n install.sh`: clean.
- Wheel built from the branch, installed into a clean venv: onboarding discovers the five products, and a filled-in `.env` placed in the tree fails the build (secrets refusal probed).
- Real-config upgrade rehearsal on a genuine floor-5 home config (owner present): the migration stamped the sidecar to 6, rewrote nothing (the five product rows were already registered against `agents/`; the one fork-era orphan row got its advisory notice and was left untouched), a second load was silent, and the upgraded config served a live probe plus one full one-shot agent turn. The floor-seven rehearsal on the same config renamed its one transition row (a one-line diff against the byte backup), stamped seven, was silent on the second load, and left the machine ids and the row's command untouched.

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

## Risk

- User-visible: on first load of a pre-v6 config, roster rows pointing into the retired tree are re-aimed at the product tree, with a one-line `Migrated` notice per changed row and a cleanup hint for the stale on-disk copy. Rows the migration cannot decide are reported, never rewritten. The floor-seven rename tells once per changed row too; only a blocked rename repeats its advisory, deliberately, until the blocking row is gone. While the block holds, the roster shows the discovered `Raven-Research` row beside the stored `Raven-Research-NG` row -- same launcher, same state root, no state split -- and converges to one row once the name frees.
- Rollback: revert the squash commit. The fork trees return from git history, and a config the migration already re-aimed keeps working on both sides of the revert: the wheel carries `agents/` before and after (that packaging landed separately), so no config rollback is needed. Rows the migration could not decide were never rewritten, and the version sidecar is additive.
- Packaging: a wheel built from an sdist (what a combined `uv build` does) carries no agent products by design -- the sdist has no `.git` for the hook's tracked-files read; the hook warns loudly, and release.yml builds the wheel directly from the checkout and asserts the products are present. Release artifacts are unaffected; do not publish a combined-build wheel.

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

## Related Issues

N/A

BREAKING CHANGE: the `subagents/` source tree is gone. Installs never consumed it directly (the wheel carries `raven/agents`), but any local tooling that read `subagents/` paths must move to `agents/` or the snapshots under `tests/fixtures/vendored_fork/`.
2026-09-09 03:59:19 +00:00
0xKT
9fc3f05721 fix(ui-web): a spawn card's stream no longer swallows a scroll back up
## Summary

Reported from real use, with a screenshot: an open spawn card's stream box could not be scrolled back up, and the page behind it would not move either. It reads as the surface freezing.

The box is `overscroll-behavior: contain`:

```css
.dlgchat { max-height: 340px; overflow-y: auto; overscroll-behavior: contain; }
```

That is right at its **bottom** edge -- reading a stream to its end should not then carry the whole conversation past the card. At the **top** edge it has nothing to hold back and takes something away. The box is a third of the window tall and the full width of the column, so a reader's cursor is very likely inside it; once the box itself is at the top, every further wheel-up is swallowed and the page stays where it is.

## What I tried first, and why neither works

Both were measured in a real Chromium against a minimal page with the same two boxes, one `contain` and one `auto`.

**Dropping `contain`.** It protects something real: with `auto`, one continuous gesture that scrolls past the box's end dragged the page 840px. That is the annoyance the property was added for.

**Toggling the property from a handler** (on `scroll`, and on `wheel` by direction). Both released the top -- and both leaked 600px downwards. The browser reads `overscroll-behavior` when the gesture *starts*, so a value written mid-gesture applies to the next one, by which time the reader has already watched the page refuse to move. CSS has no directional form of this.

So the containment stays, and the upward remainder is handed to the page by hand.

## Type

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

## Measured in a real browser

Same probe, all three states, with the cursor re-centred on the box before each phase -- an earlier run of this probe reported a false leak because the page had scrolled the box out from under the pointer:

```
A  box still has room, wheel up     box 560 -> 440   page 1021 -> 1021   page still
B  box at its top, wheel up         box 0            page 1021 ->  781   page follows
C  wheel down past the box's end    box 0 -> 560     page  781 ->  781   page not dragged
```

B is the bug. C is what `contain` is for, and it still holds.

## The ancestor walk, and the guard that turned out to be load-bearing

The page scroller is walked for rather than named, so the same card works wherever it is mounted. The walk skips an ancestor whose content already fits, and that is not a formality -- run against the live page, the chain from the box is:

```
.bd          overflow-y: auto      scrollHeight 94   clientHeight 94    skipped
.dtl.dlg     hidden
.wkin .wk .step.in .tfb .tfold     visible
#stage.col   visible
#scroll      overflow-y: auto      scrollHeight 1980 clientHeight 846   taken
```

`.bd` sits directly between the box and `#scroll` and is a scroller that cannot scroll. Without the `scrollHeight > clientHeight` test the gesture would be forwarded into it, which swallows it in a new place.

## The wheel is read in the unit it was reported in

Review caught that the first revision assigned `deltaY` straight onto `scrollTop`. Only `deltaMode` 0 is pixels: a mouse reporting lines sends about `-3` for one notch and a page-mode device sends `-1`, so the page would have crept a few pixels while the box went on consuming the gesture -- the same freeze this change is for, with a smaller number.

`pixelDelta` normalises first, on the convention `PlaybooksPage.tsx:630` already uses: a line is 16px (exported as `WHEEL_LINE_PX`, so two readings of one device cannot drift), a page is the **scroller's own** visible height -- a page means a page of the thing being scrolled -- and a scroller reporting no height falls back to a line rather than multiplying by zero, which would report a move and make none.

The line and page arithmetic is covered by unit cases, not by a real device: Playwright's `mouse.wheel` emits pixel mode only, so a line-mode gesture could not be driven through a real browser. What was measured there is the containment behaviour itself, above.

## Verification

```
make test-ui   96 files, 1422 tests passed
make lint-ui   gen:check 162 methods, type-check
```

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed -- no docs surface; the measurements above are the record

Ten cases on the rule and one on the wiring. Nine mutations, each killing at least one:

| mutation | red |
|---|---|
| drop the direction test | 2 |
| drop the at-the-top test | 2 |
| drop `scrollHeight > clientHeight` | 1 |
| stop the walk at the immediate parent | 3 |
| line mode treated as pixels | 2 |
| page mode treated as pixels | 2 |
| drop the zero-height fallback | 1 |
| stop passing `deltaMode` from the component | 1 |
| remove `onWheel` from the card | 1 |

Geometry is fabricated in the unit cases rather than laid out: happy-dom lays nothing out, so `scrollHeight` and `clientHeight` are both 0 there and every ancestor would look unscrollable -- the walk would find nothing and the cases would pass having forwarded nothing. The scroll position they assert is then only ever the number the code under test wrote, which is the whole of what is being checked.

## Risk

- [x] Security impact considered -- no new data, no network or storage surface; the change is which element a wheel gesture moves
- [x] Backward compatibility considered -- one new module and one handler on one element. The CSS is untouched, so every other nested scroller behaves exactly as before, and a page with nothing to scroll finds no target and does nothing
- [x] Rollback path is clear for risky changes -- single-commit revert; the box returns to swallowing the gesture

## Related Issues

N/A

## Swept

`mr-review-patterns` pre-submit sweep, over the branch diff.

- **1 (a write location moved)** -- nothing moved; a gesture that reached no scroller now reaches one.
- **2 (a value with several entry points)** -- `#scroll`'s `scrollTop` also has `tail.ts` as a writer, which follows the tail while `stuck`. A reader scrolling up clears `stuck`, so the two cannot fight: by the time this forwards anything the follow is already off.
- **3d (several lanes through one sink)** -- one handler on one element; the decision is a pure function with its own cases.
- **4** -- failing test IDs diffed against the base, not counts: 0 introduced.
- **9 (error handling)** -- the two ways out are both silent and both correct: no scrollable ancestor, and a wheel the box can still answer. Neither is an error and neither throws.
- **11** -- `npm ci` in `ui-web`; this worktree was fresh.

Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 6c, 7, 7b, 8, 10.
2026-09-08 06:51:52 +00:00
Handsome-wzw
9ebefab4cc fix(ui-web): a spawn card's stream no longer swallows a scroll back up
## Summary

Reported from real use, with a screenshot: an open spawn card's stream box could not be scrolled back up, and the page behind it would not move either. It reads as the surface freezing.

The box is `overscroll-behavior: contain`:

```css
.dlgchat { max-height: 340px; overflow-y: auto; overscroll-behavior: contain; }
```

That is right at its **bottom** edge -- reading a stream to its end should not then carry the whole conversation past the card. At the **top** edge it has nothing to hold back and takes something away. The box is a third of the window tall and the full width of the column, so a reader's cursor is very likely inside it; once the box itself is at the top, every further wheel-up is swallowed and the page stays where it is.

## What I tried first, and why neither works

Both were measured in a real Chromium against a minimal page with the same two boxes, one `contain` and one `auto`.

**Dropping `contain`.** It protects something real: with `auto`, one continuous gesture that scrolls past the box's end dragged the page 840px. That is the annoyance the property was added for.

**Toggling the property from a handler** (on `scroll`, and on `wheel` by direction). Both released the top -- and both leaked 600px downwards. The browser reads `overscroll-behavior` when the gesture *starts*, so a value written mid-gesture applies to the next one, by which time the reader has already watched the page refuse to move. CSS has no directional form of this.

So the containment stays, and the upward remainder is handed to the page by hand.

## Type

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

## Measured in a real browser

Same probe, all three states, with the cursor re-centred on the box before each phase -- an earlier run of this probe reported a false leak because the page had scrolled the box out from under the pointer:

```
A  box still has room, wheel up     box 560 -> 440   page 1021 -> 1021   page still
B  box at its top, wheel up         box 0            page 1021 ->  781   page follows
C  wheel down past the box's end    box 0 -> 560     page  781 ->  781   page not dragged
```

B is the bug. C is what `contain` is for, and it still holds.

## The ancestor walk, and the guard that turned out to be load-bearing

The page scroller is walked for rather than named, so the same card works wherever it is mounted. The walk skips an ancestor whose content already fits, and that is not a formality -- run against the live page, the chain from the box is:

```
.bd          overflow-y: auto      scrollHeight 94   clientHeight 94    skipped
.dtl.dlg     hidden
.wkin .wk .step.in .tfb .tfold     visible
#stage.col   visible
#scroll      overflow-y: auto      scrollHeight 1980 clientHeight 846   taken
```

`.bd` sits directly between the box and `#scroll` and is a scroller that cannot scroll. Without the `scrollHeight > clientHeight` test the gesture would be forwarded into it, which swallows it in a new place.

## The wheel is read in the unit it was reported in

Review caught that the first revision assigned `deltaY` straight onto `scrollTop`. Only `deltaMode` 0 is pixels: a mouse reporting lines sends about `-3` for one notch and a page-mode device sends `-1`, so the page would have crept a few pixels while the box went on consuming the gesture -- the same freeze this change is for, with a smaller number.

`pixelDelta` normalises first, on the convention `PlaybooksPage.tsx:630` already uses: a line is 16px (exported as `WHEEL_LINE_PX`, so two readings of one device cannot drift), a page is the **scroller's own** visible height -- a page means a page of the thing being scrolled -- and a scroller reporting no height falls back to a line rather than multiplying by zero, which would report a move and make none.

The line and page arithmetic is covered by unit cases, not by a real device: Playwright's `mouse.wheel` emits pixel mode only, so a line-mode gesture could not be driven through a real browser. What was measured there is the containment behaviour itself, above.

## Verification

```
make test-ui   96 files, 1422 tests passed
make lint-ui   gen:check 162 methods, type-check
```

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed -- no docs surface; the measurements above are the record

Ten cases on the rule and one on the wiring. Nine mutations, each killing at least one:

| mutation | red |
|---|---|
| drop the direction test | 2 |
| drop the at-the-top test | 2 |
| drop `scrollHeight > clientHeight` | 1 |
| stop the walk at the immediate parent | 3 |
| line mode treated as pixels | 2 |
| page mode treated as pixels | 2 |
| drop the zero-height fallback | 1 |
| stop passing `deltaMode` from the component | 1 |
| remove `onWheel` from the card | 1 |

Geometry is fabricated in the unit cases rather than laid out: happy-dom lays nothing out, so `scrollHeight` and `clientHeight` are both 0 there and every ancestor would look unscrollable -- the walk would find nothing and the cases would pass having forwarded nothing. The scroll position they assert is then only ever the number the code under test wrote, which is the whole of what is being checked.

## Risk

- [x] Security impact considered -- no new data, no network or storage surface; the change is which element a wheel gesture moves
- [x] Backward compatibility considered -- one new module and one handler on one element. The CSS is untouched, so every other nested scroller behaves exactly as before, and a page with nothing to scroll finds no target and does nothing
- [x] Rollback path is clear for risky changes -- single-commit revert; the box returns to swallowing the gesture

## Related Issues

N/A

## Swept

`mr-review-patterns` pre-submit sweep, over the branch diff.

- **1 (a write location moved)** -- nothing moved; a gesture that reached no scroller now reaches one.
- **2 (a value with several entry points)** -- `#scroll`'s `scrollTop` also has `tail.ts` as a writer, which follows the tail while `stuck`. A reader scrolling up clears `stuck`, so the two cannot fight: by the time this forwards anything the follow is already off.
- **3d (several lanes through one sink)** -- one handler on one element; the decision is a pure function with its own cases.
- **4** -- failing test IDs diffed against the base, not counts: 0 introduced.
- **9 (error handling)** -- the two ways out are both silent and both correct: no scrollable ancestor, and a wheel the box can still answer. Neither is an error and neither throws.
- **11** -- `npm ci` in `ui-web`; this worktree was fresh.

Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 6c, 7, 7b, 8, 10.
2026-09-08 06:51:52 +00:00
gloryfromca
2327126588 feat(permissions): permission modes with a gate at the tool dispatch door
## Summary

Land the permission-mode design: a permission gate the tool registry consults before dispatching any tool call, replacing the lexical blacklist inside ExecTool and its abort-the-whole-turn refusals.

Decision waterfall, per call: the builtin unconditional deny list (catastrophe-class commands only), then the user's deny/allow tiers and exec prefix rules from the new `permissions` config node, then the permission mode's reading of the ask tier: `ask` prompts for everything, `smart` has an LLM reviewer allow or escalate (fail-closed; the reviewer's verdict and the final decision are audited as attributes on the call's own tool.call trace span, alongside every other terminal decision -- no permission-only audit file), `full` runs it without prompting while the deny list and user deny rules still hold. The default mode is `ask`.

One ruling language, on purpose. Three specials that punched holes in each other were folded into the tiers during review (the later commits in this MR; the earlier design had them):

- A command family a surface declares (none by default; the ACP editor declares deletion and six external-effect families) does not decide anything. It names the prompt -- the human reads "push to a remote" rather than the bare command -- and is recorded on the call's tool.call span as `permission.family` whichever way the tiers decide; the call answers to the tiers and the mode like any other mutation, so a user allow rule lifts it and full mode runs it.
- A sub-agent's gate reads the turn's mode and asks through the responder the parent turn bound (the permission turn is a ContextVar its task inherits), instead of being pinned to full with asking disabled. The user authorized the spawn, not every command composed afterwards: a delegated `git push` reaches the human exactly as a direct one does, and an unattended parent (cron, one-shot) leaves it unattended.
- `tools.exec.allowDestructiveCommands` is retired. It lifted a blanket recursive-delete refusal that no longer exists (an ordinary `rm -rf build/` is ask-tier daily work; only a root or home tree is catastrophe-class). The key is still accepted and ignored, with a startup notice naming the tiers; the settings toggle, the live reader, the launcher inheritance and the settings-whitelist entry are removed.

A conversation can run in its own mode. `permissions.mode` in config is the default every conversation starts on; `config.set` with a `session_id` (same scope rule as a model switch, one shared helper) gives one conversation its own, kept the way its model is kept (in memory and on the conversation's record, so a restart does not undo it), and the gate reads the conversation's own mode first on every tool call, sub-agent tasks included. Bidirectional: the person at the keyboard can tighten or loosen either. Surfaces: `/perm X` in the TUI changes this conversation, `/perm default X` the default; on the web the composer chip changes the open conversation (a pick made in a draft is staged and applied to the session the first message mints, like the model and tier chips) and the settings panel gains the default-mode picker.

Other key decisions:

- Refusals continue the turn: every deny path returns a reasoned tool error with `continuation=CONTINUE`; the one path that ends a turn is the deny-and-stop approval choice. Parallel siblings of a blocked call still never execute. A command the policy cannot parse is refused with instructions to fix it (close the quote, or write the script to a file) rather than to give up.
- The gate is a built-in registry step ahead of the plugin tool gates: platform authority precedes plugin policy, and the gate can wait on a human and answer with a full ToolResult, which the plugin paper deliberately cannot.
- Approval outcomes carry choice (`allow`/`deny`/`deny_stop`) plus optional feedback the human types, relayed verbatim to the model. Both frontends grow the third key and the note field, localized. A channel user answers approvals through the same ask round-trip that already carries questions (`ApprovalViaAsk`); cron/sentinel/one-shot turns stay unattended and the ask tier refuses with a reason there.
- A command bound for a registered machine (the target's new exec `machine` lane) names that machine on its approval prompt -- `rm -rf /data (on prod-gpu-1)` -- and in the per-turn dedup key, so a refusal here does not pre-refuse the same text elsewhere; the gate's rulings themselves apply on every machine alike. The background lane is ruled on at the registry door like any other call and cannot be a way around a refusal.
- ShellCommandPolicy stays in place (classification, wrapper stripping, surface family registration) and is consumed by the gate; ExecTool keeps only its own integrity boundary (allowlist, workspace fence) and execution.
- Contracts: `contracts/permissions.py` is a new contract paper (ledger re-pinned across the review rounds, CONTRACTS_VERSION 5 -> 9); `SupportsApprovalTurn` is removed with its last consumer. `rpc-schema/openrpc.json` gains `config.get.session_id`; both generated clients are regenerated.
- Sandboxing earns no relaxation anywhere in the permission path: Boxlite mounts the real workspace read-write, so the deny list and the catastrophic-delete checks apply to sandboxed and direct execution alike.
- The target's config hot-reload for `tools.exec.extra_deny_patterns` is preserved and enforced at the gate: `BuiltinRulings` re-reads the live source before each ruling, a non-compiling pattern rejects the edit and keeps the current policy.

Deliberate v1 cuts, called out for review: the smart-mode reviewer sees only the tool request itself (no conversation tail); gate refusals always set `blocks_call=True` except the parse-error refusal, which the model keeps to fix. Approval frames carry the real per-call `tool_call_id`.

Out of scope, stated in CONTEXT.md: ACP-dispatched external agents (auto-approved by `acp_client/permissions.py`) and vendored out-of-process sub-agents are not covered by the gate. The channel approval transport keys late replies by conversation only; the expired-approval-then-second-approval overlap is recorded as a QuestionBroker follow-up.

## Type

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

## Verification

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

- `uv run --all-extras pytest tests/ -q` on the final tree (rebased onto main): 19424 passed, 144 skipped, 0 failed.
- `make lint`: all stages green (python, ui, tui, bridge, vendored checks).
- TUI `npx vitest run`: 2023 passed, 0 failed. Web `npx vitest run`: 1378 passed, 0 failed. `tsc --noEmit` clean on both.
- Reverse verification: with the continuation flip removed, `test_denied_delete_continues_the_turn` fails on the claimed symptom (the turn ends with the canned abort reply); restored and green. The TUI localization change was mutation-verified (keys pointed at a missing id -> red, restored -> green).
- Manual acceptance against `raven serve` with a real model (isolated RAVEN_HOME; TUI through tmux, web through Playwright), reconciled on three layers (UI rendering, server config.json, audit spans): ask prompts / allow-once / deny-with-feedback / deny-and-stop / same-turn dedupe / unconditional deny / full / smart reviewer states, on both surfaces. Two defects found there are fixed in this MR (`/perm` always reported ask: wrong `config.get` shape; approval prompt not localized).
- The delegated-approval path passed a manual pass of its own, which found and fixed a real defect: a sub-agent's first command is often asked AFTER the parent turn has ended, and the end-of-turn overlay reset wiped that prompt off the TUI with nobody having answered, so the call died at the runtime's 35s ceiling and the sub-agent reported a refusal for a prompt the user never saw. Measured both ways on a live gateway: before, the span was deny/approval at exactly 35.0s with no TUI response; after, the prompt stays up past the turn's end and the span is allow/approval/allow at 13.3s with the file written.
- The per-conversation mode passed the same manual pass (TUI and web, 13 steps): a conversation switched to full ran a write with  while the default moved to smart underneath it and a new conversation followed the default; after a gateway restart the same conversation still ran at  (had the record not been read back, smart would have sent the call to the reviewer); a mode picked on the web draft page landed on the session its first message minted (record metadata, prompt shown, ), and the settings panel moved only the default.

## Risk

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

User-visible behavior changes: the default mode is `ask`, so mutating tools (write/edit/exec and unknown MCP tools) prompt on interactive surfaces and are refused with a reason on unattended ones; previously they ran freely. Policy refusals no longer end the turn. Cron/sentinel turns lose mutating tools under the default mode until the user picks `smart` or `full`.

Changes to positions the earlier rounds of this MR had documented: on the ACP surface, full mode now runs a delete or a push it used to refuse, and a user allow rule can lift a declared family; a sub-agent in ask mode now prompts the human through the parent turn where it used to run silently; `tools.exec.allowDestructiveCommands` is read but ignored (startup notice). A conversation's own mode is stored on its session record, like its model, and survives a restart.

Rollback: set `permissions.mode` to `full`, which reproduces the old no-prompt behavior except that catastrophe-class commands are refused rather than run.

## Related Issues

N/A
2026-09-08 06:34:30 +00:00
0xKT
e26ecfa90b feat(provider): expand provider catalog and settings experience
## Summary

- Add LM Studio, NVIDIA NIM, and separate MiniMax Global and MiniMax CN provider paths across configuration, routing, onboarding, and model discovery.
- Add bundled provider icons and accessible connected or disconnected status indicators to provider lists.
- Add provider homepage metadata to the RPC contract and link provider names in Settings, onboarding, and the model picker.
- Preserve the latest main branch per-model protocol metadata while mapping provider UI rows.

![image.png](/uploads/73442917d65ca16c07026e9017153777/image.png){width=876 height=600}

## Type

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

## Verification

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- [ ] `uv run pytest tests/test_provider_catalog.py tests/test_rpc_model.py tests/test_rpc_schema_match.py tests/test_rpc_contract_shapes.py -x` - 534 passed, 4 skipped.
  * `npm test` from `ui-web/` - 1,378 passed.
  * `npm run type-check`, `npm run gen:check`, and `npm run build` from `ui-web/` - passed.
  * `npm run type-check` and `npm run lint:rpc` from `ui-tui/` - passed.
  * `.venv/bin/ruff check raven/providers/registry.py raven/rpc/methods/model.py raven/rpc/models.py tests/test_provider_catalog.py tests/test_rpc_model.py` - passed.
  * `make check-source-language check-large-files` - passed.
  * `git diff --check origin/main...HEAD` - passed.
  * Visually verified the assembled Settings and onboarding provider lists; repository rules prohibit committing standalone screenshots.

## Risk

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

The RPC homepage field is optional, and existing provider configuration remains compatible. Provider routing changes are covered by focused resolution, factory, and RPC tests. Roll back by reverting this feature commit.

## Related Issues

N/A
2026-09-08 06:05:27 +00:00
KevinHuSh
cee84a6f60 feat(provider): expand provider catalog and settings experience
## Summary

- Add LM Studio, NVIDIA NIM, and separate MiniMax Global and MiniMax CN provider paths across configuration, routing, onboarding, and model discovery.
- Add bundled provider icons and accessible connected or disconnected status indicators to provider lists.
- Add provider homepage metadata to the RPC contract and link provider names in Settings, onboarding, and the model picker.
- Preserve the latest main branch per-model protocol metadata while mapping provider UI rows.

![image.png](/uploads/73442917d65ca16c07026e9017153777/image.png){width=876 height=600}

## Type

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

## Verification

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- [ ] `uv run pytest tests/test_provider_catalog.py tests/test_rpc_model.py tests/test_rpc_schema_match.py tests/test_rpc_contract_shapes.py -x` - 534 passed, 4 skipped.
  * `npm test` from `ui-web/` - 1,378 passed.
  * `npm run type-check`, `npm run gen:check`, and `npm run build` from `ui-web/` - passed.
  * `npm run type-check` and `npm run lint:rpc` from `ui-tui/` - passed.
  * `.venv/bin/ruff check raven/providers/registry.py raven/rpc/methods/model.py raven/rpc/models.py tests/test_provider_catalog.py tests/test_rpc_model.py` - passed.
  * `make check-source-language check-large-files` - passed.
  * `git diff --check origin/main...HEAD` - passed.
  * Visually verified the assembled Settings and onboarding provider lists; repository rules prohibit committing standalone screenshots.

## Risk

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

The RPC homepage field is optional, and existing provider configuration remains compatible. Provider routing changes are covered by focused resolution, factory, and RPC tests. Roll back by reverting this feature commit.

## Related Issues

N/A
2026-09-08 06:05:27 +00:00
TongLi31
63193e299a feat(agents): raven-code manifest over acp, real effort tiers, and the !512 fixes on trunk
## Summary

Retires raven-code's worktree isolation and moves its workspace report off the reply text and onto the ACP wire; gives raven-code real effort tiers named after the host's ladder; and ports the two engine fixes of MR !512 from the retired vendored fork to trunk `raven/`, which is the engine the `agents/raven-code` product actually runs (the host discovers `agents/*/subagent.json` only, so !512's fixes protected code the host no longer launches). Rebased onto main after per-model API protocols (4fe30b0a) landed; what that changed for this branch is called out below.

Three product decisions behind the first part: an unattended dispatch has nobody to answer the write gate's authorization question, so a dirty checkout parked the node until its timeout; the coordination between parallel raven-code sessions becomes a prompt-level contract, told only when it applies; and the host keeps getting a machine-read report of what each session did to the working directory, without reading it out of prose.

- Retire the write gate and its worktree isolation (`agents/raven-code/plugins/code-flow`): the gate, the worktree allocation and the release observer go, the launcher renders no arming, and the roster line stops promising an authorization prompt. The vendored A side under `subagents/` is frozen and untouched.
- Tell parallel sessions about each other: the code-flow hook books each session into a process-wide ledger at its turn start, and when other sessions are mid-turn in the same working directory it puts a concurrency notice in front of this turn's prompt (the model's view of this turn only). A lone session hears nothing. Parallel DAG nodes are sessions of one raven-code process on one directory, so the process can count them itself; the host has no per-node place to say it.
- Relay a turn's `acp_meta` observer stash as the prompt response's `_meta` (`raven/acp/methods.py`): the loop_hooks paper already files what a hook stashes under `metadata["observers"]` onto the turn's last substantive assistant message and saves the session before the turn's ending reaches the stream; the methods layer reads that entry back and answers with it under `_meta`, the field ACP reserves for an agent's own metadata. Only messages the turn appended are read; a turn that filed nothing answers exactly as before. Generic: nothing in `raven/` knows what any plugin puts there.
- File raven-code's workspace report through it: at the send the hook measures the directory against the base commit pinned at the session's first turn (root, branch, head, commits past base, working tree, diff stat, a status that is ready only when every fact answered) and stashes it as `raven.harnessManifest`. Nothing comes from model prose; a directory outside git is reported as plain. The report is workspace-scoped (`scope: workspace`): with no worktree, HEAD is shared by every session in the directory, so `baseCommit..HEAD` is what the tree gained since the session's base, by whoever wrote it. The ledger remembers which sessions shared a directory (peers, for the rest of their lives); a report from a session with peers carries `attribution: shared` and `sharedWith`, keeps the git facts, but takes the status `shared_workspace` with the blocker spelled out and is never ready. A lone session keeps `attribution: session` and the previous statuses.
- Keep the response `_meta` on the run record (`raven/acp_client/acp_agent.py`, `RunActivity.response_meta`): verbatim, namespaced as the agent sent it, as `acp_response_meta` -- so it reaches the spawn record's `meta.json` and the DAG run's per-node entry through the same channel as the frame pointer. The host reads none of it.
- Give raven-code real effort tiers on the agents/ tree, named after the host's ladder: the product had no tiers of its own and fell back to raven's three built-in rungs, which by design leave raven's own effort untouched, so a host asking for `medium` or `max` changed nothing about the model's reasoning (and the vendored twin's `low` / `high` / `max` catalogue was one the host's clamp refused to map `medium` onto). main now carries the engine side itself (4fe30b0a: `AcpModeConfig.reasoningEffort`, carried through the resolved profile and the session policy onto every model call of the turn; the built-in tiers leave it inherited and stay inert for raven itself), so this branch keeps only what main lacks there: the tools-disabled wrap-up call a turn makes when it exhausts its iterations asks for the same effort, plus the tests for the knob. On top of it the launcher declares `medium` / `high` / `max` with `medium` and `max` as overlays moving exactly `agents.defaults.reasoningEffort` and `high` as the baseline, and the LiteLLM provider mirrors the effort into OpenRouter's `extra_body.reasoning.effort`, which litellm's `drop_params` never touches -- without that mirror the effort could be silently dropped for any model litellm cannot map behind the gateway. Verified against OpenRouter's documented vocabulary (`max` / `xhigh` / `high` / `medium` / `low` / `minimal` / `none`; for Anthropic, thinking budgets of roughly 95 / 80 / 50 / 20 percent of `max_tokens` for `max` / `high` / `medium` / `low`).
- Never prefill a thinking-only turn on a model that refuses it (`raven/agent/loop/recovery.py`, `turn_path.py`, `raven/contracts/llm_provider.py`, `raven/providers/*`). Empty-response recovery re-fed a thinking-only response as a trailing assistant message; Anthropic rejects that request while thinking is on, and through the gateway the rejection arrived as a stream that never produced a byte, so the turn sat on the request budget (the 2026-09-01 dispatched-run report, item 1). Providers now answer `supports_assistant_prefill(model)` -- default True; `LiteLLMProvider` says no for the Anthropic family by the same rule that puts `thinking_blocks` on the wire, and the lazy / per-model / resolving / endpoint-rotor wrappers forward the question to the provider they wrap. The classifier consults it before the prefill budget: a refused prefill takes the post-tool nudge when a tool just ran, else the plain retry budget, else gives up, so no request handed to such a provider ends on an assistant message. Nothing changes for a provider that accepts the prefill. The native Anthropic Messages provider needs no answer of its own: it already rewrites a trailing assistant message into user-side text, so no request it sends ends on an assistant message.
- Give the LLM stream its own idle timeout (`raven/providers/litellm_provider.py`, `raven/contracts/llm_provider.py`, `raven/config/schema.py`, `raven/providers/factory.py`, `resolving_provider.py`). `chat_stream` waited the whole request budget for every chunk, so behind `llmCallTimeout: 1800` a dead stream cost half an hour (report item 2). `agents.defaults.streamIdleTimeout` (default 180s, 0 disables) decides whether the stream is dead and resets on every chunk; the request budget is enforced separately on top, so a backend that trickles forever is still bounded. Every wait in the LiteLLM stream -- the open, the first pull, the retry after a refused cache breakpoint, each later chunk -- takes the smaller of the idle line and what is left of the budget. Per-model protocols now route a claude model onto the native Anthropic Messages provider and a gpt model onto the OpenAI Responses provider by default, so the deployed raven-code route (OpenRouter, `anthropic/claude-opus-5`) no longer streams through LiteLLM at all; both native SSE consumers had the same single cap and take the idle line beside the budget too, and the Anthropic provider, the Responses provider and the Codex request helper hand their idle line to the consumer.
- Replay the incident end to end (`tests/test_agent_loop_incident_replay.py`): the real `LiteLLMProvider` built from `agents/raven-code/config.json`'s provider and defaults blocks, driven over the streaming call with `acompletion` faked to behave as the gateway did. The replay pins the model to the chat protocol, the transport the incident ran on (per-model protocols arrived later); the native providers' idle line has its own suite. Run against `origin/main` before the fixes it reproduces the incident (requests end on an assistant message and the turn waits out the scaled budget; a dead stream stalls for the whole budget; the deployed block arms no idle line). On this branch all four tests pass.
- The two provider shape changes are on the contract tier, so `CONTRACTS_VERSION` moves 7 -> 8 -> 9 with the ledger pin (main took 6 -> 7 for `ChatDelta.thinking_blocks`). `CONTEXT.md` gains Response Meta, Harness Manifest and Concurrency Notice, the Session Mode entry names its third knob, and the Empty-Response Recovery entry names the new question.

Deliberately not in this MR: a main-model-visible summary line of the report (dag_tool / manager), a capability declaration for the relay in the initialize handshake, and a report for a turn that failed or was cancelled (`after_send` does not fire there; the host sees the stop reason). Also not ported from !512: the turn-policy pin against a concurrent `session/set_mode` (the host sends `set_mode` before `session/prompt` and never during a running turn of the same session, so the race is unreachable in this deployment) and `extra="forbid"` on the `acp` config block (trunk's stated posture for such fields is warn-and-drop, and the raven-code launcher writes that block from code).

Known limit, same as in !512: the loop asks about the model the call was made for, so a routing fallback onto an Anthropic model mid-call would not be guarded (no routing is configured for raven-code, and the streaming path has no fallback).

Review round one on !529, three findings, all addressed here. (1) Blocking, effort did not cover compaction: the two head-summary calls transcript compaction pays for (proactive over the trigger line, reactive after an overflow) called `provider.chat` with no effort, so a `max` session that compacted mid-turn summarized at the connection's default; `_summarize_head` now takes the turn's effort and both call sites pass the policy the turn read at its start, with two tests driving a turn across the context limit. (2) Blocking, the report claimed shared commits: two sessions from one base, A commits, B does nothing, and B's `baseCommit..HEAD` listed A's commit as B's, even ready for integration; fixed by the workspace scope and attribution described above -- git alone cannot say whose commit is whose, so the report says whether it may be read as one session's at all. (3) Nonblocking, the ledger's in-flight mark was refreshed only at a turn's start and send, so a turn longer than the ttl vanished from the count its peers were told; the hook now refreshes the mark at every iteration, and the ttl keeps expiring only a turn that stopped reporting. The pipeline failure on the previous head was the test job hitting the runner's 45-minute limit ("Node is not ready" at about 43 percent), not a test verdict; the same job reproduced in the CI image on this head passes completely (see Verification).

Review round two on !529, one blocking finding, addressed here: the session effort still bypassed the in-turn watch-work classifier. After a relevant tool result the turn may pay for one more model call, the judgement of whether the request touches an on-call agent's watched path (two call sites in `_note_watch_work`: the look at a path, and the shape of a hand-off); both went through `_llm_call_stream` with no effort, so a medium/max session with an on-call watcher ran that classifier at the provider default. `_note_watch_work` now takes the turn's pinned effort and hands it to both calls, and the turn path passes the policy it read at its start; three unit tests read the kwargs each classifier call was made with, and one loop-level test checks the turn path hands the pinned effort to the helper for every tool result it judges. Left nonblocking, as the review marked them: a single provider or tool wait longer than the ledger's one-hour ttl still has no heartbeat inside it (the mark is refreshed at every iteration, not mid-wait), and the recovery-rung suggestion.

## Type

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

## Verification

- `uv run pytest tests/test_watch_work.py tests/test_agent_loop_session_effort.py -q` -> 75 passed (round two: the watch-work classifier is called with the pinned effort at both sites, nothing when none is pinned, and the turn path hands it over)
- `uv run pytest tests/test_agent_loop_session_effort.py tests/test_agents_code_flow_manifest.py tests/test_agents_code_flow_sessions.py tests/test_agents_code_flow_plugin.py tests/test_agent_loop_context_overflow.py tests/test_plugin_session_observers.py tests/test_agent_hook_contract.py tests/test_agents_code_launcher.py -q` -> 169 passed (the round-one fixes: the compaction summary carries the session's effort across the context limit; a shared directory turns the report to `shared_workspace` and unready; a long turn stays counted)
- `uv run pytest tests/test_agent_loop_incident_replay.py tests/test_providers_native_stream_idle.py -q` -> 19 passed; the replay file against a clean `origin/main` worktree -> 3 failed on exactly the incident's three symptoms (four requests in a row end on an assistant message; the dead stream stalls for the whole scaled budget; `GenerationSettings` has no idle line), 1 passed
- Targeted suites on the rebased branch (`-p no:xdist`): code-flow plugin / sessions / manifest, both launchers, `test_acp_methods` / `test_acp_modes` / `test_acp_server`, `test_subagent_acp` (against the real stub server, which gained a `meta` mode that answers a prompt with `_meta`), `test_agent_loop_session_effort` / `test_agent_loop_iteration_hooks`, `test_litellm_provider_reasoning`, `test_agent_hook_contract` (the hook surface fingerprint is unchanged; the relay reads an existing seam), `test_contracts_two_tier_ledger` (the pin at 9), `test_plugin_tool_gates` / `test_plugin_session_observers`, `test_agent_loop_empty_recovery` (13 new tests), `test_litellm_provider_timeout` (5 new), `test_litellm_provider_stream`, `test_provider_stream_fallback`, `test_providers_factory`, `test_resolving_provider`, `test_openai_codex_provider`, `test_provider_protocol`, `test_agent_loop_context_overflow`, `test_watch_work`, `test_agents_oncall_flow_hooks` -> 888 passed
- `make lint-python` green; `make lint-imports` -> 8 contracts kept, 0 broken; `make check-large-files`, `make check-vendored-subagents` and `make check-vendored-invariants` green (nothing under `subagents/` changed); `git diff --check` clean
- The CI `tests` job reproduced locally in its own image and command sequence (`python:3.12-slim`, `uv sync --locked --all-extras --dev`, `uv run --all-extras pytest -q`, four xdist workers) on this head -> 19250 passed, 192 skipped, 0 failed in 5m40s. The pipeline on the branch's first head died with the runner's node ("Node is not ready" at about 43 percent, then the 45-minute cap hit during after_script and cleanup), not on a test verdict: the same job reproduced on that commit (a78636b3, a real clone) -> 19014 passed, 0 failed, and pipeline 2826205430 on the round-one head passed.
- Full host suite (`make test-python`) on the rebased branch -> 19269 passed; the failing set is the pre-existing cron timezone family only (6 failed + 20 errors, no tzdata on the machine), nothing else

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

## Risk

Behaviour changes for raven-code: no more first-write authorization prompt and no worktree; parallel sessions on one directory can write the same file, and are told so; a host `medium` or `max` session now actually changes the model's reasoning effort (it used to change nothing), and every OpenRouter-routed request carries the effort in the gateway's own `reasoning` object. The prompt response of a raven-serving-ACP agent gains a `_meta` key only when a hook filed one; existing clients that read `stopReason` alone are unaffected (the ACP schema declares `_meta` on the response). The host's run records gain one optional key. The workspace report's `readyForIntegration` is false whenever another Raven-Code session shared the directory, so an integration step reading it must expect `shared_workspace` on parallel DAG nodes and handle that case itself.

Behaviour changes for every raven-serving product on trunk, not only raven-code: a thinking-only empty response on an Anthropic-family model is now retried or nudged instead of prefilled (previously a hang behind a gateway, a 400 direct); a stream silent for 180s is reported as a timeout instead of waiting out `llmCallTimeout` (a backend that stays silent while thinking for longer than that needs `streamIdleTimeout` raised or set to 0) -- on the LiteLLM path and on the native Anthropic Messages, OpenAI Responses and Codex paths alike. Providers that accept a prefill and streams that keep producing bytes see no change.

Rollback is a revert of the branch's commits.

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

## Related Issues

Follows MR !512, which carried the same two engine fixes on the retired vendored line under `subagents/`; the host no longer launches that line.

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-08 06:04:58 +00:00
0xKT
677d090476 feat(ui-web): an instance can be set apart from the conversation
## Summary

!478 gives the conversation a sub-agent tier. This gives one instance an effort of its own, from that instance's own pane.

The two are a **precedence, not a pair**: `SubagentManager.resolve_mode` reads the instance's override and falls through to the session's tier when there is none. So the default is not a mode -- it is the ABSENCE of one, and the wire already says so with `mode: null`. The row for it reads **Auto**, and `clear: true` is what puts an instance back on it. There is no sentinel id for it on purpose, since an agent is free to call one of its own modes "default".

**Auto names where it currently lands**, not just "Auto". That is what `inherited` is for, and why !474 reports it apart from `mode`: it is the session's tier already clamped to this agent's rungs, which is not the same as the tier. A session on `high` and an agent that cannot rank it means the agent's own default runs, and the row says so.

**The menu is this AGENT's, never the ladder.** Each advertises its own rungs from its own ACP handshake -- measured, not declared. raven-research offers `fast`/`deep`/`ultra` and raven-code `low`/`max`; drawing `medium`/`high`/`max` here would offer rungs the agent does not have. An agent that advertises none draws no chip: nothing to choose between is not the same as a choice that could not be read.

A reply decides, never the click. The manager refuses a rung the agent does not advertise, naming what it does offer, and that refusal is shown rather than the chip moved to a mode the next turn will not run at.

On the pane header, through the shared menu writer with the trailing tick the model chip already uses, rather than a third popover. Live instances only -- a record is a run that already happened.

## Type

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

## Stacked on !478

Target is !478's branch. Kept separate per the ask to split MRs by focus: !478 is the conversation's control and stands alone, this is the per-instance one and only makes sense after it.

Worth noting that !474's later scope change made this smaller. Withdrawing the per-dispatch `mode` left `resolve_mode` at two levels -- the instance's override, else the session's tier -- which is exactly the two a reader can be shown. The third would have had to be explained without being settable.

## Verification, and what it does not cover

Said plainly, because the interesting half could not be driven end to end here.

**What the server really answered.** On the running page, against !474's server, with a real instance started from the agents panel:

```
subagents.instance.set_mode -> { mode: null, inherited: null, availableModes: [] }
```

Every agent registered in this environment is `kind` `cli` or `openai`, and `agent_meta` reads modes only for `acp` -- so none can advertise any, and **the chip correctly draws nothing**. That much is end to end: real server, real instance, real pane, no chip.

**What the component does with a menu** could only be driven by answering the seam on the page. The component, the menu writer, the styles and the pane are the real built ones; the reply is not the server's:

```
Auto                chip "Deep"  (.auto)      menu: Auto · Deep ✓ / Fast / Deep / Ultra
pick Ultra          chip "Ultra" (pill)       sent: ('Raven', 'raven-4cc87d', 'ultra')
reopen              menu: Auto · Deep / Fast / Deep / Ultra ✓
pick Auto           chip "Deep"  (.auto)      sent: ('Raven', 'raven-4cc87d', null)
```

So: the wire shape, the clear-versus-set distinction and the rendering are verified; **what is not** is a real agent's real advertised menu arriving over the socket. Reaching that needs an ACP sub-agent product installed and probed, which this environment has none of. The unit cases cover the states.

I also tried the other way first -- hand-writing a capability snapshot with `availableModes` -- and it changed nothing, because `agent_meta` gates the read on `kind == "acp"` and no configured agent is one. Recording it so nobody repeats it.

```
ui-web  vitest 93 files / 1330 tests, type-check, gen:check (161 methods)
ui-tui  lint:i18n up to date, lint:rpc in sync, type-check clean
```

Mutation-checked nine ways, each redding a different case: Auto showing "Auto" instead of the inherited rung, an empty menu still drawing, painting the click instead of the reply, the Auto row sending an id instead of clearing, the chip not stopping `pointerdown`, and a failed read keeping the previous instance's value. The last one survived the first pass -- the case I had only failed the FIRST read, where there is nothing to keep -- so a case was added for a pane moving to an instance it cannot read.

## After review

**An Auto chip went stale when the conversation tier moved -- `536c62a9`.** Under
Auto the chip shows `inherited`, the session's tier clamped to this agent, so a
switch changes what the pane says with nothing on the pane touched. The effect
keyed on `(agent, handle)` and `shell/tier.ts` told nobody. Reproduced by counting
the reads, with a control, since the chip does not draw against this
environment's agents:

```
                                  before          after
Auto pane open                    High, reads 1   High, reads 1
session tier switched to Max      HIGH, reads 1   Max,  reads 2
control: open another instance     reads 2         reads 3
```

The tier publishes the move and lets whoever is in the way decide -- the shape
`composer/sheets` uses for `watchAsking`, and for its reason. Two tightenings
mutation-checking forced: it tells listeners **only on a real move** (every read
passes through the same place, including the one per conversation change, so
announcing an unchanged value would have every open pane re-fetch for nothing --
my first version notified unconditionally and the suite stayed green), and the
listener re-reads **only under Auto**, through a ref so switching this instance's
own mode does not tear the subscription down and rebuild it.

**The new test file had no purpose comment -- same commit.** AGENTS.md 1.1 wants
one on every new code file. Worth recording what I checked: 38 of the 40 `ui-web`
test files I sampled carry nothing beyond the vitest directive, so the practice is
not the rule; `features/workspace/deliveries.test.ts` is the compliant form. The
rule wins for a file I am adding. `shell/tier.test.ts` on !478 has the same gap
and I have raised it there rather than pushing to an MR already cleared.

```
ui-web  vitest 93 files / 1333 tests, type-check, gen:check (161 methods)
ui-tui  lint:i18n up to date, lint:rpc in sync, type-check clean
```

## Swept

`mr-review-patterns` pre-submit sweep, over the branch diff.

- **1 (a write location moved)** — nothing moved; a new reader of an existing method.
- **2 (a value with several entry points)** — the held state has one writer, fed only by a reply.
- **3c (state out of its owner)** — kept in the component rather than a store: it is one pane's, read when the pane points at a different instance, and no other surface reads it.
- **3d (several lanes through one sink)** — one lane, the seam. The pane header's `pointerdown` is the drag handle and the pane raise, so the chip stops it; there is a case for that.
- **6c (generated artifacts)** — `ui-tui/src/i18n/messages.generated.ts` regenerated, since the catalogue is shared and `make lint-tui` fails without it.
- **9 (error handling)** — a failed read draws nothing rather than a stale rung; a refused switch is shown with the manager's own text, which names the rungs the agent does offer.
- **11** — `tsc --listFiles` resolves 194 files, 0 outside this worktree; `npm ci` in both workspaces.
- **4** — failing test IDs diffed against the base, not counts: 0 introduced.

Not applicable: 3, 3b, 3e, 4b-4d, 5, 5b, 6, 6b, 7, 7b, 8, 10.
2026-09-07 05:36:07 +00:00
Handsome-wzw
b33a35a171 feat(ui-web): an instance can be set apart from the conversation
## Summary

!478 gives the conversation a sub-agent tier. This gives one instance an effort of its own, from that instance's own pane.

The two are a **precedence, not a pair**: `SubagentManager.resolve_mode` reads the instance's override and falls through to the session's tier when there is none. So the default is not a mode -- it is the ABSENCE of one, and the wire already says so with `mode: null`. The row for it reads **Auto**, and `clear: true` is what puts an instance back on it. There is no sentinel id for it on purpose, since an agent is free to call one of its own modes "default".

**Auto names where it currently lands**, not just "Auto". That is what `inherited` is for, and why !474 reports it apart from `mode`: it is the session's tier already clamped to this agent's rungs, which is not the same as the tier. A session on `high` and an agent that cannot rank it means the agent's own default runs, and the row says so.

**The menu is this AGENT's, never the ladder.** Each advertises its own rungs from its own ACP handshake -- measured, not declared. raven-research offers `fast`/`deep`/`ultra` and raven-code `low`/`max`; drawing `medium`/`high`/`max` here would offer rungs the agent does not have. An agent that advertises none draws no chip: nothing to choose between is not the same as a choice that could not be read.

A reply decides, never the click. The manager refuses a rung the agent does not advertise, naming what it does offer, and that refusal is shown rather than the chip moved to a mode the next turn will not run at.

On the pane header, through the shared menu writer with the trailing tick the model chip already uses, rather than a third popover. Live instances only -- a record is a run that already happened.

## Type

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

## Stacked on !478

Target is !478's branch. Kept separate per the ask to split MRs by focus: !478 is the conversation's control and stands alone, this is the per-instance one and only makes sense after it.

Worth noting that !474's later scope change made this smaller. Withdrawing the per-dispatch `mode` left `resolve_mode` at two levels -- the instance's override, else the session's tier -- which is exactly the two a reader can be shown. The third would have had to be explained without being settable.

## Verification, and what it does not cover

Said plainly, because the interesting half could not be driven end to end here.

**What the server really answered.** On the running page, against !474's server, with a real instance started from the agents panel:

```
subagents.instance.set_mode -> { mode: null, inherited: null, availableModes: [] }
```

Every agent registered in this environment is `kind` `cli` or `openai`, and `agent_meta` reads modes only for `acp` -- so none can advertise any, and **the chip correctly draws nothing**. That much is end to end: real server, real instance, real pane, no chip.

**What the component does with a menu** could only be driven by answering the seam on the page. The component, the menu writer, the styles and the pane are the real built ones; the reply is not the server's:

```
Auto                chip "Deep"  (.auto)      menu: Auto · Deep ✓ / Fast / Deep / Ultra
pick Ultra          chip "Ultra" (pill)       sent: ('Raven', 'raven-4cc87d', 'ultra')
reopen              menu: Auto · Deep / Fast / Deep / Ultra ✓
pick Auto           chip "Deep"  (.auto)      sent: ('Raven', 'raven-4cc87d', null)
```

So: the wire shape, the clear-versus-set distinction and the rendering are verified; **what is not** is a real agent's real advertised menu arriving over the socket. Reaching that needs an ACP sub-agent product installed and probed, which this environment has none of. The unit cases cover the states.

I also tried the other way first -- hand-writing a capability snapshot with `availableModes` -- and it changed nothing, because `agent_meta` gates the read on `kind == "acp"` and no configured agent is one. Recording it so nobody repeats it.

```
ui-web  vitest 93 files / 1330 tests, type-check, gen:check (161 methods)
ui-tui  lint:i18n up to date, lint:rpc in sync, type-check clean
```

Mutation-checked nine ways, each redding a different case: Auto showing "Auto" instead of the inherited rung, an empty menu still drawing, painting the click instead of the reply, the Auto row sending an id instead of clearing, the chip not stopping `pointerdown`, and a failed read keeping the previous instance's value. The last one survived the first pass -- the case I had only failed the FIRST read, where there is nothing to keep -- so a case was added for a pane moving to an instance it cannot read.

## After review

**An Auto chip went stale when the conversation tier moved -- `536c62a9`.** Under
Auto the chip shows `inherited`, the session's tier clamped to this agent, so a
switch changes what the pane says with nothing on the pane touched. The effect
keyed on `(agent, handle)` and `shell/tier.ts` told nobody. Reproduced by counting
the reads, with a control, since the chip does not draw against this
environment's agents:

```
                                  before          after
Auto pane open                    High, reads 1   High, reads 1
session tier switched to Max      HIGH, reads 1   Max,  reads 2
control: open another instance     reads 2         reads 3
```

The tier publishes the move and lets whoever is in the way decide -- the shape
`composer/sheets` uses for `watchAsking`, and for its reason. Two tightenings
mutation-checking forced: it tells listeners **only on a real move** (every read
passes through the same place, including the one per conversation change, so
announcing an unchanged value would have every open pane re-fetch for nothing --
my first version notified unconditionally and the suite stayed green), and the
listener re-reads **only under Auto**, through a ref so switching this instance's
own mode does not tear the subscription down and rebuild it.

**The new test file had no purpose comment -- same commit.** AGENTS.md 1.1 wants
one on every new code file. Worth recording what I checked: 38 of the 40 `ui-web`
test files I sampled carry nothing beyond the vitest directive, so the practice is
not the rule; `features/workspace/deliveries.test.ts` is the compliant form. The
rule wins for a file I am adding. `shell/tier.test.ts` on !478 has the same gap
and I have raised it there rather than pushing to an MR already cleared.

```
ui-web  vitest 93 files / 1333 tests, type-check, gen:check (161 methods)
ui-tui  lint:i18n up to date, lint:rpc in sync, type-check clean
```

## Swept

`mr-review-patterns` pre-submit sweep, over the branch diff.

- **1 (a write location moved)** — nothing moved; a new reader of an existing method.
- **2 (a value with several entry points)** — the held state has one writer, fed only by a reply.
- **3c (state out of its owner)** — kept in the component rather than a store: it is one pane's, read when the pane points at a different instance, and no other surface reads it.
- **3d (several lanes through one sink)** — one lane, the seam. The pane header's `pointerdown` is the drag handle and the pane raise, so the chip stops it; there is a case for that.
- **6c (generated artifacts)** — `ui-tui/src/i18n/messages.generated.ts` regenerated, since the catalogue is shared and `make lint-tui` fails without it.
- **9 (error handling)** — a failed read draws nothing rather than a stale rung; a refused switch is shown with the manager's own text, which names the rungs the agent does offer.
- **11** — `tsc --listFiles` resolves 194 files, 0 outside this worktree; `npm ci` in both workspaces.
- **4** — failing test IDs diffed against the base, not counts: 0 introduced.

Not applicable: 3, 3b, 3e, 4b-4d, 5, 5b, 6, 6b, 7, 7b, 8, 10.
2026-09-07 05:36:07 +00:00
0xKT
9f4a091857 feat(agents): the request's checkable parts ride back down to where it is answered
## Summary

Three of the dimensions lost on 2026-09-04 were not research failures. A named
section was absent from the report entirely, five candidates outside the stated
length envelope took slots in the main table, and the do-not-bother list carried
items the request had already ruled out. Each of those was stated in the request
and satisfied by intention rather than by checking, because by the time the report
is written the request is fifteen thousand tokens up the context - the same reason
the template reminder exists, and it rides the same seam.

`brief_checklist` reads a request for the parts a parser can settle and the
reminder carries them back:

```
Read literally, this message asks for: 15 to 25 items; nothing from LongBench,
LooGLE, ZeroSCROLLS, LoCoMo; a do-not-bother list; a community-convention table.
Deliver each one, or name it in `## Limitations` and say why it is absent.
```

Three properties are the whole design.

**It only reads; it never judges the answer.** No bounce, no model call, no
latency. The gate that owns bouncing says in its own docstring that it bounces for
a missing section and nothing else, and a checklist wrong about what was asked
would spend generations arguing with the reader. A checklist that is merely
incomplete costs nothing.

**It quotes rather than interprets.** The count is the range as written, the
exclusions are the names as written, the artefacts are the noun phrases as
written. A misread is then visibly a misread of the request rather than a rule the
harness invented, which is also why the sentence opens "read literally" and closes
with somewhere for a wrong item to go.

**It stays silent when unsure.** A range followed by a unit is a size, not a count
("16k-256k words", "2024-2026", "4x-8x", "8-80GB"). An exclusion stated in prose
("the four we already ran") yields nothing. A bare "a table" is not an artefact and
"a report" is the answer itself. On a request with no machine-readable constraints
the reminder renders exactly the bytes it always rendered - pinned by a test.

The one thing worth naming as a near-miss: an earlier form of the name rule
anchored on a leading capital and quoted `xRAG` back as `RAG`, which is a checklist
telling the model about a benchmark that does not exist. Items are now split first
and kept or dropped whole, and that case is a test.

No new config key, and no new injection seam: the checklist rides inside the
reminder's own delimiters, so one pair still bounds everything injected and
`strip_reminder` needs no second case.

## Type

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

## Verification

```
uv run --frozen --python 3.12 --all-extras pytest -q tests/ -k research
  774 passed in 61.74s

PYTHONPATH=. uv run --frozen --python 3.12 --extra dev python scripts/check_source_language.py origin/main...HEAD
  clean

uv run --frozen --python 3.12 --extra dev ruff check agents tests
  All checks passed!

uv run --frozen --python 3.12 --extra dev ruff format --check agents tests
  907 files already formatted
```

Sixteen tests, weighted towards what the extractors refuse: four shapes of range
that are sizes rather than counts, a prose exclusion, a bare noun, the answer
itself, an empty task, the camel-cased name, and the unchanged bytes on a request
that carries nothing.
2026-09-07 05:35:48 +00:00
ZuyiZhou
3ab6df8504 feat(agents): the request's checkable parts ride back down to where it is answered
## Summary

Three of the dimensions lost on 2026-09-04 were not research failures. A named
section was absent from the report entirely, five candidates outside the stated
length envelope took slots in the main table, and the do-not-bother list carried
items the request had already ruled out. Each of those was stated in the request
and satisfied by intention rather than by checking, because by the time the report
is written the request is fifteen thousand tokens up the context - the same reason
the template reminder exists, and it rides the same seam.

`brief_checklist` reads a request for the parts a parser can settle and the
reminder carries them back:

```
Read literally, this message asks for: 15 to 25 items; nothing from LongBench,
LooGLE, ZeroSCROLLS, LoCoMo; a do-not-bother list; a community-convention table.
Deliver each one, or name it in `## Limitations` and say why it is absent.
```

Three properties are the whole design.

**It only reads; it never judges the answer.** No bounce, no model call, no
latency. The gate that owns bouncing says in its own docstring that it bounces for
a missing section and nothing else, and a checklist wrong about what was asked
would spend generations arguing with the reader. A checklist that is merely
incomplete costs nothing.

**It quotes rather than interprets.** The count is the range as written, the
exclusions are the names as written, the artefacts are the noun phrases as
written. A misread is then visibly a misread of the request rather than a rule the
harness invented, which is also why the sentence opens "read literally" and closes
with somewhere for a wrong item to go.

**It stays silent when unsure.** A range followed by a unit is a size, not a count
("16k-256k words", "2024-2026", "4x-8x", "8-80GB"). An exclusion stated in prose
("the four we already ran") yields nothing. A bare "a table" is not an artefact and
"a report" is the answer itself. On a request with no machine-readable constraints
the reminder renders exactly the bytes it always rendered - pinned by a test.

The one thing worth naming as a near-miss: an earlier form of the name rule
anchored on a leading capital and quoted `xRAG` back as `RAG`, which is a checklist
telling the model about a benchmark that does not exist. Items are now split first
and kept or dropped whole, and that case is a test.

No new config key, and no new injection seam: the checklist rides inside the
reminder's own delimiters, so one pair still bounds everything injected and
`strip_reminder` needs no second case.

## Type

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

## Verification

```
uv run --frozen --python 3.12 --all-extras pytest -q tests/ -k research
  774 passed in 61.74s

PYTHONPATH=. uv run --frozen --python 3.12 --extra dev python scripts/check_source_language.py origin/main...HEAD
  clean

uv run --frozen --python 3.12 --extra dev ruff check agents tests
  All checks passed!

uv run --frozen --python 3.12 --extra dev ruff format --check agents tests
  907 files already formatted
```

Sixteen tests, weighted towards what the extractors refuse: four shapes of range
that are sizes rather than counts, a prose exclusion, a bare noun, the answer
itself, an empty task, the camel-cased name, and the unchanged bytes on a request
that carries nothing.
2026-09-07 05:35:47 +00:00