[Feature] Add Pi support via interactive extension bridge and CLI runtime backend

[devkade]

Problem

Ouroboros currently does not have a first-class Pi integration path.

A generic “Pi support” request is ambiguous because Pi can be integrated in two different ways:

1. From inside an interactive Pi session, where a user wants to invoke Ouroboros workflows such as ooo interview, ooo run, or ooo status.
2. From Ouroboros itself, where Pi should act as a headless CLI runtime backend for task execution.

These are different transport and lifecycle contracts. If they are not separated, Pi support may accidentally conflate interactive extension behavior with subprocess runtime behavior, leading to unclear setup, recursive dispatch, duplicated workflow semantics outside Ouroboros core, or a runtime backend without a clear event normalization contract.

Why now

Pi already exposes enough surface to support both integration paths:

• Pi has an extension/session model suitable for interactive command projection.
• Pi does not currently provide native MCP support, so an explicit bridge layer is needed for MCP workflows.
• Pi CLI supports machine-readable output through pi -p --mode json, which emits JSONL events suitable for a subprocess runtime backend.
• Ouroboros already has comparable patterns through Codex CLI runtime support and OpenCode’s split between interactive plugin integration and headless subprocess runtime support.

Defining the architecture now would prevent a partial Pi integration from growing in the wrong direction.

User / persona

This affects users who want to:

• use Ouroboros workflows naturally from inside Pi;
• run ooo workflows through Pi without manually switching tools;
• use Pi as an Ouroboros execution runtime;
• preserve Ouroboros session/job/seed/execution semantics while using Pi as either the host or backend.

Current behavior

Today, Pi is not a first-class Ouroboros runtime or interactive integration target.

In particular:

• Pi sessions do not have a documented ooo command projection path into Ouroboros MCP tools.
• Pi lacks native MCP support, so an explicit bridge contract is required.
• Ouroboros does not have a PiCliRuntime equivalent to existing CLI runtime backends.
• Pi JSONL events are not normalized into Ouroboros AgentMessage / RuntimeHandle values.
• There is no documented boundary between interactive Pi extension behavior and headless Pi subprocess execution.
• The runtime capability matrix and runtime guides do not describe Pi as a supported or planned backend.

Desired behavior

Ouroboros should support Pi through two explicit integration paths.

1. Interactive Pi extension bridge

Users should be able to invoke Ouroboros workflows from inside a Pi session:

User in Pi
  → exact `ooo ...` command
  → pi-ouroboros extension
  → pi-mcp-porter generic MCP bridge
  → Ouroboros MCP tools / core workflow state
  → Pi session projection

This path should support commands such as:

ooo help
ooo interview <goal>
ooo seed <session>
ooo run <seed>
ooo status <id>
ooo cancel <id>

Pi-visible output should preserve canonical Ouroboros identifiers such as:

session_id
seed_id
job_id
execution_id

2. Pi CLI runtime backend

Ouroboros should be able to use Pi as a headless task execution runtime:

Ouroboros executor
  → PiCliRuntime.execute_task(prompt)
  → pi -p --mode json
  → Pi JSONL event stream
  → PiEventNormalizer
  → Ouroboros AgentMessage / RuntimeHandle

The initial CLI backend should use:

pi -p --mode json

not pi --mode rpc.

pi --mode rpc is richer and may be useful later for a long-lived controller, but it should not be the initial subprocess runtime contract.

Proposed solution

Add a Pi support design with two separate implementation lanes.

Interactive extension bridge

Introduce or document:

• pi-mcp-porter as a generic Pi ↔ MCP bridge substrate;
• pi-ouroboros as the Ouroboros-specific Pi extension/projection layer.

Responsibilities:

• detect exact ooo commands in Pi sessions;
• call Ouroboros MCP tools through pi-mcp-porter;
• preserve Ouroboros lifecycle identifiers;
• render Pi-friendly results, statuses, diagnostics, and errors;
• avoid reimplementing Ouroboros workflow logic inside the Pi extension.

CLI runtime backend

Add a PiCliRuntime that invokes Pi in isolated JSON print mode.

Initial command shape:

pi \
  -p \
  --mode json \
  --no-extensions \
  --no-skills \
  --no-prompt-templates \
  --no-themes

Prompt delivery should prefer stdin where possible to avoid command-line length limits:

printf '%s' "$PROMPT" | pi -p --mode json

Add a PiEventNormalizer that maps Pi JSONL events into Ouroboros runtime messages.

Expected Pi event types include:

session
agent_start
turn_start
message_start
message_update
message_end
turn_end
agent_end

The session.id field should become the native Pi runtime session identifier in RuntimeHandle.

Example mapping:

RuntimeHandle(
  backend="pi",
  kind="agent_runtime",
  native_session_id=<Pi session id>,
  cwd=<working directory>
)

Final result extraction can initially prefer turn_end.message, with agent_end.messages as a fallback.

Documentation updates required

If this feature adds a new runtime backend or CLI/config surface, it should follow the contributor documentation coverage rules.

Expected documentation updates include:

• docs/runtime-capability-matrix.md — add Pi as a runtime row with accurate capability status.
• docs/runtime-guides/pi.md — create a Pi runtime guide.
• docs/cli-reference.md — update --runtime option description if pi becomes a supported value.
• docs/getting-started.md — update prerequisites/setup if Pi or pi-mcp-porter installation is required.
• README.md — review quick-start/config snippets if the new runtime changes day-one setup.
• Any setup or MCP bridge behavior should also be reflected in the relevant setup/MCP documentation if new commands or config keys are added.

Constraints

• Pi should not be treated as if it has native MCP support.
• pi-mcp-porter should remain a generic MCP bridge, not an Ouroboros-specific integration.
• pi-ouroboros should remain a Pi projection/command layer, not a reimplementation of Ouroboros.
• Interactive Pi extension loading should be disabled in headless PiCliRuntime execution by default to avoid double dispatch or recursion.
• The initial CLI runtime backend should use pi -p --mode json.
• pi --mode rpc should be reserved for later controller-style integration unless there is a strong reason to start there.
• Tool permissions should be conservative by default.
• Docs must not list Pi as a working runtime until create_agent_runtime() actually supports it and no NotImplementedError/placeholder behavior remains.
• If a new CLI flag, config key, or setup behavior is added, the matching docs must be updated in the same change or explicitly tracked.

Suggested initial tool policy mapping:

Ouroboros policy	Pi CLI behavior
no tools	--no-tools
read-only	--tools read,grep,find,ls
workspace-write	--tools read,grep,find,ls,edit,write
shell-enabled	add bash only when explicitly allowed

Non-goals

• Do not fork or reimplement Ouroboros core workflows.
• Do not make Pi-local state the source of truth for Ouroboros sessions/jobs.
• Do not assume Pi has native MCP support.
• Do not make pi-mcp-porter Ouroboros-specific.
• Do not load pi-ouroboros inside headless PiCliRuntime subprocesses by default.
• Do not use pi --mode rpc as the initial runtime backend contract.
• Do not require full OpenCode-style task-pane/subagent UI parity in the first interactive bridge.
• Do not enable shell/write tools by default in the Pi runtime backend.
• Do not document Pi as generally available until the runtime and/or extension path is actually implemented and verified.

Alternatives considered

Only implement interactive Pi extension support

This would let Pi users call Ouroboros from inside Pi, but it would not let Ouroboros use Pi as a headless execution runtime. That would leave Pi behind Codex/OpenCode-style runtime support.

Only implement Pi CLI runtime backend

This would support headless execution but would not solve the Pi session UX problem. Users inside Pi would still lack a natural ooo workflow bridge.

Use pi --mode rpc as the first runtime backend contract

RPC mode is more powerful, but it introduces significantly more lifecycle complexity:

• persistent subprocess management;
• JSONL stdin writer;
• command ID correlation;
• prompt accepted vs prompt completed distinction;
• abort/follow-up/steering mapping;
• shutdown handling;
• extension UI request/response handling.

For the first runtime backend, pi -p --mode json better matches the existing subprocess runtime pattern used by other runtimes.

Reimplement Ouroboros workflow behavior inside Pi

This would make Pi integration more independent, but it would duplicate core workflow semantics and risk divergence. Ouroboros should remain the source of truth.

Acceptance criteria

• The design clearly separates interactive Pi extension bridge from Pi CLI runtime backend.
• pi-mcp-porter is treated as a generic MCP bridge substrate.
• pi-ouroboros is treated as the Ouroboros-specific Pi command/projection layer.
• Interactive Pi support documents exact ooo command routing.
• Pi-visible interactive output preserves canonical Ouroboros IDs such as session_id, seed_id, job_id, and execution_id.
• PiCliRuntime uses pi -p --mode json as the initial subprocess runtime contract.
• pi --mode rpc is documented as future controller work, not the initial backend.
• Headless Pi runtime execution disables interactive extension surfaces by default.
• Pi JSONL events are normalized into Ouroboros AgentMessage and RuntimeHandle values.
• session.id from Pi JSON output is captured as the native Pi runtime session identifier.
• Final assistant output is extracted from turn_end.message or agent_end.messages.
• Runtime errors, malformed JSON, missing binaries, and setup failures produce actionable diagnostics.
• Tests or fixtures cover Pi JSON event normalization and final result extraction.
• No Ouroboros core workflow semantics are reimplemented inside Pi extension or runtime adapter code.
• If pi is added as a runtime backend, docs/runtime-capability-matrix.md includes an accurate Pi row.
• If pi is added as a runtime backend, docs/runtime-guides/pi.md exists.
• If pi becomes a valid --runtime value, docs/cli-reference.md documents it.
• docs/getting-started.md documents any required Pi / pi-mcp-porter prerequisites.
• Docs do not present Pi as fully available while implementation remains a placeholder or raises NotImplementedError.

References

Comparable existing patterns:

• Existing Codex support demonstrates a CLI runtime backend pattern.
• Existing OpenCode support demonstrates the need to separate interactive host integration from subprocess/headless runtime execution.
• Pi’s --mode json provides a JSONL event stream suitable for an initial PiCliRuntime.
• Pi’s --mode rpc provides a richer bidirectional protocol that may be useful for later controller-style integration.
• CONTRIBUTING.md requires new runtime backends to update runtime capability docs, runtime guides, CLI reference, and getting-started prerequisites.

Checklist

• I searched existing issues and discussions first.
• I explained the problem, not just the solution.
• I included clear scope boundaries and non-goals.
• I listed concrete acceptance criteria.

[ouroboros-agent]

This looks like a multi-PR effort that needs design discussion before implementation. Labeling needs-design for human planning.

Scope assessment:

• Runtime backend work in src/ouroboros/orchestrator/adapter.py, src/ouroboros/orchestrator/runner.py, and CLI entrypoints such as src/ouroboros/cli/commands/run.py to add a new Pi execution path and resume/runtime-handle semantics.
• New event normalization and integration boundaries across orchestrator and MCP surfaces, including Pi JSONL -> AgentMessage / RuntimeHandle mapping and explicit separation between interactive bridge behavior and headless runtime behavior.
• Required test and documentation expansion across tests/unit/orchestrator/, tests/e2e/, CONTRIBUTING.md, docs/cli-reference.md, plus new runtime capability and guide docs.
• Estimated complexity is architectural rather than a single safe patch because it introduces a new backend contract and a second integration lane with separate lifecycle rules.

Suggested approach:

• Split this into a design phase first: define the runtime interface changes, Pi event schema normalization contract, and the boundary between pi-ouroboros and any generic MCP bridge.
• After design approval, implement in staged PRs: runtime backend, tests/fixtures, then docs and capability-matrix updates.

ouroboros-agent[bot]

[shaun0927]

Thanks for the careful framing — the dual-lane separation (interactive extension bridge vs. headless CLI runtime backend), the choice of pi -p --mode json over --mode rpc for the initial backend, and the explicit non-goals are the kind of pre-design discipline this repo benefits from.

Routing per SSOT #961:

1. Current verdict. The roadmap warden has classified this as broad needs-design work and not a safe autonomous implementation candidate in every 2026-05-20 freshness sync. I want to keep that posture for now — please treat this issue as a design thread, not an implementation queue.

2. Why it doesn't enter an implementation lane yet. Two explicit SSOT rules apply:

• "New AgentOS substrate work should attach to one of these surfaces instead of opening a new issue." Pi support would introduce two new surfaces at once (a runtime backend + an extension projection layer), which is exactly what the SSOT is designed to prevent.
• Wonder-Engine-style scope-creep guard. Tier 2 ([Feature] Define Run/Step/Artifact projections as the canonical harness vocabulary #946 projection vocabulary, Agent OS: introduce typed Workflow IR for fat-harness execution planning #956 Workflow IR) and the Agent OS plugins: standardize lifecycle hooks, permissions, and audit events #939 plugin umbrella are still open. Adding another lane before those close has historically caused the 0% → 79% → 68% convergence oscillation documented under the meta-roadmap layer.
• The five hard gates on default ooo run behavior (RFC v2: Thin Skill (YAML) + Fat Harness — Composable Execution Invariants #830 v2 / feat(orchestrator): add fat-harness baseline metrics report #977 baseline) are the active falsifiability frame; a new create_agent_runtime() backend cannot land cleanly without measurement comparability against that baseline.

3. Where the two lanes actually belong. Instead of carrying #1139 as a standalone substrate issue, I'd like the design folded into canonical surfaces:

• Interactive extension bridge (pi-ouroboros + pi-mcp-porter) → fold into Agent OS plugins: standardize lifecycle hooks, permissions, and audit events #939 as a plugin-lifecycle / permission / projection follow-up slice. This is the same surface where feat(plugin): prompt for required trust grants on install #1141 (plugin trust-grant prompting) and docs(plugin): define tool-call hook contract #1143 (tool-call hook contract) already live, so it inherits the right gates.
• `PiCliRuntime` headless backend → keep as a scoped design comment alongside the existing CLI runtime adapter pattern (`codex_cli_runtime.py`, `opencode_runtime.py`, `gemini_cli_runtime.py`, `copilot_cli_runtime.py`, `goose_runtime.py`). Implementation should wait until Tier 2 closes: `RuntimeHandle` semantics and JSONL→event normalization will be shaped by [Feature] Define Run/Step/Artifact projections as the canonical harness vocabulary #946 projection vocabulary, so landing Pi before that risks rework.

4. Design-comment checklist before any PR opens. None of these block the design discussion, but they should be settled here first:

• Authoritative Pi vendor link + version pin (the issue references the CLI but doesn't link upstream).
• Verify the flag set actually matches upstream — `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, and the `--tools edit,write,bash` token names should be cited from upstream docs, not assumed.
• Naming policy that disambiguates Ouroboros `session_id` from Pi `session.id` in projections and logs (suggest `pi_session_id` / `ouroboros_session_id` in projection surfaces).
• Ownership of `pi-mcp-porter` and `pi-ouroboros` — in-repo adapters (mirroring our other CLI runtimes) or external packages.

5. Concrete next step. This issue stays open as the design thread. Follow-up design notes for the extension/MCP-bridge lane should be cross-linked to #939; the `PiCliRuntime` lane should remain a comment thread here, with no PR until Tier 2 (#946 / #956) closes or a maintainer explicitly broadens the scope.

Thanks again for the thoroughness — this is the right shape for the design, just not the right timing for an implementation merge train yet.

[devkade]

Thanks for the careful review and routing. Adding some public references for the design-comment checklist in item 4, especially around the Pi vendor link, CLI flag surface, MCP bridge naming, and ownership split.

1. Pi CLI vendor / package references

• Pi GitHub repository
  https://github.com/earendil-works/pi

  This is the canonical public repository for Pi. It can be used to verify the upstream project, repository ownership, source layout, issues, releases, and current implementation direction.

• Pi coding-agent package source
  https://github.com/earendil-works/pi/tree/main/packages/coding-agent

  This is the package path for the Pi CLI/coding-agent package. It can be used to inspect the CLI implementation, package metadata, examples, docs, and versioned source files.

• Pi coding-agent README
  https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md

  This can be used to check documented usage, installation instructions, examples, and official notes about non-interactive usage or extension behavior.

• Pi CLI source
  https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/cli.ts

  This can be used to verify the authoritative CLI argument definitions and command behavior from source rather than relying only on local --help output.

• npm package: @earendil-works/pi-coding-agent
  https://www.npmjs.com/package/@earendil-works/pi-coding-agent

  This can be used to verify the published package name, latest npm version, package metadata, repository link, installation surface, and distribution history.

Observed package identity from npm metadata:

@earendil-works/pi-coding-agent

Current npm latest checked:

0.75.3

2. Pi CLI flag references

The CLI flag set should be verified from the Pi package source and README above:

• CLI source
  https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/cli.ts

• Package README
  https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md

These references should be used to confirm the flags mentioned in this issue, especially:

-p / --print
--mode json
--mode rpc
--no-extensions
--no-skills
--no-prompt-templates
--no-themes
--no-context-files
--tools
--no-tools
--no-builtin-tools

They should also be used to confirm the actual built-in tool names used by Pi. In particular, the shell-capable tool name appears to be:

bash

rather than:

shell

The read-only mapping should be checked against the documented/example tool names:

read
grep
find
ls

So the proposed policy mapping should cite Pi’s actual tool names rather than inventing abstract ones.

3. MCP bridge naming correction

One terminology correction: the issue currently uses:

pi-mcp-porter

That appears to be an incorrect package/reference name.

The correct public package/reference for the Pi MCP bridge is:

pi-mcp-adapter

References:

• GitHub repository: pi-mcp-adapter
  https://github.com/nicobailon/pi-mcp-adapter

  This can be used to verify the package ownership, implementation, README, configuration behavior, command/extension registration, and MCP adapter architecture.

• npm package: pi-mcp-adapter
  https://www.npmjs.com/package/pi-mcp-adapter

  This can be used to verify the published package name, latest npm version, repository link, install command, and npm package metadata.

Current npm latest checked:

2.6.1

The README describes the package as a way to use MCP servers with Pi, and documents installation with:

pi install npm:pi-mcp-adapter

The README also documents MCP config locations and adapter behavior, including:

~/.config/mcp/mcp.json
<Pi agent dir>/mcp.json
.mcp.json
.pi/mcp.json

and adapter features such as:

lazy MCP server connection
single proxy tool
directTools configuration
MCP auth/setup flow

So references to:

pi-mcp-porter

should be corrected to:

pi-mcp-adapter

or, if the issue wants to avoid binding the design text to a package name, the more generic term:

Pi MCP adapter layer

Suggested wording:

Use `pi-mcp-adapter` as the generic Pi ↔ MCP adapter reference, and keep any Ouroboros-specific Pi behavior separate from that generic MCP bridge.

4. Session identifier naming references / design check

No external link settles this by itself, but the design should explicitly disambiguate session identifiers across the involved systems:

Ouroboros workflow/session state
Pi runtime session state
MCP connection/session state

Suggested field names to evaluate in the design:

ouroboros_session_id
pi_session_id
mcp_session_id

The Pi CLI source and JSON output behavior should be checked through the Pi references above before finalizing the exact runtime handle mapping:

• https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/cli.ts
• https://github.com/earendil-works/pi/tree/main/packages/coding-agent

5. Ownership references

These links can help settle the ownership question from comment 4:

Topic	Reference	What it verifies
Pi CLI / runtime source	https://github.com/earendil-works/pi	Upstream Pi ownership and source of truth
Pi coding-agent package	https://www.npmjs.com/package/@earendil-works/pi-coding-agent	Published CLI package name/version/repository
Pi package source path	https://github.com/earendil-works/pi/tree/main/packages/coding-agent	Actual package implementation and docs
Pi MCP adapter source	https://github.com/nicobailon/pi-mcp-adapter	Generic Pi ↔ MCP bridge implementation
Pi MCP adapter npm package	https://www.npmjs.com/package/pi-mcp-adapter	Published MCP adapter package name/version/repository

Based on these references, the likely ownership split to discuss is:

Pi CLI runtime behavior:
  upstream Pi project / @earendil-works/pi-coding-agent

Generic Pi ↔ MCP bridge:
  external pi-mcp-adapter package

Ouroboros-specific Pi projection layer:
  separate design question, possibly pi-ouroboros

Ouroboros headless Pi runtime backend:
  in-repo Ouroboros runtime adapter, if/when approved

6. Suggested issue text updates

Reference-driven text update:

- Replace `pi-mcp-porter` with `pi-mcp-adapter`; `pi-mcp-porter` was an incorrect reference, while `pi-mcp-adapter` is the public Pi MCP bridge package/reference.
- If the issue wants to avoid binding to a package name in the design text, use the generic phrase `Pi MCP adapter layer`.

Potential acceptance-criteria update:

- [ ] The design cites the upstream Pi CLI package/repository used for the runtime contract.
- [ ] The design cites the Pi CLI source or docs for `-p`, `--mode json`, `--mode rpc`, and isolation flags such as `--no-extensions`.
- [ ] The design uses Pi’s actual tool names, including `bash` for shell-capable execution.
- [ ] The design treats `pi-mcp-adapter` as the existing generic Pi ↔ MCP adapter reference.
- [ ] The design separates the generic MCP adapter layer from any Ouroboros-specific Pi projection layer.