opencode-agent 0.1.0__tar.gz

opencode_agent-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: opencode-agent
+Version: 0.1.0
+Summary: Python orchestration layer for the OpenCode Agent API
+License-Expression: MIT
+Keywords: opencode,agent,ai,orchestration,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.27
+
+# OpenCode Orchestrator
+
+`opencode-orchestrator` is a Python 3.11+ client wrapper for the OpenCode server. The main API is a simple `Agent` class; defaults come from `.env`, MCP definitions come from `mcp.json`, and file or shell work runs on the OpenCode server inside the configured project path.
+
+## Features
+
+- Defaults loaded from `.env`
+- MCP server definitions loaded from `mcp.json`
+- Required `OPENCODE_PROJECT_PATH` for project-scoped file and shell operations
+- Simple `Agent` wrapper for server-side execution
+- File, terminal, tool, streaming, and MCP usage through the OpenCode server
+- Optional lower-level client and runner APIs if needed
+- Shell execution via `POST /session/:id/shell`
+- Optional SSE event streaming via `GET /event`
+- Live examples for running against a real OpenCode server
+
+## Install
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Configuration
+
+Load configuration from `.env`. MCP server definitions are loaded from `mcp.json`.
+
+The included `.env` file sets:
+
+```bash
+OPENCODE_SERVER=http://localhost:4096
+OPENCODE_PROJECT_PATH=/absolute/path/to/project
+OPENCODE_MODEL=openai/gpt-5.4-mini
+```
+
+`OPENCODE_PROJECT_PATH` is required. The client uses it as the default scope for file calls and prefixes shell commands with `cd <project_path> && ...` so the code can be run from any local directory while still operating inside the intended OpenCode project.
+
+## Minimal Usage
+
+```python
+from opencode_orchestrator import Agent
+
+agent = Agent(
+    name="MainAgent",
+    system_prompt="You are a highly capable AI assistant that uses the OpenCode server.",
+)
+
+reply = agent.run(
+    user_prompt="Who are you and what time is it? Do not use tools."
+)
+print(reply)
+
+agent.close()
+```
+
+If you want tool access and full metadata instead of only the text response:
+
+```python
+from opencode_orchestrator import Agent
+
+agent = Agent(agent="explore", tools=["glob", "read"])
+result = agent.run("Summarize this project.", return_result=True)
+print(result.output)
+print(result.metadata.session_id)
+agent.close()
+```
+
+Terminal execution is also minimal:
+
+```python
+from opencode_orchestrator import Agent
+
+agent = Agent(name="TerminalAgent")
+result = agent.run_shell("pwd && ls", return_result=True)
+print(result.metadata.tool_events)
+agent.close()
+```
+
+Available models can be listed from the already usable provider config only:
+
+```python
+from opencode_orchestrator import Agent
+
+agent = Agent()
+print(agent.list_models())
+agent.close()
+```
+
+You can also pass a custom model directly, either as the default for the agent or per call:
+
+```python
+from opencode_orchestrator import Agent
+
+agent = Agent(model="openai/gpt-5.4")
+reply = agent.run("Reply in one line.")
+
+other = agent.run(
+    "Reply in one line with a different model.",
+    model="openai/gpt-5.4-mini",
+)
+
+agent.close()
+```
+
+## Live Examples
+
+These examples are intended to run against a real OpenCode server at `http://localhost:4096`.
+
+Simple usage:
+
+```bash
+.venv/bin/python examples/simple_usage.py
+```
+
+Tool usage:
+
+```bash
+.venv/bin/python examples/tool_usage.py
+```
+
+Multiple agents:
+
+```bash
+.venv/bin/python examples/multi_agent_usage.py
+```
+
+File operations:
+
+```bash
+.venv/bin/python examples/file_operations.py
+```
+
+Terminal operations:
+
+```bash
+.venv/bin/python examples/terminal_operations.py
+```
+
+Streaming:
+
+```bash
+.venv/bin/python examples/streaming_usage.py
+```
+
+## CLI Usage
+
+Run a single task:
+
+```bash
+opencode-orchestrator run "Create a release checklist" --agent plan
+```
+
+Run a multi-agent task:
+
+```bash
+opencode-orchestrator orchestrate "Implement and review a feature" --parallel
+```
+
+Inspect sessions:
+
+```bash
+opencode-orchestrator sessions list
+opencode-orchestrator sessions status
+opencode-orchestrator sessions abort ses_123
+```
+
+Inspect tools and MCP servers:
+
+```bash
+opencode-orchestrator tools --ids
+opencode-orchestrator mcp list
+```
+
+Run a shell command through OpenCode:
+
+```bash
+opencode-orchestrator shell ses_123 "pytest -q"
+```
+
+Read a few streaming events:
+
+```bash
+opencode-orchestrator stream --limit 5
+```
+
+## Notes
+
+- Defaults are taken from `.env` unless you override fields directly in `Agent(...)` or `OpenCodeConfig`.
+- MCP registration settings come from `mcp.json`.
+- Tool allowlists are filtered against the live tool IDs reported by the server.
+- `Agent.run()` returns plain text by default so the common case stays minimal.
+- `Agent.list_models()` filters the server provider config down to models that are directly usable with the currently configured credentials.

opencode_agent-0.1.0/README.md

@@ -0,0 +1,193 @@
+# OpenCode Orchestrator
+
+`opencode-orchestrator` is a Python 3.11+ client wrapper for the OpenCode server. The main API is a simple `Agent` class; defaults come from `.env`, MCP definitions come from `mcp.json`, and file or shell work runs on the OpenCode server inside the configured project path.
+
+## Features
+
+- Defaults loaded from `.env`
+- MCP server definitions loaded from `mcp.json`
+- Required `OPENCODE_PROJECT_PATH` for project-scoped file and shell operations
+- Simple `Agent` wrapper for server-side execution
+- File, terminal, tool, streaming, and MCP usage through the OpenCode server
+- Optional lower-level client and runner APIs if needed
+- Shell execution via `POST /session/:id/shell`
+- Optional SSE event streaming via `GET /event`
+- Live examples for running against a real OpenCode server
+
+## Install
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Configuration
+
+Load configuration from `.env`. MCP server definitions are loaded from `mcp.json`.
+
+The included `.env` file sets:
+
+```bash
+OPENCODE_SERVER=http://localhost:4096
+OPENCODE_PROJECT_PATH=/absolute/path/to/project
+OPENCODE_MODEL=openai/gpt-5.4-mini
+```
+
+`OPENCODE_PROJECT_PATH` is required. The client uses it as the default scope for file calls and prefixes shell commands with `cd <project_path> && ...` so the code can be run from any local directory while still operating inside the intended OpenCode project.
+
+## Minimal Usage
+
+```python
+from opencode_orchestrator import Agent
+
+agent = Agent(
+    name="MainAgent",
+    system_prompt="You are a highly capable AI assistant that uses the OpenCode server.",
+)
+
+reply = agent.run(
+    user_prompt="Who are you and what time is it? Do not use tools."
+)
+print(reply)
+
+agent.close()
+```
+
+If you want tool access and full metadata instead of only the text response:
+
+```python
+from opencode_orchestrator import Agent
+
+agent = Agent(agent="explore", tools=["glob", "read"])
+result = agent.run("Summarize this project.", return_result=True)
+print(result.output)
+print(result.metadata.session_id)
+agent.close()
+```
+
+Terminal execution is also minimal:
+
+```python
+from opencode_orchestrator import Agent
+
+agent = Agent(name="TerminalAgent")
+result = agent.run_shell("pwd && ls", return_result=True)
+print(result.metadata.tool_events)
+agent.close()
+```
+
+Available models can be listed from the already usable provider config only:
+
+```python
+from opencode_orchestrator import Agent
+
+agent = Agent()
+print(agent.list_models())
+agent.close()
+```
+
+You can also pass a custom model directly, either as the default for the agent or per call:
+
+```python
+from opencode_orchestrator import Agent
+
+agent = Agent(model="openai/gpt-5.4")
+reply = agent.run("Reply in one line.")
+
+other = agent.run(
+    "Reply in one line with a different model.",
+    model="openai/gpt-5.4-mini",
+)
+
+agent.close()
+```
+
+## Live Examples
+
+These examples are intended to run against a real OpenCode server at `http://localhost:4096`.
+
+Simple usage:
+
+```bash
+.venv/bin/python examples/simple_usage.py
+```
+
+Tool usage:
+
+```bash
+.venv/bin/python examples/tool_usage.py
+```
+
+Multiple agents:
+
+```bash
+.venv/bin/python examples/multi_agent_usage.py
+```
+
+File operations:
+
+```bash
+.venv/bin/python examples/file_operations.py
+```
+
+Terminal operations:
+
+```bash
+.venv/bin/python examples/terminal_operations.py
+```
+
+Streaming:
+
+```bash
+.venv/bin/python examples/streaming_usage.py
+```
+
+## CLI Usage
+
+Run a single task:
+
+```bash
+opencode-orchestrator run "Create a release checklist" --agent plan
+```
+
+Run a multi-agent task:
+
+```bash
+opencode-orchestrator orchestrate "Implement and review a feature" --parallel
+```
+
+Inspect sessions:
+
+```bash
+opencode-orchestrator sessions list
+opencode-orchestrator sessions status
+opencode-orchestrator sessions abort ses_123
+```
+
+Inspect tools and MCP servers:
+
+```bash
+opencode-orchestrator tools --ids
+opencode-orchestrator mcp list
+```
+
+Run a shell command through OpenCode:
+
+```bash
+opencode-orchestrator shell ses_123 "pytest -q"
+```
+
+Read a few streaming events:
+
+```bash
+opencode-orchestrator stream --limit 5
+```
+
+## Notes
+
+- Defaults are taken from `.env` unless you override fields directly in `Agent(...)` or `OpenCodeConfig`.
+- MCP registration settings come from `mcp.json`.
+- Tool allowlists are filtered against the live tool IDs reported by the server.
+- `Agent.run()` returns plain text by default so the common case stays minimal.
+- `Agent.list_models()` filters the server provider config down to models that are directly usable with the currently configured credentials.

opencode_agent-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opencode-agent"
+version = "0.1.0"
+description = "Python orchestration layer for the OpenCode Agent API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["opencode", "agent", "ai", "orchestration", "llm"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "httpx>=0.27,<1.0",
+]
+
+[project.scripts]
+opencode-agent = "opencode_agent.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

opencode_agent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

opencode_agent-0.1.0/src/opencode_agent/__init__.py

@@ -0,0 +1,26 @@
+from .agent import Agent
+from .client import OpenCodeClient
+from .config import OpenCodeConfig
+from .exceptions import (
+    MCPReadinessError,
+    OpenCodeError,
+    OpenCodeHTTPError,
+    SessionNotFoundError,
+    TaskTimeoutError,
+    ToolNotFoundError,
+)
+from .orchestrator import MultiAgentRunner, SingleAgentRunner
+
+__all__ = [
+    "Agent",
+    "MCPReadinessError",
+    "MultiAgentRunner",
+    "OpenCodeClient",
+    "OpenCodeConfig",
+    "OpenCodeError",
+    "OpenCodeHTTPError",
+    "SessionNotFoundError",
+    "SingleAgentRunner",
+    "TaskTimeoutError",
+    "ToolNotFoundError",
+]

opencode_agent-0.1.0/src/opencode_agent/agent.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+from .client import OpenCodeClient
+from .config import OpenCodeConfig
+from .managers import MCPManager, SessionManager, ToolManager
+from .models import ExecutionMetadata, ExecutionResult, StreamEvent
+from .orchestrator import EventStreamer, SingleAgentRunner
+
+
+class Agent:
+    def __init__(
+        self,
+        name: str = "OpenCodeAgent",
+        system_prompt: str | None = None,
+        *,
+        agent: str | None = None,
+        model: str | dict[str, Any] | None = None,
+        tools: list[str] | None = None,
+        mcp_servers: list[str] | None = None,
+        project_path: str | None = None,
+        base_url: str | None = None,
+        streaming: bool | None = None,
+        verbose: bool | None = None,
+    ):
+        config = OpenCodeConfig.from_env()
+        if project_path is not None:
+            config.project_path = project_path
+        if base_url is not None:
+            config.base_url = base_url
+        if streaming is not None:
+            config.streaming = streaming
+        if verbose is not None:
+            config.verbose = verbose
+        if model is not None:
+            config.default_model = model
+        if agent is not None:
+            config.default_agent = agent
+        if tools is not None:
+            config.default_tools = tools
+
+        self.name = name
+        self.system_prompt = system_prompt
+        self.default_mcp_servers = mcp_servers or []
+        self.config = config
+        self.client = OpenCodeClient(config=config)
+        self.session_manager = SessionManager(self.client)
+        self.tool_manager = ToolManager(self.client)
+        self.mcp_manager = MCPManager(self.client)
+        self.runner = SingleAgentRunner(
+            client=self.client,
+            config=self.config,
+            session_manager=self.session_manager,
+            tool_manager=self.tool_manager,
+            mcp_manager=self.mcp_manager,
+        )
+        self.event_streamer = EventStreamer(self.client)
+        self.session_id: str | None = None
+
+    def close(self) -> None:
+        self.client.close()
+
+    def set_model(self, model: str | dict[str, Any] | None) -> None:
+        self.config.default_model = model
+
+    def list_models(self, include_details: bool = False) -> list[Any]:
+        return self.client.list_available_models(include_details=include_details)
+
+    def run(
+        self,
+        user_prompt: str,
+        *,
+        agent: str | None = None,
+        model: str | dict[str, Any] | None = None,
+        tools: list[str] | None = None,
+        mcp_servers: list[str] | None = None,
+        session_id: str | None = None,
+        return_result: bool = False,
+    ) -> str | ExecutionResult:
+        result = self.runner.run(
+            user_prompt,
+            agent=agent,
+            model=model,
+            tools=tools,
+            mcp_servers=mcp_servers or self.default_mcp_servers or None,
+            session_id=session_id or self.session_id,
+            title=self.name,
+            system=self.system_prompt,
+        )
+        self.session_id = result.metadata.session_id
+        return result if return_result else result.output
+
+    def run_async(
+        self,
+        user_prompt: str,
+        *,
+        agent: str | None = None,
+        model: str | dict[str, Any] | None = None,
+        tools: list[str] | None = None,
+        session_id: str | None = None,
+    ) -> ExecutionMetadata:
+        metadata = self.runner.run_async(
+            user_prompt,
+            agent=agent,
+            model=model,
+            tools=tools,
+            session_id=session_id or self.session_id,
+            title=self.name,
+        )
+        self.session_id = metadata.session_id
+        return metadata
+
+    def run_shell(
+        self,
+        command: str,
+        *,
+        agent: str | None = None,
+        model: str | dict[str, Any] | None = None,
+        return_result: bool = False,
+    ) -> str | ExecutionResult:
+        if not self.session_id:
+            self.session_id = self.client.create_session(title=self.name).id
+        result = self.runner.run_shell(command, session_id=self.session_id, agent=agent, model=model)
+        return result if return_result else result.output
+
+    def stream(self, *, limit: int = 10) -> list[StreamEvent]:
+        return self.event_streamer.stream(limit=limit)
+
+    @staticmethod
+    def to_dict(value: Any) -> Any:
+        if isinstance(value, list):
+            return [Agent.to_dict(item) for item in value]
+        if is_dataclass(value):
+            return asdict(value)
+        return value