opencode-agent-sdk 0.2.0__py3-none-any.whl

opencode_agent_sdk/tools.py

@@ -0,0 +1,82 @@
+"""MCP tool decorator and server creation, matching claude_agent_sdk API."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass
+class SdkMcpTool:
+    """A tool registered via the @tool decorator."""
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    handler: Callable[..., Any]
+
+
+def tool(
+    name: str,
+    description: str,
+    input_schema: dict[str, Any] | None = None,
+) -> Callable[[Callable[..., Any]], SdkMcpTool]:
+    """Decorator to create an MCP tool from a function.
+
+    Usage::
+
+        @tool(name="greet", description="Say hello", input_schema={"type": "object", "properties": {"name": {"type": "string"}}})
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+    """
+
+    def decorator(fn: Callable[..., Any]) -> SdkMcpTool:
+        return SdkMcpTool(
+            name=name,
+            description=description,
+            input_schema=input_schema or {"type": "object", "properties": {}},
+            handler=fn,
+        )
+
+    return decorator
+
+
+def create_sdk_mcp_server(
+    name: str,
+    version: str | None = None,
+    tools: list[SdkMcpTool] | None = None,
+) -> dict[str, Any]:
+    """Create an MCP server configuration for use with AgentOptions.mcp_servers.
+
+    For ACP, tools run in-process via a local stdio MCP server.
+    This returns a config dict that SDKClient uses to spawn a Python
+    MCP server subprocess hosting the given tools.
+
+    Returns a dict suitable for ``AgentOptions.mcp_servers``::
+
+        server = create_sdk_mcp_server("my-tools", tools=[my_tool])
+        options = AgentOptions(mcp_servers={"my-tools": server})
+    """
+    tool_list = tools or []
+    tool_defs = []
+    for t in tool_list:
+        tool_defs.append({
+            "name": t.name,
+            "description": t.description,
+            "inputSchema": t.input_schema,
+        })
+
+    # Store tools for the in-process MCP server runner
+    _TOOL_REGISTRY[name] = tool_list
+
+    return {
+        "command": sys.executable,
+        "args": ["-m", "opencode_agent_sdk._mcp_runner", name],
+        "_tools": tool_defs,
+        "_version": version or "1.0.0",
+    }
+
+
+# Global registry for in-process tool serving
+_TOOL_REGISTRY: dict[str, list[SdkMcpTool]] = {}

opencode_agent_sdk/types.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class TextBlock:
+    text: str
+    type: str = "text"
+
+
+@dataclass
+class ToolUseBlock:
+    id: str
+    name: str
+    input: dict[str, Any]
+    type: str = "tool_use"
+
+
+@dataclass
+class AssistantMessage:
+    content: list[TextBlock | ToolUseBlock]
+    role: str = "assistant"
+
+
+@dataclass
+class ResultMessage:
+    usage: dict[str, Any] = field(default_factory=dict)
+    total_cost_usd: float = 0.0
+    session_id: str = ""
+    duration_ms: float = 0.0
+    num_turns: int = 0
+    is_error: bool = False
+
+
+@dataclass
+class SystemMessage:
+    subtype: str
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HookMatcher:
+    matcher: str | None
+    hooks: list[Callable[..., Any]]
+    timeout: float = 30.0
+
+
+# Type aliases matching claude_agent_sdk
+HookInput = dict[str, Any]
+HookContext = dict[str, Any]
+HookJSONOutput = dict[str, Any]

opencode_agent_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: opencode-agent-sdk
+Version: 0.2.0
+Summary: Open-source Agent SDK backed by OpenCode ACP (drop-in replacement for claude_agent_sdk)
+Author: OpenCode
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anyio
+Requires-Dist: httpx
+Provides-Extra: opencode-ai
+Requires-Dist: opencode-ai>=0.1.0a36; extra == "opencode-ai"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# OpenCode Agent SDK for Python
+
+Python SDK for building agents backed by [OpenCode](https://github.com/nichochar/opencode). Drop-in replacement for `claude_agent_sdk` with support for any LLM provider (Anthropic, OpenAI, xAI, etc.).
+
+<video src="https://github.com/user-attachments/assets/061fb862-3253-46aa-92a7-71dc9258960a"
+       autoplay
+       muted
+       loop
+       playsinline
+       controls>
+</video>
+
+## Installation
+
+```bash
+pip install opencode-agent-sdk
+```
+
+**Prerequisites:**
+
+- Python 3.10+
+- An OpenCode server (`opencode serve`) **or** the `opencode` CLI installed locally
+
+## Quick Start
+
+```python
+import asyncio
+from opencode_agent_sdk import SDKClient, AgentOptions, AssistantMessage, TextBlock
+
+async def main():
+    client = SDKClient(options=AgentOptions(
+        model="claude-haiku-4-5",
+        server_url="http://localhost:54321",
+    ))
+
+    await client.connect()
+    await client.query("What is 2 + 2?")
+
+    async for message in client.receive_response():
+        if isinstance(message, AssistantMessage):
+            for block in message.content:
+                if isinstance(block, TextBlock):
+                    print(block.text)
+
+    await client.disconnect()
+
+asyncio.run(main())
+```
+
+## SDKClient
+
+`SDKClient` supports bidirectional conversations with an LLM via OpenCode. It works in two transport modes:
+
+- **HTTP mode** — communicates with a running `opencode serve` instance over REST
+- **Subprocess mode** — spawns `opencode acp` locally over stdio JSON-RPC
+
+### HTTP Mode (recommended)
+
+Start the server, then connect:
+
+```bash
+docker compose up -d   # starts opencode serve on port 54321
+```
+
+```python
+from opencode_agent_sdk import SDKClient, AgentOptions
+
+client = SDKClient(options=AgentOptions(
+    model="claude-haiku-4-5",
+    server_url="http://localhost:54321",
+    system_prompt="You are a helpful assistant",
+))
+
+await client.connect()
+await client.query("Hello!")
+
+async for msg in client.receive_response():
+    print(msg)
+
+await client.disconnect()
+```
+
+### Subprocess Mode
+
+When `server_url` is not set, the SDK spawns `opencode acp` as a child process:
+
+```python
+client = SDKClient(options=AgentOptions(
+    cwd="/path/to/project",
+    model="claude-haiku-4-5",
+))
+```
+
+### Resuming Sessions
+
+```python
+options = AgentOptions(
+    resume="session-id-from-previous-run",
+    server_url="http://localhost:54321",
+)
+```
+
+## AgentOptions
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `cwd` | `str` | `"."` | Working directory |
+| `model` | `str` | `""` | Model identifier (e.g. `"claude-haiku-4-5"`) |
+| `provider_id` | `str` | `"anthropic"` | Provider identifier |
+| `system_prompt` | `str` | `""` | System prompt for the LLM |
+| `server_url` | `str` | `""` | OpenCode server URL; enables HTTP mode when set |
+| `mcp_servers` | `dict` | `{}` | MCP server configurations |
+| `allowed_tools` | `list[str]` | `[]` | Tools the agent is allowed to use |
+| `permission_mode` | `str` | `""` | Permission mode for tool execution |
+| `hooks` | `dict` | `{}` | Hook matchers keyed by event type |
+| `max_turns` | `int` | `100` | Maximum conversation turns |
+| `resume` | `str \| None` | `None` | Session ID to resume |
+
+## Custom Tools (MCP Servers)
+
+Define tools as Python functions and expose them as in-process MCP servers:
+
+```python
+from opencode_agent_sdk import tool, create_sdk_mcp_server, SDKClient, AgentOptions
+
+@tool("greet", "Greet a user", {"type": "object", "properties": {"name": {"type": "string"}}})
+def greet_user(args):
+    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}
+
+server = create_sdk_mcp_server("my-tools", tools=[greet_user])
+
+client = SDKClient(options=AgentOptions(
+    mcp_servers={"my-tools": server},
+    allowed_tools=["mcp__my-tools__greet"],
+    server_url="http://localhost:54321",
+))
+```
+
+You can mix in-process SDK servers with external MCP servers:
+
+```python
+options = AgentOptions(
+    mcp_servers={
+        "internal": sdk_server,          # In-process SDK server
+        "external": {                    # External stdio server
+            "command": "external-server",
+            "args": ["--port", "8080"],
+        },
+    }
+)
+```
+
+## Hooks
+
+Hooks let you intercept and control tool execution. They run deterministically at specific points in the agent loop.
+
+```python
+from opencode_agent_sdk import SDKClient, AgentOptions, HookMatcher
+
+async def check_bash_command(input_data, tool_use_id, context):
+    tool_input = input_data["tool_input"]
+    command = tool_input.get("command", "")
+
+    if "rm -rf" in command:
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": "Destructive command blocked",
+            }
+        }
+    return {}
+
+options = AgentOptions(
+    allowed_tools=["Bash"],
+    hooks={
+        "PreToolUse": [
+            HookMatcher(matcher="Bash", hooks=[check_bash_command]),
+        ],
+    },
+    server_url="http://localhost:54321",
+)
+
+client = SDKClient(options=options)
+await client.connect()
+await client.query("Run: echo hello")
+
+async for msg in client.receive_response():
+    print(msg)
+
+await client.disconnect()
+```
+
+Hook event types: `"PreToolUse"`, `"Stop"`
+
+## Types
+
+See [src/opencode_agent_sdk/types.py](src/opencode_agent_sdk/types.py) for complete type definitions:
+
+- `AssistantMessage` — LLM response containing `TextBlock` and/or `ToolUseBlock`
+- `ResultMessage` — Final message with usage stats, cost, and session info
+- `SystemMessage` — Internal events (init, tool results, thoughts)
+- `TextBlock` — Text content from the LLM
+- `ToolUseBlock` — Tool invocation with name and input
+- `HookMatcher` — Matches tool names to hook functions
+
+## Error Handling
+
+```python
+from opencode_agent_sdk._errors import ProcessError
+
+try:
+    await client.connect()
+except ProcessError as e:
+    print(f"Failed with exit code: {e.exit_code}")
+```
+
+## Migrating from claude_agent_sdk
+
+This SDK mirrors the `claude_agent_sdk` API. Migration requires renaming imports:
+
+```python
+# Before (claude_agent_sdk)
+from claude_agent_sdk import (
+    ClaudeAgentOptions, ClaudeSDKClient, AssistantMessage,
+    ResultMessage, SystemMessage, TextBlock, ToolUseBlock, HookMatcher,
+)
+from claude_agent_sdk._errors import ProcessError
+
+# After (opencode_agent_sdk)
+from opencode_agent_sdk import (
+    AgentOptions, SDKClient, AssistantMessage,
+    ResultMessage, SystemMessage, TextBlock, ToolUseBlock, HookMatcher,
+)
+from opencode_agent_sdk._errors import ProcessError
+```
+
+All method calls, message types, hooks, and tool decorators stay the same. Only the class names change:
+
+| claude_agent_sdk | opencode_agent_sdk |
+|------------------|-------------------|
+| `ClaudeSDKClient` | `SDKClient` |
+| `ClaudeAgentOptions` | `AgentOptions` |
+
+## Demo: End-to-End Walkthrough
+
+A full working demo that connects to `opencode serve`, sends a prompt to clone a GitHub repo, and streams the LLM response back through the SDK.
+
+### 1. Configure API keys
+
+Create a `.env` file in the project root with your provider key:
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### 2. Start the server
+
+```bash
+docker compose up -d opencode
+```
+
+This builds and starts the `opencode serve` container on port 54321.
+
+### 3. Install dependencies
+
+```bash
+uv sync
+```
+
+### 4. Run the E2E demo
+
+```bash
+uv run python scripts/e2e_test.py
+```
+
+### Expected output
+
+```
+============================================================
+E2E Test: Clone repo & explain project
+============================================================
+Server: http://127.0.0.1:54321
+
+[*] Connecting ...
+[*] Connected.
+
+[>] Prompt:
+Clone the repo https://github.com/dingkwang/opencode-agent-sdk-python and then
+explain what the project does. Give a concise summary of its purpose,
+architecture, and key components.
+
+------------------------------------------------------------
+
+  [system:init]
+  [system:step_start]
+
+  [assistant]
+  ## opencode-agent-sdk-python
+  ### Purpose
+  An open-source Python SDK that serves as a drop-in replacement for Anthropic's
+  proprietary `claude_agent_sdk`. It delegates all LLM work to OpenCode — an
+  open-source headless server that supports any provider ...
+  ...
+
+============================================================
+  [result] session  = ses_...
+           cost     = $0.024723
+           turns    = 1
+           is_error = False
+============================================================
+
+[*] Message counts: {'system': 2, 'assistant': 1, 'result': 1}
+[*] E2E test complete.
+```
+
+### What's happening
+
+1. `SDKClient` creates an HTTP session against `opencode serve`
+2. `query()` sends the user prompt via `POST /session/{id}/message`
+3. `receive_response()` yields typed messages: `SystemMessage` (init, step events), `AssistantMessage` (LLM text/tool calls), and `ResultMessage` (cost, session ID, turn count)
+4. `disconnect()` cleans up the session
+
+### Customizing the demo
+
+Set a custom server URL via environment variable:
+
+```bash
+OPENCODE_SERVER_URL=http://your-host:54321 uv run python scripts/e2e_test.py
+```
+
+## Running with Docker
+
+```bash
+# Start opencode serve
+docker compose up -d
+
+# Run the integration test
+docker compose run --rm test
+```
+
+The Docker setup uses `opencode-ai` v1.2.6 and exposes the REST API on port 54321. Pass provider API keys via `.env` (e.g. `ANTHROPIC_API_KEY`).
+
+## Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run demo against a running opencode serve
+uv run python scripts/opencode_ai_demo.py
+
+# Interactive multi-turn chat
+uv run python scripts/chat.py
+```
+
+## License
+
+MIT

opencode_agent_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+opencode_agent_sdk/__init__.py,sha256=JYWf2ZgML1Msnj_GNANh53HZrKSBUbjGQCycdHqV_DY,572
+opencode_agent_sdk/_errors.py,sha256=iP-goiRAM1gRIoDm503jQkK0HP0SE3p00R4hljhI0js,281
+opencode_agent_sdk/client.py,sha256=wko7SHiLDd23390pht7KSV1qhj31sxwxLVcOXgmJZkI,7686
+opencode_agent_sdk/tools.py,sha256=x3mCCjSH1wxn6DQAL02icyOU8i5RPH9g1qiaqSwPjwA,2297
+opencode_agent_sdk/types.py,sha256=a2yTnCPQu6w1SfDUcHNgrphhSBzqlmwWRDboST4ZwQI,979
+opencode_agent_sdk/_internal/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+opencode_agent_sdk/_internal/acp.py,sha256=DpZfMtTEXLCClutp5H5SFXdJV3UbFm8MJUs6-BCO5EI,13466
+opencode_agent_sdk/_internal/http_transport.py,sha256=ACM4I9-57wizjCt9jvgOkpzorS33j46q1CC0d6muDMo,13038
+opencode_agent_sdk/_internal/transport.py,sha256=YNd3WepNpLpWsydNJ4hX8yukvSCXf4B-F8fBKy6LJcE,3403
+opencode_agent_sdk-0.2.0.dist-info/METADATA,sha256=yae6Gz5uxnIBE2hvxQSiVtgcDAXP-7BGGqX0SuTcT_Y,10535
+opencode_agent_sdk-0.2.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+opencode_agent_sdk-0.2.0.dist-info/top_level.txt,sha256=pAgKlVvKFtrUjAqIt0OquHRVQZ7LfEE0CIyiLjrWM74,19
+opencode_agent_sdk-0.2.0.dist-info/RECORD,,

opencode_agent_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

opencode_agent_sdk-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+opencode_agent_sdk