opencode-runtime 0.4.0__py3-none-any.whl

opencode_runtime/__init__.py

@@ -0,0 +1,17 @@
+"""
+opencode-runtime: runtime infrastructure for multi-user OpenCode deployments.
+"""
+
+__version__ = "0.4.0"
+
+from .event import OpenCodeEvent
+from .runtime import OpenCodeRuntime
+from .response import OpenCodeResponse
+from .session import OpenCodeSession
+
+__all__ = [
+    "OpenCodeRuntime",
+    "OpenCodeSession",
+    "OpenCodeEvent",
+    "OpenCodeResponse",
+]

opencode_runtime/cli.py

@@ -0,0 +1,299 @@
+"""
+CLI entry point for opencode-runtime instance management.
+
+Commands:
+    serve       Start an OpenCode instance (detached)
+    ps          List all instances tracked in the registry
+    stop        Stop an instance by key
+    stop-all    Stop all tracked instances
+    health      Check health of an instance by key
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .server import ServerManager, _compute_runtime_key
+
+# ---------------------------------------------------------------------------
+# ANSI
+# ---------------------------------------------------------------------------
+
+_R = "\033[0m"
+
+
+def _green(s: str) -> str:
+    return f"\033[32m{s}{_R}"
+
+
+def _yellow(s: str) -> str:
+    return f"\033[33m{s}{_R}"
+
+
+def _red(s: str) -> str:
+    return f"\033[31m{s}{_R}"
+
+
+def _cyan(s: str) -> str:
+    return f"\033[36m{s}{_R}"
+
+
+def _dim(s: str) -> str:
+    return f"\033[2m{s}{_R}"
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+
+def _home(path: str) -> str:
+    try:
+        return "~/" + str(Path(path).relative_to(Path.home()))
+    except ValueError:
+        return path
+
+
+def _uptime(started_at: str, alive: bool) -> str:
+    try:
+        mins = max(
+            0,
+            int(
+                (datetime.now(timezone.utc) - datetime.fromisoformat(started_at)).total_seconds()
+                // 60
+            ),
+        )
+    except Exception:
+        return "?"
+    return f"Up {mins}m" if alive else f"Dead {mins}m"
+
+
+def _row(label: str, value: str) -> None:
+    print(f"  {_cyan(f'{label:<9}')}  {value}")
+
+
+# ---------------------------------------------------------------------------
+# serve
+# ---------------------------------------------------------------------------
+
+
+async def _serve(args: argparse.Namespace) -> None:
+    project_dir = Path(args.project_dir).resolve()
+    runtime_dir = Path(args.runtime_dir).resolve() if args.runtime_dir else None
+    materials = args.materials or None
+
+    key = _compute_runtime_key(
+        workspace=args.workspace,
+        user_id=args.user_id,
+        project_dir=project_dir,
+        materials=materials,
+        config={},
+    )
+
+    manager = ServerManager()
+
+    existing = manager.find(key)
+    if existing is not None:
+        if manager.is_alive(key):
+            sys.exit(
+                _yellow(f"● Server already running  id={existing.key}  pid={existing.pid}\n")
+                + _dim(f"  use: opencode-runtime stop {existing.key}")
+            )
+
+    server_dir: Path | None = None
+    if runtime_dir is not None:
+        server_dir = runtime_dir / "servers" / key
+
+    print(_yellow("● Starting opencode server..."), flush=True)
+
+    server = await manager.get_or_start(
+        key=key,
+        project_dir=project_dir,
+        server_dir=server_dir,
+        materials=materials,
+        config={},
+        env={},
+        workspace=args.workspace,
+        user_id=args.user_id,
+    )
+
+    entry = manager.find(key)
+    assert entry is not None
+
+    print(f"\r{_green('✓ Server started')}\n")
+    _row("ID", key)
+    if args.workspace:
+        _row("Workspace", args.workspace)
+    if args.user_id:
+        _row("User", args.user_id)
+    _row("Status", _green("● alive"))
+    _row("URL", server.client.base_url)
+    _row("PID", _dim(str(entry.pid)))
+    _row("Project", _dim(_home(str(project_dir))))
+    print()
+    print(_dim(f"  opencode-runtime health {key}"))
+    print(_dim(f"  opencode-runtime stop   {key}"))
+
+
+def cmd_serve(args: argparse.Namespace) -> None:
+    try:
+        asyncio.run(_serve(args))
+    except KeyboardInterrupt:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# ps
+# ---------------------------------------------------------------------------
+
+
+def cmd_ps(_args: argparse.Namespace) -> None:
+    entries = ServerManager().list()
+    show_workspace = any(e.workspace for e, _ in entries)
+    show_user = any(e.user_id for e, _ in entries)
+
+    cols = ["  {:<18}", "{:>6}", "{:>6}", "{:<7}", "{:>8}"]
+    headers = ["ID", "PID", "PORT", "STATUS", "UPTIME"]
+    if show_workspace:
+        cols.append("{:<12}")
+        headers.append("WORKSPACE")
+    if show_user:
+        cols.append("{:<12}")
+        headers.append("USER")
+    cols.append("{}")
+    headers.append("PROJECT")
+    fmt = "  ".join(cols)
+
+    print(_cyan(fmt.format(*headers)))
+    print(_dim("  " + "─" * (70 + 14 * show_workspace + 14 * show_user)))
+
+    for e, alive in entries:
+        status_plain = "● alive" if alive else "● dead"
+        status_coloured = _green(status_plain) if alive else _red(status_plain)
+        vals = [e.key, str(e.pid), str(e.port), status_plain, _uptime(e.started_at, alive)]
+        if show_workspace:
+            vals.append(e.workspace or "-")
+        if show_user:
+            vals.append(e.user_id or "-")
+        vals.append(_home(e.project_dir))
+        row = fmt.format(*vals)
+        row = row.replace(status_plain, status_coloured, 1)
+        print(_dim(row).replace(_dim(status_coloured), status_coloured, 1))
+
+
+# ---------------------------------------------------------------------------
+# stop
+# ---------------------------------------------------------------------------
+
+
+def cmd_stop(args: argparse.Namespace) -> None:
+    manager = ServerManager()
+    entry = manager.find(args.key)
+    if entry is None:
+        sys.exit(_red(f"✗ ID {args.key!r} not found in registry"))
+
+    was_alive = asyncio.run(manager.stop(args.key))
+    if not was_alive:
+        print(_yellow(f"  ● process {entry.pid} was already dead"))
+
+    print(f"{_green('✓ Server stopped')}\n")
+    _row("ID", entry.key)
+    _row("PID", _dim(str(entry.pid)))
+
+
+# ---------------------------------------------------------------------------
+# stop-all
+# ---------------------------------------------------------------------------
+
+
+def cmd_stop_all(_args: argparse.Namespace) -> None:
+    manager = ServerManager()
+    entries = manager.list()
+    if not entries:
+        print(_dim("  no servers running"))
+        return
+
+    asyncio.run(manager.stop_all())
+
+    print(f"{_green(f'✓ Stopped {len(entries)} server(s)')}\n")
+    for e, _ in entries:
+        print(f"  {_dim(e.key)}   {_dim(f'pid {e.pid}')}")
+
+
+# ---------------------------------------------------------------------------
+# health
+# ---------------------------------------------------------------------------
+
+
+def cmd_health(args: argparse.Namespace) -> None:
+    from .exceptions import OpenCodeServerError
+
+    manager = ServerManager()
+    entry = manager.find(args.key)
+    if entry is None:
+        sys.exit(_red(f"✗ ID {args.key!r} not found in registry"))
+
+    url = f"http://127.0.0.1:{entry.port}"
+    try:
+        result = asyncio.run(manager.health(args.key))
+        version = result.get("version")
+        print(_green("✓ healthy") + f"   {_dim(f'version {version}')}" + f"   {_dim(url)}")
+    except OpenCodeServerError as exc:
+        sys.exit(_red(f"✗ unreachable   {url}\n  {exc}"))
+
+
+# ---------------------------------------------------------------------------
+# main
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="opencode-runtime", description="Manage OpenCode instance processes."
+    )
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    p = sub.add_parser("serve", help="start an opencode server (detached)")
+    p.add_argument(
+        "--project-dir", default=".", metavar="DIR", help="project directory (default: .)"
+    )
+    p.add_argument(
+        "--runtime-dir", default=None, metavar="DIR", help="isolated runtime directory (optional)"
+    )
+    p.add_argument(
+        "--materials",
+        action="append",
+        metavar="PATH",
+        help="materials path(s) to overlay (repeatable)",
+    )
+    p.add_argument(
+        "--workspace", default=None, metavar="NAME", help="tenant workspace identifier (optional)"
+    )
+    p.add_argument("--user-id", default=None, metavar="ID", help="user identifier (optional)")
+    p.set_defaults(func=cmd_serve)
+
+    p = sub.add_parser("ps", help="list tracked servers")
+    p.set_defaults(func=cmd_ps)
+
+    p = sub.add_parser("stop", help="stop a server by id")
+    p.add_argument("key", help="server id (from ps)")
+    p.set_defaults(func=cmd_stop)
+
+    p = sub.add_parser("stop-all", help="stop all tracked servers")
+    p.set_defaults(func=cmd_stop_all)
+
+    p = sub.add_parser("health", help="check health of a server by id")
+    p.add_argument("key", help="server id (from ps)")
+    p.set_defaults(func=cmd_health)
+
+    if len(sys.argv) == 1:
+        parser.print_help()
+        sys.exit(0)
+
+    args = parser.parse_args()
+    args.func(args)

opencode_runtime/client.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import base64
+import json
+import typing as t
+
+import httpx
+
+from .event import OpenCodeEvent
+from .exceptions import OpenCodeServerError, OpenCodeTimeoutError
+
+
+class OpenCodeClient:
+    """Minimal HTTP/SSE client for the OpenCode server.
+
+    Covers only what the runtime needs to function:
+    - health check
+    - fire-and-forget message send
+    - SSE event stream
+
+    For anything else use the ``get()`` / ``post()`` escape hatches directly
+    against the OpenCode REST API (see https://opencode.ai/docs/server).
+
+    Args:
+        base_url:  Base URL of the running opencode server,
+                   e.g. ``"http://127.0.0.1:4096"``.
+        password:  Value of ``OPENCODE_SERVER_PASSWORD``. Sent as
+                   ``Authorization: Bearer <password>`` when set.
+        timeout:   Default request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        password: str | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.password = password
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------
+    # Escape hatches — use these for any endpoint not covered below
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {"Accept": "application/json"}
+        if self.password:
+            # OpenCode uses HTTP Basic auth: username "opencode", password is the token
+            credentials = base64.b64encode(f"opencode:{self.password}".encode()).decode()
+            headers["Authorization"] = f"Basic {credentials}"
+        return headers
+
+    def _http(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+
+    async def get(self, path: str) -> t.Any:
+        """GET any OpenCode server endpoint. Returns parsed JSON."""
+        async with self._http() as http:
+            try:
+                r = await http.get(path)
+                r.raise_for_status()
+                return r.json()
+            except httpx.TimeoutException as exc:
+                raise OpenCodeTimeoutError(f"GET {path} timed out") from exc
+            except httpx.HTTPStatusError as exc:
+                raise OpenCodeServerError(
+                    f"GET {path} returned {exc.response.status_code}"
+                ) from exc
+
+    async def post(self, path: str, body: dict[str, t.Any]) -> t.Any:
+        """POST any OpenCode server endpoint. Returns parsed JSON."""
+        async with self._http() as http:
+            try:
+                r = await http.post(path, json=body)
+                r.raise_for_status()
+                return r.json()
+            except httpx.TimeoutException as exc:
+                raise OpenCodeTimeoutError(f"POST {path} timed out") from exc
+            except httpx.HTTPStatusError as exc:
+                raise OpenCodeServerError(
+                    f"POST {path} returned {exc.response.status_code}"
+                ) from exc
+
+    # ------------------------------------------------------------------
+    # The three things the runtime actually needs
+    # ------------------------------------------------------------------
+
+    async def health(self) -> dict[str, t.Any]:
+        """GET /global/health → ``{"healthy": true, "version": "..."}``."""
+        return await self.get("/global/health")
+
+    async def send(
+        self,
+        session_id: str,
+        message: str,
+        *,
+        model: str | None = None,
+        agent: str | None = None,
+        tools: dict[str, bool] | None = None,
+        system: str | None = None,
+    ) -> None:
+        """POST /session/:id/prompt_async — non-blocking message send.
+
+        Returns immediately. Events arrive on :meth:`events`.
+
+        ``model`` accepts either a ``"providerID/modelID"`` shorthand string
+        or a raw ``{"providerID": ..., "modelID": ...}`` dict.
+        """
+        parts: list[dict[str, t.Any]] = [{"type": "text", "text": message}]
+        body: dict[str, t.Any] = {"parts": parts}
+
+        if model is not None:
+            if isinstance(model, str) and "/" in model:
+                provider_id, model_id = model.split("/", 1)
+                body["model"] = {"providerID": provider_id, "modelID": model_id}
+            else:
+                body["model"] = model
+        if agent is not None:
+            body["agent"] = agent
+        if tools is not None:
+            body["tools"] = tools
+        if system is not None:
+            body["system"] = system
+
+        async with self._http() as http:
+            try:
+                r = await http.post(f"/session/{session_id}/prompt_async", json=body)
+                if r.status_code not in (200, 204):
+                    r.raise_for_status()
+            except httpx.TimeoutException as exc:
+                raise OpenCodeTimeoutError("send timed out") from exc
+            except httpx.HTTPStatusError as exc:
+                raise OpenCodeServerError(f"send returned {exc.response.status_code}") from exc
+
+    async def events(self, session_id: str) -> t.AsyncIterator[OpenCodeEvent]:
+        """GET /global/event — SSE bus filtered to ``session_id``.
+
+        Yields every :class:`~opencode_runtime.event.OpenCodeEvent` that
+        OpenCode emits for this session and terminates on a terminal event.
+
+        The runtime does **no interpretation** — all events are forwarded as-is
+        so callers can handle whatever OpenCode emits (text deltas, tool calls,
+        thinking, permission requests, status updates, etc.).
+
+        Common event types emitted by OpenCode:
+
+        * ``message.part.delta`` — incremental token; ``event.text`` is the
+          delta string when ``properties.field == "text"``.
+        * ``message.part.updated`` — full part snapshot (text, tool, thinking,
+          …); ``event.text`` is the text content when ``part.type == "text"``.
+        * ``session.status`` — status change (e.g. ``{type: "running"}``).
+        * ``session.idle`` — terminal; model finished.
+        * ``session.error`` — terminal; something went wrong.
+        * ``permission.asked`` — tool permission request; caller must handle.
+
+        Only ``sync`` bus-noise events are suppressed.
+        """
+        async with self._http() as http:
+            async with http.stream("GET", "/global/event") as r:
+                try:
+                    r.raise_for_status()
+                except httpx.HTTPStatusError as exc:
+                    raise OpenCodeServerError(
+                        f"SSE /global/event returned {exc.response.status_code}"
+                    ) from exc
+
+                async for line in r.aiter_lines():
+                    line = line.strip()
+
+                    if not line.startswith("data:"):
+                        continue
+
+                    raw_data = line[len("data:") :].strip()
+                    if not raw_data:
+                        continue
+
+                    try:
+                        envelope = json.loads(raw_data)
+                    except json.JSONDecodeError:
+                        continue
+
+                    # /global/event wraps each event: {"payload": {"type": ..., "properties": ...}}
+                    payload = envelope.get("payload", {})
+                    if not isinstance(payload, dict):
+                        continue
+
+                    event_type = payload.get("type", "")
+
+                    # Suppress internal bus noise — never useful to callers.
+                    if event_type == "sync":
+                        continue
+
+                    props = payload.get("properties", {})
+                    if not isinstance(props, dict):
+                        props = {}
+
+                    # Filter to this session (events without sessionID are global, pass through)
+                    sid = props.get("sessionID")
+                    if sid is not None and sid != session_id:
+                        continue
+
+                    # Derive a convenience text field where it naturally exists,
+                    # so callers don't have to dig into raw for the common case.
+                    text: str | None = None
+                    if event_type == "message.part.delta" and props.get("field") == "text":
+                        text = props.get("delta") or None
+                    elif event_type == "message.part.updated":
+                        part = props.get("part") or {}
+                        if isinstance(part, dict) and part.get("type") == "text":
+                            text = part.get("text") or None
+
+                    yield OpenCodeEvent(type=event_type, text=text, raw=payload)
+
+                    # Terminal events — stop iterating after yielding.
+                    if event_type == "session.idle":
+                        return
+                    if event_type == "session.error":
+                        return
+                    if event_type == "session.status":
+                        status = props.get("status", {})
+                        if isinstance(status, dict) and status.get("type") == "idle":
+                            return

opencode_runtime/event.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class OpenCodeEvent:
+    """A normalized event from the OpenCode server SSE stream.
+
+    Attributes:
+        type:  Event type string, e.g. "message.delta", "message.completed",
+               "session.error". Mirrors the OpenCode bus event types.
+        text:  Text content for message.delta events; None for other types.
+        raw:   The raw event payload from the server. Use this escape hatch
+               when you need fields beyond type and text.
+    """
+
+    type: str
+    text: str | None = None
+    raw: Any = None
+
+    def to_sse(self) -> str:
+        """Format as a Server-Sent Events string suitable for HTTP streaming."""
+        data = self.text or ""
+        return f"event: {self.type}\ndata: {data}\n\n"

opencode_runtime/exceptions.py

@@ -0,0 +1,14 @@
+class OpenCodeRuntimeError(Exception):
+    """Base class for all opencode-runtime errors."""
+
+
+class OpenCodeNotFoundError(OpenCodeRuntimeError):
+    """Raised when the opencode binary cannot be found on PATH."""
+
+
+class OpenCodeServerError(OpenCodeRuntimeError):
+    """Raised when the opencode server fails to start or returns an error."""
+
+
+class OpenCodeTimeoutError(OpenCodeRuntimeError):
+    """Raised when a health check or request exceeds the allowed timeout."""

opencode_runtime/registry.py

@@ -0,0 +1,84 @@
+"""
+Registry for tracking OpenCode instance processes.
+
+Each running instance is represented by a JSON file at:
+    ~/.opencode-runtime/servers/<key>.json
+
+Used by both the CLI (opencode-runtime serve/ps/stop) and the library
+(OpenCodeRuntime) — the registry is the shared source of truth for all
+running instances regardless of how they were started.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+REGISTRY_DIR = Path.home() / ".opencode-runtime" / "servers"
+
+
+@dataclass
+class RegistryEntry:
+    key: str
+    pid: int
+    port: int
+    password: str
+    project_dir: str
+    server_dir: str | None
+    started_at: str  # ISO-8601
+    workspace: str | None = None
+    user_id: str | None = None
+
+
+def write(entry: RegistryEntry) -> None:
+    """Write a registry entry to disk. File is chmod 0o600."""
+    REGISTRY_DIR.mkdir(parents=True, exist_ok=True)
+    path = REGISTRY_DIR / f"{entry.key}.json"
+    path.write_text(json.dumps(asdict(entry), indent=2), encoding="utf-8")
+    path.chmod(0o600)
+
+
+def read(key: str) -> RegistryEntry | None:
+    """Read a registry entry by key. Returns None if not found."""
+    path = REGISTRY_DIR / f"{key}.json"
+    if not path.exists():
+        return None
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return RegistryEntry(**data)
+
+
+def delete(key: str) -> None:
+    """Remove a registry entry. No-op if not found."""
+    path = REGISTRY_DIR / f"{key}.json"
+    path.unlink(missing_ok=True)
+
+
+def list_all() -> list[RegistryEntry]:
+    """Return all registry entries on disk."""
+    if not REGISTRY_DIR.exists():
+        return []
+    entries = []
+    for path in REGISTRY_DIR.glob("*.json"):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            entries.append(RegistryEntry(**data))
+        except Exception:
+            pass
+    return entries
+
+
+def is_alive(pid: int) -> bool:
+    """Return True if a process with this PID is running."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, PermissionError):
+        return False
+
+
+def now_iso() -> str:
+    """Return current UTC time as ISO-8601 string."""
+    return datetime.now(timezone.utc).isoformat()

opencode_runtime/response.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class OpenCodeResponse:
+    """Collected response from a completed ask() call.
+
+    Attributes:
+        text:  Full assistant text, concatenated from all message.delta events.
+        raw:   List of raw event objects received during the session, in order.
+               Use this as an escape hatch when you need parts beyond plain text.
+    """
+
+    text: str
+    raw: list[Any] = field(default_factory=list)