## 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>
308 lines
12 KiB
Python
308 lines
12 KiB
Python
"""Plugins observe session retirement: manifest, registry, stack, attachment.
|
|
|
|
The sixth contribution kind (paper: contracts/session_events.py). Pinned here:
|
|
the manifest entry (an observer without a usable name is refused at the door),
|
|
registry activation with cross-plugin conflict detection, the lenient stack
|
|
builder with its identity stamp, and the attachment discipline -- observers are
|
|
built inert at assembly (BIND touches no store), attached to the session store
|
|
only when a resident host starts the plugin services, detached when it stops
|
|
them, so a one-shot host that never starts services never attaches an observer.
|
|
The store-side notify semantics (every delete request, the removal outcome, a
|
|
raising observer logged and skipped) live with the store's own tests
|
|
(test_session_manager.py); the delete faces that must all reach the shared
|
|
store are pinned in test_acp_methods.py and test_rpc_session.py.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import sys
|
|
import textwrap
|
|
import types
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
from pydantic import ValidationError
|
|
|
|
from raven.contracts.llm_provider import LLMResponse
|
|
from raven.contracts.session_events import SessionObserver
|
|
from raven.plugins import (
|
|
Contributes,
|
|
DiscoveredPlugin,
|
|
ManifestOrigin,
|
|
PluginManifest,
|
|
PluginRegistry,
|
|
SessionObserverContribution,
|
|
)
|
|
from raven.providers.base import LLMProvider
|
|
|
|
_INJECTED: set[str] = set()
|
|
|
|
|
|
def _install_module(name: str, attrs: dict[str, object]) -> None:
|
|
mod = types.ModuleType(name)
|
|
for k, v in attrs.items():
|
|
setattr(mod, k, v)
|
|
sys.modules[name] = mod
|
|
_INJECTED.add(name)
|
|
|
|
|
|
@pytest.fixture(autouse=True)
|
|
def _cleanup_modules():
|
|
yield
|
|
for name in _INJECTED:
|
|
sys.modules.pop(name, None)
|
|
_INJECTED.clear()
|
|
|
|
|
|
def _discovered(plugin_id: str, observers: list[tuple[str, str]]) -> DiscoveredPlugin:
|
|
mf = PluginManifest(
|
|
id=plugin_id,
|
|
version="0.1.0",
|
|
contributes=Contributes(
|
|
session_observers=[SessionObserverContribution(name=n, factory=f) for n, f in observers]
|
|
),
|
|
)
|
|
return DiscoveredPlugin(manifest=mf, source=ManifestOrigin.USER, location=None)
|
|
|
|
|
|
class _Observer:
|
|
"""A paper-shaped observer that records what it hears."""
|
|
|
|
def __init__(self, tag: str = "obs", log: list | None = None) -> None:
|
|
self.tag = tag
|
|
self.log = log if log is not None else []
|
|
|
|
def on_session_deleted(self, session_key: str, removed: bool) -> None:
|
|
self.log.append((self.tag, session_key, removed))
|
|
|
|
|
|
class TestManifestSessionObservers:
|
|
def test_parses_a_session_observers_contribution(self) -> None:
|
|
mf = PluginManifest.from_toml_str(
|
|
textwrap.dedent(
|
|
"""
|
|
[plugin]
|
|
id = "code-flow"
|
|
version = "0.1.0"
|
|
[[plugin.contributes.session_observers]]
|
|
name = "workspace_release"
|
|
factory = "some_flow.lifecycle:make_release_observer"
|
|
"""
|
|
)
|
|
)
|
|
assert [o.name for o in mf.contributes.session_observers] == ["workspace_release"]
|
|
|
|
def test_default_session_observers_empty(self) -> None:
|
|
assert PluginManifest(id="p", version="0.1.0").contributes.session_observers == []
|
|
|
|
def test_bad_factory_ref_rejected(self) -> None:
|
|
with pytest.raises(ValidationError):
|
|
SessionObserverContribution(name="o", factory="not-a-ref")
|
|
|
|
def test_an_observer_without_a_usable_name_is_a_manifest_error(self) -> None:
|
|
with pytest.raises(ValidationError, match="name"):
|
|
PluginManifest.from_toml_str(
|
|
textwrap.dedent(
|
|
"""
|
|
[plugin]
|
|
id = "p"
|
|
version = "0.1.0"
|
|
[[plugin.contributes.session_observers]]
|
|
factory = "m:make"
|
|
"""
|
|
)
|
|
)
|
|
with pytest.raises(ValidationError, match="name"):
|
|
SessionObserverContribution(name="", factory="m:make")
|
|
|
|
def test_duplicate_session_observer_names_rejected(self) -> None:
|
|
with pytest.raises(ValidationError, match="duplicate session_observer name"):
|
|
PluginManifest(
|
|
id="p",
|
|
version="0.1.0",
|
|
contributes=Contributes(
|
|
session_observers=[
|
|
SessionObserverContribution(name="dup", factory="m:a"),
|
|
SessionObserverContribution(name="dup", factory="m:b"),
|
|
]
|
|
),
|
|
)
|
|
|
|
|
|
class TestRegistrySessionObservers:
|
|
def test_activates_and_builds(self) -> None:
|
|
seen = {}
|
|
|
|
def make(ctx):
|
|
seen["config"] = ctx.config
|
|
return "observer-instance"
|
|
|
|
_install_module("_po_a", {"make": make})
|
|
reg = PluginRegistry()
|
|
reg.activate([_discovered("alpha", [("workspace_release", "_po_a:make")])])
|
|
assert reg.session_observer_names() == ["workspace_release"]
|
|
assert reg.session_observer_plugin_id("workspace_release") == "alpha"
|
|
from raven.plugins import ServiceLocator
|
|
|
|
built = reg.build_session_observer(
|
|
"workspace_release",
|
|
config={"mode": "strict"},
|
|
services=ServiceLocator(workspace=Path("/w"), user_id="u", agent_id="a"),
|
|
)
|
|
assert built == "observer-instance"
|
|
assert seen["config"] == {"mode": "strict"}
|
|
|
|
def test_cross_plugin_name_conflict_skips_the_later_plugin(self) -> None:
|
|
_install_module("_po_b", {"make": lambda ctx: None})
|
|
reg = PluginRegistry()
|
|
reg.activate([_discovered("one", [("same", "_po_b:make")]), _discovered("two", [("same", "_po_b:make")])])
|
|
assert reg.activated_ids() == ["one"]
|
|
assert reg.session_observer_plugin_id("same") == "one"
|
|
[failure] = reg.activation_failures()
|
|
assert failure.plugin_id == "two"
|
|
assert "session_observer 'same' contributed by both 'one' and 'two'" in failure.reason
|
|
|
|
|
|
class TestBuildPluginSessionObservers:
|
|
def _config(self, plugin_config: dict | None = None):
|
|
from raven.config.raven import PluginsConfig, RavenConfig
|
|
|
|
return RavenConfig(plugins=PluginsConfig(config=dict(plugin_config or {})))
|
|
|
|
def test_builds_observers_with_the_plugins_slice_and_stamps_identity(self, tmp_path: Path) -> None:
|
|
from raven.core.plugin_stack import build_plugin_session_observers
|
|
|
|
def make(ctx):
|
|
return _Observer(f"obs::{ctx.config.get('flag')}")
|
|
|
|
_install_module("_po_c", {"make": make})
|
|
reg = PluginRegistry()
|
|
reg.activate([_discovered("myplugin", [("o1", "_po_c:make")])])
|
|
built = build_plugin_session_observers(tmp_path, self._config({"myplugin": {"flag": "on"}}), registry=reg)
|
|
assert [o.tag for o in built] == ["obs::on"]
|
|
assert built[0].contributed_by == "myplugin"
|
|
assert isinstance(built[0], SessionObserver), "the paper face is on_session_deleted"
|
|
|
|
def test_failing_and_declining_factories_are_skipped(self, tmp_path: Path) -> None:
|
|
"""Declining (a factory returning None) is the sanctioned opt-out:
|
|
nothing to release means no observer at all."""
|
|
from raven.core.plugin_stack import build_plugin_session_observers
|
|
|
|
def boom(ctx):
|
|
raise RuntimeError("nope")
|
|
|
|
_install_module("_po_d", {"boom": boom, "decline": lambda ctx: None})
|
|
reg = PluginRegistry()
|
|
reg.activate([_discovered("p", [("a", "_po_d:boom"), ("b", "_po_d:decline")])])
|
|
assert build_plugin_session_observers(tmp_path, self._config(), registry=reg) == []
|
|
|
|
@pytest.mark.parametrize("fake", [object(), "observer-as-str"])
|
|
def test_an_observer_that_cannot_carry_the_stamp_still_boards(self, tmp_path: Path, fake) -> None:
|
|
from raven.core.plugin_stack import build_plugin_session_observers
|
|
|
|
def make(ctx):
|
|
return fake
|
|
|
|
_install_module("_po_e", {"make": make})
|
|
reg = PluginRegistry()
|
|
reg.activate([_discovered("p", [("o", "_po_e:make")])])
|
|
built = build_plugin_session_observers(tmp_path, self._config(), registry=reg)
|
|
assert built == [fake]
|
|
assert not hasattr(built[0], "contributed_by")
|
|
|
|
def test_a_stub_registry_contributes_no_observers(self, tmp_path: Path) -> None:
|
|
from raven.core.plugin_stack import build_plugin_session_observers
|
|
|
|
assert build_plugin_session_observers(tmp_path, self._config(), registry=object()) == []
|
|
|
|
|
|
class _Provider(LLMProvider):
|
|
def __init__(self) -> None:
|
|
super().__init__(api_key="test")
|
|
|
|
async def chat(
|
|
self,
|
|
messages,
|
|
tools=None,
|
|
model=None,
|
|
max_tokens=4096,
|
|
temperature=0.7,
|
|
reasoning_effort=None,
|
|
tool_choice=None,
|
|
):
|
|
return LLMResponse(content="ok", finish_reason="stop")
|
|
|
|
def get_default_model(self) -> str:
|
|
return "fake/default"
|
|
|
|
|
|
DEMO_OBSERVER = """
|
|
class DemoObserver:
|
|
def __init__(self):
|
|
self.heard = []
|
|
|
|
def on_session_deleted(self, session_key, removed):
|
|
self.heard.append((session_key, removed))
|
|
|
|
def make(ctx):
|
|
return DemoObserver()
|
|
"""
|
|
|
|
|
|
@pytest.mark.asyncio
|
|
async def test_a_plugin_observer_rides_the_built_runtime_and_hears_a_delete(tmp_path: Path, monkeypatch) -> None:
|
|
"""End to end: a plugin directory's observer rides discovery -> activation
|
|
-> build -> the loop's inert tuple, satisfies the paper's face, stays off
|
|
the store until the resident host starts the services, hears a live delete
|
|
with its outcome, and stops hearing after the host stops them."""
|
|
from raven.config.raven import RavenConfig
|
|
from raven.config.schema import Config
|
|
from raven.core import plugin_stack, runtime
|
|
|
|
plug = tmp_path / "plugins" / "demoobs"
|
|
plug.mkdir(parents=True)
|
|
plug.joinpath("raven-plugin.toml").write_text(
|
|
'[plugin]\nid = "demoobs"\nversion = "1.0"\n'
|
|
"[[plugin.contributes.session_observers]]\n"
|
|
'name = "demo_observer"\nfactory = "demoobs_mod:make"\n'
|
|
)
|
|
plug.joinpath("demoobs_mod.py").write_text(DEMO_OBSERVER)
|
|
_INJECTED.add("demoobs_mod")
|
|
monkeypatch.setattr(
|
|
plugin_stack,
|
|
"plugin_discovery_sources",
|
|
lambda: {
|
|
"bundled_dir": tmp_path / "none",
|
|
"user_dir": tmp_path / "plugins",
|
|
"project_dir": tmp_path / "none",
|
|
"entry_points_group": None,
|
|
},
|
|
)
|
|
monkeypatch.setattr(runtime.token_wise_stack, "install_from_config", lambda *a, **k: None)
|
|
monkeypatch.setattr(runtime.token_wise_stack, "caching_probe", lambda *a, **k: False)
|
|
|
|
config = Config()
|
|
config.agents.defaults.workspace = str(tmp_path / "ws")
|
|
rt = runtime.build_runtime(config, RavenConfig(), provider=_Provider())
|
|
try:
|
|
observers = rt.loop.session_observers
|
|
assert len(observers) == 1
|
|
assert observers[0].contributed_by == "demoobs"
|
|
assert isinstance(observers[0], SessionObserver)
|
|
assert rt.loop.sessions._delete_observers == (), "BIND touches no store"
|
|
|
|
session = rt.loop.sessions.get_or_create("tui:e2e_obs")
|
|
session.add_message("user", "hi")
|
|
rt.loop.sessions.save(session)
|
|
|
|
await rt.loop.start_plugin_services()
|
|
assert rt.loop.sessions.delete("tui:e2e_obs") is True
|
|
assert rt.loop.sessions.delete("tui:e2e_obs") is False
|
|
assert observers[0].heard == [("tui:e2e_obs", True), ("tui:e2e_obs", False)]
|
|
|
|
await rt.loop.stop_plugin_services()
|
|
rt.loop.sessions.delete("tui:unheard")
|
|
assert len(observers[0].heard) == 2, "a stopped host's observers hear nothing"
|
|
finally:
|
|
rt.discard()
|