feat: add Pi provider integration via RPC

[IgorWarzocha]

Summary

This PR is a reference implementation for adding Pi as a provider to T3 Code.

It integrates Pi in RPC mode and wires it into the existing provider/orchestration stack instead of introducing a Pi-specific execution path. The goal is to show what a realistic provider implementation looks like against the current architecture, including server runtime management, provider health, dynamic model discovery, UI integration, and failure handling.

This PR is being opened on my fork as an example implementation that can be linked from an upstream issue/proposal.

Diff:

• Code: +2,435 / -136
• Tests: +1,838 / -4
• Docs: +701 / -0

What This Adds

• Adds pi as a first-class ProviderKind across shared contracts and runtime state.
• Introduces a Pi RPC manager on the server that:
  • starts Pi in RPC mode
  • manages session lifecycle
  • sends prompts/abort/model/thinking commands
  • handles session startup and send failures safely
  • discovers available Pi models dynamically
• Adds a Pi provider adapter that maps Pi RPC events into T3's canonical provider runtime events.
• Registers Pi in the provider layer alongside Codex.
• Adds Pi health/availability checks so the UI only enables Pi when the configured runtime is actually available.
• Adds Pi model selection through the existing T3 provider/model picker flow.
• Adds Pi thinking level selection using provider-native Pi thinking levels.
• Removes the fake Pi model fallback so unavailable discovery no longer surfaces misleading model choices.
• Adds docs/spec/todo material for the provider integration work.

Design Decisions

RPC-first, not SDK-first

Pi is integrated through its RPC mode instead of embedding the SDK directly. That keeps the provider boundary consistent with how T3 already treats harnesses as external runtimes and avoids coupling the server to Pi's internal package graph and runtime assumptions.

Reuse T3's existing provider flow

This implementation does not add a Pi-only slash-command system or custom orchestration path.

Instead it plugs into the existing T3 shape:

• provider selection
• model selection
• start session / send turn
• provider runtime event ingestion
• provider health / availability

This keeps the implementation aligned with how future providers should be added.

Dynamic Pi model discovery

Pi models are discovered live via RPC instead of relying on a hard-coded static list.

This means:

• the UI reflects what the Pi runtime actually exposes
• Codex-only users do not pay the discovery cost unless Pi is relevant
• there is no misleading fallback model shown when Pi discovery is unavailable

Provider-native thinking levels only

The Pi UI only exposes actual Pi thinking levels returned/understood by the provider path. Synthetic defaults such as Pi default were removed.

Full-access only for now

This branch does not attempt to fake Codex-style approval semantics for Pi. Pi is treated as a full-access provider in this implementation.

Architecture Overview

Shared contracts

Contracts were widened so pi can flow through the existing system instead of being treated as a special case.

Server runtime

The server now contains Pi-specific runtime management that:

• starts and stops Pi RPC child processes
• recovers cleanly on startup/send failures
• handles spawn errors correctly
• keeps session state consistent across failure paths

Provider adapter layer

The Pi adapter translates Pi RPC events into canonical runtime events consumed by T3 orchestration.

A few Pi-specific edge cases had to be handled carefully:

• tool/planning steps with no user-visible assistant text
• multi-stage runs where the real user-facing answer lands after tool activity
• avoiding duplicate turn lifecycle events

Web UI

The web app now:

• exposes Pi in the provider picker only when the provider is actually available
• supports Pi model selection through the existing picker flow
• supports Pi thinking level selection
• avoids showing fake Pi models when discovery is unavailable

Failure Handling / Hardening Included

This branch includes fixes for several correctness issues that came up during implementation:

• cleans up failed Pi session starts instead of leaving half-initialized sessions registered
• resets session turn state when prompt/get_state fails mid-send
• handles Pi CLI spawn failures without crashing the server
• validates custom Pi model slugs before persisting them
• scopes Pi model discovery so Codex-only chat loads do not unnecessarily probe Pi
• respects configured Pi binary paths in provider health checks
• avoids duplicate Pi turn start events
• avoids leaking empty Pi completions into the chat UI

UX Notes

• Pi availability is health-driven, not assumed.
• Pi model discovery is on-demand / provider-scoped.
• If no Pi models are available, the UI shows that directly instead of silently falling back to a fake model.
• Provider switching still follows the existing T3 UX rather than introducing a Pi-specific command surface.

Tests / Verification

The branch includes targeted Pi coverage across server, shared, and web packages, and the implementation was verified with:

• bun lint
• bun typecheck
• targeted bun run test ... coverage for Pi runtime, provider health, discovery, picker state, and adapter behavior

Non-goals / Current Limitations

• This is not an attempt to implement Pi approval-required semantics.
• This does not redesign T3's general provider UX.
• This does not add provider-native slash-command parsing on the server.
• This is intentionally a reference implementation on a fork, not an upstream-ready PR claim.

Why This PR Exists

The intent is to provide a concrete branch that demonstrates:

• where Pi fits into T3's current architecture
• what shared abstractions needed widening
• what provider-specific behavior had to be handled
• what a future upstream Pi provider issue/implementation would likely need to cover

[IgorWarzocha]

@codex review this pr

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 719f797c69

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".