opencode-agent 0.1.0__py3-none-any.whl

opencode_agent/orchestrator.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import logging
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from typing import Any
+
+from .client import OpenCodeClient
+from .config import OpenCodeConfig
+from .logging import log_event
+from .managers import MCPManager, SessionManager, ToolManager
+from .models import ExecutionMetadata, ExecutionResult, MultiAgentResult, StreamEvent, SubtaskTrace
+
+
+@dataclass(slots=True)
+class PlannedStep:
+    name: str
+    agent: str
+    prompt_template: str
+    fork_session: bool = True
+
+
+class TaskPlanner:
+    def __init__(self, config: OpenCodeConfig | None = None):
+        self.config = config or OpenCodeConfig.from_env()
+
+    def plan(self, prompt: str, strategy: str = "plan-explore-build-review") -> list[PlannedStep]:
+        if strategy == "coordinator-specialists-synthesizer":
+            return [
+                PlannedStep("coordinator", "plan", "Define the execution approach for this task and call out major workstreams:\n\n{prompt}", False),
+                PlannedStep("specialist-build", "build", "Implement the most important technical solution for this task:\n\n{prompt}"),
+                PlannedStep("specialist-explore", "explore", "Inspect risks, dependencies, and supporting context for this task:\n\n{prompt}"),
+                PlannedStep("synthesizer", "build", "Synthesize the specialist outputs into one actionable final result for:\n\n{prompt}", False),
+            ]
+        return [
+            PlannedStep("plan", "plan", "Create a concise execution plan for this task:\n\n{prompt}", False),
+            PlannedStep("explore", "explore", "Explore the workspace and relevant context for this task:\n\n{prompt}"),
+            PlannedStep("build", "build", "Execute the implementation work for this task:\n\n{prompt}"),
+            PlannedStep("review", "plan", "Review the implementation critically and summarize remaining risks for:\n\n{prompt}", False),
+        ]
+
+
+class EventStreamer:
+    def __init__(self, client: OpenCodeClient):
+        self.client = client
+
+    def stream(self, limit: int | None = None) -> list[StreamEvent]:
+        events: list[StreamEvent] = []
+        for event in self.client.iter_events():
+            events.append(event)
+            if limit is not None and len(events) >= limit:
+                break
+        return events
+
+
+class SingleAgentRunner:
+    def __init__(
+        self,
+        client: OpenCodeClient | None = None,
+        config: OpenCodeConfig | None = None,
+        session_manager: SessionManager | None = None,
+        tool_manager: ToolManager | None = None,
+        mcp_manager: MCPManager | None = None,
+    ):
+        self.config = config or OpenCodeConfig.from_env()
+        self.client = client or OpenCodeClient(self.config)
+        self.session_manager = session_manager or SessionManager(self.client)
+        self.tool_manager = tool_manager or ToolManager(self.client)
+        self.mcp_manager = mcp_manager or MCPManager(self.client)
+        self.logger = logging.getLogger(__name__)
+
+    def _scoped_prompt(self, prompt: str) -> str:
+        """
+        Prepend project path context so the OpenCode server agent knows which
+        directory to operate in.  All file/terminal operations are executed on
+        the OpenCode server—not on the Python client machine.
+        """
+        lines = [
+            f"Project path (on the OpenCode server): {self.config.project_path}",
+            "All file reads/writes, terminal commands, and tool calls must target",
+            "this path on the OpenCode server. Do NOT reference paths on the client.",
+            "",
+            prompt,
+        ]
+        return "\n".join(lines)
+
+    def run(
+        self,
+        prompt: str,
+        *,
+        agent: str | None = None,
+        model: str | None = None,
+        session_id: str | None = None,
+        title: str | None = None,
+        tools: list[str] | None = None,
+        mcp_servers: list[str] | None = None,
+        streaming: bool | None = None,
+        system: str | None = None,
+        attachments: list[str] | None = None,
+    ) -> ExecutionResult:
+        task_id = f"task_{uuid.uuid4().hex[:12]}"
+        session = self.session_manager.reuse_or_create(task_id, session_id=session_id, title=title or prompt[:80])
+        requested_tools = tools if tools is not None else self.config.default_tools
+        resolved_tools = self.tool_manager.resolve_allowlist(requested_tools) if requested_tools else None
+        logs: list[dict[str, Any]] = []
+
+        if mcp_servers:
+            servers = self.mcp_manager.ensure_servers(mcp_servers, self.config.mcp_servers)
+            logs.append({"event": "mcp.ready", "servers": [server.name for server in servers]})
+
+        streaming_enabled = streaming if streaming is not None else self.config.streaming
+        if streaming_enabled:
+            logs.append({"event": "streaming.enabled", "session_id": session.id})
+
+        selected_agent = agent or self.config.default_agent
+        log_event(self.logger, "task.run", task_id=task_id, session_id=session.id, agent=selected_agent)
+        scoped_prompt = self._scoped_prompt(prompt)
+        message = self.client.send_message(
+            session.id,
+            scoped_prompt,
+            agent=selected_agent,
+            model=model or self.config.default_model,
+            tools=resolved_tools,
+            system=system,
+            attachments=attachments,
+        )
+        logs.append({"event": "message.completed", "message_id": message.info.id})
+        metadata = ExecutionMetadata(
+            task_id=task_id,
+            session_id=session.id,
+            agent=selected_agent,
+            status="completed",
+            message_id=message.info.id,
+            tool_events=message.tool_events,
+            logs=logs,
+        )
+        return ExecutionResult(output=message.text_output, metadata=metadata, message=message)
+
+    def run_async(
+        self,
+        prompt: str,
+        *,
+        agent: str | None = None,
+        model: str | None = None,
+        session_id: str | None = None,
+        title: str | None = None,
+        tools: list[str] | None = None,
+    ) -> ExecutionMetadata:
+        task_id = f"task_{uuid.uuid4().hex[:12]}"
+        session = self.session_manager.reuse_or_create(task_id, session_id=session_id, title=title or prompt[:80])
+        requested_tools = tools if tools is not None else self.config.default_tools
+        resolved_tools = self.tool_manager.resolve_allowlist(requested_tools) if requested_tools else None
+        selected_agent = agent or self.config.default_agent
+        scoped_prompt = self._scoped_prompt(prompt)
+        self.client.prompt_async(
+            session.id,
+            scoped_prompt,
+            agent=selected_agent,
+            model=model or self.config.default_model,
+            tools=resolved_tools,
+        )
+        return ExecutionMetadata(task_id=task_id, session_id=session.id, agent=selected_agent, status="submitted")
+
+    def run_shell(
+        self,
+        command: str,
+        *,
+        session_id: str,
+        agent: str | None = None,
+        model: str | None = None,
+    ) -> ExecutionResult:
+        # Send the command directly to the OpenCode server shell.
+        # The server session already has the correct working directory.
+        # We intentionally do NOT prepend `cd {client_path}` because that
+        # would inject a client-side filesystem path into a server-side shell.
+        message = self.client.run_shell(
+            session_id,
+            command,
+            agent=agent or self.config.default_agent,
+            model=model or self.config.default_model,
+        )
+        metadata = ExecutionMetadata(
+            task_id=f"shell_{uuid.uuid4().hex[:12]}",
+            session_id=session_id,
+            agent=agent or self.config.default_agent,
+            status="completed",
+            message_id=message.info.id,
+            tool_events=message.tool_events,
+            logs=[{"event": "shell.completed", "command": command}],
+        )
+        return ExecutionResult(output=message.text_output, metadata=metadata, message=message)
+
+
+class ResultSynthesizer:
+    def synthesize(self, prompt: str, traces: list[SubtaskTrace]) -> str:
+        sections = [f"Parent objective: {prompt}", "Subtask results:"]
+        for trace in traces:
+            sections.append(f"[{trace.agent}] {trace.output}".strip())
+        return "\n\n".join(sections)
+
+
+class MultiAgentRunner:
+    def __init__(
+        self,
+        client: OpenCodeClient | None = None,
+        config: OpenCodeConfig | None = None,
+        session_manager: SessionManager | None = None,
+        tool_manager: ToolManager | None = None,
+        mcp_manager: MCPManager | None = None,
+        planner: TaskPlanner | None = None,
+        synthesizer: ResultSynthesizer | None = None,
+    ):
+        self.config = config or OpenCodeConfig.from_env()
+        self.client = client or OpenCodeClient(self.config)
+        self.session_manager = session_manager or SessionManager(self.client)
+        self.tool_manager = tool_manager or ToolManager(self.client)
+        self.mcp_manager = mcp_manager or MCPManager(self.client)
+        self.planner = planner or TaskPlanner(self.config)
+        self.synthesizer = synthesizer or ResultSynthesizer()
+        self.single_runner = SingleAgentRunner(
+            client=self.client,
+            config=self.config,
+            session_manager=self.session_manager,
+            tool_manager=self.tool_manager,
+            mcp_manager=self.mcp_manager,
+        )
+
+    def run(
+        self,
+        prompt: str,
+        *,
+        strategy: str = "plan-explore-build-review",
+        session_id: str | None = None,
+        title: str | None = None,
+        tools: list[str] | None = None,
+        mcp_servers: list[str] | None = None,
+        parallel: bool = False,
+    ) -> MultiAgentResult:
+        parent_task_id = f"task_{uuid.uuid4().hex[:12]}"
+        parent_session = self.session_manager.reuse_or_create(parent_task_id, session_id=session_id, title=title or prompt[:80])
+        if mcp_servers:
+            self.mcp_manager.ensure_servers(mcp_servers, self.config.mcp_servers)
+
+        steps = self.planner.plan(prompt, strategy=strategy)
+        traces: list[SubtaskTrace] = []
+
+        def execute_step(index: int, step: PlannedStep) -> SubtaskTrace:
+            child_task_id = f"{parent_task_id}_{index}_{step.name}"
+            child_session = parent_session
+            if step.fork_session:
+                child_session = self.session_manager.fork(parent_task_id, child_task_id)
+            else:
+                self.session_manager.link_existing(
+                    child_task_id,
+                    session_id=parent_session.id,
+                    title=parent_session.title,
+                )
+            result = self.single_runner.run(
+                step.prompt_template.format(prompt=prompt),
+                agent=step.agent,
+                session_id=child_session.id,
+                tools=tools,
+                title=f"{step.name}: {prompt[:48]}",
+            )
+            return SubtaskTrace(
+                task_id=result.metadata.task_id,
+                session_id=result.metadata.session_id,
+                agent=result.metadata.agent,
+                prompt=step.prompt_template.format(prompt=prompt),
+                output=result.output,
+                message_id=result.metadata.message_id,
+                status=result.metadata.status,
+            )
+
+        if parallel:
+            with ThreadPoolExecutor(max_workers=min(4, len(steps))) as executor:
+                futures = [executor.submit(execute_step, index, step) for index, step in enumerate(steps, start=1)]
+                for future in futures:
+                    traces.append(future.result())
+        else:
+            for index, step in enumerate(steps, start=1):
+                traces.append(execute_step(index, step))
+
+        output = self.synthesizer.synthesize(prompt, traces)
+        metadata = ExecutionMetadata(
+            task_id=parent_task_id,
+            session_id=parent_session.id,
+            agent="multi-agent",
+            status="completed",
+            logs=[{"event": "multi-agent.completed", "strategy": strategy, "subtasks": len(traces)}],
+        )
+        return MultiAgentResult(output=output, metadata=metadata, trace=traces)

opencode_agent-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+opencode_agent/__init__.py,sha256=KuVnubVdN-SE9AqcCqM9T7ayePSQ74oBovqjYWlmVWI,590
+opencode_agent/agent.py,sha256=z4zEPiCTVXRoBVj3Z1PZ0YYUD_-UumZ9MQmQVRMiMG8,4637
+opencode_agent/cli.py,sha256=RFGEX26snm3mU19J4LsoQgmz47OKbRL87ljbstEbxbs,7835
+opencode_agent/client.py,sha256=nPZLkKa6O0oihxl9BWCxWYJY3s3iRtQcF1AUA-v8GW8,13048
+opencode_agent/config.py,sha256=Xzu3faOd6M8Kf3Uc8B2EM3WmGc8V8aZDmhofShAOmFQ,4221
+opencode_agent/exceptions.py,sha256=kAaHM6cot9lFol5OrEG5wG1NQhZZFtNrJ5uOlcUk-14,784
+opencode_agent/logging.py,sha256=1yrzN3QU_iQWfhK9M2_q0PWUxIHjtWsZagpMagm3unk,408
+opencode_agent/managers.py,sha256=NF3a4CdGwYS51R_bFoXxi8Nq-v77WEHTcspZo4V4X7o,6184
+opencode_agent/models.py,sha256=K1yeYTslWdHK0TBsoiNqoZAmLiGQ2c6d1kuDUWgqm0g,3163
+opencode_agent/orchestrator.py,sha256=uSsMDmB3dbDlWHuBPgNNI3cpc6N5iXh_O80pg43Hqpc,12385
+opencode_agent-0.1.0.dist-info/METADATA,sha256=-TsGuZjp0nhygno0p9FMjKItWH-jGXGvOp0Wvf0KwZs,5129
+opencode_agent-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+opencode_agent-0.1.0.dist-info/entry_points.txt,sha256=SIrL2cWr0YQePT9AwQ0qsIU-wniX1BP8QZo8NJi-X_A,59
+opencode_agent-0.1.0.dist-info/top_level.txt,sha256=wkQW9W5NQ66pKpNwD3D9bhlPZxRToDX_IXrIdz2ss08,15
+opencode_agent-0.1.0.dist-info/RECORD,,

opencode_agent-0.1.0.dist-info/WHEEL

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

opencode_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+opencode-agent = opencode_agent.cli:main

opencode_agent-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+opencode_agent