Add pi as an agent backend alongside Goose and Codex

[rtzll]

Summary

Add pi as a third agent backend so Rascal can run tasks with pi, goose, or codex.

This is feasible with the current architecture, but it is not just an enum addition. The control plane is already mostly backend-agnostic for task/run/session state, while the runner, deploy surfaces, and stored-credential flow are still shaped around exactly two backends and one credential type.

Current state

Rascal already stores agent_backend on tasks/runs and persists backend-specific task sessions, so the basic scheduling/state model can support a third backend.

The main coupling points today are:

• internal/agent: backend parsing/normalization only supports goose and codex
• cmd/rascal-runner: backend dispatch only supports runGoose and runCodex
• internal/runner/docker: session mounts and env wiring are only GOOSE_PATH_ROOT or CODEX_HOME
• runner/Dockerfile: only goose-runner and codex-runner images exist
• deploy / doctor / CLI flags: assume exactly two runner images
• stored credentials: explicitly modeled as codex_credentials and written to runDir/codex/auth.json

What needs to change

Backend plumbing

• Add pi to backend parsing and normalization
• Update config/image selection to support a Pi runner image
• Update CLI help/docs/tests that currently say goose or codex

Runner implementation

• Add a runPi(...) path in cmd/rascal-runner
• Validate the pi binary in backend-specific command checks
• Map Rascal instructions/output/session handling onto Pi CLI behavior
• Preserve the canonical run artifacts (agent.ndjson, agent_output.txt, meta.json)

Session support

• Add Pi-specific session root/home env wiring in Docker launcher
• Mount task-scoped Pi session state when session resume is enabled
• Persist/reuse backend session IDs for Pi if needed by its CLI model

Runner image / deploy

• Add a pi-runner image target or install Pi in the shared runner base image
• Extend deploy/bootstrap to build/publish the Pi runner image
• Extend remote doctor to inspect Pi image config and presence
• Add config/env support for RASCAL_RUNNER_IMAGE_PI

Credentials

This is the main design decision.

Short term:

• Support Pi with env/API-key auth only

Long term:

• Generalize stored credentials from codex_credentials to backend/provider-aware credentials
• Allow Rascal to broker both Codex and Pi credentials cleanly
• Stop hardcoding runDir/codex/auth.json as the only leased auth material path

Proposed rollout

Phase 1: MVP Pi backend

• Add pi backend enum/config/runner dispatch
• Add Pi runner image
• Add Pi session-dir wiring
• Support Pi with env/API-key auth only
• Keep existing Codex credential broker unchanged

Phase 2: Credential model refactor

• Generalize stored credentials to support multiple backends/providers
• Add Pi credential acquisition/lease/write/cleanup flow
• Update auth management CLI and API accordingly

Phase 3: Parity work

• Add Pi token-usage extraction if Pi JSON output exposes it
• Update docs/runbook/config/deploy help text
• Extend tests across runner, deploy, config, doctor, and state flows

Acceptance criteria

• Rascal accepts RASCAL_AGENT_BACKEND=pi
• The orchestrator can schedule and execute Pi-backed runs end-to-end
• Pi runs can create/update PRs the same way Goose/Codex runs do today
• Session resume works for Pi when agent sessions are enabled
• Deploy/bootstrap/doctor support a Pi runner image
• Tests and docs are updated to describe all three backends

Open questions

• Should Pi be introduced only as a direct/API-key backend first, or should stored/brokered Pi credentials be part of the first implementation?
• Does Pi expose stable enough session identifiers that we should persist backend_session_id, or is mounted session storage alone sufficient?
• Do we want three distinct runner images (goose, codex, pi) or a consolidated image with all agent CLIs installed?

Suggested first milestone

Ship Phase 1 first: Pi backend + runner image + session support, without blocking on the credential-schema refactor.

[rtzll]

Rascal started run run_924b92806c7a9d35 for this issue.

Run Settings

• Requested by: rtzll

• Trigger: issue_label

• Backend: goose

• Runner commit: 3083699eff12ea3726b473b7fdf796b188707d25

• Branches: main -> rascal/rtzll/rascal-173-924b92806c

• Session mode: all

• Resume: true

• Debug: true

• Queue delay: 0s

• Task: Add pi as an agent backend alongside Goose and Codex ## Summary Add pi as a third agent backend so Rascal can run tasks with pi, goose, or codex. This is feasible with the current architecture, but it is not just an enum addition. T...

• Context: Triggered by label 'rascal' on issue Add pi as an agent backend alongside Goose and Codex #173