pi-ccswitch-auto-switch 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Juny Wuuuu91
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,109 @@
+# Pi CCSwitch Auto Switch
+
+> 中文说明：[README.zh-CN.md](README.zh-CN.md)
+
+Resilient model failover for [Pi](https://github.com/badlogic/pi-mono) when its providers are managed by [CC Switch](https://ccswitch.io/).
+
+The extension observes real Pi requests, records sanitized health signals, and—only in interactive TUI/RPC sessions—moves a failed request to a healthy model. It treats provider failures as provider failures: an exhausted balance, invalid credentials, or rate limit will not cause a rapid series of retries against sibling models from the same provider.
+
+## Features
+
+- Uses Pi's effective model registry; never reads CC Switch databases, Pi auth files, or API keys.
+- Provider-first circuit breakers for authentication, quota, billing, and rate-limit failures.
+- Endpoint circuit breakers for DNS, connection, server, and streaming failures.
+- Model-only isolation for missing models and incompatible parameters.
+- Prefers a healthy model from another provider before considering a sibling model.
+- 90-second first-response and 120-second streaming-idle watchdogs.
+- Exponential cooldowns, `Retry-After` support, and one persisted half-open probe lease per provider.
+- Persistent, atomic, cross-process health state with error redaction and bounded logs.
+- Compact Pi status bar and interactive health panel.
+- Non-interactive `--print` / JSON runs monitor and record failures but do not inject a competing retry.
+
+## Requirements
+
+- Pi `0.84.4` or newer.
+- CC Switch `3.20+` is recommended for its native Pi model configuration support.
+- Node.js `22.19+` only for local development and tests. Pi supplies the runtime for the extension itself.
+
+## Installation
+
+### Pi package install (recommended)
+
+```bash
+pi install git:github.com/JunyWuuuu91/pi-ccswitch-auto-switch
+```
+
+This works on macOS, Linux, and Windows when Git is available. After the npm release, this will also work:
+
+```bash
+pi install npm:pi-ccswitch-auto-switch
+```
+
+Restart Pi or run `/reload` after installing or updating. To update the Git installation later, run `pi update --extensions`.
+
+CC Switch should be configured normally. This extension deliberately does not write Pi model settings or CC Switch data.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `/ccswitch` or `/ccswitch status` | Open the health panel. |
+| `/ccswitch help` | Show the command reference in Pi. |
+| `/ccswitch refresh` | Refresh Pi's model registry and the status display. |
+| `/ccswitch reactivate <provider/model\|all>` | Clear a breaker and let the next real request verify recovery, while preserving history. |
+| `/ccswitch disable <provider/model>` | Manually exclude a model from failover. |
+| `/ccswitch reset <provider/model\|all>` | Delete selected health history after confirmation. |
+| `/ccswitch-test` | Inspect candidate discovery without changing models. |
+
+Examples:
+
+```text
+/ccswitch reactivate all
+/ccswitch disable openai/gpt-4.1
+/ccswitch reset anthropic/claude-sonnet-4
+```
+
+## Status bar
+
+```text
+CCS ✓130 · ⏳1 · ⛔0
+```
+
+- `✓130`: effective models currently eligible for selection.
+- `⏳1`: one model, provider, or endpoint health record is cooling down.
+- `⛔0`: no manually disabled models.
+- During a switch, `CCS ↻2/5 provider/model` means the second of at most five attempts is being made.
+
+Use `/ccswitch` to inspect the exact record behind a cooldown.
+
+## Failover behavior
+
+The state machine waits for Pi's native retry cycle to settle before switching. A user message invalidates any pending switch from an older round, avoiding duplicate dispatches.
+
+| Failure | Scope | Initial cooldown |
+| --- | --- | --- |
+| `401`, `403`, quota, billing | Provider | 30 minutes |
+| `429` | Provider | `Retry-After` when present; otherwise 5 minutes |
+| DNS, network, `5xx`, interrupted stream | Endpoint | 2 minutes |
+| `404`, invalid model, incompatible parameters | Model | 15 minutes |
+| Content filtering or context overflow | Current round only | None |
+
+Cooldowns grow exponentially within bounded limits. Context-overflow retries only consider models with a larger context window. User cancellations are not recorded as failures; watchdog cancellations are recorded as timeouts.
+
+## Data and privacy
+
+Health state is stored in Pi's agent directory as `ccswitch-auto-switch-state.json`. The extension stores counters, timestamps, cooldowns, and redacted/truncated error summaries. It does not access credentials, authorization headers, CC Switch's database, or Pi's `auth.json`.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+Tests use Node's built-in test runner and cover failure classification, provider-first selection, cooldowns, state persistence, and Windows-compatible paths.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,101 @@
+# Pi CCSwitch 自动故障转移
+
+> English: [README.md](README.md)
+
+当 [CC Switch](https://ccswitch.io/) 管理 [Pi](https://github.com/badlogic/pi-mono) 的 Provider 时，为 Pi 提供更稳健的模型自动故障转移。
+
+它只观察 Pi 的真实请求，保存脱敏健康记录；仅在 TUI/RPC 交互会话中，才会把失败请求平滑切到健康模型。额度耗尽、凭据失效或限流等 Provider 级问题会直接熔断整个 Provider，不会连续尝试同一 Provider 下的多个兄弟模型。
+
+## 功能
+
+- 以 Pi 的有效模型注册表为准，不读取 CC Switch 数据库、Pi 认证文件或 API Key。
+- 对认证、额度、账单和限流实施 Provider 优先熔断。
+- 对 DNS、连接、服务端和流中断实施端点熔断。
+- 模型不存在或参数不兼容时仅隔离该模型。
+- 优先选择不同 Provider 的健康模型；同 Provider 的模型排在后面。
+- 首响应 90 秒、流式停滞 120 秒看门狗。
+- 指数退避、`Retry-After` 支持和跨进程 half-open 单探针租约。
+- 原子持久化状态、错误脱敏和有上限的日志。
+- Pi 紧凑状态栏与健康管理面板。
+- `--print` / JSON 非交互运行只监控和记录，不会注入可能与进程退出竞争的新请求。
+
+## 要求
+
+- Pi `0.84.4` 或更高版本。
+- 建议使用 CC Switch `3.20+`，其已支持原生维护 Pi 模型配置。
+- 本地开发和测试需要 Node.js `22.19+`；Pi 运行插件本身不需要额外安装 Node。
+
+## 安装
+
+### 通过 Pi Package 安装（推荐）
+
+```bash
+pi install git:github.com/JunyWuuuu91/pi-ccswitch-auto-switch
+```
+
+该命令在 macOS、Linux 和安装了 Git 的 Windows 上均可使用。npm 版本发布后，也可以执行：
+
+```bash
+pi install npm:pi-ccswitch-auto-switch
+```
+
+安装或更新后重启 Pi，或执行 `/reload`。后续更新 Git 版本可执行 `pi update --extensions`。
+
+正常使用 CC Switch 配置 Provider 即可；本插件不会修改 Pi 模型设置或 CC Switch 数据。
+
+## 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `/ccswitch` 或 `/ccswitch status` | 打开健康面板。 |
+| `/ccswitch help` | 在 Pi 内显示命令帮助。 |
+| `/ccswitch refresh` | 刷新 Pi 模型注册表和状态栏。 |
+| `/ccswitch reactivate <provider/model\|all>` | 解除熔断，下一次真实请求验证恢复情况；保留历史。 |
+| `/ccswitch disable <provider/model>` | 手动排除模型。 |
+| `/ccswitch reset <provider/model\|all>` | 确认后删除相应健康历史。 |
+| `/ccswitch-test` | 仅检查候选发现，不切换模型。 |
+
+## 状态栏
+
+```text
+CCS ✓130 · ⏳1 · ⛔0
+```
+
+- `✓130`：当前可参与选择的有效模型数量。
+- `⏳1`：有一条模型、Provider 或端点健康记录仍在冷却。
+- `⛔0`：没有被手动禁用的模型。
+- 切换中出现 `CCS ↻2/5 provider/model`，表示正在进行最多 5 次尝试中的第 2 次。
+
+通过 `/ccswitch` 查看具体哪个记录正在冷却。
+
+## 故障转移逻辑
+
+插件会先等待 Pi 内置重试结束和会话恢复 idle，再进行切换。新的用户输入会使旧轮次的待切换任务失效，从而避免重复发送。
+
+| 失败类型 | 熔断范围 | 初始冷却 |
+| --- | --- | --- |
+| `401`、`403`、额度或账单问题 | Provider | 30 分钟 |
+| `429` | Provider | 优先使用 `Retry-After`，否则 5 分钟 |
+| DNS、网络、`5xx`、流中断 | 端点 | 2 分钟 |
+| `404`、模型不存在、参数不兼容 | 模型 | 15 分钟 |
+| 内容过滤、上下文溢出 | 仅本轮 | 无 |
+
+冷却时间会指数增长但有上限。上下文溢出时只会选择上下文窗口更大的模型。用户主动取消不计失败；看门狗取消会记录为超时。
+
+## 数据与隐私
+
+健康状态保存在 Pi agent 目录的 `ccswitch-auto-switch-state.json`。其中只有计数、时间、冷却信息和脱敏/截断的错误摘要；插件不会访问凭据、Authorization 请求头、CC Switch 数据库或 Pi 的 `auth.json`。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+测试使用 Node 内置测试运行器，覆盖失败分类、Provider 优先选择、冷却、状态持久化以及 Windows 路径。
+
+## 许可证
+
+[MIT](LICENSE)

package/candidates.ts

@@ -0,0 +1,49 @@
+import type { ModelRef, ScopedModel } from './types.ts'
+import { endpointKey, modelKey, type HealthState } from './health.ts'
+
+export interface CandidateOptions {
+  current?: ModelRef
+  tried: Set<string>
+  failureKind?: string
+  health: HealthState
+}
+
+function blocked(model: ModelRef, health: HealthState, now = Date.now()): boolean {
+  const records = [health.models[modelKey(model)], health.providers[model.provider], health.endpoints[endpointKey(model)]]
+  return records.some(record => Boolean(record?.disabled || (record?.cooldownUntil && record.cooldownUntil > now) || (record?.leaseUntil && record.leaseUntil > now)))
+}
+
+export function effectiveCandidates(scoped: readonly ScopedModel[], available: ModelRef[]): ModelRef[] {
+  const source = scoped.length > 0 ? scoped.map(item => item.model) : available
+  const seen = new Set<string>()
+  return source.filter(model => {
+    const key = modelKey(model)
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+export function chooseCandidate(models: ModelRef[], options: CandidateOptions): ModelRef | undefined {
+  const current = options.current
+  const candidates = models.filter(model => {
+    if (options.tried.has(modelKey(model)) || blocked(model, options.health)) return false
+    if (options.failureKind === 'context_overflow' && current && (model.contextWindow ?? 0) <= (current.contextWindow ?? 0)) return false
+    return true
+  })
+  return candidates.sort((a, b) => score(a, current) - score(b, current))[0]
+}
+
+function score(candidate: ModelRef, current?: ModelRef): number {
+  if (!current) return 0
+  const sameProvider = candidate.provider === current.provider ? 1000 : 0
+  const differentId = candidate.id === current.id ? 0 : 100
+  const inputMismatch = sameInputs(candidate, current) ? 0 : 20
+  const reasoningMismatch = candidate.reasoning === current.reasoning ? 0 : 10
+  const contextPenalty = (candidate.contextWindow ?? 0) < (current.contextWindow ?? 0) ? 5 : 0
+  return sameProvider + differentId + inputMismatch + reasoningMismatch + contextPenalty
+}
+
+function sameInputs(a: ModelRef, b: ModelRef): boolean {
+  return (a.input ?? []).join(',') === (b.input ?? []).join(',')
+}

package/classify.ts

@@ -0,0 +1,37 @@
+import type { FailureClass, FailureObservation, HealthScope } from './types.ts'
+
+export interface Classification {
+  kind: FailureClass
+  scope?: HealthScope
+  roundOnly: boolean
+  retryAfterMs?: number
+}
+
+const content = /content[ _-]?filter|sensitive|guardrail|policy[_ ]?violation|content[_ ]?blocked/i
+const quota = /quota|billing|insufficient.?balance|out of budget|usage.?limit|credit.?balance|monthly.?limit/i
+const context = /context.?window|context.?length|too many tokens|prompt is too long|input is too long|token limit/i
+const transport = /dns|enotfound|eai_again|socket|connection|network|fetch failed|timed? ?out|timeout|stream ended|terminated|websocket/i
+
+export function classifyFailure(observation: FailureObservation): Classification {
+  const text = `${observation.rawStopReason ?? ''} ${observation.message ?? ''}`
+  const status = observation.status
+  if (observation.aborted && !observation.watchdog) return { kind: 'unknown', roundOnly: true }
+  if (observation.watchdog) return { kind: 'timeout', scope: 'endpoint', roundOnly: false }
+  if (content.test(text)) return { kind: 'content_policy', roundOnly: true }
+  if (context.test(text)) return { kind: 'context_overflow', roundOnly: true }
+  if (status === 429) return { kind: 'rate_limit', scope: 'provider', roundOnly: false, retryAfterMs: observation.retryAfterMs }
+  if (status === 401 || status === 403) return { kind: 'auth', scope: 'provider', roundOnly: false }
+  if (quota.test(text)) return { kind: 'quota', scope: 'provider', roundOnly: false }
+  if (status !== undefined && status >= 500) return { kind: 'endpoint', scope: 'endpoint', roundOnly: false }
+  if (status === 400 || status === 404 || status === 422) return { kind: 'model_config', scope: 'model', roundOnly: false }
+  if (transport.test(text)) return { kind: 'endpoint', scope: 'endpoint', roundOnly: false }
+  return { kind: 'unknown', scope: 'model', roundOnly: false }
+}
+
+export function parseRetryAfter(value: string | undefined, now = Date.now()): number | undefined {
+  if (!value) return undefined
+  const seconds = Number(value)
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000
+  const at = Date.parse(value)
+  return Number.isNaN(at) ? undefined : Math.max(0, at - now)
+}

package/health.ts

@@ -0,0 +1,291 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { appendFile, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { FailureClass, HealthScope, ModelRef } from './types.ts'
+
+const STATE_FILE = 'ccswitch-auto-switch-state.json'
+const LEGACY_FILE = 'ccswitch-cooldown.json'
+const LOCK_DIR = '.ccswitch-auto-switch.lock'
+const LOG_FILE = 'ccswitch-auto-switch.log'
+const REPORT_FILE = 'ccswitch-failure-report.md'
+const MAX_LOG_BYTES = 512 * 1024
+
+export interface HealthRecord {
+  consecutiveFailures: number
+  totalFailures: number
+  lastFailureAt?: number
+  lastSuccessAt?: number
+  cooldownUntil?: number
+  lastClass?: FailureClass
+  lastError?: string
+  disabled?: boolean
+  leaseUntil?: number
+}
+
+export interface HealthState {
+  schemaVersion: 2
+  updatedAt: number
+  models: Record<string, HealthRecord>
+  providers: Record<string, HealthRecord>
+  endpoints: Record<string, HealthRecord>
+}
+
+export function agentDir(env = process.env, home = homedir()): string {
+  return env.PI_CODING_AGENT_DIR?.trim() || join(home, '.pi', 'agent')
+}
+
+export function modelKey(model: Pick<ModelRef, 'provider' | 'id'>): string {
+  return `${model.provider}/${model.id}`
+}
+
+export function endpointKey(model: ModelRef): string {
+  const source = model.baseUrl ? safeEndpoint(model.baseUrl) : `provider:${model.provider}`
+  return createHash('sha256').update(`${model.provider}\0${source}`).digest('hex').slice(0, 20)
+}
+
+function safeEndpoint(value: string): string {
+  try {
+    const url = new URL(value)
+    return `${url.protocol}//${url.host}${url.pathname}`
+  } catch {
+    return value.slice(0, 256)
+  }
+}
+
+function blank(): HealthState {
+  return { schemaVersion: 2, updatedAt: Date.now(), models: {}, providers: {}, endpoints: {} }
+}
+
+function redact(text: string | undefined): string | undefined {
+  if (!text) return undefined
+  return text
+    .replace(/(authorization\s*[:=]\s*)(\S+)/gi, '$1[redacted]')
+    .replace(/(bearer\s+)(\S+)/gi, '$1[redacted]')
+    .replace(/([?&](?:key|token|api[_-]?key|signature)=)[^&\s]+/gi, '$1[redacted]')
+    .replace(/sk-[A-Za-z0-9_-]{12,}/g, '[redacted]')
+    .replace(/[\x00-\x1f\x7f]/g, ' ')
+    .slice(0, 240)
+}
+
+function cooldownMs(kind: FailureClass, failures: number, retryAfterMs?: number): number {
+  const factor = 2 ** Math.max(0, failures - 1)
+  if (kind === 'rate_limit') return Math.min(24 * 60 * 60_000, Math.max(retryAfterMs ?? 0, 5 * 60_000 * factor))
+  if (kind === 'auth' || kind === 'quota') return Math.min(6 * 60 * 60_000, 30 * 60_000 * factor)
+  if (kind === 'model_config') return Math.min(2 * 60 * 60_000, 15 * 60_000 * factor)
+  return Math.min(30 * 60_000, 2 * 60_000 * factor)
+}
+
+export class HealthStore {
+  readonly dir: string
+  private state: HealthState = blank()
+  private dirty = false
+  private replaceOnFlush = false
+
+  constructor(dir = agentDir()) { this.dir = dir }
+  get file(): string { return join(this.dir, STATE_FILE) }
+  get snapshot(): HealthState { return structuredClone(this.state) }
+
+  async load(): Promise<void> {
+    await mkdir(this.dir, { recursive: true })
+    try {
+      if (existsSync(this.file)) {
+        const parsed = JSON.parse(await readFile(this.file, 'utf8')) as HealthState
+        if (parsed.schemaVersion !== 2 || !parsed.models || !parsed.providers || !parsed.endpoints) throw new Error('unsupported state schema')
+        this.state = parsed
+      } else {
+        await this.migrateLegacy()
+      }
+    } catch {
+      if (existsSync(this.file)) await rename(this.file, `${this.file}.corrupt-${Date.now()}`).catch(() => {})
+      this.state = blank()
+      this.dirty = true
+      await this.flush()
+    }
+  }
+
+  private async migrateLegacy(): Promise<void> {
+    const legacy = join(this.dir, LEGACY_FILE)
+    if (!existsSync(legacy)) return
+    try {
+      const entries = JSON.parse(await readFile(legacy, 'utf8')) as Record<string, { failedAt?: number, reason?: string, errorMessage?: string }>
+      for (const [key, entry] of Object.entries(entries)) {
+        this.state.models[key] = {
+          consecutiveFailures: 1, totalFailures: 1, lastFailureAt: entry.failedAt,
+          cooldownUntil: (entry.failedAt ?? Date.now()) + 60 * 60_000,
+          lastClass: entry.reason === 'sensitive' ? 'content_policy' : 'unknown', lastError: redact(entry.errorMessage),
+        }
+      }
+      this.dirty = true
+      await this.flush()
+    } catch { /* legacy data is optional */ }
+  }
+
+  recordFailure(scope: HealthScope, key: string, kind: FailureClass, message?: string, retryAfterMs?: number): void {
+    const bucket = this.bucket(scope)
+    const previous = bucket[key] ?? { consecutiveFailures: 0, totalFailures: 0 }
+    const failures = previous.consecutiveFailures + 1
+    bucket[key] = {
+      ...previous, consecutiveFailures: failures, totalFailures: previous.totalFailures + 1,
+      lastFailureAt: Date.now(), cooldownUntil: Date.now() + cooldownMs(kind, failures, retryAfterMs),
+      lastClass: kind, lastError: redact(message), leaseUntil: undefined,
+    }
+    this.touch()
+  }
+
+  recordSuccess(model: ModelRef): void {
+    this.close('model', modelKey(model))
+    this.close('provider', model.provider)
+    this.close('endpoint', endpointKey(model))
+    this.touch()
+  }
+
+  private close(scope: HealthScope, key: string): void {
+    const current = this.bucket(scope)[key]
+    if (!current) return
+    this.bucket(scope)[key] = { ...current, consecutiveFailures: 0, cooldownUntil: undefined, leaseUntil: undefined, lastSuccessAt: Date.now() }
+  }
+
+  disable(key: string, disabled: boolean): void {
+    const old = this.state.models[key] ?? { consecutiveFailures: 0, totalFailures: 0 }
+    this.state.models[key] = { ...old, disabled }
+    this.touch()
+  }
+
+  reactivate(model: ModelRef): void {
+    const key = modelKey(model)
+    for (const [scope, id] of [['model', key], ['provider', model.provider], ['endpoint', endpointKey(model)]] as const) {
+      const old = this.bucket(scope)[id]
+      if (old) this.bucket(scope)[id] = { ...old, disabled: false, cooldownUntil: undefined, leaseUntil: undefined, lastSuccessAt: Date.now(), consecutiveFailures: 0 }
+    }
+    this.touch()
+  }
+
+  reactivateAll(): void {
+    const now = Date.now()
+    for (const bucket of [this.state.models, this.state.providers, this.state.endpoints]) {
+      for (const [key, old] of Object.entries(bucket)) bucket[key] = { ...old, disabled: false, cooldownUntil: undefined, leaseUntil: undefined, lastSuccessAt: now, consecutiveFailures: 0 }
+    }
+    this.touch()
+  }
+
+  reset(target: string | 'all'): void {
+    if (target === 'all') this.state = blank()
+    else delete this.state.models[target]
+    this.replaceOnFlush = true
+    this.touch()
+  }
+
+  isBlocked(model: ModelRef, now = Date.now()): boolean {
+    return [this.state.models[modelKey(model)], this.state.providers[model.provider], this.state.endpoints[endpointKey(model)]]
+      .some(record => Boolean(record?.disabled || (record?.cooldownUntil && record.cooldownUntil > now) || (record?.leaseUntil && record.leaseUntil > now)))
+  }
+
+  async claimProvider(model: ModelRef): Promise<boolean> {
+    const key = model.provider
+    let claimed = true
+    await this.withLock(async () => {
+      if (!this.replaceOnFlush) this.state = mergeState(await this.readDisk(), this.state)
+      const record = this.state.providers[key]
+      if (!record || !(record.cooldownUntil && record.cooldownUntil <= Date.now())) return
+      if (record.leaseUntil && record.leaseUntil > Date.now()) { claimed = false; return }
+      record.leaseUntil = Date.now() + 2 * 60_000
+      this.touch()
+      await this.commit()
+    }).catch(() => { claimed = false })
+    return claimed
+  }
+
+  async flush(): Promise<void> {
+    if (!this.dirty) return
+    await this.withLock(async () => {
+      this.state = mergeState(await this.readDisk(), this.state)
+      await this.commit()
+    }).catch(() => {})
+  }
+
+  async log(line: string): Promise<void> {
+    const path = join(this.dir, LOG_FILE)
+    try {
+      if (existsSync(path) && (await stat(path)).size > MAX_LOG_BYTES) {
+        await rm(`${path}.3`, { force: true })
+        await rename(`${path}.2`, `${path}.3`).catch(() => {})
+        await rename(`${path}.1`, `${path}.2`).catch(() => {})
+        await rename(path, `${path}.1`)
+      }
+      await appendFile(path, `[${new Date().toISOString()}] ${redact(line) ?? ''}\n`, 'utf8')
+    } catch { /* logging must never affect Pi */ }
+  }
+
+  async report(markdown: string): Promise<void> {
+    const safe = markdown.split('\n').map(line => redact(line) ?? '').join('\n')
+    await writeFile(join(this.dir, REPORT_FILE), safe, 'utf8').catch(() => {})
+  }
+
+  private touch(): void { this.dirty = true }
+  private async readDisk(): Promise<HealthState> {
+    try {
+      if (!existsSync(this.file)) return blank()
+      const parsed = JSON.parse(await readFile(this.file, 'utf8')) as HealthState
+      return parsed.schemaVersion === 2 ? parsed : blank()
+    } catch { return blank() }
+  }
+  private async commit(): Promise<void> {
+    this.state.updatedAt = Date.now()
+    const temp = `${this.file}.tmp-${process.pid}-${randomUUID()}`
+    await writeFile(temp, JSON.stringify(this.state, null, 2), 'utf8')
+    await rename(temp, this.file)
+    this.dirty = false
+    this.replaceOnFlush = false
+  }
+  private bucket(scope: HealthScope): Record<string, HealthRecord> {
+    return scope === 'model' ? this.state.models : scope === 'provider' ? this.state.providers : this.state.endpoints
+  }
+  private async withLock<T>(work: () => Promise<T>): Promise<T> {
+    const lock = join(this.dir, LOCK_DIR)
+    const deadline = Date.now() + 750
+    while (true) {
+      try {
+        await mkdir(lock)
+        try { return await work() } finally { await rm(lock, { recursive: true, force: true }) }
+      } catch (error: any) {
+        if (error?.code !== 'EEXIST' || Date.now() >= deadline) throw error
+        try { if (Date.now() - (await stat(lock)).mtimeMs > 30_000) await rm(lock, { recursive: true, force: true }) } catch { /* another process won */ }
+        await new Promise(resolve => setTimeout(resolve, 25 + Math.floor(Math.random() * 50)))
+      }
+    }
+  }
+}
+
+function mergeRecord(a: HealthRecord | undefined, b: HealthRecord | undefined): HealthRecord | undefined {
+  if (!a) return b
+  if (!b) return a
+  const newest = (b.lastFailureAt ?? 0) >= (a.lastFailureAt ?? 0) ? b : a
+  const lastFailureAt = Math.max(a.lastFailureAt ?? 0, b.lastFailureAt ?? 0)
+  const lastSuccessAt = Math.max(a.lastSuccessAt ?? 0, b.lastSuccessAt ?? 0)
+  const successWins = lastSuccessAt > lastFailureAt
+  return {
+    ...newest,
+    totalFailures: Math.max(a.totalFailures, b.totalFailures),
+    disabled: b.disabled ?? a.disabled,
+    lastFailureAt: lastFailureAt || undefined,
+    lastSuccessAt: lastSuccessAt || undefined,
+    consecutiveFailures: successWins ? 0 : Math.max(a.consecutiveFailures, b.consecutiveFailures),
+    cooldownUntil: successWins ? undefined : Math.max(a.cooldownUntil ?? 0, b.cooldownUntil ?? 0) || undefined,
+    leaseUntil: successWins ? undefined : Math.max(a.leaseUntil ?? 0, b.leaseUntil ?? 0) || undefined,
+  }
+}
+
+function mergeBucket(a: Record<string, HealthRecord>, b: Record<string, HealthRecord>): Record<string, HealthRecord> {
+  const output: Record<string, HealthRecord> = {}
+  for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+    const record = mergeRecord(a[key], b[key])
+    if (record) output[key] = record
+  }
+  return output
+}
+
+function mergeState(a: HealthState, b: HealthState): HealthState {
+  return { schemaVersion: 2, updatedAt: Math.max(a.updatedAt ?? 0, b.updatedAt ?? 0), models: mergeBucket(a.models ?? {}, b.models ?? {}), providers: mergeBucket(a.providers ?? {}, b.providers ?? {}), endpoints: mergeBucket(a.endpoints ?? {}, b.endpoints ?? {}) }
+}

package/index.ts

@@ -0,0 +1,236 @@
+import type { ExtensionAPI, ExtensionContext, FailureObservation, ModelRef } from './types.ts'
+import { classifyFailure, parseRetryAfter } from './classify.ts'
+import { effectiveCandidates, chooseCandidate } from './candidates.ts'
+import { HealthStore, endpointKey, modelKey } from './health.ts'
+
+const FIRST_RESPONSE_TIMEOUT = 90_000
+const STREAM_IDLE_TIMEOUT = 120_000
+const MAX_ATTEMPTS = 5
+const ROUND_LIMIT = 8 * 60_000
+
+type Phase = 'idle' | 'monitoring' | 'settled-error' | 'switching' | 'redispatching' | 'verifying' | 'exhausted'
+interface Round {
+  id: number
+  phase: Phase
+  startedAt: number
+  text: string
+  images?: Array<Record<string, unknown>>
+  tried: Set<string>
+  attempts: number
+  hadTool: boolean
+  inTool: boolean
+  hadOutput: boolean
+  watchdog: boolean
+  cleanRetry: boolean
+  observation?: FailureObservation
+  model?: ModelRef
+}
+
+function key(model: ModelRef | undefined): string | undefined { return model && modelKey(model) }
+function canRetry(ctx: ExtensionContext): boolean { return ctx.mode === 'tui' || ctx.mode === 'rpc' }
+
+export default function (pi: ExtensionAPI) {
+  const health = new HealthStore()
+  let round: Round | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let lastStatus: { status?: number, retryAfterMs?: number } = {}
+
+  const clearWatchdog = () => { if (timer) clearTimeout(timer); timer = undefined }
+  const armWatchdog = (ctx: ExtensionContext, ms: number, roundId: number) => {
+    clearWatchdog()
+    timer = setTimeout(() => {
+      if (!round || round.id !== roundId || (!ctx.isIdle() && !round.inTool)) {
+        round && (round.watchdog = true)
+        ctx.abort()
+      }
+    }, ms)
+    timer.unref?.()
+  }
+  const status = (ctx: ExtensionContext) => {
+    const state = health.snapshot
+    const models = effectiveCandidates(ctx.scopedModels, ctx.modelRegistry.getAvailable())
+    const now = Date.now()
+    const disabled = Object.values(state.models).filter(item => item.disabled).length
+    const cooling = [...Object.values(state.models), ...Object.values(state.providers), ...Object.values(state.endpoints)]
+      .filter(item => item.cooldownUntil && item.cooldownUntil > now).length
+    const unhealthy = models.filter(model => health.isBlocked(model)).length
+    const healthy = Math.max(0, models.length - unhealthy)
+    const plain = round?.phase === 'switching' ? `CCS ↻${round.attempts}/${MAX_ATTEMPTS} ${round.model ? modelKey(round.model) : ''}` :
+      cooling || disabled ? `CCS ✓${healthy} · ⏳${cooling} · ⛔${disabled}` : `CCS ✓${models.length}`
+    const theme = ctx.ui.theme
+    ctx.ui.setStatus('ccswitch-ha', theme ? theme.fg(cooling || disabled ? 'warning' : 'success', plain) : plain)
+  }
+  const notify = (ctx: ExtensionContext, message: string, type: 'info' | 'warning' | 'error' = 'info') => {
+    if (ctx.hasUI) ctx.ui.notify(message, type)
+  }
+  const showHelp = (ctx: ExtensionContext) => {
+    notify(ctx, [
+      'CCSwitch 命令：',
+      '/ccswitch 或 /ccswitch status — 查看健康面板',
+      '/ccswitch help — 显示此帮助',
+      '/ccswitch refresh — 刷新 Pi 模型注册表和状态',
+      '/ccswitch reactivate <provider/model|all> — 解除熔断，保留历史',
+      '/ccswitch disable <provider/model> — 手动禁用模型',
+      '/ccswitch reset <provider/model|all> — 清除健康历史（需确认）',
+      '/ccswitch-test — 自检候选模型，不实际切换',
+    ].join('\n'), 'info')
+  }
+  const refresh = async (ctx: ExtensionContext) => {
+    try { await ctx.modelRegistry.refresh() } catch (error) { await health.log(`registry refresh failed: ${String(error)}`); notify(ctx, 'CCSwitch：Pi 模型注册表刷新失败，继续使用上次快照', 'warning') }
+    status(ctx)
+  }
+  const showPanel = async (ctx: ExtensionContext) => {
+    const state = health.snapshot
+    const candidates = effectiveCandidates(ctx.scopedModels, ctx.modelRegistry.getAvailable())
+    const rows = candidates.slice(0, 10).map(model => {
+      const record = state.models[modelKey(model)] ?? state.providers[model.provider]
+      const suffix = record?.disabled ? '禁用' : record?.cooldownUntil && record.cooldownUntil > Date.now() ? `冷却 ${Math.ceil((record.cooldownUntil - Date.now()) / 60_000)}m` : '健康'
+      return `${modelKey(model)}  ${suffix}`
+    })
+    if (!ctx.ui.select) { notify(ctx, `CCSwitch：${candidates.length} 个候选，${rows.filter(row => row.includes('冷却')).length} 个冷却`, 'info'); return }
+    const action = await ctx.ui.select(`CCSwitch 健康面板\n当前：${key(ctx.model) ?? '无'}\n${rows.join('\n') || '没有可用模型'}`, ['刷新', '重新激活当前模型', '禁用当前模型', '重置当前模型历史', '关闭'])
+    if (action === '刷新') await refresh(ctx)
+    if (action === '重新激活当前模型' && ctx.model) { health.reactivate(ctx.model); await health.flush(); status(ctx); notify(ctx, '已重新激活当前模型') }
+    if (action === '禁用当前模型' && ctx.model) { health.disable(modelKey(ctx.model), true); await health.flush(); status(ctx); notify(ctx, '已禁用当前模型', 'warning') }
+    if (action === '重置当前模型历史' && ctx.model) {
+      const ok = !ctx.ui.confirm || await ctx.ui.confirm('重置健康历史', `删除 ${modelKey(ctx.model)} 的记录？`)
+      if (ok) { health.reset(modelKey(ctx.model)); await health.flush(); status(ctx) }
+    }
+  }
+  const exhaust = async (ctx: ExtensionContext, reason: string) => {
+    if (!round) return
+    round.phase = 'exhausted'
+    clearWatchdog()
+    ctx.ui.setWorkingMessage()
+    await health.report(`# CCSwitch 自动故障转移失败\n\n时间：${new Date().toISOString()}\n原因：${reason}\n\n已尝试：\n${[...round.tried].map(item => `- ${item}`).join('\n')}\n\n可使用 /ccswitch status 查看状态，/ccswitch reactivate <provider/model> 重新激活。`)
+    await health.log(`round exhausted: ${reason}; tried=${[...round.tried].join(',')}`)
+    notify(ctx, `CCSwitch：自动切换停止（${reason}），请用 /ccswitch 查看详情`, 'error')
+    status(ctx)
+  }
+  const failover = async (ctx: ExtensionContext) => {
+    if (!round || !round.observation || !round.model || !canRetry(ctx)) return
+    if (round.attempts >= MAX_ATTEMPTS || Date.now() - round.startedAt >= ROUND_LIMIT) return exhaust(ctx, '达到本轮切换上限')
+    const classification = classifyFailure(round.observation)
+    if (round.observation.aborted && !round.observation.watchdog) { round.phase = 'idle'; clearWatchdog(); status(ctx); return }
+    round.phase = 'switching'
+    round.tried.add(modelKey(round.model))
+    if (!classification.roundOnly && classification.scope) health.recordFailure(classification.scope, classification.scope === 'model' ? modelKey(round.model) : classification.scope === 'provider' ? round.model.provider : endpointKey(round.model), classification.kind, round.observation.message, classification.retryAfterMs)
+    await health.flush()
+    await refresh(ctx)
+    const candidates = effectiveCandidates(ctx.scopedModels, ctx.modelRegistry.getAvailable())
+    let next = chooseCandidate(candidates, { current: round.model, tried: round.tried, failureKind: classification.kind, health: health.snapshot })
+    while (next) {
+      if (!await health.claimProvider(next)) { round.tried.add(modelKey(next)); next = chooseCandidate(candidates, { current: round.model, tried: round.tried, failureKind: classification.kind, health: health.snapshot }); continue }
+      round.attempts++
+      ctx.ui.setWorkingMessage(`模型异常，正在切换到 ${modelKey(next)}…`)
+      const set = await pi.setModel(next).catch(() => false)
+      if (!set) {
+        health.recordFailure('model', modelKey(next), 'model_config', 'Pi refused model selection')
+        round.tried.add(modelKey(next)); await health.flush()
+        next = chooseCandidate(candidates, { current: round.model, tried: round.tried, failureKind: classification.kind, health: health.snapshot })
+        continue
+      }
+      round.model = next
+      round.phase = 'redispatching'
+      notify(ctx, `CCSwitch：已切换至 ${modelKey(next)}（${round.attempts}/${MAX_ATTEMPTS}）`, 'info')
+      const continuation = round.hadTool || round.hadOutput
+        ? '请从当前会话状态继续完成上一条请求；不要重复已经完成的工具操作。'
+        : round.images?.length ? [{ type: 'text', text: round.text }, ...round.images] : round.text
+      round.cleanRetry = !round.hadTool && !round.hadOutput
+      round.observation = undefined
+      round.watchdog = false
+      round.phase = 'verifying'
+      pi.sendUserMessage(continuation as any)
+      status(ctx)
+      return
+    }
+    await exhaust(ctx, '没有健康的候选模型')
+  }
+
+  pi.on('session_start', async (_event, ctx) => { await health.load(); await refresh(ctx); await health.log('extension started') })
+  pi.on('session_shutdown', async (_event, ctx) => { clearWatchdog(); ctx.ui.setWorkingMessage(); await health.flush() })
+  pi.on('input', (event, ctx) => {
+    if (event.source === 'extension') return { action: 'continue' }
+    clearWatchdog()
+    lastStatus = {}
+    round = { id: (round?.id ?? 0) + 1, phase: 'monitoring', startedAt: Date.now(), text: event.text, images: event.images, tried: new Set(), attempts: 0, hadTool: false, inTool: false, hadOutput: false, watchdog: false, cleanRetry: false, model: ctx.model }
+    status(ctx)
+    return { action: 'continue' }
+  })
+  pi.on('before_provider_request', (_event, ctx) => { lastStatus = {}; if (round) { round.inTool = false; armWatchdog(ctx, FIRST_RESPONSE_TIMEOUT, round.id) } })
+  pi.on('after_provider_response', (event, ctx) => {
+    lastStatus = { status: event.status, retryAfterMs: parseRetryAfter(event.headers?.['retry-after']) }
+    if (round && event.status >= 200 && event.status < 300) armWatchdog(ctx, STREAM_IDLE_TIMEOUT, round.id)
+  })
+  pi.on('message_update', (_event, ctx) => { if (round) armWatchdog(ctx, STREAM_IDLE_TIMEOUT, round.id) })
+  pi.on('context', (event) => {
+    if (!round?.cleanRetry) return
+    round.cleanRetry = false
+    let removed = false
+    return {
+      messages: event.messages.filter((message: any) => {
+        if (!removed && message?.role === 'assistant' && (message.stopReason === 'error' || message.stopReason === 'aborted')) { removed = true; return false }
+        return true
+      }),
+    }
+  })
+  pi.on('tool_execution_start', () => { if (round) { round.hadTool = true; round.inTool = true; clearWatchdog() } })
+  pi.on('tool_execution_end', () => { if (round) round.inTool = false })
+  pi.on('turn_end', async (event, ctx) => {
+    const message = event.message
+    if (message?.role !== 'assistant' || !round) return
+    clearWatchdog()
+    round.model = { provider: message.provider, id: message.model }
+    round.hadOutput ||= Boolean(message.content?.length)
+    if (message.stopReason === 'error' || message.stopReason === 'aborted') {
+      round.phase = 'settled-error'
+      round.observation = { message: message.errorMessage, rawStopReason: message.rawStopReason, status: lastStatus.status, retryAfterMs: lastStatus.retryAfterMs, watchdog: round.watchdog, aborted: message.stopReason === 'aborted' }
+      await health.log(`turn failed ${modelKey(round.model)}: ${message.errorMessage ?? message.stopReason}`)
+    } else {
+      health.recordSuccess(round.model); await health.flush()
+      round.phase = 'idle'; round.observation = undefined; ctx.ui.setWorkingMessage(); status(ctx)
+    }
+  })
+  pi.on('agent_settled', async (_event, ctx) => {
+    if (!round || round.phase !== 'settled-error') return
+    if (!ctx.isIdle()) return
+    if (!canRetry(ctx) && round.observation && round.model) {
+      const classification = classifyFailure(round.observation)
+      if (!classification.roundOnly && classification.scope) {
+        const domain = classification.scope === 'model' ? modelKey(round.model) : classification.scope === 'provider' ? round.model.provider : endpointKey(round.model)
+        health.recordFailure(classification.scope, domain, classification.kind, round.observation.message, classification.retryAfterMs)
+        await health.flush()
+      }
+      round.phase = 'idle'
+      status(ctx)
+      return
+    }
+    await failover(ctx)
+  })
+  pi.on('model_select', (_event, ctx) => status(ctx))
+
+  pi.registerCommand('ccswitch', { description: '查看和管理 CCSwitch 自动故障转移健康状态', handler: async (args, ctx) => {
+    const [verb, target] = args.trim().split(/\s+/, 2)
+    if (!verb || verb === 'status') return showPanel(ctx)
+    if (verb === 'help') return showHelp(ctx)
+    if (verb === 'refresh') return refresh(ctx)
+    if (!target && verb !== 'reset') { notify(ctx, '请指定 provider/model 或 all', 'warning'); return }
+    if (verb === 'disable' && target) { health.disable(target, true); await health.flush(); status(ctx); return }
+    if (verb === 'reactivate' && target) {
+      if (target === 'all') health.reactivateAll()
+      else { const [provider, ...rest] = target.split('/'); health.reactivate({ provider, id: rest.join('/') }) }
+      await health.flush(); status(ctx); return
+    }
+    if (verb === 'reset' && target) {
+      const ok = !ctx.ui.confirm || await ctx.ui.confirm('重置健康历史', `删除 ${target} 的健康记录？`)
+      if (ok) { health.reset(target === 'all' ? 'all' : target); await health.flush(); status(ctx) }
+      return
+    }
+    showHelp(ctx)
+  }})
+  pi.registerCommand('ccswitch-test', { description: '检查 CCSwitch 候选模型和健康状态（不切换模型）', handler: async (_args, ctx) => {
+    await refresh(ctx)
+    const count = effectiveCandidates(ctx.scopedModels, ctx.modelRegistry.getAvailable()).length
+    notify(ctx, `CCSwitch 自检完成：${count} 个有效候选模型`, count ? 'info' : 'warning')
+  }})
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "pi-ccswitch-auto-switch",
+  "version": "0.1.0",
+  "description": "Provider-first automatic model failover extension for Pi and CC Switch",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "ccswitch",
+    "failover",
+    "model-routing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JunyWuuuu91/pi-ccswitch-auto-switch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JunyWuuuu91/pi-ccswitch-auto-switch/issues"
+  },
+  "homepage": "https://github.com/JunyWuuuu91/pi-ccswitch-auto-switch#readme",
+  "files": [
+    "index.ts",
+    "types.ts",
+    "classify.ts",
+    "candidates.ts",
+    "health.ts"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --module nodenext --moduleResolution nodenext --target es2022 --skipLibCheck *.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19"
+  }
+}

package/types.ts

@@ -0,0 +1,71 @@
+export interface ModelRef {
+  provider: string
+  id: string
+  name?: string
+  baseUrl?: string
+  contextWindow?: number
+  maxTokens?: number
+  reasoning?: boolean
+  input?: string[]
+}
+
+export interface ScopedModel {
+  model: ModelRef
+  thinkingLevel?: string
+}
+
+export interface ExtensionContext {
+  mode: 'tui' | 'rpc' | 'json' | 'print'
+  hasUI: boolean
+  model?: ModelRef
+  scopedModels: readonly ScopedModel[]
+  isIdle(): boolean
+  hasPendingMessages(): boolean
+  abort(): void
+  signal?: AbortSignal
+  modelRegistry: {
+    refresh(): Promise<unknown>
+    getAvailable(): ModelRef[]
+  }
+  ui: {
+    theme?: { fg(kind: string, text: string): string }
+    notify(message: string, type?: 'info' | 'warning' | 'error'): void
+    setStatus(key: string, text: string | undefined): void
+    setWorkingMessage(message?: string): void
+    select?(title: string, options: string[]): Promise<string | undefined>
+    confirm?(title: string, message: string): Promise<boolean>
+  }
+}
+
+export interface ExtensionAPI {
+  on(event: string, handler: (event: any, ctx: ExtensionContext) => unknown): void
+  registerCommand(name: string, options: {
+    description: string
+    handler: (args: string, ctx: ExtensionContext) => Promise<void> | void
+  }): void
+  sendUserMessage(content: string | Array<Record<string, unknown>>): void
+  setModel(model: ModelRef): Promise<boolean>
+  setThinkingLevel?(level: string): void
+}
+
+export type FailureClass =
+  | 'auth'
+  | 'quota'
+  | 'rate_limit'
+  | 'endpoint'
+  | 'timeout'
+  | 'model_config'
+  | 'content_policy'
+  | 'context_overflow'
+  | 'unknown'
+
+export type HealthScope = 'model' | 'provider' | 'endpoint'
+
+export interface FailureObservation {
+  message?: string
+  status?: number
+  retryAfterMs?: number
+  watchdog?: boolean
+  aborted?: boolean
+  rawStopReason?: string
+}