# 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):

```sh
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)

```json
{
  "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:

```json
{ "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.