Raven-1/plugins-dist
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
..