@bugmole/cli 0.4.0

package/src/runtime/cursor-driver-run.ts

@@ -0,0 +1,323 @@
+/**
+ * CURSOR_DRIVER main execution function
+ *
+ * This is the LLM API adapter that replaces traditional LLM calls.
+ * It orchestrates the full flow:
+ * 1. Generate prompt with finalization protocol
+ * 2. Inject prompt into Cursor via AppleScript
+ * 3. Monitor MCP server for commit response
+ * 4. Return structured response
+ */
+
+import {
+  generateCursorDriverPrompt,
+  validateCommitPayload,
+  CursorDriverResponse,
+  CursorDriverRunOptions,
+} from "./cursor-driver.js";
+import { injectPrompt, isCursorRunning, openCursorInDirectory } from "./cursor-applescript.js";
+import { waitForCommitResponse } from "./cursor-mcp-monitor.js";
+import { runCursorCliDriver, type CursorCliDriverOptions } from "./cursor-cli-driver.js";
+import { ControlPlaneClient, isClaimableTask, type RegistryTask } from "../registry/control-plane-client.js";
+
+/**
+ * Main CURSOR_DRIVER function - acts as an LLM API adapter
+ *
+ * @param task - The task/prompt to send to Cursor
+ * @param options - Configuration options
+ * @returns Structured response from Cursor
+ */
+export async function runCursorDriver(
+  task: string,
+  options: CursorDriverRunOptions,
+): Promise<CursorDriverResponse> {
+  const {
+    mcpHost = "127.0.0.1",
+    mcpPort = 3187,
+    artifactsDir,
+    timeout = 300000,
+    pollInterval = 1000,
+    injectionOptions = {},
+    ...promptOptions
+  } = options;
+
+  try {
+    // Step 1: Open Cursor in project directory if specified
+    if (options.projectDirectory) {
+      console.log(`[CURSOR_DRIVER] Opening Cursor in directory: ${options.projectDirectory}`);
+      await openCursorInDirectory(options.projectDirectory);
+      // Wait for Cursor workspace to load AND for MCP tools to initialize
+      // This is critical - MCP tools must be available before injecting prompts
+      console.log("[CURSOR_DRIVER] Waiting for workspace and MCP tools to initialize...");
+      await new Promise((resolve) => setTimeout(resolve, 5000));
+      console.log("[CURSOR_DRIVER] Workspace and MCP tools should be ready");
+    }
+
+    // Step 2: Verify Cursor is running
+    const cursorRunning = await isCursorRunning();
+    if (!cursorRunning) {
+      return {
+        success: false,
+        error: "Cursor application is not running",
+        errorCode: "MCP_UNAVAILABLE",
+      };
+    }
+
+    // Step 3: Generate prompt with finalization protocol
+    const fullPrompt = generateCursorDriverPrompt(task, promptOptions);
+    console.log("[CURSOR_DRIVER] Generated prompt with finalization protocol");
+
+    // Step 4: Inject prompt into Cursor
+    console.log("[CURSOR_DRIVER] Injecting prompt into Cursor...");
+    await injectPrompt(fullPrompt, {
+      ...injectionOptions,
+      mcpHost,
+      mcpPort,
+    });
+    console.log("[CURSOR_DRIVER] Prompt injected successfully");
+
+    // Step 4.5: Grace period for planning models
+    // Planning models (like GPT-4) may take 10-30 seconds to think before calling MCP tools
+    // Give them time to process before we start monitoring
+    const gracePeriod = 15000; // 15 seconds
+    console.log(
+      `[CURSOR_DRIVER] Waiting ${gracePeriod / 1000}s grace period for model to process...`,
+    );
+    await new Promise((resolve) => setTimeout(resolve, gracePeriod));
+    console.log("[CURSOR_DRIVER] Grace period complete, starting to monitor...");
+
+    // Step 5: Monitor for commit response
+    console.log("[CURSOR_DRIVER] Waiting for commit response...");
+
+    // Set up nudge callback (enabled by default unless explicitly disabled)
+    const nudgeOptions = options.nudgeOptions;
+    const nudgeEnabled = nudgeOptions?.enabled !== false; // Default to true
+    let nudgeCallback: ((nudgeCount: number) => Promise<void>) | undefined;
+
+    if (nudgeEnabled) {
+      // Import sendNudge dynamically to avoid circular dependencies
+      const { sendNudge } = await import("./cursor-applescript.js");
+      const nudgeMessage =
+        nudgeOptions?.customMessage ||
+        "Please continue working on the task. Remember to call bugmole_commit_response when you are fully finished.";
+
+      nudgeCallback = async (nudgeCount: number) => {
+        await sendNudge(nudgeMessage);
+      };
+    }
+
+    const commit = await waitForCommitResponse({
+      host: mcpHost,
+      port: mcpPort,
+      artifactsDir,
+      timeout,
+      pollInterval,
+      requestId: promptOptions.requestId,
+      nudgeOptions: {
+        enabled: nudgeEnabled,
+        progressReportTimeout: nudgeOptions?.progressReportTimeout,
+        nudgeInterval: nudgeOptions?.nudgeInterval,
+        maxNudges: nudgeOptions?.maxNudges,
+        customMessage: nudgeOptions?.customMessage,
+        onNudge: nudgeCallback,
+      },
+    });
+
+    console.log(`[CURSOR_DRIVER] Received commit: ${commit.id}`);
+
+    // Step 6: Validate payload
+    const validation = validateCommitPayload(commit.payload);
+    if (!validation.valid) {
+      return {
+        success: false,
+        commitId: commit.id,
+        error: `Payload validation failed: ${validation.errors.join(", ")}`,
+        errorCode: "VALIDATION_FAILED",
+      };
+    }
+
+    // Step 7: Return structured response
+    return {
+      success: true,
+      commitId: commit.id,
+      payload: commit.payload,
+    };
+  } catch (error: any) {
+    // Handle timeout
+    if (error.message?.includes("Timeout")) {
+      return {
+        success: false,
+        error: error.message,
+        errorCode: "TIMEOUT",
+      };
+    }
+
+    // Handle MCP unavailable
+    if (error.message?.includes("not responding") || error.message?.includes("MCP")) {
+      return {
+        success: false,
+        error: error.message,
+        errorCode: "MCP_UNAVAILABLE",
+      };
+    }
+
+    // Handle injection failures
+    if (error.message?.includes("inject") || error.message?.includes("AppleScript")) {
+      return {
+        success: false,
+        error: error.message,
+        errorCode: "INJECTION_FAILED",
+      };
+    }
+
+    // Generic error
+    return {
+      success: false,
+      error: error.message || "Unknown error",
+    };
+  }
+}
+
+/**
+ * Runs a prompt through a real coding agent, preferring the headless
+ * `cursor-agent` CLI (no GUI, no accessibility permissions, no polling) and
+ * falling back to the AppleScript-driven Cursor GUI automation only when the
+ * CLI is unavailable on this machine.
+ */
+export async function runCursorAgent(
+  task: string,
+  options: CursorDriverRunOptions & Partial<CursorCliDriverOptions>,
+): Promise<CursorDriverResponse> {
+  const cliResponse = await runCursorCliDriver(task, {
+    ...options,
+    workspaceDirectory: options.workspaceDirectory ?? options.projectDirectory,
+  });
+  if (!shouldFallBackToCursorGui(cliResponse)) return cliResponse;
+  return runCursorDriver(task, options);
+}
+
+/**
+ * The GUI fallback drives the Cursor app through AppleScript, which exists only on macOS. On a
+ * Linux worker a missing `cursor-agent` is reported as-is instead of failing inside osascript.
+ */
+export function shouldFallBackToCursorGui(response: CursorDriverResponse, platform: NodeJS.Platform = process.platform): boolean {
+  return !response.success && response.errorCode === "MCP_UNAVAILABLE" && platform === "darwin";
+}
+
+export async function runNextAgentTask(
+  options: CursorDriverRunOptions & {
+    registryUrl: string;
+    apiKey: string;
+    projectId: string;
+    workerId: string;
+  },
+): Promise<{ task: RegistryTask | null; response?: CursorDriverResponse; message?: string }> {
+  const client = new ControlPlaneClient({
+    registryUrl: options.registryUrl,
+    apiKey: options.apiKey,
+    projectId: options.projectId,
+  });
+  const available = await client.listTasks();
+  // Discovery tasks are run by the worker's own browser, not a coding agent.
+  const next = available.tasks.find((task) => task.taskType !== "discovery" && isClaimableTask(task));
+  if (!next) return { task: null, message: "No queued agent task is available." };
+  // Losing a claim is a normal race, not a failure: another worker got
+  // there first, or the task changed state between listing and claiming.
+  // Letting it throw aborted the whole poll, which also skipped the
+  // pipeline reconciliation that runs afterwards — one contended task
+  // stalled all forward progress.
+  let claimed: Awaited<ReturnType<typeof client.claimTask>>;
+  try {
+    claimed = await client.claimTask(next.id, options.workerId);
+  } catch (error) {
+    return {
+      task: null,
+      message: `Could not claim ${next.id}: ${error instanceof Error ? error.message : "claim rejected"}`,
+    };
+  }
+  const taskPrompt = [
+    `Continue the Bugmole dashboard task "${next.title}".`,
+    "",
+    next.description,
+    "",
+    "Read bugmole://guidance/agent-task-queue before acting.",
+    "Report progress as you work and use bugmole_task_update for the final status.",
+    next.taskType === "ui"
+      ? "This is a UI task: rerun parity after the fix and do not complete without a fresh parity audit id and match score."
+      : "",
+  ].filter(Boolean).join("\n");
+  // Pass the task type through so a long exploration gets the longer CLI
+  // budget instead of being SIGTERM'd at the short default mid-flight.
+  // Keep the lease fresh for as long as the agent is genuinely working.
+  // Without this a long exploration would outlive its 60s lease and look
+  // abandoned, and the stale-lease recovery below would hand the same task
+  // to another worker while the first was still running it.
+  const heartbeat = setInterval(() => {
+    void client.updateTask(next.id, {
+      workerId: options.workerId,
+      status: "running",
+      progressMessage: `Working on "${next.title}"…`,
+    }).catch(() => undefined);
+  }, 30_000);
+  if (typeof heartbeat.unref === "function") heartbeat.unref();
+
+  let response: CursorDriverResponse;
+  try {
+    response = await runCursorAgent(taskPrompt, { ...options, taskType: next.taskType });
+  } finally {
+    clearInterval(heartbeat);
+  }
+  if (!response.success) {
+    await client.updateTask(next.id, {
+      workerId: options.workerId,
+      status: "blocked",
+      errorMessage: response.error ?? "Cursor task execution failed",
+      progressMessage: "Cursor execution stopped; task can be continued.",
+    });
+    return { task: claimed.task, response };
+  }
+
+  // The agent is supposed to close its own task, but nothing guaranteed it
+  // did — and a task left "running" blocks the pipeline forever, since the
+  // reconciler treats an in-flight task as a reason not to queue the next
+  // stage. Close it here only if the agent did not, so a self-reported
+  // status (with its parity evidence and summary) always wins.
+  const after = await client.listTasks().catch(() => null);
+  const current = after?.tasks.find((task) => task.id === next.id);
+  if (current && current.status !== "completed" && current.status !== "error") {
+    await client.updateTask(next.id, {
+      workerId: options.workerId,
+      status: "completed",
+      completionSummary: response.payload?.summary
+        ?? "Worker completed the task; the agent did not report a status.",
+    }).catch(() => undefined);
+  }
+  return { task: claimed.task, response };
+}
+
+/**
+ * Convenience function for simple text completion (LLM API-like interface)
+ */
+export async function cursorComplete(
+  prompt: string,
+  options: CursorDriverRunOptions,
+): Promise<string> {
+  const response = await runCursorDriver(prompt, options);
+
+  if (!response.success || !response.payload) {
+    throw new Error(response.error || "Cursor driver failed to complete task");
+  }
+
+  // Return the markdown answer, or summary as fallback
+  return response.payload.answer_markdown || response.payload.summary;
+}
+
+/**
+ * Convenience function for structured completion (returns full payload)
+ */
+export async function cursorCompleteStructured(
+  prompt: string,
+  options: CursorDriverRunOptions,
+): Promise<CursorDriverResponse> {
+  return runCursorDriver(prompt, options);
+}

package/src/runtime/cursor-driver.ts

@@ -0,0 +1,332 @@
+/**
+ * CURSOR_DRIVER utilities
+ *
+ * Provides functions for generating prompts that enforce the mandatory
+ * MCP finalization protocol, ensuring deterministic completion signals.
+ */
+
+export interface CursorDriverOptions {
+  /**
+   * Whether to include the mandatory finalization protocol
+   * @default true
+   */
+  includeFinalization?: boolean;
+
+  /**
+   * Custom instructions to append before the finalization protocol
+   */
+  customInstructions?: string;
+
+  /**
+   * Request ID for tracking parallel runs
+   */
+  requestId?: string;
+}
+
+/**
+ * Generates the mandatory MCP finalization protocol footer
+ * that must be appended to all CURSOR_DRIVER prompts.
+ */
+export function generateFinalizationProtocol(options: CursorDriverOptions = {}): string {
+  const { requestId } = options;
+
+  let protocol = "\n\n⸻\n\n";
+
+  if (requestId) {
+    protocol += `REQUEST_ID: ${requestId}\n\n`;
+  }
+
+  protocol += `MCP FINALIZATION (MANDATORY)\n\n`;
+
+  protocol += `PROGRESS REPORTING:\n`;
+  protocol += `- For long-running tasks (more than 2-3 minutes), periodically call bugmole_report_progress every 2-3 minutes.\n`;
+  protocol += `- This lets the framework know you are still working and prevents unnecessary nudges.\n`;
+  protocol += `- Use bugmole_report_progress with status "working", "blocked", or "completed".\n`;
+  protocol += `- Only nudge if you have not reported progress for an extended period.\n\n`;
+
+  protocol += `INCREMENTAL JOURNEY EXPLORATION:\n`;
+  protocol += `- After every bugmole_explore or bugmole_record_discovery call, inspect the selected flow with bugmole_journey_get.\n`;
+  protocol += `- Call bugmole_journey_next, perform its actionable task, and record the observed step/transition.\n`;
+  protocol += `- Repeat until bugmole_journey_next returns exhausted or an explicit blocked reason; do not plan from an unchecked actionable flow.\n\n`;
+
+  protocol += `COMPLETION:\n`;
+  protocol += `1. Perform all reasoning and work first.\n`;
+  protocol += `2. CRITICAL RULE: If your answer mentions "Next Steps", "TODO", "should do", "need to", "use bugmole_", or any future actions, you MUST include them in "next_steps" array.\n`;
+  protocol += `3. The "next_steps" field is MANDATORY if you describe any remaining work, even in answer_markdown.\n`;
+  protocol += `4. ONLY omit "next_steps" when EVERYTHING is 100% done and NO further work exists.\n`;
+  protocol += `5. When fully finished (with no more work), call bugmole_commit_response exactly once.\n`;
+  protocol += `6. The final answer MUST be included only in the tool payload.\n`;
+  protocol += `7. Do NOT print the final answer in chat.\n`;
+  protocol += `8. The payload must be valid JSON. Use this SIMPLE format (all fields except status/summary are optional):\n\n`;
+
+  protocol += `MINIMAL EXAMPLE (use this if you're unsure):\n`;
+  protocol += `{\n`;
+  protocol += `  "status": "ok",\n`;
+  protocol += `  "summary": "What you did",\n`;
+  protocol += `  "next_steps": ["Next action if any"]\n`;
+  protocol += `}\n\n`;
+
+  protocol += `EXAMPLE WITH NEXT STEPS:\n`;
+  protocol += `{\n`;
+  protocol += `  "status": "ok",\n`;
+  protocol += `  "summary": "Investigated project, ready for exploration",\n`;
+  protocol += `  "next_steps": [\n`;
+  protocol += `    "Run bugmole_explore with baseUrl=http://localhost:8000",\n`;
+  protocol += `    "Create test plans for discovered journeys"\n`;
+  protocol += `  ]\n`;
+  protocol += `}\n\n`;
+
+  protocol += `FULL SCHEMA (only include fields you have):\n`;
+  protocol += `{\n`;
+  protocol += `  "status": "ok" | "error",  // REQUIRED\n`;
+  protocol += `  "summary": "Short summary",  // REQUIRED\n`;
+  protocol += `  "answer_markdown": "Optional full answer",  // OPTIONAL\n`;
+  protocol += `  "actions": [],  // OPTIONAL - only if you made changes\n`;
+  protocol += `  "artifacts": [],  // OPTIONAL - only if you created artifacts\n`;
+  protocol += `  "next_steps": []  // OPTIONAL - only if more work remains\n`;
+  protocol += `}\n\n`;
+
+  protocol += `SIMPLE RULES:\n`;
+  protocol += `- Only "status" and "summary" are required\n`;
+  protocol += `- Everything else is optional - only include if you have it\n`;
+  protocol += `- Keep it simple - smaller JSON is easier to generate correctly\n`;
+  protocol += `- If you have next steps, include them as an array of strings\n\n`;
+
+  protocol += `⚠️ CRITICAL RULE ABOUT next_steps:\n`;
+  protocol += `- If you write ANY section titled "Next Steps", "TODO", "Remaining Work", or list future actions, you MUST include them in "next_steps".\n`;
+  protocol += `- If you mention commands like "use bugmole_explore", "run bugmole_plan", "execute bugmole_run", these MUST be in "next_steps".\n`;
+  protocol += `- If you say "should do", "need to", "next", "then", these indicate remaining work → include in "next_steps".\n`;
+  protocol += `- Example: If you write "Next: Run bugmole_explore", then next_steps MUST be: ["Run bugmole_explore with baseUrl=http://localhost:8000"]\n`;
+  protocol += `- ONLY omit "next_steps" when you have completed EVERYTHING and there is ZERO remaining work.\n`;
+  protocol += `- When in doubt, include next_steps. It's better to continue than to stop prematurely.\n\n`;
+
+  protocol += `💡 TIP FOR SMALLER MODELS: Keep it simple!\n`;
+  protocol += `- Minimal example: {"status": "ok", "summary": "Done", "next_steps": ["Continue with X"]}\n`;
+  protocol += `- Don't worry about actions/artifacts if you don't have them\n`;
+  protocol += `- Focus on getting status, summary, and next_steps correct\n\n`;
+
+  protocol += `9. If MCP tools are unavailable, output exactly: MCP_UNAVAILABLE\n\n`;
+
+  protocol += `⸻\n`;
+
+  return protocol;
+}
+
+/**
+ * Appends the mandatory finalization protocol to a prompt.
+ * This is the primary function for preparing CURSOR_DRIVER prompts.
+ */
+export function appendFinalizationProtocol(
+  prompt: string,
+  options: CursorDriverOptions = {},
+): string {
+  const { includeFinalization = true, customInstructions } = options;
+
+  if (!includeFinalization) {
+    return prompt;
+  }
+
+  let finalPrompt = prompt;
+
+  if (customInstructions) {
+    finalPrompt += `\n\n${customInstructions}\n`;
+  }
+
+  finalPrompt += generateFinalizationProtocol(options);
+
+  return finalPrompt;
+}
+
+/**
+ * Validates that a commit response payload matches the expected schema.
+ * This is intentionally lenient - only status and summary are required.
+ * All other fields are optional and validation is forgiving.
+ */
+export function validateCommitPayload(payload: any): {
+  valid: boolean;
+  errors: string[];
+} {
+  const errors: string[] = [];
+
+  if (!payload || typeof payload !== "object") {
+    errors.push("Payload must be an object");
+    return { valid: false, errors };
+  }
+
+  // Only status and summary are required
+  if (!payload.status || !["ok", "error"].includes(payload.status)) {
+    errors.push('status must be "ok" or "error"');
+  }
+
+  if (!payload.summary || typeof payload.summary !== "string") {
+    errors.push("summary is required and must be a string");
+  }
+
+  // Everything else is optional - only validate if present
+  if (payload.actions !== undefined) {
+    if (!Array.isArray(payload.actions)) {
+      errors.push("actions must be an array if provided");
+    } else {
+      // Only validate action structure if actions array exists
+      payload.actions.forEach((action: any, index: number) => {
+        if (action && typeof action === "object") {
+          if (action.type && !["edit", "create", "delete", "command"].includes(action.type)) {
+            errors.push(`actions[${index}].type must be one of: edit, create, delete, command`);
+          }
+        }
+        // If action is malformed, we'll just skip it rather than fail validation
+      });
+    }
+  }
+
+  if (payload.artifacts !== undefined) {
+    if (!Array.isArray(payload.artifacts)) {
+      errors.push("artifacts must be an array if provided");
+    } else {
+      // Only validate artifact structure if artifacts array exists
+      payload.artifacts.forEach((artifact: any, index: number) => {
+        if (artifact && typeof artifact === "object") {
+          if (artifact.type && !["patch", "config", "command", "note"].includes(artifact.type)) {
+            errors.push(`artifacts[${index}].type must be one of: patch, config, command, note`);
+          }
+        }
+        // If artifact is malformed, we'll just skip it rather than fail validation
+      });
+    }
+  }
+
+  // next_steps is optional - if present, should be an array of strings
+  if (payload.next_steps !== undefined && !Array.isArray(payload.next_steps)) {
+    errors.push("next_steps must be an array if provided");
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Generates a complete CURSOR_DRIVER prompt with task and finalization protocol.
+ */
+export function generateCursorDriverPrompt(
+  task: string,
+  options: CursorDriverOptions = {},
+): string {
+  return appendFinalizationProtocol(task, options);
+}
+
+/**
+ * CURSOR_DRIVER response structure
+ */
+export interface CursorDriverResponse {
+  success: boolean;
+  commitId?: 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[];
+  };
+  error?: string;
+  errorCode?: "TIMEOUT" | "MCP_UNAVAILABLE" | "INJECTION_FAILED" | "VALIDATION_FAILED";
+}
+
+/**
+ * CURSOR_DRIVER options for the main driver function
+ */
+export interface CursorDriverRunOptions extends CursorDriverOptions {
+  /**
+   * Task type of the work being run. Drives the CLI timeout default, since
+   * an exploration needs far longer than a small code edit.
+   */
+  taskType?: string;
+
+  /**
+   * MCP server host
+   * @default '127.0.0.1'
+   */
+  mcpHost?: string;
+
+  /**
+   * MCP server port
+   * @default 3187
+   */
+  mcpPort?: number;
+
+  /**
+   * Artifacts directory
+   */
+  artifactsDir: string;
+
+  /**
+   * Timeout for waiting for commit response (ms)
+   * @default 300000 (5 minutes)
+   */
+  timeout?: number;
+
+  /**
+   * Polling interval for checking commits (ms)
+   * @default 1000
+   */
+  pollInterval?: number;
+
+  /**
+   * AppleScript injection options
+   */
+  injectionOptions?: {
+    pasteDelay?: number;
+    submitDelay?: number;
+    maxRetries?: number;
+  };
+
+  /**
+   * Nudge configuration for when model stops working
+   * Nudges are only sent if no progress report is received for an extended period
+   */
+  nudgeOptions?: {
+    /**
+     * Enable nudging when model appears inactive
+     * @default true
+     */
+    enabled?: boolean;
+
+    /**
+     * Time in ms without progress report before sending first nudge
+     * @default 300000 (5 minutes)
+     */
+    progressReportTimeout?: number;
+
+    /**
+     * Minimum interval between nudges in ms
+     * @default 120000 (2 minutes)
+     */
+    nudgeInterval?: number;
+
+    /**
+     * Maximum number of nudges to send
+     * @default 10
+     */
+    maxNudges?: number;
+
+    /**
+     * Custom nudge message (optional)
+     */
+    customMessage?: string;
+  };
+
+  /**
+   * Project directory to open in Cursor before testing
+   * If specified, will open a new Cursor window in this directory
+   */
+  projectDirectory?: string;
+}