opencode-runtime 0.4.0__tar.gz → 0.5.0__tar.gz

{opencode_runtime-0.4.0 → opencode_runtime-0.5.0}/.github/workflows/ci.yml

@@ -1,8 +1,10 @@
 name: ci
 
 on:
-  push:
   pull_request:
+  push:
+    branches:
+      - main
 
 jobs:
   ci:

{opencode_runtime-0.4.0 → opencode_runtime-0.5.0}/.gitignore

@@ -38,7 +38,7 @@ MANIFEST
 *.whl
 
 # opencode-runtime runtime state
-.opencode-runtime/
+.opencode-runtime/*
 
 # macOS
 .DS_Store

{opencode_runtime-0.4.0 → opencode_runtime-0.5.0}/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## [Unreleased]
+## [0.5.0]
+
+### Added
+- SQLite-backed server registry at `~/.opencode-runtime/servers/registry.db` — persistent, atomic, supports concurrent claims
+- `ServerState` enum (STARTING, RUNNING, STOPPING, FAILED) for type-safe state tracking
+- Health probes: process liveness check + HTTP health endpoint verification; display status shows running/starting/unhealthy/stale/failed
+- `inspect` command: detailed server info (PID, port, uptime, idle time, runtime version, health)
+- Server metadata: track `runtime_version` and `last_used_at` timestamp
+
+### Changed
+- Registry moved from PID files to SQLite — no API changes, same registry operations
+- All state tracking uses `ServerState` enum instead of string literals (type safety)
+- Server startup now lazy — contexts don't auto-create default server, start on first `session()` call
+- `runtime.close()` now stops only servers that `OpenCodeRuntime` instance itself started; servers it merely attached to (already running, started by another process or the CLI) are left alone (safe for multi-process deployments)
+
+### Fixed
+- one `OpenCodeRuntime` exiting would terminate servers created by other processes or CLI — now scoped to servers it actually started
+
+## [0.4.1] - 2026-07-09
+
+### Fixed
+- `server.py`: set `OPENCODE_CONFIG` env var instead of the unrecognised `OPENCODE_CONFIG_HOME` — without this fix the `config` dict (model, permissions, etc.) was never read by the opencode binary, silently ignored every time
+- `client.py`: SSE stream now terminates only on `session.idle` or `session.error`; previously `session.status {type: "idle"}` caused the generator to exit early, dropping any events that followed — including `permission.asked`
+- `session.py`: `ask()` now propagates the real server error message from `event.raw["properties"]["error"]`; previously it always raised the generic fallback `"unknown error from opencode server"` because `event.text` is always `None` for `session.error` events
 
 ## [0.4.0] - 2026-07-07
 

opencode_runtime-0.5.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: opencode-runtime
+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
+Project-URL: Issues, https://github.com/ashish16052/opencode-runtime/issues
+Author: Ashish Mohite
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: AI coding agent,agent runtime,lifecycle management,multi-user,opencode,workspace isolation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-timeout; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opencode-runtime
+
+**Embed OpenCode in your Python application.**
+
+OpenCode is a great CLI coding agent. But to embed it in a product, SaaS
+backend, or multi-user automation system, you need more than a CLI process.
+
+opencode-runtime turns OpenCode into a managed application runtime for
+Python. It uses OpenCode as the agent harness and adds what you need to
+run it as part of an application: lifecycle management, per-user
+workspaces, reusable sessions, health checks, streaming output, and
+multi-server orchestration.
+
+## Install
+
+```sh
+pip install opencode-runtime
+npm install -g opencode-ai   # opencode must be on PATH
+```
+
+## Use
+
+### Your first session
+
+```python
+from opencode_runtime import OpenCodeRuntime
+
+async with OpenCodeRuntime() as r:
+    session = await r.session()
+    response = await session.ask("Explain this repo")
+    print(response.text)
+```
+
+### One server per user, automatically
+
+Every `(workspace, user_id)` pair gets its own isolated server, workspace, and conversation history — started on first use, reused after:
+
+```python
+async with OpenCodeRuntime(runtime_dir=".opencode-runtime") as r:
+    s1 = await r.session(workspace="org_a", user_id="u_1")
+    s2 = await r.session(workspace="org_b", user_id="u_2")
+```
+
+### Stream every token as it arrives
+
+```python
+async for event in session.stream("Review this PR"):
+    if event.type == "message.part.delta" and event.text:
+        print(event.text, end="", flush=True)
+```
+
+## Inspect
+
+Servers started from Python are visible and manageable from the terminal:
+
+```sh
+opencode-runtime ps
+```
+
+```
+  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
+```
+
+## Guides
+
+- [OpenCode config](docs/opencode-config.md) — models, permissions, agents, skills
+- [Sessions](docs/sessions.md) — continuation, resume across restarts
+- [Users & workspaces](docs/users-and-workspaces.md) — multi-tenant isolation
+- [Streaming](docs/streaming.md) — event types, tool calls, permissions, cost
+- [CLI](docs/cli.md) — manage your fleet from the terminal
+- [HTTP client](docs/http-client.md) — direct server access
+
+## Requirements
+
+- Python 3.10+
+- `opencode` 1.0+ on PATH
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+Apache 2.0

opencode_runtime-0.5.0/README.md

@@ -0,0 +1,93 @@
+# opencode-runtime
+
+**Embed OpenCode in your Python application.**
+
+OpenCode is a great CLI coding agent. But to embed it in a product, SaaS
+backend, or multi-user automation system, you need more than a CLI process.
+
+opencode-runtime turns OpenCode into a managed application runtime for
+Python. It uses OpenCode as the agent harness and adds what you need to
+run it as part of an application: lifecycle management, per-user
+workspaces, reusable sessions, health checks, streaming output, and
+multi-server orchestration.
+
+## Install
+
+```sh
+pip install opencode-runtime
+npm install -g opencode-ai   # opencode must be on PATH
+```
+
+## Use
+
+### Your first session
+
+```python
+from opencode_runtime import OpenCodeRuntime
+
+async with OpenCodeRuntime() as r:
+    session = await r.session()
+    response = await session.ask("Explain this repo")
+    print(response.text)
+```
+
+### One server per user, automatically
+
+Every `(workspace, user_id)` pair gets its own isolated server, workspace, and conversation history — started on first use, reused after:
+
+```python
+async with OpenCodeRuntime(runtime_dir=".opencode-runtime") as r:
+    s1 = await r.session(workspace="org_a", user_id="u_1")
+    s2 = await r.session(workspace="org_b", user_id="u_2")
+```
+
+### Stream every token as it arrives
+
+```python
+async for event in session.stream("Review this PR"):
+    if event.type == "message.part.delta" and event.text:
+        print(event.text, end="", flush=True)
+```
+
+## Inspect
+
+Servers started from Python are visible and manageable from the terminal:
+
+```sh
+opencode-runtime ps
+```
+
+```
+  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
+```
+
+## Guides
+
+- [OpenCode config](docs/opencode-config.md) — models, permissions, agents, skills
+- [Sessions](docs/sessions.md) — continuation, resume across restarts
+- [Users & workspaces](docs/users-and-workspaces.md) — multi-tenant isolation
+- [Streaming](docs/streaming.md) — event types, tool calls, permissions, cost
+- [CLI](docs/cli.md) — manage your fleet from the terminal
+- [HTTP client](docs/http-client.md) — direct server access
+
+## Requirements
+
+- Python 3.10+
+- `opencode` 1.0+ on PATH
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+Apache 2.0

opencode_runtime-0.5.0/docs/cli.md

@@ -0,0 +1,120 @@
+# CLI
+
+Every server your Python app starts is also visible and controllable from the terminal — same registry, no separate daemon. The CLI is how you operate your OpenCode fleet in production: inspect running servers, health-check tenants, drain a workspace, or kill everything before a deploy.
+
+Think of it as `kubectl` for your OpenCode fleet.
+
+## See everything that's running
+
+```sh
+opencode-runtime ps
+```
+
+```
+  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
+  c3f2a1d9e8b74f05   13204   58413   ● running   1h        org_c       u_3     ~/Developer/myproject
+```
+
+Every server your Python app has started — across all users and workspaces — is visible here. PID, port, uptime, which tenant, which user, which project. No guessing, no digging through logs.
+
+## Health check a specific server
+
+```sh
+opencode-runtime health 39dce5beb4debfaa
+```
+
+Hit the health endpoint of any server by ID. Use this in a monitoring script, a deployment check, or just to verify a server is responsive after a spike in traffic.
+
+Pipe it into your alerting:
+
+```sh
+opencode-runtime health 39dce5beb4debfaa || pagerduty-alert "opencode server down"
+```
+
+## Inspect a server in detail
+
+`health` tells you if a server is up; `inspect` tells you everything else — uptime, idle time, runtime version, log file location:
+
+```sh
+opencode-runtime inspect 39dce5beb4debfaa
+```
+
+```
+  ID         39dce5beb4debfaa
+  Status     ● running
+  Project    ~/Developer/myproject
+  Workspace  org_a
+  User       u_1
+  PID        12051
+  Port       58409
+  Uptime     5m 12s
+  Last used  30s ago
+```
+
+## Start a server manually
+
+Spin up a server outside of Python — useful for pre-warming tenants before they hit your API, or for running one-off tasks from the terminal:
+
+```sh
+opencode-runtime serve --workspace acme --user-id alice
+```
+
+The server registers in the same shared registry your Python app uses. When your app later calls `r.session(workspace="acme", user_id="alice")`, it reuses the already-running server instead of starting a new one.
+
+## Drain a tenant
+
+A tenant is causing runaway resource usage. Stop their server without touching any other tenant:
+
+```sh
+# find the server
+opencode-runtime ps | grep acme
+
+# stop just that one
+opencode-runtime stop 39dce5beb4debfaa
+```
+
+Next request from that tenant will cold-start a fresh server — clean slate, no lingering state.
+
+## Emergency stop
+
+Deploy gone wrong. A bug is spawning servers faster than expected. Kill everything instantly:
+
+```sh
+opencode-runtime stop-all
+```
+
+All servers stopped, all ports freed. Your app will restart them on next use.
+
+## Use as a sidecar in production
+
+The CLI reads from the same registry as the Python library — no separate daemon, no IPC. Run it alongside your application in any environment:
+
+```sh
+# in one terminal — your app
+python app.py
+
+# in another — live monitoring
+watch -n 5 opencode-runtime ps
+```
+
+Or wire it into your infra tooling. The `ps` output is structured enough to parse, `health` exits non-zero on failure, and `stop`/`stop-all` are safe to call from scripts or runbooks.
+
+```sh
+# runbook: drain all servers before a deploy
+opencode-runtime stop-all
+deploy.sh
+```
+
+## Command reference
+
+| Command | Description |
+|---|---|
+| `opencode-runtime ps` | List all running servers with ID, PID, port, status, uptime, workspace, user, project |
+| `opencode-runtime serve` | Start a background server. Accepts `--workspace`, `--user-id` |
+| `opencode-runtime health <id>` | Health check a server by ID. Exits non-zero if unhealthy |
+| `opencode-runtime inspect <id>` | Show detailed info for a server: uptime, idle time, runtime version, log file |
+| `opencode-runtime stop <id>` | Stop a specific server by ID |
+| `opencode-runtime stop-all` | Stop all running servers |

opencode_runtime-0.5.0/docs/http-client.md

@@ -0,0 +1,96 @@
+# Raw client
+
+`session.raw_client` gives you direct access to every OpenCode server endpoint — anything not covered by `ask()` and `stream()`. It exposes two methods: `get(path)` and `post(path, body)`, both return parsed JSON.
+
+The examples below follow a single story: a code review backend that receives a PR, runs an agent review, tracks progress, stores the result, and handles rollback.
+
+```python
+from opencode_runtime import OpenCodeRuntime
+
+async with OpenCodeRuntime(runtime_dir=".opencode-runtime") as r:
+    session = await r.session(workspace="acme", user_id="alice")
+    client = session.raw_client
+```
+
+## 1. Pick the right agent
+
+Before running the review, confirm which agents are available and pick the one best suited for the task:
+
+```python
+agents = await client.get("/agent")
+review_agents = [a for a in agents if "review" in a["name"].lower()]
+
+# fall back to "plan" (read-only, no edits) if no dedicated reviewer
+agent = review_agents[0]["name"] if review_agents else "plan"
+```
+
+## 2. Run the review
+
+Use the chosen agent for this specific call:
+
+```python
+response = await session.ask(
+    "Review this PR for security issues, logic bugs, and test coverage gaps",
+    agent=agent,
+)
+print(response.text)
+```
+
+## 3. Track todos
+
+For complex PRs, the agent creates a todo list as it works through the review. Poll it to show progress in your UI:
+
+```python
+todos = await client.get(f"/session/{session.session_id}/todo")
+for todo in todos:
+    icon = {"completed": "✓", "in_progress": "⟳", "pending": "○", "cancelled": "✗"}.get(todo["status"], "?")
+    print(f"  {icon} {todo['content']}")
+```
+
+## 4. Store the full conversation
+
+After the review, fetch the full message history to persist in your database — useful for audit trails, displaying review threads in your UI, or feeding into downstream pipelines:
+
+```python
+messages = await client.get(f"/session/{session.session_id}/message")
+for entry in messages:
+    info = entry["info"]
+    role = info["role"]
+    cost = info.get("cost", 0) if role == "assistant" else 0
+    text = next((p["text"] for p in entry["parts"] if p["type"] == "text"), "")
+    db.insert(session_id=session.session_id, role=role, text=text, cost=cost)
+```
+
+## 5. Revert if the agent made unwanted changes
+
+If the agent edited files as part of the review and you want to roll them back:
+
+```python
+messages = await client.get(f"/session/{session.session_id}/message")
+
+# revert to just before the last assistant turn
+message_id = messages[-2]["info"]["id"]
+await client.post(
+    f"/session/{session.session_id}/revert",
+    {"messageID": message_id},
+)
+```
+
+## 6. Report cost
+
+At the end of the review, read the final cost from the last assistant message for billing or quota tracking:
+
+```python
+messages = await client.get(f"/session/{session.session_id}/message")
+assistant_messages = [e for e in messages if e["info"]["role"] == "assistant"]
+
+if assistant_messages:
+    last = assistant_messages[-1]["info"]
+    cost = last.get("cost", 0)
+    tokens = last.get("tokens", {})
+    print(f"Review cost: ${cost:.5f} ({tokens.get('input', 0)} in / {tokens.get('output', 0)} out)")
+```
+
+## Full endpoint reference
+
+See the [OpenCode server docs](https://opencode.ai/docs/server) for all endpoints and the full type definitions in [types.gen.ts](https://github.com/anomalyco/opencode/blob/dev/packages/sdk/js/src/gen/types.gen.ts).

opencode_runtime-0.5.0/docs/opencode-config.md

@@ -0,0 +1,94 @@
+# Configuration & materials
+
+## Config
+
+Pass any valid `opencode.json` keys as a dict. opencode-runtime writes this as the server's config before starting. **`runtime_dir` must be set for config to take effect** — without it no config file is written.
+
+```python
+from opencode_runtime import OpenCodeRuntime
+
+async with OpenCodeRuntime(
+    runtime_dir=".opencode-runtime",
+    config={
+        "model": "anthropic/claude-sonnet-4-5",
+        "permission": {"bash": "deny"},
+    },
+) as r:
+    session = await r.session()
+    response = await session.ask("Analyse the architecture")
+    print(response.text)
+```
+
+See the [OpenCode config reference](https://opencode.ai/docs/config/) for all available keys.
+
+## Materials
+
+Pass a directory of OpenCode-native files and they are copied into the server before it starts. This is how you bring custom instructions, agents, and skills to a managed server.
+
+```python
+from opencode_runtime import OpenCodeRuntime
+
+async with OpenCodeRuntime(
+    runtime_dir=".opencode-runtime",
+    materials="./opencode-materials",
+) as r:
+    session = await r.session()
+    response = await session.ask("Follow the instructions in AGENTS.md")
+    print(response.text)
+```
+
+What can go in a materials directory:
+
+| File / path | Purpose | Docs |
+|---|---|---|
+| `opencode.json` | Server config (model, permissions, MCP servers, …) | [Config](https://opencode.ai/docs/config/) |
+| `AGENTS.md` | Rules and instructions included in every session | [Rules](https://opencode.ai/docs/rules/) |
+| `.opencode/agents/` | Custom agent definitions (markdown format) | [Agents](https://opencode.ai/docs/agents/#markdown) |
+| `.opencode/skills/` | Reusable skill definitions | [Agent Skills](https://opencode.ai/docs/skills/) |
+
+## project_dir
+
+The directory OpenCode runs against — the working directory of the subprocess. Defaults to `.` (wherever your Python process is running).
+
+```python
+async with OpenCodeRuntime(project_dir="/path/to/repo") as r:
+    session = await r.session()
+    response = await session.ask("What does this project do?")
+    print(response.text)
+```
+
+**When to use:** when your Python backend runs from a different location than the repo you want OpenCode to work on — for example, a service that checks out customer repos to a temp directory and points OpenCode at each one.
+
+## runtime_dir
+
+When set, each server gets its own isolated `HOME` and config file (`opencode.json`) under `runtime_dir/servers/<key>/`. Without it, OpenCode uses your real user environment and any `config` or `materials` passed to the runtime are ignored.
+
+```python
+async with OpenCodeRuntime(runtime_dir=".opencode-runtime") as r:
+    session = await r.session()
+    response = await session.ask("What does this project do?")
+    print(response.text)
+```
+
+**When to use:** any multi-user or production setup. Without `runtime_dir`, all servers share your real home directory — meaning shared OpenCode config, shared history, and API keys from your personal environment. Setting it gives every server a clean, isolated slate.
+
+## Session-level overrides
+
+`config`, `materials`, and `env` can all be overridden per session. Session config is shallow-merged with runtime config; session materials replace runtime materials; session env is merged with runtime env. Session keys win in all cases.
+
+```python
+async with OpenCodeRuntime(
+    config={"model": "anthropic/claude-sonnet-4-5"},
+    materials="./base-materials",
+    env={"API_KEY": "default"},
+) as r:
+    session = await r.session(
+        config={"model": "anthropic/claude-opus-4-5"},
+        materials="./org-a-materials",
+        env={"API_KEY": "org-a-key"},
+    )
+    response = await session.ask("Analyse the architecture")
+    print(response.text)
+```
+
+Note: `config` and `materials` affect server identity — different values produce a separate server process. `env` does not; if the server is already running, a different `env` passed to `session()` has no effect.

opencode_runtime-0.5.0/docs/sessions.md

@@ -0,0 +1,102 @@
+# Sessions
+
+## Single ask
+
+The simplest usage — send a message, get a response:
+
+```python
+from opencode_runtime import OpenCodeRuntime
+
+async with OpenCodeRuntime() as r:
+    session = await r.session()
+    response = await session.ask("What does this project do?")
+    print(response.text)
+```
+
+`response.text` is the full assistant reply. `response.raw` contains all raw events if you need them (tool calls, thinking, status updates).
+
+## Multi-turn conversation
+
+Multiple `ask()` calls on the same session continue the same conversation — OpenCode keeps the full history server-side:
+
+```python
+async with OpenCodeRuntime() as r:
+    session = await r.session()
+    await session.ask("Explain this repo's architecture")
+    await session.ask("Which file handles authentication?")  # has full context
+    response = await session.ask("What would you change about it?")
+    print(response.text)
+```
+
+To start a fresh independent conversation, get a new session:
+
+```python
+async with OpenCodeRuntime() as r:
+    session_a = await r.session()  # conversation A
+    session_b = await r.session()  # conversation B — isolated, no shared history
+```
+
+## Resume across restarts
+
+`session_id` is set after the first `ask()` or `stream()` call. Persist it to resume the conversation later:
+
+```python
+# First run
+async with OpenCodeRuntime() as r:
+    session = await r.session()
+    await session.ask("Explain this repo")
+    saved_id = session.session_id  # store in your DB
+
+# Later — picks up the same conversation
+async with OpenCodeRuntime() as r:
+    session = await r.session(session_id=saved_id)
+    response = await session.ask("Where did we get to?")
+    print(response.text)
+```
+
+## Per-message overrides
+
+`ask()` and `stream()` accept per-message overrides for model, agent, tools, and system prompt. These apply to that message only — they don't change the session's config:
+
+```python
+async with OpenCodeRuntime() as r:
+    session = await r.session()
+
+    # use a specific agent for one task
+    review = await session.ask(
+        "Review this PR for security issues",
+        agent="security-auditor",
+    )
+
+    # override model for a single expensive call
+    deep = await session.ask(
+        "Redesign the auth module",
+        model="anthropic/claude-opus-4-5",
+    )
+
+    # disable bash for one call
+    safe = await session.ask(
+        "Summarise the test coverage",
+        tools={"bash": False},
+    )
+```
+
+## Abort
+
+Cancel a running session mid-flight:
+
+```python
+import asyncio
+from opencode_runtime import OpenCodeRuntime
+
+async with OpenCodeRuntime() as r:
+    session = await r.session()
+
+    async def run():
+        await session.ask("Refactor the entire codebase")
+
+    task = asyncio.create_task(run())
+    await asyncio.sleep(5)
+    await session.abort()   # cancels the in-progress session server-side
+    task.cancel()
+```