fix(wrap): support Pi CLI wrapping

[manuschillerdev]

Description

Add headroom wrap pi support so Pi can be launched through Headroom like the other supported CLI agents. Pi does not honor ANTHROPIC_BASE_URL / OPENAI_BASE_URL directly, so the wrapper uses a transient Pi extension to override Pi’s built-in provider base URLs for the wrapped process.

This PR proposes creating a temporary extension with pi. Status Draft, because I want to clarify with the pi team, if there is no better option (https://discord.com/channels/1456806362351669492/1517536900175368222/1517536900175368222)

Closes #

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

Changes Made

• Added headroom wrap pi.
• Added headroom.providers.pi runtime helpers for Pi-specific provider routing.
• Launch Pi with a transient extension that routes Anthropic, Google Gemini/Vertex, OpenAI, and OpenAI Codex providers through the local Headroom proxy.
• Added focused tests for Pi wrapping behavior.
• Updated README and CHANGELOG.

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• Type checking passes (mypy headroom)
• New tests added for new functionality
• Manual testing performed

Test Output

$ uv run --no-sync ruff check headroom/cli/wrap.py headroom/providers/pi tests/test_cli/test_wrap_pi.py
All checks passed!

$ uv run --no-sync pytest tests/test_cli/test_wrap_pi.py tests/test_cli/test_wrap_goose.py
4 passed, 1 warning in 1.56s

$ uv run --no-sync python -m headroom.cli wrap pi --help | head -12
Usage: python -m headroom.cli wrap pi [OPTIONS] [PI_ARGS]...

  Launch Pi through Headroom proxy.

  Pi does not read ANTHROPIC_BASE_URL or OPENAI_BASE_URL directly. This
  wrapper creates a temporary Pi extension and launches Pi with ``-e`` so
  the extension can register provider overrides for Pi's built-in Anthropic,
  Google Gemini/Vertex, OpenAI, and OpenAI Codex providers.

$ uv run --no-sync ruff check .
benchmarks/ccr_regression_benchmark.py:293:12: UP038 Use `X | Y` in `isinstance` call instead of `(X, Y)`
headroom/cache/compression_store.py:103:12: UP038 Use `X | Y` in `isinstance` call instead of `(X, Y)`
headroom/cli/doctor.py:90:53: UP038 Use `X | Y` in `isinstance` call instead of `(X, Y)`
headroom/evals/session_probes.py:268:12: UP038 Use `X | Y` in `isinstance` call instead of `(X, Y)`
...
tests/test_proxy_warmup.py:21:1: E402 Module level import not at top of file
Found 82 errors.

$ uv run --no-sync pytest
ERROR tests/test_compress_api.py - ValueError: Expected lark version to be >= 1.1.5. Received 1.1.2.
ERROR tests/test_memory/test_embedder_mps_serialization.py - ValueError: numpy.dtype size changed, may indicate binary incompatibility. Expected 96 from C header, got 88 from PyObject
Interrupted: 2 errors during collection
7 skipped, 551 warnings, 2 errors in 24.66s

$ uv run --no-sync mypy headroom
headroom/binaries.py:345: error: Returning Any from function declared to return "str"  [no-any-return]
headroom/evals/memory/runner_v3.py:324: error: "object" has no attribute "save_memory"  [attr-defined]
Found 2 errors in 2 files (checked 377 source files)

Real Behavior Proof

• Environment: macOS, local branch fix/wrap-pi-command, Pi available at /Users/User/.bun/bin/pi
• Bug before:

❯ headroom wrap pi
Usage: headroom wrap [OPTIONS] COMMAND [ARGS]...
Try 'headroom wrap --help' for help.

Error: No such command 'pi'.
❯ which pi
/Users/User/.bun/bin/pi
❯ headroom wrap /Users/User/.bun/bin/pi
Usage: headroom wrap [OPTIONS] COMMAND [ARGS]...
Try 'headroom wrap --help' for help.

Error: No such command '/Users/User/.bun/bin/pi'.

• Exact command / steps:

headroom wrap pi

• Observed result:

  Setting up rtk for Pi...
  Downloading rtk (Rust Token Killer)...
  rtk installed at /Users/User/.headroom/bin/rtk
  rtk instructions injected into /Users/User/code/github.com/manuschillerdev/headroom/AGENTS.md

  ╔═══════════════════════════════════════════════╗
  ║               HEADROOM WRAP: PI               ║
  ╚═══════════════════════════════════════════════╝

  Starting Headroom proxy on port 8787...
  Logs: /Users/User/.headroom/logs/proxy.log
  Proxy ready on http://127.0.0.1:8787

  Launching PI (API routed through Headroom)...
  Pi extension=/var/folders/b9/mktkysmx05zg5m58wbb094q00000gq/T/headroom-pi-2xg806o9/headroom-pi-provider.ts
  Anthropic base URL=http://127.0.0.1:8787
  Google/Gemini base URL=http://127.0.0.1:8787/v1beta
  Google Vertex base URL=http://127.0.0.1:8787
  OpenAI/OpenAI Codex base URL=http://127.0.0.1:8787/v1
  Extra args: -e /var/folders/b9/mktkysmx05zg5m58wbb094q00000gq/T/headroom-pi-2xg806o9/headroom-pi-provider.ts
  Telemetry:    ENABLED (anonymous aggregate stats) | Disable: HEADROOM_TELEMETRY=off or --no-telemetry


 pi v0.79.6
 escape interrupt · ctrl+c/ctrl+d clear/exit · / commands · ! bash · ctrl+o more
 Press ctrl+o to show full startup help and loaded resources.

 Pi can explain its own features and look up its docs. Ask it how to use or extend Pi.
[...]

• Not tested:
  • Live provider request through a real model account.

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have updated the CHANGELOG.md if applicable

Screenshots (if applicable)

N/A

Additional Notes

Full pytest, full-project ruff check ., and mypy headroom were run locally. They currently fail on existing repository/environment issues unrelated to this change, as shown above. Focused lint and tests for the changed files pass.

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Paste real command output or artifact links in Testing → Test Output.
• Fill in Real Behavior Proof → Exact command / steps.
• Fill in Real Behavior Proof → Observed result.
• Fill in Real Behavior Proof → Not tested.

Please update the PR body, or move the PR back to draft while it is still in progress.

[travisday]

looking forward to this, do you know will it work with Oh My Pi? Or would that need it's own wrap as well?