ouroboros-ai 0.40.2.dev16__tar.gz → 0.40.2.dev18__tar.gz

{ouroboros_ai-0.40.2.dev16 → ouroboros_ai-0.40.2.dev18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.40.2.dev16
+Version: 0.40.2.dev18
 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

{ouroboros_ai-0.40.2.dev16 → ouroboros_ai-0.40.2.dev18}/docs/architecture.md

@@ -549,6 +549,8 @@ The orchestrator never inspects backend-specific internals — each adapter maps
 - **`GeminiCliRuntime`** (`backend="gemini"`) — Drives the Google Gemini CLI in stream-json mode. Module: `src/ouroboros/orchestrator/gemini_cli_runtime.py`
 - **`KiroAdapter`** (`backend="kiro"`) — Drives the Kiro CLI in headless mode. Module: `src/ouroboros/orchestrator/kiro_adapter.py`
 - **`CopilotCliLLMAdapter`** (`backend="copilot"`) — Drives the GitHub Copilot CLI via `copilot -p`, with live model discovery (queries `https://api.githubcopilot.com/models` at setup) and automatic hyphen-to-dotted model name mapping for cross-runtime config compatibility. Module: `src/ouroboros/providers/copilot_cli_adapter.py`
+- **`PiRuntime`** (`backend="pi"`) — Drives the Pi CLI in documented JSON mode with skill dispatch, session resumption, and JSONL event normalization. Module: `src/ouroboros/orchestrator/pi_runtime.py`
+- **`PiLLMAdapter`** (`backend="pi"`) — Exposes the Pi CLI for unstructured LLM-only flows such as interview and seed generation. Module: `src/ouroboros/providers/pi_llm_adapter.py`
 
 > Each runtime has different tool sets, permission models, and streaming semantics. Ouroboros normalizes these differences at the adapter boundary, but feature parity is not guaranteed across runtimes.
 
@@ -560,7 +562,7 @@ The orchestrator never inspects backend-specific internals — each adapter maps
 2. `orchestrator.runtime_backend` in `~/.ouroboros/config.yaml`
 3. Explicit `backend=` parameter
 
-Accepted aliases: `claude` / `claude_code`, `codex` / `codex_cli`, `opencode` / `opencode_cli`, `hermes` / `hermes_cli`, `gemini` / `gemini_cli`, `kiro` / `kiro_cli`, `copilot` / `copilot_cli`.
+Accepted aliases: `claude` / `claude_code`, `codex` / `codex_cli`, `opencode` / `opencode_cli`, `hermes` / `hermes_cli`, `gemini` / `gemini_cli`, `kiro` / `kiro_cli`, `copilot` / `copilot_cli`, `pi` / `pi_cli`.
 
 For API details, see the source in `src/ouroboros/orchestrator/adapter.py`. For contributing a new runtime adapter, see [Contributing](contributing/).
 
@@ -605,4 +607,4 @@ For environment variables, `config.yaml` schema, and all configuration options,
 ---
 
 > For install instructions and first-run onboarding, see **[Getting Started](getting-started.md)**.
-> For backend-specific configuration, see the [Claude Code](runtime-guides/claude-code.md), [Codex CLI](runtime-guides/codex.md), [OpenCode](runtime-guides/opencode.md), [Hermes](runtime-guides/hermes.md), [Gemini](runtime-guides/gemini.md), [Kiro CLI](runtime-guides/kiro.md), and [GitHub Copilot CLI](runtime-guides/copilot.md) runtime guides.
+> For backend-specific configuration, see the [Claude Code](runtime-guides/claude-code.md), [Codex CLI](runtime-guides/codex.md), [OpenCode](runtime-guides/opencode.md), [Hermes](runtime-guides/hermes.md), [Gemini](runtime-guides/gemini.md), [Kiro CLI](runtime-guides/kiro.md), and [GitHub Copilot CLI](runtime-guides/copilot.md) runtime guides. For Pi's JSON-mode contract, see the [Pi JSON mode documentation](https://pi.dev/docs/latest/json).

{ouroboros_ai-0.40.2.dev16 → ouroboros_ai-0.40.2.dev18}/docs/config-reference.md

@@ -182,7 +182,7 @@ Controls how Ouroboros launches and communicates with the agent runtime backend.
 
 ```yaml
 orchestrator:
-  runtime_backend: claude       # "claude" | "codex" | "opencode" | "hermes" | "gemini" | "kiro" | "copilot"
+  runtime_backend: claude       # "claude" | "codex" | "opencode" | "hermes" | "gemini" | "kiro" | "copilot" | "pi"
   permission_mode: acceptEdits  # "default" | "acceptEdits" | "bypassPermissions"
   opencode_permission_mode: bypassPermissions
   max_parallel_workers: 3       # Maximum concurrent AC workers
@@ -190,12 +190,13 @@ orchestrator:
   codex_cli_path: null          # Path to Codex CLI binary; null = resolve from PATH
   opencode_cli_path: null       # Path to OpenCode CLI binary; null = resolve from PATH
   copilot_cli_path: null        # Path to Copilot CLI binary; null = resolve from PATH
+  pi_cli_path: null             # Path to Pi CLI binary; null = resolve from PATH
   default_max_turns: 10
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `runtime_backend` | `"claude"` \| `"codex"` \| `"opencode"` \| `"hermes"` \| `"gemini"` \| `"kiro"` \| `"copilot"` | `"claude"` | The agent runtime backend used for workflow execution. Overridable via `OUROBOROS_AGENT_RUNTIME`. See [runtime capability matrix](runtime-capability-matrix.md). |
+| `runtime_backend` | `"claude"` \| `"codex"` \| `"opencode"` \| `"hermes"` \| `"gemini"` \| `"kiro"` \| `"copilot"` \| `"pi"` | `"claude"` | The agent runtime backend used for workflow execution. Overridable via `OUROBOROS_AGENT_RUNTIME`. See [runtime capability matrix](runtime-capability-matrix.md). |
 | `permission_mode` | `"default"` \| `"acceptEdits"` \| `"bypassPermissions"` | `"acceptEdits"` | Permission mode for Claude and Codex runtimes. Overridable via `OUROBOROS_AGENT_PERMISSION_MODE`. |
 | `opencode_permission_mode` | `"default"` \| `"acceptEdits"` \| `"bypassPermissions"` | `"bypassPermissions"` | Permission mode when using the OpenCode runtime. Overridable via `OUROBOROS_OPENCODE_PERMISSION_MODE`. |
 | `max_parallel_workers` | `int >= 1` | `3` | Maximum concurrent Acceptance Criteria workers for parallel execution. Overridable via `OUROBOROS_MAX_PARALLEL_WORKERS`. Invalid explicit values fail instead of falling back to the default. |
@@ -203,6 +204,7 @@ orchestrator:
 | `codex_cli_path` | `string \| null` | `null` | Absolute path to the Codex CLI binary (`~` is expanded). When `null`, resolved from `PATH` at runtime. Overridable via `OUROBOROS_CODEX_CLI_PATH`. |
 | `opencode_cli_path` | `string \| null` | `null` | Absolute path to the OpenCode CLI binary (`~` is expanded). When `null`, resolved from `PATH` at runtime. Overridable via `OUROBOROS_OPENCODE_CLI_PATH`. |
 | `copilot_cli_path` | `string \| null` | `null` | Absolute path to the GitHub Copilot CLI binary (`~` is expanded). When `null`, resolved from `PATH` at runtime. Overridable via `OUROBOROS_COPILOT_CLI_PATH`. |
+| `pi_cli_path` | `string \| null` | `null` | Absolute path to the Pi CLI binary (`~` is expanded). When `null`, resolved from `PATH` at runtime. Overridable via `OUROBOROS_PI_CLI_PATH`. |
 | `default_max_turns` | `int >= 1` | `10` | Default maximum number of turns per agent execution task. |
 
 ---
@@ -224,7 +226,7 @@ llm:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `backend` | `"claude"` \| `"claude_code"` \| `"litellm"` \| `"codex"` \| `"opencode"` \| `"hermes"` \| `"gemini"` \| `"kiro"` \| `"copilot"` | `"claude_code"` | Default backend for LLM-only flows. Overridable via `OUROBOROS_LLM_BACKEND`. |
+| `backend` | `"claude"` \| `"claude_code"` \| `"litellm"` \| `"codex"` \| `"opencode"` \| `"hermes"` \| `"gemini"` \| `"kiro"` \| `"copilot"` \| `"pi"` | `"claude_code"` | Default backend for LLM-only flows. Overridable via `OUROBOROS_LLM_BACKEND`. |
 | `permission_mode` | `"default"` \| `"acceptEdits"` \| `"bypassPermissions"` | `"default"` | Permission mode for non-OpenCode LLM flows. Overridable via `OUROBOROS_LLM_PERMISSION_MODE`. |
 | `opencode_permission_mode` | `"default"` \| `"acceptEdits"` \| `"bypassPermissions"` | `"acceptEdits"` | Permission mode for OpenCode-backed LLM flows. Overridable via `OUROBOROS_OPENCODE_PERMISSION_MODE`. |
 | `qa_model` | `string` | `"claude-sonnet-4-20250514"` | Model used for post-execution QA verdict generation. Overridable via `OUROBOROS_QA_MODEL`. |
@@ -593,13 +595,14 @@ All environment variables have higher priority than the corresponding `config.ya
 
 | Variable | Overrides | Description |
 |----------|-----------|-------------|
-| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Active runtime backend (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`, `copilot`). |
+| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Active runtime backend (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`, `copilot`, `pi`). |
 | `OUROBOROS_AGENT_PERMISSION_MODE` | `orchestrator.permission_mode` | Permission mode for non-OpenCode runtimes. |
 | `OUROBOROS_OPENCODE_PERMISSION_MODE` | `orchestrator.opencode_permission_mode` | Permission mode when using OpenCode runtime. |
 | `OUROBOROS_MAX_PARALLEL_WORKERS` | `orchestrator.max_parallel_workers` | Maximum concurrent Acceptance Criteria workers for parallel execution. Must be a positive integer. |
 | `OUROBOROS_CLI_PATH` | `orchestrator.cli_path` | Path to the Claude CLI binary. |
 | `OUROBOROS_CODEX_CLI_PATH` | `orchestrator.codex_cli_path` | Path to the Codex CLI binary. |
 | `OUROBOROS_OPENCODE_CLI_PATH` | `orchestrator.opencode_cli_path` | Path to the OpenCode CLI binary. |
+| `OUROBOROS_PI_CLI_PATH` | `orchestrator.pi_cli_path` | Path to the Pi CLI binary. |
 | `OUROBOROS_SKIP_VERSION_CHECK` | *(none)* | Controls the Claude Agent SDK per-call version compatibility check. Defaults to `"1"` (skip the check, saving ~0.3-0.8 s per LLM call). Set to `"0"` to re-enable the check for debugging version-mismatch issues. Maps to `CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK` internally. |
 
 ### LLM Flow
@@ -751,6 +754,20 @@ clarification:
 
 The Copilot CLI runtime is unique in that `ouroboros setup --runtime copilot` **live-discovers the available models** from the GitHub Copilot models API at setup time and writes the chosen default into the config above. Re-run setup after GitHub publishes new models. Authentication uses `gh auth login`; no separate API key is required. Hyphenated Anthropic IDs (for example `claude-opus-4-6`) used elsewhere in your config are auto-mapped to the dotted Copilot form (`claude-opus-4.6`) at runtime, so existing per-role overrides keep working when you switch backends. See [Copilot CLI runtime guide](runtime-guides/copilot.md) for full details.
 
+### Pi CLI Runtime
+
+```yaml
+# ~/.ouroboros/config.yaml
+orchestrator:
+  runtime_backend: pi
+  pi_cli_path: null                       # omit if `pi` is already on PATH
+
+llm:
+  backend: pi
+```
+
+Pi is available as an agent runtime backend and, when the Pi LLM adapter is installed, an LLM-only backend for unstructured interview and seed-generation flows. The Pi LLM adapter rejects structured `response_format` requests, so schema-dependent flows such as QA should continue to use a backend with structured output support. The runtime uses documented JSON mode (`pi --mode json <prompt>`) and preserves Pi native session IDs for targeted resume.
+
 ### Full Config Skeleton
 
 ```yaml
@@ -762,6 +779,7 @@ orchestrator:
   cli_path: null
   codex_cli_path: null
   opencode_cli_path: null
+  pi_cli_path: null
   default_max_turns: 10
 
 llm:

{ouroboros_ai-0.40.2.dev16 → ouroboros_ai-0.40.2.dev18}/docs/getting-started.md

@@ -163,6 +163,7 @@ Use WSL 2 for the supported Windows path, then run the Linux install commands fr
 | OpenCode backend | Python >= 3.12, `opencode` on PATH, provider configured in OpenCode |
 | Kiro CLI backend | Python >= 3.12, `kiro-cli` on PATH (signed in to Kiro), `pip install ouroboros-ai[claude]` (shares the Claude extras for the Agent SDK types). Then `ouroboros setup --runtime kiro` to register the Ouroboros MCP server in `~/.kiro/settings/mcp.json` |
 | GitHub Copilot CLI backend | Python >= 3.12, `copilot` on PATH, `gh` on PATH (`gh auth login`), `pip install 'ouroboros-ai[mcp]'` (or `pipx`/`uv tool` install). Then `ouroboros setup --runtime copilot` to live-discover available models, pick a default, and register the Ouroboros MCP server in `~/.copilot/mcp-config.json` |
+| Pi CLI backend | Python >= 3.12, `pi` on PATH or `orchestrator.pi_cli_path` configured. Use `runtime_backend: pi` for workflow execution and `llm.backend: pi` only for unstructured LLM flows such as interview and seed generation |
 
 ---
 
@@ -186,10 +187,10 @@ export OPENAI_API_KEY="your-openai-key"
 
 ```yaml
 orchestrator:
-  runtime_backend: claude   # claude | codex | opencode | hermes | gemini | kiro | copilot
+  runtime_backend: claude   # claude | codex | opencode | hermes | gemini | kiro | copilot | pi
 
 llm:
-  backend: claude_code      # claude_code | codex | litellm | kiro | copilot
+  backend: claude_code      # claude_code | codex | litellm | kiro | copilot | pi
 
 logging:
   level: info

{ouroboros_ai-0.40.2.dev16 → ouroboros_ai-0.40.2.dev18}/docs/runtime-capability-matrix.md

@@ -13,7 +13,7 @@ The runtime backend is selected via the `orchestrator.runtime_backend` config ke
 
 ```yaml
 orchestrator:
-  runtime_backend: claude   # Supported values: claude | codex | opencode | hermes | kiro | copilot
+  runtime_backend: claude   # Supported values: claude | codex | opencode | hermes | kiro | copilot | pi
                             # The runtime abstraction layer also accepts custom
                             # adapters registered in runtime_factory.py
 ```
@@ -26,7 +26,7 @@ ouroboros run workflow --runtime codex seed.yaml
 
 You can also override the configured backend with the `OUROBOROS_AGENT_RUNTIME` environment variable.
 
-> **Extensibility:** Ouroboros uses a pluggable `AgentRuntime` protocol. Claude Code, Codex CLI, OpenCode, Hermes, Kiro CLI, and GitHub Copilot CLI are the natively shipped backends; additional runtimes can be registered by implementing the protocol and extending `runtime_factory.py`. See [Architecture — How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter).
+> **Extensibility:** Ouroboros uses a pluggable `AgentRuntime` protocol. Claude Code, Codex CLI, OpenCode, Hermes, Kiro CLI, GitHub Copilot CLI, and Pi CLI are the natively shipped backends; additional runtimes can be registered by implementing the protocol and extending `runtime_factory.py`. See [Architecture — How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter).
 
 ## Capability Matrix
 
@@ -34,41 +34,41 @@ You can also override the configured backend with the `OUROBOROS_AGENT_RUNTIME`
 
 These capabilities are part of the Ouroboros core engine and work the same way regardless of runtime backend.
 
-| Capability                         | Claude Code | Codex CLI | OpenCode | Hermes | Kiro CLI | Copilot CLI | Notes                                                       |
-| ---------------------------------- | :---------: | :-------: | :------: | :----: | :------: | :---------: | ----------------------------------------------------------- |
-| Seed file parsing                  |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     | Same YAML schema, same validation                           |
-| Acceptance criteria tree           |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     | Structured AC decomposition                                 |
-| Evaluation principles              |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     | Weighted scoring against principles                         |
-| Exit conditions                    |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     | Deterministic termination logic                             |
-| Event sourcing (SQLite)            |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     | Full event log, replay support                              |
-| Checkpoint / resume                |     Yes     |    Yes    |   Yes    |  Yes   | Partial  |     No      | `--resume <session_id>` everywhere; Kiro forwards to `--resume-id` **when the caller supplies the id** — headless does not surface session ids, so automatic checkpoint/resume is future work; Copilot CLI does not expose a resume API |
-| TUI dashboard                      |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     | Textual-based progress view                                 |
-| Interview (Socratic seed creation) |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     | `ouroboros init start ...` with the appropriate LLM backend |
-| Dry-run validation                 |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     | `--dry-run` validates without executing                     |
-| Live model discovery               |     No      |    No     |    No    |   No   |    No    |     Yes     | Only Copilot queries its provider's models API at setup time and lets you pick a default from the live list |
+| Capability                         | Claude Code | Codex CLI | OpenCode | Hermes | Kiro CLI | Copilot CLI | Pi CLI | Notes                                                       |
+| ---------------------------------- | :---------: | :-------: | :------: | :----: | :------: | :---------: | :----: | ----------------------------------------------------------- |
+| Seed file parsing                  |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Same YAML schema, same validation                           |
+| Acceptance criteria tree           |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Structured AC decomposition                                 |
+| Evaluation principles              |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Weighted scoring against principles                         |
+| Exit conditions                    |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Deterministic termination logic                             |
+| Event sourcing (SQLite)            |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Full event log, replay support                              |
+| Checkpoint / resume                |     Yes     |    Yes    |   Yes    |  Yes   | Partial  |     No      |  Yes   | `--resume <session_id>` everywhere; Kiro forwards to `--resume-id` **when the caller supplies the id** — headless does not surface session ids, so automatic checkpoint/resume is future work; Copilot CLI does not expose a resume API; Pi resumes with its native `--session` flag |
+| TUI dashboard                      |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | Textual-based progress view                                 |
+| Interview (Socratic seed creation) |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | `ouroboros init start ...` with the appropriate LLM backend |
+| Dry-run validation                 |     Yes     |    Yes    |   Yes    |  Yes   |   Yes    |     Yes     |  Yes   | `--dry-run` validates without executing                     |
+| Live model discovery               |     No      |    No     |    No    |   No   |    No    |     Yes     |   No   | Only Copilot queries its provider's models API at setup time and lets you pick a default from the live list |
 
 ### Runtime Layer (differs by backend)
 
 These capabilities depend on the runtime backend's native features and execution model.
 
-| Capability                |             Claude Code             |       Codex CLI       |                         OpenCode                          |                                   Hermes                                   |           Kiro CLI           |                                Copilot CLI                                | Notes                                                            |
-| ------------------------- | :---------------------------------: | :-------------------: | :-------------------------------------------------------: | :------------------------------------------------------------------------: | :--------------------------: | :-----------------------------------------------------------------------: | ---------------------------------------------------------------- |
-| **Authentication**        |        Max Plan subscription        |    OpenAI API key     |        Provider API keys (configured in OpenCode)         |        NousResearch (or compatible provider) API key or local model        |      Kiro AWS sign-in        | GitHub Copilot subscription via `gh auth login`                           | No API key needed for Claude Code, Kiro, or Copilot              |
-| **Underlying model**      |         Claude (Anthropic)          |   GPT-5.4+ (OpenAI)   | Provider-dependent (OpenCode supports multiple providers) | Provider-dependent (Hermes supports multiple providers) or Any local model | Claude (via AWS) + others    | Live-discovered (Claude, GPT-5, etc.; whatever your subscription grants)  | Copilot is the only runtime with a live model picker             |
-| **Tool surface**          | Read, Write, Edit, Bash, Glob, Grep | Codex-native tool set |            Read, Write, Edit, Bash, Glob, Grep            |                      Custom skills via MCP + run cmd                       |   Kiro-native tool set       | Read, Write, Edit, Bash, Glob, Grep (via `--available-tools` allowlist)   | Different tool implementations; same task outcomes               |
-| **Sandbox / permissions** |    Claude Code permission system    |  Codex sandbox model  |                OpenCode permission system                 |                          Hermes permission system                          | `--trust-tools` / `--trust-all-tools` | `--add-dir <CWD>` boundary + `--allow-tool` envelope             | Each runtime manages its own safety boundaries                   |
-| **Cost model**            |        Included in Max Plan         | Per-token API charges |              Depends on configured provider               |                            Depends on API/Local                            |    Included in Kiro plan     | Included in Copilot subscription                                          | See [OpenAI pricing](https://openai.com/pricing) for Codex costs |
-| **Declared capabilities** | skill_dispatch, targeted_resume, structured_output | all three | all three | all three | skill_dispatch only; `targeted_resume=False` (headless does not surface session ids), `structured_output=False` (plain-text stdio) | skill_dispatch only; `targeted_resume=False` (no resume API); `structured_output=False` (no `--output-schema`, JSON via prompt directive) | See `RuntimeCapabilities` on the adapter |
+| Capability                |             Claude Code             |       Codex CLI       |                         OpenCode                          |                                   Hermes                                   |           Kiro CLI           |                                Copilot CLI                                |             Pi CLI              | Notes                                                            |
+| ------------------------- | :---------------------------------: | :-------------------: | :-------------------------------------------------------: | :------------------------------------------------------------------------: | :--------------------------: | :-----------------------------------------------------------------------: | :-----------------------------: | ---------------------------------------------------------------- |
+| **Authentication**        |        Max Plan subscription        |    OpenAI API key     |        Provider API keys (configured in OpenCode)         |        NousResearch (or compatible provider) API key or local model        |      Kiro AWS sign-in        | GitHub Copilot subscription via `gh auth login`                           | Pi CLI account/session          | No API key needed for Claude Code, Kiro, Copilot, or Pi CLI      |
+| **Underlying model**      |         Claude (Anthropic)          |   GPT-5.4+ (OpenAI)   | Provider-dependent (OpenCode supports multiple providers) | Provider-dependent (Hermes supports multiple providers) or Any local model | Claude (via AWS) + others    | Live-discovered (Claude, GPT-5, etc.; whatever your subscription grants)  | Pi-selected or `--model` value  | Copilot is the only runtime with a live model picker             |
+| **Tool surface**          | Read, Write, Edit, Bash, Glob, Grep | Codex-native tool set |            Read, Write, Edit, Bash, Glob, Grep            |                      Custom skills via MCP + run cmd                       |   Kiro-native tool set       | Read, Write, Edit, Bash, Glob, Grep (via `--available-tools` allowlist)   | Pi-native tool set              | Different tool implementations; same task outcomes               |
+| **Sandbox / permissions** |    Claude Code permission system    |  Codex sandbox model  |                OpenCode permission system                 |                          Hermes permission system                          | `--trust-tools` / `--trust-all-tools` | `--add-dir <CWD>` boundary + `--allow-tool` envelope             | Pi CLI permission model         | Each runtime manages its own safety boundaries                   |
+| **Cost model**            |        Included in Max Plan         | Per-token API charges |              Depends on configured provider               |                            Depends on API/Local                            |    Included in Kiro plan     | Included in Copilot subscription                                          | Depends on Pi account/provider  | See [OpenAI pricing](https://openai.com/pricing) for Codex costs |
+| **Declared capabilities** | skill_dispatch, targeted_resume, structured_output | all three | all three | all three | skill_dispatch only; `targeted_resume=False` (headless does not surface session ids), `structured_output=False` (plain-text stdio) | skill_dispatch only; `targeted_resume=False` (no resume API); `structured_output=False` (no `--output-schema`, JSON via prompt directive) | all three | See `RuntimeCapabilities` on the adapter |
 
 ### Integration Surface (UX differences)
 
-| Aspect                      | Claude Code                                   | Codex CLI                                                                                                                                                                                                                                                    | OpenCode                                           | Hermes                                           | Kiro CLI                                                                                      | Copilot CLI                                                                                                                                                  |
-| --------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Primary UX**              | In-session skills and MCP server              | Session-oriented Ouroboros runtime over Codex CLI transport                                                                                                                                                                                                  | MCP server integration                             | In-session skills and MCP server                 | In-session skills and MCP server (Kiro headless mode)                                         | In-session skills and MCP server (Copilot CLI session)                                                                                                       |
-| **Skill shortcuts (`ooo`)** | Yes -- skills loaded into Claude Code session | Yes -- after `ouroboros setup --runtime codex` installs managed skills into `~/.codex/skills/`, rules into `~/.codex/rules/`, and the MCP/env hookup into `~/.codex/config.toml`. Keep role-specific Ouroboros model overrides in `~/.ouroboros/config.yaml` | Yes -- after `ouroboros setup --runtime opencode`  | Yes -- after `ouroboros setup --runtime hermes`  | Yes -- after `ouroboros setup --runtime kiro` the Ouroboros MCP server is registered in `~/.kiro/settings/mcp.json` with `OUROBOROS_RUNTIME=kiro` / `OUROBOROS_LLM_BACKEND=kiro` baked in | Yes -- after `ouroboros setup --runtime copilot` the MCP server is registered in `~/.copilot/mcp-config.json` with `OUROBOROS_AGENT_RUNTIME=copilot` / `OUROBOROS_LLM_BACKEND=copilot` baked in |
-| **MCP integration**         | Native MCP server support                     | Deterministic skill/MCP dispatch through the Ouroboros Codex adapter                                                                                                                                                                                         | Native MCP server support                          | Native MCP server support                        | Native MCP server support; `SkillInterceptor` routes `ooo <skill>` prefixes before spawning Kiro subprocess | Native MCP server support; restart required after first registration so Copilot binds the new child         |
-| **Session context**         | Shares Claude Code session context            | Preserved via runtime handles, native session IDs, and resume support                                                                                                                                                                                        | Session IDs + resume via `--session`               | Preserved via session IDs and internal parser    | Headless runs do not surface session IDs; callers may pass an externally sourced `--resume-id`, but automatic targeted resume is not declared yet | Copilot CLI does not expose a session resume API; checkpointing happens at the Ouroboros lineage layer                                                       |
-| **Install extras**          | `ouroboros-ai[claude]`                        | `ouroboros-ai` (base package) + `codex` on PATH                                                                                                                                                                                                              | `ouroboros-ai` (base package) + `opencode` on PATH | `ouroboros-ai` (base package) + `hermes` on PATH | `ouroboros-ai[claude]` + `kiro-cli` on PATH                                                   | `ouroboros-ai[mcp]` + `copilot` on PATH + `gh` on PATH (for live model discovery)                                                                            |
+| Aspect                      | Claude Code                                   | Codex CLI                                                                                                                                                                                                                                                    | OpenCode                                           | Hermes                                           | Kiro CLI                                                                                      | Copilot CLI                                                                                                                                                  | Pi CLI                                      |
+| --------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
+| **Primary UX**              | In-session skills and MCP server              | Session-oriented Ouroboros runtime over Codex CLI transport                                                                                                                                                                                                  | MCP server integration                             | In-session skills and MCP server                 | In-session skills and MCP server (Kiro headless mode)                                         | In-session skills and MCP server (Copilot CLI session)                                                                                                       | Pi CLI JSON-mode runtime                    |
+| **Skill shortcuts (`ooo`)** | Yes -- skills loaded into Claude Code session | Yes -- after `ouroboros setup --runtime codex` installs managed skills into `~/.codex/skills/`, rules into `~/.codex/rules/`, and the MCP/env hookup into `~/.codex/config.toml`. Keep role-specific Ouroboros model overrides in `~/.ouroboros/config.yaml` | Yes -- after `ouroboros setup --runtime opencode`  | Yes -- after `ouroboros setup --runtime hermes`  | Yes -- after `ouroboros setup --runtime kiro` the Ouroboros MCP server is registered in `~/.kiro/settings/mcp.json` with `OUROBOROS_RUNTIME=kiro` / `OUROBOROS_LLM_BACKEND=kiro` baked in | Yes -- after `ouroboros setup --runtime copilot` the MCP server is registered in `~/.copilot/mcp-config.json` with `OUROBOROS_AGENT_RUNTIME=copilot` / `OUROBOROS_LLM_BACKEND=copilot` baked in | Yes -- `SkillInterceptor` routes `ooo <skill>` prefixes before spawning Pi |
+| **MCP integration**         | Native MCP server support                     | Deterministic skill/MCP dispatch through the Ouroboros Codex adapter                                                                                                                                                                                         | Native MCP server support                          | Native MCP server support                        | Native MCP server support; `SkillInterceptor` routes `ooo <skill>` prefixes before spawning Kiro subprocess | Native MCP server support; restart required after first registration so Copilot binds the new child         | Deterministic skill/MCP dispatch through the Ouroboros Pi adapter |
+| **Session context**         | Shares Claude Code session context            | Preserved via runtime handles, native session IDs, and resume support                                                                                                                                                                                        | Session IDs + resume via `--session`               | Preserved via session IDs and internal parser    | Headless runs do not surface session IDs; callers may pass an externally sourced `--resume-id`, but automatic targeted resume is not declared yet | Copilot CLI does not expose a session resume API; checkpointing happens at the Ouroboros lineage layer                                                       | Native Pi session IDs preserved through runtime handles |
+| **Install extras**          | `ouroboros-ai[claude]`                        | `ouroboros-ai` (base package) + `codex` on PATH                                                                                                                                                                                                              | `ouroboros-ai` (base package) + `opencode` on PATH | `ouroboros-ai` (base package) + `hermes` on PATH | `ouroboros-ai[claude]` + `kiro-cli` on PATH                                                   | `ouroboros-ai[mcp]` + `copilot` on PATH + `gh` on PATH (for live model discovery)                                                                            | `ouroboros-ai` (base package) + `pi` on PATH |
 
 ## What Stays the Same
 
@@ -104,12 +104,12 @@ demote a persisted `opencode_mode == "plugin"` to `subprocess` for the
 authoring handlers, because a `_subagent` envelope would have no receiver
 outside an active OpenCode bridge plugin session.
 
-| Phase                   | `claude` | `codex` | `opencode` | `hermes` | `gemini` | `kiro` | `copilot` |
-| ----------------------- | :------: | :-----: | :--------: | :------: | :------: | :----: | :-------: |
-| 1. Interview authoring  | in-process | in-process | in-process | in-process | in-process | in-process | in-process |
-| 2. Seed generation      | in-process | in-process | in-process | in-process | in-process | in-process | in-process |
-| 3. Seed repair          | in-process | in-process | in-process | in-process | in-process | in-process | in-process |
-| 4. Run handoff (Seed →) | claude adapter | codex adapter | opencode adapter (see entry-point note below) | hermes adapter | gemini adapter | kiro adapter | copilot adapter |
+| Phase                   | `claude` | `codex` | `opencode` | `hermes` | `gemini` | `kiro` | `copilot` | `pi` |
+| ----------------------- | :------: | :-----: | :--------: | :------: | :------: | :----: | :-------: | :--: |
+| 1. Interview authoring  | in-process | in-process | in-process | in-process | in-process | in-process | in-process | in-process |
+| 2. Seed generation      | in-process | in-process | in-process | in-process | in-process | in-process | in-process | in-process |
+| 3. Seed repair          | in-process | in-process | in-process | in-process | in-process | in-process | in-process | in-process |
+| 4. Run handoff (Seed →) | claude adapter | codex adapter | opencode adapter (see entry-point note below) | hermes adapter | gemini adapter | kiro adapter | copilot adapter | pi adapter |
 
 > **Run-handoff `opencode_mode` differs by entry point.** The CLI
 > entry point [`cli/commands/auto.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/cli/commands/auto.py)
@@ -160,6 +160,7 @@ The table below covers the three currently shipped backends. Because Ouroboros u
 | Want to use the Hermes Agent (open source local & API agent)           | Hermes (`runtime_backend: hermes`)                                            |
 | Want to use Kiro CLI (AWS-provided coding agent, browser-free headless) | Kiro (`runtime_backend: kiro`)                                                |
 | Have a GitHub Copilot subscription and want the live model picker       | Copilot CLI (`runtime_backend: copilot`)                                      |
+| Want to use the Pi coding agent through JSON mode                       | Pi CLI (`runtime_backend: pi`)                                                |
 | Want to use Anthropic's Claude models                                  | Claude Code or Copilot CLI (Claude models exposed via Copilot subscription)   |
 | Want to use OpenAI's GPT models                                        | Codex CLI or Copilot CLI                                                      |
 | Want to use multiple providers via a single runtime                    | OpenCode or Copilot CLI (Copilot multiplexes Anthropic + OpenAI under one auth) |
@@ -175,5 +176,6 @@ The table below covers the three currently shipped backends. Because Ouroboros u
 - [OpenCode runtime guide](runtime-guides/opencode.md)
 - [Kiro CLI runtime guide](runtime-guides/kiro.md)
 - [GitHub Copilot CLI runtime guide](runtime-guides/copilot.md)
+- [Pi JSON mode documentation](https://pi.dev/docs/latest/json)
 - [Platform support matrix](platform-support.md) (OS and Python version compatibility)
 - [Architecture overview](architecture.md) — including [How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter)

{ouroboros_ai-0.40.2.dev16 → ouroboros_ai-0.40.2.dev18}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.40.2.dev16'
-__version_tuple__ = version_tuple = (0, 40, 2, 'dev16')
+__version__ = version = '0.40.2.dev18'
+__version_tuple__ = version_tuple = (0, 40, 2, 'dev18')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.40.2.dev16 → ouroboros_ai-0.40.2.dev18}/src/ouroboros/providers/__init__.py

@@ -47,6 +47,10 @@ def __getattr__(name: str) -> object:
         from ouroboros.providers.goose_cli_adapter import GooseCliLLMAdapter
 
         return GooseCliLLMAdapter
+    if name == "PiLLMAdapter":
+        from ouroboros.providers.pi_llm_adapter import PiLLMAdapter
+
+        return PiLLMAdapter
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
@@ -66,6 +70,7 @@ __all__ = [
     "OpenCodeLLMAdapter",
     "HermesCliLLMAdapter",
     "GooseCliLLMAdapter",
+    "PiLLMAdapter",
     "LiteLLMAdapter",
     # Factory helpers
     "create_llm_adapter",

ouroboros_ai-0.40.2.dev18/tests/integration/test_pi_native_smoke.py

@@ -0,0 +1,113 @@
+"""Opt-in smoke test for the native Pi CLI runtime.
+
+Skipped by default so regular CI does not require a real Pi installation,
+credentials, or network access. To run locally, install/authenticate the Pi CLI
+and set ``OUROBOROS_PI_NATIVE_SMOKE=1``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import shutil
+import subprocess
+from typing import NamedTuple
+
+import pytest
+
+from ouroboros.config import get_pi_cli_path
+from ouroboros.orchestrator.runtime_factory import create_agent_runtime
+
+SMOKE_ENABLED = os.environ.get("OUROBOROS_PI_NATIVE_SMOKE", "").strip() == "1"
+REFERENCE_REPO_ENV = "OUROBOROS_PI_REFERENCE_REPO"
+
+
+class GitSnapshot(NamedTuple):
+    """Minimal repository state used to detect smoke-test side effects."""
+
+    head: str
+    status: str
+
+
+def _reference_repo_path() -> Path | None:
+    raw_path = os.environ.get(REFERENCE_REPO_ENV, "").strip()
+    if not raw_path:
+        return None
+    return Path(raw_path).expanduser()
+
+
+def _git_snapshot(path: Path | None) -> GitSnapshot | None:
+    if path is None or not path.exists():
+        return None
+
+    head = subprocess.run(
+        ["git", "-C", str(path), "rev-parse", "HEAD"],
+        check=True,
+        capture_output=True,
+        text=True,
+    ).stdout.strip()
+    status = subprocess.run(
+        [
+            "git",
+            "-C",
+            str(path),
+            "status",
+            "--porcelain=v1",
+            "--untracked-files=all",
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    ).stdout
+    return GitSnapshot(head=head, status=status)
+
+
+def _configured_pi_cli_path() -> str | None:
+    configured_path = get_pi_cli_path()
+    if not configured_path:
+        return None
+    return configured_path
+
+
+@pytest.fixture()
+def reference_repo_snapshot() -> GitSnapshot | None:
+    reference_repo = _reference_repo_path()
+    before = _git_snapshot(reference_repo)
+    yield before
+    after = _git_snapshot(reference_repo)
+    assert after == before, f"{reference_repo} was modified by the Pi smoke test"
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+@pytest.mark.skipif(
+    not SMOKE_ENABLED,
+    reason="set OUROBOROS_PI_NATIVE_SMOKE=1 to enable the real Pi CLI smoke test",
+)
+async def test_real_pi_cli_runtime_returns_response_without_reference_repo_side_effects(
+    tmp_path: Path,
+    reference_repo_snapshot: GitSnapshot | None,
+) -> None:
+    del reference_repo_snapshot
+    if shutil.which("pi") is None and _configured_pi_cli_path() is None:
+        pytest.skip("Pi CLI is not on PATH and no Pi CLI path is configured via env/config")
+
+    runtime = create_agent_runtime(
+        backend="pi",
+        cwd=tmp_path,
+        permission_mode="acceptEdits",
+    )
+
+    result = await runtime.execute_task_to_result(
+        'Reply with exactly the word "ready" and nothing else.',
+        tools=[],
+        system_prompt="You are running a smoke test. Return only the requested word.",
+    )
+
+    assert runtime.runtime_backend == "pi"
+    assert result.is_ok, f"Pi CLI returned error: {result.error}"
+    task_result = result.value
+    assert task_result.success is True
+    assert task_result.final_message.strip()
+    assert "ready" in task_result.final_message.lower()
+    assert task_result.messages

ouroboros_ai-0.40.2.dev18/tests/unit/providers/test_public_exports.py

@@ -0,0 +1,9 @@
+"""Regression tests for provider package public exports."""
+
+import ouroboros.providers as providers
+from ouroboros.providers.pi_llm_adapter import PiLLMAdapter
+
+
+def test_pi_llm_adapter_is_package_exported() -> None:
+    assert providers.PiLLMAdapter is PiLLMAdapter
+    assert "PiLLMAdapter" in providers.__all__