coderouter-cli 2.2.0__py3-none-any.whl → 2.3.0a4__py3-none-any.whl

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/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/plugins/__init__.py

@@ -0,0 +1,56 @@
+"""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__ = [
+    "PLUGIN_GROUPS_FUTURE",
+    "PLUGIN_GROUPS_V2_3",
+    "Adapter",
+    "Frontend",
+    "Guard",
+    "InputFilter",
+    "Observer",
+    "OutputFilter",
+    "PluginRegistry",
+    "discover_and_load",
+]

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/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

coderouter/plugins/registry.py

@@ -0,0 +1,83 @@
+"""PluginRegistry — group-keyed container for loaded plugin instances.
+
+The registry is constructed once during config load (by
+:func:`coderouter.plugins.loader.discover_and_load`) and held by the
+:class:`coderouter.routing.fallback.FallbackEngine` for the process
+lifetime. Lookups are O(1) per group; insertion order is preserved so
+that ``plugins.enabled`` order in providers.yaml controls the order
+filters run.
+
+Group keys are lowercase, the same names used in pyproject.toml
+``[project.entry-points."coderouter.<group>"]`` sections (e.g.
+``input_filter``, ``observer``).
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+
+class PluginRegistry:
+    """In-memory registry of loaded plugin instances grouped by hook kind.
+
+    Use the typed ``input_filters`` / ``observers`` properties on the
+    hot path; plugin code should not iterate ``_by_group`` directly.
+    """
+
+    def __init__(self) -> None:
+        # ``defaultdict(list)`` keeps insertion order, which matters for
+        # InputFilter chaining (filters apply in registration order).
+        self._by_group: dict[str, list[Any]] = defaultdict(list)
+
+    @classmethod
+    def empty(cls) -> PluginRegistry:
+        """Convenience constructor for the no-plugin baseline.
+
+        ``FallbackEngine`` defaults to this when ``providers.yaml``
+        omits the ``plugins`` block, so all existing call sites
+        (``__init__``, tests that build engines via ``__new__``) keep
+        their zero-cost behavior.
+        """
+        return cls()
+
+    def add(self, group: str, instance: Any) -> None:
+        """Register an instance under a hook group.
+
+        The instance is appended to the group's list — duplicates are
+        not deduplicated here because the loader applies the
+        ``enabled`` allowlist upstream (no instance reaches this
+        method without an explicit enable).
+        """
+        self._by_group[group].append(instance)
+
+    @property
+    def input_filters(self) -> list[Any]:
+        """Plugins registered as ``coderouter.input_filter``.
+
+        Returns a copy so iteration during chain execution can't be
+        invalidated by a concurrent registration (registrations only
+        happen at startup, but defensive copying is cheap).
+        """
+        return list(self._by_group.get("input_filter", ()))
+
+    @property
+    def observers(self) -> list[Any]:
+        """Plugins registered as ``coderouter.observer``."""
+        return list(self._by_group.get("observer", ()))
+
+    def is_empty(self) -> bool:
+        """True iff no plugin instance has been registered, in any group.
+
+        ``FallbackEngine`` uses this to short-circuit the hook loops
+        entirely when no plugins are configured — keeping the no-
+        plugin code path bit-identical to v2.2.0 behavior.
+        """
+        return not any(self._by_group.values())
+
+    def count(self, group: str) -> int:
+        """Number of instances registered in ``group``. Used by tests + logs."""
+        return len(self._by_group.get(group, ()))
+
+    def groups(self) -> list[str]:
+        """All group names that have at least one registered instance."""
+        return [g for g, items in self._by_group.items() if items]

coderouter/routing/fallback.py

@@ -75,6 +75,7 @@ from coderouter.logging import (
     log_skip_memory_pressure,
     log_tool_loop_detected,
 )
+from coderouter.plugins.registry import PluginRegistry
 from coderouter.routing.adaptive import AdaptiveAdjuster
 from coderouter.routing.budget import BudgetTracker
 from coderouter.routing.capability import (
@@ -803,7 +804,11 @@ class FallbackEngine:
     translation behavior.
     """
 
-    def __init__(self, config: CodeRouterConfig) -> None:
+    def __init__(
+        self,
+        config: CodeRouterConfig,
+        plugins: PluginRegistry | None = None,
+    ) -> None:
         """Pre-build one adapter per configured provider.
 
         Adapters are stateless with respect to requests (all state is
@@ -816,8 +821,29 @@ class FallbackEngine:
         with ``adaptive: true`` actually fires. Adapter calls under
         non-adaptive profiles record nothing — zero observation
         overhead in the default configuration.
+
+        v2.3.0: an optional :class:`PluginRegistry` carries
+        InputFilter / Observer instances loaded by
+        :func:`coderouter.plugins.discover_and_load`. When omitted (or
+        empty), all hook loops in :meth:`generate_anthropic` /
+        :meth:`stream_anthropic` short-circuit and the request flow is
+        bit-identical to v2.2.0 — that's the zero-cost no-plugin path.
         """
         self.config = config
+        # v2.3.0: plugin registry.  Default empty so legacy callers
+        # (engine constructed without going through the loader) keep
+        # working unchanged.  Stored under ``_plugin_registry`` and
+        # surfaced via the ``plugins`` property — same lazy fallback
+        # pattern as ``_adaptive`` / ``_budget`` / ``_memory_pressure_guard``
+        # so tests that build the engine via ``FallbackEngine.__new__``
+        # see an empty registry instead of AttributeError.
+        self._plugin_registry: PluginRegistry = plugins or PluginRegistry.empty()
+        # v2.3.0: holds strong refs to in-flight Observer fanout tasks
+        # so the asyncio event loop's weak-ref bookkeeping doesn't GC
+        # them mid-flight (RUF006).  Tasks remove themselves on done
+        # via ``add_done_callback(_observer_tasks.discard)`` in
+        # :meth:`_fanout_observers`.
+        self._observer_tasks: set[asyncio.Task[None]] = set()
         # Cache adapters so we don't re-instantiate per request
         self._adapters: dict[str, BaseAdapter] = {
             p.name: build_adapter(p) for p in config.providers
@@ -875,6 +901,23 @@ class FallbackEngine:
         # v2.0-K: persistent state store (None = in-memory only).
         self._state_store: StateStore | None = None
 
+    @property
+    def plugins(self) -> PluginRegistry:
+        """Return the plugin registry, lazily building an empty one if absent.
+
+        Same legacy-test compatibility pattern as :py:attr:`_adaptive` /
+        :py:attr:`_budget`. Tests that construct the engine via
+        ``FallbackEngine.__new__`` (bypassing ``__init__``) see an
+        empty registry here instead of AttributeError, so the hook
+        helpers ``_apply_input_filters`` / ``_fanout_observers``
+        short-circuit cleanly without any plugin work happening.
+        """
+        existing = getattr(self, "_plugin_registry", None)
+        if existing is None:
+            self._plugin_registry = PluginRegistry.empty()
+            existing = self._plugin_registry
+        return existing
+
     @property
     def last_drift_severity(self) -> str | None:
         """Return the severity string of the most recent drift verdict, or None.
@@ -1785,6 +1828,106 @@ class FallbackEngine:
             request, config=self.config, first_provider_config=first_provider_config,
         )
 
+    # ====================================================================
+    # v2.3.0: Plugin SDK hook helpers
+    # ====================================================================
+
+    async def _apply_input_filters(
+        self, request: AnthropicRequest
+    ) -> AnthropicRequest:
+        """Run the InputFilter chain over ``request``.
+
+        Filters apply in registration order (= the order the user
+        listed them in ``plugins.enabled``). A filter that raises is
+        logged at warn level and skipped — its predecessor's output
+        flows through unchanged. The chain is short-circuited
+        entirely when no plugin is registered (zero overhead).
+
+        Plugin contract: filters MUST return a new
+        :class:`AnthropicRequest` (typically via ``model_copy``) and
+        not mutate the input in place. The engine treats the return
+        value as the new authoritative request and discards the
+        previous one.
+        """
+        if self.plugins.is_empty():
+            return request
+        filters = self.plugins.input_filters
+        if not filters:
+            return request
+        for filt in filters:
+            try:
+                request = await filt.transform(request)
+            except Exception as exc:  # pragma: no cover - defensive
+                logger.warning(
+                    "input-filter-failed",
+                    extra={
+                        "plugin": getattr(filt, "name", filt.__class__.__name__),
+                        "error_type": type(exc).__name__,
+                        "error": str(exc)[:500],
+                    },
+                )
+        return request
+
+    def _fanout_observers(
+        self,
+        event_type: str,
+        **payload: Any,
+    ) -> None:
+        """Fan out an Observer event as a fire-and-forget asyncio task.
+
+        The engine never awaits these tasks: a slow observer (e.g. a
+        Langfuse uploader) cannot stretch the wire-level latency the
+        client measures. Errors are caught inside
+        :meth:`_safe_observe` and logged, never propagated.
+
+        ``payload`` is whatever the call site supplied; the receiving
+        plugin's :meth:`Observer.on_event` is expected to tolerate
+        unknown keys (forward-compat).
+        """
+        observers = self.plugins.observers
+        if not observers:
+            return
+        # Lazy-init the task set for engines built via ``__new__`` —
+        # mirrors the lazy ``plugins`` property pattern so legacy
+        # tests that bypass __init__ don't crash here.
+        if not hasattr(self, "_observer_tasks"):
+            self._observer_tasks = set()
+        for obs in observers:
+            task = asyncio.create_task(
+                self._safe_observe(obs, event_type, payload)
+            )
+            # Strong-ref keeps the task alive past the loop iteration;
+            # ``discard`` cleans up after the task completes (success
+            # or exception). Avoids the RUF006 footgun where
+            # asyncio.create_task's weakref-only bookkeeping can let
+            # the loop GC a fanout-in-progress task.
+            self._observer_tasks.add(task)
+            task.add_done_callback(self._observer_tasks.discard)
+
+    async def _safe_observe(
+        self,
+        obs: Any,
+        event_type: str,
+        payload: dict[str, Any],
+    ) -> None:
+        """Wrap a single Observer.on_event call in try/except.
+
+        Separated from the fanout loop so the test suite can call it
+        directly with a synthetic observer + payload.
+        """
+        try:
+            await obs.on_event(event_type, payload)
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.warning(
+                "observer-failed",
+                extra={
+                    "plugin": getattr(obs, "name", obs.__class__.__name__),
+                    "event": event_type,
+                    "error_type": type(exc).__name__,
+                    "error": str(exc)[:500],
+                },
+            )
+
     async def generate_anthropic(self, request: AnthropicRequest) -> AnthropicResponse:
         """Non-streaming Anthropic request, per-provider dispatch."""
         # v1.9-E (L3): tool-loop guard runs before chain dispatch so the
@@ -1792,6 +1935,12 @@ class FallbackEngine:
         # naturally. `break` raises ToolLoopBreakError, which the
         # ingress converts to a 400 response.
         request = _apply_tool_loop_guard(request, config=self.config)
+        # v2.3.0: input_filter plugin chain runs *after* the built-in
+        # tool-loop guard but *before* chain resolution + context
+        # budget guard. That order lets a filter (e.g. memory inject)
+        # grow ``request.system`` without bypassing the budget cap —
+        # the budget guard sees the post-filter payload.
+        request = await self._apply_input_filters(request)
         chain = self._resolve_anthropic_chain(request)
 
         # v2.0-F (L1): context budget guard runs after chain resolution
@@ -1961,6 +2110,19 @@ class FallbackEngine:
                 provider_config=adapter.config,
                 budget=self._budget,
             )
+            # v2.3.0: observer plugin fanout — fire-and-forget, never
+            # blocks the engine response. Latency in ms uses the same
+            # per-attempt clock the adaptive recorder used above so a
+            # plugin's view of "this request took N ms" matches the
+            # /metrics view.
+            self._fanout_observers(
+                "request_completed",
+                request=request,
+                response=resp,
+                provider=adapter.name,
+                latency_ms=(time.monotonic() - attempt_started) * 1000.0,
+                stream=False,
+            )
             return resp
 
         profile = request.profile or self.config.default_profile
@@ -1982,6 +2144,11 @@ class FallbackEngine:
         """
         # v1.9-E (L3): tool-loop guard mirrors the non-streaming path.
         request = _apply_tool_loop_guard(request, config=self.config)
+        # v2.3.0: input_filter chain — same ordering rules as the
+        # non-streaming path. Filters can grow ``request.system``
+        # before chain resolution, and the budget guard below sees
+        # the post-filter payload.
+        request = await self._apply_input_filters(request)
         chain = self._resolve_anthropic_chain(request)
 
         # v2.0-F (L1): context budget guard mirrors the non-streaming path.
@@ -2169,6 +2336,19 @@ class FallbackEngine:
                 provider_config=adapter.config,
                 budget=self._budget,
             )
+            # v2.3.0: streaming observer fanout fires once, after the
+            # SSE terminates successfully. We hand the accumulator's
+            # final view (text + usage + tool-use flag) so plugins can
+            # treat it like the non-streaming response — they don't
+            # need to re-aggregate SSE chunks themselves.
+            self._fanout_observers(
+                "request_completed",
+                request=request,
+                response=acc,
+                provider=adapter.name,
+                latency_ms=None,  # streaming latency is end-of-stream-relative; left to plugin
+                stream=True,
+            )
             return
 
         profile = request.profile or self.config.default_profile

{coderouter_cli-2.2.0.dist-info → coderouter_cli-2.3.0a4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.2.0
+Version: 2.3.0a4
 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.dist-info → coderouter_cli-2.3.0a4.dist-info}/RECORD

@@ -19,7 +19,7 @@ coderouter/config/__init__.py,sha256=FODEn74fN-qZnt4INPSHswqhOlEgpL6-_onxsitSx8g
 coderouter/config/capability_registry.py,sha256=F6DetVL5oM03R4QeK1g6h_Q_zrXH0opnYDp3duZmkN4,15808
 coderouter/config/env_file.py,sha256=CoMK27fuAXm-NtoLzXb8yN2E-wDFjHQuFwiIlmgTBQw,10356
 coderouter/config/loader.py,sha256=FUEe8m4Tnmj_aul0vSctD8vKvNW-oLRoMRbTpSKqSmc,4077
-coderouter/config/schemas.py,sha256=lwTHUnaL4eqTIk1n22RBBhisVPoUVQxiPzEenEXQNFk,52143
+coderouter/config/schemas.py,sha256=NuD107zOGiQTIg_8Ngu8i3Rcc5mIRv9QhvrlCEJ4rfU,54756
 coderouter/data/__init__.py,sha256=uNyfD9jaCvTWsBAWtaw1Fr25OSxzv3psGMfBjT1z0Cc,328
 coderouter/data/model-capabilities.yaml,sha256=2ztY4PUbGN_cWG-UUB-iPy-baeVFnGV8OcZHJUfZE7c,19290
 coderouter/guards/__init__.py,sha256=D_4bEHvLIp4deEKX9odTIoeUCdEcpWBAaO6noLTUTRk,1011
@@ -33,19 +33,23 @@ coderouter/guards/self_healing.py,sha256=_fT_EJvTTp5VSi-qAP93J_1LkgPK5jkzsyrUHdK
 coderouter/guards/tool_loop.py,sha256=EzeMcmU7BLeTW2jsRVevU81l5rhWcn1oUr7EpzgXjVM,15209
 coderouter/ingress/__init__.py,sha256=WQsCH2CGJCAhy0mS6GSEdeYZRkkQu2OHDsP4CJWTLug,155
 coderouter/ingress/anthropic_routes.py,sha256=It2f7XGe3fgKQX01J2F5JOCoZr96t_Tx_kY2om99MVo,16894
-coderouter/ingress/app.py,sha256=qX4koRVXXyy1aOdIY-fsR4nJNLTNwCnhG2ZnBICcW0A,11639
+coderouter/ingress/app.py,sha256=FBgn9Vujn-xesmeUzQcaPhtdvAYfs9cIQSMBgs0V_XI,12110
 coderouter/ingress/dashboard_routes.py,sha256=jVFc_4Q67YrP0VIppuQfBLnLvnvaCWJJ4z7aZsHmu1s,21822
 coderouter/ingress/metrics_routes.py,sha256=M22dwOGn24P05Ge4W3c7d7mYytSGWjIR-pPSPOAiHJY,3965
 coderouter/ingress/openai_routes.py,sha256=Zw1efPw9DI6GgV8ZcLrzS6Cda0KLrFkKn2GBZWSe6Vo,6322
 coderouter/metrics/__init__.py,sha256=7Es351DPS7yLM0yVF_F0eesmiD83n7Zzhie44chht38,1465
 coderouter/metrics/collector.py,sha256=Q0_CY0orX8_i0EICBME5sYW2RqL2VD4SpNs8qfCnBM0,47432
 coderouter/metrics/prometheus.py,sha256=YRqyT931s40zVkIj07D-M2UNfDhIEElVFRz3izdJcnQ,24419
+coderouter/plugins/__init__.py,sha256=76hMLe5dV_ilripHXzWn3HSYoIALjzlw4EJVyI-GyIM,1974
+coderouter/plugins/base.py,sha256=n9hsck2NCSqi6oeHIumKC5zhQ8JGwCXUz7J5AZQCQss,5772
+coderouter/plugins/loader.py,sha256=xAIf6bIuth0QXCzwxO_ja6aSUlLzIqZNbrbQNJDgSE8,6841
+coderouter/plugins/registry.py,sha256=Tx0QHJHozZ5LTUliGylBdNVcdzHTBV0nedCUwGlbLMM,3236
 coderouter/routing/__init__.py,sha256=g2vhutbozRx5QBThReqwPN3imk5qXdpDiaogILd3IRc,257
 coderouter/routing/adaptive.py,sha256=G2o377twGSjbUh65wiIFx6klnpFGjsD_nI3oDvcBwhY,21257
 coderouter/routing/auto_router.py,sha256=4_sQR0ztSED9FgQSvQqgqSiydyQVY_qOSRvwyZ5BfRc,12909
 coderouter/routing/budget.py,sha256=A3_i44tmS3SrqVNnoGkLKMsiYwI_Ug6m5-3gitVoQSM,8452
 coderouter/routing/capability.py,sha256=ziIDuE5keH_jxYDlXSKufRVxxSYOAvUxJ6Rw5QkYDDU,18436
-coderouter/routing/fallback.py,sha256=MXyht62vew33JW603ia-XqPtDuSgSzYanaSkv0LqTDM,94752
+coderouter/routing/fallback.py,sha256=j2clcgcr9Y5wQqJDwy8UhEMWRYJr1ZDV0bEvo_tgOfA,102930
 coderouter/state/__init__.py,sha256=mmINqwIyIu6-zt-Qo-7Ddxdxz_-5vzuPjLvjYW5T_bk,782
 coderouter/state/audit_log.py,sha256=JwGd0OkkDlkh0Fdc6SmnuyViwKzEaFA7Ux_VqHzakWE,8358
 coderouter/state/replay.py,sha256=Z_YHKroTKZdrL8qObFxcoLOAQWWXZvXFdLfxzvBhEJg,11230
@@ -55,8 +59,8 @@ coderouter/translation/__init__.py,sha256=PYXN7XVEwpG1uC8RLy6fvnGbzEZhhrEuUapH8I
 coderouter/translation/anthropic.py,sha256=JpvIWNXHUPVqOGvps7o_6ZADhXuJuvpU7RdMqQFtwwM,6421
 coderouter/translation/convert.py,sha256=-qyzFzmmr9hhQV6_Sg75kJnvCZvHe3n7vRdaZtk_JqQ,47269
 coderouter/translation/tool_repair.py,sha256=Ok2PF947Liegc5oaytfptv5MWMkpfJYQie-zdP1y3cY,9946
-coderouter_cli-2.2.0.dist-info/METADATA,sha256=VYLzUypwOhGmB0iZhFueTv_WobHZKCXBoWdSdLS8WVc,9991
-coderouter_cli-2.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-coderouter_cli-2.2.0.dist-info/entry_points.txt,sha256=-dnLfD1YZ2WjH2zSdNCvlO65wYltM9bsHt9Fhg3yGss,51
-coderouter_cli-2.2.0.dist-info/licenses/LICENSE,sha256=wkEzoR86jFw33jvfOHjULqmkGEfxTFMgMaJnpR8mPRw,1065
-coderouter_cli-2.2.0.dist-info/RECORD,,
+coderouter_cli-2.3.0a4.dist-info/METADATA,sha256=6U8KQgMiL-g1TbAyu4SPEINFKroIPicJKsLTnm6fE4U,9993
+coderouter_cli-2.3.0a4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+coderouter_cli-2.3.0a4.dist-info/entry_points.txt,sha256=-dnLfD1YZ2WjH2zSdNCvlO65wYltM9bsHt9Fhg3yGss,51
+coderouter_cli-2.3.0a4.dist-info/licenses/LICENSE,sha256=wkEzoR86jFw33jvfOHjULqmkGEfxTFMgMaJnpR8mPRw,1065
+coderouter_cli-2.3.0a4.dist-info/RECORD,,