pi-ccswitch-auto-switch 0.2.0 → 0.3.0

package/README.md

@@ -21,6 +21,7 @@ The extension observes real Pi requests, records sanitized health signals, and
 - 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.
+- `pi-ccswitch-run` keeps one headless Pi RPC session alive and returns only the final successful answer after automatic model failover.
 
 ## Requirements
 
@@ -46,6 +47,18 @@ Restart Pi or run `/reload` after installing or updating. To update the Git inst
 
 CC Switch should be configured normally. This extension deliberately does not write Pi model settings or CC Switch data.
 
+### Headless / automation use
+
+Install the package as an npm dependency, then run its binary (or invoke the packaged `runner.mjs` with Node):
+
+```bash
+pi-ccswitch-run --no-tools --no-context-files @prompt.md "Summarize the attached text"
+```
+
+The runner starts one `pi --mode rpc --no-session --no-extensions --extension <this package>/index.ts` process, so only CCSwitch is loaded. `PI_BIN` may point to the real Pi executable; it must not point to `pi-ccswitch-run`. The default deadline is ten minutes and can be changed with `--timeout-ms`.
+
+Exit codes are `0` for success, `1` when candidates are exhausted, `2` for invocation/RPC configuration failures, `124` for timeout, and `130`/`143` for interruption. Text `@files` are supported in the first release; images and stdin input are intentionally not.
+
 ## Commands
 
 | Command | What it does |
@@ -81,7 +94,7 @@ CCS ✓70/131 · ⏳61 · ⛔0 · 🔄3 · provider/model-id
 
 四个状态（健康/冷却/禁用/切换）即使为 0 也始终显示，便于确认扩展处于监控中。All-healthy still shows zero counters, e.g. `CCS ✓131/131 · ⏳0 · ⛔0 · 🔄0 · provider/model-id`. Use `/ccswitch` or `/ccswitch-test` to see Pi's raw scope entry count, the deduplicated model count, affected model counts, and the underlying breaker-record count.
 
-切换成功后扩展还会通过 `appendEntry` 向会话注入一条 `ccswitch-switch` custom entry（不参与 LLM 上下文），触发 TUI 底栏重绘——这样 Pi 右下角的模型名显示也会同步为切换后的模型。
+切换成功后扩展还会通过 `appendEntry` 向会话注入一条 `ccswitch-switch` custom entry（不参与 LLM 上下文），触发 TUI 底栏重绘——这样 Pi 右下角的模型名显示也会同步为切换后的模型。RPC 模式还会发出协议版本为 `1` 的 `ccswitch-complete` 或 `ccswitch-exhausted` 终态 entry；runner 用它们区分中间失败轮和最终结果。
 
 ## Failover behavior
 

package/README.zh-CN.md

@@ -19,6 +19,7 @@
 - 原子持久化状态、错误脱敏和有上限的日志。
 - Pi 紧凑状态栏与健康管理面板。
 - `--print` / JSON 非交互运行只监控和记录，不会注入可能与进程退出竞争的新请求。
+- `pi-ccswitch-run` 使用单个 Pi RPC 会话完成无头自动故障转移，只输出最终成功模型的回答。
 
 ## 要求
 
@@ -42,6 +43,16 @@ pi install npm:pi-ccswitch-auto-switch
 
 安装或更新后重启 Pi，或执行 `/reload`。后续更新 Git 版本可执行 `pi update --extensions`。
 
+### 无头自动化调用
+
+将本包作为 npm 依赖安装后，可调用：
+
+```bash
+pi-ccswitch-run --no-tools --no-context-files @prompt.md "请总结附件"
+```
+
+runner 内部只显式加载本扩展并启动一次 Pi RPC；`PI_BIN` 只能指定内部真实 `pi`，不能指向 runner。默认总超时为 10 分钟，可用 `--timeout-ms` 调整。退出码：成功 `0`、候选耗尽 `1`、参数/RPC 配置错误 `2`、超时 `124`、中断 `130/143`。首版只支持文本 `@文件`，不支持图片和 stdin。
+
 正常使用 CC Switch 配置 Provider 即可；本插件不会修改 Pi 模型设置或 CC Switch 数据。
 
 ## 命令
@@ -71,7 +82,7 @@ CCS ✓70/131 · ⏳61 · ⛔0 · 🔄3 · provider/model-id
 
 四个状态（健康/冷却/禁用/切换）即使为 0 也始终显示，便于确认扩展处于监控中；全部健康时仍显示零计数，例如 `CCS ✓131/131 · ⏳0 · ⛔0 · 🔄0 · provider/model-id`。通过 `/ccswitch` 或 `/ccswitch-test` 可同时查看 Pi 原始 scope 条目数、去重模型数、受影响模型数、底层熔断记录数、本 session 切换数与累计切换数。
 
-切换成功后扩展还会通过 `appendEntry` 向会话注入一条 `ccswitch-switch` custom entry（不参与 LLM 上下文），触发 TUI 底栏重绘——这样 Pi 右下角的模型名显示也会同步为切换后的模型。
+切换成功后扩展还会通过 `appendEntry` 向会话注入一条 `ccswitch-switch` custom entry（不参与 LLM 上下文），触发 TUI 底栏重绘——这样 Pi 右下角的模型名显示也会同步为切换后的模型。RPC 模式还会发出协议版本为 `1` 的 `ccswitch-complete` 或 `ccswitch-exhausted` 终态 entry，供 runner 判定最终结果。
 
 ## 故障转移逻辑
 

package/index.ts

@@ -7,6 +7,7 @@ const FIRST_RESPONSE_TIMEOUT = 90_000
 const STREAM_IDLE_TIMEOUT = 120_000
 const MAX_ATTEMPTS = 5
 const ROUND_LIMIT = 8 * 60_000
+const RPC_PROTOCOL_VERSION = 1
 // 同端点（BaseURL 相同）连续失败达到该次数即隔离该端点，避免同一个平台的多个模型逐个试错耗尽本轮切换
 const ENDPOINT_FAIL_THRESHOLD = 3
 
@@ -156,6 +157,23 @@ export default function (pi: ExtensionAPI) {
     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(',')}`)
+    // RPC runner relies on an explicit terminal signal instead of guessing from
+    // agent_settled. Keep this RPC-only so ordinary TUI transcripts stay quiet.
+    if (ctx.mode === 'rpc') {
+      const lastFailure = round.observation ? classifyFailure(round.observation).kind : undefined
+      try {
+        pi.appendEntry?.('ccswitch-exhausted', {
+          protocolVersion: RPC_PROTOCOL_VERSION,
+          roundId: round.id,
+          reason,
+          lastFailure,
+          model: key(round.model),
+          attempts: round.attempts,
+          tried: [...round.tried],
+          sessionSwitches,
+        })
+      } catch { /* reporting must not prevent the regular exhausted path */ }
+    }
     notify(ctx, `CCSwitch：自动切换停止（${reason}），请用 /ccswitch 查看详情`, 'error')
     status(ctx)
   }
@@ -223,7 +241,15 @@ export default function (pi: ExtensionAPI) {
       // interactive-mode 收到后执行 footer.invalidate() + requestRender()，footer 从 session.state.model 重新读取，
       // 从而让右下角模型名同步显示新模型（setModel 只改 state，不直接触发 footer 刷新）。
       try {
-        pi.appendEntry?.('ccswitch-switch', { from: fromKey ?? '', to: modelKey(next), reason: classification.kind, sessionSwitches })
+        pi.appendEntry?.('ccswitch-switch', {
+          protocolVersion: RPC_PROTOCOL_VERSION,
+          roundId: round.id,
+          from: fromKey ?? '',
+          to: modelKey(next),
+          reason: classification.kind,
+          attempts: round.attempts,
+          sessionSwitches,
+        })
       } catch { /* appendEntry 失败不影响切换 */ }
       const continuation = round.hadTool || round.hadOutput
         ? '请从当前会话状态继续完成上一条请求；不要重复已经完成的工具操作。'
@@ -281,6 +307,20 @@ export default function (pi: ExtensionAPI) {
     } else {
       health.recordSuccess(round.model); await health.flush()
       round.phase = 'idle'; round.observation = undefined; ctx.ui.setWorkingMessage(); status(ctx)
+      // agent_settled is also emitted after intermediate failed turns. An
+      // explicit terminal entry lets the headless RPC runner return only after
+      // this final successful assistant turn has settled.
+      if (ctx.mode === 'rpc') {
+        try {
+          pi.appendEntry?.('ccswitch-complete', {
+            protocolVersion: RPC_PROTOCOL_VERSION,
+            roundId: round.id,
+            model: key(round.model),
+            attempts: round.attempts,
+            sessionSwitches,
+          })
+        } catch { /* completion reporting is best-effort */ }
+      }
     }
   })
   pi.on('agent_settled', async (_event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ccswitch-auto-switch",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Provider-first automatic model failover extension for Pi and CC Switch",
   "license": "MIT",
   "keywords": [
@@ -20,11 +20,15 @@
   "homepage": "https://github.com/JunyWuuuu91/pi-ccswitch-auto-switch#readme",
   "files": [
     "index.ts",
+    "runner.mjs",
     "types.ts",
     "classify.ts",
     "candidates.ts",
     "health.ts"
   ],
+  "bin": {
+    "pi-ccswitch-run": "./runner.mjs"
+  },
   "pi": {
     "extensions": [
       "./index.ts"
@@ -35,7 +39,7 @@
     "node": ">=22.19.0"
   },
   "scripts": {
-    "test": "node --test test/*.test.ts",
+    "test": "node --test test/*.test.ts test/*.test.mjs",
     "typecheck": "tsc --noEmit --allowImportingTsExtensions --module nodenext --moduleResolution nodenext --target es2022 --skipLibCheck *.ts"
   },
   "devDependencies": {

package/runner.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * Headless Pi runner that keeps one RPC session alive while the CCSwitch
+ * extension retries a failed turn on another model.
+ */
+import { spawn } from 'node:child_process'
+import { access, readFile, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { basename, delimiter, dirname, extname, isAbsolute, join, resolve } from 'node:path'
+
+export const EXIT = Object.freeze({ SUCCESS: 0, EXHAUSTED: 1, CONFIG: 2, TIMEOUT: 124, INTERRUPTED: 130, TERMINATED: 143 })
+export const DEFAULT_TIMEOUT_MS = 600_000
+
+const usage = `Usage: pi-ccswitch-run [options] [--] [@text-file ...] <prompt>
+
+Options:
+  --timeout-ms <ms>       Total runner timeout (default: ${DEFAULT_TIMEOUT_MS})
+  --no-tools              Disable Pi tools
+  --no-context-files      Disable AGENTS.md / CLAUDE.md discovery
+  --provider <name>       Initial Pi provider
+  --model <name>          Initial Pi model
+  --thinking <level>      Initial Pi thinking level
+  --models <patterns>     Limit the failover candidate scope
+  -p, --print             Accepted for migration compatibility
+  --no-session            Accepted; sessions are always ephemeral
+  --no-extensions         Accepted; external discovery is always disabled
+  -h, --help              Show this help`
+
+const passthroughWithValue = new Set(['--provider', '--model', '--thinking', '--models'])
+const acceptedNoops = new Set(['-p', '--print', '--no-session', '--no-extensions'])
+
+export function parseArgs(argv) {
+  const piArgs = []
+  const files = []
+  const prompt = []
+  let timeoutMs = DEFAULT_TIMEOUT_MS
+  let positional = false
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--') { positional = true; continue }
+    if (!positional && (arg === '-h' || arg === '--help')) return { help: true }
+    if (!positional && arg === '--timeout-ms') {
+      const raw = argv[++index]
+      const value = Number(raw)
+      if (!Number.isSafeInteger(value) || value <= 0) throw new Error('--timeout-ms must be a positive integer')
+      timeoutMs = value
+      continue
+    }
+    if (!positional && (arg === '--no-tools' || arg === '--no-context-files')) { piArgs.push(arg); continue }
+    if (!positional && passthroughWithValue.has(arg)) {
+      const value = argv[++index]
+      if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`)
+      piArgs.push(arg, value)
+      continue
+    }
+    if (!positional && acceptedNoops.has(arg)) continue
+    if (!positional && arg.startsWith('-')) throw new Error(`unsupported option: ${arg}`)
+    if (!positional && arg.startsWith('@')) {
+      if (arg.length === 1) throw new Error('@file requires a path')
+      files.push(arg.slice(1))
+      continue
+    }
+    prompt.push(arg)
+  }
+  if (prompt.length === 0) throw new Error('a prompt is required')
+  return { timeoutMs, piArgs, files, prompt: prompt.join(' ') }
+}
+
+export async function readTextFiles(fileArgs, cwd = process.cwd()) {
+  let text = ''
+  for (const raw of fileArgs) {
+    const path = resolve(cwd, raw)
+    try { await access(path) } catch { throw new Error(`file not found: ${path}`) }
+    const info = await stat(path)
+    if (!info.isFile()) throw new Error(`not a regular text file: ${path}`)
+    if (info.size === 0) continue
+    let content
+    try { content = await readFile(path, 'utf8') } catch { throw new Error(`not a UTF-8 text file: ${path}`) }
+    if (content.includes('\0')) throw new Error(`binary files are not supported: ${path}`)
+    text += `<file name="${path}">\n${content.replace(/^\uFEFF/, '')}\n</file>\n`
+  }
+  return text
+}
+
+export function buildMessage(fileText, prompt) {
+  return fileText ? `${fileText}\n${prompt}` : prompt
+}
+
+function validPiBinary(value) {
+  const normalized = basename(value).toLowerCase().replace(/\.(cmd|exe|bat)$/, '')
+  return normalized === 'pi'
+}
+
+async function resolveWindowsShim(command) {
+  const candidates = []
+  if (isAbsolute(command) || command.includes('\\') || command.includes('/')) candidates.push(command)
+  else {
+    for (const dir of (process.env.PATH || '').split(delimiter).filter(Boolean)) {
+      candidates.push(join(dir, command))
+      if (!/\.(cmd|bat)$/i.test(command)) candidates.push(join(dir, `${command}.cmd`))
+    }
+  }
+  for (const candidate of candidates) {
+    if (!existsSync(candidate) || !/\.(cmd|bat)$/i.test(candidate)) continue
+    const source = await readFile(candidate, 'utf8').catch(() => '')
+    const match = source.match(/["']([^"']+\.js)["']/i)
+    if (!match) continue
+    const target = match[1].replace(/%~dp0/ig, `${dirname(candidate)}\\`)
+    const entry = resolve(target.replace(/\\/g, '/'))
+    if (existsSync(entry)) return { command: process.execPath, prefix: [entry] }
+  }
+  return { command, prefix: [] }
+}
+
+async function resolvePiCommand() {
+  const configured = String(process.env.PI_BIN || '').trim()
+  if (configured && !validPiBinary(configured)) throw new Error('PI_BIN must name the real pi executable, not an arbitrary command')
+  const command = configured || 'pi'
+  if (process.platform === 'win32') return resolveWindowsShim(command)
+  return { command, prefix: [] }
+}
+
+function terminateTree(child, signal = 'SIGTERM') {
+  if (!child || child.exitCode !== null) return
+  if (process.platform === 'win32' && child.pid) {
+    const killer = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true })
+    killer.on('error', () => { try { child.kill('SIGKILL') } catch {} })
+    return
+  }
+  try { child.kill(signal) } catch {}
+  setTimeout(() => { try { child.kill('SIGKILL') } catch {} }, 1_000).unref()
+}
+
+function customEntry(event) {
+  if (event?.type !== 'entry_appended' || event.entry?.type !== 'custom') return undefined
+  return { type: event.entry.customType, data: event.entry.data || {} }
+}
+
+export async function run(options, runtime = {}) {
+  const spawnImpl = runtime.spawn || spawn
+  const extensionPath = runtime.extensionPath || fileURLToPath(new URL('./index.ts', import.meta.url))
+  const resolvePi = runtime.resolvePiCommand || resolvePiCommand
+  const log = runtime.log || ((message) => process.stderr.write(`[ccswitch] ${message}\n`))
+  const resolved = await resolvePi()
+  const args = [...resolved.prefix, '--mode', 'rpc', '--no-session', '--no-extensions', '--extension', extensionPath, ...options.piArgs]
+  const child = spawnImpl(resolved.command, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, env: process.env })
+  let buffer = ''
+  let closed = false
+  let terminal
+  let retryPending = false
+  let protocolError
+  let nextId = 1
+  const pending = new Map()
+  const closeStdin = () => { try { child.stdin?.end() } catch {} }
+  const request = (type, payload = {}) => new Promise((resolveRequest, rejectRequest) => {
+    const id = String(nextId++)
+    pending.set(id, { resolve: resolveRequest, reject: rejectRequest })
+    try { child.stdin.write(`${JSON.stringify({ id, type, ...payload })}\n`) } catch (error) { pending.delete(id); rejectRequest(error) }
+  })
+  const failPending = (error) => {
+    for (const item of pending.values()) item.reject(error)
+    pending.clear()
+  }
+  const handleEvent = (event) => {
+    if (event?.type === 'extension_error') { protocolError = `extension error: ${event.error}`; return }
+    if (event?.type === 'turn_start') retryPending = false
+    const entry = customEntry(event)
+    if (!entry) {
+      if (event?.type === 'agent_settled' && !terminal && !retryPending) {
+        protocolError = 'Pi settled without a CCSwitch terminal event'
+      }
+      return
+    }
+    if (entry.data?.protocolVersion !== 1) return
+    if (entry.type === 'ccswitch-switch') {
+      retryPending = true
+      log(`switch ${entry.data.from || '?'} → ${entry.data.to || '?'} (${entry.data.attempts ?? '?'}/5)`)
+    } else if (entry.type === 'ccswitch-complete') {
+      terminal = { kind: 'complete', data: entry.data }
+    } else if (entry.type === 'ccswitch-exhausted') {
+      terminal = { kind: 'exhausted', data: entry.data }
+    }
+  }
+  const processLine = (line) => {
+    if (!line.trim()) return
+    let event
+    try { event = JSON.parse(line) } catch { protocolError = 'Pi RPC emitted malformed JSONL'; return }
+    if (event?.type === 'response' && event.id !== undefined) {
+      const item = pending.get(String(event.id))
+      if (item) {
+        pending.delete(String(event.id))
+        if (event.success) item.resolve(event.data)
+        else item.reject(new Error(event.error || `${event.command || 'RPC'} failed`))
+      }
+      return
+    }
+    handleEvent(event)
+  }
+  child.stdout?.setEncoding('utf8')
+  child.stdout?.on('data', (chunk) => {
+    buffer += chunk
+    let newline
+    while ((newline = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newline)
+      buffer = buffer.slice(newline + 1)
+      processLine(line)
+    }
+  })
+  child.stderr?.on('data', () => {})
+  const exit = new Promise((resolveExit, rejectExit) => {
+    child.once('error', rejectExit)
+    child.once('close', (code, signal) => { closed = true; resolveExit({ code, signal }) })
+  })
+  const timeout = setTimeout(() => { protocolError = 'runner timed out'; terminateTree(child) }, options.timeoutMs)
+  timeout.unref?.()
+  const onSignal = (signal, code) => {
+    protocolError = signal
+    terminateTree(child, signal)
+    process.exitCode = code
+  }
+  const onSigint = () => onSignal('SIGINT', EXIT.INTERRUPTED)
+  const onSigterm = () => onSignal('SIGTERM', EXIT.TERMINATED)
+  process.once('SIGINT', onSigint)
+  process.once('SIGTERM', onSigterm)
+  try {
+    const commands = await request('get_commands')
+    if (!Array.isArray(commands?.commands) || !commands.commands.some((entry) => entry.name === 'ccswitch')) {
+      throw new Error('CCSwitch extension did not load')
+    }
+    await request('prompt', { message: options.message })
+    while (!terminal && !protocolError && !closed) await new Promise(resolveWait => setTimeout(resolveWait, 10))
+    if (protocolError) {
+      closeStdin()
+      await exit.catch(() => {})
+      if (protocolError === 'runner timed out') return { code: EXIT.TIMEOUT, error: protocolError }
+      if (protocolError === 'SIGINT') return { code: EXIT.INTERRUPTED, error: protocolError }
+      if (protocolError === 'SIGTERM') return { code: EXIT.TERMINATED, error: protocolError }
+      return { code: EXIT.CONFIG, error: protocolError }
+    }
+    if (!terminal) return { code: EXIT.CONFIG, error: 'Pi exited before CCSwitch reached a terminal state' }
+    if (terminal.kind === 'exhausted') {
+      closeStdin()
+      await exit.catch(() => {})
+      return { code: EXIT.EXHAUSTED, error: terminal.data.reason || 'all candidate models were exhausted' }
+    }
+    const last = await request('get_last_assistant_text')
+    const text = String(last?.text || '').trim()
+    closeStdin()
+    await exit.catch(() => {})
+    if (!text) return { code: EXIT.CONFIG, error: 'CCSwitch completed but Pi returned no assistant text' }
+    return { code: EXIT.SUCCESS, text }
+  } catch (error) {
+    terminateTree(child)
+    closeStdin()
+    await exit.catch(() => {})
+    return { code: EXIT.CONFIG, error: error instanceof Error ? error.message : String(error) }
+  } finally {
+    clearTimeout(timeout)
+    process.off('SIGINT', onSigint)
+    process.off('SIGTERM', onSigterm)
+    if (!closed) { failPending(new Error('runner stopped')); terminateTree(child) }
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  let options
+  try { options = parseArgs(argv) } catch (error) { process.stderr.write(`pi-ccswitch-run: ${error.message}\n${usage}\n`); return EXIT.CONFIG }
+  if (options.help) { process.stdout.write(`${usage}\n`); return EXIT.SUCCESS }
+  try {
+    const fileText = await readTextFiles(options.files)
+    const result = await run({ ...options, message: buildMessage(fileText, options.prompt) })
+    if (result.text) process.stdout.write(`${result.text}\n`)
+    if (result.error) process.stderr.write(`pi-ccswitch-run: ${result.error}\n`)
+    return result.code
+  } catch (error) {
+    process.stderr.write(`pi-ccswitch-run: ${error instanceof Error ? error.message : String(error)}\n`)
+    return EXIT.CONFIG
+  }
+}
+
+const invoked = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (invoked) main().then(code => { process.exitCode = code })