coderouter-cli 2.7.10__tar.gz → 2.8.0__tar.gz

{coderouter_cli-2.7.10 → coderouter_cli-2.8.0}/CHANGELOG.md

@@ -9,6 +9,53 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.8.0] — 2026-07-11 (Plugin SDK: Adapter hook wired — Phase 2a of the agent_cli extraction)
+
+Opens the Plugin SDK's Adapter surface: the previously dead-end `Adapter`
+Protocol (name-only) is now a real engine-integrated hook, so an external
+plugin package can provide new `kind` values for providers.yaml without
+touching Core. This is Phase 2a of the agent_cli plugin-extraction design
+(`docs/designs/agent-cli-plugin-extraction.md`): hook wiring only — the
+in-core `agent_cli` adapter is unchanged and keeps working exactly as in
+v2.7.10; the actual move into `coderouter-plugin-agents` is Phase 2b/2c.
+
+### Added
+
+- **`Adapter` plugin Protocol** (`coderouter/plugins/base.py`) — `kind: str`
+  plus synchronous `build(config: ProviderConfig) -> BaseAdapter`. A factory
+  shape (kind → adapter), unlike the per-request hooks: construction happens
+  once at startup and does no I/O. The `adapter` entry-point group
+  (`coderouter.adapter`, singular — matching the loader's group mechanics)
+  moved from the future list into the active groups; the existing two-stage
+  gate (installed + listed in `plugins.enabled`) applies as-is.
+- **`build_adapter` plugin resolution** (`coderouter/adapters/registry.py`)
+  — resolution order is in-core kinds first (`openai_compat` / `anthropic` /
+  `agent_cli`; a plugin can never shadow them), then plugin-provided kinds,
+  then a `ValueError` listing every known kind plus an install/enable hint.
+  Both engine call sites (startup adapter cache + runtime
+  `register_provider`) pass the plugin registry.
+- **Tests** (`tests/test_plugin_adapter.py`, new, 10) — plugin-kind
+  resolution, in-core shadowing prevention, unknown-kind error contents,
+  two-stage gate via the real entry-point loader path, runtime
+  `register_provider` with a plugin kind, and an E2E request through
+  `POST /v1/chat/completions` served by a plugin-provided adapter.
+
+### Changed
+
+- **`ProviderConfig.kind`: `Literal[...]` → `str`** (`config/schemas.py`) —
+  plugin kinds cannot be known at config-load time (plugins are discovered
+  after the config is parsed), so the closed Literal had to open. Fail-fast
+  for a typo'd kind moves one step later but stays at startup: the engine
+  builds adapters for **all** providers eagerly in its constructor, so an
+  unknown kind still aborts `serve` at load with a message that now lists
+  in-core and plugin kinds (strictly more helpful than the old pydantic
+  error). Recorded as a design deviation in
+  `agent-cli-plugin-extraction.md` §8.1, including the residual limitation
+  that `doctor` (HTTP-probe based) does not surface typo'd kinds.
+- Plugin-group bookkeeping: `adapter` no longer warns as
+  "plugin-group-not-yet-active"; `PluginRegistry` gained an `adapters`
+  view alongside `input_filters` / `observers`.
+
 ## [v2.7.10] — 2026-07-11 (agent_cli Phase 1c: antigravity — Phase 1 complete)
 
 Completes agent_cli Phase 1: `agent: antigravity` (the Google Antigravity

{coderouter_cli-2.7.10 → coderouter_cli-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.7.10
+Version: 2.8.0
 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.8.0/coderouter/adapters/registry.py

@@ -0,0 +1,60 @@
+"""Adapter factory — maps `kind` strings to adapter classes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from coderouter.adapters.anthropic_native import AnthropicAdapter
+from coderouter.adapters.base import BaseAdapter
+from coderouter.adapters.openai_compat import OpenAICompatAdapter
+from coderouter.config.schemas import ProviderConfig
+
+if TYPE_CHECKING:
+    from coderouter.plugins.registry import PluginRegistry
+
+# in-core kinds, in resolution order. Kept as a tuple (not derived from
+# the if-chain below) so the "Unknown adapter kind" error message and
+# the plugin-shadow guard have a single source of truth.
+_IN_CORE_KINDS: tuple[str, ...] = ("openai_compat", "anthropic", "agent_cli")
+
+
+def _plugin_kinds(plugin_registry: PluginRegistry | None) -> list[str]:
+    """``kind`` values served by enabled adapter plugins, for error text."""
+    if plugin_registry is None:
+        return []
+    return [factory.kind for factory in plugin_registry.adapters]
+
+
+def build_adapter(
+    provider: ProviderConfig,
+    plugin_registry: PluginRegistry | None = None,
+) -> BaseAdapter:
+    """Construct an adapter from a ProviderConfig.
+
+    Resolution order (docs/designs/agent-cli-plugin-extraction.md §3.2):
+    in-core kinds first, then plugin-provided kinds, then a fail-fast
+    error. In-core kinds are checked first so a plugin can never shadow
+    a kind Core itself guarantees (``openai_compat`` / ``anthropic`` /,
+    during the Phase 2b migration window, ``agent_cli``).
+    """
+    if provider.kind == "openai_compat":
+        return OpenAICompatAdapter(provider)
+    if provider.kind == "anthropic":
+        return AnthropicAdapter(provider)
+    if provider.kind == "agent_cli":
+        # Imported lazily so the external-agent adapter (and its subprocess /
+        # os plumbing) is only pulled in when a config actually uses it.
+        from coderouter.adapters.agent_cli import AgentCliAdapter
+
+        return AgentCliAdapter(provider)
+    if plugin_registry is not None:
+        for factory in plugin_registry.adapters:
+            if factory.kind == provider.kind:
+                return factory.build(provider)
+    raise ValueError(
+        f"Unknown adapter kind {provider.kind!r}. "
+        f"in-core kinds: {', '.join(_IN_CORE_KINDS)}; "
+        f"plugin-provided kinds: {_plugin_kinds(plugin_registry)}. "
+        f"If a plugin should provide {provider.kind!r}, ensure it is "
+        f"installed AND listed in plugins.enabled."
+    )

{coderouter_cli-2.7.10 → coderouter_cli-2.8.0}/coderouter/config/schemas.py

@@ -342,13 +342,23 @@ class ProviderConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     name: str = Field(..., description="Unique identifier used in profiles.yaml")
-    kind: Literal["openai_compat", "anthropic", "agent_cli"] = Field(
+    # v2.8.0: widened from Literal["openai_compat", "anthropic", "agent_cli"]
+    # to str so a provider can name a kind served by an adapter plugin
+    # (docs/designs/agent-cli-plugin-extraction.md §3). Config loading
+    # happens before plugin discovery (coderouter/ingress/app.py
+    # ``load_config`` then ``discover_and_load``), so pydantic can't know
+    # the full set of valid kinds at this point — an unknown kind still
+    # fails fast, just one step later, in ``build_adapter`` when the
+    # engine builds its adapter cache at startup.
+    kind: str = Field(
         default="openai_compat",
         description=(
             "Adapter type. 'openai_compat' covers llama.cpp / Ollama / "
             "OpenRouter / LM Studio / Together / Groq. 'anthropic' is the "
             "native Anthropic Messages API passthrough (v0.3.x). 'agent_cli' "
-            "invokes an external coding-agent CLI one-shot (see AgentCliConfig)."
+            "invokes an external coding-agent CLI one-shot (see AgentCliConfig). "
+            "Other values must be served by an adapter plugin listed in "
+            "plugins.enabled."
         ),
     )
     # base_url is required for HTTP-backed adapters (openai_compat / anthropic)

{coderouter_cli-2.7.10 → coderouter_cli-2.8.0}/coderouter/plugins/base.py

@@ -1,11 +1,13 @@
-"""Plugin SDK Protocol contracts (v2.3.0).
+"""Plugin SDK Protocol contracts (v2.3.0, Adapter wired in v2.8.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.
+Six extension points are defined here. Three are wired into the engine
+(:class:`InputFilter`, :class:`Observer` since v2.3.0; :class:`Adapter`
+since v2.8.0 — see ``docs/designs/agent-cli-plugin-extraction.md`` §2);
+three remain Protocol-only (:class:`Frontend`, :class:`Guard`,
+:class:`OutputFilter`) 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``
@@ -14,9 +16,11 @@ 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).
+InputFilter / Observer are async and run repeatedly on the hot path;
+failures must NEVER block the engine response, so the engine wraps
+every hook call in try/except and degrades gracefully (see
+``coderouter/routing/fallback.py`` integration site). Adapter is
+different in shape — see its docstring below.
 """
 from __future__ import annotations
 
@@ -25,7 +29,8 @@ 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.adapters.base import BaseAdapter
+    from coderouter.config.schemas import CodeRouterConfig, ProviderConfig
     from coderouter.translation.anthropic import (
         AnthropicRequest,
         AnthropicResponse,
@@ -93,6 +98,44 @@ class Observer(Protocol):
     async def on_event(self, event_type: str, payload: dict[str, Any]) -> None: ...
 
 
+# ====================================================================
+# Adapter hook (engine integration in v2.8.0)
+# ====================================================================
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """New ``kind`` value in providers.yaml, backed by a plugin.
+
+    The plugin declares the ``kind`` string it serves and a factory
+    that turns a matching :class:`~coderouter.config.schemas.ProviderConfig`
+    into a :class:`~coderouter.adapters.base.BaseAdapter` instance —
+    the same surface :func:`coderouter.adapters.registry.build_adapter`
+    uses for in-core kinds, so the engine treats plugin adapters
+    indistinguishably from built-ins once registered. See
+    ``docs/designs/agent-cli-plugin-extraction.md`` §2 for the design
+    rationale.
+
+    Shape-wise this hook differs from :class:`InputFilter` /
+    :class:`Observer`: those are instances the engine calls repeatedly
+    on the hot path, so they're async. An adapter provider is instead
+    a **factory** consulted once per provider at engine startup (and
+    again if the provider is re-registered at runtime) — construction
+    is I/O-free, so :meth:`build` is synchronous, matching
+    ``build_adapter``.
+    """
+
+    name: str
+    # The ``kind`` value this plugin serves in providers.yaml. Distinct
+    # from ``name`` (the plugin's own identifier, used in
+    # ``plugins.enabled`` / logs) — kept 1:1 for now; a future
+    # ``kinds: tuple[str, ...]`` can generalize this if a real plugin
+    # needs to serve more than one kind.
+    kind: str
+
+    def build(self, config: ProviderConfig) -> BaseAdapter: ...
+
+
 # ====================================================================
 # Future hooks (Protocol-only, engine integration in v2.4+)
 # ====================================================================
@@ -151,18 +194,3 @@ class OutputFilter(Protocol):
     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.7.10 → coderouter_cli-2.8.0}/coderouter/plugins/loader.py

@@ -38,10 +38,14 @@ if TYPE_CHECKING:
 
 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")
+# Active hook groups. The engine wires these into the request flow;
+# plugins targeting them will see their methods called at runtime.
+# ``input_filter`` / ``observer`` since v2.3.0; ``adapter`` joined in
+# v2.8.0 (docs/designs/agent-cli-plugin-extraction.md §2.4) — its
+# factories are consulted from ``build_adapter``, not iterated on the
+# hot path like the other two, but it goes through the same
+# discover-then-enable-gate machinery below.
+PLUGIN_GROUPS_V2_3: tuple[str, ...] = ("input_filter", "observer", "adapter")
 
 # Hook groups whose Protocol contracts are stable but whose engine
 # integration is deferred. Listing them here means a plugin author
@@ -51,7 +55,6 @@ PLUGIN_GROUPS_FUTURE: tuple[str, ...] = (
     "frontend",
     "guard",
     "output_filter",
-    "adapter",
 )
 
 

{coderouter_cli-2.7.10 → coderouter_cli-2.8.0}/coderouter/plugins/registry.py

@@ -20,8 +20,8 @@ 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.
+    Use the typed ``input_filters`` / ``observers`` / ``adapters``
+    properties; plugin code should not iterate ``_by_group`` directly.
     """
 
     def __init__(self) -> None:
@@ -65,6 +65,17 @@ class PluginRegistry:
         """Plugins registered as ``coderouter.observer``."""
         return list(self._by_group.get("observer", ()))
 
+    @property
+    def adapters(self) -> list[Any]:
+        """Plugins registered as ``coderouter.adapter`` (kind factories).
+
+        Unlike ``input_filters`` / ``observers``, these aren't called
+        repeatedly on the hot path — :func:`coderouter.adapters.registry.build_adapter`
+        consults this list once per provider to resolve a plugin-served
+        ``kind`` (v2.8.0, docs/designs/agent-cli-plugin-extraction.md §2.4).
+        """
+        return list(self._by_group.get("adapter", ()))
+
     def is_empty(self) -> bool:
         """True iff no plugin instance has been registered, in any group.
 

{coderouter_cli-2.7.10 → coderouter_cli-2.8.0}/coderouter/routing/fallback.py

@@ -1104,9 +1104,13 @@ class FallbackEngine:
         # 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
+        # Cache adapters so we don't re-instantiate per request. v2.8.0:
+        # pass the plugin registry through so a provider whose ``kind``
+        # is served by an enabled adapter plugin resolves via
+        # ``build_adapter``'s plugin lookup (agent-cli-plugin-extraction
+        # §3.5) instead of raising "Unknown adapter kind".
         self._adapters: dict[str, BaseAdapter] = {
-            p.name: build_adapter(p) for p in config.providers
+            p.name: build_adapter(p, self._plugin_registry) for p in config.providers
         }
         # v1.9-C: per-process adaptive routing adjuster (rolling-window
         # latency + error-rate observations, debounced rank changes).
@@ -1217,7 +1221,7 @@ class FallbackEngine:
                 break
         if not replaced:
             self.config.providers.append(provider)
-        self._adapters[provider.name] = build_adapter(provider)
+        self._adapters[provider.name] = build_adapter(provider, self._plugin_registry)
 
         try:
             chain = self.config.profile_by_name(profile_name)