coderouter-cli 2.2.0__tar.gz → 2.3.0a3__tar.gz

{coderouter_cli-2.2.0 → coderouter_cli-2.3.0a3}/CHANGELOG.md

@@ -6,6 +6,145 @@ versioning follows [SemVer](https://semver.org/).
 
 ---
 
+## [v2.3.0a3] — 2026-05-08 (Plugin SDK — LogRecord.module collision fix)
+
+Patch over `v2.3.0a2`. The wheel-install-and-test job in CI surfaced
+one more issue that the source-tree test runs hadn't caught.
+
+### Fixed
+
+- **`KeyError: "Attempt to overwrite 'module' in LogRecord"`** in
+  `discover_and_load`. Python's `logging` module reserves several
+  attribute names on `LogRecord` (``name`` / ``msg`` / ``args`` /
+  ``levelname`` / ``levelno`` / ``pathname`` / ``filename`` /
+  **``module``** / ``lineno`` / ``funcName`` / ``exc_info`` /
+  ``exc_text`` / ``stack_info`` / ``created`` / ``msecs`` /
+  ``relativeCreated`` / ``thread`` / ``threadName`` / ``processName``
+  / ``process`` / ``message`` / ``asctime``); passing any of these
+  via ``extra=`` raises ``KeyError`` rather than silently overwriting.
+  v2.3.0a1's `plugin-loaded` and `plugin-load-failed` log lines used
+  ``"module"`` as an extra key (intended to mean "the module:attr
+  string from `entry_point.value`"), which collided.
+
+  Renamed the key to ``"entry_point"`` everywhere in
+  `coderouter/plugins/loader.py`. Audited every `extra=` payload in
+  the new plugins module + the engine's hook helpers — none of them
+  use any of the other reserved names.
+
+### Files touched
+
+```
+M  coderouter/plugins/loader.py     — "module" → "entry_point" (×2)
+M  CHANGELOG.md, pyproject.toml     — 2.3.0a2 → 2.3.0a3
+```
+
+No other behavioral change. Downstream consumers that don't rely on
+the structured log shape are unaffected; anyone parsing the JSON
+log lines should rename `module` → `entry_point` to match.
+
+---
+
+## [v2.3.0a2] — 2026-05-08 (Plugin SDK — CI fixes)
+
+Patch over `v2.3.0a1`. The Plugin SDK addition was sound but two
+issues showed up in the test matrix and have been fixed:
+
+### Fixed
+
+- **`'FallbackEngine' object has no attribute 'plugins'`** —
+  Many existing tests construct the engine via
+  ``FallbackEngine.__new__`` to bypass full initialization (only
+  ``config`` + ``_adapters`` are populated). The new direct
+  attribute ``self.plugins`` was missing on those instances and
+  raised ``AttributeError`` whenever the engine reached the hook
+  helpers. Converted to the same lazy-property pattern that
+  ``_adaptive`` / ``_budget`` / ``_memory_pressure_guard`` already
+  use: store under ``_plugin_registry`` in ``__init__``, surface
+  via a ``plugins`` property that lazily builds an empty registry
+  when the underlying attribute is missing. Bypass-tests now see
+  an empty registry and the hook helpers short-circuit cleanly.
+
+- **`LogRecord` assertions in `test_plugins_loader.py` /
+  `test_plugins_integration.py`** — used ``rec.message`` which
+  isn't always populated (depends on whether a Formatter has
+  processed the record). Switched to ``rec.msg`` with exact
+  match, matching the rest of the test suite's convention
+  (e.g. ``test_fallback_paid_gate.py``,
+  ``test_memory_pressure.py``) where structured-log event names
+  are tested via ``rec.msg == "<event-name>"``.
+
+### Files touched
+
+```
+M  coderouter/routing/fallback.py    — lazy plugins property
+M  tests/test_plugins_loader.py      — rec.msg ==
+M  tests/test_plugins_integration.py — rec.msg ==
+M  CHANGELOG.md, pyproject.toml      — 2.3.0a1 → 2.3.0a2
+```
+
+No behavioral change vs `v2.3.0a1`. If you've already pinned
+`v2.3.0a1` in a downstream that doesn't construct engines via
+``__new__`` and doesn't run our test suite, the upgrade is a
+no-op for runtime.
+
+---
+
+## [v2.3.0a1] — 2026-05-08 (Plugin SDK)
+
+**Theme: in-process plugin SDK. Core 5 deps stays untouched.** v2.3.0a1 adds the plugin discovery + dispatch infrastructure that ``coderouter-plugin-memory`` 0.1.0+ will consume. Two of the six designed extension points (``input_filter`` and ``observer``) are wired into the engine; the other four (``frontend`` / ``guard`` / ``output_filter`` / ``adapter``) ship as Protocol contracts only — plugin authors can target them today, but engine integration is deferred until a real plugin drives the requirement (v2.4+).
+
+### Plugin SDK (new module: ``coderouter.plugins``)
+
+| Component | What it does |
+|---|---|
+| ``coderouter.plugins.base`` | Six ``Protocol`` definitions (InputFilter, Observer, Frontend, Guard, OutputFilter, Adapter). All ``runtime_checkable`` so ``isinstance(x, InputFilter)`` works for diagnostics. |
+| ``coderouter.plugins.loader`` | Reads ``importlib.metadata.entry_points`` under ``coderouter.<group>`` and applies the user's explicit ``plugins.enabled`` allowlist. Failures are logged + degraded — never abort startup. |
+| ``coderouter.plugins.registry`` | Group-keyed container. ``input_filters`` / ``observers`` properties return defensive copies. |
+| ``PluginsConfig`` (in ``schemas.py``) | New ``plugins:`` block in ``providers.yaml`` — ``enabled`` list + ``config`` dict. Absent → identical behavior to v2.2.0. |
+| ``FallbackEngine`` integration | ``__init__`` now takes ``plugins=PluginRegistry``; ``generate_anthropic`` runs the InputFilter chain before chain dispatch; both Anthropic paths fan out ``request_completed`` to observers as fire-and-forget asyncio tasks. The no-plugin code path is bit-identical to v2.2.0. |
+| ``ingress/app.py`` | ``create_app`` calls ``discover_and_load`` and hands the registry to the engine. |
+
+### Supply-chain defense
+
+``pip install coderouter-plugin-X`` is **not** sufficient to activate a plugin. The user must also list its entry-point name under ``plugins.enabled`` in ``providers.yaml``. Unlisted-but-installed entry points are logged ``plugin-skipped`` and never instantiated, so a compromised transitive dependency cannot wedge itself into the request flow.
+
+### Failure semantics
+
+| Failure | Engine behavior |
+|---|---|
+| ``importlib.metadata`` finds no entry point with an enabled name | ``plugin-not-found`` warn (one per missing name); engine boots normally. |
+| Plugin module import fails | ``plugin-load-failed`` error; engine boots without that plugin. |
+| Plugin ``__init__`` raises | Same — error logged, plugin skipped. |
+| ``InputFilter.transform`` raises | ``input-filter-failed`` warn; pre-mutation request flows to the next filter / chain. |
+| ``Observer.on_event`` raises | ``observer-failed`` warn; engine response is unaffected (fanout is fire-and-forget). |
+
+### Backward compatibility
+
+100%. ``providers.yaml`` files written for v2.2.0 keep working unchanged because ``plugins`` is optional and defaults to ``None``. The ``FallbackEngine(config)`` legacy constructor keeps working too — the new ``plugins=`` parameter has a sane default.
+
+### Files changed
+
+```
+A  coderouter/plugins/__init__.py
+A  coderouter/plugins/base.py
+A  coderouter/plugins/loader.py
+A  coderouter/plugins/registry.py
+M  coderouter/config/schemas.py    — PluginsConfig + CodeRouterConfig.plugins field
+M  coderouter/routing/fallback.py  — engine __init__, _apply_input_filters,
+                                     _fanout_observers, _safe_observe + hook calls
+M  coderouter/ingress/app.py       — discover_and_load wired into create_app
+A  tests/test_plugins_registry.py
+A  tests/test_plugins_loader.py
+A  tests/test_plugins_integration.py
+```
+
+### Out-of-scope (deferred)
+
+- Engine integration for ``frontend`` / ``guard`` / ``output_filter`` / ``adapter`` — Protocol contracts only.
+- ``coderouter-plugin-memory`` itself — separate repo, separate release cadence (0.1.0 lands after this Core release publishes).
+
+---
+
 ## [v2.2.0] — 2026-05-06 (Self-healing + Multi-day operation + Replay)
 
 **Theme: 自己修復 + 状態永続化 + 統計リプレイで "無人長時間運用" 基盤を完成。** v2.0-J で UNHEALTHY provider の自動除外 + restart + 復帰を実装、v2.0-K で sqlite3 StateStore + 構造化 audit log + request journal + `coderouter replay` 統計 A/B 分析を実装。v2.2 で Unsloth Studio 由来の堅牢化 3 件を吸収。**6 系統障害全対処 + 自己修復 + 永続化 + リプレイ**に到達。

{coderouter_cli-2.2.0 → coderouter_cli-2.3.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.2.0
+Version: 2.3.0a3
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter

{coderouter_cli-2.2.0 → coderouter_cli-2.3.0a3}/coderouter/config/schemas.py

@@ -14,7 +14,7 @@ Design notes (see plan.md §2 / §5.4):
 from __future__ import annotations
 
 import re
-from typing import Literal, Self
+from typing import Any, Literal, Self
 
 from pydantic import BaseModel, ConfigDict, Field, HttpUrl, model_validator
 
@@ -852,6 +852,51 @@ class AutoRouterConfig(BaseModel):
     )
 
 
+class PluginsConfig(BaseModel):
+    """The ``plugins:`` block in providers.yaml (v2.3.0).
+
+    Declarative opt-in for in-process plugins distributed as separate
+    PyPI packages (``coderouter-plugin-*``). Two-step gating:
+
+    1. ``pip install coderouter-plugin-X`` makes the entry point
+       discoverable.
+    2. The plugin's entry-point name MUST appear in :attr:`enabled`
+       before the loader will instantiate it.
+
+    Step 2 is the supply-chain defense: a malicious transitive dep
+    cannot wedge itself into the request flow without an explicit
+    user action in providers.yaml. See
+    :mod:`coderouter.plugins.loader` for the full discovery logic.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: list[str] = Field(
+        default_factory=list,
+        description=(
+            "v2.3.0: ordered list of plugin entry-point names to load. "
+            "An entry-point name is the LHS of an entry in a plugin's "
+            "``[project.entry-points.\"coderouter.<group>\"]`` block — "
+            "e.g. ``memory`` for ``coderouter-plugin-memory``. Order "
+            "controls the order InputFilter chains apply (each filter "
+            "sees the previous filter's output). Empty list = no "
+            "plugins active (default behavior, identical to v2.2.0)."
+        ),
+    )
+    config: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description=(
+            "v2.3.0: per-plugin keyword arguments. The dict at "
+            "``config[<plugin-name>]`` is splatted into the plugin's "
+            "``__init__`` as ``**kwargs``. Validation of each "
+            "sub-dict's schema is the plugin's responsibility — Core "
+            "stays out of plugin-specific config shapes. Plugins not "
+            "listed in :attr:`enabled` are ignored even if they have "
+            "config entries here."
+        ),
+    )
+
+
 class CodeRouterConfig(BaseModel):
     """Top-level config loaded from providers.yaml."""
 
@@ -1001,6 +1046,21 @@ class CodeRouterConfig(BaseModel):
         ),
     )
 
+    # v2.3.0: in-process plugin SDK. Optional — when None, the engine
+    # builds an empty ``PluginRegistry`` and the hook chains are
+    # short-circuited (zero-cost path, identical to v2.2.0 behavior).
+    plugins: PluginsConfig | None = Field(
+        default=None,
+        description=(
+            "v2.3.0: in-process plugin configuration. Plugins are "
+            "distributed as separate PyPI packages (e.g. "
+            "``coderouter-plugin-memory``); this block lists which of "
+            "the installed plugins to actually activate, and supplies "
+            "their per-plugin keyword arguments. Absent or empty = no "
+            "plugins (zero-cost, backward-compatible default)."
+        ),
+    )
+
     @model_validator(mode="after")
     def _check_default_profile_exists(self) -> CodeRouterConfig:
         """v0.6-A: surface a typo'd ``default_profile`` at load time.

{coderouter_cli-2.2.0 → coderouter_cli-2.3.0a3}/coderouter/ingress/app.py

@@ -17,6 +17,7 @@ from coderouter.ingress.metrics_routes import router as metrics_router
 from coderouter.ingress.openai_routes import router as openai_router
 from coderouter.logging import configure_logging, get_logger
 from coderouter.metrics import install_collector
+from coderouter.plugins import discover_and_load
 from coderouter.routing import FallbackEngine
 from coderouter.routing.capability import check_claude_code_chain_suitability
 
@@ -38,7 +39,13 @@ def create_app(config_path: str | None = None) -> FastAPI:
     # so multiple create_app() calls (tests) don't stack handlers.
     install_collector()
     config = load_config(config_path)
-    engine = FallbackEngine(config)
+    # v2.3.0: discover plugins from importlib.metadata entry points and
+    # apply the user's explicit ``plugins.enabled`` allowlist. When the
+    # ``plugins`` block is absent or empty, the loader returns an empty
+    # registry and the engine's hook loops short-circuit — the request
+    # flow is bit-identical to v2.2.0 in that default case.
+    plugin_registry = discover_and_load(config)
+    engine = FallbackEngine(config, plugins=plugin_registry)
 
     @asynccontextmanager
     async def lifespan(app: FastAPI) -> AsyncIterator[None]:

coderouter_cli-2.3.0a3/coderouter/plugins/__init__.py

@@ -0,0 +1,59 @@
+"""Plugin SDK — extension points for in-process CodeRouter plugins (v2.3.0).
+
+CodeRouter Core stays at 5 deps. Optional functionality (memory, PII
+redaction, observability bridges, alternative ingresses, etc.) ships
+as separate ``coderouter-plugin-*`` packages on PyPI. Each plugin
+declares one or more *entry points* in its ``pyproject.toml``; this
+SDK discovers them at startup, applies the user's explicit ``enabled``
+allowlist (supply chain defense, see :func:`loader.discover_and_load`),
+and exposes a :class:`registry.PluginRegistry` to the engine.
+
+Six extension points are defined as :mod:`Protocols <typing>` in
+:mod:`coderouter.plugins.base`. v2.3.0 implements the engine-side hook
+integration for two of them (``input_filter`` and ``observer``); the
+remaining four (``frontend``, ``guard``, ``output_filter``,
+``adapter``) have a stable Protocol contract so plugins can target
+them now, but the engine doesn't yet wire them into the request flow.
+That's intentional — adding contracts is cheap, adding hot-path code
+isn't, so we wait for a real plugin to drive each integration.
+
+Public API:
+
+- :class:`InputFilter`, :class:`Observer` — implementable today.
+- :class:`Frontend`, :class:`Guard`, :class:`OutputFilter`,
+  :class:`Adapter` — Protocol-only, integration in v2.4+.
+- :func:`discover_and_load` — called once during config load.
+- :class:`PluginRegistry` — held by :class:`FallbackEngine`.
+"""
+from __future__ import annotations
+
+from coderouter.plugins.base import (
+    Adapter,
+    Frontend,
+    Guard,
+    InputFilter,
+    Observer,
+    OutputFilter,
+)
+from coderouter.plugins.loader import (
+    PLUGIN_GROUPS_FUTURE,
+    PLUGIN_GROUPS_V2_3,
+    discover_and_load,
+)
+from coderouter.plugins.registry import PluginRegistry
+
+__all__ = [
+    # Active hooks
+    "InputFilter",
+    "Observer",
+    # Future hooks (Protocol-only, no engine integration yet)
+    "Frontend",
+    "Guard",
+    "OutputFilter",
+    "Adapter",
+    # Discovery + container
+    "PluginRegistry",
+    "discover_and_load",
+    "PLUGIN_GROUPS_V2_3",
+    "PLUGIN_GROUPS_FUTURE",
+]

coderouter_cli-2.3.0a3/coderouter/plugins/base.py

@@ -0,0 +1,168 @@
+"""Plugin SDK Protocol contracts (v2.3.0).
+
+Six extension points are defined here. Two are wired into the engine
+in v2.3.0 (:class:`InputFilter`, :class:`Observer`); four are
+Protocol-only (:class:`Frontend`, :class:`Guard`, :class:`OutputFilter`,
+:class:`Adapter`) and will get engine integration when a real plugin
+drives the requirement — see ``docs/inside/plugin-architecture-draft.md``
+§3 for the full design rationale.
+
+Why declare contracts ahead of integration? It lets a plugin author
+build against the SDK *now* (and ship a working ``coderouter.frontend``
+plugin once integration lands) without us having to do a
+backward-incompatible Protocol revision later. ``runtime_checkable``
+is used so :func:`isinstance` checks work in the loader for clearer
+error messages.
+
+All hooks are async. Failures must NEVER block the engine response —
+the engine wraps every hook call in try/except and degrades gracefully
+(see ``coderouter/routing/fallback.py`` integration site).
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    # Avoid circular imports at runtime — Protocol typing only needs
+    # these for documentation and static analysis.
+    from coderouter.config.schemas import CodeRouterConfig
+    from coderouter.translation.anthropic import (
+        AnthropicRequest,
+        AnthropicResponse,
+    )
+
+
+# ====================================================================
+# Active hooks (engine integration in v2.3.0)
+# ====================================================================
+
+
+@runtime_checkable
+class InputFilter(Protocol):
+    """Mutates an inbound :class:`AnthropicRequest` before chain dispatch.
+
+    Plugins MUST treat the input as immutable: build the modified
+    request with ``request.model_copy(update={...})`` and return the
+    new instance. The engine assumes the returned value is a
+    *replacement*, not the same object.
+
+    Engine semantics:
+
+    - Filters run sequentially in the order they appear in
+      ``plugins.enabled``. The first filter sees the raw inbound
+      request; each subsequent filter sees the previous filter's
+      output.
+    - If :meth:`transform` raises, the engine logs ``input-filter-failed``
+      and continues with the *pre-mutation* request for that filter.
+      Other filters still run.
+    - The transform runs *after* the v1.9-E tool-loop guard but
+      *before* chain resolution and the v2.0-F context budget guard.
+      That order matters: filters can grow ``request.system`` (e.g.
+      memory injection) without bypassing the budget cap, because the
+      budget guard reruns over the post-filter payload.
+    """
+
+    name: str
+
+    async def transform(self, request: AnthropicRequest) -> AnthropicRequest: ...
+
+
+@runtime_checkable
+class Observer(Protocol):
+    """Passive event consumer. Cannot mutate anything.
+
+    The engine calls observers via :func:`asyncio.create_task` (fire
+    and forget). An observer that takes 30s won't slow a 200ms
+    response down — it just runs in the background. If it raises,
+    the engine logs ``observer-failed`` and discards the exception.
+
+    Event vocabulary (v2.3.0):
+
+    - ``request_completed`` — payload: ``{request, response,
+      latency_ms, provider}``. Fires after a successful Anthropic or
+      OpenAI-compat response. Streaming requests fire this event once,
+      after the SSE stream has terminated (not on each chunk).
+
+    Plugins MUST tolerate unknown event types — the vocabulary will
+    grow over time, and an old plugin should silently ignore events
+    it doesn't recognize rather than crash.
+    """
+
+    name: str
+
+    async def on_event(self, event_type: str, payload: dict[str, Any]) -> None: ...
+
+
+# ====================================================================
+# Future hooks (Protocol-only, engine integration in v2.4+)
+# ====================================================================
+
+
+@runtime_checkable
+class Frontend(Protocol):
+    """Alternative ingress (Discord, Telegram, MCP, Voice, ...).
+
+    Frontends *run* the engine rather than being called by it.
+    Integration plan: each frontend gets its own
+    :func:`asyncio.create_task` started by ``coderouter serve``;
+    SIGTERM cancels all of them and waits for cleanup.
+
+    Not yet integrated — Protocol contract only.
+    """
+
+    name: str
+
+    async def serve(
+        self, engine: Any, config: CodeRouterConfig
+    ) -> None: ...
+
+
+@runtime_checkable
+class Guard(Protocol):
+    """Reliability guard, parallel to the built-in tool-loop guard.
+
+    Runs synchronously on the hot path, so implementations must be
+    cheap. Heavy work (HTTP calls, model invocations, etc.) belongs
+    in an :class:`Observer`.
+
+    Not yet integrated — Protocol contract only.
+    """
+
+    name: str
+
+    async def check(
+        self, request: AnthropicRequest, config: CodeRouterConfig
+    ) -> None: ...
+
+
+@runtime_checkable
+class OutputFilter(Protocol):
+    """Mutates a response before it returns to the client.
+
+    For streaming, the engine plans to call :meth:`transform` once
+    per ``AnthropicStreamEvent``; for non-streaming, once per
+    response.
+
+    Not yet integrated — Protocol contract only.
+    """
+
+    name: str
+
+    async def transform(
+        self, response: AnthropicResponse
+    ) -> AnthropicResponse: ...
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """New ``kind`` value in providers.yaml (e.g. ``bedrock-native``).
+
+    Plugins implement the same async surface as
+    :class:`coderouter.adapters.base.BaseAdapter` so the engine can
+    treat them indistinguishably from built-in adapters once the
+    loader registers the new ``kind`` mapping.
+
+    Not yet integrated — Protocol contract only.
+    """
+
+    name: str

coderouter_cli-2.3.0a3/coderouter/plugins/loader.py

@@ -0,0 +1,176 @@
+"""Plugin discovery + instantiation (v2.3.0).
+
+Reads ``importlib.metadata`` entry points under the ``coderouter.*``
+groups, applies the user's explicit ``plugins.enabled`` allowlist,
+constructs each plugin with its config dict, and returns a
+:class:`PluginRegistry` ready for the engine to consume.
+
+Supply-chain defense
+====================
+
+Just having ``coderouter-plugin-X`` installed is **not enough** to
+activate a plugin — the user must list the entry-point name in
+``providers.yaml`` under ``plugins.enabled``. Without that explicit
+opt-in, an installed-but-unlisted plugin is silently skipped (logged
+as ``plugin-skipped``). This stops a compromised transitive
+dependency from injecting itself into the request flow.
+
+Failure mode: degraded continue
+===============================
+
+Plugin loading is best-effort. A failure to import a module, find a
+class, or call ``__init__`` is logged at error level and the engine
+keeps booting without that plugin. The rationale: a misconfigured
+optional plugin shouldn't take down the wire-level router that other
+plugins (and the core) depend on. Operators see the failure in logs
+and the ``/dashboard`` plugin panel.
+"""
+from __future__ import annotations
+
+import importlib.metadata as md
+from typing import TYPE_CHECKING
+
+from coderouter.logging import get_logger
+from coderouter.plugins.registry import PluginRegistry
+
+if TYPE_CHECKING:
+    from coderouter.config.schemas import CodeRouterConfig
+
+logger = get_logger(__name__)
+
+# Active hook groups in v2.3.0. The engine wires these into the
+# request flow; plugins targeting them will see their methods called
+# at runtime.
+PLUGIN_GROUPS_V2_3: tuple[str, ...] = ("input_filter", "observer")
+
+# Hook groups whose Protocol contracts are stable but whose engine
+# integration is deferred. Listing them here means a plugin author
+# can publish today and the loader will silently skip them with a
+# clear log line — no surprise crashes when integration lands.
+PLUGIN_GROUPS_FUTURE: tuple[str, ...] = (
+    "frontend",
+    "guard",
+    "output_filter",
+    "adapter",
+)
+
+
+def discover_and_load(config: CodeRouterConfig) -> PluginRegistry:
+    """Load plugins listed in ``config.plugins.enabled``.
+
+    Returns an empty registry when the ``plugins`` block is absent
+    from providers.yaml or its ``enabled`` list is empty. The empty
+    return is the same one ``PluginRegistry.empty()`` produces, so
+    the engine's hook loops short-circuit and incur zero cost in the
+    default (no-plugin) configuration.
+
+    Each enabled plugin is instantiated as
+    ``cls(**config.plugins.config.get(name, {}))``. The plugin's
+    ``__init__`` gets a fresh dict (validation happens inside the
+    plugin's own constructor — Core stays out of plugin-specific
+    schemas).
+
+    Logs emitted (one per outcome, all structured):
+
+    - ``plugin-loaded`` (info) — module + class loaded and constructed.
+    - ``plugin-skipped`` (info) — entry point exists but not enabled.
+    - ``plugin-load-failed`` (error) — import or ``__init__`` raised;
+      the engine continues without that plugin.
+    """
+    plugins_cfg = getattr(config, "plugins", None)
+    if plugins_cfg is None or not plugins_cfg.enabled:
+        return PluginRegistry.empty()
+
+    enabled = set(plugins_cfg.enabled)
+    registry = PluginRegistry()
+
+    # Track which enabled names actually matched an entry point so we
+    # can warn the operator about typos in ``plugins.enabled`` —
+    # otherwise a misspelled name silently does nothing and is hard
+    # to diagnose.
+    seen_names: set[str] = set()
+
+    for group in PLUGIN_GROUPS_V2_3 + PLUGIN_GROUPS_FUTURE:
+        ep_group = f"coderouter.{group}"
+        for ep in md.entry_points(group=ep_group):
+            if ep.name not in enabled:
+                # Installed but not enabled — silently skip.  Logged
+                # at info level so operators have a paper trail of
+                # plugins they could enable.
+                logger.info(
+                    "plugin-skipped",
+                    extra={
+                        "plugin": ep.name,
+                        "group": group,
+                        "reason": "not in plugins.enabled",
+                    },
+                )
+                continue
+
+            seen_names.add(ep.name)
+
+            # Future-only groups: plugin is installed *and* enabled,
+            # but the engine doesn't yet wire this group into the
+            # request flow. Load it anyway so the plugin can sanity-
+            # check its own construction; just log a clear warning.
+            if group in PLUGIN_GROUPS_FUTURE:
+                logger.warning(
+                    "plugin-group-not-yet-active",
+                    extra={
+                        "plugin": ep.name,
+                        "group": group,
+                        "note": (
+                            f"engine integration for '{group}' "
+                            "is deferred to v2.4+; the plugin will "
+                            "be loaded but its hook is never called"
+                        ),
+                    },
+                )
+
+            try:
+                cls = ep.load()
+                cfg = plugins_cfg.config.get(ep.name, {}) or {}
+                instance = cls(**cfg)
+                registry.add(group, instance)
+                logger.info(
+                    "plugin-loaded",
+                    extra={
+                        "plugin": ep.name,
+                        "group": group,
+                        "entry_point": ep.value,
+                    },
+                )
+            except Exception as exc:
+                # Don't propagate — engine boot must succeed even when
+                # an optional plugin is broken.
+                logger.error(
+                    "plugin-load-failed",
+                    extra={
+                        "plugin": ep.name,
+                        "group": group,
+                        "entry_point": ep.value,
+                        "error_type": type(exc).__name__,
+                        "error": str(exc),
+                    },
+                )
+
+    # Warn on enabled names that didn't match any installed entry
+    # point — most often this means the user typed a name in
+    # providers.yaml but forgot to ``pip install`` the corresponding
+    # plugin package.
+    missing = enabled - seen_names
+    if missing:
+        for name in sorted(missing):
+            logger.warning(
+                "plugin-not-found",
+                extra={
+                    "plugin": name,
+                    "hint": (
+                        "listed in plugins.enabled but no entry point "
+                        "with this name was discovered. Did you forget "
+                        "to install the plugin package?"
+                    ),
+                },
+            )
+
+    return registry