opencode-plugin-quota-resume 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-plugin-quota-resume contributors
+
+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

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# opencode-plugin-quota-resume
 
-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.
+OpenCode **v2** 插件：当会话因第三方订阅（token plan）的额度/限流（HTTP 429 等）而**彻底失败**（内置重试耗尽）后，自动等待到下一个额度窗口（默认 5 小时）边界，然后向**同一个会话、同一个订阅模型**重新提交一条“继续”prompt，实现“自动重试直到额度恢复”。
+
+## 工作原理
+
+1. 订阅 `session.execution.failed` 事件——这是内置重试全部耗尽后的终态失败，不受单次请求重试次数硬上限的约束；
+2. 判断失败原因是否为限流/额度耗尽：HTTP 状态码匹配（默认 `429`）或错误信息正则匹配（默认包含 `rate limit / too many requests / quota / extra usage / balance has run out / insufficient balance / 额度 / 限流 / 余额不足` 等，覆盖 Kimi `Extra Usage balance has run out`、OpenAI `insufficient_quota` 等常见文案）；
+3. 计算到下一个额度窗口边界的等待时间（`窗口 - (now - 锚点) % 窗口 + 缓冲`）；
+4. 定时器到期后调用 `ctx.session.prompt` 自动重新提交，继续执行；
+5. 若用户在等待期间手动继续任务，定时器自动取消。
+
+## 保护机制
+
+- 每个会话同时最多挂起一个恢复定时器；
+- 每会话自动恢复次数上限（默认 12 次），防止额度长期不恢复时的无限循环；
+- 等待时长下限（默认 60s），避免窗口对齐结果过小时高频请求；
+- 插件卸载/服务停止时清理全部定时器。
+
+## 安装
+
+### 方式一：npm 发布包（推荐）
+
+```bash
+opencode plugin add opencode-plugin-quota-resume
+```
+
+或在 `opencode.json(c)` 中配置：
+
+```jsonc
+{
+  "plugins": ["opencode-plugin-quota-resume"],
+}
+```
+
+### 方式二：本地目录
+
+```jsonc
+{
+  "plugins": ["../path/to/opencode-plugin-quota-resume"],
+}
+```
+
+### 方式三：开发调试
+
+把本仓库放到任意 `.opencode/plugins/` 目录下会自动加载（无需改配置）：
+
+```text
+<project>/.opencode/plugins/opencode-plugin-quota-resume/
+```
+
+## 配置（均为可选）
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "opencode-plugin-quota-resume",
+      "options": {
+        "windowHours": 5, // 订阅额度窗口长度（小时）
+        "windowEpoch": "2026-01-01T00:00:00.000Z", // 窗口对齐锚点（ISO 时间）
+        "bufferSeconds": 30, // 窗口边界后的额外缓冲（秒）
+        "minDelaySeconds": 60, // 等待时长下限（秒）
+        "resumeText": "继续上一个任务", // 恢复时自动发送的 prompt
+        "maxResumesPerSession": 12, // 每会话自动恢复次数上限
+        "statusCodes": [429], // 视为限流的 HTTP 状态码
+        "messagePatterns": ["rate.?limit", "too many requests", "quota", "extra usage", "balance has run out", "insufficient balance", "额度", "限流", "余额不足"] // 错误信息正则
+      }
+    }
+  ]
+}
+```
+
+> `windowEpoch` 的作用：把等待时间对齐到服务商额度窗口的整点边界。如果你的 5 小时窗口是从首次请求或固定时刻滚动开始，把锚点设为该时刻即可；不确定时保持默认即可，等待上限就是一个窗口长度。
+
+## 日志
+
+插件运行日志（`[quota-resume]` 前缀）写入 OpenCode 服务端日志，可用 `opencode debug paths log` 查看日志路径。
+
+## 已知限制
+
+- 定时器保存在内存中，OpenCode 服务端重启后未触发的恢复任务会丢失（失败消息仍保留在会话里，手动继续即可）；
+- 恢复时发送的是**新的 prompt**，而不是从断点无损续传——模型会看到之前的完整会话历史（含失败信息），对于“继续上一个任务”这类指令通常足够。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+## 发布
+
+```bash
+npm publish
+```
+
+`prepublishOnly` 会自动执行类型检查和测试。

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "opencode-plugin-quota-resume",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "OpenCode v2 plugin: when a session dies on a provider rate/quota limit (HTTP 429 etc.), wait until the plan's quota window resets, then automatically re-prompt the session to continue on the same subscription model.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "rate-limit",
+    "quota",
+    "429",
+    "retry"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@opencode/plugin": "latest",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,263 @@
+import { Plugin } from "@opencode/plugin"
+
+/**
+ * opencode-plugin-quota-resume
+ *
+ * 方案二（事件驱动）：
+ *   1. 订阅 `session.execution.failed` —— 内置重试全部耗尽后的终态失败；
+ *   2. 失败原因是限流/额度耗尽（HTTP 429 或错误信息匹配）时，
+ *      计算到下一个订阅额度窗口（默认 5 小时）边界的等待时间；
+ *   3. 定时器到期后向同一个会话重新提交一条“继续”prompt，
+ *      从而在“同一个订阅模型”上自动恢复，直到额度恢复为止。
+ *
+ * 保护机制：
+ *   - 每个会话同时最多挂起一个恢复定时器；
+ *   - 若用户在等待期间手动继续（会话重新进入执行），自动取消定时器；
+ *   - 每个会话的自动恢复次数有上限（默认 12 次），防止无限循环；
+ *   - 等待时长有下限（默认 60s），窗口对齐结果过小时不会高频轰炸服务端。
+ */
+
+const LOG_PREFIX = "[quota-resume]"
+
+// ---------------------------------------------------------------------------
+// 纯函数工具（独立导出以便测试）
+// ---------------------------------------------------------------------------
+
+export interface QuotaResumeOptions {
+  /** 订阅额度窗口长度（小时），默认 5 */
+  windowHours: number
+  /** 额度窗口的对齐锚点（epoch 毫秒），默认 2026-01-01T00:00:00Z */
+  windowEpochMs: number
+  /** 窗口边界后的额外缓冲（毫秒），默认 30s */
+  bufferMs: number
+  /** 等待时长下限（毫秒），默认 60s */
+  minDelayMs: number
+  /** 恢复执行时自动发送的 prompt 文本 */
+  resumeText: string
+  /** 每个会话最多自动恢复次数，默认 12 */
+  maxResumesPerSession: number
+  /** 视为限流的 HTTP 状态码 */
+  statusCodes: number[]
+  /** 视为限流的错误信息正则（匹配 type + message，忽略大小写） */
+  messagePatterns: RegExp[]
+}
+
+const DEFAULT_MESSAGE_PATTERN_SOURCES = [
+  "rate.?limit",
+  "too many requests",
+  "resource exhausted",
+  "quota",
+  "extra usage",
+  "balance has run out",
+  "insufficient balance",
+  "insufficient_quota",
+  "out of credits",
+  "额度",
+  "限流",
+  "余额不足",
+  "余额耗尽",
+  "欠费",
+]
+
+const DEFAULTS = {
+  windowHours: 5,
+  windowEpoch: "2026-01-01T00:00:00.000Z",
+  bufferSeconds: 30,
+  minDelaySeconds: 60,
+  resumeText: "继续上一个任务",
+  maxResumesPerSession: 12,
+  statusCodes: [429],
+  messagePatterns: DEFAULT_MESSAGE_PATTERN_SOURCES,
+} as const
+
+function asNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback
+}
+
+function asString(value: unknown, fallback: string): string {
+  return typeof value === "string" && value.trim() !== "" ? value : fallback
+}
+
+function asNumberArray(value: unknown, fallback: number[]): number[] {
+  if (!Array.isArray(value)) return fallback
+  const result = value.filter((v): v is number => typeof v === "number" && Number.isFinite(v))
+  return result.length > 0 ? result : fallback
+}
+
+function asPatternArray(value: unknown, fallback: string[]): RegExp[] {
+  const sources = Array.isArray(value)
+    ? value.filter((v): v is string => typeof v === "string" && v.trim() !== "")
+    : fallback
+  const patterns: RegExp[] = []
+  for (const source of sources) {
+    try {
+      patterns.push(new RegExp(source, "i"))
+    } catch {
+      // 忽略无效正则，使用默认兜底
+    }
+  }
+  return patterns.length > 0 ? patterns : fallback.map((s) => new RegExp(s, "i"))
+}
+
+/** 解析插件配置（来自 opencode.json 的 plugins 数组选项），带安全兜底 */
+export function resolveOptions(raw: unknown): QuotaResumeOptions {
+  const opts = (raw ?? {}) as Record<string, unknown>
+  const epochDate = Date.parse(asString(opts.windowEpoch, DEFAULTS.windowEpoch))
+  return {
+    windowHours: asNumber(opts.windowHours, DEFAULTS.windowHours),
+    windowEpochMs: Number.isNaN(epochDate) ? Date.parse(DEFAULTS.windowEpoch) : epochDate,
+    bufferMs: asNumber(opts.bufferSeconds, DEFAULTS.bufferSeconds) * 1000,
+    minDelayMs: asNumber(opts.minDelaySeconds, DEFAULTS.minDelaySeconds) * 1000,
+    resumeText: asString(opts.resumeText, DEFAULTS.resumeText),
+    maxResumesPerSession: Math.max(1, Math.floor(asNumber(opts.maxResumesPerSession, DEFAULTS.maxResumesPerSession))),
+    statusCodes: asNumberArray(opts.statusCodes, [...DEFAULTS.statusCodes]),
+    messagePatterns: asPatternArray(opts.messagePatterns, [...DEFAULTS.messagePatterns]),
+  }
+}
+
+/**
+ * 计算到下一个额度窗口边界的等待毫秒数。
+ *  - remainder = (now - epoch) % window
+ *  - remainder 很小（< minDelay）说明窗口刚重置，只等 minDelay；
+ *  - 否则等待 remainder + buffer（缓冲服务端计数刷新延迟）。
+ */
+export function nextWindowDelay(
+  nowMs: number,
+  windowMs: number,
+  epochMs: number,
+  bufferMs: number,
+  minDelayMs: number,
+): number {
+  if (windowMs <= 0) return minDelayMs
+  const remainder = ((nowMs - epochMs) % windowMs + windowMs) % windowMs
+  if (remainder < minDelayMs) return minDelayMs
+  return windowMs - remainder + bufferMs
+}
+
+export interface ProviderErrorLike {
+  status?: number
+  type?: string
+  message?: string
+}
+
+/** 判断一次失败是否应视为“额度/限流” */
+export function matchesQuotaError(error: ProviderErrorLike | undefined, options: QuotaResumeOptions): boolean {
+  if (!error) return false
+  if (error.status !== undefined && options.statusCodes.includes(error.status)) return true
+  const haystack = `${error.type ?? ""} ${error.message ?? ""}`.toLowerCase()
+  return options.messagePatterns.some((pattern) => pattern.test(haystack))
+}
+
+// ---------------------------------------------------------------------------
+// 事件载荷提取（不同版本字段位置可能不同，做防御式提取）
+// ---------------------------------------------------------------------------
+
+function extractError(payload: unknown): ProviderErrorLike | undefined {
+  const p = payload as Record<string, unknown> | undefined
+  const candidates = [p?.error, (p?.durable as Record<string, unknown> | undefined)?.error]
+  for (const candidate of candidates) {
+    if (candidate && typeof candidate === "object") return candidate as ProviderErrorLike
+  }
+  return undefined
+}
+
+function extractSessionID(payload: unknown): string | undefined {
+  const p = payload as Record<string, unknown> | undefined
+  const durable = p?.durable as Record<string, unknown> | undefined
+  const candidates = [p?.sessionID, durable?.sessionID]
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate !== "") return candidate
+  }
+  return undefined
+}
+
+// ---------------------------------------------------------------------------
+// 插件主体
+// ---------------------------------------------------------------------------
+
+export default Plugin.define({
+  id: "quota-resume",
+  async setup(ctx) {
+    const options = resolveOptions(ctx.options)
+    const windowMs = options.windowHours * 60 * 60 * 1000
+
+    /** sessionID -> 挂起中的恢复定时器 */
+    const pending = new Map<string, ReturnType<typeof setTimeout>>()
+    /** sessionID -> 已自动恢复次数 */
+    const resumeCounts = new Map<string, number>()
+
+    const cancelPending = (sessionID: string, reason: string) => {
+      const timer = pending.get(sessionID)
+      if (timer === undefined) return
+      clearTimeout(timer)
+      pending.delete(sessionID)
+      console.log(`${LOG_PREFIX} session ${sessionID} 的自动恢复已取消（${reason}）`)
+    }
+
+    const controller = new AbortController()
+    void (async () => {
+      for await (const event of ctx.event.subscribe({
+        types: [
+          "session.execution.failed",
+          "session.execution.started",
+          "session.execution.succeeded",
+          "session.execution.interrupted",
+        ],
+        signal: controller.signal,
+      })) {
+        const sessionID = extractSessionID(event)
+        if (!sessionID) continue
+
+        // 会话重新进入执行（用户手动继续 / 其他来源）→ 取消挂起的自动恢复
+        if (event.type !== "session.execution.failed") {
+          cancelPending(sessionID, "会话已恢复执行")
+          continue
+        }
+
+        // 仅处理终态失败
+        if (pending.has(sessionID)) continue
+        const error = extractError(event)
+        if (!matchesQuotaError(error, options)) continue
+
+        const count = (resumeCounts.get(sessionID) ?? 0) + 1
+        if (count > options.maxResumesPerSession) {
+          console.warn(
+            `${LOG_PREFIX} session ${sessionID} 自动恢复次数已达上限（${options.maxResumesPerSession}），停止重试。` +
+              `最后一个错误：${error?.message ?? JSON.stringify(error)}`,
+          )
+          continue
+        }
+
+        const delay = nextWindowDelay(Date.now(), windowMs, options.windowEpochMs, options.bufferMs, options.minDelayMs)
+        resumeCounts.set(sessionID, count)
+        console.log(
+          `${LOG_PREFIX} session ${sessionID} 因额度/限流失败（${error?.status ?? error?.type ?? "unknown"}），` +
+            `第 ${count}/${options.maxResumesPerSession} 次自动恢复将于 ${Math.round(delay / 60000)} 分钟后执行`,
+        )
+
+        pending.set(
+          sessionID,
+          setTimeout(() => {
+            pending.delete(sessionID)
+            void ctx.session
+              .prompt({ sessionID, text: options.resumeText })
+              .then(() => console.log(`${LOG_PREFIX} session ${sessionID} 已自动重新提交，继续执行`))
+              .catch((e: unknown) =>
+                console.error(`${LOG_PREFIX} session ${sessionID} 自动重新提交失败：`, e),
+              )
+          }, delay),
+        )
+      }
+    })().catch((e: unknown) => {
+      if ((e as Error)?.name !== "AbortError") console.error(`${LOG_PREFIX} 事件订阅异常：`, e)
+    })
+
+    // 插件卸载时清理
+    return () => {
+      controller.abort()
+      for (const timer of pending.values()) clearTimeout(timer)
+      pending.clear()
+      resumeCounts.clear()
+    }
+  },
+})