@lgcyaxi/oh-my-claude 1.0.0 → 1.1.1

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

@@ -24,6 +24,7 @@ import {
   cancelAllTasks,
   listTasks,
   cleanupTasks,
+  updateStatusFile,
 } from "./task-manager";
 import { getConcurrencyStatus } from "./concurrency";
 import { getProvidersStatus } from "../../providers/router";
@@ -50,6 +51,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 +121,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 +324,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     completed: new Date(t.completedAt).toISOString(),
                   }),
                   ...(t.error && { error: t.error }),
+                  ...(t.fallback && { fallback: t.fallback }),
                 })),
               }),
             },
@@ -369,6 +374,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
+
+  // Write initial status file for statusline display
+  updateStatusFile();
+
   console.error("oh-my-claude Background Agent MCP Server running");
 }
 

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

@@ -5,13 +5,21 @@
  * - Launch tasks with agent/category routing
  * - Track task status and results
  * - Handle concurrency limits per provider
+ * - Write status file for statusline display
  */
 
-import { routeByAgent, routeByCategory } from "../../providers/router";
+import { routeByAgent, routeByCategory, FallbackRequiredError } from "../../providers/router";
 import { getAgent } from "../../agents";
 import type { ChatMessage } from "../../providers/types";
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { getConcurrencyStatus } from "./concurrency";
 
-export type TaskStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+// Status file path for statusline integration
+const STATUS_FILE_PATH = join(homedir(), ".claude", "oh-my-claude", "status.json");
+
+export type TaskStatus = "pending" | "running" | "completed" | "failed" | "cancelled" | "fallback_required";
 
 export interface Task {
   id: string;
@@ -21,6 +29,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;
@@ -34,6 +49,42 @@ function generateTaskId(): string {
   return `task_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 }
 
+/**
+ * Write current status to file for statusline integration
+ * Called on every task state change and on server startup
+ */
+export function updateStatusFile(): void {
+  try {
+    // Ensure directory exists
+    const dir = dirname(STATUS_FILE_PATH);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    // Get active tasks
+    const activeTasks = Array.from(tasks.values())
+      .filter((t) => t.status === "running" || t.status === "pending")
+      .map((t) => ({
+        agent: t.agentName || t.categoryName || "unknown",
+        startedAt: t.startedAt || t.createdAt,
+      }));
+
+    // Get provider concurrency
+    const providers = getConcurrencyStatus();
+
+    const status = {
+      activeTasks,
+      providers,
+      updatedAt: new Date().toISOString(),
+    };
+
+    writeFileSync(STATUS_FILE_PATH, JSON.stringify(status, null, 2));
+  } catch (error) {
+    // Silently fail - statusline is non-critical
+    console.error("Failed to update status file:", error);
+  }
+}
+
 /**
  * Launch a new background task
  */
@@ -70,6 +121,7 @@ export async function launchTask(options: {
   };
 
   tasks.set(taskId, task);
+  updateStatusFile();
 
   // Start the task asynchronously
   runTask(task, finalSystemPrompt).catch((error) => {
@@ -87,6 +139,7 @@ async function runTask(task: Task, systemPrompt?: string): Promise<void> {
   task.status = "running";
   task.startedAt = Date.now();
   tasks.set(task.id, task);
+  updateStatusFile();
 
   try {
     const messages: ChatMessage[] = [];
@@ -122,11 +175,25 @@ async function runTask(task: Task, systemPrompt?: string): Promise<void> {
     task.result = result;
     task.completedAt = Date.now();
     tasks.set(task.id, task);
+    updateStatusFile();
   } 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);
+    updateStatusFile();
   }
 }
 
@@ -144,6 +211,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 +228,7 @@ export function pollTask(taskId: string): {
     status: task.status,
     result: task.result,
     error: task.error,
+    fallback: task.fallback,
   };
 }
 
@@ -173,6 +247,7 @@ export function cancelTask(taskId: string): boolean {
     task.status = "cancelled";
     task.completedAt = Date.now();
     tasks.set(taskId, task);
+    updateStatusFile();
     return true;
   }
 
@@ -194,6 +269,10 @@ export function cancelAllTasks(): number {
     }
   }
 
+  if (cancelled > 0) {
+    updateStatusFile();
+  }
+
   return cancelled;
 }
 

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 = {

package/src/statusline/formatter.ts

@@ -0,0 +1,164 @@
+/**
+ * StatusLine Formatter
+ *
+ * Formats task and provider data into a compact status line string
+ * for display in Claude Code's statusLine feature.
+ */
+
+export interface ActiveTask {
+  agent: string;
+  startedAt: number;
+}
+
+export interface ProviderStatus {
+  active: number;
+  limit: number;
+}
+
+export interface StatusLineData {
+  activeTasks: ActiveTask[];
+  providers: Record<string, ProviderStatus>;
+  updatedAt: string;
+}
+
+// Agent name abbreviations for compact display (MCP agents)
+const AGENT_ABBREV: Record<string, string> = {
+  oracle: "Oracle",
+  librarian: "Lib",
+  explore: "Exp",
+  "frontend-ui-ux": "UI",
+  "document-writer": "Doc",
+};
+
+// Task tool agent abbreviations (Claude-subscription agents)
+const TASK_AGENT_ABBREV: Record<string, string> = {
+  Scout: "Scout",
+  Planner: "Plan",
+  General: "Gen",
+  Guide: "Guide",
+  Bash: "Bash",
+};
+
+// Provider name abbreviations
+const PROVIDER_ABBREV: Record<string, string> = {
+  deepseek: "DS",
+  zhipu: "ZP",
+  minimax: "MM",
+  openrouter: "OR",
+};
+
+/**
+ * Format duration in seconds to compact string
+ * e.g., 45 -> "45s", 125 -> "2m"
+ */
+function formatDuration(seconds: number): string {
+  if (seconds < 60) {
+    return `${Math.floor(seconds)}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes}m`;
+}
+
+/**
+ * Get abbreviated agent name
+ * Handles both MCP agents and Task tool agents (prefixed with @)
+ */
+function getAgentAbbrev(agent: string): string {
+  // Task tool agents are prefixed with @
+  if (agent.startsWith("@")) {
+    const taskAgent = agent.slice(1);
+    return `@${TASK_AGENT_ABBREV[taskAgent] || taskAgent.slice(0, 4)}`;
+  }
+  return AGENT_ABBREV[agent.toLowerCase()] || agent.slice(0, 4);
+}
+
+/**
+ * Get abbreviated provider name
+ */
+function getProviderAbbrev(provider: string): string {
+  return PROVIDER_ABBREV[provider.toLowerCase()] || provider.slice(0, 2).toUpperCase();
+}
+
+/**
+ * Format the status line data into a compact string
+ *
+ * Output format examples:
+ * - No tasks: "omc"
+ * - With tasks: "omc [Oracle: 32s] [Lib: 12s] | DS: 2/10 ZP: 1/10"
+ * - Tasks only: "omc [Oracle: 32s]"
+ */
+export function formatStatusLine(data: StatusLineData): string {
+  const parts: string[] = ["omc"];
+  const now = Date.now();
+
+  // Format active tasks
+  if (data.activeTasks.length > 0) {
+    // Limit to 3 tasks max for readability
+    const tasksToShow = data.activeTasks.slice(0, 3);
+
+    for (const task of tasksToShow) {
+      const durationSec = Math.floor((now - task.startedAt) / 1000);
+      const agentName = getAgentAbbrev(task.agent);
+      const duration = formatDuration(durationSec);
+      parts.push(`[${agentName}: ${duration}]`);
+    }
+
+    if (data.activeTasks.length > 3) {
+      parts.push(`+${data.activeTasks.length - 3}`);
+    }
+  }
+
+  // Format provider concurrency (only show non-zero or if there are active tasks)
+  const providerParts: string[] = [];
+  const providersToShow = ["deepseek", "zhipu", "minimax"];
+
+  for (const provider of providersToShow) {
+    const status = data.providers[provider];
+    if (status && (status.active > 0 || data.activeTasks.length > 0)) {
+      const abbrev = getProviderAbbrev(provider);
+      providerParts.push(`${abbrev}: ${status.active}/${status.limit}`);
+    }
+  }
+
+  if (providerParts.length > 0) {
+    parts.push("|");
+    parts.push(...providerParts);
+  }
+
+  return parts.join(" ");
+}
+
+/**
+ * Format a minimal status line when no data is available
+ * Shows "omc ready" to indicate the system is available
+ */
+export function formatEmptyStatusLine(): string {
+  return "omc ready";
+}
+
+/**
+ * Format idle status line with provider info
+ * Shows availability even when no tasks are running
+ */
+export function formatIdleStatusLine(providers: Record<string, ProviderStatus>): string {
+  const parts: string[] = ["omc ready"];
+
+  // Show provider availability
+  const providerParts: string[] = [];
+  const providersToShow = ["deepseek", "zhipu", "minimax"];
+
+  for (const provider of providersToShow) {
+    const status = providers[provider];
+    if (status && status.limit > 0) {
+      const abbrev = getProviderAbbrev(provider);
+      providerParts.push(`${abbrev}: ${status.limit}`);
+    }
+  }
+
+  if (providerParts.length > 0) {
+    parts.push("|");
+    parts.push(...providerParts);
+  }
+
+  return parts.join(" ");
+}

package/src/statusline/statusline.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * oh-my-claude StatusLine Script
+ *
+ * Reads MCP background task status from a status file and outputs
+ * a formatted status line for Claude Code's statusLine feature.
+ *
+ * Usage in settings.json:
+ * {
+ *   "statusLine": {
+ *     "type": "command",
+ *     "command": "node ~/.claude/oh-my-claude/dist/statusline/statusline.js"
+ *   }
+ * }
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+import { formatStatusLine, formatEmptyStatusLine, formatIdleStatusLine, type StatusLineData } from "./formatter";
+
+// Status file path - MCP server writes to this
+const STATUS_FILE_PATH = join(homedir(), ".claude", "oh-my-claude", "status.json");
+
+// Timeout for the entire script (prevent blocking terminal)
+const TIMEOUT_MS = 100;
+
+/**
+ * Read status from the shared status file
+ */
+function readStatusFile(): StatusLineData | null {
+  try {
+    if (!existsSync(STATUS_FILE_PATH)) {
+      return null;
+    }
+
+    const content = readFileSync(STATUS_FILE_PATH, "utf-8");
+    const data = JSON.parse(content) as StatusLineData;
+
+    // Validate the data structure
+    if (!data || typeof data !== "object") {
+      return null;
+    }
+
+    // Check if data is stale (older than 5 minutes)
+    if (data.updatedAt) {
+      const updatedAt = new Date(data.updatedAt).getTime();
+      const age = Date.now() - updatedAt;
+      if (age > 5 * 60 * 1000) {
+        // Data is stale, return empty
+        return null;
+      }
+    }
+
+    return data;
+  } catch {
+    // Silently fail - status file may not exist or be malformed
+    return null;
+  }
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  // Set up timeout to prevent blocking
+  const timeoutId = setTimeout(() => {
+    // Output empty status and exit on timeout
+    console.log(formatEmptyStatusLine());
+    process.exit(0);
+  }, TIMEOUT_MS);
+
+  try {
+    // Read Claude Code's input from stdin (may be empty or JSON)
+    // We don't actually need it, but we consume it to avoid broken pipe
+    let _input = "";
+    try {
+      _input = readFileSync(0, "utf-8");
+    } catch {
+      // stdin may be empty or unavailable
+    }
+
+    // Read status from file
+    const statusData = readStatusFile();
+
+    if (!statusData) {
+      console.log(formatEmptyStatusLine());
+    } else if (statusData.activeTasks.length === 0) {
+      // No active tasks - show idle status with provider info
+      console.log(formatIdleStatusLine(statusData.providers));
+    } else {
+      console.log(formatStatusLine(statusData));
+    }
+  } catch {
+    // On any error, output minimal status
+    console.log(formatEmptyStatusLine());
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+main();