opencode-runtime 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

opencode_runtime/__init__.py

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

opencode_runtime/cli.py

@@ -17,13 +17,14 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
-from .server import ServerManager, _compute_runtime_key
+from .server import DisplayStatus, ServerManager, _compute_runtime_key
 
 # ---------------------------------------------------------------------------
 # ANSI
 # ---------------------------------------------------------------------------
 
 _R = "\033[0m"
+_DIM = "\033[2m"
 
 
 def _green(s: str) -> str:
@@ -43,7 +44,7 @@ def _cyan(s: str) -> str:
 
 
 def _dim(s: str) -> str:
-    return f"\033[2m{s}{_R}"
+    return f"{_DIM}{s}{_R}"
 
 
 # ---------------------------------------------------------------------------
@@ -76,6 +77,29 @@ def _row(label: str, value: str) -> None:
     print(f"  {_cyan(f'{label:<9}')}  {value}")
 
 
+_STATUS_ICONS: dict[DisplayStatus, str] = {
+    DisplayStatus.RUNNING: "●",
+    DisplayStatus.STARTING: "◐",
+    DisplayStatus.UNHEALTHY: "▲",
+    DisplayStatus.STALE: "○",
+    DisplayStatus.FAILED: "✗",
+}
+_STATUS_COLORS = {
+    DisplayStatus.RUNNING: _green,
+    DisplayStatus.STARTING: _yellow,
+    DisplayStatus.UNHEALTHY: _red,
+    DisplayStatus.STALE: _dim,
+    DisplayStatus.FAILED: _red,
+}
+
+
+def _status_display(status: DisplayStatus) -> str:
+    """Render a ServerStatus.display value as a coloured icon + label."""
+    icon = _STATUS_ICONS.get(status, "?")
+    color = _STATUS_COLORS.get(status, _dim)
+    return color(f"{icon} {status.value}")
+
+
 # ---------------------------------------------------------------------------
 # serve
 # ---------------------------------------------------------------------------
@@ -152,11 +176,11 @@ def cmd_serve(args: argparse.Namespace) -> None:
 
 
 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)
+    statuses = asyncio.run(ServerManager().list_statuses())
+    show_workspace = any(st.entry.workspace for st in statuses)
+    show_user = any(st.entry.user_id for st in statuses)
 
-    cols = ["  {:<18}", "{:>6}", "{:>6}", "{:<7}", "{:>8}"]
+    cols = ["  {:<18}", "{:>6}", "{:>6}", "{:<11}", "{:>8}"]
     headers = ["ID", "PID", "PORT", "STATUS", "UPTIME"]
     if show_workspace:
         cols.append("{:<12}")
@@ -171,18 +195,33 @@ def cmd_ps(_args: argparse.Namespace) -> None:
     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)]
+    for st in statuses:
+        e = st.entry
+        status_plain = f"{_STATUS_ICONS.get(st.display, '?')} {st.display.value}"
+        status_coloured = _status_display(st.display)
+
+        # Compute uptime
+        try:
+            started = datetime.fromisoformat(e.started_at)
+            uptime_secs = int((datetime.now(timezone.utc) - started).total_seconds())
+            if uptime_secs < 60:
+                uptime_str = f"{uptime_secs}s"
+            elif uptime_secs < 3600:
+                uptime_str = f"{uptime_secs // 60}m"
+            else:
+                uptime_str = f"{uptime_secs // 3600}h"
+        except Exception:
+            uptime_str = "?"
+
+        vals = [e.key, str(e.pid), str(e.port), status_plain, uptime_str]
         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))
+        dimmed_row = _dim(row).replace(status_plain, f"{status_coloured}{_DIM}", 1)
+        print(dimmed_row)
 
 
 # ---------------------------------------------------------------------------
@@ -191,8 +230,10 @@ def cmd_ps(_args: argparse.Namespace) -> None:
 
 
 def cmd_stop(args: argparse.Namespace) -> None:
+    from . import registry
+
     manager = ServerManager()
-    entry = manager.find(args.key)
+    entry = registry.read(args.key)
     if entry is None:
         sys.exit(_red(f"✗ ID {args.key!r} not found in registry"))
 
@@ -202,7 +243,7 @@ def cmd_stop(args: argparse.Namespace) -> None:
 
     print(f"{_green('✓ Server stopped')}\n")
     _row("ID", entry.key)
-    _row("PID", _dim(str(entry.pid)))
+    _row("PID", _dim(str(entry.pid)) if entry.pid else _dim("(none)"))
 
 
 # ---------------------------------------------------------------------------
@@ -230,20 +271,103 @@ def cmd_stop_all(_args: argparse.Namespace) -> None:
 
 
 def cmd_health(args: argparse.Namespace) -> None:
-    from .exceptions import OpenCodeServerError
+    manager = ServerManager()
+    st = asyncio.run(manager.status(args.key))
+    if st is None:
+        sys.exit(_red(f"✗ ID {args.key!r} not found in registry"))
+    entry = st.entry
+
+    if st.display == DisplayStatus.RUNNING:
+        try:
+            result = asyncio.run(manager.health(args.key))
+            version = result.get("version")
+            print(
+                _green("✓ healthy")
+                + f"   {_dim(f'version {version}')}"
+                + f"   {_dim(f'http://127.0.0.1:{entry.port}')}"
+            )
+        except Exception as exc:
+            sys.exit(_red(f"✗ unhealthy: /global/health failed: {exc}"))
+    elif st.display == DisplayStatus.STARTING:
+        try:
+            claimed = datetime.fromisoformat(entry.claimed_at)
+            age_secs = int((datetime.now(timezone.utc) - claimed).total_seconds())
+            sys.exit(_yellow(f"◐ starting: claimed {age_secs}s ago, health check pending"))
+        except Exception:
+            sys.exit(_yellow("◐ starting: awaiting health check"))
+    elif st.display == DisplayStatus.UNHEALTHY:
+        sys.exit(
+            _red(
+                f"✗ unhealthy: process running (pid {entry.pid}) but /global/health endpoint failed"
+            )
+        )
+    elif st.display == DisplayStatus.STALE:
+        sys.exit(_red(f"✗ stale: registry entry exists but pid {entry.pid} is not running"))
+    elif st.display == DisplayStatus.FAILED:
+        sys.exit(_red("✗ failed: startup failed or lease expired"))
+    else:
+        sys.exit(_red(f"✗ unknown: {st.display}"))
+
 
+# ---------------------------------------------------------------------------
+# inspect
+# ---------------------------------------------------------------------------
+
+
+def cmd_inspect(args: argparse.Namespace) -> None:
     manager = ServerManager()
-    entry = manager.find(args.key)
-    if entry is None:
+    st = asyncio.run(manager.status(args.key))
+    if st is None:
         sys.exit(_red(f"✗ ID {args.key!r} not found in registry"))
+    entry = st.entry
 
-    url = f"http://127.0.0.1:{entry.port}"
+    # Compute uptime
     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}"))
+        started = datetime.fromisoformat(entry.started_at)
+        uptime_secs = int((datetime.now(timezone.utc) - started).total_seconds())
+        if uptime_secs < 60:
+            uptime = f"{uptime_secs}s"
+        elif uptime_secs < 3600:
+            uptime = f"{uptime_secs // 60}m {uptime_secs % 60}s"
+        else:
+            uptime = f"{uptime_secs // 3600}h {(uptime_secs % 3600) // 60}m"
+    except Exception:
+        uptime = "?"
+
+    # Compute idle time (time since last use)
+    if entry.last_used_at:
+        try:
+            last_used = datetime.fromisoformat(entry.last_used_at)
+            idle_secs = int((datetime.now(timezone.utc) - last_used).total_seconds())
+            if idle_secs < 60:
+                idle = f"{idle_secs}s ago"
+            elif idle_secs < 3600:
+                idle = f"{idle_secs // 60}m ago"
+            else:
+                idle = f"{idle_secs // 3600}h ago"
+        except Exception:
+            idle = "?"
+    else:
+        idle = "-"
+
+    print()
+    _row("ID", entry.key)
+    _row("Status", _status_display(st.display))
+    _row("Project", _home(entry.project_dir))
+    if entry.workspace:
+        _row("Workspace", entry.workspace)
+    if entry.user_id:
+        _row("User", entry.user_id)
+    _row("PID", _dim(str(entry.pid)) if entry.pid else _dim("(none)"))
+    _row("Port", _dim(str(entry.port)))
+    _row("Uptime", uptime)
+    _row("Last used", idle)
+    if entry.runtime_version:
+        _row("Runtime", entry.runtime_version)
+    if entry.server_dir:
+        log_file = _home(str(Path(entry.server_dir) / "opencode.log"))
+        _row("Log file", _dim(log_file))
+    print()
 
 
 # ---------------------------------------------------------------------------
@@ -291,6 +415,10 @@ def main() -> None:
     p.add_argument("key", help="server id (from ps)")
     p.set_defaults(func=cmd_health)
 
+    p = sub.add_parser("inspect", help="show detailed server information")
+    p.add_argument("key", help="server id (from ps)")
+    p.set_defaults(func=cmd_inspect)
+
     if len(sys.argv) == 1:
         parser.print_help()
         sys.exit(0)

opencode_runtime/client.py

@@ -24,8 +24,9 @@ class OpenCodeClient:
     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.
+        password:  Value of ``OPENCODE_SERVER_PASSWORD``. Sent as HTTP Basic
+                   auth (``Authorization: Basic base64("opencode:<password>")``)
+                   when set.
         timeout:   Default request timeout in seconds.
     """
 
@@ -154,7 +155,7 @@ class OpenCodeClient:
           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.status`` — status change (e.g. ``{type: "busy"}``).
         * ``session.idle`` — terminal; model finished.
         * ``session.error`` — terminal; something went wrong.
         * ``permission.asked`` — tool permission request; caller must handle.
@@ -222,7 +223,3 @@ class OpenCodeClient:
                         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

@@ -9,9 +9,10 @@ class OpenCodeEvent:
     """A normalized event from the OpenCode server SSE stream.
 
     Attributes:
-        type:  Event type string, e.g. "message.delta", "message.completed",
+        type:  Event type string, e.g. "message.part.delta", "message.part.updated",
                "session.error". Mirrors the OpenCode bus event types.
-        text:  Text content for message.delta events; None for other types.
+        text:  Text content for message.part.delta events (when properties.field == "text")
+               and message.part.updated events (when part.type == "text"); None otherwise.
         raw:   The raw event payload from the server. Use this escape hatch
                when you need fields beyond type and text.
     """
@@ -19,8 +20,3 @@ class OpenCodeEvent:
     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

@@ -12,3 +12,11 @@ class OpenCodeServerError(OpenCodeRuntimeError):
 
 class OpenCodeTimeoutError(OpenCodeRuntimeError):
     """Raised when a health check or request exceeds the allowed timeout."""
+
+
+class RegistrySchemaError(OpenCodeRuntimeError):
+    """Raised when the registry database's schema version can't be handled.
+
+    Either it's newer than this version of opencode-runtime understands, or
+    no migration is registered to bring it up to the current version.
+    """

opencode_runtime/registry.py

@@ -1,8 +1,8 @@
 """
 Registry for tracking OpenCode instance processes.
 
-Each running instance is represented by a JSON file at:
-    ~/.opencode-runtime/servers/<key>.json
+Every running instance is a row in a SQLite database at:
+    ~/.opencode-runtime/servers/registry.db
 
 Used by both the CLI (opencode-runtime serve/ps/stop) and the library
 (OpenCodeRuntime) — the registry is the shared source of truth for all
@@ -11,67 +11,166 @@ running instances regardless of how they were started.
 
 from __future__ import annotations
 
-import json
 import os
+import sqlite3
+from contextlib import contextmanager
 from dataclasses import asdict, dataclass
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
+from enum import Enum
 from pathlib import Path
+from typing import Generator
 
-REGISTRY_DIR = Path.home() / ".opencode-runtime" / "servers"
+from .schema import SCHEMA, SCHEMA_VERSION, migrate
+
+REGISTRY_DIR = Path(
+    os.environ.get("OPENCODE_RUNTIME_REGISTRY_DIR")
+    or (Path.home() / ".opencode-runtime" / "servers")
+)
+
+# A 'starting' row older than this is treated as abandoned (its starter
+# crashed — SIGKILL, host reboot — before reaching write()/delete()) and is
+# reclaimed by the next claim_starting() call. Comfortably above
+# _wait_healthy's default 60s startup timeout, so a claim only expires once
+# a start attempt has definitely either finished or died without cleaning
+# up after itself.
+_START_LEASE_SECONDS = 90
+
+
+class ServerState(str, Enum):
+    """Server lifecycle state.
+
+    STARTING: claimed startup slot, awaiting health check.
+    RUNNING: process alive, health check passing.
+    STOPPING: shutdown initiated (reserved for future use).
+    FAILED: startup failed or lease expired (reserved for future use).
+    """
+
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    FAILED = "failed"
 
 
 @dataclass
 class RegistryEntry:
+    """A server entry in the registry.
+
+    state: ServerState enum value. Display status is derived from state + observed health.
+    """
+
     key: str
-    pid: int
+    state: ServerState
+    pid: int | None
     port: int
     password: str
     project_dir: str
     server_dir: str | None
     started_at: str  # ISO-8601
+    claimed_at: str  # ISO-8601; only meaningful while state == "starting"
     workspace: str | None = None
     user_id: str | None = None
+    last_used_at: str | None = None
+    runtime_version: str | None = None
 
 
-def write(entry: RegistryEntry) -> None:
-    """Write a registry entry to disk. File is chmod 0o600."""
+_INSERT = """
+INSERT INTO servers (key, state, pid, port, password, project_dir, server_dir,
+                     started_at, claimed_at, workspace, user_id, last_used_at,
+                     runtime_version)
+VALUES (:key, :state, :pid, :port, :password, :project_dir, :server_dir,
+        :started_at, :claimed_at, :workspace, :user_id, :last_used_at,
+        :runtime_version)
+"""
+
+_UPSERT = _INSERT.replace("INSERT", "INSERT OR REPLACE", 1)
+
+
+@contextmanager
+def _connect() -> Generator[sqlite3.Connection, None, None]:
+    """Open the registry database, creating it on first use.
+
+    Commits on clean exit, rolls back if the body raises. The 5s timeout is
+    SQLite's busy timeout — concurrent writers wait for each other instead
+    of failing immediately.
+    """
     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)
+    db_path = REGISTRY_DIR / "registry.db"
+    is_new = not db_path.exists()
+    conn = sqlite3.connect(db_path, timeout=5.0)
+    try:
+        conn.row_factory = sqlite3.Row
+        conn.execute(SCHEMA)
+        if is_new:
+            db_path.chmod(0o600)  # entries hold server passwords
+            conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+        else:
+            current_version = conn.execute("PRAGMA user_version").fetchone()[0]
+            if current_version != SCHEMA_VERSION:
+                migrate(conn, current_version)
+        yield conn
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def _entry(row: sqlite3.Row) -> RegistryEntry:
+    # Column names match RegistryEntry field names one-to-one.
+    return RegistryEntry(**{name: row[name] for name in row.keys()})
+
+
+def write(entry: RegistryEntry) -> None:
+    """Write (insert or replace) a registry entry."""
+    with _connect() as conn:
+        conn.execute(_UPSERT, asdict(entry))
 
 
 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)
+    with _connect() as conn:
+        row = conn.execute("SELECT * FROM servers WHERE key = ?", (key,)).fetchone()
+    return _entry(row) if row is not None else None
 
 
 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)
+    with _connect() as conn:
+        conn.execute("DELETE FROM servers WHERE key = ?", (key,))
 
 
 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."""
+    """Return all registry entries."""
+    with _connect() as conn:
+        rows = conn.execute("SELECT * FROM servers").fetchall()
+    return [_entry(row) for row in rows]
+
+
+def claim_starting(entry: RegistryEntry) -> bool:
+    """Atomically insert a 'starting' row for entry.key.
+
+    Returns True if this call claimed the key, False if a row for the key
+    already exists (a live 'starting' claim or a 'ready' server). A
+    'starting' row older than _START_LEASE_SECONDS is treated as abandoned
+    and reclaimed within the same transaction.
+    """
+    cutoff = (datetime.now(timezone.utc) - timedelta(seconds=_START_LEASE_SECONDS)).isoformat(
+        timespec="microseconds"
+    )
+    try:
+        with _connect() as conn:
+            conn.execute(
+                "DELETE FROM servers WHERE key = ? AND state = ? AND claimed_at < ?",
+                (entry.key, ServerState.STARTING.value, cutoff),
+            )
+            conn.execute(_INSERT, asdict(entry))
+        return True
+    except sqlite3.IntegrityError:  # PRIMARY KEY conflict — someone else holds the key
+        return False
+
+
+def is_alive(pid: int | None) -> bool:
+    """Return True if pid is set and a process with it is running."""
+    if pid is None:
+        return False
     try:
         os.kill(pid, 0)
         return True
@@ -80,5 +179,10 @@ def is_alive(pid: int) -> bool:
 
 
 def now_iso() -> str:
-    """Return current UTC time as ISO-8601 string."""
-    return datetime.now(timezone.utc).isoformat()
+    """Return current UTC time as ISO-8601 string with fixed microsecond precision.
+
+    Fixed precision (rather than omitting the fraction when it's exactly
+    zero, as isoformat() does by default) keeps these strings correctly
+    orderable by plain string comparison, e.g. in claim_starting()'s lease check.
+    """
+    return datetime.now(timezone.utc).isoformat(timespec="microseconds")

opencode_runtime/response.py

@@ -9,7 +9,7 @@ class OpenCodeResponse:
     """Collected response from a completed ask() call.
 
     Attributes:
-        text:  Full assistant text, concatenated from all message.delta events.
+        text:  Full assistant text, concatenated from all message.part.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.
     """

opencode_runtime/runtime.py

@@ -55,19 +55,21 @@ class OpenCodeRuntime:
     # ------------------------------------------------------------------
 
     async def __aenter__(self) -> OpenCodeRuntime:
-        await self.start()
         return self
 
     async def __aexit__(self, exc_type: t.Any, exc: t.Any, tb: t.Any) -> None:
-        await self.stop()
+        await self.close()
 
-    async def start(self) -> None:
-        """Start the default OpenCode instance eagerly so the runtime is ready to use."""
-        await self.session()
+    async def close(self) -> None:
+        """Stop every server this runtime instance itself started.
 
-    async def stop(self) -> None:
-        """Shut down all managed OpenCode instance processes."""
-        await self._server_manager.stop_all()
+        Servers this runtime merely attached to — already running, started
+        by another process or the CLI — are left alone; they're shared
+        state and exiting this runtime shouldn't terminate them out from
+        under whoever else is using them. To stop those explicitly, use the
+        CLI (``opencode-runtime stop`` / ``stop-all``).
+        """
+        await self._server_manager.stop_owned()
 
     # ------------------------------------------------------------------
     # Session factory
@@ -126,6 +128,8 @@ class OpenCodeRuntime:
             user_id=user_id,
         )
 
+        self._server_manager.touch(key)
+
         return OpenCodeSession(
             client=server.client,
             workspace=workspace,