PI_agent_fallback

Plugin para Pi que asigna a cada modelo basado en créditos un modelo de fallback designado por el admin: al agotarse los créditos del modelo principal, Pi conmuta automáticamente al fallback, marca todos los cambios hechos bajo el sustituto para que el principal los revise, y revierte al principal en cuanto vuelve a estar disponible. Cada modelo define su propio fallback de forma independiente, lo que permite cadenas (modelo → fallback → fallback del fallback).

pi-fallback loads the TypeScript extension source through Pi's jiti loader. The tsup build is a verification/bundling gate; the manifest deliberately targets ./extensions, not dist.

Install and trust

Global install (recommended):

pi install npm:pi-fallback

For a project-local install, use Pi's project scope (pi install -l npm:pi-fallback). Project packages are trust-gated and extensions run with full host permissions. Review this source before trusting a project package.

Configure

The extension owns JSON configuration; it does not modify Pi's settings.json:

• Global: ~/.pi/agent/fallback-models.json
• Project: <project>/.pi/fallback-models.json (project values win)

{
  "version": 1,
  "fallbacks": { "openai-codex/gpt-5.3-codex": "anthropic/claude-sonnet-4-5" },
  "policy": { "probe": { "intervalMin": 60 }, "review": { "flagShellActivity": true } }
}

Assignments can also be managed immediately with the commands below. A project assignment is the default write target; use --global when supported.

Commands

• /fallback set <primary> <substitutes...> [--assistant=<model>] — add or replace that primary's ordered candidate set. Each mapping is root-owned: it applies only when its own model opens the episode and is never followed recursively from another candidate, so cross-set references — even mutual ones — are accepted. A self-edge or a duplicate within one primary's set (including a model given as both substitute and assistant) is still rejected.
• /fallback remove <primary> — remove one assignment; /fallback remove --all clears assignments globally and locally.
• /fallback list — show effective global/project assignments.
• /fallback status — show the episode, model, probe, and pending-review state.
• /fallback review — hand off flagged files and unattributed shell activity to the primary.
• /fallback clear — mark the current review index read without deleting history.
• /fallback reload — reload both extension-owned configuration files.

Runtime and review behavior

Only finalized, provider-specific high-confidence quota signals activate a fallback. Generic 429s, transient outages, context overflow, unknown providers, and unclassified billing text remain fail-closed. Switching occurs at a turn boundary; completed tool side effects are not replayed.

Recovery probes are silent: one early discrimination probe, then fixed-interval probes (60 minutes by default), with a valid provider reset time taking precedence. Probes pause while Pi is busy, and quota probing stops after 24 attempts. A successful probe restores the primary and reports pending review work.

Active fallback edit/write results retain a fallbackReview marker and the durable review index records model/timestamp attribution. Bash and PowerShell are recorded only as unattributed shell activity; inspect the current working-tree diff as ground truth.

Keep provider-level retries disabled so the extension can observe terminal quota failures:

{ "retry": { "provider": { "maxRetries": 0 } } }

Limits, security, and rollback

Extensions have full system access. Install only packages and project-local resources you trust. Provider error wording is version-sensitive and fixture-pinned to Pi 0.84.3; unsupported provider signals fail closed. This extension does not patch Pi core, emulate provider-native fallback, duplicate core retry/compaction, swap an in-flight request, or claim file attribution for shell mutations.

To roll back, run pi remove npm:pi-fallback (or remove the installed package) to restore stock Pi behavior. To keep the extension installed while disabling configured routing, run /fallback remove --all. Review markers and index entries are additive metadata and need no migration.