@bugmole/cli 0.4.0

package/src/runtime/cursor-llm-example.ts

@@ -0,0 +1,90 @@
+/**
+ * Example: Using CURSOR_DRIVER as a simple LLM replacement
+ *
+ * This demonstrates the simplest way to use CURSOR_DRIVER - just like any LLM API.
+ */
+
+import { cursorLLM, cursorLLMStructured } from "./cursor-llm.js";
+
+/**
+ * Example 1: Simple text completion (like OpenAI API)
+ *
+ * Just pass a prompt, get back text. That's it.
+ */
+export async function exampleSimple() {
+  const answer = await cursorLLM("Analyze the error handling patterns in this codebase");
+  console.log(answer);
+  return answer;
+}
+
+/**
+ * Example 2: Structured response with actions and artifacts
+ */
+export async function exampleStructured() {
+  const response = await cursorLLMStructured(
+    "Review test failures and propose fixes. Focus on selector mismatches.",
+  );
+
+  if (response.success && response.payload) {
+    console.log("Status:", response.payload.status);
+    console.log("Summary:", response.payload.summary);
+    console.log("Actions:", response.payload.actions);
+    console.log("Artifacts:", response.payload.artifacts);
+    console.log("Full Answer:", response.payload.answer_markdown);
+  } else {
+    console.error("Error:", response.error);
+  }
+
+  return response;
+}
+
+/**
+ * Example 3: With custom options (optional)
+ */
+export async function exampleWithOptions() {
+  const answer = await cursorLLM("Refactor the authentication module", {
+    timeout: 600000, // 10 minutes
+    requestId: `refactor_${Date.now()}`,
+    customInstructions: "Focus on security best practices",
+  });
+  return answer;
+}
+
+/**
+ * Example 4: Using in a workflow
+ */
+export async function exampleWorkflow() {
+  // Step 1: Analyze
+  const analysis = await cursorLLM("Analyze the current test coverage");
+
+  // Step 2: Generate plan
+  const plan = await cursorLLMStructured(
+    "Based on this analysis, create a test plan:\n\n" + analysis,
+  );
+
+  // Step 3: Execute (if needed)
+  if (plan.success && plan.payload?.actions) {
+    console.log("Actions to take:", plan.payload.actions);
+  }
+
+  return { analysis, plan };
+}
+
+/**
+ * Example 5: Error handling
+ */
+export async function exampleWithErrorHandling() {
+  try {
+    const answer = await cursorLLM("Your task here");
+    return answer;
+  } catch (error: any) {
+    if (error.message?.includes("MCP_UNAVAILABLE")) {
+      console.error("MCP server not available. Start it with: npm run bugmole:mcp");
+    } else if (error.message?.includes("Timeout")) {
+      console.error("Task timed out. Try increasing timeout or simplifying the task.");
+    } else {
+      console.error("Error:", error.message);
+    }
+    throw error;
+  }
+}

package/src/runtime/cursor-llm.ts

@@ -0,0 +1,206 @@
+/**
+ * CURSOR_DRIVER as a simple LLM API replacement
+ *
+ * This module provides a drop-in replacement for LLM API calls.
+ * Just pass a prompt, and it handles everything else using config.
+ *
+ * Usage:
+ *   import { cursorLLM } from './cursor-llm.js';
+ *   const response = await cursorLLM('Your prompt here');
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import dotenv from "dotenv";
+import { preferExisting } from "./legacy-names.js";
+import YAML from "yaml";
+import { runCursorDriver } from "./cursor-driver-run.js";
+import type { CursorDriverResponse, CursorDriverRunOptions } from "./cursor-driver.js";
+
+// Cache config to avoid reloading
+let cachedConfig: any = null;
+
+/**
+ * Loads and caches the Bugmole MCP configuration
+ */
+function loadConfig(configPath: string = preferExisting("bugmole.config.yaml", "valkyrie.config.yaml")): any {
+  if (cachedConfig) {
+    return cachedConfig;
+  }
+
+  const scriptPath = fileURLToPath(import.meta.url);
+  const scriptDir = path.dirname(scriptPath);
+  const projectRoot = path.resolve(scriptDir, "../..");
+
+  // Change to project root to ensure relative paths work
+  const originalCwd = process.cwd();
+  process.chdir(projectRoot);
+
+  try {
+    dotenv.config({ quiet: true });
+
+    const fullConfigPath = path.join(projectRoot, configPath);
+    if (!fs.existsSync(fullConfigPath)) {
+      throw new Error(`Config file not found: ${fullConfigPath}`);
+    }
+
+    const raw = fs.readFileSync(fullConfigPath, "utf-8");
+    const parsed = YAML.parse(raw);
+
+    // Interpolate environment variables
+    cachedConfig = interpolateEnv(parsed);
+    return cachedConfig;
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
+// tiny ${ENV} interpolator for yaml configs
+function interpolateEnv(obj: any): any {
+  if (typeof obj === "string") {
+    return obj.replace(/\$\{([A-Z0-9_]+)(?::-([^}]+))?\}/g, (_, k, defaultValue) => {
+      const envValue = process.env[k];
+      if (envValue !== undefined && envValue !== "") {
+        return envValue;
+      }
+      return defaultValue !== undefined ? defaultValue : "";
+    });
+  }
+  if (Array.isArray(obj)) return obj.map(interpolateEnv);
+  if (obj && typeof obj === "object") {
+    const out: any = {};
+    for (const [k, v] of Object.entries(obj)) out[k] = interpolateEnv(v);
+    return out;
+  }
+  return obj;
+}
+
+/**
+ * Options for cursorLLM (all optional, uses config defaults)
+ */
+export interface CursorLLMOptions {
+  /**
+   * Custom config file path (default: bugmole.config.yaml)
+   */
+  configPath?: string;
+
+  /**
+   * Override MCP host (default: from config)
+   */
+  mcpHost?: string;
+
+  /**
+   * Override MCP port (default: from config)
+   */
+  mcpPort?: number;
+
+  /**
+   * Override artifacts directory (default: from config)
+   */
+  artifactsDir?: string;
+
+  /**
+   * Timeout in milliseconds (default: 300000 = 5 minutes)
+   */
+  timeout?: number;
+
+  /**
+   * Project directory to open in Cursor (default: from config)
+   */
+  projectDirectory?: string;
+
+  /**
+   * Request ID for tracking
+   */
+  requestId?: string;
+
+  /**
+   * Custom instructions to append before finalization protocol
+   */
+  customInstructions?: string;
+
+  /**
+   * Disable nudging (default: enabled)
+   */
+  disableNudging?: boolean;
+}
+
+/**
+ * Simple LLM-like interface - just pass a prompt
+ *
+ * @param prompt - The prompt/task to send to Cursor
+ * @param options - Optional overrides (uses config defaults)
+ * @returns The response text (markdown answer or summary)
+ *
+ * @example
+ * ```typescript
+ * import { cursorLLM } from './cursor-llm.js';
+ *
+ * const answer = await cursorLLM('Analyze the error handling in this codebase');
+ * console.log(answer);
+ * ```
+ */
+export async function cursorLLM(prompt: string, options: CursorLLMOptions = {}): Promise<string> {
+  const cfg = loadConfig(options.configPath);
+
+  const response = await runCursorDriver(prompt, {
+    mcpHost: options.mcpHost || cfg.mcp?.host || "127.0.0.1",
+    mcpPort: options.mcpPort || cfg.mcp?.port || 3187,
+    artifactsDir: options.artifactsDir || cfg.runtime?.artifacts_dir || "./runs",
+    timeout: options.timeout || 300000,
+    projectDirectory: options.projectDirectory || cfg.cursor_driver?.project_directory,
+    requestId: options.requestId,
+    customInstructions: options.customInstructions,
+    nudgeOptions: options.disableNudging ? { enabled: false } : undefined,
+  });
+
+  if (!response.success || !response.payload) {
+    throw new Error(response.error || "Cursor driver failed to complete task");
+  }
+
+  return response.payload.answer_markdown || response.payload.summary;
+}
+
+/**
+ * LLM-like interface that returns structured response
+ *
+ * @param prompt - The prompt/task to send to Cursor
+ * @param options - Optional overrides (uses config defaults)
+ * @returns Full structured response with actions and artifacts
+ *
+ * @example
+ * ```typescript
+ * import { cursorLLMStructured } from './cursor-llm.js';
+ *
+ * const response = await cursorLLMStructured('Review test failures and propose fixes');
+ * if (response.success) {
+ *   console.log('Actions:', response.payload?.actions);
+ *   console.log('Answer:', response.payload?.answer_markdown);
+ * }
+ * ```
+ */
+export async function cursorLLMStructured(
+  prompt: string,
+  options: CursorLLMOptions = {},
+): Promise<CursorDriverResponse> {
+  const cfg = loadConfig(options.configPath);
+
+  return runCursorDriver(prompt, {
+    mcpHost: options.mcpHost || cfg.mcp?.host || "127.0.0.1",
+    mcpPort: options.mcpPort || cfg.mcp?.port || 3187,
+    artifactsDir: options.artifactsDir || cfg.runtime?.artifacts_dir || "./runs",
+    timeout: options.timeout || 300000,
+    projectDirectory: options.projectDirectory || cfg.cursor_driver?.project_directory,
+    requestId: options.requestId,
+    customInstructions: options.customInstructions,
+    nudgeOptions: options.disableNudging ? { enabled: false } : undefined,
+  });
+}
+
+/**
+ * Reset the config cache (useful for testing or when config changes)
+ */
+export function resetConfigCache(): void {
+  cachedConfig = null;
+}

package/src/runtime/cursor-mcp-monitor.ts

@@ -0,0 +1,386 @@
+/**
+ * MCP commit response monitor
+ *
+ * Polls the MCP server for commit responses from Cursor.
+ * This is how we receive structured output from Cursor tasks.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import http from "node:http";
+
+export interface CommitResponse {
+  id: string;
+  timestamp: string;
+  payload: {
+    status: "ok" | "error";
+    summary: string;
+    answer_markdown?: string;
+    actions?: Array<{
+      type: "edit" | "create" | "delete" | "command";
+      target: string;
+      details: string;
+    }>;
+    artifacts?: Array<{
+      type: "patch" | "config" | "command" | "note";
+      content: string;
+    }>;
+    next_steps?: string[];
+  };
+}
+
+export interface ProgressReport {
+  id: string;
+  timestamp: string;
+  status: "working" | "blocked" | "completed";
+  message: string;
+  details?: string;
+  estimated_time_remaining?: string;
+}
+
+export interface MonitorOptions {
+  /**
+   * MCP server host
+   * @default '127.0.0.1'
+   */
+  host?: string;
+
+  /**
+   * MCP server port
+   * @default 3187
+   */
+  port?: number;
+
+  /**
+   * Artifacts directory where commits are stored
+   */
+  artifactsDir: string;
+
+  /**
+   * Polling interval in ms
+   * @default 1000
+   */
+  pollInterval?: number;
+
+  /**
+   * Maximum wait time in ms
+   * @default 300000 (5 minutes)
+   */
+  timeout?: number;
+
+  /**
+   * Request ID to filter commits (optional)
+   */
+  requestId?: string;
+
+  /**
+   * Nudge configuration for inactivity detection
+   */
+  nudgeOptions?: {
+    enabled?: boolean;
+    /**
+     * Time without progress report before nudging (default: 300000 = 5 minutes)
+     */
+    progressReportTimeout?: number;
+    /**
+     * Minimum time between nudges (default: 120000 = 2 minutes)
+     */
+    nudgeInterval?: number;
+    maxNudges?: number;
+    customMessage?: string;
+    onNudge?: (nudgeCount: number) => Promise<void>;
+  };
+}
+
+/**
+ * Reads a commit file from the artifacts directory
+ */
+function readCommitFile(filePath: string): CommitResponse | null {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+
+    const content = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(content) as CommitResponse;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lists all commit files in the cursor_commits directory
+ */
+function listCommitFiles(artifactsDir: string): string[] {
+  const commitDir = path.join(artifactsDir, "cursor_commits");
+
+  if (!fs.existsSync(commitDir)) {
+    return [];
+  }
+
+  try {
+    return fs
+      .readdirSync(commitDir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => path.join(commitDir, f))
+      .sort((a, b) => {
+        // Sort by modification time (newest first)
+        const statA = fs.statSync(a);
+        const statB = fs.statSync(b);
+        return statB.mtimeMs - statA.mtimeMs;
+      });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Lists all progress report files in the progress_reports directory
+ */
+function listProgressReportFiles(artifactsDir: string): string[] {
+  const progressDir = path.join(artifactsDir, "progress_reports");
+
+  if (!fs.existsSync(progressDir)) {
+    return [];
+  }
+
+  try {
+    return fs
+      .readdirSync(progressDir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => path.join(progressDir, f))
+      .sort((a, b) => {
+        // Sort by modification time (newest first)
+        const statA = fs.statSync(a);
+        const statB = fs.statSync(b);
+        return statB.mtimeMs - statA.mtimeMs;
+      });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Reads a progress report file
+ */
+function readProgressReportFile(filePath: string): ProgressReport | null {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+
+    const content = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(content) as ProgressReport;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gets the most recent progress report after a given timestamp
+ */
+function getLatestProgressReport(
+  artifactsDir: string,
+  afterTimestamp: number,
+): ProgressReport | null {
+  const progressFiles = listProgressReportFiles(artifactsDir);
+
+  for (const filePath of progressFiles) {
+    const report = readProgressReportFile(filePath);
+    if (!report) continue;
+
+    const reportTime = new Date(report.timestamp).getTime();
+    if (reportTime >= afterTimestamp) {
+      return report;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Checks MCP server health
+ */
+async function checkMcpHealth(host: string, port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const req = http.get(`http://${host}:${port}/health`, (res) => {
+      resolve(res.statusCode === 200);
+    });
+
+    req.on("error", () => resolve(false));
+    req.setTimeout(2000, () => {
+      req.destroy();
+      resolve(false);
+    });
+  });
+}
+
+/**
+ * Monitors for a commit response from Cursor
+ *
+ * Polls the artifacts directory for new commit files.
+ * Returns the first commit that appears after the start time.
+ * Includes nudge mechanism to detect and handle inactivity.
+ */
+export async function waitForCommitResponse(options: MonitorOptions): Promise<CommitResponse> {
+  const {
+    host = "127.0.0.1",
+    port = 3187,
+    artifactsDir,
+    pollInterval = 1000,
+    timeout = 300000,
+    requestId,
+    nudgeOptions,
+  } = options;
+
+  const startTime = Date.now();
+  const seenCommitIds = new Set<string>();
+
+  // Nudge tracking - now based on progress reports
+  const nudgeEnabled = nudgeOptions?.enabled !== false;
+  const progressReportTimeout = nudgeOptions?.progressReportTimeout ?? 300000; // 5 minutes default - only nudge if no progress report for this long
+  const nudgeInterval = nudgeOptions?.nudgeInterval ?? 120000; // 2 minutes minimum between nudges
+  const maxNudges = nudgeOptions?.maxNudges ?? 10;
+  const customMessage = nudgeOptions?.customMessage;
+  const onNudge = nudgeOptions?.onNudge;
+
+  let lastProgressReportTime = startTime;
+  let lastNudgeTime = 0;
+  let nudgeCount = 0;
+
+  // First, verify MCP server is running
+  const isHealthy = await checkMcpHealth(host, port);
+  if (!isHealthy) {
+    throw new Error(`MCP server at ${host}:${port} is not responding`);
+  }
+
+  return new Promise((resolve, reject) => {
+    const poll = async () => {
+      const now = Date.now();
+
+      // Check timeout
+      if (now - startTime > timeout) {
+        reject(new Error(`Timeout waiting for commit response after ${timeout}ms`));
+        return;
+      }
+
+      // List commit files
+      const commitFiles = listCommitFiles(artifactsDir);
+
+      // Check each commit file
+      let foundNewCommit = false;
+      for (const filePath of commitFiles) {
+        const commit = readCommitFile(filePath);
+        if (!commit) continue;
+
+        // Skip if we've already seen this commit
+        if (seenCommitIds.has(commit.id)) {
+          continue;
+        }
+
+        // Check if commit is after start time (new commit)
+        const commitTime = new Date(commit.timestamp).getTime();
+        if (commitTime >= startTime) {
+          // If requestId is specified, check if it matches
+          // (This would require requestId to be embedded in the commit payload)
+          // For now, we just return the first new commit
+
+          seenCommitIds.add(commit.id);
+          foundNewCommit = true;
+          resolve(commit);
+          return;
+        }
+      }
+
+      // Check for progress reports (even if no commit yet)
+      const latestProgressReport = getLatestProgressReport(artifactsDir, startTime);
+      if (latestProgressReport) {
+        const reportTime = new Date(latestProgressReport.timestamp).getTime();
+        if (reportTime > lastProgressReportTime) {
+          lastProgressReportTime = reportTime;
+          console.log(
+            `[CURSOR_DRIVER] Progress report received: ${latestProgressReport.status} - ${latestProgressReport.message}`,
+          );
+        }
+      }
+
+      if (!foundNewCommit) {
+        // Add grace period before checking for MCP tool calls
+        // Planning models may take 10-30 seconds to think before calling tools
+        // Only start checking after initial grace period has passed
+        const gracePeriod = 15000; // 15 seconds grace period for planning models
+        const timeSinceStart = now - startTime;
+
+        if (timeSinceStart >= gracePeriod) {
+          // Periodically try to approve MCP tool dialogs that might be waiting
+          // Cursor sometimes shows confirmation dialogs for MCP tool execution
+          // But only after grace period to avoid interrupting model's thinking
+          try {
+            const { approveMcpTool } = await import("./cursor-applescript.js");
+            await approveMcpTool();
+          } catch (error: any) {
+            // Non-critical - approval might not be needed
+          }
+        }
+
+        // Check if we haven't received a progress report for too long
+        // Only nudge if no progress report has been received for the timeout period
+        const timeSinceLastProgressReport = now - lastProgressReportTime;
+        const timeSinceLastNudge = now - lastNudgeTime;
+
+        if (
+          nudgeEnabled &&
+          timeSinceLastProgressReport >= progressReportTimeout &&
+          timeSinceLastNudge >= nudgeInterval &&
+          nudgeCount < maxNudges
+        ) {
+          // Send nudge - agent hasn't reported progress for a while
+          nudgeCount++;
+          lastNudgeTime = now;
+
+          console.log(
+            `[CURSOR_DRIVER] Sending nudge #${nudgeCount} (no progress report for ${Math.round(
+              timeSinceLastProgressReport / 1000,
+            )}s)`,
+          );
+
+          try {
+            if (onNudge) {
+              await onNudge(nudgeCount);
+            } else {
+              // Default nudge implementation
+              const { sendNudge } = await import("./cursor-applescript.js");
+              const message =
+                customMessage ||
+                "Please continue working on the task. If you are still working, please call bugmole_report_progress to let me know. Remember to call bugmole_commit_response when you are fully finished.";
+              await sendNudge(message);
+            }
+          } catch (error: any) {
+            console.warn(`[CURSOR_DRIVER] Failed to send nudge: ${error.message}`);
+          }
+        }
+      }
+
+      // No new commit yet, poll again
+      setTimeout(poll, pollInterval);
+    };
+
+    // Start polling
+    poll();
+  });
+}
+
+/**
+ * Gets the most recent commit response
+ */
+export function getLatestCommit(artifactsDir: string): CommitResponse | null {
+  const commitFiles = listCommitFiles(artifactsDir);
+
+  if (commitFiles.length === 0) {
+    return null;
+  }
+
+  // Get the most recent file
+  const latestFile = commitFiles[0];
+  return readCommitFile(latestFile);
+}