@lgcyaxi/oh-my-claude 1.0.0 → 1.0.1

package/src/config/schema.ts

@@ -15,6 +15,13 @@ export const ProviderConfigSchema = z.object({
   note: z.string().optional(),
 });
 
+// Agent fallback configuration schema
+export const AgentFallbackConfigSchema = z.object({
+  provider: z.string(),
+  model: z.string(),
+  executionMode: z.enum(["task", "mcp"]).optional(),
+});
+
 // Agent configuration schema
 export const AgentConfigSchema = z.object({
   provider: z.string(),
@@ -27,6 +34,7 @@ export const AgentConfigSchema = z.object({
       budget_tokens: z.number().optional(),
     })
     .optional(),
+  fallback: AgentFallbackConfigSchema.optional(),
 });
 
 // Category configuration schema
@@ -77,6 +85,7 @@ export const OhMyClaudeConfigSchema = z.object({
   }),
 
   agents: z.record(z.string(), AgentConfigSchema).default({
+    // Claude subscription agents (no fallback needed)
     Sisyphus: { provider: "claude", model: "claude-opus-4-5" },
     "claude-reviewer": {
       provider: "claude",
@@ -88,22 +97,36 @@ export const OhMyClaudeConfigSchema = z.object({
       model: "claude-haiku-4-5",
       temperature: 0.3,
     },
+    // External API agents (with Claude fallbacks)
     oracle: {
       provider: "deepseek",
       model: "deepseek-reasoner",
       temperature: 0.1,
+      fallback: { provider: "claude", model: "claude-opus-4-5", executionMode: "task" },
+    },
+    librarian: {
+      provider: "zhipu",
+      model: "glm-4.7",
+      temperature: 0.3,
+      fallback: { provider: "claude", model: "claude-sonnet-4-5", executionMode: "task" },
+    },
+    explore: {
+      provider: "deepseek",
+      model: "deepseek-chat",
+      temperature: 0.1,
+      fallback: { provider: "claude", model: "claude-haiku-4-5", executionMode: "task" },
     },
-    librarian: { provider: "zhipu", model: "glm-4.7", temperature: 0.3 },
-    explore: { provider: "deepseek", model: "deepseek-chat", temperature: 0.1 },
     "frontend-ui-ux": {
       provider: "zhipu",
       model: "glm-4v-flash",
       temperature: 0.7,
+      fallback: { provider: "claude", model: "claude-sonnet-4-5", executionMode: "task" },
     },
     "document-writer": {
       provider: "minimax",
       model: "MiniMax-M2.1",
       temperature: 0.5,
+      fallback: { provider: "claude", model: "claude-sonnet-4-5", executionMode: "task" },
     },
   }),
 

package/src/generators/agent-generator.ts

@@ -35,7 +35,7 @@ export function generateAgentMarkdown(agent: AgentDefinition): string {
   lines.push(`> ${agent.description}`);
   lines.push("");
 
-  // Execution mode note
+  // Execution mode note with fallback info
   if (agent.executionMode === "task") {
     lines.push(
       `<!-- Execution: Claude Code Task tool (sync) - Uses Claude subscription -->`
@@ -44,12 +44,28 @@ export function generateAgentMarkdown(agent: AgentDefinition): string {
     lines.push(
       `<!-- Execution: oh-my-claude MCP server (async) - Uses ${agent.defaultProvider} API -->`
     );
+    // Add fallback info for MCP agents
+    if (agent.fallback) {
+      lines.push(
+        `<!-- Fallback: ${agent.fallback.provider}/${agent.fallback.model} via Task tool (when ${agent.defaultProvider.toUpperCase()}_API_KEY is not set) -->`
+      );
+    }
   }
   lines.push("");
 
   // The actual prompt
   lines.push(agent.prompt);
 
+  // Add fallback usage note for MCP agents
+  if (agent.executionMode === "mcp" && agent.fallback) {
+    lines.push("");
+    lines.push("## Fallback Mode");
+    lines.push("");
+    lines.push(`If \`${agent.defaultProvider.toUpperCase()}_API_KEY\` is not configured, this agent will automatically fall back to using **${agent.fallback.model}** via Claude's Task tool.`);
+    lines.push("");
+    lines.push("The fallback provides similar capabilities using your Claude subscription, though the primary provider may offer specialized features.");
+  }
+
   return lines.join("\n");
 }
 

package/src/mcp/background-agent-server/server.ts

@@ -50,6 +50,9 @@ Use this for async operations that should run in parallel without blocking.
 - visual-engineering: UI/UX work
 - writing: Documentation and text
 
+**Fallback Behavior**:
+If the provider's API key is not configured, the task will return with status "fallback_required" and include fallback info. When this happens, use Claude Code's Task tool with the specified fallback model instead.
+
 Note: Agents using Claude subscription (sisyphus, claude-reviewer, claude-scout) should use Claude Code's Task tool instead.`,
     inputSchema: {
       type: "object",
@@ -117,8 +120,8 @@ Note: Agents using Claude subscription (sisyphus, claude-reviewer, claude-scout)
       properties: {
         status: {
           type: "string",
-          enum: ["pending", "running", "completed", "failed", "cancelled"],
-          description: "Filter by status",
+          enum: ["pending", "running", "completed", "failed", "cancelled", "fallback_required"],
+          description: "Filter by status. 'fallback_required' means the provider API key is not configured and Claude Task tool should be used instead.",
         },
         limit: {
           type: "number",
@@ -320,6 +323,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     completed: new Date(t.completedAt).toISOString(),
                   }),
                   ...(t.error && { error: t.error }),
+                  ...(t.fallback && { fallback: t.fallback }),
                 })),
               }),
             },

package/src/mcp/background-agent-server/task-manager.ts

@@ -7,11 +7,11 @@
  * - Handle concurrency limits per provider
  */
 
-import { routeByAgent, routeByCategory } from "../../providers/router";
+import { routeByAgent, routeByCategory, FallbackRequiredError } from "../../providers/router";
 import { getAgent } from "../../agents";
 import type { ChatMessage } from "../../providers/types";
 
-export type TaskStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+export type TaskStatus = "pending" | "running" | "completed" | "failed" | "cancelled" | "fallback_required";
 
 export interface Task {
   id: string;
@@ -21,6 +21,13 @@ export interface Task {
   status: TaskStatus;
   result?: string;
   error?: string;
+  /** Fallback info when primary provider is not configured */
+  fallback?: {
+    provider: string;
+    model: string;
+    executionMode?: string;
+    reason: string;
+  };
   createdAt: number;
   startedAt?: number;
   completedAt?: number;
@@ -123,8 +130,20 @@ async function runTask(task: Task, systemPrompt?: string): Promise<void> {
     task.completedAt = Date.now();
     tasks.set(task.id, task);
   } catch (error) {
-    task.status = "failed";
-    task.error = error instanceof Error ? error.message : String(error);
+    // Handle fallback required error specially
+    if (error instanceof FallbackRequiredError) {
+      task.status = "fallback_required";
+      task.error = error.message;
+      task.fallback = {
+        provider: error.fallback.provider,
+        model: error.fallback.model,
+        executionMode: error.fallback.executionMode,
+        reason: error.reason,
+      };
+    } else {
+      task.status = "failed";
+      task.error = error instanceof Error ? error.message : String(error);
+    }
     task.completedAt = Date.now();
     tasks.set(task.id, task);
   }
@@ -144,6 +163,12 @@ export function pollTask(taskId: string): {
   status: TaskStatus;
   result?: string;
   error?: string;
+  fallback?: {
+    provider: string;
+    model: string;
+    executionMode?: string;
+    reason: string;
+  };
 } {
   const task = tasks.get(taskId);
 
@@ -155,6 +180,7 @@ export function pollTask(taskId: string): {
     status: task.status,
     result: task.result,
     error: task.error,
+    fallback: task.fallback,
   };
 }
 

package/src/providers/router.ts

@@ -16,6 +16,8 @@ import {
   resolveProviderForAgent,
   resolveProviderForCategory,
   getProviderDetails,
+  shouldUseFallback,
+  isProviderConfigured,
   type OhMyClaudeConfig,
 } from "../config";
 
@@ -80,6 +82,21 @@ function getProviderClient(
   return client;
 }
 
+/**
+ * Custom error class for fallback scenarios
+ */
+export class FallbackRequiredError extends Error {
+  constructor(
+    message: string,
+    public readonly agentName: string,
+    public readonly fallback: { provider: string; model: string; executionMode?: string },
+    public readonly reason: string
+  ) {
+    super(message);
+    this.name = "FallbackRequiredError";
+  }
+}
+
 /**
  * Route a request to the appropriate provider based on agent name
  */
@@ -106,6 +123,17 @@ export async function routeByAgent(
     );
   }
 
+  // Check if fallback should be used (primary provider not configured)
+  const fallbackCheck = shouldUseFallback(config, agentName);
+  if (fallbackCheck.useFallback && fallbackCheck.fallback) {
+    throw new FallbackRequiredError(
+      `Agent "${agentName}" requires fallback: ${fallbackCheck.reason}. Use Task tool with ${fallbackCheck.fallback.model} instead.`,
+      agentName,
+      fallbackCheck.fallback,
+      fallbackCheck.reason ?? "Provider not configured"
+    );
+  }
+
   const client = getProviderClient(agentConfig.provider, config);
 
   const request: ChatCompletionRequest = {