@erikenz/pi-model-fallback 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 erikenz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,195 @@
1
- # Temporary Holding Version
1
+ # @erikenz/pi-model-fallback
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Automatic, transparent model failover chains for the [Pi coding agent](https://github.com/earendil-works/pi-coding-agent).
4
+
5
+ Start a turn on a free or cheap model. If it hits a rate limit, quota depletion, or provider overload, Pi quietly fails over to the next model in the chain — no crashed turn, no manual `/model` switch.
6
+
7
+ ```text
8
+ fallback/deepseek-flash
9
+ ├─ opencode/deepseek-v4.1-flash (free tier)
10
+ ├─ opencode-go/deepseek-v4.1-flash (subscription)
11
+ └─ opencode-go/claude-haiku-5-5 (backup)
12
+ ```
13
+
14
+ ---
15
+
16
+ ## Features
17
+
18
+ - 🔗 **Virtual fallback models**: every configured chain registers as `fallback/<id>` and appears in `/model`, `--model`, and model settings like any other model.
19
+ - 🚦 **Automatic failover on retry**: a 429, quota error, exhausted credits, insufficient balance, payment requirement, or overload indicator puts the failed model into cooldown and routes the retry to the next candidate.
20
+ - ⏱️ **Cooldowns**: cooled-down models are skipped on new turns until their window expires. Default is 30 minutes; override globally or per chain.
21
+ - 📌 **Sticky continuations**: tool results and multi-step turns stay on the model that answered the turn, preserving prompt caches and thinking signatures.
22
+ - 🧠 **Capability mirroring**: the virtual model inherits `contextWindow`, `maxTokens`, `input`, and supported thinking levels from the chain's primary physical model, so token budgets and compaction work correctly.
23
+ - 💾 **Session-aware state**: cooldowns and the active candidate are stored as Pi router state, following session branches, forks, and compaction.
24
+ - 🩺 **Status command**: `/fallback` (or `/fallbacks`) shows every chain, its active candidate, and remaining cooldowns. `/fallback reset` clears them.
25
+
26
+ ---
27
+
28
+ ## Installation
29
+
30
+ ### Via Pi packages
31
+
32
+ ```bash
33
+ pi install @erikenz/pi-model-fallback
34
+ ```
35
+
36
+ Or add it to `~/.config/pi/agent/settings.json`:
37
+
38
+ ```json
39
+ {
40
+ "packages": ["npm:@erikenz/pi-model-fallback"]
41
+ }
42
+ ```
43
+
44
+ ### Local development
45
+
46
+ ```bash
47
+ ln -s "$(pwd)/packages/pi-model-fallback/extensions/index.ts" \
48
+ ~/.config/pi/agent/extensions/pi-model-fallback.ts
49
+ ```
50
+
51
+ ---
52
+
53
+ ## Configuration
54
+
55
+ Create `~/.config/pi/agent/model-fallback.json`:
56
+
57
+ ```json
58
+ {
59
+ "$schema": "./schema.json",
60
+ "cooldownMs": 1800000,
61
+ "fallbacks": {
62
+ "deepseek-flash": {
63
+ "name": "DeepSeek Flash (Auto Fallback)",
64
+ "chain": [
65
+ "opencode/deepseek-v4.1-flash",
66
+ "opencode-go/deepseek-v4.1-flash"
67
+ ],
68
+ "cooldownMs": 1800000
69
+ },
70
+ "claude-workhorse": {
71
+ "name": "Claude Smart Fallback",
72
+ "chain": ["opencode-go/claude-sonnet-5-5", "opencode-go/claude-haiku-5-5"]
73
+ }
74
+ }
75
+ }
76
+ ```
77
+
78
+ | Field | Meaning |
79
+ | --- | --- |
80
+ | `cooldownMs` | Default cooldown in milliseconds. Defaults to `1800000` (30 minutes). |
81
+ | `fallbacks` | Map of chain id to chain configuration. Each id registers `fallback/<id>`. |
82
+ | `fallbacks.<id>.name` | Display name. Defaults to `<id> (Auto Fallback)`. |
83
+ | `fallbacks.<id>.chain` | Ordered model keys, `provider/model`. The first entry is the preferred model. |
84
+ | `fallbacks.<id>.cooldownMs` | Per-chain cooldown override. |
85
+
86
+ The file is optional. A missing, empty, or invalid file simply means no fallback models are registered. Invalid chain entries are skipped at load time; models that do not exist in the catalog are skipped at route time with a warning.
87
+
88
+ Then select the virtual model:
89
+
90
+ ```bash
91
+ pi --model fallback/deepseek-flash
92
+ ```
93
+
94
+ ---
95
+
96
+ ## Routing rules
97
+
98
+ `fallback/<id>` registers a Pi virtual model. Pi calls its router before every request with a `reason`:
99
+
100
+ | `reason` | Behavior |
101
+ | --- | --- |
102
+ | `user` | Pick the highest-priority chain model that is not cooling down. If every model is cooling down, pick the one whose cooldown ends soonest. |
103
+ | `continuation` | Stay on `request.previous.model` and its thinking level, even if it is cooling down. This keeps tool-call follow-ups on the same model and preserves the prompt cache. |
104
+ | `retry` | If `request.failed` reports a quota/rate-limit/overload error, cool the failed model down and route to the next healthy candidate after it. Otherwise retry the failed model. |
105
+ | `direct` | Same selection as `user`. Used for compaction summaries and extension-initiated calls. |
106
+
107
+ The returned state is `{ activeCandidateIndex, cooldowns }`:
108
+
109
+ ```json
110
+ {
111
+ "activeCandidateIndex": 1,
112
+ "cooldowns": {
113
+ "opencode/deepseek-v4.1-flash": 1767225600000
114
+ }
115
+ }
116
+ ```
117
+
118
+ Pi stores it on the session branch, restores it across forks and compaction, and passes it back as `request.state`. The extension also keeps a process-wide copy so `direct` requests and status reporting see current cooldowns.
119
+
120
+ ### Recognized failure indicators
121
+
122
+ The error matcher checks `request.failed.message.errorMessage` and `stopReason` for:
123
+
124
+ - HTTP `429`, `402`, `529`, `rate limit`, `too many requests`
125
+ - `quota`, `insufficient_quota`, `resource_exhausted`
126
+ - `credits exhausted`, `out of credits`, `insufficient balance`, `credit balance is too low`
127
+ - `usage limit`, `weekly limit`, `monthly limit`, `daily limit`, `hourly limit`
128
+ - `overloaded`, `server at capacity`
129
+ - `billing`, `payment required`
130
+
131
+ Non-quota failures (invalid API key, context overflow, tool errors) do not trigger failover.
132
+
133
+ ---
134
+
135
+ ## Commands
136
+
137
+ ### `/fallback` or `/fallbacks`
138
+
139
+ Print the status of every configured chain:
140
+
141
+ ```text
142
+ Model fallback chains (2):
143
+ • deepseek-flash — DeepSeek Flash (Auto Fallback) [fallback/deepseek-flash]
144
+ *1. opencode/deepseek-v4.1-flash — cooling down (29m 12s left)
145
+ 2. opencode-go/deepseek-v4.1-flash — ready
146
+ • claude-workhorse — Claude Smart Fallback [fallback/claude-workhorse]
147
+ 1. opencode-go/claude-sonnet-5-5 — ready
148
+ 2. opencode-go/claude-haiku-5-5 — ready
149
+ ```
150
+
151
+ `*` marks the active candidate.
152
+
153
+ ### `/fallback reset [chain-id]`
154
+
155
+ Clear cooldowns for one chain (`deepseek-flash` or `fallback/deepseek-flash`) or for every chain when no id is given.
156
+
157
+ ---
158
+
159
+ ## How it works
160
+
161
+ ```text
162
+ Pi turn
163
+ → virtual model fallback/deepseek-flash
164
+ → route(request)
165
+ reason=user → first healthy candidate
166
+ reason=continuation → request.previous.model
167
+ reason=retry → quota? cool down + next candidate
168
+ → physical model (streamed by its provider)
169
+ ```
170
+
171
+ The package is intentionally small:
172
+
173
+ | File | Responsibility |
174
+ | --- | --- |
175
+ | `extensions/index.ts` | Registers virtual models and slash commands; re-mirrors capabilities on `session_start`. |
176
+ | `src/config.ts` | Loads and validates `model-fallback.json`. |
177
+ | `src/errors.ts` | Classifies quota, rate-limit, and overload errors. |
178
+ | `src/cooldown.ts` | Cooldown windows, expiry pruning, and the in-memory router store. |
179
+ | `src/router.ts` | The `route(request, ctx)` implementation and capability mirroring. |
180
+ | `src/commands.ts` | `/fallback` status and reset command. |
181
+
182
+ ---
183
+
184
+ ## Development
185
+
186
+ ```bash
187
+ pnpm install
188
+ pnpm -r test # Node's native test runner
189
+ pnpm typecheck # tsc --noEmit
190
+ pnpm check # ultracite check
191
+ ```
192
+
193
+ ## License
194
+
195
+ MIT
@@ -0,0 +1,258 @@
1
+ import type { Api, Model } from "@earendil-works/pi-ai";
2
+ import type {
3
+ AgentBeforeSettleEvent,
4
+ AgentBeforeSettleEventResult,
5
+ ExtensionAPI,
6
+ ExtensionContext,
7
+ ExtensionVirtualModel,
8
+ } from "@earendil-works/pi-coding-agent";
9
+
10
+ import { handleFallbackCommand } from "../src/commands.ts";
11
+ import { FALLBACK_PROVIDER, loadConfig, parseModelKey } from "../src/config.ts";
12
+ import { isCoolingDown, markCooldown, routerStore } from "../src/cooldown.ts";
13
+ import { isQuotaOrRateLimitError } from "../src/errors.ts";
14
+ import { capabilitiesFromModel, createRouter } from "../src/router.ts";
15
+ import type { FallbackEntry, RouterState } from "../src/types.ts";
16
+
17
+ const warn = (message: string): void => {
18
+ process.stderr.write(`[pi-model-fallback] ${message}\n`);
19
+ };
20
+
21
+ const buildDefinition = (
22
+ entry: FallbackEntry,
23
+ primary: Model<Api> | undefined
24
+ ): ExtensionVirtualModel<RouterState> => ({
25
+ ...capabilitiesFromModel(primary),
26
+ id: entry.id,
27
+ name: entry.name,
28
+ provider: FALLBACK_PROVIDER,
29
+ route: createRouter({
30
+ chain: entry.chain,
31
+ chainId: `${FALLBACK_PROVIDER}/${entry.id}`,
32
+ cooldownMs: entry.cooldownMs,
33
+ warn,
34
+ }),
35
+ });
36
+
37
+ /** Find the first model in the chain that the registry knows about. */
38
+ const primaryModelFor = (
39
+ entry: FallbackEntry,
40
+ ctx: ExtensionContext
41
+ ): Model<Api> | undefined => {
42
+ for (const key of entry.chain) {
43
+ const parsed = parseModelKey(key);
44
+ if (parsed === undefined) {
45
+ continue;
46
+ }
47
+ // oxlint-disable-next-line no-array-method-this-argument
48
+ // eslint-disable-next-line no-array-method-this-argument
49
+ const model = ctx.modelRegistry.find(parsed.provider, parsed.id);
50
+ if (model !== undefined) {
51
+ return model;
52
+ }
53
+ }
54
+ return undefined;
55
+ };
56
+
57
+ let registeredIds = new Set<string>();
58
+
59
+ const syncRegistrations = (
60
+ pi: ExtensionAPI,
61
+ modelFor: (entry: FallbackEntry) => Model<Api> | undefined
62
+ ): void => {
63
+ const config = loadConfig();
64
+ const configuredIds = new Set(config.fallbacks.map((entry) => entry.id));
65
+
66
+ for (const id of registeredIds) {
67
+ if (configuredIds.has(id)) {
68
+ continue;
69
+ }
70
+ try {
71
+ pi.unregisterVirtualModel(FALLBACK_PROVIDER, id);
72
+ } catch {
73
+ // Ignore: the model may already be gone.
74
+ }
75
+ }
76
+
77
+ const nextIds = new Set<string>();
78
+ for (const entry of config.fallbacks) {
79
+ try {
80
+ pi.registerVirtualModel(buildDefinition(entry, modelFor(entry)));
81
+ nextIds.add(entry.id);
82
+ } catch (error) {
83
+ warn(
84
+ `Failed to register ${FALLBACK_PROVIDER}/${entry.id}: ${String(error)}`
85
+ );
86
+ }
87
+ }
88
+ registeredIds = nextIds;
89
+ };
90
+
91
+ const registerCommand = (
92
+ pi: ExtensionAPI,
93
+ name: string,
94
+ description: string
95
+ ): void => {
96
+ try {
97
+ pi.registerCommand(name, {
98
+ description,
99
+ handler: async (args, ctx) => {
100
+ await handleFallbackCommand(args ?? "", ctx);
101
+ },
102
+ });
103
+ } catch {
104
+ // Ignore conflicts with a command another extension already registered.
105
+ }
106
+ };
107
+
108
+ let lastFailedAssistantEntryId: string | undefined;
109
+
110
+ const noPrimaryModel = (): Model<Api> | undefined => undefined;
111
+
112
+ interface AntigravityRuntime {
113
+ closeSession: (id: string) => Promise<void>;
114
+ }
115
+
116
+ const isAntigravityRuntime = (value: unknown): value is AntigravityRuntime =>
117
+ value !== null &&
118
+ typeof value === "object" &&
119
+ "closeSession" in value &&
120
+ typeof value.closeSession === "function";
121
+
122
+ const isAntigravityHolder = (
123
+ value: unknown
124
+ ): value is { runtime: AntigravityRuntime } =>
125
+ value !== null &&
126
+ typeof value === "object" &&
127
+ "runtime" in value &&
128
+ isAntigravityRuntime(value.runtime);
129
+
130
+ const cleanupAntigravitySession = async (
131
+ ctx: ExtensionContext
132
+ ): Promise<void> => {
133
+ try {
134
+ const key = Symbol.for("pi-antigravity-acp:runtime");
135
+ const container: Record<symbol, unknown> = globalThis;
136
+ const holder = container[key];
137
+ if (isAntigravityHolder(holder)) {
138
+ const sessionId = ctx.sessionManager.getSessionId();
139
+ if (sessionId.length > 0) {
140
+ await holder.runtime.closeSession(sessionId);
141
+ }
142
+ }
143
+ } catch {
144
+ // Best-effort cleanup for stateful Antigravity ACP provider sessions.
145
+ }
146
+ };
147
+
148
+ const handleAgentBeforeSettle = async (
149
+ event: AgentBeforeSettleEvent,
150
+ ctx: ExtensionContext
151
+ ): Promise<AgentBeforeSettleEventResult | undefined> => {
152
+ const { model } = ctx;
153
+ if (model === undefined || model.provider !== FALLBACK_PROVIDER) {
154
+ return undefined;
155
+ }
156
+
157
+ if (lastFailedAssistantEntryId === undefined || event.outcome !== "error") {
158
+ lastFailedAssistantEntryId = undefined;
159
+ return undefined;
160
+ }
161
+
162
+ const failedId = lastFailedAssistantEntryId;
163
+ lastFailedAssistantEntryId = undefined;
164
+
165
+ const config = loadConfig();
166
+ const entry = config.fallbacks.find((item) => item.id === model.id);
167
+ if (entry === undefined) {
168
+ return undefined;
169
+ }
170
+
171
+ const chainId = `${FALLBACK_PROVIDER}/${entry.id}`;
172
+ const currentState = routerStore.get(chainId) ?? {
173
+ activeCandidateIndex: 0,
174
+ cooldowns: {},
175
+ };
176
+ const currentKey = entry.chain[currentState.activeCandidateIndex];
177
+ const now = Date.now();
178
+
179
+ if (currentKey !== undefined) {
180
+ currentState.cooldowns = markCooldown(
181
+ currentState.cooldowns,
182
+ currentKey,
183
+ now,
184
+ entry.cooldownMs
185
+ );
186
+ routerStore.set(chainId, currentState);
187
+ }
188
+
189
+ const hasOtherHealthy = entry.chain.some(
190
+ (key) =>
191
+ key !== currentKey && !isCoolingDown(currentState.cooldowns, key, now)
192
+ );
193
+ if (!hasOtherHealthy) {
194
+ return undefined;
195
+ }
196
+
197
+ if (
198
+ currentKey?.startsWith("antigravity-acp/") ||
199
+ entry.chain.some((key) => key.startsWith("antigravity-acp/"))
200
+ ) {
201
+ await cleanupAntigravitySession(ctx);
202
+ }
203
+
204
+ ctx.ui?.notify(
205
+ `Quota limit reached on ${currentKey ?? "model"}. Falling back to next model in chain...`,
206
+ "warning"
207
+ );
208
+
209
+ return {
210
+ continue: true,
211
+ entries: [
212
+ ...event.entries,
213
+ {
214
+ replacement: null,
215
+ targetId: failedId,
216
+ type: "context_edit",
217
+ },
218
+ ],
219
+ };
220
+ };
221
+
222
+ const fallbackExtension = (pi: ExtensionAPI): void => {
223
+ syncRegistrations(pi, noPrimaryModel);
224
+
225
+ pi.on("session_start", (_event, ctx) => {
226
+ lastFailedAssistantEntryId = undefined;
227
+ syncRegistrations(pi, (entry) => primaryModelFor(entry, ctx));
228
+ });
229
+
230
+ pi.on("agent_start", () => {
231
+ lastFailedAssistantEntryId = undefined;
232
+ });
233
+
234
+ pi.on("turn_end", (event) => {
235
+ if (
236
+ event.outcome === "error" &&
237
+ event.message.role === "assistant" &&
238
+ isQuotaOrRateLimitError(event.message)
239
+ ) {
240
+ lastFailedAssistantEntryId = event.messageEntryId;
241
+ }
242
+ });
243
+
244
+ pi.on("agent_before_settle", handleAgentBeforeSettle);
245
+
246
+ registerCommand(
247
+ pi,
248
+ "fallback",
249
+ "Show model fallback chains, active models, and cooldown status"
250
+ );
251
+ registerCommand(
252
+ pi,
253
+ "fallbacks",
254
+ "Alias for /fallback: show model fallback chain status"
255
+ );
256
+ };
257
+
258
+ export default fallbackExtension;
package/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "@erikenz/pi-model-fallback",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.1",
4
+ "description": "Automatic model failover chains with cooldowns for the Pi coding agent.",
5
+ "keywords": [
6
+ "ai",
7
+ "failover",
8
+ "fallback",
9
+ "model-fallback",
10
+ "pi-extension",
11
+ "pi-package",
12
+ "rate-limit"
13
+ ],
14
+ "license": "MIT",
15
+ "author": "erikenz",
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/erikenz/pi-extensions.git",
19
+ "directory": "packages/pi-model-fallback"
20
+ },
21
+ "files": [
22
+ "extensions",
23
+ "src",
24
+ "README.md",
25
+ "LICENSE"
26
+ ],
27
+ "type": "module",
28
+ "devDependencies": {
29
+ "@earendil-works/pi-ai": "*",
30
+ "@earendil-works/pi-coding-agent": "*"
31
+ },
32
+ "peerDependencies": {
33
+ "@earendil-works/pi-ai": "*",
34
+ "@earendil-works/pi-coding-agent": "*"
35
+ },
36
+ "engines": {
37
+ "node": ">=18"
38
+ },
39
+ "pi": {
40
+ "extensions": [
41
+ "./extensions/index.ts"
42
+ ]
43
+ },
44
+ "scripts": {
45
+ "test": "node --test",
46
+ "typecheck": "tsc --noEmit"
47
+ }
6
48
  }
@@ -0,0 +1,89 @@
1
+ import { FALLBACK_PROVIDER, loadConfig } from "./config.ts";
2
+ import {
3
+ formatDuration,
4
+ pruneExpiredCooldowns,
5
+ routerStore,
6
+ } from "./cooldown.ts";
7
+ import type { RouterStore } from "./cooldown.ts";
8
+ import type { FallbackConfig } from "./types.ts";
9
+
10
+ const chainId = (id: string): string => `${FALLBACK_PROVIDER}/${id}`;
11
+
12
+ /** Render the status of every configured fallback chain. */
13
+ export const describeStatus = (
14
+ config: FallbackConfig,
15
+ store: RouterStore = routerStore,
16
+ now: number = Date.now()
17
+ ): string => {
18
+ if (config.fallbacks.length === 0) {
19
+ return "No fallback chains configured. Add `fallbacks` entries to ~/.config/pi/agent/model-fallback.json.";
20
+ }
21
+
22
+ const lines = [`Model fallback chains (${config.fallbacks.length}):`];
23
+ for (const entry of config.fallbacks) {
24
+ const id = chainId(entry.id);
25
+ const state = store.get(id);
26
+ const cooldowns = pruneExpiredCooldowns(state?.cooldowns, now);
27
+ lines.push(`• ${entry.id} — ${entry.name} [${id}]`);
28
+ for (const [index, key] of entry.chain.entries()) {
29
+ const active = index === state?.activeCandidateIndex ? "*" : " ";
30
+ const expiresAt = cooldowns[key];
31
+ const status =
32
+ expiresAt !== undefined && expiresAt > now
33
+ ? `cooling down (${formatDuration(expiresAt - now)} left)`
34
+ : "ready";
35
+ lines.push(` ${active}${index + 1}. ${key} — ${status}`);
36
+ }
37
+ }
38
+ return lines.join("\n");
39
+ };
40
+
41
+ export interface FallbackCommandContext {
42
+ ui: {
43
+ notify: (message: string, type?: "info" | "warning" | "error") => void;
44
+ };
45
+ }
46
+
47
+ // Pi's command contract is async, but every step here is synchronous UI work.
48
+ // oxlint-disable-next-line require-await
49
+ // eslint-disable-next-line require-await
50
+ export const handleFallbackCommand = async (
51
+ raw: string,
52
+ ctx: FallbackCommandContext,
53
+ store: RouterStore = routerStore,
54
+ config: FallbackConfig = loadConfig()
55
+ ): Promise<void> => {
56
+ const [subcommand = "", ...rest] = raw.trim().split(/\s+/u);
57
+
58
+ if (subcommand === "reset" || subcommand === "clear") {
59
+ const [target] = rest;
60
+ if (target === undefined || target.length === 0) {
61
+ store.clear();
62
+ for (const entry of config.fallbacks) {
63
+ store.set(chainId(entry.id), {
64
+ activeCandidateIndex: 0,
65
+ cooldowns: {},
66
+ });
67
+ }
68
+ ctx.ui.notify("Cleared all fallback cooldowns.", "info");
69
+ return;
70
+ }
71
+ const entry = config.fallbacks.find(
72
+ (candidate) => candidate.id === target || chainId(candidate.id) === target
73
+ );
74
+ if (entry === undefined) {
75
+ ctx.ui.notify(`Unknown fallback chain "${target}".`, "warning");
76
+ return;
77
+ }
78
+ store.set(chainId(entry.id), { activeCandidateIndex: 0, cooldowns: {} });
79
+ ctx.ui.notify(`Cleared cooldowns for ${chainId(entry.id)}.`, "info");
80
+ return;
81
+ }
82
+
83
+ if (subcommand === "" || subcommand === "status") {
84
+ ctx.ui.notify(describeStatus(config, store), "info");
85
+ return;
86
+ }
87
+
88
+ ctx.ui.notify("Usage: /fallback [status | reset [chain-id]]", "warning");
89
+ };
package/src/config.ts ADDED
@@ -0,0 +1,116 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import path from "node:path";
3
+
4
+ import { getAgentDir } from "@earendil-works/pi-coding-agent";
5
+
6
+ import type { FallbackConfig, FallbackEntry } from "./types.ts";
7
+
8
+ export const FALLBACK_PROVIDER = "fallback";
9
+
10
+ export const DEFAULT_COOLDOWN_MS = 30 * 60 * 1000;
11
+
12
+ const DEFAULT_NAME_SUFFIX = "(Auto Fallback)";
13
+
14
+ const isRecord = (value: unknown): value is Record<string, unknown> =>
15
+ typeof value === "object" && value !== null && !Array.isArray(value);
16
+
17
+ const toPositiveNumber = (value: unknown): number | undefined => {
18
+ if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
19
+ return undefined;
20
+ }
21
+ return value;
22
+ };
23
+
24
+ export const configPath = (): string =>
25
+ path.join(getAgentDir(), "model-fallback.json");
26
+
27
+ /** Split a `provider/model` key at the first slash. */
28
+ export const parseModelKey = (
29
+ key: string
30
+ ): { provider: string; id: string } | undefined => {
31
+ const trimmed = key.trim();
32
+ const slash = trimmed.indexOf("/");
33
+ if (slash <= 0 || slash === trimmed.length - 1) {
34
+ return undefined;
35
+ }
36
+ const provider = trimmed.slice(0, slash).trim();
37
+ const id = trimmed.slice(slash + 1).trim();
38
+ if (provider.length === 0 || id.length === 0) {
39
+ return undefined;
40
+ }
41
+ return { id, provider };
42
+ };
43
+
44
+ export const modelKey = (model: { provider: string; id: string }): string =>
45
+ `${model.provider}/${model.id}`;
46
+
47
+ const parseChain = (value: unknown): string[] => {
48
+ if (!Array.isArray(value)) {
49
+ return [];
50
+ }
51
+ const chain: string[] = [];
52
+ for (const item of value) {
53
+ if (typeof item !== "string") {
54
+ continue;
55
+ }
56
+ const key = item.trim();
57
+ if (
58
+ key.length === 0 ||
59
+ chain.includes(key) ||
60
+ parseModelKey(key) === undefined
61
+ ) {
62
+ continue;
63
+ }
64
+ chain.push(key);
65
+ }
66
+ return chain;
67
+ };
68
+
69
+ /** Parse and validate a raw configuration value. Never throws. */
70
+ export const parseConfig = (raw: unknown): FallbackConfig => {
71
+ const globalCooldown = isRecord(raw)
72
+ ? (toPositiveNumber(raw.cooldownMs) ?? DEFAULT_COOLDOWN_MS)
73
+ : DEFAULT_COOLDOWN_MS;
74
+ const fallbacks: FallbackEntry[] = [];
75
+
76
+ if (!isRecord(raw) || !isRecord(raw.fallbacks)) {
77
+ return { cooldownMs: globalCooldown, fallbacks };
78
+ }
79
+
80
+ for (const [rawId, value] of Object.entries(raw.fallbacks)) {
81
+ const id = rawId.trim();
82
+ if (id.length === 0 || !isRecord(value)) {
83
+ continue;
84
+ }
85
+ const chain = parseChain(value.chain);
86
+ if (chain.length === 0) {
87
+ continue;
88
+ }
89
+ const rawName = typeof value.name === "string" ? value.name.trim() : "";
90
+ const name = rawName.length > 0 ? rawName : `${id} ${DEFAULT_NAME_SUFFIX}`;
91
+ fallbacks.push({
92
+ chain,
93
+ cooldownMs: toPositiveNumber(value.cooldownMs) ?? globalCooldown,
94
+ id,
95
+ name,
96
+ });
97
+ }
98
+
99
+ return { cooldownMs: globalCooldown, fallbacks };
100
+ };
101
+
102
+ /** Load the config, returning defaults for a missing, empty, or invalid file. */
103
+ export const loadConfig = (filePath: string = configPath()): FallbackConfig => {
104
+ if (!existsSync(filePath)) {
105
+ return parseConfig(undefined);
106
+ }
107
+ try {
108
+ const raw = readFileSync(filePath, "utf-8");
109
+ if (raw.trim().length === 0) {
110
+ return parseConfig(undefined);
111
+ }
112
+ return parseConfig(JSON.parse(raw));
113
+ } catch {
114
+ return parseConfig(undefined);
115
+ }
116
+ };
@@ -0,0 +1,85 @@
1
+ import type { RouterState } from "./types.ts";
2
+
3
+ export type Cooldowns = Record<string, number>;
4
+
5
+ /** Remove cooldowns whose expiry is at or before `now`. */
6
+ export const pruneExpiredCooldowns = (
7
+ cooldowns: Cooldowns | undefined,
8
+ now: number
9
+ ): Cooldowns => {
10
+ const result: Cooldowns = {};
11
+ for (const [key, expiresAt] of Object.entries(cooldowns ?? {})) {
12
+ if (Number.isFinite(expiresAt) && expiresAt > now) {
13
+ result[key] = expiresAt;
14
+ }
15
+ }
16
+ return result;
17
+ };
18
+
19
+ export const isCoolingDown = (
20
+ cooldowns: Cooldowns | undefined,
21
+ key: string,
22
+ now: number
23
+ ): boolean => {
24
+ const expiresAt = cooldowns?.[key];
25
+ return typeof expiresAt === "number" && expiresAt > now;
26
+ };
27
+
28
+ /** Return a new cooldowns record with `key` cooling down for `durationMs`. */
29
+ export const markCooldown = (
30
+ cooldowns: Cooldowns | undefined,
31
+ key: string,
32
+ now: number,
33
+ durationMs: number
34
+ ): Cooldowns => ({
35
+ ...pruneExpiredCooldowns(cooldowns, now),
36
+ [key]: now + Math.max(0, durationMs),
37
+ });
38
+
39
+ export const formatDuration = (ms: number): string => {
40
+ const totalSeconds = Math.max(0, Math.ceil(ms / 1000));
41
+ const minutes = Math.floor(totalSeconds / 60);
42
+ const seconds = totalSeconds % 60;
43
+ return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
44
+ };
45
+
46
+ const cloneState = (state: RouterState): RouterState => ({
47
+ activeCandidateIndex: state.activeCandidateIndex,
48
+ cooldowns: { ...state.cooldowns },
49
+ });
50
+
51
+ /** Persistence surface for router state. Tests inject an isolated instance. */
52
+ export interface RouterStore {
53
+ clear: (chainId?: string) => void;
54
+ entries: () => [string, RouterState][];
55
+ get: (chainId: string) => RouterState | undefined;
56
+ set: (chainId: string, state: RouterState) => void;
57
+ }
58
+
59
+ export const createMemoryRouterStore = (): RouterStore => {
60
+ const states = new Map<string, RouterState>();
61
+ return {
62
+ clear: (chainId) => {
63
+ if (chainId === undefined) {
64
+ states.clear();
65
+ return;
66
+ }
67
+ states.delete(chainId);
68
+ },
69
+ entries: () =>
70
+ [...states.entries()].map(([chainId, state]) => [
71
+ chainId,
72
+ cloneState(state),
73
+ ]),
74
+ get: (chainId) => {
75
+ const state = states.get(chainId);
76
+ return state === undefined ? undefined : cloneState(state);
77
+ },
78
+ set: (chainId, state) => {
79
+ states.set(chainId, cloneState(state));
80
+ },
81
+ };
82
+ };
83
+
84
+ /** Process-wide store used by the extension and the status command. */
85
+ export const routerStore: RouterStore = createMemoryRouterStore();
package/src/errors.ts ADDED
@@ -0,0 +1,47 @@
1
+ import type { FailureMessage } from "./types.ts";
2
+
3
+ /**
4
+ * Indicators of quota depletion, rate limiting, or provider overload. They are checked
5
+ * against both `errorMessage` and `stopReason`.
6
+ */
7
+ const QUOTA_PATTERNS: readonly RegExp[] = [
8
+ /\b429\b/u,
9
+ /\b402\b/u,
10
+ /\b529\b/u,
11
+ /rate[\s_-]*limit/iu,
12
+ /\btoo many requests\b/iu,
13
+ /\bquota\b/iu,
14
+ /\binsufficient[\s_-]*(?:quota|balance|credits?|funds?)\b/iu,
15
+ /\b(?:credits?|balance|funds?)\s+(?:exhausted|depleted|exceeded|insufficient|empty|too low)\b/iu,
16
+ /\bcredit balance\b/iu,
17
+ /\bout of (?:credits?|quota|balance|funds?)\b/iu,
18
+ /\b(?:usage|weekly|monthly|daily|hourly)\s+limit\b/iu,
19
+ /\b(?:resource|quota)[\s_-]*exhausted\b/iu,
20
+ /\boverloaded\b/iu,
21
+ /\b(?:service|server)\s+(?:is\s+)?(?:at|over)\s+capacity\b/iu,
22
+ /\bbilling\b/iu,
23
+ /\bpayment required\b/iu,
24
+ ];
25
+
26
+ export const isQuotaOrRateLimitError = (
27
+ failure: FailureMessage | string | undefined | null
28
+ ): boolean => {
29
+ if (failure === undefined || failure === null) {
30
+ return false;
31
+ }
32
+ const text =
33
+ typeof failure === "string"
34
+ ? failure
35
+ : [failure.errorMessage, failure.stopReason]
36
+ .filter((part): part is string => typeof part === "string")
37
+ .join(" ");
38
+ if (text.trim().length === 0) {
39
+ return false;
40
+ }
41
+ return QUOTA_PATTERNS.some((pattern) => pattern.test(text));
42
+ };
43
+
44
+ /** Whether a `request.failed` object reports a quota/rate-limit failure. */
45
+ export const isQuotaFailure = (
46
+ failed: { message: FailureMessage } | undefined
47
+ ): boolean => isQuotaOrRateLimitError(failed?.message);
package/src/router.ts ADDED
@@ -0,0 +1,281 @@
1
+ import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
2
+ import type {
3
+ Api,
4
+ Model,
5
+ ModelInputModality,
6
+ ModelThinkingLevel,
7
+ } from "@earendil-works/pi-ai";
8
+
9
+ import { modelKey, parseModelKey } from "./config.ts";
10
+ import {
11
+ isCoolingDown,
12
+ markCooldown,
13
+ pruneExpiredCooldowns,
14
+ routerStore,
15
+ } from "./cooldown.ts";
16
+ import type { RouterStore } from "./cooldown.ts";
17
+ import { isQuotaFailure } from "./errors.ts";
18
+ import type {
19
+ RouterContext,
20
+ RouterRequest,
21
+ RouterRoute,
22
+ RouterState,
23
+ } from "./types.ts";
24
+
25
+ export const DEFAULT_THINKING_LEVELS: readonly ModelThinkingLevel[] = [
26
+ "off",
27
+ "minimal",
28
+ "low",
29
+ "medium",
30
+ "high",
31
+ "xhigh",
32
+ "max",
33
+ ];
34
+
35
+ export interface VirtualModelCapabilities {
36
+ contextWindow?: number;
37
+ input?: ModelInputModality[];
38
+ maxTokens?: number;
39
+ thinkingLevels: readonly ModelThinkingLevel[];
40
+ }
41
+
42
+ /** Mirror the primary physical model's limits and thinking levels. */
43
+ export const capabilitiesFromModel = (
44
+ model: Model<Api> | undefined
45
+ ): VirtualModelCapabilities => {
46
+ if (model === undefined) {
47
+ return { thinkingLevels: DEFAULT_THINKING_LEVELS };
48
+ }
49
+ const supported = getSupportedThinkingLevels(model);
50
+ return {
51
+ contextWindow: model.contextWindow,
52
+ input: [...model.input],
53
+ maxTokens: model.maxTokens,
54
+ thinkingLevels: supported.length > 0 ? supported : DEFAULT_THINKING_LEVELS,
55
+ };
56
+ };
57
+
58
+ export interface RouterOptions {
59
+ chain: readonly string[];
60
+ chainId: string;
61
+ cooldownMs: number;
62
+ now?: () => number;
63
+ store?: RouterStore;
64
+ warn?: (message: string) => void;
65
+ }
66
+
67
+ interface Candidate {
68
+ index: number;
69
+ key: string;
70
+ model: Model<Api>;
71
+ }
72
+
73
+ const resolveCandidates = (
74
+ options: RouterOptions,
75
+ ctx: RouterContext,
76
+ warned: Set<string>
77
+ ): Candidate[] => {
78
+ const candidates: Candidate[] = [];
79
+ for (const [index, key] of options.chain.entries()) {
80
+ const parsed = parseModelKey(key);
81
+ if (parsed === undefined) {
82
+ if (!warned.has(key)) {
83
+ warned.add(key);
84
+ options.warn?.(
85
+ `Skipping invalid model key "${key}" in chain "${options.chainId}".`
86
+ );
87
+ }
88
+ continue;
89
+ }
90
+ // oxlint-disable-next-line no-array-method-this-argument
91
+ // eslint-disable-next-line no-array-method-this-argument
92
+ const model = ctx.modelRegistry.find(parsed.provider, parsed.id);
93
+ if (model === undefined) {
94
+ if (!warned.has(key)) {
95
+ warned.add(key);
96
+ options.warn?.(
97
+ `Skipping missing model "${key}" in chain "${options.chainId}".`
98
+ );
99
+ }
100
+ continue;
101
+ }
102
+ candidates.push({ index, key, model });
103
+ }
104
+ return candidates;
105
+ };
106
+
107
+ const firstHealthy = (
108
+ candidates: readonly Candidate[],
109
+ cooldowns: Record<string, number>,
110
+ now: number
111
+ ): Candidate | undefined =>
112
+ candidates.find((candidate) => !isCoolingDown(cooldowns, candidate.key, now));
113
+
114
+ const earliestExpiry = (
115
+ candidates: readonly Candidate[],
116
+ cooldowns: Record<string, number>
117
+ ): Candidate | undefined => {
118
+ let result: Candidate | undefined;
119
+ for (const candidate of candidates) {
120
+ if (result === undefined) {
121
+ result = candidate;
122
+ continue;
123
+ }
124
+ const expiry = cooldowns[candidate.key] ?? 0;
125
+ const resultExpiry = cooldowns[result.key] ?? 0;
126
+ if (expiry < resultExpiry) {
127
+ result = candidate;
128
+ }
129
+ }
130
+ return result;
131
+ };
132
+
133
+ /** The next candidate after the failed one, preferring a healthy one. */
134
+ const nextAfterFailure = (
135
+ candidates: readonly Candidate[],
136
+ failedKey: string,
137
+ cooldowns: Record<string, number>,
138
+ now: number
139
+ ): Candidate | undefined => {
140
+ const failedIndex = candidates.findIndex(
141
+ (candidate) => candidate.key === failedKey
142
+ );
143
+ const start = failedIndex === -1 ? -1 : failedIndex;
144
+ for (let offset = 1; offset <= candidates.length; offset += 1) {
145
+ const candidate =
146
+ candidates[(start + offset + candidates.length) % candidates.length];
147
+ if (
148
+ candidate !== undefined &&
149
+ candidate.key !== failedKey &&
150
+ !isCoolingDown(cooldowns, candidate.key, now)
151
+ ) {
152
+ return candidate;
153
+ }
154
+ }
155
+ const others = candidates.filter((candidate) => candidate.key !== failedKey);
156
+ return earliestExpiry(others, cooldowns) ?? candidates[0];
157
+ };
158
+
159
+ const buildState = (
160
+ request: RouterRequest,
161
+ options: RouterOptions,
162
+ store: RouterStore,
163
+ now: number
164
+ ): RouterState => {
165
+ const memory = store.get(options.chainId);
166
+ return {
167
+ activeCandidateIndex:
168
+ request.state?.activeCandidateIndex ?? memory?.activeCandidateIndex ?? 0,
169
+ // The in-memory store is the live overlay: it is updated on every route and
170
+ // makes `/fallback reset` effective. Session state is the persisted baseline
171
+ // after a restart or when a branch predates the current process.
172
+ cooldowns: pruneExpiredCooldowns(
173
+ memory === undefined ? request.state?.cooldowns : memory.cooldowns,
174
+ now
175
+ ),
176
+ };
177
+ };
178
+
179
+ const finish = (
180
+ chosen: Candidate,
181
+ thinkingLevel: ModelThinkingLevel,
182
+ state: RouterState,
183
+ store: RouterStore,
184
+ options: RouterOptions,
185
+ now: number
186
+ ): RouterRoute => {
187
+ const nextState: RouterState = {
188
+ activeCandidateIndex: chosen.index,
189
+ cooldowns: pruneExpiredCooldowns(state.cooldowns, now),
190
+ };
191
+ store.set(options.chainId, nextState);
192
+ return { model: chosen.model, state: nextState, thinkingLevel };
193
+ };
194
+
195
+ /**
196
+ * Build a router for one fallback chain. The returned function is Pi's `route`
197
+ * implementation: it picks a physical model and thinking level per request.
198
+ */
199
+ export const createRouter = (
200
+ options: RouterOptions
201
+ ): ((request: RouterRequest, ctx: RouterContext) => RouterRoute) => {
202
+ const store = options.store ?? routerStore;
203
+ const warned = new Set<string>();
204
+
205
+ return (request, ctx) => {
206
+ const now = options.now?.() ?? Date.now();
207
+ const candidates = resolveCandidates(options, ctx, warned);
208
+ if (candidates.length === 0) {
209
+ throw new Error(
210
+ `No available models in fallback chain "${options.chainId}". Check model-fallback.json and provider credentials.`
211
+ );
212
+ }
213
+
214
+ const state = buildState(request, options, store, now);
215
+
216
+ if (request.reason === "continuation" && request.previous !== undefined) {
217
+ const previousKey = modelKey(request.previous.model);
218
+ const sticky = candidates.find(
219
+ (candidate) => candidate.key === previousKey
220
+ );
221
+ const chosen = sticky ?? {
222
+ index: state.activeCandidateIndex,
223
+ key: previousKey,
224
+ model: request.previous.model,
225
+ };
226
+ return finish(
227
+ chosen,
228
+ request.previous.thinkingLevel ?? request.thinkingLevel,
229
+ state,
230
+ store,
231
+ options,
232
+ now
233
+ );
234
+ }
235
+
236
+ if (request.reason === "retry" && request.failed !== undefined) {
237
+ const failedKey = modelKey(request.failed.model);
238
+ const thinkingLevel =
239
+ request.failed.thinkingLevel ?? request.thinkingLevel;
240
+
241
+ if (isQuotaFailure(request.failed)) {
242
+ state.cooldowns = markCooldown(
243
+ state.cooldowns,
244
+ failedKey,
245
+ now,
246
+ options.cooldownMs
247
+ );
248
+ const chosen = nextAfterFailure(
249
+ candidates,
250
+ failedKey,
251
+ state.cooldowns,
252
+ now
253
+ );
254
+ return finish(
255
+ chosen ?? candidates[0],
256
+ thinkingLevel,
257
+ state,
258
+ store,
259
+ options,
260
+ now
261
+ );
262
+ }
263
+
264
+ const failedCandidate = candidates.find(
265
+ (candidate) => candidate.key === failedKey
266
+ );
267
+ const chosen = failedCandidate ?? {
268
+ index: state.activeCandidateIndex,
269
+ key: failedKey,
270
+ model: request.failed.model,
271
+ };
272
+ return finish(chosen, thinkingLevel, state, store, options, now);
273
+ }
274
+
275
+ const chosen =
276
+ firstHealthy(candidates, state.cooldowns, now) ??
277
+ earliestExpiry(candidates, state.cooldowns) ??
278
+ candidates[0];
279
+ return finish(chosen, request.thinkingLevel, state, store, options, now);
280
+ };
281
+ };
package/src/types.ts ADDED
@@ -0,0 +1,64 @@
1
+ import type { Api, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
2
+ import type {
3
+ ModelRoute,
4
+ ModelRouteReason,
5
+ ModelRouteRequest,
6
+ } from "@earendil-works/pi-coding-agent";
7
+
8
+ /** A configured fallback chain: fallback/<id> routes through `chain`. */
9
+ export interface FallbackEntry {
10
+ id: string;
11
+ name: string;
12
+ chain: string[];
13
+ cooldownMs: number;
14
+ }
15
+
16
+ export interface FallbackConfig {
17
+ cooldownMs: number;
18
+ fallbacks: FallbackEntry[];
19
+ }
20
+
21
+ /** Router state stored on the session branch by Pi. */
22
+ export interface RouterState {
23
+ activeCandidateIndex: number;
24
+ /** Model key (`provider/id`) mapped to the epoch-millisecond time its cooldown ends. */
25
+ cooldowns: Record<string, number>;
26
+ }
27
+
28
+ /** The failure details the router inspects. */
29
+ export interface FailureMessage {
30
+ stopReason?: string;
31
+ errorMessage?: string;
32
+ }
33
+
34
+ /**
35
+ * The narrow request shape the router needs. `ModelRouteRequest` satisfies it, while
36
+ * tests can build one without a full conversation transcript.
37
+ */
38
+ export interface RouterRequest {
39
+ reason: ModelRouteReason;
40
+ thinkingLevel: ModelThinkingLevel;
41
+ previous?: {
42
+ model: Model<Api>;
43
+ thinkingLevel?: ModelThinkingLevel;
44
+ };
45
+ failed?: {
46
+ model: Model<Api>;
47
+ thinkingLevel?: ModelThinkingLevel;
48
+ message: FailureMessage;
49
+ };
50
+ state?: RouterState;
51
+ }
52
+
53
+ /** The narrow registry surface the router needs. */
54
+ export interface RouterContext {
55
+ modelRegistry: {
56
+ find: (provider: string, modelId: string) => Model<Api> | undefined;
57
+ };
58
+ }
59
+
60
+ export type RouterRoute = ModelRoute<RouterState>;
61
+
62
+ /** Compile-time check that Pi's request shape stays compatible with our narrow one. */
63
+ export type _RouterRequestCompatibility =
64
+ ModelRouteRequest<RouterState> extends RouterRequest ? true : never;