@crystalfluxay/opencode-rate-limiter 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# opencode-rate-limit
+
+OpenCode plugin for proactive TPM/RPM rate limiting with multi-provider fallback.
+
+## Features
+
+- **Proactive TPM/RPM limiting** — counts tokens per minute, blocks requests before they hit the API
+- **Reactive error detection** — parses response body against user-configured regex rules
+- **Fuzzy error matching** — `bodyPattern` regex matches any text in the response body
+- **Multi-provider support** — different error rules per provider
+- **Fallback model switching** — auto-switch to backup models when rate limited
+- **Circuit breaker** — auto-disconnect failing models
+- **Smart cooldown** — skip rate-limited models for configurable duration
+- **`/rate-limit-status`** — diagnostic command
+
+## Install
+
+Add to `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-rate-limit"]
+}
+```
+
+## Configure
+
+Create `~/.opencode/rate-limit.json`:
+
+```json
+{
+  "providers": [
+    {
+      "provider": "xfyun",
+      "tpm": 100000,
+      "rpm": 10,
+      "errorDetection": [
+        { "bodyPattern": "11210|TPM.*超限", "category": "tpm", "description": "TPM超限", "waitMs": 60000 },
+        { "bodyPattern": "11201|次数超限", "category": "tpm", "description": "次数超限", "waitMs": 60000 },
+        { "statusPattern": "^429$", "category": "tpm", "description": "HTTP 429", "waitMs": 60000 },
+        { "statusPattern": "^5\\d{2}$", "category": "server_error", "description": "HTTP 5xx" },
+        { "statusPattern": "^401$", "category": "fatal", "description": "HTTP 401" }
+      ]
+    }
+  ],
+  "fallbackModels": [
+    { "providerId": "openai", "modelId": "gpt-4o" }
+  ]
+}
+```
+
+### Error categories
+
+| Category | Behavior |
+|----------|----------|
+| `tpm` | Wait `waitMs` (default 60s), then retry or fallback |
+| `rpm` | Wait `waitMs`, then retry or fallback |
+| `server_error` | Wait `cooldownMs`, retry with backoff |
+| `retryable` | Wait `waitMs`, retry |
+| `fatal` | No retry, propagate error immediately |
+
+### Pattern matching
+
+- `statusPattern` — regex against HTTP status code string (e.g. `"^429$"`, `"^5\\d{2}$"`)
+- `bodyPattern` — regex against full response body (case-insensitive, fuzzy match)
+- Both optional — at least one required per rule
+- When both specified, BOTH must match (AND logic)
+- Rules checked in order, first match wins
+
+### Full config reference
+
+```json
+{
+  "enabled": true,
+  "cooldownMs": 60000,
+  "fallbackMode": "cycle",
+  "fallbackModels": [],
+  "retryPolicy": {
+    "maxRetries": 3,
+    "strategy": "exponential",
+    "baseDelayMs": 1000,
+    "maxDelayMs": 30000,
+    "jitterEnabled": true
+  },
+  "circuitBreaker": {
+    "enabled": true,
+    "failureThreshold": 5,
+    "recoveryTimeoutMs": 60000
+  },
+  "providers": [],
+  "fetchInterception": true,
+  "eventFallback": true,
+  "logLevel": "warn"
+}
+```
+
+## Preset templates
+
+Copy from `src/error-codes.ts`:
+- `XUNFEI_PRESET` — 讯飞星辰 MaaS Astron Coding Plan
+- `OPENAI_PRESET` — Standard OpenAI-compatible providers
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,779 @@
+// src/config.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+var DEFAULT_RETRY_POLICY = {
+  maxRetries: 3,
+  strategy: "exponential",
+  baseDelayMs: 1000,
+  maxDelayMs: 30000,
+  jitterEnabled: true
+};
+var DEFAULT_CIRCUIT_BREAKER = {
+  enabled: true,
+  failureThreshold: 5,
+  recoveryTimeoutMs: 60000
+};
+var DEFAULT_CONFIG = {
+  enabled: true,
+  cooldownMs: 60000,
+  fallbackMode: "cycle",
+  fallbackModels: [],
+  retryPolicy: DEFAULT_RETRY_POLICY,
+  circuitBreaker: DEFAULT_CIRCUIT_BREAKER,
+  providers: [],
+  fetchInterception: true,
+  eventFallback: true,
+  logLevel: "warn"
+};
+function resolveConfigPath(worktree) {
+  const projectPath = worktree ? path.join(worktree, ".opencode", "rate-limit.json") : path.join(process.cwd(), ".opencode", "rate-limit.json");
+  if (fs.existsSync(projectPath)) {
+    return projectPath;
+  }
+  const homePath = path.join(os.homedir(), ".opencode", "rate-limit.json");
+  if (fs.existsSync(homePath)) {
+    return homePath;
+  }
+  return homePath;
+}
+function isObject(item) {
+  return item !== null && typeof item === "object" && !Array.isArray(item);
+}
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const sourceVal = source[key];
+    const targetVal = result[key];
+    if (isObject(sourceVal) && isObject(targetVal)) {
+      result[key] = deepMerge(targetVal, sourceVal);
+    } else if (sourceVal !== undefined) {
+      result[key] = sourceVal;
+    }
+  }
+  return result;
+}
+function validateConfig(config) {
+  const errors = [];
+  if (config.cooldownMs < 0) {
+    errors.push("cooldownMs must be >= 0");
+  }
+  if (config.retryPolicy.maxRetries < 0) {
+    errors.push("retryPolicy.maxRetries must be >= 0");
+  }
+  if (config.retryPolicy.baseDelayMs < 0) {
+    errors.push("retryPolicy.baseDelayMs must be >= 0");
+  }
+  if (config.circuitBreaker.failureThreshold < 1) {
+    errors.push("circuitBreaker.failureThreshold must be >= 1");
+  }
+  for (const p of config.providers) {
+    if (p.tpm !== undefined && p.tpm < 0) {
+      errors.push(`provider "${p.provider}": tpm must be >= 0`);
+    }
+    if (p.rpm !== undefined && p.rpm < 0) {
+      errors.push(`provider "${p.provider}": rpm must be >= 0`);
+    }
+  }
+  for (const fm of config.fallbackModels) {
+    if (!fm.providerId || !fm.modelId) {
+      errors.push(`fallback model: providerId and modelId are required`);
+    }
+  }
+  return errors;
+}
+function loadConfig(worktree) {
+  let userConfig = {};
+  let sourcePath = null;
+  const configPath = resolveConfigPath(worktree);
+  if (fs.existsSync(configPath)) {
+    try {
+      const raw = fs.readFileSync(configPath, "utf-8");
+      userConfig = JSON.parse(raw);
+      sourcePath = configPath;
+    } catch (err) {
+      return {
+        config: DEFAULT_CONFIG,
+        sourcePath: configPath,
+        errors: [`Failed to parse config: ${err instanceof Error ? err.message : String(err)}`]
+      };
+    }
+  }
+  const merged = deepMerge(DEFAULT_CONFIG, userConfig);
+  const errors = validateConfig(merged);
+  return { config: merged, sourcePath, errors };
+}
+function findProviderTPM(config, providerId, modelId) {
+  const exact = config.providers.find((p) => p.provider === providerId && p.model === modelId);
+  if (exact?.tpm !== undefined)
+    return exact.tpm;
+  const provider = config.providers.find((p) => p.provider === providerId && !p.model);
+  if (provider?.tpm !== undefined)
+    return provider.tpm;
+  return 0;
+}
+function findProviderRPM(config, providerId, modelId) {
+  const exact = config.providers.find((p) => p.provider === providerId && p.model === modelId);
+  if (exact?.rpm !== undefined)
+    return exact.rpm;
+  const provider = config.providers.find((p) => p.provider === providerId && !p.model);
+  if (provider?.rpm !== undefined)
+    return provider.rpm;
+  return 0;
+}
+
+// src/token-counter.ts
+var WINDOW_MS = 60000;
+
+class TokenCounter {
+  windows = new Map;
+  rpmCounters = new Map;
+  rpmResetTimers = new Map;
+  record(key, tokens) {
+    const now = Date.now();
+    let entries = this.windows.get(key);
+    if (!entries) {
+      entries = [];
+      this.windows.set(key, entries);
+    }
+    const cutoff = now - WINDOW_MS;
+    entries = entries.filter((e) => e.ts > cutoff);
+    entries.push({ ts: now, tokens });
+    this.windows.set(key, entries);
+  }
+  recordRequest(key) {
+    this.rpmCounters.set(key, (this.rpmCounters.get(key) ?? 0) + 1);
+  }
+  getTPM(key) {
+    const entries = this.windows.get(key);
+    if (!entries)
+      return 0;
+    const cutoff = Date.now() - WINDOW_MS;
+    return entries.filter((e) => e.ts > cutoff).reduce((sum, e) => sum + e.tokens, 0);
+  }
+  getRPM(key) {
+    return this.rpmCounters.get(key) ?? 0;
+  }
+  wouldExceedTPM(key, limit, incomingTokens) {
+    if (limit <= 0)
+      return false;
+    return this.getTPM(key) + incomingTokens > limit;
+  }
+  wouldExceedRPM(key, limit) {
+    if (limit <= 0)
+      return false;
+    return this.getRPM(key) >= limit;
+  }
+  reset() {
+    this.windows.clear();
+    this.rpmCounters.clear();
+  }
+  resetKey(key) {
+    this.windows.delete(key);
+    this.rpmCounters.delete(key);
+  }
+  getKeys() {
+    return [...this.windows.keys()];
+  }
+  startResetTimer() {
+    setInterval(() => {
+      this.rpmCounters.clear();
+    }, WINDOW_MS);
+  }
+  destroy() {
+    for (const timer of this.rpmResetTimers.values()) {
+      clearInterval(timer);
+    }
+    this.rpmResetTimers.clear();
+    this.windows.clear();
+    this.rpmCounters.clear();
+  }
+}
+function parseRateLimitHeaders(headers) {
+  const limitRaw = headers.get("x-ratelimit-limit");
+  const remainingRaw = headers.get("x-ratelimit-remaining");
+  const resetRaw = headers.get("x-ratelimit-reset");
+  if (!limitRaw || !remainingRaw || !resetRaw)
+    return null;
+  const firstValue = (raw) => {
+    const parts = raw.split(",");
+    const trimmed = parts[0]?.trim() ?? "";
+    return parseInt(trimmed, 10);
+  };
+  const limit = firstValue(limitRaw);
+  const remaining = firstValue(remainingRaw);
+  const reset = parseInt(resetRaw.trim(), 10);
+  if (isNaN(limit) || isNaN(remaining) || isNaN(reset))
+    return null;
+  return { limit, remaining, reset };
+}
+var tokenCounter = new TokenCounter;
+
+// src/error-codes.ts
+function matchError(httpStatus, body, rules, defaultCooldownMs) {
+  let bodyCode;
+  let bodyMessage;
+  if (body) {
+    try {
+      const parsed = JSON.parse(body);
+      bodyCode = extractNumericField(parsed, ["code", "error_code", "errorCode", "errCode", "ret"]);
+      bodyMessage = extractStringField(parsed, ["message", "msg", "error", "error_msg", "errorMsg", "errMsg"]);
+      if (!bodyCode && parsed.error && typeof parsed.error === "object") {
+        const err = parsed.error;
+        bodyCode = extractNumericField(err, ["code", "error_code", "errorCode"]);
+        bodyMessage = extractStringField(err, ["message", "msg"]);
+      }
+    } catch {}
+  }
+  for (const rule of rules) {
+    let matches = true;
+    if (rule.httpStatus !== undefined && rule.httpStatus !== httpStatus) {
+      matches = false;
+    }
+    if (rule.bodyCode !== undefined && bodyCode !== undefined) {
+      if (String(rule.bodyCode) !== String(bodyCode)) {
+        matches = false;
+      }
+    } else if (rule.bodyCode !== undefined && bodyCode === undefined) {
+      matches = false;
+    }
+    if (rule.messagePattern && bodyMessage) {
+      try {
+        const regex = new RegExp(rule.messagePattern, "i");
+        if (!regex.test(bodyMessage)) {
+          matches = false;
+        }
+      } catch {
+        matches = false;
+      }
+    }
+    if (matches) {
+      return {
+        matched: true,
+        category: rule.category,
+        description: rule.description,
+        waitMs: rule.waitMs ?? defaultCooldownMs,
+        rule
+      };
+    }
+  }
+  if (httpStatus === 429) {
+    return {
+      matched: true,
+      category: "tpm",
+      description: "HTTP 429 (unmatched by rules, treating as TPM)",
+      waitMs: defaultCooldownMs,
+      rule: null
+    };
+  }
+  if (httpStatus >= 500) {
+    return {
+      matched: true,
+      category: "server_error",
+      description: `HTTP ${httpStatus} (unmatched, treating as server error)`,
+      waitMs: defaultCooldownMs,
+      rule: null
+    };
+  }
+  return { matched: false, category: "fatal", description: "Unknown error", waitMs: 0, rule: null };
+}
+function extractNumericField(obj, keys) {
+  for (const key of keys) {
+    const val = obj[key];
+    if (typeof val === "number")
+      return val;
+    if (typeof val === "string") {
+      const num = parseInt(val, 10);
+      if (!isNaN(num))
+        return num;
+    }
+  }
+  return;
+}
+function extractStringField(obj, keys) {
+  for (const key of keys) {
+    const val = obj[key];
+    if (typeof val === "string")
+      return val;
+  }
+  return;
+}
+
+// src/fetch-wrapper.ts
+var rateLimitStates = new Map;
+function stateKey(pid, mid) {
+  return `${pid}::${mid}`;
+}
+function getState(k) {
+  let s = rateLimitStates.get(k);
+  if (!s) {
+    s = { cooldownUntil: 0, consecutiveFailures: 0, circuitOpen: false, circuitRecoveryAt: 0 };
+    rateLimitStates.set(k, s);
+  }
+  return s;
+}
+function estimateTokens(body) {
+  if (!body)
+    return 0;
+  try {
+    const p = JSON.parse(body);
+    if (Array.isArray(p.messages)) {
+      let c = 0;
+      for (const m of p.messages) {
+        if (typeof m.content === "string")
+          c += m.content.length;
+        else if (Array.isArray(m.content))
+          for (const x of m.content) {
+            if (typeof x === "string")
+              c += x.length;
+            else if (typeof x === "object" && x !== null && "text" in x)
+              c += String(x.text).length;
+          }
+      }
+      return Math.ceil(c / 4);
+    }
+    return Math.ceil(body.length / 4);
+  } catch {
+    return Math.ceil(body.length / 4);
+  }
+}
+var _log = { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} };
+function setLogger(l) {
+  _log = l;
+}
+async function peekBody(r) {
+  try {
+    return await r.clone().text();
+  } catch {
+    return "";
+  }
+}
+function createWrappedFetch(baseFetch, opts) {
+  const { config, providerId, modelId, onRateLimited, onFatalError } = opts;
+  const key = stateKey(providerId, modelId);
+  const tpmLimit = findProviderTPM(config, providerId, modelId);
+  const rpmLimit = findProviderRPM(config, providerId, modelId);
+  const provCfg = config.providers.find((p) => p.provider === providerId);
+  const errorRules = provCfg?.errorDetection ?? [];
+  return async (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const isChat = url.includes("/chat/completions");
+    const now = Date.now();
+    const state = getState(key);
+    if (state.circuitOpen) {
+      if (now < state.circuitRecoveryAt) {
+        _log.warn(`[rl] Circuit OPEN: ${key}`);
+        throw new Error(`Circuit breaker open`);
+      }
+      state.circuitOpen = false;
+      _log.info(`[rl] Circuit recovery: ${key}`);
+    }
+    if (state.cooldownUntil > 0 && now < state.cooldownUntil) {
+      const rem = Math.ceil((state.cooldownUntil - now) / 1000);
+      _log.warn(`[rl] Cooldown ${key} (${rem}s)`);
+      onRateLimited(providerId, modelId, `Cooldown: ${rem}s`);
+      throw new Error(`Provider in cooldown`);
+    }
+    if (isChat && init?.body) {
+      const bodyStr = typeof init.body === "string" ? init.body : "";
+      const est = estimateTokens(bodyStr);
+      if (tpmLimit > 0 && tokenCounter.wouldExceedTPM(key, tpmLimit, est)) {
+        const cur = tokenCounter.getTPM(key);
+        _log.warn(`[rl] TPM: ${cur}/${tpmLimit} +${est} -> ${key}`);
+        onRateLimited(providerId, modelId, `Pre-flight TPM: ${cur}/${tpmLimit}`);
+        throw new Error(`TPM limit`);
+      }
+      if (rpmLimit > 0 && tokenCounter.wouldExceedRPM(key, rpmLimit)) {
+        _log.warn(`[rl] RPM: ${rpmLimit} -> ${key}`);
+        onRateLimited(providerId, modelId, `Pre-flight RPM: ${rpmLimit}`);
+        throw new Error(`RPM limit`);
+      }
+      tokenCounter.record(key, est);
+      tokenCounter.recordRequest(key);
+    }
+    let response;
+    try {
+      response = await baseFetch(input, init);
+    } catch (e) {
+      throw e;
+    }
+    if (isChat) {
+      const rlh = parseRateLimitHeaders(response.headers);
+      if (rlh)
+        _log.debug(`[rl] quota ${key}: ${rlh.remaining}/${rlh.limit}`);
+    }
+    if (!response.ok) {
+      const bodyText = await peekBody(response);
+      const result = matchError(response.status, bodyText, errorRules, config.cooldownMs);
+      if (result.matched) {
+        _log.warn(`[rl] [${result.category}] ${result.description} (${key})`);
+        if (result.category === "fatal") {
+          _log.error(`[rl] FATAL: ${result.description}`);
+          onFatalError(providerId, modelId, result.description);
+        } else {
+          state.consecutiveFailures++;
+          if (config.circuitBreaker.enabled && state.consecutiveFailures >= config.circuitBreaker.failureThreshold) {
+            state.circuitOpen = true;
+            state.circuitRecoveryAt = now + config.circuitBreaker.recoveryTimeoutMs;
+            _log.error(`[rl] Circuit BREAKER OPEN: ${key}`);
+          }
+          state.cooldownUntil = now + result.waitMs;
+          onRateLimited(providerId, modelId, result.description);
+        }
+      } else {
+        _log.warn(`[rl] Unclassified HTTP ${response.status}: ${key}`);
+      }
+    } else if (state.consecutiveFailures > 0) {
+      _log.info(`[rl] ${key} recovered (failures: ${state.consecutiveFailures})`);
+      state.consecutiveFailures = 0;
+    }
+    return response;
+  };
+}
+function getFetchStatus(config) {
+  const now = Date.now();
+  return tokenCounter.getKeys().map((key) => {
+    const [pid, mid] = key.split("::");
+    const s = rateLimitStates.get(key);
+    return {
+      providerId: pid,
+      modelId: mid,
+      tpm: tokenCounter.getTPM(key),
+      tpmLimit: findProviderTPM(config, pid, mid),
+      rpm: tokenCounter.getRPM(key),
+      rpmLimit: findProviderRPM(config, pid, mid),
+      cooldownRemaining: s && s.cooldownUntil > now ? Math.ceil((s.cooldownUntil - now) / 1000) : 0,
+      circuitOpen: s?.circuitOpen ?? false,
+      consecutiveFailures: s?.consecutiveFailures ?? 0
+    };
+  });
+}
+
+// src/fallback.ts
+var sessionStates = new Map;
+function getOrCreateSession(sessionId, originalModel) {
+  let state = sessionStates.get(sessionId);
+  if (!state) {
+    state = {
+      attemptCount: 0,
+      triedModels: [],
+      originalModel,
+      succeeded: false
+    };
+    sessionStates.set(sessionId, state);
+  }
+  return state;
+}
+var cooldowns = new Map;
+function getModelKey(providerId, modelId) {
+  return `${providerId}::${modelId}`;
+}
+function isInCooldown(providerId, modelId) {
+  const entry = cooldowns.get(getModelKey(providerId, modelId));
+  if (!entry)
+    return false;
+  return Date.now() < entry.until;
+}
+function setCooldown(providerId, modelId, durationMs, reason) {
+  cooldowns.set(getModelKey(providerId, modelId), {
+    until: Date.now() + durationMs,
+    reason
+  });
+}
+function calculateDelay(policy, attempt) {
+  let delay;
+  switch (policy.strategy) {
+    case "immediate":
+      delay = 0;
+      break;
+    case "linear":
+      delay = policy.baseDelayMs * attempt;
+      break;
+    case "exponential":
+    default:
+      delay = policy.baseDelayMs * Math.pow(2, attempt - 1);
+      break;
+  }
+  delay = Math.min(delay, policy.maxDelayMs);
+  if (policy.jitterEnabled) {
+    delay = delay * (0.5 + Math.random() * 0.5);
+  }
+  return Math.round(delay);
+}
+function getAvailableFallbacks(config, triedModels) {
+  return config.fallbackModels.filter((fm) => {
+    const key = getModelKey(fm.providerId, fm.modelId);
+    return !triedModels.includes(key) && !isInCooldown(fm.providerId, fm.modelId);
+  }).sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+}
+var log = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {}
+};
+function attemptFallback(config, sessionId, originalProviderId, originalModelId, reason) {
+  const session = getOrCreateSession(sessionId, originalModelId);
+  setCooldown(originalProviderId, originalModelId, config.cooldownMs, reason);
+  session.triedModels.push(getModelKey(originalProviderId, originalModelId));
+  if (session.attemptCount >= config.retryPolicy.maxRetries) {
+    log.error(`[rate-limit] Max retries (${config.retryPolicy.maxRetries}) reached for session ${sessionId}`);
+    return { model: null, ok: false, reason: "Max retries exceeded" };
+  }
+  const available = getAvailableFallbacks(config, session.triedModels);
+  if (available.length === 0) {
+    if (config.fallbackMode === "cycle") {
+      log.info("[rate-limit] All models exhausted, clearing cooldowns for cycle mode");
+      cooldowns.clear();
+      const retryAvailable = getAvailableFallbacks(config, session.triedModels);
+      if (retryAvailable.length === 0) {
+        return { model: null, ok: false, reason: "No fallback models available" };
+      }
+      const next2 = retryAvailable[0];
+      session.attemptCount++;
+      session.triedModels.push(getModelKey(next2.providerId, next2.modelId));
+      return { model: next2, ok: true, reason: `Cycling to ${next2.providerId}/${next2.modelId}` };
+    }
+    return { model: null, ok: false, reason: "No fallback models available" };
+  }
+  const next = available[0];
+  session.attemptCount++;
+  session.triedModels.push(getModelKey(next.providerId, next.modelId));
+  const delay = calculateDelay(config.retryPolicy, session.attemptCount);
+  if (delay > 0) {
+    log.info(`[rate-limit] Waiting ${delay}ms before fallback attempt ${session.attemptCount}`);
+  }
+  log.info(`[rate-limit] Fallback attempt ${session.attemptCount}: ` + `${originalProviderId}/${originalModelId} → ${next.providerId}/${next.modelId} (reason: ${reason})`);
+  return {
+    model: next,
+    ok: true,
+    reason: `Switched to ${next.providerId}/${next.modelId}`
+  };
+}
+function markFallbackSuccess(sessionId) {
+  const state = sessionStates.get(sessionId);
+  if (state) {
+    state.succeeded = true;
+  }
+}
+function removeSession(sessionId) {
+  sessionStates.delete(sessionId);
+}
+function getFallbackStatus() {
+  const now = Date.now();
+  const cooldownEntries = [];
+  for (const [key, entry] of cooldowns.entries()) {
+    if (now < entry.until) {
+      cooldownEntries.push({
+        key,
+        remaining: Math.ceil((entry.until - now) / 1000),
+        reason: entry.reason
+      });
+    }
+  }
+  return {
+    activeSessions: sessionStates.size,
+    cooldowns: cooldownEntries
+  };
+}
+
+// src/event-handler.ts
+var _l = { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} };
+function setEventLogger(l) {
+  _l = l;
+}
+function allRules(config, pid) {
+  const pc = config.providers.find((x) => x.provider === pid);
+  const r = pc?.errorDetection ?? [];
+  return r.length > 0 ? r : config.providers.flatMap((x) => x.errorDetection ?? []);
+}
+function handleEvent(e, ctx) {
+  if (!ctx.config.eventFallback)
+    return false;
+  if (e.type === "session.error") {
+    const p = e.properties;
+    if (!p?.sessionID || !p?.error)
+      return false;
+    const msg = typeof p.error.message === "string" ? p.error.message : JSON.stringify(p.error);
+    const st = typeof p.error.statusCode === "number" ? p.error.statusCode : 0;
+    const r = matchError(st, msg, allRules(ctx.config, ""), ctx.config.cooldownMs);
+    if (r.matched && r.category !== "fatal") {
+      _l.warn(`[rl] event err: ${r.description}`);
+      const fb = attemptFallback(ctx.config, p.sessionID, "", "", r.description);
+      if (fb.ok && fb.model)
+        ctx.onFb(fb.model.providerId, fb.model.modelId, p.sessionID);
+      return true;
+    }
+  }
+  if (e.type === "message.updated") {
+    const p = e.properties;
+    if (!p?.info)
+      return false;
+    const i = p.info;
+    if (i.status === "completed" && !i.error && i.sessionID) {
+      markFallbackSuccess(i.sessionID);
+      return false;
+    }
+    if (!i.error)
+      return false;
+    const msg = typeof i.error === "string" ? i.error : JSON.stringify(i.error);
+    const r = matchError(0, msg, allRules(ctx.config, i.providerID ?? ""), ctx.config.cooldownMs);
+    if (r.matched && r.category !== "fatal") {
+      _l.warn(`[rl] event msg: ${r.description}`);
+      const fb = attemptFallback(ctx.config, i.sessionID ?? "", i.providerID ?? "", i.modelID ?? "", r.description);
+      if (fb.ok && fb.model)
+        ctx.onFb(fb.model.providerId, fb.model.modelId, i.sessionID ?? "");
+      return true;
+    }
+  }
+  if (e.type === "session.status") {
+    const p = e.properties;
+    if (p?.status?.type === "retry" && p.status.message) {
+      const r = matchError(0, p.status.message, allRules(ctx.config, ""), ctx.config.cooldownMs);
+      if (r.matched && r.category !== "fatal") {
+        _l.warn(`[rl] event retry: ${r.description}`);
+        const fb = attemptFallback(ctx.config, p.sessionID ?? "", "", "", r.description);
+        if (fb.ok && fb.model)
+          ctx.onFb(fb.model.providerId, fb.model.modelId, p.sessionID ?? "");
+        return true;
+      }
+    }
+  }
+  if (e.type === "session.deleted") {
+    const p = e.properties;
+    if (p?.sessionID)
+      removeSession(p.sessionID);
+  }
+  return false;
+}
+
+// src/index.ts
+var RateLimitPlugin = async ({ client, directory, worktree }) => {
+  const { config, sourcePath, errors } = loadConfig(worktree);
+  const levels = { debug: 0, info: 1, warn: 2, error: 3 };
+  const threshold = levels[config.logLevel] ?? 2;
+  const logger = {
+    debug: (m, ...a) => {
+      if (threshold <= 0)
+        console.debug(`[rate-limit] ${m}`, ...a);
+    },
+    info: (m, ...a) => {
+      if (threshold <= 1)
+        console.info(`[rate-limit] ${m}`, ...a);
+    },
+    warn: (m, ...a) => {
+      if (threshold <= 2)
+        console.warn(`[rate-limit] ${m}`, ...a);
+    },
+    error: (m, ...a) => {
+      if (threshold <= 3)
+        console.error(`[rate-limit] ${m}`, ...a);
+    }
+  };
+  setLogger(logger);
+  setEventLogger(logger);
+  if (!config.enabled) {
+    logger.info("Plugin disabled");
+    return {};
+  }
+  if (sourcePath)
+    logger.info(`Config: ${sourcePath}`);
+  else
+    logger.info("No config file, using defaults");
+  if (errors.length > 0) {
+    for (const e of errors)
+      logger.error(`Config error: ${e}`);
+    return {};
+  }
+  tokenCounter.startResetTimer();
+  return {
+    async config(cfg) {
+      if (!config.fetchInterception)
+        return;
+      const providers = cfg.provider ?? {};
+      for (const [pid, pCfg] of Object.entries(providers)) {
+        if (!pCfg || typeof pCfg !== "object")
+          continue;
+        const pc = pCfg;
+        const models = pc.models ?? {};
+        for (const [mid] of Object.entries(models)) {
+          const origFetch = pc.options?.fetch;
+          const baseFetch = origFetch ?? globalThis.fetch.bind(globalThis);
+          const wrapped = createWrappedFetch(baseFetch, {
+            config,
+            providerId: pid,
+            modelId: mid,
+            onRateLimited: (p, m, reason) => {
+              logger.warn(`Fallback triggered: ${p}/${m} — ${reason}`);
+            },
+            onFatalError: (p, m, reason) => {
+              logger.error(`Fatal: ${p}/${m} — ${reason}`);
+            }
+          });
+          if (!pc.options)
+            pc.options = {};
+          pc.options.fetch = wrapped;
+          logger.info(`Fetch injected: ${pid}/${mid}`);
+        }
+      }
+    },
+    event: async ({ event }) => {
+      handleEvent(event, {
+        config,
+        onFb: (pid, mid, sid) => {
+          logger.warn(`Event fallback: ${pid}/${mid} for session ${sid}`);
+        }
+      });
+    },
+    async command(cfg) {
+      cfg.command = cfg.command ?? {};
+      cfg.command["rate-limit-status"] = {
+        description: "Show rate limit status and statistics",
+        template: buildStatusReport(config)
+      };
+    },
+    cleanup: () => {
+      tokenCounter.destroy();
+    }
+  };
+};
+function buildStatusReport(config) {
+  const fetchStatus = getFetchStatus(config);
+  const fallbackStatus = getFallbackStatus();
+  let report = `## Rate Limit Status
+
+`;
+  if (fetchStatus.length === 0) {
+    report += `_No active providers tracked._
+`;
+  } else {
+    report += `| Provider | Model | TPM | Limit | RPM | Limit | Cooldown | Circuit | Failures |
+`;
+    report += `|----------|-------|-----|-------|-----|-------|----------|---------|----------|
+`;
+    for (const s of fetchStatus) {
+      report += `| ${s.providerId} | ${s.modelId} | ${s.tpm} | ${s.tpmLimit || "∞"} | ${s.rpm} | ${s.rpmLimit || "∞"} | ${s.cooldownRemaining > 0 ? s.cooldownRemaining + "s" : "—"} | ${s.circuitOpen ? "⚠ OPEN" : "✅"} | ${s.consecutiveFailures} |
+`;
+    }
+  }
+  report += `
+**Active sessions:** ${fallbackStatus.activeSessions}
+`;
+  if (fallbackStatus.cooldowns.length > 0) {
+    report += `
+**Cooldowns:**
+`;
+    for (const c of fallbackStatus.cooldowns) {
+      report += `- ${c.key}: ${c.remaining}s (${c.reason})
+`;
+    }
+  }
+  report += `
+**Config:** ${config.enabled ? "enabled" : "disabled"} | Fetch: ${config.fetchInterception ? "on" : "off"} | Events: ${config.eventFallback ? "on" : "off"}`;
+  return report;
+}
+var src_default = RateLimitPlugin;
+export {
+  src_default as default,
+  RateLimitPlugin
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@crystalfluxay/opencode-rate-limiter",
+  "version": "0.1.0",
+  "description": "OpenCode plugin for proactive TPM/RPM rate limiting with multi-provider fallback and fuzzy error matching",
+  "author": {
+    "name": "crystalfluxay"
+  },
+  "license": "MIT",
+  "keywords": ["opencode", "plugin", "rate-limit", "tpm", "rpm", "fallback", "xunfei", "xfyun"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crystalfluxay/opencode-rate-limiter"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "rate-limit.example.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "@opencode-ai/plugin": "1.0.85"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.5",
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/rate-limit.example.json

@@ -0,0 +1,53 @@
+{
+  "enabled": true,
+  "cooldownMs": 60000,
+  "fallbackMode": "cycle",
+  "fallbackModels": [],
+  "retryPolicy": {
+    "maxRetries": 3,
+    "strategy": "exponential",
+    "baseDelayMs": 1000,
+    "maxDelayMs": 30000,
+    "jitterEnabled": true
+  },
+  "circuitBreaker": {
+    "enabled": true,
+    "failureThreshold": 5,
+    "recoveryTimeoutMs": 60000
+  },
+  "providers": [
+    {
+      "provider": "xfyun",
+      "tpm": 100000,
+      "rpm": 10,
+      "errorDetection": [
+        { "bodyPattern": "11210|TPM.*超限|tpm.*limit", "category": "tpm", "description": "TPM超限", "waitMs": 60000 },
+        { "bodyPattern": "11201|次数超限|速率限制|请求.*过快", "category": "tpm", "description": "次数超限", "waitMs": 60000 },
+        { "bodyPattern": "11202|秒级流控", "category": "rpm", "description": "秒级流控超限", "waitMs": 5000 },
+        { "bodyPattern": "11203|并发.*超|并发流控|并发.*限制", "category": "rpm", "description": "并发流控超限", "waitMs": 10000 },
+        { "statusPattern": "^429$", "category": "tpm", "description": "HTTP 429", "waitMs": 60000 },
+        { "bodyPattern": "10008|服务容量不足", "category": "server_error", "description": "服务容量不足" },
+        { "bodyPattern": "10010|引擎.*排队|引擎.*连接失败", "category": "server_error", "description": "引擎排队" },
+        { "bodyPattern": "10012|引擎内部错误", "category": "server_error", "description": "引擎内部错误" },
+        { "bodyPattern": "10110|服务忙|服务繁忙", "category": "server_error", "description": "服务忙" },
+        { "bodyPattern": "10222|引擎网络异常", "category": "server_error", "description": "引擎网络异常" },
+        { "statusPattern": "^5\\d{2}$", "category": "server_error", "description": "HTTP 5xx" },
+        { "bodyPattern": "10907|10910|token.*上限|token.*超", "category": "retryable", "description": "Token超上限", "waitMs": 5000 },
+        { "statusPattern": "^401$", "category": "fatal", "description": "HTTP 401" },
+        { "statusPattern": "^403$", "category": "fatal", "description": "HTTP 403" },
+        { "bodyPattern": "10004|schema.*错误", "category": "fatal", "description": "schema错误" },
+        { "bodyPattern": "10005|参数.*错误", "category": "fatal", "description": "参数错误" },
+        { "bodyPattern": "10013|审核不通过", "category": "fatal", "description": "审核不通过" },
+        { "bodyPattern": "10014|回复.*敏感", "category": "fatal", "description": "回复敏感" },
+        { "bodyPattern": "10015|黑名单", "category": "fatal", "description": "黑名单" },
+        { "bodyPattern": "10016|授权.*错误|未开通", "category": "fatal", "description": "授权错误" },
+        { "bodyPattern": "10019|疑似敏感", "category": "fatal", "description": "疑似敏感" },
+        { "bodyPattern": "11200|授权错误|无.*授权", "category": "fatal", "description": "授权错误" },
+        { "bodyPattern": "11221|套餐.*不支持|模型配置错误", "category": "fatal", "description": "模型配置错误" }
+      ]
+    }
+  ],
+  "fetchInterception": true,
+  "eventFallback": true,
+  "logLevel": "warn"
+}