@skj1724/oh-my-opencode 3.19.6 → 3.19.7

package/dist/cli/index.js

@@ -6117,6 +6117,12 @@ var init_model_resolver = __esm(() => {
   init_model_availability();
 });
 
+// src/shared/runtime-fallback.ts
+var init_runtime_fallback = __esm(() => {
+  init_model_availability();
+  init_model_requirements();
+});
+
 // src/shared/perf-timer.ts
 class PerfTimer {
   marks = new Map;
@@ -6226,6 +6232,7 @@ var init_shared = __esm(() => {
   init_model_requirements();
   init_model_resolver();
   init_model_availability();
+  init_runtime_fallback();
   init_perf_tracer();
   init_fileio_monitor();
   init_windows_reserved_names();
@@ -8460,7 +8467,7 @@ var import_picocolors2 = __toESM(require_picocolors(), 1);
 // package.json
 var package_default = {
   name: "@skj1724/oh-my-opencode",
-  version: "3.19.6",
+  version: "3.19.7",
   description: "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   main: "dist/index.js",
   types: "dist/index.d.ts",
@@ -24997,6 +25004,7 @@ var HookNameSchema = exports_external.enum([
   "auto-slash-command",
   "edit-error-recovery",
   "delegate-task-retry",
+  "runtime-fallback",
   "prometheus-md-only",
   "perf-profiler",
   "start-work",
@@ -25183,6 +25191,15 @@ var GitMasterConfigSchema = exports_external.object({
   commit_footer: exports_external.boolean().default(true),
   include_co_authored_by: exports_external.boolean().default(true)
 });
+var RuntimeFallbackConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().default(true),
+  max_attempts: exports_external.number().min(0).default(3),
+  initial_delay_ms: exports_external.number().min(0).default(2000),
+  backoff_factor: exports_external.number().min(1).default(2),
+  max_delay_ms: exports_external.number().min(0).default(30000),
+  respect_retry_after: exports_external.boolean().default(true),
+  jitter: exports_external.boolean().default(true)
+});
 var OhMyOpenCodeConfigSchema = exports_external.object({
   $schema: exports_external.string().optional(),
   disabled_mcps: exports_external.array(AnyMcpNameSchema).optional(),
@@ -25201,7 +25218,8 @@ var OhMyOpenCodeConfigSchema = exports_external.object({
   ralph_loop: RalphLoopConfigSchema.optional(),
   background_task: BackgroundTaskConfigSchema.optional(),
   notification: NotificationConfigSchema.optional(),
-  git_master: GitMasterConfigSchema.optional()
+  git_master: GitMasterConfigSchema.optional(),
+  runtime_fallback: RuntimeFallbackConfigSchema.optional()
 });
 // src/cli/doctor/checks/config.ts
 var USER_CONFIG_DIR2 = getOpenCodeConfigDir({ binary: "opencode" });

package/dist/config/schema.d.ts

@@ -70,6 +70,7 @@ export declare const HookNameSchema: z.ZodEnum<{
     "auto-slash-command": "auto-slash-command";
     "edit-error-recovery": "edit-error-recovery";
     "delegate-task-retry": "delegate-task-retry";
+    "runtime-fallback": "runtime-fallback";
     "prometheus-md-only": "prometheus-md-only";
     "perf-profiler": "perf-profiler";
     "start-work": "start-work";
@@ -1016,6 +1017,15 @@ export declare const GitMasterConfigSchema: z.ZodObject<{
     commit_footer: z.ZodDefault<z.ZodBoolean>;
     include_co_authored_by: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
+export declare const RuntimeFallbackConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    max_attempts: z.ZodDefault<z.ZodNumber>;
+    initial_delay_ms: z.ZodDefault<z.ZodNumber>;
+    backoff_factor: z.ZodDefault<z.ZodNumber>;
+    max_delay_ms: z.ZodDefault<z.ZodNumber>;
+    respect_retry_after: z.ZodDefault<z.ZodBoolean>;
+    jitter: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
 export declare const OhMyOpenCodeConfigSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     disabled_mcps: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1064,6 +1074,7 @@ export declare const OhMyOpenCodeConfigSchema: z.ZodObject<{
         "auto-slash-command": "auto-slash-command";
         "edit-error-recovery": "edit-error-recovery";
         "delegate-task-retry": "delegate-task-retry";
+        "runtime-fallback": "runtime-fallback";
         "prometheus-md-only": "prometheus-md-only";
         "perf-profiler": "perf-profiler";
         "start-work": "start-work";
@@ -1855,6 +1866,15 @@ export declare const OhMyOpenCodeConfigSchema: z.ZodObject<{
         commit_footer: z.ZodDefault<z.ZodBoolean>;
         include_co_authored_by: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
+    runtime_fallback: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        max_attempts: z.ZodDefault<z.ZodNumber>;
+        initial_delay_ms: z.ZodDefault<z.ZodNumber>;
+        backoff_factor: z.ZodDefault<z.ZodNumber>;
+        max_delay_ms: z.ZodDefault<z.ZodNumber>;
+        respect_retry_after: z.ZodDefault<z.ZodBoolean>;
+        jitter: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type OhMyOpenCodeConfig = z.infer<typeof OhMyOpenCodeConfigSchema>;
 export type AgentOverrideConfig = z.infer<typeof AgentOverrideConfigSchema>;
@@ -1877,4 +1897,5 @@ export type CategoryConfig = z.infer<typeof CategoryConfigSchema>;
 export type CategoriesConfig = z.infer<typeof CategoriesConfigSchema>;
 export type BuiltinCategoryName = z.infer<typeof BuiltinCategoryNameSchema>;
 export type GitMasterConfig = z.infer<typeof GitMasterConfigSchema>;
+export type RuntimeFallbackConfig = z.infer<typeof RuntimeFallbackConfigSchema>;
 export { AnyMcpNameSchema, type AnyMcpName, McpNameSchema, type McpName } from "../mcp/types";

package/dist/features/background-agent/types.d.ts

@@ -1,3 +1,5 @@
+import type { FallbackAttempt } from "../../shared/runtime-fallback";
+export type { FallbackAttempt };
 export type BackgroundTaskStatus = "pending" | "running" | "completed" | "error" | "cancelled";
 export interface PhaseTiming {
     /** queuedAt -> startedAt in ms */
@@ -65,6 +67,8 @@ export interface BackgroundTask {
     maxRuntimeMs?: number;
     /** Max duration of a single step in ms (0 / undefined = unlimited) */
     stepTimeoutMs?: number;
+    /** Fallback attempts history */
+    attempts?: FallbackAttempt[];
 }
 export interface LaunchInput {
     description: string;

package/dist/hooks/runtime-fallback/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Runtime Fallback Hook
+ *
+ * 处理 session.error 事件中的 provider 错误（quota、rate_limit），
+ * 在 retry 耗尽后自动切换到 fallback 模型。
+ *
+ * 不处理：context_overflow（由 context-window-recovery 处理）、auth、bad_request。
+ * 避让 sessionRecovery（可恢复错误优先由 sessionRecovery 处理）。
+ */
+import type { PluginInput } from "@opencode-ai/plugin";
+export interface RuntimeFallbackOptions {
+    sessionRecovery?: {
+        isRecoverableError: (error: unknown) => boolean;
+    };
+}
+export declare function createRuntimeFallbackHook(ctx: PluginInput, options?: RuntimeFallbackOptions): {
+    handler: ({ event, }: {
+        event: {
+            type: string;
+            properties?: unknown;
+        };
+    }) => Promise<boolean>;
+};

package/dist/hooks/runtime-fallback/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -4859,7 +4859,7 @@ var init_agent_tool_restrictions = __esm(() => {
 });
 
 // src/shared/model-requirements.ts
-var AGENT_MODEL_REQUIREMENTS;
+var AGENT_MODEL_REQUIREMENTS, CATEGORY_MODEL_REQUIREMENTS;
 var init_model_requirements = __esm(() => {
   AGENT_MODEL_REQUIREMENTS = {
     sisyphus: {
@@ -4928,6 +4928,58 @@ var init_model_requirements = __esm(() => {
       ]
     }
   };
+  CATEGORY_MODEL_REQUIREMENTS = {
+    "visual-engineering": {
+      fallbackChain: [
+        { providers: ["google", "github-copilot", "opencode"], model: "gemini-3-pro" },
+        { providers: ["anthropic", "github-copilot", "opencode"], model: "claude-opus-4-5", variant: "max" },
+        { providers: ["openai", "github-copilot", "opencode"], model: "gpt-5.2", variant: "high" }
+      ]
+    },
+    ultrabrain: {
+      fallbackChain: [
+        { providers: ["openai", "github-copilot", "opencode"], model: "gpt-5.2-codex", variant: "xhigh" },
+        { providers: ["anthropic", "github-copilot", "opencode"], model: "claude-opus-4-5", variant: "max" },
+        { providers: ["google", "github-copilot", "opencode"], model: "gemini-3-pro" }
+      ]
+    },
+    artistry: {
+      fallbackChain: [
+        { providers: ["google", "github-copilot", "opencode"], model: "gemini-3-pro", variant: "max" },
+        { providers: ["anthropic", "github-copilot", "opencode"], model: "claude-opus-4-5", variant: "max" },
+        { providers: ["openai", "github-copilot", "opencode"], model: "gpt-5.2" }
+      ]
+    },
+    quick: {
+      fallbackChain: [
+        { providers: ["anthropic", "github-copilot", "opencode"], model: "claude-haiku-4-5" },
+        { providers: ["google", "github-copilot", "opencode"], model: "gemini-3-flash" },
+        { providers: ["opencode"], model: "gpt-5-nano" }
+      ]
+    },
+    "unspecified-low": {
+      fallbackChain: [
+        { providers: ["anthropic", "github-copilot", "opencode"], model: "claude-sonnet-4-5" },
+        { providers: ["openai", "github-copilot", "opencode"], model: "gpt-5.2-codex", variant: "medium" },
+        { providers: ["google", "github-copilot", "opencode"], model: "gemini-3-flash" }
+      ]
+    },
+    "unspecified-high": {
+      fallbackChain: [
+        { providers: ["anthropic", "github-copilot", "opencode"], model: "claude-opus-4-5", variant: "max" },
+        { providers: ["openai", "github-copilot", "opencode"], model: "gpt-5.2", variant: "high" },
+        { providers: ["google", "github-copilot", "opencode"], model: "gemini-3-pro" }
+      ]
+    },
+    writing: {
+      fallbackChain: [
+        { providers: ["google", "github-copilot", "opencode"], model: "gemini-3-flash" },
+        { providers: ["anthropic", "github-copilot", "opencode"], model: "claude-sonnet-4-5" },
+        { providers: ["zai-coding-plan"], model: "glm-4.7" },
+        { providers: ["openai", "github-copilot", "opencode"], model: "gpt-5.2" }
+      ]
+    }
+  };
 });
 
 // src/shared/model-availability.ts
@@ -5064,6 +5116,81 @@ var init_model_resolver = __esm(() => {
   init_model_availability();
 });
 
+// src/shared/runtime-fallback.ts
+function expandChain(chain) {
+  const candidates = [];
+  for (const entry of chain) {
+    for (const provider of entry.providers) {
+      candidates.push({
+        providerID: provider,
+        modelID: entry.model,
+        variant: entry.variant
+      });
+    }
+  }
+  return candidates;
+}
+function modelKey(m) {
+  return `${m.providerID}/${m.modelID}`;
+}
+function getChain(agent, category) {
+  if (agent && AGENT_MODEL_REQUIREMENTS[agent]) {
+    return AGENT_MODEL_REQUIREMENTS[agent].fallbackChain;
+  }
+  if (category && CATEGORY_MODEL_REQUIREMENTS[category]) {
+    return CATEGORY_MODEL_REQUIREMENTS[category].fallbackChain;
+  }
+  throw new Error(`No fallback chain found for agent="${agent ?? ""}" category="${category ?? ""}"`);
+}
+function resolveNextFallbackModel(input) {
+  const {
+    agent,
+    category,
+    currentModel,
+    attempts,
+    availableModels,
+    lastErrorClassification
+  } = input;
+  const chain = getChain(agent, category);
+  const candidates = expandChain(chain);
+  const skipKeys = new Set;
+  skipKeys.add(modelKey(currentModel));
+  for (const a of attempts) {
+    skipKeys.add(modelKey(a.model));
+  }
+  const resultAttempts = [...attempts];
+  const currentKey = modelKey(currentModel);
+  const isInAttempts = attempts.some((a) => modelKey(a.model) === currentKey);
+  if (!isInAttempts) {
+    resultAttempts.push({ model: currentModel });
+  }
+  const hasAvailabilityFilter = availableModels != null && availableModels.size > 0;
+  for (const candidate of candidates) {
+    const key = modelKey(candidate);
+    if (skipKeys.has(key))
+      continue;
+    if (hasAvailabilityFilter) {
+      const match = fuzzyMatchModel(key, availableModels, [candidate.providerID]);
+      if (!match)
+        continue;
+    }
+    return {
+      kind: "next",
+      model: candidate,
+      attempts: resultAttempts
+    };
+  }
+  return {
+    kind: "exhausted",
+    attempts: resultAttempts,
+    lastErrorClassification
+  };
+}
+var init_runtime_fallback = __esm(() => {
+  init_model_availability();
+  init_model_requirements();
+});
+
 // src/shared/perf-timer.ts
 class PerfTimer {
   marks = new Map;
@@ -5348,6 +5475,7 @@ var init_shared = __esm(() => {
   init_model_requirements();
   init_model_resolver();
   init_model_availability();
+  init_runtime_fallback();
   init_perf_tracer();
   init_fileio_monitor();
   init_windows_reserved_names();
@@ -43257,6 +43385,256 @@ function initTaskToastManager(client2, concurrencyManager) {
 }
 // src/tools/delegate-task/tools.ts
 init_shared();
+
+// src/shared/provider-error-classifier.ts
+function extractErrorInfo(error45) {
+  if (typeof error45 === "string") {
+    return { message: error45 };
+  }
+  if (error45 instanceof Error) {
+    const anyErr = error45;
+    return {
+      statusCode: anyErr.status ?? anyErr.statusCode ?? anyErr.httpStatus,
+      code: anyErr.code ?? anyErr.error?.code,
+      type: anyErr.type ?? anyErr.error?.type,
+      message: error45.message,
+      status: anyErr.status ?? anyErr.error?.status,
+      headers: anyErr.headers
+    };
+  }
+  if (typeof error45 === "object" && error45 !== null) {
+    const obj = error45;
+    const inner = obj.error ?? {};
+    return {
+      statusCode: obj.status ?? obj.statusCode ?? inner.status,
+      code: inner.code ?? obj.code,
+      type: inner.type ?? obj.type,
+      message: inner.message ?? obj.message ?? String(error45),
+      status: inner.status ?? obj.status,
+      headers: obj.headers
+    };
+  }
+  return { message: String(error45) };
+}
+function parseRetryAfterMs(headers) {
+  if (!headers)
+    return;
+  const retryAfter = headers["retry-after"] ?? headers["Retry-After"];
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (!isNaN(seconds) && seconds > 0) {
+      return seconds * 1000;
+    }
+  }
+  const reset = headers["x-ratelimit-reset"] ?? headers["X-Ratelimit-Reset"];
+  if (reset) {
+    const resetTimestamp = Number(reset);
+    if (!isNaN(resetTimestamp)) {
+      const resetMs = resetTimestamp > 1000000000000 ? resetTimestamp : resetTimestamp * 1000;
+      const delayMs = resetMs - Date.now();
+      return delayMs > 0 ? delayMs : 0;
+    }
+  }
+  return;
+}
+function isContextOverflow(message, code) {
+  const lowerMessage = message.toLowerCase();
+  return lowerMessage.includes("context_length_exceeded") || lowerMessage.includes("prompt is too long") || lowerMessage.includes("maximum context length") || code === "context_length_exceeded";
+}
+function isZhipuQuotaCode(code) {
+  if (typeof code !== "number")
+    return false;
+  return [1113, 1304, 1308, 1309].includes(code);
+}
+function isZhipuRateLimitCode(code) {
+  if (typeof code !== "number")
+    return false;
+  return [1302, 1303].includes(code);
+}
+function isZhipuOverloadedCode(code) {
+  if (typeof code !== "number")
+    return false;
+  return code === 1312;
+}
+function isGeminiQuotaDetails(details) {
+  if (!Array.isArray(details))
+    return false;
+  return details.some((d) => d?.["@type"]?.includes("QuotaFailure") || d?.["@type"]?.includes("google.rpc.QuotaFailure"));
+}
+function isGeminiPerMinuteLimit(message, details) {
+  const lowerMessage = message.toLowerCase();
+  if (lowerMessage.includes("per_minute") || lowerMessage.includes("per minute")) {
+    return true;
+  }
+  if (Array.isArray(details)) {
+    return details.some((d) => d?.["@type"]?.includes("RetryInfo"));
+  }
+  return false;
+}
+function classifyProviderError(error45) {
+  const info = extractErrorInfo(error45);
+  const { statusCode, code, type: type2, message, status, headers } = info;
+  if (isContextOverflow(message, code)) {
+    return {
+      category: "context_overflow",
+      retryable: false,
+      shouldFallback: false,
+      statusCode,
+      reason: "Context length exceeded, prompt too long for model"
+    };
+  }
+  if (statusCode === 401 || statusCode === 403) {
+    return {
+      category: "auth",
+      retryable: false,
+      shouldFallback: false,
+      statusCode,
+      reason: statusCode === 401 ? "Invalid API key or authentication" : "Permission denied"
+    };
+  }
+  if (statusCode === 400) {
+    return {
+      category: "bad_request",
+      retryable: false,
+      shouldFallback: false,
+      statusCode,
+      reason: "Invalid request parameters"
+    };
+  }
+  if (statusCode === 429 && (code === "insufficient_quota" || type2 === "insufficient_quota")) {
+    return {
+      category: "quota",
+      retryable: false,
+      shouldFallback: true,
+      statusCode,
+      providerGuess: "openai",
+      reason: "OpenAI quota exceeded, billing issue"
+    };
+  }
+  if (statusCode === 402 && type2 === "billing_error") {
+    return {
+      category: "quota",
+      retryable: false,
+      shouldFallback: true,
+      statusCode,
+      providerGuess: "anthropic",
+      reason: "Anthropic billing error, payment required"
+    };
+  }
+  if (statusCode === 429 && status === "RESOURCE_EXHAUSTED" && isGeminiQuotaDetails(info.headers ? undefined : error45?.error?.details)) {
+    return {
+      category: "quota",
+      retryable: false,
+      shouldFallback: true,
+      statusCode,
+      providerGuess: "gemini",
+      reason: "Gemini daily quota exceeded"
+    };
+  }
+  if (statusCode === 429 && isZhipuQuotaCode(code)) {
+    const quotaReasons = {
+      1113: "\u8D26\u6237\u6B20\u8D39",
+      1304: "\u8C03\u7528\u6B21\u6570\u8D85\u8FC7\u9650\u989D",
+      1308: "\u4F7F\u7528\u91CF\u8D85\u8FC7\u4E0A\u9650",
+      1309: "\u5957\u9910\u5DF2\u5230\u671F"
+    };
+    return {
+      category: "quota",
+      retryable: false,
+      shouldFallback: true,
+      statusCode,
+      providerGuess: "zhipu",
+      reason: `Zhipu/GLM: ${quotaReasons[code] ?? "quota exceeded"}`
+    };
+  }
+  if (statusCode === 529 && type2 === "overloaded_error") {
+    return {
+      category: "overloaded",
+      retryable: true,
+      shouldFallback: false,
+      statusCode,
+      providerGuess: "anthropic",
+      reason: "Anthropic API overloaded"
+    };
+  }
+  if (statusCode === 429 && isZhipuOverloadedCode(code)) {
+    return {
+      category: "overloaded",
+      retryable: true,
+      shouldFallback: false,
+      statusCode,
+      providerGuess: "zhipu",
+      reason: "Zhipu/GLM: \u5F53\u524D\u8D1F\u8F7D\u8FC7\u9AD8"
+    };
+  }
+  if (statusCode === 429 && type2 === "rate_limit_error") {
+    return {
+      category: "rate_limit",
+      retryable: true,
+      shouldFallback: false,
+      statusCode,
+      providerGuess: "anthropic",
+      retryAfterMs: parseRetryAfterMs(headers),
+      reason: "Anthropic rate limit exceeded"
+    };
+  }
+  if (statusCode === 429 && code === "rate_limit_exceeded") {
+    return {
+      category: "rate_limit",
+      retryable: true,
+      shouldFallback: false,
+      statusCode,
+      providerGuess: "openai",
+      retryAfterMs: parseRetryAfterMs(headers),
+      reason: "OpenAI rate limit exceeded"
+    };
+  }
+  if (statusCode === 429 && status === "RESOURCE_EXHAUSTED" && isGeminiPerMinuteLimit(message, error45?.error?.details)) {
+    return {
+      category: "rate_limit",
+      retryable: true,
+      shouldFallback: false,
+      statusCode,
+      providerGuess: "gemini",
+      retryAfterMs: parseRetryAfterMs(headers),
+      reason: "Gemini per-minute rate limit exceeded"
+    };
+  }
+  if (statusCode === 429 && isZhipuRateLimitCode(code)) {
+    const rateLimitReasons = {
+      1302: "\u5E76\u53D1\u8BF7\u6C42\u8D85\u8FC7\u9650\u5236",
+      1303: "\u8BF7\u6C42\u9891\u7387\u8D85\u8FC7\u9650\u5236"
+    };
+    return {
+      category: "rate_limit",
+      retryable: true,
+      shouldFallback: false,
+      statusCode,
+      providerGuess: "zhipu",
+      retryAfterMs: parseRetryAfterMs(headers),
+      reason: `Zhipu/GLM: ${rateLimitReasons[code] ?? "rate limit exceeded"}`
+    };
+  }
+  if (statusCode === 429) {
+    return {
+      category: "rate_limit",
+      retryable: true,
+      shouldFallback: false,
+      statusCode,
+      retryAfterMs: parseRetryAfterMs(headers),
+      reason: "Rate limit exceeded (generic 429)"
+    };
+  }
+  return {
+    category: "unknown",
+    retryable: false,
+    shouldFallback: false,
+    statusCode,
+    reason: `Unknown error: ${message.substring(0, 100)}`
+  };
+}
+
+// src/tools/delegate-task/tools.ts
 var SISYPHUS_JUNIOR_AGENT = "sisyphus-junior";
 function parseModelString(model) {
   const parts = model.split("/");
@@ -43868,7 +44246,12 @@ Session ID: ${sessionID}`;
           path: { id: sessionID }
         });
         if (messagesResult.error) {
-          return `Error fetching result: ${messagesResult.error}
+          const classification = classifyProviderError(messagesResult.error);
+          const diagnosis = classification.category !== "unknown" ? `
+
+\uD83D\uDD0D **\u9519\u8BEF\u5206\u7C7B**: ${classification.reason}
+${classification.shouldFallback ? "\uD83D\uDCA1 \u6B64\u9519\u8BEF\u53EF\u901A\u8FC7 runtime fallback \u81EA\u52A8\u5904\u7406\u3002" : classification.retryable ? "\u23F3 \u6B64\u9519\u8BEF\u53EF\u91CD\u8BD5\u3002" : ""}` : "";
+          return `Error fetching result: ${messagesResult.error}${diagnosis}
 
 Session ID: ${sessionID}`;
         }
@@ -43906,13 +44289,14 @@ ${textContent || "(\u65E0\u6587\u672C\u8F93\u51FA)"}
         if (syncSessionID) {
           subagentSessions.delete(syncSessionID);
         }
-        return formatDetailedError(error45, {
-          operation: "\u6267\u884C\u4EFB\u52A1",
-          args,
-          sessionID: syncSessionID,
-          agent: agentToUse,
-          category: args.category
-        });
+        const classification = classifyProviderError(error45);
+        const diagnosis = classification.category !== "unknown" ? `
+
+\uD83D\uDD0D **\u9519\u8BEF\u5206\u7C7B**: ${classification.reason}
+${classification.shouldFallback ? "\uD83D\uDCA1 \u6B64\u9519\u8BEF\u53EF\u901A\u8FC7 runtime fallback \u81EA\u52A8\u5904\u7406\u3002" : classification.retryable ? "\u23F3 \u6B64\u9519\u8BEF\u53EF\u91CD\u8BD5\u3002" : ""}` : "";
+        return `\u4EFB\u52A1\u6267\u884C\u5931\u8D25: ${error45 instanceof Error ? error45.message : String(error45)}${diagnosis}
+
+Session ID: ${syncSessionID ?? "unknown"}`;
       }
     }
   });
@@ -44041,6 +44425,9 @@ class ConcurrencyManager {
   }
 }
 
+// src/features/background-agent/manager.ts
+init_runtime_fallback();
+
 // src/features/background-agent/perf-aggregator.ts
 function percentile(sorted, p) {
   if (sorted.length === 0)
@@ -44293,13 +44680,58 @@ class BackgroundManager {
       log("[background-agent] promptAsync error:", error45);
       const existingTask = this.findBySession(sessionID);
       if (existingTask) {
-        existingTask.status = "error";
-        const errorMessage = error45 instanceof Error ? error45.message : String(error45);
-        if (errorMessage.includes("agent.name") || errorMessage.includes("undefined")) {
-          existingTask.error = `Agent "${input.agent}" not found. Make sure the agent is registered in your opencode.json or provided by a plugin.`;
+        const classification = classifyProviderError(error45);
+        if (classification.retryable || classification.shouldFallback) {
+          const attempts = existingTask.attempts ?? [];
+          const currentModel = input.model ?? { providerID: "", modelID: "" };
+          const fallbackResult = resolveNextFallbackModel({
+            agent: input.agent,
+            currentModel,
+            attempts,
+            lastErrorClassification: classification
+          });
+          if (fallbackResult.kind === "next") {
+            existingTask.attempts = [...attempts, {
+              model: fallbackResult.model,
+              error: classification
+            }];
+            log("[background-agent] Fallback to model:", fallbackResult.model);
+            this.client.session.prompt({
+              path: { id: sessionID },
+              body: {
+                agent: input.agent,
+                model: fallbackResult.model,
+                parts: [{ type: "text", text: input.prompt }]
+              }
+            }).catch((retryError) => {
+              log("[background-agent] Fallback prompt error:", retryError);
+              const task2 = this.findBySession(sessionID);
+              if (task2) {
+                task2.status = "error";
+                task2.error = `Fallback failed: ${retryError instanceof Error ? retryError.message : String(retryError)}`;
+                task2.completedAt = new Date;
+                if (task2.concurrencyKey) {
+                  this.concurrencyManager.release(task2.concurrencyKey);
+                  task2.concurrencyKey = undefined;
+                }
+                this.markForNotification(task2);
+                this.notifyParentSession(task2).catch((err) => {
+                  log("[background-agent] Failed to notify on fallback error:", err);
+                });
+              }
+            });
+            return;
+          }
+          existingTask.error = `All fallback models exhausted. Last error: ${classification.reason}`;
         } else {
-          existingTask.error = errorMessage;
+          const errorMessage = error45 instanceof Error ? error45.message : String(error45);
+          if (errorMessage.includes("agent.name") || errorMessage.includes("undefined")) {
+            existingTask.error = `Agent "${input.agent}" not found. Make sure the agent is registered in your opencode.json or provided by a plugin.`;
+          } else {
+            existingTask.error = errorMessage;
+          }
         }
+        existingTask.status = "error";
         existingTask.completedAt = new Date;
         if (existingTask.concurrencyKey) {
           this.concurrencyManager.release(existingTask.concurrencyKey);
@@ -63126,6 +63558,7 @@ var HookNameSchema = exports_external2.enum([
   "auto-slash-command",
   "edit-error-recovery",
   "delegate-task-retry",
+  "runtime-fallback",
   "prometheus-md-only",
   "perf-profiler",
   "start-work",
@@ -63312,6 +63745,15 @@ var GitMasterConfigSchema = exports_external2.object({
   commit_footer: exports_external2.boolean().default(true),
   include_co_authored_by: exports_external2.boolean().default(true)
 });
+var RuntimeFallbackConfigSchema = exports_external2.object({
+  enabled: exports_external2.boolean().default(true),
+  max_attempts: exports_external2.number().min(0).default(3),
+  initial_delay_ms: exports_external2.number().min(0).default(2000),
+  backoff_factor: exports_external2.number().min(1).default(2),
+  max_delay_ms: exports_external2.number().min(0).default(30000),
+  respect_retry_after: exports_external2.boolean().default(true),
+  jitter: exports_external2.boolean().default(true)
+});
 var OhMyOpenCodeConfigSchema = exports_external2.object({
   $schema: exports_external2.string().optional(),
   disabled_mcps: exports_external2.array(AnyMcpNameSchema).optional(),
@@ -63330,7 +63772,8 @@ var OhMyOpenCodeConfigSchema = exports_external2.object({
   ralph_loop: RalphLoopConfigSchema.optional(),
   background_task: BackgroundTaskConfigSchema.optional(),
   notification: NotificationConfigSchema.optional(),
-  git_master: GitMasterConfigSchema.optional()
+  git_master: GitMasterConfigSchema.optional(),
+  runtime_fallback: RuntimeFallbackConfigSchema.optional()
 });
 // src/plugin-config.ts
 init_shared();

package/dist/shared/index.d.ts

@@ -28,6 +28,7 @@ export * from "./agent-tool-restrictions";
 export * from "./model-requirements";
 export * from "./model-resolver";
 export * from "./model-availability";
+export * from "./runtime-fallback";
 export * from "./perf-timer";
 export * from "./perf-tracer";
 export * from "./case-insensitive";

package/dist/shared/provider-error-classifier.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Provider Error Classifier
+ *
+ * 统一的 provider 错误分类逻辑，用于判断错误类型和是否可重试/fallback。
+ * 支持 OpenAI、Anthropic、Gemini、xAI、Zhipu 等主流 provider。
+ */
+export type ErrorCategory = "rate_limit" | "quota" | "overloaded" | "context_overflow" | "auth" | "bad_request" | "unknown";
+export interface ProviderErrorClassification {
+    category: ErrorCategory;
+    retryable: boolean;
+    shouldFallback: boolean;
+    statusCode?: number;
+    providerGuess?: string;
+    retryAfterMs?: number;
+    reason: string;
+}
+/**
+ * 分类 provider 错误
+ *
+ * @param error - 未知类型的错误对象
+ * @returns 包含错误分类、可重试性、是否应该 fallback 等信息
+ */
+export declare function classifyProviderError(error: unknown): ProviderErrorClassification;

package/dist/shared/provider-error-classifier.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/retry-strategy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Retry/backoff 策略服务
+ *
+ * 提供纯函数式的重试决策计算，支持指数退避、Retry-After 和 Jitter。
+ */
+export interface RetryConfig {
+    /** 最大重试次数 */
+    max_attempts: number;
+    /** 初始延迟（毫秒） */
+    initial_delay_ms: number;
+    /** 退避因子 */
+    backoff_factor: number;
+    /** 最大延迟（毫秒） */
+    max_delay_ms: number;
+    /** 是否启用 jitter */
+    jitter: boolean;
+    /** 是否尊重 Retry-After 头 */
+    respect_retry_after: boolean;
+}
+export interface RetryDecision {
+    /** 是否可重试 */
+    retryable: boolean;
+    /** 延迟时间（毫秒） */
+    delay_ms: number;
+    /** 当前尝试次数 */
+    attempt: number;
+    /** 决策原因 */
+    reason: string;
+}
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * 计算重试延迟
+ *
+ * @param attempt - 当前尝试次数（从 0 开始）
+ * @param config - 重试配置
+ * @param retryAfterMs - 可选的 Retry-After 值（毫秒）
+ * @returns 重试决策
+ */
+export declare function calculateRetryDelay(attempt: number, config: RetryConfig, retryAfterMs?: number): RetryDecision;

package/dist/shared/retry-strategy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/runtime-fallback.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Runtime Fallback Decision Service
+ *
+ * 纯函数：根据 agent/category 的 fallback chain，结合当前失败状态和可用模型，
+ * 决定下一个要尝试的模型。
+ */
+import type { ProviderErrorClassification } from "./provider-error-classifier";
+export interface FallbackModel {
+    providerID: string;
+    modelID: string;
+    variant?: string;
+}
+export interface FallbackAttempt {
+    model: FallbackModel;
+    error?: ProviderErrorClassification;
+}
+export interface FallbackNextResult {
+    kind: "next";
+    model: FallbackModel;
+    attempts: FallbackAttempt[];
+}
+export interface FallbackExhaustedResult {
+    kind: "exhausted";
+    attempts: FallbackAttempt[];
+    lastErrorClassification?: ProviderErrorClassification;
+}
+export type FallbackResult = FallbackNextResult | FallbackExhaustedResult;
+export interface RuntimeFallbackInput {
+    agent?: string;
+    category?: string;
+    currentModel: FallbackModel;
+    attempts: FallbackAttempt[];
+    availableModels?: Set<string>;
+    lastErrorClassification?: ProviderErrorClassification;
+}
+/**
+ * 解析下一个 fallback 模型
+ *
+ * 逻辑：
+ * 1. 从 AGENT_MODEL_REQUIREMENTS 或 CATEGORY_MODEL_REQUIREMENTS 获取 fallbackChain
+ * 2. 将 chain 展开为候选列表（每个 provider × model 组合，保持顺序）
+ * 3. 跳过 currentModel 和 attempts 中的 model
+ * 4. 如果 availableModels 非空，使用 fuzzyMatchModel 检查可用性
+ * 5. 返回第一个有效候选，或 exhausted
+ */
+export declare function resolveNextFallbackModel(input: RuntimeFallbackInput): FallbackResult;

package/dist/shared/runtime-fallback.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skj1724/oh-my-opencode",
-  "version": "3.19.6",
+  "version": "3.19.7",
   "description": "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",