## 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>
6.7 KiB
Building a Plugin
A Raven plugin contributes to the runtime through a declarative manifest and Python factories. It is not a skill bundle, an MCP server, or a Codex plugin. Plugin code executes inside Raven's process and is trusted code, not sandboxed by the manifest.
Choose a contribution
Manifest group under plugin.contributes |
Purpose |
|---|---|
tools |
Model-callable actions |
hooks |
Loop timing hooks or supported participant factories |
memory_backends |
Memory storage/recall implementation |
services |
Resident-host lifecycle work |
tool_gates |
Plugin-specific tool adjudication |
session_observers |
Session lifecycle observations |
onboard |
Setup steps for the plugin's memory backend |
Use the existing contract in raven/contracts/ rather than importing CLI/RPC
internals. A Tool Gate is not the platform Permission Gate and does not replace
its authorization decisions.
Start with a working template
The default agent scaffold includes a directory-shaped plugin:
raven agents new example-agent --dry-run
Create it as described in Building an Agent, then customize the generated tool/hook. Its layout is:
plugins/example-agent-flow/
raven-plugin.toml
example_agent_flow/
__init__.py
plugin.py
tools/
__init__.py
hello.py
A manifest for that layout:
[plugin]
id = "example-agent-flow"
version = "0.1.0"
display_name = "Example Agent Flow"
enabled_by_default = true
[[plugin.contributes.tools]]
name = "example_agent_hello"
factory = "example_agent_flow.tools.hello:make_hello"
[[plugin.contributes.hooks]]
name = "example_agent_flow"
factory = "example_agent_flow.plugin:make_hook"
Directory discovery reads manifests without importing plugin code. Entry-point
discovery uses importlib.resources.files() to locate the packaged manifest,
which imports the package's __init__.py. Keep that module free of startup work.
Activation resolves the module.path:callable factories; a valid manifest alone
does not establish that a factory can load or its tool will register.
Factories and configuration
A factory receives PluginContext from raven.plugins.context:
configis only this plugin's admitted configuration slice.servicesexposes the declared host service surface.loggeris bound to the plugin identity.
Tool factories return a Tool or None to decline registration. A tool
provides a stable name, description, JSON-schema parameters, and asynchronous
execution returning text or ToolResult. Reuse the generated greeting example;
do not invent a different signature for a factory.
The config slice belongs under plugins.config["example-agent-flow"].
Declared config schema fields are checked at admission. An empty schema is
pass-through, not automatic validation of arbitrary values; validate your own
settings before using them. Unknown configuration keys may warn and pass through.
Prefix new tool names with the plugin/agent identity. A plugin tool using a
built-in name deliberately replaces that built-in; two plugins contributing
the same tool name conflict: the plugin activated first keeps the name and the
other is skipped. A plugin that fails to activate -- a factory that will not
import, or a name conflict -- is skipped alone: the host stays up, every other
plugin loads, the host prints a notice naming the plugin and its cause, and
raven plugins lists it as failed. So check the effective tool roster as well
as boot success. Adding its id to plugins.disabled stops the host loading it,
and the host's product sub-agents inherit that opt-out (a product never
inherits the opt-out of its own engine plugin).
Hooks and per-turn participants
The AgentHook timing phases are before_user_inbound, before_iteration,
before_execute_tools, after_iteration, terminal_answerless, and after_send.
The generated example overrides only after_send; other phases pass through.
Tool withholding belongs to before_iteration, not an arbitrary phase.
For agent-specific judgements, the current AgentParticipant paper offers
read-only StepView inputs and optional verbs such as intake, select_tools,
advise, system_addendum, review, salvage, outbound, and archive.
The host owns timing and adapts supported participant factories through the
hook contribution path. A participant is constructed per turn, so turn-local
state does not leak into another concurrent conversation.
Read raven/contracts/participant.py and raven/contracts/loop_hooks.py
before choosing. Preserve the contract's version/tier boundaries rather than
writing to the loop's transcript or reaching into its scheduler.
Lifecycle and packaging
Services implement the lifecycle in raven/contracts/services.py. Assembly
constructs contributions; the resident host starts and stops them. Do not start
background work as an import side effect or mutate the assembled runtime from
a service. Test shutdown and failure paths, not only startup.
Directory discovery scans <root>/<plugin-id>/raven-plugin.toml, including
roots supplied by plugins.dirs. Duplicate plugin ids resolve by the current
priority, from highest to lowest: bundled, user, project/extra directories,
then entry points.
Do not use a duplicate id as a version-selection mechanism without checking
which copy actually won.
For a separately installed engine, use the wheel-shaped scaffold. Its entry point targets a package, and its manifest must be packaged inside that package:
[project.entry-points."raven.plugins"]
example-agent-engine = "example_agent_engine"
Installing an enabled-by-default engine can activate discovery in every Raven
process in that environment. Keep the engine template's explicit configuration
gate so tools only register for the intended agent. Use uv for dependencies,
and keep runtime state and secrets outside the distributable package.
Verification checklist
- Parse the manifest through
PluginManifest.from_toml_path. - Import factories in the actual runtime environment and exercise enabled, disabled, and invalid-config cases.
- Test tool arguments/results and any denial or rollback path without a live model.
- Verify the effective roster and one harmless real task through the hosting surface that will use the plugin.
- Test two concurrent conversations, service shutdown, and a missing dependency.
Maintainer regression checks:
uv run pytest tests/test_plugin_manifest.py tests/test_plugin_registry.py tests/test_plugin_tools.py tests/test_plugin_hooks.py -q
Schemas are exported under schemas/. Developer workflow and repository gates
are in Development; permissions are documented separately in
Permissions and Security.