opencode-agent-sdk 0.2.0__tar.gz → 0.4.6__tar.gz

{opencode_agent_sdk-0.2.0 → opencode_agent_sdk-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-agent-sdk
-Version: 0.2.0
+Version: 0.4.6
 Summary: Open-source Agent SDK backed by OpenCode ACP (drop-in replacement for claude_agent_sdk)
 Author: OpenCode
 License: MIT
@@ -16,6 +16,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: anyio
 Requires-Dist: httpx
+Requires-Dist: fastmcp>=2.0.0
 Provides-Extra: opencode-ai
 Requires-Dist: opencode-ai>=0.1.0a36; extra == "opencode-ai"
 Provides-Extra: dev

{opencode_agent_sdk-0.2.0 → opencode_agent_sdk-0.4.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opencode-agent-sdk"
-version = "0.2.0"
+version = "0.4.6"
 description = "Open-source Agent SDK backed by OpenCode ACP (drop-in replacement for claude_agent_sdk)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,6 +25,7 @@ classifiers = [
 dependencies = [
     "anyio",
     "httpx",
+    "fastmcp>=2.0.0",
 ]
 
 [project.optional-dependencies]
@@ -45,4 +46,5 @@ addopts = "-q"
 [dependency-groups]
 dev = [
     "build>=1.4.0",
+    "twine>=6.2.0",
 ]

{opencode_agent_sdk-0.2.0 → opencode_agent_sdk-0.4.6}/src/opencode_agent_sdk/__init__.py

@@ -11,6 +11,7 @@ from .types import (
 )
 from .client import AgentOptions, SDKClient
 from .tools import create_sdk_mcp_server, tool
+from .model_registry import ModelConfig, ModelRegistry
 
 __all__ = [
     "AgentOptions",
@@ -19,6 +20,8 @@ __all__ = [
     "HookInput",
     "HookJSONOutput",
     "HookMatcher",
+    "ModelConfig",
+    "ModelRegistry",
     "ResultMessage",
     "SDKClient",
     "SystemMessage",

{opencode_agent_sdk-0.2.0 → opencode_agent_sdk-0.4.6}/src/opencode_agent_sdk/_internal/acp.py

@@ -23,7 +23,7 @@ from .transport import SubprocessTransport
 
 logger = logging.getLogger(__name__)
 
-_PROTOCOL_VERSION = "2025-01-01"
+_PROTOCOL_VERSION = 1
 
 
 class ACPSession:
@@ -128,8 +128,9 @@ class ACPSession:
             await self._handle_permission_request(msg)
             return
 
-        # Notification: sessionUpdate
-        if method == "sessionUpdate":
+        # Notification: session/update (opencode ACP v1.2.15+)
+        # Also accept legacy "sessionUpdate" for backwards compatibility
+        if method in ("session/update", "sessionUpdate"):
             params = msg.get("params", {})
             await self._update_queue.put(params)
             return
@@ -213,25 +214,62 @@ class ACPSession:
         cwd: str,
         mcp_servers: list[dict[str, Any]] | None = None,
         model: str | None = None,
+        provider_id: str | None = None,
+        permission_mode: str = "",
+        system_prompt: str = "",
     ) -> str:
-        """Create a new ACP session. Returns the session ID."""
+        """Create a new ACP session and optionally set the model.
+
+        OpenCode's ``session/new`` does not accept model/provider params.
+        The model must be set separately via ``session/set_model`` after
+        the session is created.  The ``modelId`` format is
+        ``"{providerID}/{modelID}"``.
+        """
         params: dict[str, Any] = {
             "cwd": cwd,
             "mcpServers": mcp_servers or [],
         }
-        result = await self._send_request("newSession", params)
+        if permission_mode:
+            params["permissionMode"] = permission_mode
+        if system_prompt:
+            params["systemPrompt"] = system_prompt
+        result = await self._send_request("session/new", params)
         self._session_id = result.get("sessionId", "")
         logger.debug("New session: %s", self._session_id)
+
+        # Set the model via session/set_model (session/new ignores model params)
+        if model and provider_id:
+            model_id = f"{provider_id}/{model}"
+        elif model:
+            model_id = model
+        else:
+            model_id = None
+
+        if model_id:
+            try:
+                await self._send_request("session/set_model", {
+                    "sessionId": self._session_id,
+                    "modelId": model_id,
+                })
+                logger.debug("Set model to %s", model_id)
+            except Exception as exc:
+                logger.warning("Failed to set model %s: %s", model_id, exc)
+
         return self._session_id
 
-    async def load_session(self, session_id: str, cwd: str) -> str:
+    async def load_session(
+        self,
+        session_id: str,
+        cwd: str,
+        mcp_servers: list[dict[str, Any]] | None = None,
+    ) -> str:
         """Resume an existing ACP session."""
         params: dict[str, Any] = {
             "sessionId": session_id,
             "cwd": cwd,
-            "mcpServers": [],
+            "mcpServers": mcp_servers or [],
         }
-        result = await self._send_request("loadSession", params)
+        result = await self._send_request("session/load", params)
         self._session_id = result.get("sessionId", session_id)
         return self._session_id
 
@@ -243,7 +281,7 @@ class ACPSession:
         self._usage = {}
         self._cost = {}
 
-        result = await self._send_request("prompt", {
+        result = await self._send_request("session/prompt", {
             "sessionId": self._session_id,
             "prompt": parts,
         })
@@ -260,7 +298,7 @@ class ACPSession:
 
     async def cancel(self) -> None:
         """Cancel the current operation."""
-        await self._send_notification("cancel", {
+        await self._send_notification("session/cancel", {
             "sessionId": self._session_id,
         })
 

{opencode_agent_sdk-0.2.0 → opencode_agent_sdk-0.4.6}/src/opencode_agent_sdk/_internal/transport.py

@@ -46,6 +46,7 @@ class SubprocessTransport:
         self._cwd = os.path.abspath(cwd)
         self._process: anyio.abc.Process | None = None
         self._read_lock = anyio.Lock()
+        self._stderr_task: anyio.abc.TaskGroup | None = None
 
     async def connect(self) -> None:
         """Spawn the opencode acp subprocess."""
@@ -53,12 +54,47 @@ class SubprocessTransport:
         logger.debug("Spawning: %s acp --cwd %s", binary, self._cwd)
 
         self._process = await anyio.open_process(
-            [binary, "acp", "--cwd", self._cwd],
+            [binary, "acp", "--print-logs", "--log-level", "INFO", "--cwd", self._cwd],
             stdin=subprocess.PIPE,
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
         )
 
+        # Drain stderr in background to prevent pipe buffer deadlock and
+        # surface opencode's internal logs (model routing, provider init, etc.)
+        self._stderr_scope = await anyio.create_task_group().__aenter__()
+        self._stderr_scope.start_soon(self._drain_stderr)
+
+    async def _drain_stderr(self) -> None:
+        """Read stderr lines and log them.
+
+        Surfaces opencode's internal logs — especially ``service=llm``
+        lines that show which provider/model is actually used.
+        """
+        if self._process is None or self._process.stderr is None:
+            return
+        buffer = b""
+        try:
+            async for chunk in self._process.stderr:
+                buffer += chunk
+                while b"\n" in buffer:
+                    line_bytes, buffer = buffer.split(b"\n", 1)
+                    line = line_bytes.decode("utf-8", errors="replace").strip()
+                    if not line:
+                        continue
+                    if "service=llm" in line:
+                        logger.info("opencode LLM: %s", line)
+                    elif "service=provider" in line and "found" in line:
+                        logger.debug("opencode provider: %s", line)
+                    elif "ERR" in line or "error" in line.lower():
+                        logger.warning("opencode stderr: %s", line)
+                    else:
+                        logger.debug("opencode: %s", line)
+        except anyio.ClosedResourceError:
+            pass
+        except Exception as exc:
+            logger.debug("stderr drain ended: %s", exc)
+
     async def write(self, data: dict[str, Any]) -> None:
         """Write a JSON-RPC message (NDJSON line) to the subprocess stdin."""
         if self._process is None or self._process.stdin is None:
@@ -109,4 +145,13 @@ class SubprocessTransport:
         except Exception:
             pass
 
+        # Clean up the stderr drain task group
+        if self._stderr_scope is not None:
+            try:
+                self._stderr_scope.cancel_scope.cancel()
+                await self._stderr_scope.__aexit__(None, None, None)
+            except Exception:
+                pass
+            self._stderr_scope = None
+
         self._process = None

opencode_agent_sdk-0.4.6/src/opencode_agent_sdk/_mcp_bridge.py

@@ -0,0 +1,250 @@
+"""Bridge for running SDK MCP tools as HTTP servers.
+
+Opencode expects MCP servers to be either subprocesses (stdio) or remote
+HTTP/SSE servers.  SDK-defined tools (created via create_sdk_mcp_server)
+have Python function handlers that must run in the same process.
+
+This module bridges the gap by starting FastMCP HTTP servers in the SDK
+process and returning remote URLs for opencode to connect to.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import socket
+from contextlib import asynccontextmanager
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _find_free_port() -> int:
+    """Find an available TCP port on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class McpHttpBridge:
+    """Hosts SDK MCP tools as HTTP servers for opencode consumption.
+
+    For each SDK-defined MCP server (those with ``_tools`` in their config),
+    starts a FastMCP HTTP server on a random port.  The config is then
+    converted to a remote server pointing to ``http://127.0.0.1:<port>/mcp``
+    so opencode can connect to it.
+    """
+
+    def __init__(self) -> None:
+        self._servers: list[Any] = []  # uvicorn.Server instances
+        self._tasks: list[asyncio.Task[None]] = []
+
+    async def start_server(self, name: str) -> int:
+        """Start an HTTP MCP server for the given tools.
+
+        Args:
+            name: MCP server name (must match a name registered via
+                  create_sdk_mcp_server).
+
+        Returns:
+            The port the server is listening on.
+        """
+        from .tools import _TOOL_REGISTRY
+
+        tool_handlers = _TOOL_REGISTRY.get(name, [])
+        if not tool_handlers:
+            raise ValueError(f"No tool handlers registered for MCP server '{name}'")
+
+        from fastmcp import FastMCP
+        from fastmcp.tools import Tool as FastMCPTool
+
+        mcp_server = FastMCP(name)
+
+        for sdk_tool in tool_handlers:
+            wrapper = _make_wrapper(sdk_tool)
+            mcp_server.add_tool(
+                FastMCPTool.from_function(
+                    wrapper,
+                    name=sdk_tool.name,
+                    description=sdk_tool.description,
+                )
+            )
+
+        app = mcp_server.http_app(transport="streamable-http")
+        port = _find_free_port()
+
+        import uvicorn
+
+        config = uvicorn.Config(
+            app,
+            host="127.0.0.1",
+            port=port,
+            log_level="warning",
+        )
+        uv_server = uvicorn.Server(config)
+        self._servers.append(uv_server)
+
+        task = asyncio.create_task(uv_server.serve())
+        self._tasks.append(task)
+
+        # Wait briefly for the server to start accepting connections
+        await asyncio.sleep(0.3)
+
+        logger.info(
+            "MCP HTTP bridge started: %s on port %d (%d tools)",
+            name, port, len(tool_handlers),
+        )
+        return port
+
+    async def start_server_from_instance(self, name: str, server_instance: Any) -> int:
+        """Host an existing mcp.server.Server instance as an HTTP MCP server.
+
+        This enables cross-SDK compatibility: MCP servers created by the
+        claude-agent-sdk (``McpSdkServerConfig`` with ``type="sdk"`` and an
+        ``instance`` field) can be served over HTTP so the opencode ACP layer
+        can consume them.
+
+        Args:
+            name: MCP server name (for logging).
+            server_instance: An ``mcp.server.Server`` (low-level) with tool
+                handlers already registered.
+
+        Returns:
+            The port the server is listening on.
+        """
+        from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+        from fastmcp.server.http import StreamableHTTPASGIApp
+        from starlette.applications import Starlette
+        from starlette.routing import Route
+
+        session_manager = StreamableHTTPSessionManager(
+            app=server_instance,
+            stateless=True,
+        )
+        asgi_handler = StreamableHTTPASGIApp(session_manager)
+
+        @asynccontextmanager
+        async def lifespan(app: Any) -> Any:
+            async with session_manager.run():
+                yield
+
+        starlette_app = Starlette(
+            routes=[Route("/mcp", endpoint=asgi_handler, methods=["GET", "POST", "DELETE"])],
+            lifespan=lifespan,
+        )
+
+        port = _find_free_port()
+
+        import uvicorn
+
+        config = uvicorn.Config(
+            starlette_app,
+            host="127.0.0.1",
+            port=port,
+            log_level="warning",
+        )
+        uv_server = uvicorn.Server(config)
+        self._servers.append(uv_server)
+
+        task = asyncio.create_task(uv_server.serve())
+        self._tasks.append(task)
+
+        await asyncio.sleep(0.3)
+
+        logger.info(
+            "MCP HTTP bridge started (from instance): %s on port %d",
+            name, port,
+        )
+        return port
+
+    async def stop_all(self) -> None:
+        """Stop all running HTTP MCP servers."""
+        for server in self._servers:
+            server.should_exit = True
+        for task in self._tasks:
+            task.cancel()
+            try:
+                await task
+            except (asyncio.CancelledError, Exception):
+                pass
+        self._servers.clear()
+        self._tasks.clear()
+        logger.debug("All MCP HTTP bridges stopped")
+
+
+def _make_wrapper(sdk_tool: Any) -> Any:
+    """Create an async wrapper function that bridges SDK tool handler format.
+
+    SDK tools accept ``args: dict[str, Any]`` and return
+    ``{"content": [{"type": "text", "text": "..."}]}``.
+
+    FastMCP expects typed keyword arguments and a return value that it
+    serializes.  This function dynamically creates a wrapper with the
+    correct signature derived from ``input_schema``.
+    """
+    schema = sdk_tool.input_schema or {}
+    properties = schema.get("properties", {})
+    handler = sdk_tool.handler
+
+    # Build parameter list from input_schema properties
+    params = []
+    for prop_name, prop_def in properties.items():
+        json_type = prop_def.get("type", "string")
+        annotation = _json_type_to_python(json_type, prop_def)
+
+        required = prop_name in schema.get("required", [])
+        if required:
+            params.append(
+                inspect.Parameter(
+                    prop_name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=annotation,
+                )
+            )
+        else:
+            default = prop_def.get("default", None)
+            params.append(
+                inspect.Parameter(
+                    prop_name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    default=default,
+                    annotation=annotation,
+                )
+            )
+
+    async def wrapper(**kwargs: Any) -> str:
+        result = await handler(kwargs)
+        # Extract text from MCP content format
+        if isinstance(result, dict) and "content" in result:
+            texts = [
+                c["text"]
+                for c in result["content"]
+                if isinstance(c, dict) and c.get("type") == "text"
+            ]
+            return "\n".join(texts) if texts else str(result)
+        return str(result)
+
+    # Set signature AND annotations so FastMCP/Pydantic can introspect
+    wrapper.__signature__ = inspect.Signature(params, return_annotation=str)
+    wrapper.__name__ = sdk_tool.name
+    wrapper.__doc__ = sdk_tool.description
+    wrapper.__annotations__ = {p.name: p.annotation for p in params}
+    wrapper.__annotations__["return"] = str
+
+    return wrapper
+
+
+def _json_type_to_python(json_type: str, prop_def: dict[str, Any]) -> type:
+    """Map JSON Schema type to Python type annotation."""
+    type_map: dict[str, type] = {
+        "string": str,
+        "integer": int,
+        "number": float,
+        "boolean": bool,
+    }
+    if json_type == "array":
+        return list
+    if json_type == "object":
+        return dict
+    return type_map.get(json_type, str)

{opencode_agent_sdk-0.2.0 → opencode_agent_sdk-0.4.6}/src/opencode_agent_sdk/client.py

@@ -65,6 +65,7 @@ class SDKClient:
         self._session: Any = None  # ACPSession (subprocess mode only)
         self._http_mode = bool(options.server_url)
         self._pending_parts: dict[str, Any] | None = None
+        self._mcp_bridge: Any = None  # McpHttpBridge for SDK MCP servers
 
     async def connect(self) -> None:
         """Connect to opencode — either via HTTP or subprocess ACP."""
@@ -99,23 +100,75 @@ class SDKClient:
         # Protocol handshake
         await self._session.initialize()
 
-        # Create or resume session
-        mcp_servers = _build_mcp_servers(self._options.mcp_servers)
+        # Start HTTP bridges for SDK-defined MCP servers.
+        # SDK tools have Python function handlers that must run in-process.
+        # We host them as HTTP MCP servers and tell opencode about them as
+        # remote servers.
+        #
+        # Two config formats are supported:
+        # - Opencode-format: has "_tools" key (from opencode create_sdk_mcp_server)
+        # - Claude-format:   has type="sdk" + "instance" key (from claude create_sdk_mcp_server)
+        effective_servers = dict(self._options.mcp_servers)
+        sdk_servers = {
+            name: cfg for name, cfg in effective_servers.items()
+            if isinstance(cfg, dict) and (
+                "_tools" in cfg
+                or (cfg.get("type") == "sdk" and "instance" in cfg)
+            )
+        }
+        if sdk_servers:
+            from ._mcp_bridge import McpHttpBridge
+
+            self._mcp_bridge = McpHttpBridge()
+            for name, cfg in sdk_servers.items():
+                if "_tools" in cfg:
+                    port = await self._mcp_bridge.start_server(name)
+                else:
+                    # Claude-format: host the mcp.server.Server instance directly
+                    port = await self._mcp_bridge.start_server_from_instance(
+                        name, cfg["instance"],
+                    )
+                # Replace config with remote HTTP config
+                effective_servers[name] = {
+                    "url": f"http://127.0.0.1:{port}/mcp",
+                }
+
+        acp_mcp_servers = _build_mcp_servers(effective_servers)
 
         if self._options.resume:
             await self._session.load_session(
                 session_id=self._options.resume,
                 cwd=self._options.cwd,
+                mcp_servers=acp_mcp_servers,
             )
         else:
             await self._session.new_session(
                 cwd=self._options.cwd,
-                mcp_servers=mcp_servers,
+                mcp_servers=acp_mcp_servers,
                 model=self._options.model or None,
+                provider_id=self._options.provider_id or None,
+                permission_mode=self._options.permission_mode,
+                system_prompt=self._options.system_prompt,
             )
 
+    def _build_init_data(self, session_id: str) -> dict[str, Any]:
+        """Build the init SystemMessage data dict from options."""
+        data: dict[str, Any] = {
+            "session_id": session_id,
+            "model": self._options.model,
+            "cwd": self._options.cwd,
+        }
+        if self._options.plugins:
+            data["plugins"] = self._options.plugins
+        if self._options.mcp_servers:
+            data["mcp_servers"] = list(self._options.mcp_servers.keys())
+        return data
+
     async def disconnect(self) -> None:
         """Shut down the transport and clean up."""
+        if self._mcp_bridge:
+            await self._mcp_bridge.stop_all()
+            self._mcp_bridge = None
         if self._transport:
             await self._transport.close()
             self._transport = None
@@ -171,11 +224,9 @@ class SDKClient:
             # Yield init system message
             yield SystemMessage(
                 subtype="init",
-                data={
-                    "session_id": self._transport.session_id,
-                    "model": self._options.model,
-                    "cwd": self._options.cwd,
-                },
+                data=self._build_init_data(
+                    session_id=self._transport.session_id,
+                ),
             )
 
             # Stream response parts via SSE
@@ -192,11 +243,9 @@ class SDKClient:
 
             yield SystemMessage(
                 subtype="init",
-                data={
-                    "session_id": self._session.session_id,
-                    "model": self._options.model,
-                    "cwd": self._options.cwd,
-                },
+                data=self._build_init_data(
+                    session_id=self._session.session_id,
+                ),
             )
 
             async for msg in self._session.receive_messages():
@@ -204,18 +253,43 @@ class SDKClient:
 
 
 def _build_mcp_servers(servers: dict[str, Any]) -> list[dict[str, Any]]:
-    """Convert the mcp_servers dict to ACP mcpServers format."""
+    """Convert the mcp_servers dict to ACP mcpServers wire format.
+
+    ACP distinguishes server types by the presence of a ``type`` field:
+    - Local/stdio (no ``type``): ``{name, command, args, env}``
+    - Remote HTTP (``type: "http"``): ``{name, type, url, headers}``
+    - Remote SSE (``type: "sse"``): ``{name, type, url, headers}``
+
+    ``env`` and ``headers`` use ``[{name, value}]`` array format on the wire,
+    not dict format.
+    """
     result = []
     for name, config in servers.items():
-        if isinstance(config, dict):
-            entry: dict[str, Any] = {"name": name}
-            if "command" in config:
-                entry["transport"] = "stdio"
-                entry["command"] = config["command"]
-                entry["args"] = config.get("args", [])
-                entry["env"] = config.get("env", {})
-            elif "url" in config:
-                entry["transport"] = "sse"
-                entry["url"] = config["url"]
-            result.append(entry)
+        if not isinstance(config, dict):
+            continue
+        entry: dict[str, Any] = {"name": name}
+        if "command" in config:
+            # Local/stdio server — NO "type" field
+            entry["command"] = config["command"]
+            entry["args"] = config.get("args", [])
+            # Convert env dict to [{name, value}] array
+            raw_env = config.get("env", {})
+            if isinstance(raw_env, dict):
+                entry["env"] = [{"name": k, "value": v} for k, v in raw_env.items()]
+            elif isinstance(raw_env, list):
+                entry["env"] = raw_env
+            else:
+                entry["env"] = []
+        elif "url" in config:
+            # Remote server — "http" for streamable-http, "sse" for SSE
+            entry["type"] = config.get("type", "http")
+            entry["url"] = config["url"]
+            raw_headers = config.get("headers", {})
+            if isinstance(raw_headers, dict):
+                entry["headers"] = [{"name": k, "value": v} for k, v in raw_headers.items()]
+            elif isinstance(raw_headers, list):
+                entry["headers"] = raw_headers
+            else:
+                entry["headers"] = []
+        result.append(entry)
     return result

opencode_agent_sdk-0.4.6/src/opencode_agent_sdk/model_registry.py

@@ -0,0 +1,81 @@
+"""Generic model registry for mapping user-friendly aliases to model configurations.
+
+Provides a pluggable registry that SDK consumers can populate with their own
+model aliases and provider mappings. No vendor-specific defaults are included.
+
+Usage::
+
+    from opencode_agent_sdk.model_registry import ModelConfig, ModelRegistry
+
+    registry = ModelRegistry()
+    registry.register("my-model", ModelConfig("actual-model-id", "my-provider"))
+
+    config = registry.resolve("my-model")
+    if config:
+        options = AgentOptions(model=config.model_id, provider_id=config.provider_id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ModelConfig:
+    """Model configuration mapping an alias to its actual model and provider IDs."""
+
+    model_id: str
+    provider_id: str
+
+
+class ModelRegistry:
+    """Registry for model alias → (model_id, provider_id) mappings.
+
+    Thread-safe for reads; callers should populate the registry at startup
+    before concurrent access.
+    """
+
+    def __init__(self) -> None:
+        self._models: dict[str, ModelConfig] = {}
+
+    def register(self, alias: str, config: ModelConfig) -> None:
+        """Register a model alias.
+
+        Args:
+            alias: User-friendly name (stored lowercase).
+            config: Model configuration with model_id and provider_id.
+        """
+        self._models[alias.lower()] = config
+
+    def register_many(self, models: dict[str, ModelConfig]) -> None:
+        """Register multiple model aliases at once.
+
+        Args:
+            models: Mapping of alias → ModelConfig.
+        """
+        for alias, config in models.items():
+            self._models[alias.lower()] = config
+
+    def resolve(self, alias: str) -> ModelConfig | None:
+        """Resolve a user-friendly alias to a ModelConfig.
+
+        Args:
+            alias: Model alias (case-insensitive lookup).
+
+        Returns:
+            ModelConfig if alias is known, None otherwise.
+        """
+        return self._models.get(alias.lower())
+
+    def list_models(self) -> dict[str, ModelConfig]:
+        """Return a copy of all registered models."""
+        return dict(self._models)
+
+    def format_help(self) -> str:
+        """Return a formatted list of available models for user-facing help."""
+        if not self._models:
+            return "No models registered."
+        lines = ["Available models:"]
+        for alias, config in sorted(self._models.items()):
+            lines.append(f"  {alias} -> {config.model_id} (provider: {config.provider_id})")
+        return "\n".join(lines)

{opencode_agent_sdk-0.2.0 → opencode_agent_sdk-0.4.6}/src/opencode_agent_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-agent-sdk
-Version: 0.2.0
+Version: 0.4.6
 Summary: Open-source Agent SDK backed by OpenCode ACP (drop-in replacement for claude_agent_sdk)
 Author: OpenCode
 License: MIT
@@ -16,6 +16,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: anyio
 Requires-Dist: httpx
+Requires-Dist: fastmcp>=2.0.0
 Provides-Extra: opencode-ai
 Requires-Dist: opencode-ai>=0.1.0a36; extra == "opencode-ai"
 Provides-Extra: dev

{opencode_agent_sdk-0.2.0 → opencode_agent_sdk-0.4.6}/src/opencode_agent_sdk.egg-info/SOURCES.txt

@@ -2,7 +2,9 @@ README.md
 pyproject.toml
 src/opencode_agent_sdk/__init__.py
 src/opencode_agent_sdk/_errors.py
+src/opencode_agent_sdk/_mcp_bridge.py
 src/opencode_agent_sdk/client.py
+src/opencode_agent_sdk/model_registry.py
 src/opencode_agent_sdk/tools.py
 src/opencode_agent_sdk/types.py
 src/opencode_agent_sdk.egg-info/PKG-INFO
@@ -15,5 +17,6 @@ src/opencode_agent_sdk/_internal/acp.py
 src/opencode_agent_sdk/_internal/http_transport.py
 src/opencode_agent_sdk/_internal/transport.py
 tests/test_common.py
+tests/test_model_registry.py
 tests/test_opencode_agent.py
 tests/test_runner.py

{opencode_agent_sdk-0.2.0 → opencode_agent_sdk-0.4.6}/src/opencode_agent_sdk.egg-info/requires.txt

@@ -1,5 +1,6 @@
 anyio
 httpx
+fastmcp>=2.0.0
 
 [dev]
 pytest>=8.0

opencode_agent_sdk-0.4.6/tests/test_model_registry.py

@@ -0,0 +1,64 @@
+"""Tests for the generic ModelRegistry in the SDK."""
+
+import pytest
+from opencode_agent_sdk.model_registry import ModelConfig, ModelRegistry
+
+
+class TestModelRegistry:
+    def test_register_and_resolve(self):
+        registry = ModelRegistry()
+        registry.register("test-model", ModelConfig("actual-id", "test-provider"))
+        config = registry.resolve("test-model")
+        assert config is not None
+        assert config.model_id == "actual-id"
+        assert config.provider_id == "test-provider"
+
+    def test_resolve_case_insensitive(self):
+        registry = ModelRegistry()
+        registry.register("My-Model", ModelConfig("id", "provider"))
+        assert registry.resolve("my-model") is not None
+        assert registry.resolve("MY-MODEL") is not None
+
+    def test_resolve_unknown_returns_none(self):
+        registry = ModelRegistry()
+        assert registry.resolve("nonexistent") is None
+
+    def test_register_many(self):
+        registry = ModelRegistry()
+        registry.register_many({
+            "model-a": ModelConfig("a-id", "a-provider"),
+            "model-b": ModelConfig("b-id", "b-provider"),
+        })
+        assert registry.resolve("model-a") is not None
+        assert registry.resolve("model-b") is not None
+
+    def test_list_models(self):
+        registry = ModelRegistry()
+        registry.register("x", ModelConfig("x-id", "x-provider"))
+        models = registry.list_models()
+        assert "x" in models
+        assert models["x"].model_id == "x-id"
+
+    def test_list_models_returns_copy(self):
+        registry = ModelRegistry()
+        registry.register("x", ModelConfig("x-id", "x-provider"))
+        models = registry.list_models()
+        models["y"] = ModelConfig("y-id", "y-provider")
+        assert registry.resolve("y") is None
+
+    def test_format_help_empty(self):
+        registry = ModelRegistry()
+        assert "No models registered" in registry.format_help()
+
+    def test_format_help_with_models(self):
+        registry = ModelRegistry()
+        registry.register("my-model", ModelConfig("real-id", "my-provider"))
+        help_text = registry.format_help()
+        assert "my-model" in help_text
+        assert "real-id" in help_text
+        assert "my-provider" in help_text
+
+    def test_model_config_frozen(self):
+        config = ModelConfig("id", "provider")
+        with pytest.raises(AttributeError):
+            config.model_id = "changed"