opencode-runtime 0.4.1__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.1"
+__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.
     """
 

opencode_runtime/event.py

@@ -20,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/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,

opencode_runtime/schema.py

@@ -0,0 +1,79 @@
+"""
+SQLite schema and migration mechanism for the registry database.
+
+The schema version is stored in the database itself via SQLite's built-in
+`PRAGMA user_version` — no separate metadata table needed. A fresh database
+is stamped with SCHEMA_VERSION directly; an existing one is brought up to it
+by migrate().
+
+Bump SCHEMA_VERSION and add a step to _MIGRATIONS whenever the `servers`
+table shape changes. Never edit SCHEMA in place once a version has shipped —
+existing databases on disk still have the old shape and rely on a migration
+step to reach the new one.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from typing import Callable
+
+from .exceptions import RegistrySchemaError
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS servers (
+    key             TEXT PRIMARY KEY,
+    state           TEXT NOT NULL,
+    pid             INTEGER,
+    port            INTEGER NOT NULL,
+    password        TEXT NOT NULL,
+    project_dir     TEXT NOT NULL,
+    server_dir      TEXT,
+    started_at      TEXT NOT NULL,
+    claimed_at      TEXT NOT NULL,
+    workspace       TEXT,
+    user_id         TEXT,
+    last_used_at    TEXT,
+    runtime_version TEXT
+)
+"""
+
+SCHEMA_VERSION = 1
+
+# Migration steps, keyed by the version they upgrade *from*. Each callable
+# receives the open connection (mid-transaction, table already created) and
+# must leave the database in the shape of `from_version + 1` — e.g. an
+# `ALTER TABLE servers ADD COLUMN ...`.
+#
+# Version 0 covers every database that predates this versioning scheme. Its
+# table shape is identical to version 1 (versioning was introduced with no
+# accompanying column change), so that migration is a no-op — it exists so
+# unversioned databases get stamped with a version the first time they're
+# opened under this scheme.
+_MIGRATIONS: dict[int, Callable[[sqlite3.Connection], None]] = {
+    0: lambda conn: None,
+}
+
+
+def migrate(conn: sqlite3.Connection, current_version: int) -> None:
+    """Bring conn's schema from current_version up to SCHEMA_VERSION, in place.
+
+    Raises RegistrySchemaError if current_version is newer than this code
+    understands, or if a required migration step isn't registered.
+    """
+    if current_version > SCHEMA_VERSION:
+        raise RegistrySchemaError(
+            f"registry database is schema v{current_version}, but this version of "
+            f"opencode-runtime only understands up to v{SCHEMA_VERSION}. Upgrade "
+            "opencode-runtime to use it."
+        )
+    version = current_version
+    while version < SCHEMA_VERSION:
+        step = _MIGRATIONS.get(version)
+        if step is None:
+            raise RegistrySchemaError(
+                f"no migration registered to bring the registry database from schema "
+                f"v{version} to v{version + 1}"
+            )
+        step(conn)
+        version += 1
+    conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")

opencode_runtime/server.py

@@ -13,15 +13,34 @@ import json
 import os
 import secrets
 import shutil
+import signal
 import socket
 from dataclasses import dataclass
+from enum import Enum
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
-if TYPE_CHECKING:
-    from .client import OpenCodeClient
+try:
+    from importlib.metadata import version
+except ImportError:
+    from importlib_metadata import version  # type: ignore[import-not-found,no-redef]
 
-from .registry import RegistryEntry
+import httpx
+
+from . import registry
+from .client import OpenCodeClient
+from .exceptions import (
+    OpenCodeNotFoundError,
+    OpenCodeRuntimeError,
+    OpenCodeServerError,
+    OpenCodeTimeoutError,
+)
+from .registry import RegistryEntry, ServerState
+
+# One or more paths to overlay into the server dir before startup.
+# Module-level alias: inside ServerManager's class body, `list[...]` in an
+# annotation would resolve to the ServerManager.list method, not the builtin.
+Materials = str | Path | list[str | Path] | None
 
 
 @dataclass
@@ -34,6 +53,58 @@ class _ManagedServer:
     server_dir: Path | None  # None when runtime_dir is not set (no isolation)
 
 
+class DisplayStatus(str, Enum):
+    """User-facing status derived from registry state, process liveness, and health."""
+
+    STARTING = "starting"
+    RUNNING = "running"
+    UNHEALTHY = "unhealthy"
+    STALE = "stale"
+    FAILED = "failed"
+    STOPPING = "stopping"
+
+
+@dataclass
+class ServerStatus:
+    """Computed liveness/health status for a registry entry."""
+
+    entry: RegistryEntry
+    process_alive: bool
+    health_ok: bool
+    display: DisplayStatus
+
+
+def _is_process_alive(pid: int | None) -> bool:
+    """Return True if pid is set and a process with it is running."""
+    return registry.is_alive(pid)
+
+
+async def _is_health_ok(client: OpenCodeClient, timeout: float = 3.0) -> bool:
+    """Return True if /global/health endpoint responds successfully."""
+    try:
+        await asyncio.wait_for(client.health(), timeout=timeout)
+        return True
+    except Exception:
+        return False
+
+
+def _compute_display_status(
+    state: ServerState, process_alive: bool, health_ok: bool, lease_expired: bool = False
+) -> DisplayStatus:
+    """Derive user-facing display status from state, process liveness, and health."""
+    if state == ServerState.STARTING:
+        return DisplayStatus.FAILED if lease_expired else DisplayStatus.STARTING
+    if state == ServerState.STOPPING:
+        return DisplayStatus.STOPPING
+    if state == ServerState.FAILED:
+        return DisplayStatus.FAILED
+    if not process_alive:
+        return DisplayStatus.STALE
+    if not health_ok:
+        return DisplayStatus.UNHEALTHY
+    return DisplayStatus.RUNNING
+
+
 def _find_free_port(host: str = "127.0.0.1") -> int:
     """Bind to port 0 and let the OS pick a free ephemeral port."""
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
@@ -47,8 +118,6 @@ async def _wait_healthy(
     process: asyncio.subprocess.Process | None = None,
 ) -> None:
     """Poll GET /global/health until the server responds or timeout expires."""
-    from .exceptions import OpenCodeTimeoutError
-
     deadline = asyncio.get_event_loop().time() + timeout
     last_exc: Exception | None = None
 
@@ -70,11 +139,9 @@ async def _wait_healthy(
 def _prepare_dir(
     server_dir: Path,
     config: dict[str, Any],
-    materials: str | Path | list[str | Path] | None,
+    materials: Materials,
 ) -> None:
     """Write opencode.json and overlay materials into server_dir."""
-    from .exceptions import OpenCodeRuntimeError
-
     if config:
         (server_dir / "opencode.json").write_text(
             json.dumps(config, indent=2),
@@ -119,7 +186,7 @@ def _compute_runtime_key(
     workspace: str | None,
     user_id: str | None,
     project_dir: Path,
-    materials: str | Path | list[str | Path] | None,
+    materials: Materials,
     config: dict[str, Any],
 ) -> str:
     """Compute a stable 16-char key for a unique server configuration.
@@ -152,31 +219,82 @@ class ServerManager:
     and config gets its own isolated OpenCode instance. Instances are started
     on demand and reused when the same key is requested again.
 
-    The registry is the single source of truth. There is no in-memory cache —
-    every call consults the registry so that external actors (CLI stop-all,
-    another process) are always reflected immediately.
+    The registry is the single source of truth for server state — there is
+    no in-memory cache of it, so every call consults the registry and
+    external actors (CLI stop-all, another process) are always reflected
+    immediately. The one piece of instance state this class keeps is
+    _owned — which keys *this instance* actually spawned via get_or_start(),
+    as opposed to attaching to a server already running elsewhere — so that
+    callers like OpenCodeRuntime.close() can stop what they started without
+    touching servers owned by someone else.
     """
 
-    def find(self, key: str) -> RegistryEntry | None:
-        """Return the registry entry for key, or None if not found."""
-        from .registry import read as registry_read
+    def __init__(self) -> None:
+        self._owned: set[str] = set()
 
-        return registry_read(key)
+    def find(self, key: str) -> RegistryEntry | None:
+        """Return the registry entry for key, or None if not found or still starting."""
+        entry = registry.read(key)
+        return entry if entry is not None and entry.state == ServerState.RUNNING else None
 
     def is_alive(self, key: str) -> bool:
         """Return True if the server for key is running."""
-        from .registry import is_alive
-        from .registry import read as registry_read
+        entry = self.find(key)
+        return entry is not None and registry.is_alive(entry.pid)
+
+    def touch(self, key: str) -> None:
+        """Update last_used_at timestamp for a server. Call after session creation."""
+        entry = registry.read(key)
+        if entry is not None and entry.state == ServerState.RUNNING:
+            entry.last_used_at = registry.now_iso()
+            registry.write(entry)
+
+    async def _status_for_entry(
+        self, entry: RegistryEntry, *, health_timeout: float = 3.0
+    ) -> ServerStatus:
+        """Derive a ServerStatus for an already-fetched registry entry."""
+        process_alive = (
+            _is_process_alive(entry.pid) if entry.state == ServerState.RUNNING else False
+        )
+        health_ok = False
+        if process_alive:
+            client = OpenCodeClient(
+                base_url=f"http://127.0.0.1:{entry.port}",
+                password=entry.password,
+            )
+            health_ok = await _is_health_ok(client, timeout=health_timeout)
+        display = _compute_display_status(entry.state, process_alive, health_ok)
+        return ServerStatus(
+            entry=entry, process_alive=process_alive, health_ok=health_ok, display=display
+        )
 
-        entry = registry_read(key)
-        return entry is not None and is_alive(entry.pid)
+    async def status(self, key: str, *, health_timeout: float = 3.0) -> ServerStatus | None:
+        """Return the computed status for key, or None if not in the registry."""
+        entry = registry.read(key)
+        if entry is None:
+            return None
+        return await self._status_for_entry(entry, health_timeout=health_timeout)
+
+    # NOTE: list() and list_statuses() must stay defined in this order — once
+    # `list` is bound as a class attribute (the method below), any later
+    # annotation in this class body that writes the bare name `list[...]`
+    # resolves to that method, not the builtin (see the Materials alias note
+    # up top for the same issue). list_statuses()'s `-> list[ServerStatus]`
+    # return annotation is defined above list() to avoid it.
+    async def list_statuses(self, *, health_timeout: float = 1.0) -> list[ServerStatus]:
+        """Return computed status for every ready registry entry."""
+        return [
+            await self._status_for_entry(entry, health_timeout=health_timeout)
+            for entry, _ in self.list()
+        ]
 
     def list(self) -> list[tuple[RegistryEntry, bool]]:
-        """Return all registry entries with their liveness status."""
-        from .registry import is_alive
-        from .registry import list_all
-
-        return [(entry, is_alive(entry.pid)) for entry in list_all()]
+        """Return all ready registry entries with their liveness status."""
+        return [
+            (entry, registry.is_alive(entry.pid))
+            for entry in registry.list_all()
+            if entry.state == ServerState.RUNNING
+        ]
 
     async def health(self, key: str) -> dict[str, Any]:
         """Return health info for the server at key.
@@ -184,13 +302,7 @@ class ServerManager:
         Raises ``OpenCodeServerError`` if key is not in the registry or the
         server is unreachable.
         """
-        import httpx
-
-        from .client import OpenCodeClient
-        from .exceptions import OpenCodeServerError
-        from .registry import read as registry_read
-
-        entry = registry_read(key)
+        entry = self.find(key)
         if entry is None:
             raise OpenCodeServerError(f"server {key!r} not found in registry")
 
@@ -209,21 +321,15 @@ class ServerManager:
         Returns True if the process was alive and killed, False if it was
         already dead or not found in the registry.
         """
-        from .registry import delete as registry_delete
-        from .registry import is_alive
-        from .registry import read as registry_read
-
-        entry = registry_read(key)
+        entry = registry.read(key)
         if entry is None:
             return False
 
-        registry_delete(key)
+        registry.delete(key)
 
-        if not is_alive(entry.pid):
+        if entry.pid is None or not registry.is_alive(entry.pid):
             return False
 
-        import signal
-
         try:
             os.kill(entry.pid, signal.SIGTERM)
         except ProcessLookupError:
@@ -231,7 +337,7 @@ class ServerManager:
         # Wait for the process to exit (up to 5s, then SIGKILL).
         deadline = asyncio.get_event_loop().time() + 5.0
         while asyncio.get_event_loop().time() < deadline:
-            if not is_alive(entry.pid):
+            if not registry.is_alive(entry.pid):
                 return True
             await asyncio.sleep(0.1)
         try:
@@ -242,54 +348,112 @@ class ServerManager:
 
     async def stop_all(self) -> None:
         """Kill all servers tracked in the registry."""
-        from .registry import list_all
-
-        for entry in list_all():
+        for entry in registry.list_all():
             await self.stop(entry.key)
 
+    async def stop_owned(self) -> None:
+        """Stop every server this instance itself spawned via get_or_start().
+
+        Servers this instance merely attached to — already running, started
+        by another process or the CLI — are left alone.
+        """
+        for key in list(self._owned):
+            await self.stop(key)
+        self._owned.clear()
+
     async def get_or_start(
         self,
         *,
         key: str,
         project_dir: Path,
         server_dir: Path | None,
-        materials: str | Path | list[str | Path] | None,
+        materials: Materials,
         config: dict[str, Any],
         env: dict[str, str],
         workspace: str | None = None,
         user_id: str | None = None,
     ) -> _ManagedServer:
         """Return a client for the running server, starting one if needed."""
-        from .client import OpenCodeClient
-        from .registry import delete as registry_delete
-        from .registry import is_alive
-        from .registry import read as registry_read
-
-        entry = registry_read(key)
-        if entry is not None and is_alive(entry.pid):
-            return _ManagedServer(
+        entry = registry.read(key)
+        if entry is not None and entry.state == ServerState.RUNNING:
+            if registry.is_alive(entry.pid):
+                return self._attach(entry)
+            # Stale — the process died after finishing startup.
+            registry.delete(key)
+
+        # port/password are generated here (not inside _start) because a
+        # 'starting' claim row needs both up front — pid is the only field
+        # that isn't known until the subprocess actually exists.
+        port = _find_free_port()
+        password = secrets.token_urlsafe(32)
+        timestamp = registry.now_iso()
+
+        claimed = registry.claim_starting(
+            RegistryEntry(
                 key=key,
-                process=None,
-                client=OpenCodeClient(
-                    base_url=f"http://127.0.0.1:{entry.port}",
-                    password=entry.password,
-                ),
-                server_dir=Path(entry.server_dir) if entry.server_dir else None,
+                state=ServerState.STARTING,
+                pid=None,
+                port=port,
+                password=password,
+                project_dir=str(project_dir),
+                server_dir=str(server_dir) if server_dir else None,
+                started_at=timestamp,
+                claimed_at=timestamp,
+                workspace=workspace,
+                user_id=user_id,
             )
+        )
+        if not claimed:
+            # Another caller is already starting this key — wait for it
+            # instead of racing to spawn a second process for the same key.
+            return await self._wait_for_ready(key)
 
-        # Not running — clean up stale registry entry and start fresh.
-        if entry is not None:
-            registry_delete(key)
+        try:
+            server = await self._start(
+                key=key,
+                project_dir=project_dir,
+                server_dir=server_dir,
+                materials=materials,
+                config=config,
+                env=env,
+                port=port,
+                password=password,
+                workspace=workspace,
+                user_id=user_id,
+            )
+        except Exception:
+            registry.delete(key)
+            raise
+        self._owned.add(key)
+        return server
 
-        return await self._start(
-            key=key,
-            project_dir=project_dir,
-            server_dir=server_dir,
-            materials=materials,
-            config=config,
-            env=env,
-            workspace=workspace,
-            user_id=user_id,
+    def _attach(self, entry: RegistryEntry) -> _ManagedServer:
+        """Build a _ManagedServer client for an already-running registry entry."""
+        return _ManagedServer(
+            key=entry.key,
+            process=None,
+            client=OpenCodeClient(
+                base_url=f"http://127.0.0.1:{entry.port}",
+                password=entry.password,
+            ),
+            server_dir=Path(entry.server_dir) if entry.server_dir else None,
+        )
+
+    async def _wait_for_ready(self, key: str, timeout: float = 60.0) -> _ManagedServer:
+        """Poll the registry until the caller holding the start-claim finishes."""
+        deadline = asyncio.get_event_loop().time() + timeout
+        while asyncio.get_event_loop().time() < deadline:
+            entry = registry.read(key)
+            if entry is None:
+                raise OpenCodeServerError(
+                    f"the caller starting server {key!r} failed before it became ready"
+                )
+            if entry.state == ServerState.RUNNING and registry.is_alive(entry.pid):
+                return self._attach(entry)
+            await asyncio.sleep(0.1)
+
+        raise OpenCodeTimeoutError(
+            f"timed out waiting for another caller to start the server for key {key!r}"
         )
 
     async def _start(
@@ -298,44 +462,33 @@ class ServerManager:
         key: str,
         project_dir: Path,
         server_dir: Path | None,
-        materials: str | Path | list[str | Path] | None,
+        materials: Materials,
         config: dict[str, Any],
         env: dict[str, str],
+        port: int,
+        password: str,
         workspace: str | None = None,
         user_id: str | None = None,
     ) -> _ManagedServer:
         """Start a new OpenCode instance and return a _ManagedServer."""
-        from .client import OpenCodeClient
-        from .exceptions import OpenCodeNotFoundError
-
         if shutil.which("opencode") is None:
             raise OpenCodeNotFoundError(
                 "opencode binary not found on PATH. Install it with: npm install -g opencode-ai"
             )
 
-        if server_dir is not None:
-            server_dir.mkdir(parents=True, exist_ok=True)
-            (server_dir / "tmp").mkdir(exist_ok=True)
-            _prepare_dir(server_dir, config, materials)
-
-        port = _find_free_port()
-        password = secrets.token_urlsafe(32)
-
         process_env = {**os.environ, **env}
         process_env["OPENCODE_SERVER_PASSWORD"] = password
 
         if server_dir is not None:
+            server_dir.mkdir(parents=True, exist_ok=True)
+            (server_dir / "tmp").mkdir(exist_ok=True)
+            _prepare_dir(server_dir, config, materials)
             process_env["HOME"] = str(server_dir)
             process_env["TMPDIR"] = str(server_dir / "tmp")
             process_env["OPENCODE_CONFIG"] = str(server_dir / "opencode.json")
-
-        if server_dir is not None:
-            log_file = open(server_dir / "opencode.log", "ab")
-            stdout = log_file
-            stderr = log_file
+            output: Any = open(server_dir / "opencode.log", "ab")
         else:
-            stdout = asyncio.subprocess.DEVNULL
-            stderr = asyncio.subprocess.DEVNULL
+            output = asyncio.subprocess.DEVNULL
 
         process = await asyncio.create_subprocess_exec(
             "opencode",
@@ -346,8 +499,8 @@ class ServerManager:
             str(port),
             cwd=str(project_dir),
             env=process_env,
-            stdout=stdout,
-            stderr=stderr,
+            stdout=output,
+            stderr=output,
         )
 
         client = OpenCodeClient(
@@ -369,18 +522,20 @@ class ServerManager:
             await _terminate_process(process)
             raise
 
-        from .registry import RegistryEntry, now_iso
-        from .registry import write as registry_write
-
-        registry_write(
+        timestamp = registry.now_iso()
+        registry.write(
             RegistryEntry(
                 key=key,
+                state=ServerState.RUNNING,
                 pid=process.pid,
                 port=port,
                 password=password,
                 project_dir=str(project_dir),
                 server_dir=str(server_dir) if server_dir else None,
-                started_at=now_iso(),
+                started_at=timestamp,
+                claimed_at=timestamp,
+                last_used_at=timestamp,
+                runtime_version=version("opencode-runtime"),
                 workspace=workspace,
                 user_id=user_id,
             )

opencode_runtime/session.py

@@ -147,6 +147,6 @@ class OpenCodeSession:
         if self.session_id is not None:
             await self._client.post(f"/session/{self.session_id}/abort", {})
 
-    async def close(self) -> None:
-        """Release conversation-level resources."""
+    async def reset(self) -> None:
+        """Forget the current conversation. The next ask()/stream() call starts a new one."""
         self.session_id = None

{opencode_runtime-0.4.1.dist-info → opencode_runtime-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-runtime
-Version: 0.4.1
+Version: 0.5.0
 Summary: Embed OpenCode in your Python application.
 Project-URL: Homepage, https://github.com/ashish16052/opencode-runtime
 Project-URL: Repository, https://github.com/ashish16052/opencode-runtime
@@ -91,14 +91,15 @@ opencode-runtime ps
 ```
 
 ```
-  ID                  PID    PORT    STATUS     UPTIME    WORKSPACE   USER    PROJECT
-  ──────────────────────────────────────────────────────────────────────────────────
-  39dce5beb4debfaa   12051   58409   ● alive    Up 5m     org_a       u_1     ~/Developer/myproject
-  81fa29acb3e9210f   12088   58411   ● alive    Up 3m     org_b       u_2     ~/Developer/myproject
+  ID                  PID    PORT    STATUS      UPTIME    WORKSPACE   USER    PROJECT
+  ───────────────────────────────────────────────────────────────────────────────────
+  39dce5beb4debfaa   12051   58409   ● running   5m        org_a       u_1     ~/Developer/myproject
+  81fa29acb3e9210f   12088   58411   ● running   3m        org_b       u_2     ~/Developer/myproject
 ```
 
 ```sh
 opencode-runtime health 39dce5beb4debfaa
+opencode-runtime inspect 39dce5beb4debfaa
 opencode-runtime stop-all
 ```
 

opencode_runtime-0.5.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+opencode_runtime/__init__.py,sha256=fK91fH2ELtCTVAlMQet6T1N8A4P9phbocbZvKJVXpRI,362
+opencode_runtime/cli.py,sha256=tRrDaolRx_EEByAeWiIHaw7i-HVtCkFR_hTMnQsvIiI,13446
+opencode_runtime/client.py,sha256=EJ9bRsItC8_AdeYLSXTLNllEjlo5xlbLc6jsAuv7EcE,9124
+opencode_runtime/event.py,sha256=6-mIAGEURP-sfj2zGABe1O8h9Phd2ao0iqmDOr1PDGI,763
+opencode_runtime/exceptions.py,sha256=d6X7SFVnzUM_OHNzAuJ_qTkhRID1yNPchIaTepYGD4o,753
+opencode_runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+opencode_runtime/registry.py,sha256=-tymxyEM6bd6KHLB5Gao5lav83hnPB5NtUlu8I-q6WQ,6292
+opencode_runtime/response.py,sha256=MmT4qiakWD55J8cFg64VOztusfWkynrucdjbm0srNks,541
+opencode_runtime/runtime.py,sha256=4b4c-cdZyUvTfy-GoWJwvgowm5wQCucP5llAV_dSSts,5488
+opencode_runtime/schema.py,sha256=xPTKUKdgW9Oo0YqNBsO4vqIZ4fwJFBbxnt7iv1u3bSE,2889
+opencode_runtime/server.py,sha256=DKVaJk29peJ0QsqfQBNnzPOVygBwQetM4rmTVCJra4s,19139
+opencode_runtime/session.py,sha256=wUNgh6q12_ZqHitlPVJ-axRxK6XL30ll4nvwqFHRXXw,5819
+opencode_runtime-0.5.0.dist-info/METADATA,sha256=HcCuN-_IT3sRAWE_Gt6XBzjHIgLQyWDa7zvmhLkl9tI,4227
+opencode_runtime-0.5.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+opencode_runtime-0.5.0.dist-info/entry_points.txt,sha256=4lbdu1KELOg8TD6F7gC-Xrt3VJXdk3RTaH8cQHVy-Tc,63
+opencode_runtime-0.5.0.dist-info/licenses/LICENSE,sha256=EVYfwpsynn_pB9fQ0OhMX-ghTZM10CrFAPv1JbLODi4,11343
+opencode_runtime-0.5.0.dist-info/RECORD,,

opencode_runtime-0.4.1.dist-info/RECORD

@@ -1,16 +0,0 @@
-opencode_runtime/__init__.py,sha256=RNZO_09NXusYD_xhbeJLb2HCp_0JeogNEi6247mPcL4,362
-opencode_runtime/cli.py,sha256=byy2ezufQvk5f_e1nwDN8ZIFflIwgvuC9SX7HQGYTkU,8938
-opencode_runtime/client.py,sha256=XZw413XiTOaAeKY5WufmMFsDAlullel50i_N5A0wYyM,9069
-opencode_runtime/event.py,sha256=7tWTLXTVUB6g3Ni7jiG2VYdHhjU9rpiwrY0MT1RnEMQ,960
-opencode_runtime/exceptions.py,sha256=uarBFCh8ovI3w4ZB4oQuffv97-5nwTdkZQrkBcOWtWs,471
-opencode_runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-opencode_runtime/registry.py,sha256=rxr3D4iqceskmPBYvRC_lbtME8hoMR4I6rsdYCqllLA,2309
-opencode_runtime/response.py,sha256=MmT4qiakWD55J8cFg64VOztusfWkynrucdjbm0srNks,541
-opencode_runtime/runtime.py,sha256=magKzC-kN7g9bsttNhSLEif9hD92_qrHgJgvXDOauYU,5255
-opencode_runtime/server.py,sha256=eu2JwLwkpICRviZx4OmN2z2_gVWCkfnm4qhcQRW3bSw,12595
-opencode_runtime/session.py,sha256=9ES_mVvXWFhLPNnFFY9KwvRi_4zoVNTe8EToU8oe3ng,5777
-opencode_runtime-0.4.1.dist-info/METADATA,sha256=IkOu8zi4YGNidowr_OUYpypcvCYsq4R1-z8ul8-ocZc,4179
-opencode_runtime-0.4.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-opencode_runtime-0.4.1.dist-info/entry_points.txt,sha256=4lbdu1KELOg8TD6F7gC-Xrt3VJXdk3RTaH8cQHVy-Tc,63
-opencode_runtime-0.4.1.dist-info/licenses/LICENSE,sha256=EVYfwpsynn_pB9fQ0OhMX-ghTZM10CrFAPv1JbLODi4,11343
-opencode_runtime-0.4.1.dist-info/RECORD,,