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

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

@@ -6,6 +6,190 @@ versioning follows [SemVer](https://semver.org/).
 
 ---
 
+## [v2.3.0a4] — 2026-05-08 (Plugin SDK — ruff cleanup)
+
+Patch over `v2.3.0a3`. CI's `ruff check .` job surfaced six lint
+findings in the new Plugin SDK code. None affect runtime behavior.
+
+### Fixed
+
+- **RUF022**: `__all__` in `coderouter/plugins/__init__.py` is now
+  isort-sorted alphabetically.
+- **RUF006**: `_fanout_observers` was using `asyncio.create_task`
+  without holding a strong reference. Asyncio's task tracker only
+  keeps a weakref, so a fanout-in-flight task could be GC'd before
+  the observer ran. Fixed by storing tasks in a per-engine
+  ``_observer_tasks: set[asyncio.Task[None]]`` and removing each
+  via ``task.add_done_callback(set.discard)`` on completion. The
+  attribute is lazy-initialized in `_fanout_observers` itself so
+  engines built via ``__new__`` (which bypass ``__init__``) still
+  work.
+- **I001 + F841**: `tests/test_plugins_integration.py` had unused
+  imports (`AnthropicResponse`, `AnthropicUsage`) and an unused
+  local (`captured_chat`) left over from a build-engine helper
+  whose code path never ran. Removed the helper entirely; the
+  remaining tests exercise the engine's hook surface
+  (``_apply_input_filters`` / ``_fanout_observers`` /
+  ``_safe_observe``) directly, which is what they always actually
+  did.
+- **I001**: `tests/test_plugins_loader.py` import block reordered
+  alphabetically by module name.
+
+### Files touched
+
+```
+M  coderouter/plugins/__init__.py        — __all__ alphabetical
+M  coderouter/routing/fallback.py        — task strong-ref set
+M  tests/test_plugins_integration.py     — drop dead helper
+M  tests/test_plugins_loader.py          — import order
+M  tests/test_plugins_registry.py        — formatting nit (blank line)
+M  CHANGELOG.md, pyproject.toml          — 2.3.0a3 → 2.3.0a4
+```
+
+After this patch, ``ruff check .`` passes against every tracked
+Python file in the repo.
+
+---
+
+## [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.0a4}/PKG-INFO

@@ -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 → coderouter_cli-2.3.0a4}/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.0a4}/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.0a4/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_cli-2.3.0a4/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