ouroboros-ai 0.28.1.dev2__tar.gz → 0.28.1.dev4__tar.gz

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/CONTRIBUTING.md

@@ -551,7 +551,7 @@ Changes under `src/ouroboros/orchestrator/` affect runtime behavior documentatio
 | `runtime_factory.py` | `docs/runtime-capability-matrix.md`, `docs/runtime-guides/claude-code.md`, `docs/runtime-guides/codex.md` — if a backend is added, removed, or changes its `NotImplementedError` status |
 | `adapter.py` (`ClaudeAgentAdapter`) | `docs/runtime-guides/claude-code.md` — permission modes, session flow |
 | `codex_cli_runtime.py` (`CodexCliRuntime`) | `docs/runtime-guides/codex.md` — permission modes, `--runtime codex` behavior |
-| `opencode_runtime.py` (`OpenCodeRuntime`) | `docs/runtime-capability-matrix.md` — mark `[Not yet available]` until `NotImplementedError` is removed; `docs/runtime-guides/` — create guide only when fully shipped |
+| `opencode_runtime.py` (`OpenCodeRuntime`) | `docs/runtime-capability-matrix.md`, `docs/runtime-guides/opencode.md` — permission modes, `--runtime opencode` behavior |
 | `runner.py` (`OrchestratorRunner`) | `docs/architecture.md` — orchestration lifecycle; `docs/getting-started.md` — session ID output, resume flow |
 | `parallel_executor.py` | `docs/cli-reference.md` — `--sequential` flag behavior; `docs/architecture.md` — parallel execution strategy |
 | `coordinator.py` (`LevelCoordinator`) | `docs/architecture.md` — inter-level conflict resolution and coordinator review gate |
@@ -563,7 +563,7 @@ Changes under `src/ouroboros/orchestrator/` affect runtime behavior documentatio
 | `command_dispatcher.py` | `docs/architecture.md` — command dispatch model |
 | `level_context.py` | `docs/architecture.md` — level context description |
 
-**Runtime availability rule**: If `create_agent_runtime()` raises `NotImplementedError` for a backend, that backend **must not** appear in docs as a working option. Currently `opencode` is unimplemented — it must be marked `[Not yet available]` wherever documented.
+**Runtime availability rule**: If `create_agent_runtime()` raises `NotImplementedError` for a backend, that backend **must not** appear in docs as a working option. All three backends (`claude`, `codex`, `opencode`) are fully implemented and documented.
 
 ---
 
@@ -703,7 +703,7 @@ To catch doc drift during development, reviewers should check:
 
 1. **Flag parity**: Run `ouroboros <cmd> --help` and compare every flag to `docs/cli-reference.md`. Any mismatch is a documentation bug.
 2. **Placeholder honesty**: If a command's implementation body is `# Placeholder implementation`, the corresponding doc entry must say `[Placeholder — not yet implemented]`.
-3. **Runtime parity**: `claude` and `codex` are the only fully-implemented backends. Any doc that lists `opencode` without a `[Not yet available]` marker is incorrect.
+3. **Runtime parity**: `claude`, `codex`, and `opencode` are all fully-implemented backends. Any doc that lists a backend as available must have a corresponding runtime guide in `docs/runtime-guides/`.
 4. **Config key drift**: After any change to `src/ouroboros/config/models.py`, grep for the changed key name across `docs/` to find stale references.
 5. **TUI key bindings**: If `screens/*.py` `BINDINGS` arrays change, verify `docs/guides/tui-usage.md` reflects the new keys.
 6. **Skills registry drift**: If a new `skills/*.yaml` file is added, check that `docs/runtime-guides/codex.md` or the relevant guide mentions it.

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.28.1.dev2
+Version: 0.28.1.dev4
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE
@@ -119,7 +119,7 @@ curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.
 > ooo interview "I want to build a task management CLI"
 ```
 
-> Works with Claude Code and Codex CLI. The installer detects your runtime, registers the MCP server, and installs skills automatically.
+> Works with Claude Code, Codex CLI, and OpenCode. The installer detects Claude Code and Codex CLI automatically and registers the MCP server. For OpenCode, run `ouroboros setup --runtime opencode` after installation.
 
 <details>
 <summary><strong>Other install methods</strong></summary>
@@ -143,7 +143,7 @@ ouroboros setup                         # configure runtime
 
 Legacy compatibility: `ouroboros-ai[dashboard]` is still accepted as a compatibility alias while extras migrate.
 
-See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md)
+See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md) · [OpenCode](./docs/runtime-guides/opencode.md)
 
 Chat platform integration (OpenClaw / Slack / Discord):
 ```bash

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/README.md

@@ -80,7 +80,7 @@ curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.
 > ooo interview "I want to build a task management CLI"
 ```
 
-> Works with Claude Code and Codex CLI. The installer detects your runtime, registers the MCP server, and installs skills automatically.
+> Works with Claude Code, Codex CLI, and OpenCode. The installer detects Claude Code and Codex CLI automatically and registers the MCP server. For OpenCode, run `ouroboros setup --runtime opencode` after installation.
 
 <details>
 <summary><strong>Other install methods</strong></summary>
@@ -104,7 +104,7 @@ ouroboros setup                         # configure runtime
 
 Legacy compatibility: `ouroboros-ai[dashboard]` is still accepted as a compatibility alias while extras migrate.
 
-See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md)
+See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md) · [OpenCode](./docs/runtime-guides/opencode.md)
 
 Chat platform integration (OpenClaw / Slack / Discord):
 ```bash

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/docs/config-reference.md

@@ -1,6 +1,6 @@
 <!--
 doc_metadata:
-  runtime_scope: [local, claude, codex]
+  runtime_scope: [local, claude, codex, opencode]
 -->
 
 # Configuration Reference
@@ -537,6 +537,23 @@ consensus:
 
 This is the recommended Ouroboros-side pattern for Codex users. Keep `~/.codex/config.toml` limited to the MCP/env block created by setup.
 
+### OpenCode Runtime
+
+```yaml
+# ~/.ouroboros/config.yaml
+orchestrator:
+  runtime_backend: opencode
+  opencode_cli_path: /usr/local/bin/opencode   # omit if opencode is already on PATH
+
+llm:
+  backend: opencode
+
+logging:
+  level: info
+```
+
+OpenCode supports multiple model providers (Anthropic, OpenAI, Google, and others). Model selection is configured in OpenCode itself (`~/.config/opencode/opencode.json`), not in `config.yaml`. The `orchestrator.opencode_permission_mode` defaults to `bypassPermissions` since OpenCode runs non-interactively via `opencode run --format json`. The `llm.opencode_permission_mode` defaults to `acceptEdits`, but the factory forces `bypassPermissions` for interview/seed use cases to avoid CLI sandbox blocking.
+
 ### Full Config Skeleton
 
 ```yaml

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/docs/contributing/findings-registry.md

@@ -630,7 +630,7 @@ findings:
       - docs/guides/cli-usage.md
     code_deps:
       - src/ouroboros/cli/commands/setup.py
-    resolution_ref: "cli-audit-findings.md#F-12; fixed in this generation"
+    resolution_ref: "cli-audit-findings.md#F-12; fixed in this generation. OpenCode runtime fully implemented in PR #324."
 
   - id: FIND-025
     claim_id: CLM-025
@@ -870,7 +870,8 @@ findings:
     resolution_ref: >-
       runtime-capability-crosscheck.md#Sec2;
       fix: "(opencode is in the CLI enum but out of scope)" note added to all
-      --runtime/--llm-backend option descriptions in cli-reference.md
+      --runtime/--llm-backend option descriptions in cli-reference.md.
+      OpenCode runtime fully implemented in PR #324 — out-of-scope notes no longer apply.
 
   - id: FIND-040
     claim_id: CLM-040

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/docs/getting-started.md

@@ -115,7 +115,7 @@ uv run ouroboros --version            # verify CLI
 | Claude Code (`ooo`) | Claude Code with plugin support |
 | Standalone CLI (`ouroboros`) | Python >= 3.12, API key (Anthropic or OpenAI) |
 | Codex CLI backend | Python >= 3.12, `npm install -g @openai/codex`, OpenAI API key with access to GPT-5.4 |
-| OpenCode backend | Python >= 3.12, `opencode` on PATH, API key for your configured provider |
+| OpenCode backend | Python >= 3.12, `opencode` on PATH, provider configured in OpenCode |
 
 ---
 
@@ -198,7 +198,7 @@ Inside a Claude Code session:
 ooo interview "I want to build a personal finance tracker"
 ```
 
-> **CLI note:** The standalone CLI does not have an `interview` command. Use `ooo interview` inside Claude Code, or use MCP tools to run interviews.
+> **CLI note:** You can also run interviews from the terminal with `ouroboros init start --llm-backend <backend> "your idea"` (where `<backend>` is `claude_code`, `codex`, `opencode`, or `litellm`). For in-agent `ooo interview` usage: Claude Code works out-of-the-box; Codex CLI and OpenCode require `ouroboros setup --runtime <codex|opencode>` first to register the MCP server.
 
 The Socratic Interviewer asks clarifying questions:
 - "What platforms do you want to track?" (Bank accounts, credit cards, investments)
@@ -289,7 +289,7 @@ ooo interview "Add real-time notifications to the chat app"
 ooo run
 ```
 
-> **Terminal users:** The standalone CLI does not have an `interview` command. Generate seeds via `ooo interview` in Claude Code or via MCP tools, then run with `ouroboros run <seed_file>`.
+> **Terminal users:** Run interviews from the terminal with `ouroboros init start --llm-backend <backend> "your idea"`, then execute with `ouroboros run workflow <seed_file>`. (Separate from in-agent `ooo` usage; terminal flows don't require MCP registration.)
 
 ---
 

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/docs/runtime-capability-matrix.md

@@ -91,7 +91,7 @@ The runtime backend affects:
 
 ## Choosing a Runtime
 
-The table below covers the two currently shipped backends. Because Ouroboros uses a pluggable `AgentRuntime` protocol, teams can register additional backends without modifying the core engine.
+The table below covers the three currently shipped backends. Because Ouroboros uses a pluggable `AgentRuntime` protocol, teams can register additional backends without modifying the core engine.
 
 | If you... | Consider |
 |-----------|----------|

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/docs/runtime-guides/codex.md

@@ -125,11 +125,11 @@ After running `ouroboros setup --runtime codex`, the bundled `ooo` skills are in
 | `ooo interview` | Yes | `ouroboros init start --llm-backend codex "your idea"` |
 | `ooo seed` | Yes | *(bundled in `ouroboros init start`)* |
 | `ooo run` | Yes | `ouroboros run workflow --runtime codex seed.yaml` |
-| `ooo status` | Yes | `ouroboros status execution <session_id>` |
+| `ooo status` | Yes | `ouroboros status execution <execution_id>` |
 | `ooo evaluate` | Yes | *(MCP only)* |
 | `ooo evolve` | Yes | *(MCP only)* |
 | `ooo ralph` | Yes | *(MCP only)* |
-| `ooo cancel` | Yes | `ouroboros cancel execution <session_id>` |
+| `ooo cancel` | Yes | `ouroboros cancel execution <execution_id>` |
 | `ooo unstuck` | Yes | *(MCP only)* |
 | `ooo tutorial` | Yes | *(MCP only)* |
 | `ooo welcome` | Yes | *(MCP only)* |

ouroboros_ai-0.28.1.dev4/docs/runtime-guides/opencode.md

@@ -0,0 +1,284 @@
+<!--
+doc_metadata:
+  runtime_scope: [opencode]
+-->
+
+# Running Ouroboros with OpenCode
+
+> For installation and first-run onboarding, see [Getting Started](../getting-started.md).
+
+Ouroboros can use **OpenCode** as a runtime backend. [OpenCode](https://opencode.ai) is an open-source AI coding agent that supports multiple model providers (Anthropic, OpenAI, Google, and others) through its own provider management. In Ouroboros, the OpenCode backend is presented as a **session-oriented runtime** with the same specification-first workflow harness (acceptance criteria, evaluation principles, deterministic exit conditions).
+
+No additional Python SDK is required beyond the base `ouroboros-ai` package.
+
+> **Model recommendation:** OpenCode supports any model available through your configured provider. For best results with Ouroboros workflows, use a frontier-class model (Claude Opus, GPT-5.4, or equivalent) that handles multi-step agentic coding tasks well.
+
+## Prerequisites
+
+- **OpenCode** installed, configured, and on your `PATH` (see [install steps](#installing-opencode) below)
+- A **provider configured in OpenCode** (run `opencode` and complete the first-run setup, or use `opencode providers auth <provider>`)
+- **Python >= 3.12**
+
+> **Note:** OpenCode manages its own provider authentication. You do not need to set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` environment variables for Ouroboros — OpenCode handles provider credentials internally via its own configuration at `~/.config/opencode/opencode.json`.
+
+## Installing OpenCode
+
+OpenCode is distributed as a standalone binary. Install via the official installer script or npm:
+
+```bash
+# Recommended: official installer
+curl -fsSL https://opencode.ai/install | bash
+
+# Alternative: npm
+npm i -g opencode-ai@latest
+```
+
+Verify the installation:
+
+```bash
+opencode --version
+```
+
+After install, run `opencode` once to complete first-run provider setup (select a provider and authenticate).
+
+For alternative install methods, see the [OpenCode documentation](https://opencode.ai/docs).
+
+## Installing Ouroboros
+
+> For all installation options (pip, one-liner, from source) and first-run onboarding, see **[Getting Started](../getting-started.md)**.
+> The base `ouroboros-ai` package includes the OpenCode runtime adapter — no extras are required.
+
+## Platform Notes
+
+The OpenCode runtime adapter has been developed and tested on Linux. Other platforms may work but have not been verified with the Ouroboros integration.
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux (x86_64/ARM64) | Tested | Primary development and testing platform |
+| macOS (ARM/Intel) | Untested | Expected to work — OpenCode supports macOS natively |
+| Windows (WSL 2) | Untested | Expected to work via WSL 2 — not verified with Ouroboros |
+| Windows (native) | Untested | Not recommended — subprocess and path handling may have issues |
+
+> If you test on macOS or Windows and encounter issues, please report them.
+
+## Configuration
+
+To select OpenCode as the runtime backend, set the following in your Ouroboros configuration:
+
+```yaml
+orchestrator:
+  runtime_backend: opencode
+```
+
+Or pass the backend on the command line:
+
+```bash
+uv run ouroboros run workflow --runtime opencode ~/.ouroboros/seeds/seed_abcd1234ef56.yaml
+```
+
+### Where OpenCode users configure what
+
+Use `~/.ouroboros/config.yaml` for Ouroboros runtime settings (backend selection, permission mode, CLI path).
+
+Use `~/.config/opencode/opencode.json` (OpenCode's own config) for provider/model selection, MCP servers, and tool permissions. `ouroboros setup --runtime opencode` writes the Ouroboros MCP server entry into this file automatically.
+
+```yaml
+# ~/.ouroboros/config.yaml
+orchestrator:
+  runtime_backend: opencode
+  opencode_cli_path: /usr/local/bin/opencode   # omit if opencode is already on PATH
+
+llm:
+  backend: opencode
+```
+
+Model selection for OpenCode-backed workflows is configured in OpenCode itself, not in `config.yaml`. The `orchestrator.opencode_permission_mode` defaults to `bypassPermissions` since OpenCode runs non-interactively via `opencode run --format json`.
+
+### Setup
+
+Run the setup command to auto-configure:
+
+```bash
+ouroboros setup --runtime opencode
+```
+
+This:
+
+- Detects the `opencode` binary on your `PATH` and records it as `orchestrator.opencode_cli_path`
+- Writes `orchestrator.runtime_backend: opencode` and `llm.backend: opencode` to `~/.ouroboros/config.yaml`
+- Registers the Ouroboros MCP server in OpenCode's configuration file (`~/.config/opencode/opencode.json`). Note: The setup process rewrites the file as plain JSON and removes comments (the file supports JSONC format initially, but setup normalizes to JSON for compatibility).
+
+### `ooo` Skill Availability on OpenCode
+
+After running `ouroboros setup --runtime opencode`, the Ouroboros MCP server is registered in OpenCode's config. The `ooo` skills are available via MCP tool dispatch within OpenCode sessions.
+
+| `ooo` Skill | OpenCode session | CLI equivalent (Terminal) |
+|-------------|------------------|--------------------------|
+| `ooo interview` | Yes | `ouroboros init start --llm-backend opencode "your idea"` |
+| `ooo seed` | Yes | *(bundled in `ouroboros init start`)* |
+| `ooo run` | Yes | `ouroboros run workflow --runtime opencode seed.yaml` |
+| `ooo status` | Yes | `ouroboros status execution <execution_id>` |
+| `ooo evaluate` | Yes | *(MCP only)* |
+| `ooo evolve` | Yes | *(MCP only)* |
+| `ooo ralph` | Yes | *(MCP only)* |
+| `ooo cancel` | Yes | `ouroboros cancel execution <execution_id>` |
+| `ooo unstuck` | Yes | *(MCP only)* |
+| `ooo tutorial` | Yes | *(MCP only)* |
+| `ooo welcome` | Yes | *(MCP only)* |
+| `ooo update` | Yes | `pip install --upgrade ouroboros-ai` |
+| `ooo help` | Yes | `ouroboros --help` |
+| `ooo qa` | Yes | *(MCP only)* |
+| `ooo setup` | Yes | `ouroboros setup --runtime opencode` |
+| `ooo publish` | Yes | *(no direct `ouroboros publish` subcommand; skill/runtime flow uses `gh` CLI)* |
+
+> **Note on `ooo seed` vs `ooo interview`:** These are two distinct skills with separate roles. `ooo interview` runs a Socratic Q&A session and returns a `session_id`. `ooo seed` accepts that `session_id` and generates a structured Seed YAML (with ambiguity scoring). From the terminal, both steps are performed in a single `ouroboros init start` invocation.
+
+## Quick Start
+
+> For the full first-run onboarding flow (interview -> seed -> execute), see **[Getting Started](../getting-started.md)**.
+
+### Verify Installation
+
+```bash
+opencode --version
+ouroboros --help
+```
+
+## How It Works
+
+```
++-----------------+     +------------------+     +-----------------+
+|   Seed YAML     | --> |   Orchestrator   | --> |    OpenCode     |
+|  (your task)    |     | (runtime_factory)|     |   (runtime)     |
++-----------------+     +------------------+     +-----------------+
+                                |
+                                v
+                        +------------------+
+                        |  Tools Available |
+                        |  - Read          |
+                        |  - Write         |
+                        |  - Edit          |
+                        |  - Bash          |
+                        |  - Glob          |
+                        |  - Grep          |
+                        +------------------+
+```
+
+The `OpenCodeRuntime` adapter launches `opencode run --format json` as a subprocess for each task execution. The orchestrator pipes the prompt via stdin and parses the structured JSON event stream from stdout.
+
+> For a side-by-side comparison of all runtime backends, see the [runtime capability matrix](../runtime-capability-matrix.md).
+
+## OpenCode-Specific Strengths
+
+- **Multi-provider support** -- use Anthropic, OpenAI, Google, or other providers through a single runtime
+- **Built-in provider management** -- OpenCode handles its own authentication and provider configuration, no env var setup required
+- **Rich tool access** -- full suite of file, shell, and search tools (same surface as Claude Code)
+- **Native MCP integration** -- OpenCode has built-in MCP server support
+- **Open-source** -- fully open-source, allowing inspection and contribution
+- **Session-aware runtime** -- Ouroboros preserves OpenCode session handles and resume state across workflow steps via `--session` flag
+
+## Runtime Differences
+
+OpenCode, Claude Code, and Codex CLI are independent runtime backends with different tool sets, permission models, and provider ecosystems. The same Seed file works with all three, but execution paths may differ.
+
+| Aspect | OpenCode | Claude Code | Codex CLI |
+|--------|----------|-------------|-----------|
+| What it is | Ouroboros session runtime backed by OpenCode subprocess | Anthropic's agentic coding tool | Ouroboros session runtime backed by Codex CLI transport |
+| Authentication | Managed by OpenCode (`opencode providers auth`) | Max Plan subscription | OpenAI API key |
+| Model | Any model supported by configured provider | Claude (via claude-agent-sdk) | GPT-5.4 with medium reasoning effort (recommended) |
+| Tool surface | Read, Write, Edit, Bash, Glob, Grep | Read, Write, Edit, Bash, Glob, Grep | Codex-native tools (file I/O, shell) |
+| Session model | Session-aware via `--session` flag and runtime handles | Native Claude session context | Session-aware via runtime handles, resume IDs, and skill dispatch |
+| Transport | Subprocess (`opencode run --format json`), prompt via stdin | Claude Agent SDK (direct API) | Subprocess (`codex` executable) |
+| Cost model | Provider API usage charges | Included in Max Plan subscription | OpenAI API usage charges |
+| Tested platforms | Linux | Linux, macOS | Linux, macOS |
+
+> **Note:** The Ouroboros workflow model (Seed files, acceptance criteria, evaluation principles) is identical across runtimes. However, because OpenCode, Claude Code, and Codex CLI have different underlying agent capabilities, tool access, and provider ecosystems, they may produce different execution paths and results for the same Seed file.
+
+## CLI Options
+
+### Workflow Commands
+
+```bash
+# Execute workflow (OpenCode runtime)
+# Seeds generated by ouroboros init are saved to ~/.ouroboros/seeds/seed_{id}.yaml
+uv run ouroboros run workflow --runtime opencode ~/.ouroboros/seeds/seed_abcd1234ef56.yaml
+
+# Debug output (show logs and agent output)
+uv run ouroboros run workflow --runtime opencode --debug ~/.ouroboros/seeds/seed_abcd1234ef56.yaml
+
+# Resume a previous session
+uv run ouroboros run workflow --runtime opencode --resume <session_id> ~/.ouroboros/seeds/seed_abcd1234ef56.yaml
+```
+
+## Seed File Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `goal` | Yes | Primary objective |
+| `task_type` | No | Execution strategy: `code` (default), `research`, or `analysis` |
+| `constraints` | No | Hard constraints to satisfy |
+| `acceptance_criteria` | No | Specific success criteria |
+| `ontology_schema` | Yes | Output structure definition |
+| `evaluation_principles` | No | Principles for evaluation |
+| `exit_conditions` | No | Termination conditions |
+| `metadata.ambiguity_score` | Yes | Must be <= 0.2 |
+
+## Known Limitations
+
+### Session pollution
+
+Each task execution via `opencode run` creates a visible session in OpenCode's session history. Long-running workflows with many orchestrator steps will accumulate sessions. A future phase will reparent these sessions under the caller to prevent polluting the session picker (see [#331](https://github.com/Q00/ouroboros/issues/331)).
+
+### No interactive mode
+
+The adapter uses `opencode run --format json` (non-interactive). Features that require interactive OpenCode sessions (e.g., manual approval prompts) are not available during Ouroboros execution.
+
+### Permission mode not wired to CLI
+
+OpenCode's `opencode run` command does not expose a `--permission-mode` flag. The `opencode_permission_mode` config value is stored for forward compatibility but is not currently passed to the subprocess. OpenCode runs non-interactively by default, so there is no approval dialogue to bypass.
+
+## Troubleshooting
+
+### OpenCode not found
+
+Ensure `opencode` is installed and available on your `PATH`:
+
+```bash
+which opencode
+```
+
+If not installed:
+
+```bash
+curl -fsSL https://opencode.ai/install | bash
+```
+
+### Provider not configured
+
+If OpenCode reports a provider error, ensure you have completed first-run setup:
+
+```bash
+opencode                        # interactive first-run setup
+# or
+opencode providers auth anthropic   # configure a specific provider
+```
+
+OpenCode manages its own provider credentials — you do not need to set `ANTHROPIC_API_KEY` or similar environment variables for the Ouroboros integration.
+
+### "Providers: warning" in health check
+
+This is normal when using the orchestrator runtime backends. The warning refers to LiteLLM providers, which are not used in orchestrator mode.
+
+### "EventStore not initialized"
+
+The database will be created automatically at `~/.ouroboros/ouroboros.db`.
+
+## Cost
+
+Using OpenCode as the runtime backend incurs API charges from your configured provider. Costs depend on:
+
+- Provider and model selected in OpenCode's configuration
+- Task complexity and token usage
+- Number of tool calls and iterations
+
+Refer to your provider's pricing page for current rates.

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.28.1.dev2'
-__version_tuple__ = version_tuple = (0, 28, 1, 'dev2')
+__version__ = version = '0.28.1.dev4'
+__version_tuple__ = version_tuple = (0, 28, 1, 'dev4')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/src/ouroboros/cli/commands/mcp.py

@@ -7,8 +7,11 @@ from __future__ import annotations
 
 import asyncio
 from enum import Enum
+import json
 import os
 from pathlib import Path
+import subprocess
+import sys
 from typing import Annotated
 
 from rich.console import Console
@@ -98,6 +101,60 @@ def _check_stale_instance() -> bool:
         return True
 
 
+def _ensure_shell_env(*, timeout: float = 10.0) -> None:
+    """Load login-shell environment when launched outside a login shell.
+
+    When a gateway process (e.g., OpenClaw) spawns ``ouroboros mcp serve``,
+    the child inherits only a minimal environment. This sources the user's
+    shell profile to recover PATH, ANTHROPIC_API_KEY, etc.
+
+    Uses JSON serialization to avoid multiline env value parsing issues.
+    Avoids the ``-i`` (interactive) flag which hangs on oh-my-zsh/p10k.
+    """
+    # Fast path: if key indicators are already present, skip
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        return
+
+    shell = os.environ.get("SHELL", "/bin/zsh" if sys.platform == "darwin" else "/bin/bash")
+    shell_name = Path(shell).name
+
+    # Dump env as JSON — unambiguous, handles multiline values
+    dump_cmd = 'python3 -c "import os,json,sys; json.dump(dict(os.environ), sys.stdout)"'
+
+    if shell_name == "zsh":
+        cmd = [shell, "-l", "-c", f"[[ -f ~/.zshrc ]] && source ~/.zshrc 2>/dev/null; {dump_cmd}"]
+    elif shell_name == "bash":
+        cmd = [shell, "-l", "-c", f"[[ -f ~/.bashrc ]] && source ~/.bashrc 2>/dev/null; {dump_cmd}"]
+    else:
+        cmd = [shell, "-l", "-c", dump_cmd]
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError) as e:
+        _stderr_console.print(f"[yellow]Warning: shell env load failed: {e}[/yellow]")
+        return
+
+    if result.returncode != 0:
+        return
+
+    try:
+        env = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        _stderr_console.print("[yellow]Warning: could not parse shell env output[/yellow]")
+        return
+
+    current_path_dirs = set(os.environ.get("PATH", "").split(os.pathsep))
+    for key, val in env.items():
+        if key == "PATH":
+            new_dirs = [d for d in val.split(os.pathsep) if d and d not in current_path_dirs]
+            if new_dirs:
+                os.environ["PATH"] = (
+                    os.pathsep.join(new_dirs) + os.pathsep + os.environ.get("PATH", "")
+                )
+        elif key not in os.environ:
+            os.environ[key] = val
+
+
 app = typer.Typer(
     name="mcp",
     help="MCP (Model Context Protocol) server commands.",
@@ -123,6 +180,9 @@ async def _run_mcp_server(
         runtime_backend: Optional orchestrator runtime backend override.
         llm_backend: Optional LLM-only backend override.
     """
+    # Ensure login-shell environment is available (critical for gateway-spawned processes)
+    _ensure_shell_env()
+
     from ouroboros.mcp.server.adapter import create_ouroboros_server, validate_transport
     from ouroboros.orchestrator.session import SessionRepository
     from ouroboros.persistence.event_store import EventStore

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/src/ouroboros/mcp/server/adapter.py

@@ -1257,7 +1257,8 @@ def create_ouroboros_server(
         validator=_evolution_validator,
     )
     job_manager = JobManager(event_store)
-    openclaw_db_path = state_dir / "openclaw.db"
+    cwd = Path.cwd()
+    openclaw_db_path = Path.home() / ".ouroboros" / "ouroboros.db"
     workflow_manager = ChannelWorkflowManager(openclaw_db_path)
     repo_registry = ChannelRepoRegistry(openclaw_db_path)
 
@@ -1327,6 +1328,7 @@ def create_ouroboros_server(
         ChannelWorkflowHandler(
             workflow_manager=workflow_manager,
             repo_registry=repo_registry,
+            default_repo=str(cwd) if str(cwd) != "/" else None,
             interview_handler=InterviewHandler(
                 interview_engine=interview_engine,
                 event_store=event_store,

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/src/ouroboros/mcp/tools/channel_workflow_handler.py

@@ -44,6 +44,7 @@ class ChannelWorkflowHandler:
     job_status_handler: JobStatusHandler | None = field(default=None, repr=False)
     job_wait_handler: JobWaitHandler | None = field(default=None, repr=False)
     job_result_handler: JobResultHandler | None = field(default=None, repr=False)
+    default_repo: str | None = field(default=None, repr=False)
 
     def __post_init__(self) -> None:
         self._workflow_manager = self.workflow_manager or ChannelWorkflowManager()
@@ -348,6 +349,7 @@ class ChannelWorkflowHandler:
             arguments.get("repo")
             or self._repo_registry.get(channel)
             or (active.repo if active else None)
+            or self.default_repo
         )
         if not isinstance(repo, str) or not repo.strip():
             return Result.err(

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/src/ouroboros/mcp/tools/definitions.py

@@ -152,6 +152,7 @@ def channel_workflow_handler(
     job_wait_handler: JobWaitHandler | None = None,
     job_status_handler: JobStatusHandler | None = None,
     job_result_handler: JobResultHandler | None = None,
+    default_repo: str | None = None,
 ) -> ChannelWorkflowHandler:
     """Create a ChannelWorkflowHandler instance.
 
@@ -171,6 +172,7 @@ def channel_workflow_handler(
         job_wait_handler=job_wait_handler or JobWaitHandler(),
         job_status_handler=job_status_handler or JobStatusHandler(),
         job_result_handler=job_result_handler or JobResultHandler(),
+        default_repo=default_repo,
     )
 
 

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/src/ouroboros/openclaw/store.py

@@ -11,7 +11,7 @@ from typing import Any
 
 def default_openclaw_db_path() -> Path:
     """Return the default SQLite database path for OpenClaw workflow state."""
-    return Path.cwd() / ".ouroboros" / "openclaw.db"
+    return Path.home() / ".ouroboros" / "ouroboros.db"
 
 
 class OpenClawStateStore:

{ouroboros_ai-0.28.1.dev2 → ouroboros_ai-0.28.1.dev4}/tests/integration/mcp/test_server_adapter.py

@@ -590,7 +590,7 @@ class TestCreateOuroborosServer:
         assert status_result.is_ok
         assert "Channel Workflow Summary" in status_result.value.text_content
         assert str(tmp_path / "repo") in status_result.value.text_content
-        assert (tmp_path / "data" / "openclaw.db").exists()
+        assert (Path.home() / ".ouroboros" / "ouroboros.db").exists()
 
 
 class TestMCPServerAdapterConcurrency: