pi-provider-manager

Visual configuration panel + roundrobin failover engine + provider health stats for pi coding agent.

Features

• Visual models.json editor — /providers command opens a local web panel to edit providers, models, API keys, headers, compat fields, thinking level maps, and more. Drag-to-reorder, inline rename, upstream model discovery.
• Roundrobin failover engine — register a virtual roundrobin provider that pools multiple real provider/model candidates. Sticky strategy with automatic failover on first-response timeout or stream error. If a whole candidate pass fails before streaming starts, it waits for the earliest cooldown and cycles from the preferred candidate again until one starts successfully or the request is cancelled. Per-candidate health stats and cooldown circuit-breaking.
• Provider health statistics — 7-day rolling success rate, TTFT (time-to-first-token), and total latency for every provider/model. Events append to ~/.pi/agent/roundrobin/health.jsonl and are shared across concurrent CLI processes. Collected passively via pi events.

Concurrency caveat (best-effort): the shared health.jsonl has no file lock. Append is safe (OS-level O_APPEND atomicity for small lines), but prune/reset use read-filter-rename / truncate, which can race with a concurrent append from another CLI and lose a line or two. This is acceptable for single-user, few-CLI setups; aggregation correctness does not depend on pruning (loadEvents filters by the 7-day window on read, so skipping prune only affects file size, not numbers).

• Hot reload — panel saves trigger pi.events so the roundrobin engine reloads candidates and config immediately. No restart needed.
• Idle auto-stop — the panel server shuts itself down after 5 minutes with no HTTP access, freeing port 17890. Re-run /providers to start it again. The frontend polls every 3s while open, so an active panel never times out.
• Preset management — save and switch between named candidate combinations.

Install

pi install npm:@arcaneorion/pi-provider-manager

Usage

Visual config panel

Run /providers in pi to start the local web server and open the config panel in your browser.

The panel has two tabs:

• 模型配置 (Models) — edit ~/.pi/agent/models.json with full field-level control. Fetch available models from upstream endpoints, diff against configured models, add/remove with one click.
• 轮询配置 (Roundrobin) — edit ~/.pi/agent/roundrobin/config.json. Configure virtual model metadata, candidate pool, timeout/cooldown, strategy. Save/load named presets.

Saves are hot-reloaded — the roundrobin engine picks up new candidates immediately.

Roundrobin failover

1. In the roundrobin tab, add candidates from your configured models.
2. Save the config.
3. In pi, use /model to select roundrobin/<virtualModelId>.
4. All requests now flow through the failover engine: if the current candidate times out or errors before the response stream starts, the next candidate is tried automatically. If every candidate fails, the engine waits for cooldown and starts another pass from the preferred candidate; this continues until a candidate starts successfully or the request is cancelled.

A mid-stream error is returned immediately rather than replayed on another provider, because content or tool calls may already have been emitted.

Strategy: sticky — stays on the current candidate until it fails. After cooldown, returns to the preferred (first) candidate automatically.

Provider health stats

Every provider's health stats appear in the models tab under each provider's form. Stats are a 7-day historical average (not only the current process):

• Success/fail count and rate
• Average TTFT (time to first token)
• Average total latency

Each request appends one line to ~/.pi/agent/roundrobin/health.jsonl. Multiple concurrent pi CLIs share the same file (best-effort, no file lock — see concurrency caveat above). On session start, events older than 7 days are pruned. Pending requests are tracked per provider/model in a FIFO queue so concurrent requests to the same model don't clobber each other. Use the "重置统计" button to clear the file.

Configuration

models.json

Standard pi models.json — the panel edits this file with full schema support.

roundrobin/config.json

{
  "virtualModel": {
    "id": "roundrobin",
    "name": "Model Round Robin",
    "reasoning": true,
    "input": ["text", "image"],
    "contextWindow": 200000
  },
  "candidates": [
    { "provider": "my-openai", "model": "gpt-4o" },
    { "provider": "my-anthropic", "model": "claude-sonnet-4-20250514" }
  ],
  "log": true,
  "timeoutMs": 30000,
  "cooldownMs": 60000,
  "strategy": "sticky"
}

Security

The config panel runs a local HTTP server on 127.0.0.1 only, with a random 192-bit token per session. API keys are resolved server-side ($ENV_VAR / !command) — the browser never sees resolved values.

License

MIT