opencode-talk-bridge 0.2.7__py3-none-any.whl

opencode_talk_bridge/opencode.py

@@ -0,0 +1,418 @@
+"""HTTP + SSE client for a local ``opencode serve`` instance.
+
+Verified against the OpenAPI of OpenCode 1.15.11 (``GET /doc``). Routes are
+session-level (not project-scoped) and the permission flow is global:
+
+  - ``GET  /global/health``                     -> {healthy, version}
+  - ``GET  /global/event``                       -> SSE stream of GlobalEvent
+  - ``POST /session``                            -> create a Session
+  - ``GET  /session``                            -> list sessions
+  - ``POST /session/{id}/message``               -> blocks; returns {info, parts}
+  - ``POST /session/{id}/abort``                 -> abort the running turn
+  - ``GET  /permission``                         -> list pending permissions
+  - ``POST /permission/{requestID}/reply``       -> {reply: once|always|reject}
+
+The prompt endpoint (``POST /session/{id}/message``) is synchronous: it returns
+the assembled assistant message when the turn finishes. While it blocks, the
+agent may ask for permission — those asks arrive on the SSE stream, so the
+bridge runs the prompt in a worker thread and the SSE reader in another.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+# Permission reply outcomes accepted by POST /permission/{id}/reply.
+PERMISSION_REPLIES = ("once", "always", "reject")
+
+# Sentinel: "use the client's configured directory" vs an explicit per-call one.
+_DEFAULT_DIR = object()
+
+
+class OpenCodeError(Exception):
+    """Base error for OpenCode HTTP interactions."""
+
+
+class OpenCodeDownError(OpenCodeError):
+    """The OpenCode server is unreachable (transport error / failed health)."""
+
+
+@dataclass(frozen=True)
+class PermissionAsk:
+    """A pending permission request surfaced by the SSE stream."""
+
+    request_id: str
+    session_id: str
+    permission: str
+    patterns: tuple[str, ...]
+    tool: dict[str, Any]
+
+    @classmethod
+    def from_request(cls, raw: dict[str, Any]) -> PermissionAsk:
+        return cls(
+            request_id=raw["id"],
+            session_id=raw.get("sessionID", ""),
+            permission=raw.get("permission", ""),
+            patterns=tuple(raw.get("patterns") or ()),
+            tool=raw.get("tool") or {},
+        )
+
+
+@dataclass(frozen=True)
+class QuestionOption:
+    label: str  # also the value sent back in the answer
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class QuestionAsk:
+    """A pending agent question surfaced by the SSE stream.
+
+    A question carries one or more sub-questions, each with options and an
+    optional free-text ("custom") answer. The bridge handles the common case:
+    a single question, rendered as a numbered picker (plus free text if custom).
+    The selected option's ``label`` is what gets sent back as the answer.
+    """
+
+    request_id: str
+    session_id: str
+    question: str
+    header: str
+    options: tuple[QuestionOption, ...]
+    custom: bool
+
+    @classmethod
+    def from_request(cls, raw: dict[str, Any]) -> QuestionAsk:
+        questions = raw.get("questions") or [{}]
+        first = questions[0] if questions else {}
+        options = tuple(
+            QuestionOption(label=o.get("label", ""), description=o.get("description", ""))
+            for o in (first.get("options") or [])
+            if isinstance(o, dict)
+        )
+        return cls(
+            request_id=raw["id"],
+            session_id=raw.get("sessionID", ""),
+            question=first.get("question", ""),
+            header=first.get("header", ""),
+            options=options,
+            custom=bool(first.get("custom")),
+        )
+
+
+@dataclass(frozen=True)
+class PromptResult:
+    """The outcome of a blocking prompt: assistant text + any errors."""
+
+    text: str
+    aborted: bool
+    error: str | None
+
+
+class OpenCodeClient:
+    """Thin sync wrapper around the OpenCode server HTTP API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        username: str | None = None,
+        password: str | None = None,
+        directory: str | None = None,
+        default_model: str | None = None,
+        timeout: float = 30.0,
+        prompt_timeout: float = 600.0,
+    ) -> None:
+        self._base = base_url.rstrip("/")
+        self._directory = directory
+        self._default_model = default_model
+        self._prompt_timeout = prompt_timeout
+        auth = httpx.BasicAuth(username, password) if username else None
+        self._client = httpx.Client(base_url=self._base, auth=auth, timeout=timeout)
+
+    def __enter__(self) -> OpenCodeClient:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # --- health ------------------------------------------------------------
+
+    def health(self) -> bool:
+        """Return True iff the server reports healthy. Never raises."""
+        try:
+            resp = self._client.get("/global/health", timeout=5.0)
+            resp.raise_for_status()
+            return bool(resp.json().get("healthy"))
+        except (httpx.HTTPError, ValueError):
+            return False
+
+    # --- sessions ----------------------------------------------------------
+
+    def create_session(self, title: str | None = None, directory: str | None = None) -> str:
+        body: dict[str, Any] = {}
+        if title:
+            body["title"] = title
+        # None -> use the client's configured directory; a path overrides it.
+        data = self._post("/session", body, directory=directory or _DEFAULT_DIR)
+        session_id = data.get("id")
+        if not session_id:
+            raise OpenCodeError(f"session create returned no id: {data!r}")
+        return session_id
+
+    def list_sessions(self, directory: str | None = None) -> list[dict[str, Any]]:
+        # /session is project-scoped: None -> client default directory; a path
+        # filters to that project (matching what the OpenCode TUI/desktop shows).
+        return self._get("/session", directory=directory or _DEFAULT_DIR) or []
+
+    def abort(self, session_id: str) -> bool:
+        return bool(self._post(f"/session/{session_id}/abort", {}))
+
+    def prompt(
+        self,
+        session_id: str,
+        text: str,
+        *,
+        model: str | None = None,
+        agent: str | None = None,
+        extra_parts: list[dict[str, Any]] | None = None,
+    ) -> PromptResult:
+        """Send a prompt and block until the assistant turn completes.
+
+        ``model`` overrides the default ("providerID/modelID"); ``agent`` selects
+        an agent (e.g. "plan"/"build"); ``extra_parts`` appends file parts.
+        """
+        parts: list[dict[str, Any]] = [{"type": "text", "text": text}]
+        if extra_parts:
+            parts.extend(extra_parts)
+        body: dict[str, Any] = {"parts": parts}
+        model_ref = _parse_model(model or self._default_model)
+        if model_ref is not None:
+            body["model"] = model_ref
+        if agent:
+            body["agent"] = agent
+        data = self._post(
+            f"/session/{session_id}/message",
+            body,
+            timeout=self._prompt_timeout,
+        )
+        return _prompt_result(data)
+
+    def rename_session(self, session_id: str, title: str) -> None:
+        self._patch(f"/session/{session_id}", {"title": title})
+
+    def revert(self, session_id: str, message_id: str, part_id: str | None = None) -> None:
+        body: dict[str, Any] = {"messageID": message_id}
+        if part_id:
+            body["partID"] = part_id
+        self._post(f"/session/{session_id}/revert", body)
+
+    def unrevert(self, session_id: str) -> None:
+        self._post(f"/session/{session_id}/unrevert", {})
+
+    def fork(self, session_id: str, message_id: str) -> str:
+        data = self._post(f"/session/{session_id}/fork", {"messageID": message_id})
+        new_id = data.get("id") if isinstance(data, dict) else None
+        if not new_id:
+            raise OpenCodeError(f"fork returned no id: {data!r}")
+        return new_id
+
+    def session_messages(self, session_id: str) -> list[dict[str, Any]]:
+        return self._get(f"/session/{session_id}/message") or []
+
+    # --- projects / worktrees ---------------------------------------------
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        return self._get("/project") or []
+
+    def current_project(self) -> dict[str, Any] | None:
+        return self._get("/project/current")
+
+    def list_worktrees(self) -> list[str]:
+        return self._get("/experimental/worktree") or []
+
+    # --- models / agents / commands / mcp ---------------------------------
+
+    def list_models(self) -> list[dict[str, Any]]:
+        return self._get("/api/model") or []
+
+    def list_agents(self) -> list[dict[str, Any]]:
+        return self._get("/agent") or []
+
+    def list_commands(self, directory: str | None = None) -> list[dict[str, Any]]:
+        return self._get("/command", directory=directory or _DEFAULT_DIR) or []
+
+    def list_skills(self, directory: str | None = None) -> list[dict[str, Any]]:
+        return self._get("/skill", directory=directory or _DEFAULT_DIR) or []
+
+    def run_command(self, session_id: str, command: str, arguments: str = "") -> PromptResult:
+        # `arguments` is a required field on the command endpoint, even when empty.
+        body: dict[str, Any] = {"command": command, "arguments": arguments}
+        data = self._post(f"/session/{session_id}/command", body, timeout=self._prompt_timeout)
+        return _prompt_result(data)
+
+    def list_mcps(self) -> dict[str, Any]:
+        return self._get("/mcp") or {}
+
+    def toggle_mcp(self, name: str, enable: bool) -> bool:
+        action = "connect" if enable else "disconnect"
+        return bool(self._post(f"/mcp/{name}/{action}", {}))
+
+    # --- permissions -------------------------------------------------------
+
+    def list_permissions(self) -> list[PermissionAsk]:
+        return [PermissionAsk.from_request(p) for p in self._get("/permission")]
+
+    def reply_permission(self, request_id: str, reply: str, message: str | None = None) -> bool:
+        if reply not in PERMISSION_REPLIES:
+            raise ValueError(f"reply must be one of {PERMISSION_REPLIES}, got {reply!r}")
+        body: dict[str, Any] = {"reply": reply}
+        if message:
+            body["message"] = message
+        return bool(self._post(f"/permission/{request_id}/reply", body))
+
+    # --- questions ---------------------------------------------------------
+
+    def reply_question(self, request_id: str, answer: str) -> bool:
+        """Answer a single-question agent prompt. ``answer`` is the chosen
+        option label (or free text when the question allows custom input)."""
+        return bool(self._post(f"/question/{request_id}/reply", {"answers": [[answer]]}))
+
+    def reject_question(self, request_id: str) -> bool:
+        return bool(self._post(f"/question/{request_id}/reject", {}))
+
+    # --- events (SSE) ------------------------------------------------------
+
+    def iter_events(self) -> Iterator[dict[str, Any]]:
+        """Yield decoded SSE event payloads from ``GET /global/event``.
+
+        Each yielded dict is the GlobalEvent ``payload`` object, i.e. has
+        ``{"type": <event-type>, "properties": {...}}``. Raises
+        OpenCodeDownError on transport failure so the caller can reconnect.
+        """
+        try:
+            with self._client.stream("GET", "/global/event", timeout=None) as resp:
+                resp.raise_for_status()
+                for line in resp.iter_lines():
+                    if not line or not line.startswith("data:"):
+                        continue
+                    raw = line[len("data:") :].strip()
+                    if not raw:
+                        continue
+                    try:
+                        event = json.loads(raw)
+                    except ValueError:
+                        continue
+                    payload = event.get("payload") if isinstance(event, dict) else None
+                    if isinstance(payload, dict) and "type" in payload:
+                        yield payload
+        except httpx.HTTPError as exc:
+            raise OpenCodeDownError(f"event stream failed: {exc}") from exc
+
+    # --- internal ----------------------------------------------------------
+
+    def _get(self, path: str, *, directory: str | None | object = _DEFAULT_DIR) -> Any:
+        if directory is _DEFAULT_DIR:
+            params = self._dir_params()
+        else:
+            params = {"directory": directory} if directory else None
+        try:
+            resp = self._client.get(path, params=params)
+        except httpx.TransportError as exc:
+            raise OpenCodeDownError(f"GET {path} failed: {exc}") from exc
+        return self._unwrap(resp, path)
+
+    def _post(
+        self,
+        path: str,
+        body: dict[str, Any],
+        *,
+        timeout: float | None = None,
+        directory: str | None | object = _DEFAULT_DIR,
+    ) -> Any:
+        # directory=_DEFAULT_DIR -> use the client's configured directory;
+        # an explicit value (or None) overrides it for this call.
+        params = (
+            self._dir_params()
+            if directory is _DEFAULT_DIR
+            else ({"directory": directory} if directory else None)
+        )
+        try:
+            resp = self._client.post(
+                path,
+                json=body,
+                params=params,
+                timeout=httpx.USE_CLIENT_DEFAULT if timeout is None else timeout,
+            )
+        except httpx.TransportError as exc:
+            raise OpenCodeDownError(f"POST {path} failed: {exc}") from exc
+        return self._unwrap(resp, path)
+
+    def _patch(self, path: str, body: dict[str, Any]) -> Any:
+        try:
+            resp = self._client.patch(path, json=body, params=self._dir_params())
+        except httpx.TransportError as exc:
+            raise OpenCodeDownError(f"PATCH {path} failed: {exc}") from exc
+        return self._unwrap(resp, path)
+
+    def _dir_params(self) -> dict[str, str] | None:
+        return {"directory": self._directory} if self._directory else None
+
+    @staticmethod
+    def _unwrap(resp: httpx.Response, path: str) -> Any:
+        if resp.status_code >= 400:
+            raise OpenCodeError(f"{path} -> HTTP {resp.status_code}: {resp.text[:300]}")
+        if not resp.content:
+            return None
+        try:
+            return resp.json()
+        except ValueError:
+            return resp.text
+
+
+def _parse_model(model: str | None) -> dict[str, str] | None:
+    """Turn "providerID/modelID" into the API's model object."""
+    if not model:
+        return None
+    provider, _, model_id = model.partition("/")
+    if not provider or not model_id:
+        raise ValueError(f'model must be "providerID/modelID", got {model!r}')
+    return {"providerID": provider, "modelID": model_id}
+
+
+def _prompt_result(data: Any) -> PromptResult:
+    """Extract assistant text + error from a {info, parts} response."""
+    if not isinstance(data, dict):
+        return PromptResult(text="", aborted=False, error="unexpected response")
+    info = data.get("info") or {}
+    parts = data.get("parts") or []
+    texts = [p.get("text", "") for p in parts if isinstance(p, dict) and p.get("type") == "text"]
+    text = "\n".join(t for t in texts if t).strip()
+
+    error = info.get("error")
+    aborted = False
+    err_msg: str | None = None
+    if isinstance(error, dict):
+        name = error.get("name", "")
+        aborted = name == "MessageAbortedError"
+        err_msg = None if aborted else (error.get("data", {}).get("message") or name or "error")
+    return PromptResult(text=text, aborted=aborted, error=err_msg)
+
+
+def wait_for_healthy(client: OpenCodeClient, attempts: int = 1, delay: float = 1.0) -> bool:
+    """Poll health up to ``attempts`` times. Returns True on first success."""
+    for i in range(attempts):
+        if client.health():
+            return True
+        if i < attempts - 1:
+            time.sleep(delay)
+    return False

opencode_talk_bridge/pending.py

@@ -0,0 +1,115 @@
+"""Unified pending-interaction registry.
+
+Talk has no inline buttons, so every interactive flow (permission, agent
+question, list picker) is driven by the *next reply* in the conversation. At
+most one interaction is pending per conversation; OpenCode serialises these
+within a session. The bridge consults the pending interaction before normal
+message handling (see ``bridge._handle_message``):
+
+  - **permission** — answered by ``ja``/``immer``/``nein`` (``interpret_reply``).
+  - **question** — an agent question; a numbered option or free text answers it.
+  - **selection** — a numbered list; a bare integer runs the stored callback.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from .opencode import PermissionAsk, QuestionAsk
+
+
+@dataclass(frozen=True)
+class SelectItem:
+    label: str
+    value: str
+    description: str = ""
+
+
+@dataclass
+class PermissionPending:
+    ask: PermissionAsk
+    kind: str = field(default="permission", init=False)
+
+
+@dataclass
+class QuestionPending:
+    ask: QuestionAsk
+    kind: str = field(default="question", init=False)
+
+
+@dataclass
+class SelectionPending:
+    title: str
+    items: list[SelectItem]
+    on_select: Callable[[str], None]  # receives the chosen item's value
+    kind: str = field(default="selection", init=False)
+
+
+Pending = PermissionPending | QuestionPending | SelectionPending
+
+
+class PendingRegistry:
+    """Thread-safe one-pending-interaction-per-conversation store."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._by_token: dict[str, Pending] = {}
+
+    def set(self, token: str, pending: Pending) -> None:
+        with self._lock:
+            self._by_token[token] = pending
+
+    def get(self, token: str) -> Pending | None:
+        with self._lock:
+            return self._by_token.get(token)
+
+    def pop(self, token: str) -> Pending | None:
+        with self._lock:
+            return self._by_token.pop(token, None)
+
+    def has(self, token: str) -> bool:
+        with self._lock:
+            return token in self._by_token
+
+
+def format_selection(title: str, items: list[SelectItem], hint: str = "_Antworte mit der Nummer._") -> str:
+    """Render a numbered picker. Reply with the number to choose."""
+    lines = [title]
+    for i, item in enumerate(items, 1):
+        line = f"{i}. {item.label}"
+        if item.description:
+            line += f" — {item.description}"
+        lines.append(line)
+    lines.append(hint)
+    return "\n".join(lines)
+
+
+def parse_choice(text: str, count: int) -> int | None:
+    """Parse a bare 1..count integer reply into a 0-based index, else None."""
+    token = text.strip()
+    if not token.isdigit():
+        return None
+    n = int(token)
+    return n - 1 if 1 <= n <= count else None
+
+
+def format_question(ask: QuestionAsk) -> str:
+    """Render an agent question with its options as a numbered picker."""
+    lines: list[str] = []
+    if ask.header:
+        lines.append(f"❓ *{ask.header}*")
+    if ask.question:
+        lines.append(ask.question)
+    for i, opt in enumerate(ask.options, 1):
+        line = f"{i}. {opt.label}"
+        if opt.description:
+            line += f" — {opt.description}"
+        lines.append(line)
+    if ask.options:
+        hint = "Antworte mit der Nummer" + (" oder mit freiem Text." if ask.custom else ".")
+    else:
+        hint = "Antworte frei."
+    lines.append(f"_{hint}_")
+    return "\n".join(lines)

opencode_talk_bridge/permissions.py

@@ -0,0 +1,79 @@
+"""Map OpenCode permission requests to Talk yes/no prompts and back.
+
+When OpenCode wants to run something dangerous (shell, file write) it emits a
+``permission.asked`` event and blocks. The bridge posts a concise prompt into
+the bound conversation; the next reply from an allowlisted user is interpreted
+as the answer and sent to ``POST /permission/{id}/reply``.
+
+Nothing from the tool payload beyond the permission kind and the suggested
+patterns is echoed, and even those are length-capped, so command arguments that
+might contain secrets are never posted verbatim.
+"""
+
+from __future__ import annotations
+
+import threading
+
+from .opencode import PermissionAsk
+
+# Reply-word -> OpenCode outcome. Lowercased exact-token match.
+_ALLOW_ONCE = {"ja", "yes", "y", "j", "ok", "allow", "erlauben"}
+_ALLOW_ALWAYS = {"immer", "always", "a"}
+_REJECT = {"nein", "no", "n", "deny", "reject", "ablehnen", "stop"}
+
+_MAX_PATTERN_LEN = 80
+
+
+def interpret_reply(text: str) -> str | None:
+    """Return "once"/"always"/"reject", or None if the text isn't an answer."""
+    token = text.strip().lower()
+    if token in _ALLOW_ALWAYS:
+        return "always"
+    if token in _ALLOW_ONCE:
+        return "once"
+    if token in _REJECT:
+        return "reject"
+    return None
+
+
+def format_prompt(ask: PermissionAsk) -> str:
+    """Build a concise, secret-safe Talk prompt for a permission request."""
+    kind = ask.permission or "eine Aktion"
+    detail = ""
+    if ask.patterns:
+        pattern = ask.patterns[0]
+        if len(pattern) > _MAX_PATTERN_LEN:
+            pattern = pattern[:_MAX_PATTERN_LEN] + "…"
+        detail = f" (`{pattern}`)"
+    return (
+        f"🔐 OpenCode möchte *{kind}*{detail} ausführen.\n"
+        "Antworte `ja` (einmal), `immer` (für diese Session) oder `nein`."
+    )
+
+
+class PendingPermissions:
+    """Thread-safe registry of the permission awaiting a reply per conversation.
+
+    Only one pending permission per conversation is tracked; OpenCode serialises
+    permission asks within a session, so a newer ask replaces an older one.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._by_token: dict[str, PermissionAsk] = {}
+
+    def set(self, token: str, ask: PermissionAsk) -> None:
+        with self._lock:
+            self._by_token[token] = ask
+
+    def get(self, token: str) -> PermissionAsk | None:
+        with self._lock:
+            return self._by_token.get(token)
+
+    def pop(self, token: str) -> PermissionAsk | None:
+        with self._lock:
+            return self._by_token.pop(token, None)
+
+    def has(self, token: str) -> bool:
+        with self._lock:
+            return token in self._by_token