DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
test(plugins): pin entry-point loader contract across load, isolation, duplicate and gating paths (#1740)
evan188199-techa325ddfbbd88
diff --git a/evidence/test-plugins-loader-20261004/README.md b/evidence/test-plugins-loader-20261004/README.mdnew file mode 100644index 000000000..4a92614af--- /dev/null+++ b/evidence/test-plugins-loader-20261004/README.md@@ -0,0 +1,54 @@+# test: plugins entry-point loader contract tests++Branch: `test/plugins-entrypoint-loader-20261004` (based on `origin/main` @ `ef2d9e5c3`)++## Scope++New file `tests/plugins/test_entrypoint_loader.py` — 13 contract tests pinning the+current behaviour of the entry-point loader stack, as groundwork for upstream+#961 (learning resource providers with lifecycle controls) and #1307 (managed+third-party plugin platform). No product code was modified.++Layers exercised:++- `deeptutor/core/entry_points.py` — shared `load_entry_point_group` plumbing+- `deeptutor/plugins/loader.py` — `discover_plugins` / `load_plugin_capability`+- `deeptutor/runtime/registry/capability_registry.py` — `CapabilityRegistry.load_plugins`++## Path families covered (asserting current real behaviour)++1. **Normal loading** — clean entry points are coerced in order (`load_entry_point_group`);+ class- and instance-yielding plugins produce manifests (`discover_plugins`); the+ canonical `deeptutor.extensions` group registers into the registry.+2. **Missing dependencies** — an entry point raising `ModuleNotFoundError` at load is+ skipped while others load; instantiation via `load_plugin_capability` propagates a+ missing module (discovery isolates, instantiation does not); a legacy manifest whose+ entry cannot import aborts the remaining legacy manifests (logged only at debug).+3. **Load-error isolation** — a raising entry point is skipped with a warning naming the+ group and entry point; a failing group read returns `[]` with a warning; a coercer+ returning `None` rejects without error.+4. **Duplicate registration** — two canonical entry points shipping the same capability+ name keep the first and warn "already registered"; a legacy plugin with a taken name+ is skipped after canonical wins, and legacy-group presence emits a `DeprecationWarning`.+5. **Disable-gating status quo** — `PluginManifest` has no `enabled`/`disabled` field+ (structural fields only), and the only gates are structural (empty entry,+ `tool.py` entry, non-capability `type`) and short-circuit before resolving the entry,+ so a gated manifest never imports its target.++## Commands and results++```+python -m pytest -q -p no:cacheprovider tests/plugins/test_entrypoint_loader.py+→ 13 passed, 1 warning in 0.27s++python -m pytest -q -p no:cacheprovider tests/plugins/+→ 19 passed, 2 warnings in 0.25s (13 new + 6 pre-existing in test_loader.py)++python -m ruff check tests/plugins/test_entrypoint_loader.py+→ All checks passed!+```++Full verbose run: `pytest-output.txt`.++Environment: Python 3.13.13, pytest 9.1.1, shared repo venv; worktree of+`/Users/Shared/DeepTutor` at `origin/main` (`ef2d9e5c3`, release v1.6.12).diff --git a/evidence/test-plugins-loader-20261004/pytest-output.txt b/evidence/test-plugins-loader-20261004/pytest-output.txtnew file mode 100644index 000000000..5a9743efd--- /dev/null+++ b/evidence/test-plugins-loader-20261004/pytest-output.txt@@ -0,0 +1,12 @@+============================= test session starts ==============================+platform darwin -- Python 3.13.13, pytest-9.1.1, pluggy-1.6.0+rootdir: /Users/xzh/services/ai-development/multica-pilot/workspaces/agents-plan-5fede2af789a/agen-480-1c472ac18bc5/workdir/dt-plugins-loader-wt+configfile: pyproject.toml+plugins: cov-7.1.0, devtools-0.12.2, asyncio-1.4.0, anyio-4.14.2+asyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=function, asyncio_default_test_loop_scope=function+collected 19 items++tests/plugins/test_entrypoint_loader.py ............. [ 68%]+tests/plugins/test_loader.py ...... [100%]++======================== 19 passed, 2 warnings in 0.29s ========================diff --git a/tests/plugins/test_entrypoint_loader.py b/tests/plugins/test_entrypoint_loader.pynew file mode 100644index 000000000..39b268e32--- /dev/null+++ b/tests/plugins/test_entrypoint_loader.py@@ -0,0 +1,370 @@+"""Contract tests for the plugins entry-point loader.++These pin the *current* behaviour of the three layers that turn entry-point+registrations into registered capabilities — the shared plumbing in+``deeptutor.core.entry_points``, the neutral discovery in+``deeptutor.plugins.loader``, and ``CapabilityRegistry.load_plugins`` — so the+managed-plugin slices (upstream #961 / #1307) extend a documented contract+instead of an accident.++Five path families are covered:++* normal loading+* missing dependencies+* load-error isolation+* duplicate registration+* disable-gating status quo (structural gates only, no user toggle)+"""++from __future__ import annotations++import dataclasses+import logging+from types import SimpleNamespace++import pytest++from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability+from deeptutor.core.context import UnifiedContext+import deeptutor.core.entry_points as ep_module+from deeptutor.plugins.loader import (+ PluginManifest,+ discover_plugins,+ load_plugin_capability,+)+from deeptutor.runtime.registry.capability_registry import CapabilityRegistry+from deeptutor.runtime.stream_bus import StreamBus++PLUGINS_GROUP = "deeptutor.plugins"+EXTENSIONS_GROUP = "deeptutor.extensions"+PLUGINS_LOGGER = "deeptutor.plugins.loader"+PLUMBING_LOGGER = "deeptutor.core.entry_points"+REGISTRY_LOGGER = "deeptutor.runtime.registry.capability_registry"+++class _PluginCap(TurnCapability):+ manifest = CapabilityManifest(+ name="plugin_cap",+ description="Capability provided by a plugin entry point.",+ stages=["responding"],+ )++ async def run(self, context: UnifiedContext, stream: StreamBus) -> None:+ return None+++class _PluginCapBis(TurnCapability):+ """Different plugin class, same declared capability name as _PluginCap."""++ manifest = CapabilityManifest(+ name="plugin_cap",+ description="Second plugin shipping the same capability name.",+ stages=["responding"],+ )++ async def run(self, context: UnifiedContext, stream: StreamBus) -> None:+ return None+++class _OtherCap(TurnCapability):+ manifest = CapabilityManifest(+ name="other_cap",+ description="Second plugin capability with its own name.",+ stages=["responding"],+ )++ async def run(self, context: UnifiedContext, stream: StreamBus) -> None:+ return None+++def _make_missing_module_capability() -> type[TurnCapability]:+ """Capability class whose qualified entry points at a module that is not installed."""++ async def _run(self, context: UnifiedContext, stream: StreamBus) -> None:+ return None++ cls = type(+ "_MissingModuleCap",+ (TurnCapability,),+ {+ "manifest": CapabilityManifest(+ name="missing_cap",+ description="Capability whose module cannot be imported.",+ stages=["responding"],+ ),+ "run": _run,+ },+ )+ cls.__module__ = "tests.plugins._no_such_module"+ return cls+++def _ep(name: str, load):+ return SimpleNamespace(name=name, load=load)+++def _fake_groups(groups: dict[str, list]):+ def fake_entry_points(*, group: str):+ return list(groups.get(group, []))++ return fake_entry_points+++# ---------------------------------------------------------------------------+# Normal loading+# ---------------------------------------------------------------------------+++def test_load_entry_point_group_returns_coerced_values_in_order(monkeypatch):+ monkeypatch.setattr(+ ep_module,+ "entry_points",+ _fake_groups({"g": [_ep("a", lambda: "A"), _ep("b", lambda: "B")]}),+ )+ loaded = ep_module.load_entry_point_group("g", lambda _name, obj: obj)+ assert loaded == ["A", "B"]+++def test_discover_plugins_normal_load_from_class_and_instance(monkeypatch):+ monkeypatch.setattr(+ ep_module,+ "entry_points",+ _fake_groups(+ {+ PLUGINS_GROUP: [+ _ep("plugin_cap", lambda: _PluginCap),+ _ep("other_cap", lambda: _OtherCap()),+ ]+ }+ ),+ )+ manifests = discover_plugins()+ assert [m.name for m in manifests] == ["plugin_cap", "other_cap"]+ by_name = {m.name: m for m in manifests}+ for manifest in by_name.values():+ assert manifest.type == "capability"+ assert manifest.stages == ["responding"]+ assert ":" in manifest.entry+ assert by_name["plugin_cap"].entry.endswith("_PluginCap")+ assert by_name["other_cap"].entry.endswith("_OtherCap")+++def test_registry_load_plugins_loads_canonical_extensions_group(monkeypatch):+ monkeypatch.setattr(+ ep_module,+ "entry_points",+ _fake_groups({EXTENSIONS_GROUP: [_ep("plugin_cap", lambda: _PluginCap)]}),+ )+ reg = CapabilityRegistry()+ reg.load_plugins()+ assert isinstance(reg.get("plugin_cap"), _PluginCap)+++# ---------------------------------------------------------------------------+# Missing dependencies+# ---------------------------------------------------------------------------+++def test_missing_dependency_entry_point_is_skipped_others_still_load(monkeypatch, caplog):+ def _missing_dep():+ raise ModuleNotFoundError("No module named 'plugin_dep'")++ monkeypatch.setattr(+ ep_module,+ "entry_points",+ _fake_groups(+ {+ PLUGINS_GROUP: [+ _ep("needs_dep", _missing_dep),+ _ep("plugin_cap", lambda: _PluginCap),+ ]+ }+ ),+ )+ with caplog.at_level(logging.WARNING, logger=PLUGINS_LOGGER):+ manifests = discover_plugins()+ assert [m.name for m in manifests] == ["plugin_cap"]+ assert any("needs_dep" in record.getMessage() for record in caplog.records)+++def test_load_plugin_capability_propagates_missing_module():+ """Discovery isolates import failures; instantiation does not (current contract)."""++ manifest = PluginManifest(+ name="gone_cap",+ type="capability",+ entry="tests.plugins._no_such_module:Cap",+ )+ with pytest.raises(ModuleNotFoundError):+ load_plugin_capability(manifest)+++def test_legacy_instantiation_error_aborts_remaining_legacy_manifests(monkeypatch, caplog):+ """A legacy manifest that fails to instantiate drops every manifest after it."""++ missing_cls = _make_missing_module_capability()+ monkeypatch.setattr(+ ep_module,+ "entry_points",+ _fake_groups(+ {+ EXTENSIONS_GROUP: [],+ PLUGINS_GROUP: [+ _ep("good_first", lambda: _PluginCap),+ _ep("needs_dep", lambda: missing_cls),+ _ep("good_after", lambda: _OtherCap),+ ],+ }+ ),+ )+ reg = CapabilityRegistry()+ with caplog.at_level(logging.DEBUG, logger=REGISTRY_LOGGER):+ reg.load_plugins()+ assert isinstance(reg.get("plugin_cap"), _PluginCap)+ assert reg.get("other_cap") is None+ assert any(+ "Legacy plugin loader unavailable" in record.getMessage() for record in caplog.records+ )+++# ---------------------------------------------------------------------------+# Load-error isolation+# ---------------------------------------------------------------------------+++def test_entry_point_load_error_is_isolated_and_named_in_warning(monkeypatch, caplog):+ def _boom():+ raise RuntimeError("boom at import time")++ monkeypatch.setattr(+ ep_module,+ "entry_points",+ _fake_groups(+ {+ PLUGINS_GROUP: [+ _ep("bad", _boom),+ _ep("plugin_cap", lambda: _PluginCap),+ _ep("worse", _boom),+ ]+ }+ ),+ )+ with caplog.at_level(logging.WARNING, logger=PLUGINS_LOGGER):+ manifests = discover_plugins()+ assert [m.name for m in manifests] == ["plugin_cap"]+ assert any(+ PLUGINS_GROUP in message and "skipping" in message+ for message in (record.getMessage() for record in caplog.records)+ )+++def test_group_read_failure_returns_empty_with_warning(monkeypatch, caplog):+ def _broken_reader(*, group: str):+ raise RuntimeError("metadata reader exploded")++ monkeypatch.setattr(ep_module, "entry_points", _broken_reader)+ with caplog.at_level(logging.WARNING, logger=PLUMBING_LOGGER):+ loaded = ep_module.load_entry_point_group(PLUGINS_GROUP, lambda _name, obj: obj)+ assert loaded == []+ assert any(PLUGINS_GROUP in record.getMessage() for record in caplog.records)+++def test_coercer_none_rejects_entry_point_without_error(monkeypatch):+ monkeypatch.setattr(+ ep_module,+ "entry_points",+ _fake_groups({"g": [_ep("junk", lambda: object()), _ep("keep", lambda: "kept")]}),+ )+ loaded = ep_module.load_entry_point_group(+ "g", lambda name, obj: obj if name == "keep" else None+ )+ assert loaded == ["kept"]+++# ---------------------------------------------------------------------------+# Duplicate registration+# ---------------------------------------------------------------------------+++def test_duplicate_extension_registration_first_wins_with_warning(monkeypatch, caplog):+ monkeypatch.setattr(+ ep_module,+ "entry_points",+ _fake_groups(+ {+ EXTENSIONS_GROUP: [+ _ep("first_ship", lambda: _PluginCap),+ _ep("second_ship", lambda: _PluginCapBis),+ ]+ }+ ),+ )+ reg = CapabilityRegistry()+ with caplog.at_level(logging.WARNING, logger=REGISTRY_LOGGER):+ reg.load_plugins()+ assert reg.list_capabilities().count("plugin_cap") == 1+ cap = reg.get("plugin_cap")+ assert isinstance(cap, _PluginCap)+ assert any(+ "second_ship" in record.getMessage() and "already registered" in record.getMessage()+ for record in caplog.records+ )+++def test_legacy_plugin_with_taken_name_is_ignored(monkeypatch):+ """Canonical registrations win; a same-named legacy plugin is skipped, and the+ legacy group's presence is announced with a DeprecationWarning."""++ monkeypatch.setattr(+ ep_module,+ "entry_points",+ _fake_groups(+ {+ EXTENSIONS_GROUP: [_ep("plugin_cap", lambda: _PluginCap)],+ PLUGINS_GROUP: [_ep("legacy_dup", lambda: _PluginCapBis)],+ }+ ),+ )+ reg = CapabilityRegistry()+ with pytest.warns(DeprecationWarning, match="deprecated"):+ reg.load_plugins()+ assert reg.list_capabilities().count("plugin_cap") == 1+ assert isinstance(reg.get("plugin_cap"), _PluginCap)+++# ---------------------------------------------------------------------------+# Disable-gating status quo+# ---------------------------------------------------------------------------+++def test_plugin_manifest_has_no_enable_disable_gate():+ """Today a plugin cannot be disabled declaratively: PluginManifest carries no+ enabled/disabled flag, and the loader consults none."""++ field_names = {f.name for f in dataclasses.fields(PluginManifest)}+ assert field_names == {+ "name",+ "type",+ "description",+ "stages",+ "version",+ "author",+ "entry",+ }+ assert not field_names & {"enabled", "disabled"}+++def test_structural_gates_short_circuit_before_resolving_entry():+ """The only gates are structural (entry / type) and run before any import, so a+ gated manifest never triggers its (here broken) entry point."""++ empty_entry = PluginManifest(name="t1", type="capability", entry="")+ tool_script = PluginManifest(name="t2", type="capability", entry="tests/plugins/tool.py")+ wrong_type = PluginManifest(+ name="t3",+ type="tool",+ entry="tests.plugins._no_such_module:Cap",+ )+ assert load_plugin_capability(empty_entry) is None+ assert load_plugin_capability(tool_script) is None+ assert load_plugin_capability(wrong_type) is None