opencode-agent 0.1.0__py3-none-any.whl

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/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

opencode_agent/cli.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import asdict, is_dataclass
+import json
+from typing import Any
+
+from .client import OpenCodeClient
+from .config import OpenCodeConfig
+from .logging import configure_logging
+from .managers import MCPManager, SessionManager, ToolManager
+from .orchestrator import EventStreamer, MultiAgentRunner, SingleAgentRunner
+
+
+def _build_runtime(config: OpenCodeConfig) -> dict[str, Any]:
+    client = OpenCodeClient(config)
+    session_manager = SessionManager(client)
+    tool_manager = ToolManager(client)
+    mcp_manager = MCPManager(client)
+    return {
+        "client": client,
+        "single": SingleAgentRunner(client=client, config=config, session_manager=session_manager, tool_manager=tool_manager, mcp_manager=mcp_manager),
+        "multi": MultiAgentRunner(client=client, config=config, session_manager=session_manager, tool_manager=tool_manager, mcp_manager=mcp_manager),
+        "session_manager": session_manager,
+        "tool_manager": tool_manager,
+        "mcp_manager": mcp_manager,
+        "event_streamer": EventStreamer(client),
+    }
+
+
+def _print_json(payload: Any) -> None:
+    def _default(obj: Any) -> Any:
+        if is_dataclass(obj):
+            return asdict(obj)
+        return str(obj)
+
+    print(json.dumps(payload, indent=2, default=_default))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="opencode-orchestrator")
+    parser.add_argument("--base-url", help="Override OpenCode base URL")
+    parser.add_argument("--project-path", help="Override OpenCode project path")
+    parser.add_argument("--verbose", action="store_true", help="Enable verbose logging")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run_parser = subparsers.add_parser("run", help="Run a single-agent task")
+    run_parser.add_argument("prompt")
+    run_parser.add_argument("--agent")
+    run_parser.add_argument("--model")
+    run_parser.add_argument("--session-id")
+    run_parser.add_argument("--title")
+    run_parser.add_argument("--tool", action="append", default=[])
+    run_parser.add_argument("--mcp", action="append", default=[])
+    run_parser.add_argument("--stream", action="store_true")
+    run_parser.add_argument("--async", dest="async_mode", action="store_true")
+
+    orchestration_parser = subparsers.add_parser("orchestrate", help="Run a multi-agent task")
+    orchestration_parser.add_argument("prompt")
+    orchestration_parser.add_argument("--strategy", default="plan-explore-build-review")
+    orchestration_parser.add_argument("--session-id")
+    orchestration_parser.add_argument("--title")
+    orchestration_parser.add_argument("--tool", action="append", default=[])
+    orchestration_parser.add_argument("--mcp", action="append", default=[])
+    orchestration_parser.add_argument("--parallel", action="store_true")
+
+    sessions_parser = subparsers.add_parser("sessions", help="Inspect sessions")
+    sessions_subparsers = sessions_parser.add_subparsers(dest="sessions_command", required=True)
+    sessions_subparsers.add_parser("list", help="List sessions")
+    status_parser = sessions_subparsers.add_parser("status", help="Show session status")
+    status_parser.add_argument("session_id", nargs="?")
+    abort_parser = sessions_subparsers.add_parser("abort", help="Abort a session")
+    abort_parser.add_argument("session_id")
+
+    tool_parser = subparsers.add_parser("tools", help="Inspect tools")
+    tool_parser.add_argument("--provider")
+    tool_parser.add_argument("--model")
+    tool_parser.add_argument("--ids", action="store_true")
+
+    mcp_parser = subparsers.add_parser("mcp", help="Inspect or register MCP servers")
+    mcp_subparsers = mcp_parser.add_subparsers(dest="mcp_command", required=True)
+    mcp_subparsers.add_parser("list", help="List MCP servers")
+    register_parser = mcp_subparsers.add_parser("register", help="Register an MCP server")
+    register_parser.add_argument("name")
+    register_parser.add_argument("config_json")
+
+    shell_parser = subparsers.add_parser("shell", help="Run a shell command inside a session")
+    shell_parser.add_argument("session_id")
+    shell_parser.add_argument("command_text")
+    shell_parser.add_argument("--agent")
+    shell_parser.add_argument("--model")
+
+    stream_parser = subparsers.add_parser("stream", help="Read SSE events")
+    stream_parser.add_argument("--limit", type=int, default=10)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    config = OpenCodeConfig.from_env()
+    if args.base_url:
+        config.base_url = args.base_url
+    if args.project_path:
+        config.project_path = args.project_path
+    if args.verbose:
+        config.verbose = True
+    configure_logging(config.verbose)
+    runtime = _build_runtime(config)
+    client: OpenCodeClient = runtime["client"]
+    try:
+        if args.command == "run":
+            if args.async_mode:
+                result = runtime["single"].run_async(
+                    args.prompt,
+                    agent=args.agent,
+                    model=args.model,
+                    session_id=args.session_id,
+                    title=args.title,
+                    tools=args.tool or None,
+                )
+                _print_json(result)
+                return 0
+            result = runtime["single"].run(
+                args.prompt,
+                agent=args.agent,
+                model=args.model,
+                session_id=args.session_id,
+                title=args.title,
+                tools=args.tool or None,
+                mcp_servers=args.mcp or None,
+                streaming=args.stream,
+            )
+            _print_json({"output": result.output, "metadata": result.metadata, "message": result.message})
+            return 0
+        if args.command == "orchestrate":
+            result = runtime["multi"].run(
+                args.prompt,
+                strategy=args.strategy,
+                session_id=args.session_id,
+                title=args.title,
+                tools=args.tool or None,
+                mcp_servers=args.mcp or None,
+                parallel=args.parallel,
+            )
+            _print_json(result)
+            return 0
+        if args.command == "sessions":
+            if args.sessions_command == "list":
+                _print_json(client.list_sessions())
+                return 0
+            if args.sessions_command == "status":
+                status = client.get_session_status()
+                if args.session_id:
+                    _print_json(status.get(args.session_id))
+                else:
+                    _print_json(status)
+                return 0
+            if args.sessions_command == "abort":
+                client.abort_session(args.session_id)
+                print(f"aborted {args.session_id}")
+                return 0
+        if args.command == "tools":
+            _print_json(client.list_tool_ids() if args.ids else client.list_tools(provider=args.provider, model=args.model))
+            return 0
+        if args.command == "mcp":
+            if args.mcp_command == "list":
+                _print_json(runtime["mcp_manager"].list_servers())
+                return 0
+            if args.mcp_command == "register":
+                _print_json(runtime["mcp_manager"].register(args.name, json.loads(args.config_json)))
+                return 0
+        if args.command == "shell":
+            result = runtime["single"].run_shell(args.command_text, session_id=args.session_id, agent=args.agent, model=args.model)
+            _print_json(result)
+            return 0
+        if args.command == "stream":
+            _print_json(runtime["event_streamer"].stream(limit=args.limit))
+            return 0
+        return 1
+    finally:
+        client.close()

opencode_agent/client.py

@@ -0,0 +1,331 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from .config import OpenCodeConfig
+from .exceptions import OpenCodeHTTPError
+from .models import AgentDefinition, MCPServer, Message, Session, SessionState, StreamEvent, ToolSchema
+
+
+def _normalize_tools(tools: list[str] | dict[str, Any] | None) -> dict[str, Any] | None:
+    if tools is None:
+        return None
+    if isinstance(tools, dict):
+        return tools
+    return {tool: True for tool in tools}
+
+
+def _normalize_model(model: str | dict[str, Any] | None) -> dict[str, Any] | None:
+    if model is None:
+        return None
+    if isinstance(model, dict):
+        return model
+    if "/" in model:
+        provider_id, model_id = model.split("/", 1)
+        return {"providerID": provider_id, "modelID": model_id}
+    return {"modelID": model}
+
+
+class OpenCodeClient:
+    def __init__(self, config: OpenCodeConfig | None = None, http_client: httpx.Client | None = None):
+        self.config = config or OpenCodeConfig.from_env()
+        self._client = http_client or httpx.Client(
+            base_url=self.config.base_url,
+            timeout=self.config.timeout_seconds,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        last_error: Exception | None = None
+        for attempt in range(1, self.config.retry_policy.attempts + 1):
+            try:
+                response = self._client.request(method, path, **kwargs)
+                if response.status_code >= 400:
+                    detail = response.text
+                    try:
+                        payload = response.json()
+                        detail = payload.get("error", detail)
+                    except json.JSONDecodeError:
+                        pass
+                    raise OpenCodeHTTPError(response.status_code, detail)
+                if response.status_code == 204:
+                    return None
+                if not response.content:
+                    return None
+                return response.json()
+            except (httpx.HTTPError, OpenCodeHTTPError) as exc:
+                last_error = exc
+                if attempt == self.config.retry_policy.attempts:
+                    raise
+                time.sleep(self.config.retry_policy.backoff_seconds * attempt)
+        if last_error:
+            raise last_error
+        return None
+
+    def list_sessions(self) -> list[Session]:
+        return [Session.from_dict(item) for item in self._request("GET", "/session")]
+
+    def create_session(self, title: str | None = None, parent_id: str | None = None) -> Session:
+        payload = {}
+        if title:
+            payload["title"] = title
+        if parent_id:
+            payload["parentID"] = parent_id
+        return Session.from_dict(self._request("POST", "/session", json=payload))
+
+    def get_session(self, session_id: str) -> Session:
+        return Session.from_dict(self._request("GET", f"/session/{session_id}"))
+
+    def update_session(self, session_id: str, **fields: Any) -> Session:
+        return Session.from_dict(self._request("PATCH", f"/session/{session_id}", json=fields))
+
+    def delete_session(self, session_id: str) -> None:
+        self._request("DELETE", f"/session/{session_id}")
+
+    def abort_session(self, session_id: str) -> None:
+        self._request("POST", f"/session/{session_id}/abort")
+
+    def fork_session(self, session_id: str, message_id: str | None = None) -> Session:
+        payload = {"messageID": message_id} if message_id else {}
+        return Session.from_dict(self._request("POST", f"/session/{session_id}/fork", json=payload))
+
+    def get_session_children(self, session_id: str) -> list[Session]:
+        return [Session.from_dict(item) for item in self._request("GET", f"/session/{session_id}/children")]
+
+    def get_session_todos(self, session_id: str) -> list[dict[str, Any]]:
+        return self._request("GET", f"/session/{session_id}/todo")
+
+    def get_session_status(self) -> dict[str, SessionState]:
+        payload = self._request("GET", "/session/status")
+        return {
+            session_id: SessionState(
+                session_id=session_id,
+                status=details.get("status", "unknown"),
+                active_form=details.get("activeForm"),
+            )
+            for session_id, details in payload.items()
+        }
+
+    def list_messages(self, session_id: str) -> list[Message]:
+        return [Message.from_dict(item) for item in self._request("GET", f"/session/{session_id}/message")]
+
+    def get_message(self, session_id: str, message_id: str) -> Message:
+        return Message.from_dict(self._request("GET", f"/session/{session_id}/message/{message_id}"))
+
+    def send_message(
+        self,
+        session_id: str,
+        prompt: str,
+        *,
+        agent: str | None = None,
+        model: str | dict[str, Any] | None = None,
+        tools: list[str] | dict[str, Any] | None = None,
+        system: str | None = None,
+        message_id: str | None = None,
+        attachments: list[str] | None = None,
+        no_reply: bool = False,
+    ) -> Message:
+        parts: list[dict[str, Any]] = [{"type": "text", "text": prompt}]
+        for attachment in attachments or []:
+            parts.append({"type": "attach", "path": attachment})
+        payload: dict[str, Any] = {"parts": parts, "noReply": no_reply}
+        if agent:
+            payload["agent"] = agent
+        normalized_model = _normalize_model(model)
+        if normalized_model:
+            payload["model"] = normalized_model
+        normalized_tools = _normalize_tools(tools)
+        if normalized_tools:
+            payload["tools"] = normalized_tools
+        if system:
+            payload["system"] = system
+        if message_id:
+            payload["messageID"] = message_id
+        return Message.from_dict(self._request("POST", f"/session/{session_id}/message", json=payload))
+
+    def prompt_async(
+        self,
+        session_id: str,
+        prompt: str,
+        *,
+        agent: str | None = None,
+        model: str | dict[str, Any] | None = None,
+        tools: list[str] | dict[str, Any] | None = None,
+    ) -> None:
+        payload: dict[str, Any] = {"parts": [{"type": "text", "text": prompt}]}
+        if agent:
+            payload["agent"] = agent
+        normalized_model = _normalize_model(model)
+        if normalized_model:
+            payload["model"] = normalized_model
+        normalized_tools = _normalize_tools(tools)
+        if normalized_tools:
+            payload["tools"] = normalized_tools
+        self._request("POST", f"/session/{session_id}/prompt_async", json=payload)
+
+    def run_command(self, session_id: str, command: str, arguments: dict[str, Any] | None = None) -> Any:
+        return self._request(
+            "POST",
+            f"/session/{session_id}/command",
+            json={"command": command, "arguments": arguments or {}},
+        )
+
+    def run_shell(
+        self,
+        session_id: str,
+        command: str,
+        *,
+        agent: str | None = None,
+        model: str | dict[str, Any] | None = None,
+    ) -> Message:
+        payload = {"command": command}
+        if agent:
+            payload["agent"] = agent
+        normalized_model = _normalize_model(model)
+        if normalized_model:
+            payload["model"] = normalized_model
+        return Message.from_dict(self._request("POST", f"/session/{session_id}/shell", json=payload))
+
+    def list_tool_ids(self) -> list[str]:
+        payload = self._request("GET", "/experimental/tool/ids")
+        if isinstance(payload, list):
+            return payload
+        return payload.get("ids", [])
+
+    def list_tools(self, provider: str | None = None, model: str | None = None) -> list[ToolSchema]:
+        params = {}
+        if provider:
+            params["provider"] = provider
+        if model:
+            params["model"] = model
+        payload = self._request("GET", "/experimental/tool", params=params)
+        return [
+            ToolSchema(
+                name=item["name"],
+                description=item.get("description"),
+                input_schema=item.get("inputSchema", {}),
+            )
+            for item in payload.get("tools", [])
+        ]
+
+    def list_files(self, path: str | None = None) -> Any:
+        # Always use the server-side project path; never fall back to os.getcwd()
+        server_path = path or self.config.project_path
+        if not server_path:
+            raise ValueError("path is required: set OPENCODE_PROJECT_PATH or pass path explicitly")
+        return self._request("GET", "/file", params={"path": server_path})
+
+    def get_file_content(self, path: str) -> Any:
+        # Paths are resolved server-side; send as-is. If relative, OpenCode resolves
+        # against the session's working directory on the server.
+        return self._request("GET", "/file/content", params={"path": path})
+
+    def get_file_status(self) -> Any:
+        return self._request("GET", "/file/status")
+
+    def find_files(
+        self,
+        query: str,
+        *,
+        item_type: str | None = None,
+        directory: str | None = None,
+        limit: int | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {"query": query}
+        if item_type:
+            params["type"] = item_type
+        # Use server-side project path; never resolve locally
+        server_dir = directory or self.config.project_path
+        if server_dir:
+            params["directory"] = server_dir
+        if limit is not None:
+            params["limit"] = limit
+        return self._request("GET", "/find/file", params=params)
+
+    def find_symbols(self, query: str) -> Any:
+        return self._request("GET", "/find/symbol", params={"query": query})
+
+    def search(self, pattern: str) -> Any:
+        return self._request("GET", "/find", params={"pattern": pattern})
+
+    def get_mcp_status(self) -> list[MCPServer]:
+        payload = self._request("GET", "/mcp")
+        return [
+            MCPServer(name=name, status=details.get("status"), tools=details.get("tools", []), raw=details)
+            for name, details in payload.items()
+        ]
+
+    def register_mcp_server(self, name: str, config: dict[str, Any]) -> Any:
+        return self._request("POST", "/mcp", json={"name": name, "config": config})
+
+    def list_commands(self) -> Any:
+        return self._request("GET", "/command")
+
+    def get_current_path(self) -> Any:
+        return self._request("GET", "/path")
+
+    def get_current_project(self) -> Any:
+        return self._request("GET", "/project/current")
+
+    def list_agents(self) -> list[AgentDefinition]:
+        return [
+            AgentDefinition(id=item["id"], name=item.get("name"), description=item.get("description"))
+            for item in self._request("GET", "/agent")
+        ]
+
+    def get_provider_config(self) -> dict[str, Any]:
+        return self._request("GET", "/config/providers")
+
+    def list_available_models(self, include_details: bool = False) -> list[Any]:
+        payload = self.get_provider_config()
+        models: list[Any] = []
+        for provider in payload.get("providers", []):
+            if not self._provider_is_ready(provider):
+                continue
+            provider_id = provider.get("id", "")
+            for model_id, details in provider.get("models", {}).items():
+                model_ref = f"{provider_id}/{model_id}"
+                if include_details:
+                    models.append(
+                        {
+                            "provider": provider_id,
+                            "model": model_id,
+                            "ref": model_ref,
+                            "name": details.get("name", model_id),
+                            "status": details.get("status"),
+                            "context_window": details.get("limit", {}).get("context"),
+                            "raw": details,
+                        }
+                    )
+                else:
+                    models.append(model_ref)
+        return models
+
+    @staticmethod
+    def _provider_is_ready(provider: dict[str, Any]) -> bool:
+        env_keys = provider.get("env", [])
+        options = provider.get("options", {})
+        api_key = options.get("apiKey")
+        if isinstance(api_key, str) and api_key.strip():
+            return True
+        if env_keys and all(os.getenv(key) for key in env_keys):
+            return True
+        return not env_keys
+
+    def iter_events(self) -> Iterator[StreamEvent]:
+        with self._client.stream("GET", "/event", headers={"Accept": "text/event-stream"}) as response:
+            response.raise_for_status()
+            for line in response.iter_lines():
+                if not line:
+                    continue
+                if line.startswith("data:"):
+                    payload = json.loads(line[5:].strip())
+                    yield StreamEvent(type=payload.get("type", "message"), payload=payload.get("payload", {}))