@litmers/cursorflow-orchestrator 0.1.8 → 0.1.12

package/src/cli/resume.ts

@@ -9,12 +9,31 @@ import * as logger from '../utils/logger';
 import { loadConfig, getLogsDir } from '../utils/config';
 import { loadState } from '../utils/state';
 import { LaneState } from '../utils/types';
+import { runDoctor } from '../utils/doctor';
 
 interface ResumeOptions {
   lane: string | null;
   runDir: string | null;
   clean: boolean;
   restart: boolean;
+  skipDoctor: boolean;
+  help: boolean;
+}
+
+function printHelp(): void {
+  console.log(`
+Usage: cursorflow resume <lane> [options]
+
+Resume an interrupted or failed lane.
+
+Options:
+  <lane>                 Lane name to resume
+  --run-dir <path>       Use a specific run directory (default: latest)
+  --clean                Clean up existing worktree before resuming
+  --restart              Restart from the first task (index 0)
+  --skip-doctor          Skip environment/branch checks (not recommended)
+  --help, -h             Show help
+  `);
 }
 
 function parseArgs(args: string[]): ResumeOptions {
@@ -25,6 +44,8 @@ function parseArgs(args: string[]): ResumeOptions {
     runDir: runDirIdx >= 0 ? args[runDirIdx + 1] || null : null,
     clean: args.includes('--clean'),
     restart: args.includes('--restart'),
+    skipDoctor: args.includes('--skip-doctor') || args.includes('--no-doctor'),
+    help: args.includes('--help') || args.includes('-h'),
   };
 }
 
@@ -45,6 +66,12 @@ function findLatestRunDir(logsDir: string): string | null {
 
 async function resume(args: string[]): Promise<void> {
   const options = parseArgs(args);
+  
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
   const config = loadConfig();
   const logsDir = getLogsDir(config);
   
@@ -77,6 +104,45 @@ async function resume(args: string[]): Promise<void> {
     throw new Error(`Original tasks file not found: ${state.tasksFile}. Resume impossible without task definition.`);
   }
   
+  // Run doctor check before resuming (check branches, etc.)
+  if (!options.skipDoctor) {
+    const tasksDir = path.dirname(state.tasksFile);
+    logger.info('Running pre-flight checks...');
+    
+    const report = runDoctor({
+      cwd: process.cwd(),
+      tasksDir,
+      includeCursorAgentChecks: false, // Skip agent checks for resume
+    });
+    
+    // Only show blocking errors for resume
+    const blockingIssues = report.issues.filter(i => 
+      i.severity === 'error' && 
+      (i.id.startsWith('branch.') || i.id.startsWith('git.'))
+    );
+    
+    if (blockingIssues.length > 0) {
+      logger.section('🛑 Pre-resume check found issues');
+      for (const issue of blockingIssues) {
+        logger.error(`${issue.title} (${issue.id})`, '❌');
+        console.log(`   ${issue.message}`);
+        if (issue.details) console.log(`   Details: ${issue.details}`);
+        if (issue.fixes?.length) {
+          console.log('   Fix:');
+          for (const fix of issue.fixes) console.log(`     - ${fix}`);
+        }
+        console.log('');
+      }
+      throw new Error('Pre-resume checks failed. Use --skip-doctor to bypass (not recommended).');
+    }
+    
+    // Show warnings but don't block
+    const warnings = report.issues.filter(i => i.severity === 'warn' && i.id.startsWith('branch.'));
+    if (warnings.length > 0) {
+      logger.warn(`${warnings.length} warning(s) found. Run 'cursorflow doctor' for details.`);
+    }
+  }
+  
   logger.section(`🔁 Resuming Lane: ${options.lane}`);
   logger.info(`Run: ${path.basename(runDir)}`);
   logger.info(`Tasks: ${state.tasksFile}`);

package/src/cli/run.ts

@@ -7,31 +7,57 @@ import * as fs from 'fs';
 import * as logger from '../utils/logger';
 import { orchestrate } from '../core/orchestrator';
 import { getLogsDir, loadConfig } from '../utils/config';
-import { runDoctor } from '../utils/doctor';
+import { runDoctor, getDoctorStatus } from '../utils/doctor';
 import { areCommandsInstalled, setupCommands } from './setup-commands';
 
 interface RunOptions {
   tasksDir?: string;
   dryRun: boolean;
   executor: string | null;
+  maxConcurrent: number | null;
   skipDoctor: boolean;
+  help: boolean;
+}
+
+function printHelp(): void {
+  console.log(`
+Usage: cursorflow run <tasks-dir> [options]
+
+Run task orchestration based on dependency graph.
+
+Options:
+  <tasks-dir>            Directory containing task JSON files
+  --max-concurrent <num> Limit parallel agents (overrides config)
+  --executor <type>      cursor-agent | cloud
+  --skip-doctor          Skip environment checks (not recommended)
+  --dry-run              Show execution plan without starting agents
+  --help, -h             Show help
+  `);
 }
 
 function parseArgs(args: string[]): RunOptions {
   const tasksDir = args.find(a => !a.startsWith('--'));
   const executorIdx = args.indexOf('--executor');
+  const maxConcurrentIdx = args.indexOf('--max-concurrent');
   
   return {
     tasksDir,
     dryRun: args.includes('--dry-run'),
     executor: executorIdx >= 0 ? args[executorIdx + 1] || null : null,
+    maxConcurrent: maxConcurrentIdx >= 0 ? parseInt(args[maxConcurrentIdx + 1] || '0') || null : null,
     skipDoctor: args.includes('--skip-doctor') || args.includes('--no-doctor'),
+    help: args.includes('--help') || args.includes('-h'),
   };
 }
 
 async function run(args: string[]): Promise<void> {
   const options = parseArgs(args);
   
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
   // Auto-setup Cursor commands if missing or outdated
   if (!areCommandsInstalled()) {
     logger.info('Installing missing or outdated Cursor IDE commands...');
@@ -64,6 +90,14 @@ async function run(args: string[]): Promise<void> {
     throw new Error(`Tasks directory not found: ${tasksDir}`);
   }
 
+  // Check if doctor has been run at least once
+  const doctorStatus = getDoctorStatus(config.projectRoot);
+  if (!doctorStatus) {
+    logger.warn('It looks like you haven\'t run `cursorflow doctor` yet.');
+    logger.warn('Running doctor is highly recommended to catch environment issues early.');
+    console.log('   Run: cursorflow doctor\n');
+  }
+
   // Preflight checks (doctor)
   if (!options.skipDoctor) {
     const report = runDoctor({
@@ -99,7 +133,7 @@ async function run(args: string[]): Promise<void> {
       executor: options.executor || config.executor,
       pollInterval: config.pollInterval * 1000,
       runDir: path.join(logsDir, 'runs', `run-${Date.now()}`),
-      maxConcurrentLanes: config.maxConcurrentLanes,
+      maxConcurrentLanes: options.maxConcurrent || config.maxConcurrentLanes,
     });
   } catch (error: any) {
     // Re-throw to be handled by the main entry point

package/src/cli/signal.ts

@@ -14,6 +14,21 @@ interface SignalOptions {
   lane: string | null;
   message: string | null;
   runDir: string | null;
+  help: boolean;
+}
+
+function printHelp(): void {
+  console.log(`
+Usage: cursorflow signal <lane> "<message>" [options]
+
+Directly intervene in a running lane by sending a message to the agent.
+
+Options:
+  <lane>                 Lane name to signal
+  "<message>"            Message text to send
+  --run-dir <path>       Use a specific run directory (default: latest)
+  --help, -h             Show help
+  `);
 }
 
 function parseArgs(args: string[]): SignalOptions {
@@ -26,6 +41,7 @@ function parseArgs(args: string[]): SignalOptions {
     lane: nonOptions[0] || null,
     message: nonOptions.slice(1).join(' ') || null,
     runDir: runDirIdx >= 0 ? args[runDirIdx + 1] || null : null,
+    help: args.includes('--help') || args.includes('-h'),
   };
 }
 
@@ -43,6 +59,12 @@ function findLatestRunDir(logsDir: string): string | null {
 
 async function signal(args: string[]): Promise<void> {
   const options = parseArgs(args);
+  
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
   const config = loadConfig();
   const logsDir = getLogsDir(config);
   

package/src/core/runner.ts

@@ -107,15 +107,79 @@ function parseJsonFromStdout(stdout: string): any {
   return null;
 }
 
+/** Default timeout: 5 minutes */
+const DEFAULT_TIMEOUT_MS = 300000;
+
+/** Heartbeat interval: 30 seconds */
+const HEARTBEAT_INTERVAL_MS = 30000;
+
+/**
+ * Validate task configuration
+ * @throws Error if validation fails
+ */
+export function validateTaskConfig(config: RunnerConfig): void {
+  if (!config.tasks || !Array.isArray(config.tasks)) {
+    throw new Error('Invalid config: "tasks" must be an array');
+  }
+  
+  if (config.tasks.length === 0) {
+    throw new Error('Invalid config: "tasks" array is empty');
+  }
+  
+  for (let i = 0; i < config.tasks.length; i++) {
+    const task = config.tasks[i];
+    const taskNum = i + 1;
+    
+    if (!task) {
+      throw new Error(`Invalid config: Task ${taskNum} is null or undefined`);
+    }
+    
+    if (!task.name || typeof task.name !== 'string') {
+      throw new Error(
+        `Invalid config: Task ${taskNum} missing required "name" field.\n` +
+        `  Found: ${JSON.stringify(task, null, 2).substring(0, 200)}...\n` +
+        `  Expected: { "name": "task-name", "prompt": "..." }`
+      );
+    }
+    
+    if (!task.prompt || typeof task.prompt !== 'string') {
+      throw new Error(
+        `Invalid config: Task "${task.name}" (${taskNum}) missing required "prompt" field`
+      );
+    }
+    
+    // Validate task name format (no spaces, special chars that could break branch names)
+    if (!/^[a-zA-Z0-9_-]+$/.test(task.name)) {
+      throw new Error(
+        `Invalid config: Task name "${task.name}" contains invalid characters.\n` +
+        `  Task names must only contain: letters, numbers, underscore (_), hyphen (-)`
+      );
+    }
+  }
+  
+  // Validate timeout if provided
+  if (config.timeout !== undefined) {
+    if (typeof config.timeout !== 'number' || config.timeout <= 0) {
+      throw new Error(
+        `Invalid config: "timeout" must be a positive number (milliseconds).\n` +
+        `  Found: ${config.timeout}`
+      );
+    }
+  }
+}
+
 /**
  * Execute cursor-agent command with streaming and better error handling
  */
-export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, signalDir }: { 
+export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, signalDir, timeout, enableIntervention }: { 
   workspaceDir: string; 
   chatId: string; 
   prompt: string; 
   model?: string; 
   signalDir?: string;
+  timeout?: number;
+  /** Enable stdin piping for intervention feature (may cause buffering issues on some systems) */
+  enableIntervention?: boolean;
 }): Promise<AgentSendResult> {
   const args = [
     '--print',
@@ -126,17 +190,67 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
     prompt,
   ];
   
-  logger.info('Executing cursor-agent...');
+  const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
+  logger.info(`Executing cursor-agent... (timeout: ${Math.round(timeoutMs / 1000)}s)`);
+  
+  // Determine stdio mode based on intervention setting
+  // When intervention is enabled, we pipe stdin for message injection
+  // When disabled (default), we ignore stdin to avoid buffering issues
+  const stdinMode = enableIntervention ? 'pipe' : 'ignore';
+  
+  if (enableIntervention) {
+    logger.info('Intervention mode enabled (stdin piped)');
+  }
   
   return new Promise((resolve) => {
+    // Build environment, preserving user's NODE_OPTIONS but disabling problematic flags
+    const childEnv = { ...process.env };
+    
+    // Only filter out specific problematic NODE_OPTIONS, don't clear entirely
+    if (childEnv.NODE_OPTIONS) {
+      // Remove flags that might interfere with cursor-agent
+      const filtered = childEnv.NODE_OPTIONS
+        .split(' ')
+        .filter(opt => !opt.includes('--inspect') && !opt.includes('--debug'))
+        .join(' ');
+      childEnv.NODE_OPTIONS = filtered;
+    }
+    
+    // Disable Python buffering in case cursor-agent uses Python
+    childEnv.PYTHONUNBUFFERED = '1';
+    
     const child = spawn('cursor-agent', args, {
-      stdio: ['pipe', 'pipe', 'pipe'], // Enable stdin piping
-      env: process.env,
+      stdio: [stdinMode, 'pipe', 'pipe'],
+      env: childEnv,
     });
 
+    // Save PID to state if possible
+    if (child.pid && signalDir) {
+      try {
+        const statePath = path.join(signalDir, 'state.json');
+        if (fs.existsSync(statePath)) {
+          const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+          state.pid = child.pid;
+          fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+        }
+      } catch (e) {
+        // Best effort
+      }
+    }
+
     let fullStdout = '';
     let fullStderr = '';
 
+    // Heartbeat logging to show progress
+    let lastHeartbeat = Date.now();
+    let bytesReceived = 0;
+    const heartbeatInterval = setInterval(() => {
+      const elapsed = Math.round((Date.now() - lastHeartbeat) / 1000);
+      const totalElapsed = Math.round((Date.now() - startTime) / 1000);
+      logger.info(`⏱ Heartbeat: ${totalElapsed}s elapsed, ${bytesReceived} bytes received`);
+    }, HEARTBEAT_INTERVAL_MS);
+    const startTime = Date.now();
+
     // Watch for "intervention.txt" signal file if any
     const interventionPath = signalDir ? path.join(signalDir, 'intervention.txt') : null;
     let interventionWatcher: fs.FSWatcher | null = null;
@@ -147,8 +261,13 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
           try {
             const message = fs.readFileSync(interventionPath, 'utf8').trim();
             if (message) {
-              logger.info(`Injecting intervention: ${message}`);
-              child.stdin.write(message + '\n');
+              if (enableIntervention && child.stdin) {
+                logger.info(`Injecting intervention: ${message}`);
+                child.stdin.write(message + '\n');
+              } else {
+                logger.warn(`Intervention requested but stdin not available: ${message}`);
+                logger.warn('To enable intervention, set enableIntervention: true in config');
+              }
               fs.unlinkSync(interventionPath); // Clear it
             }
           } catch (e) {
@@ -158,30 +277,38 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
       });
     }
 
-    child.stdout.on('data', (data) => {
-      const str = data.toString();
-      fullStdout += str;
-      // Also pipe to our own stdout so it goes to terminal.log
-      process.stdout.write(data);
-    });
+    if (child.stdout) {
+      child.stdout.on('data', (data) => {
+        const str = data.toString();
+        fullStdout += str;
+        bytesReceived += data.length;
+        // Also pipe to our own stdout so it goes to terminal.log
+        process.stdout.write(data);
+      });
+    }
 
-    child.stderr.on('data', (data) => {
-      fullStderr += data.toString();
-      // Pipe to our own stderr so it goes to terminal.log
-      process.stderr.write(data);
-    });
+    if (child.stderr) {
+      child.stderr.on('data', (data) => {
+        fullStderr += data.toString();
+        // Pipe to our own stderr so it goes to terminal.log
+        process.stderr.write(data);
+      });
+    }
 
-    const timeout = setTimeout(() => {
+    const timeoutHandle = setTimeout(() => {
+      clearInterval(heartbeatInterval);
       child.kill();
+      const timeoutSec = Math.round(timeoutMs / 1000);
       resolve({
         ok: false,
         exitCode: -1,
-        error: 'cursor-agent timed out after 5 minutes. The LLM request may be taking too long or there may be network issues.',
+        error: `cursor-agent timed out after ${timeoutSec} seconds. The LLM request may be taking too long or there may be network issues.`,
       });
-    }, 300000);
+    }, timeoutMs);
 
     child.on('close', (code) => {
-      clearTimeout(timeout);
+      clearTimeout(timeoutHandle);
+      clearInterval(heartbeatInterval);
       if (interventionWatcher) interventionWatcher.close();
       
       const json = parseJsonFromStdout(fullStdout);
@@ -214,7 +341,8 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
     });
 
     child.on('error', (err) => {
-      clearTimeout(timeout);
+      clearTimeout(timeoutHandle);
+      clearInterval(heartbeatInterval);
       resolve({
         ok: false,
         exitCode: -1,
@@ -361,7 +489,9 @@ export async function runTask({
     chatId,
     prompt: prompt1,
     model,
-    signalDir: runDir
+    signalDir: runDir,
+    timeout: config.timeout,
+    enableIntervention: config.enableIntervention,
   });
   
   appendLog(convoPath, createConversationEntry('assistant', r1.resultText || r1.error || 'No response', {
@@ -405,6 +535,17 @@ export async function runTask({
 export async function runTasks(tasksFile: string, config: RunnerConfig, runDir: string, options: { startIndex?: number } = {}): Promise<TaskExecutionResult[]> {
   const startIndex = options.startIndex || 0;
   
+  // Validate configuration before starting
+  logger.info('Validating task configuration...');
+  try {
+    validateTaskConfig(config);
+    logger.success('✓ Configuration valid');
+  } catch (validationError: any) {
+    logger.error('❌ Configuration validation failed');
+    logger.error(`   ${validationError.message}`);
+    throw validationError;
+  }
+  
   // Ensure cursor-agent is installed
   ensureCursorAgent();
   

package/src/utils/cursor-agent.ts

@@ -114,19 +114,35 @@ export function validateSetup(executor = 'cursor-agent'): { valid: boolean; erro
  * Get available models (if cursor-agent supports it)
  */
 export function getAvailableModels(): string[] {
+  // Known models in the current version of cursor-agent
+  const knownModels = [
+    'sonnet-4.5',
+    'sonnet-4.5-thinking',
+    'opus-4.5',
+    'opus-4.5-thinking',
+    'gpt-5.2',
+    'gpt-5.2-high',
+  ];
+
   try {
-    // This is a placeholder - actual implementation depends on cursor-agent API
-    // execSync('cursor-agent --model invalid "test"', {
-    //   encoding: 'utf8',
-    //   stdio: 'pipe',
-    // });
+    // Try to trigger a model list by using an invalid model with --print
+    // Some versions of cursor-agent output valid models when an invalid one is used.
+    const result = spawnSync('cursor-agent', ['--print', '--model', 'list-available-models', 'test'], {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      timeout: 5000,
+    });
+    
+    const output = (result.stderr || result.stdout || '').toString();
+    const discoveredModels = parseModelsFromOutput(output);
     
-    return [];
+    if (discoveredModels.length > 0) {
+      return [...new Set([...knownModels, ...discoveredModels])];
+    }
+    
+    return knownModels;
   } catch (error: any) {
-    // Parse from error message
-    const output = (error.stderr || error.stdout || '').toString();
-    // Extract model names from output
-    return parseModelsFromOutput(output);
+    return knownModels;
   }
 }
 
@@ -175,6 +191,42 @@ export function testCursorAgent(): { success: boolean; output?: string; error?:
   }
 }
 
+/**
+ * Run interactive agent test to prime permissions (MCP, user approval, etc.)
+ */
+export function runInteractiveAgentTest(): boolean {
+  const { spawnSync } = require('child_process');
+  
+  console.log('\n' + '━'.repeat(60));
+  console.log('🤖 Interactive Agent Priming Test');
+  console.log('━'.repeat(60));
+  console.log('\nThis will start cursor-agent in interactive mode (NOT --print).');
+  console.log('Use this to approve MCP permissions or initial setup requests.\n');
+  console.log('MISSION: Just say hello and confirm MCP connectivity.');
+  console.log('ACTION: Once the agent responds and finishes, you can exit.');
+  console.log('\n' + '─'.repeat(60) + '\n');
+
+  try {
+    // Run WITHOUT --print to allow interactive user input and UI popups
+    const result = spawnSync('cursor-agent', ['Hello, verify MCP and system access.'], {
+      stdio: 'inherit', // Crucial for interactivity
+      env: process.env,
+    });
+
+    console.log('\n' + '─'.repeat(60));
+    if (result.status === 0) {
+      console.log('✅ Interactive test completed successfully!');
+      return true;
+    } else {
+      console.log('❌ Interactive test exited with code: ' + result.status);
+      return false;
+    }
+  } catch (error: any) {
+    console.log('❌ Failed to run interactive test: ' + error.message);
+    return false;
+  }
+}
+
 export interface AuthCheckResult {
   authenticated: boolean;
   message: string;