@zibby/core 0.1.1 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/core",
-  "version": "0.1.1",
+  "version": "0.1.6",
   "description": "Core test automation engine with multi-agent and multi-MCP support",
   "type": "module",
   "main": "src/index.js",
@@ -22,7 +22,8 @@
     "./utils/node-schema-parser.js": "./src/utils/node-schema-parser.js",
     "./templates/register-nodes.js": "./templates/register-nodes.js",
     "./templates": "./templates/index.js",
-    "./templates/*": "./templates/*"
+    "./templates/*": "./templates/*",
+    "./package.json": "./package.json"
   },
   "scripts": {
     "test": "vitest run",
@@ -60,6 +61,7 @@
     "!templates/**/__tests__/",
     "!templates/**/*.test.js",
     "!templates/**/*.spec.js",
+    "scripts/",
     "README.md",
     "LICENSE"
   ],

package/scripts/export-default-workflows.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Export default workflows as JSON for the backend API
+ * Run: node packages/core/scripts/export-default-workflows.js
+ */
+
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { WorkflowGraph } from '../src/framework/graph.js';
+import { buildAnalysisGraph } from '../templates/graphs/analysisGraph.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const outputDir = join(__dirname, '../../../backend/src/data');
+
+// Ensure output directory exists
+if (!existsSync(outputDir)) {
+  mkdirSync(outputDir, { recursive: true });
+}
+
+// Build and serialize analysis workflow
+console.log('Building analysis workflow...');
+const analysisGraph = new WorkflowGraph();
+buildAnalysisGraph(analysisGraph);
+const serializedAnalysis = analysisGraph.serialize();
+
+// Add workflow metadata
+const analysisWorkflow = {
+  id: 'default_analysis',
+  name: 'Analysis Workflow',
+  description: 'Analyzes tickets and generates code implementation',
+  ...serializedAnalysis,
+  createdAt: new Date().toISOString(),
+  isDefault: true
+};
+
+// Write to JSON file
+const outputPath = join(outputDir, 'default-workflows.json');
+const workflows = {
+  analysis: analysisWorkflow
+};
+
+writeFileSync(outputPath, JSON.stringify(workflows, null, 2));
+console.log(`✅ Exported default workflows to ${outputPath}`);
+
+// Also export as individual files for clarity
+writeFileSync(
+  join(outputDir, 'default-analysis-workflow.json'),
+  JSON.stringify(analysisWorkflow, null, 2)
+);
+console.log('✅ Exported individual workflow files');

package/scripts/patch-cursor-mcp.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * Patch cursor-agent CLI to auto-approve MCP tool calls for CI/CD use.
+ *
+ * This script modifies the cursor-agent source code to bypass the manual
+ * approval prompt for MCP tool executions, making it suitable for automated
+ * CI/CD pipelines.
+ *
+ * Usage:
+ *   node patch-cursor-mcp.js
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function findLatestCursorAgent() {
+  const versionsDir = join(homedir(), '.local/share/cursor-agent/versions');
+  
+  if (!existsSync(versionsDir)) {
+    console.error(`❌ Cursor agent versions directory not found: ${versionsDir}`);
+    console.error('   Make sure cursor-agent is installed: curl https://cursor.com/install -fsS | bash');
+    process.exit(1);
+  }
+  
+  const versions = readdirSync(versionsDir)
+    .map(name => join(versionsDir, name))
+    .filter(path => statSync(path).isDirectory());
+  
+  if (versions.length === 0) {
+    console.error(`❌ No cursor-agent versions found in ${versionsDir}`);
+    process.exit(1);
+  }
+  
+  // Get the latest version by creation time
+  const latestVersion = versions
+    .map(path => ({ path, ctime: statSync(path).ctimeMs }))
+    .sort((a, b) => b.ctime - a.ctime)[0].path;
+  
+  return join(latestVersion, 'index.js');
+}
+
+function backupFile(filePath) {
+  const backupPath = `${filePath  }.backup`;
+  
+  if (existsSync(backupPath)) {
+    console.log(`ℹ️  Backup already exists: ${backupPath}`);
+    return backupPath;
+  }
+  
+  const content = readFileSync(filePath, 'utf8');
+  writeFileSync(backupPath, content, 'utf8');
+  
+  console.log(`✅ Backup created: ${backupPath}`);
+  return backupPath;
+}
+
+function patchMcpApproval(filePath) {
+  const content = readFileSync(filePath, 'utf8');
+  
+  // Check if already patched
+  if (content.includes('AUTO-APPROVE MCP TOOLS FOR CI/CD')) {
+    console.log('✅ File is already patched!');
+    return false;
+  }
+  
+  // Pattern to match the requestApproval call for MCP
+  const pattern = /(\s+const result = await this\.pendingDecisionProvider\.requestApproval\(\{\s+type: OperationType\.Mcp,\s+details: \{\s+name: approvalDetails\.name,\s+toolName: approvalDetails\.toolName,\s+providerIdentifier: approvalDetails\.providerIdentifier,\s+args: approvalDetails\.args,\s+\},\s+toolCallId: args\.toolCallId,\s+\}\);)/;
+  
+  const replacement = `                        // AUTO-APPROVE MCP TOOLS FOR CI/CD
+                        const result = { approved: true };
+                        /*
+                        const result = await this.pendingDecisionProvider.requestApproval({
+                            type: OperationType.Mcp,
+                            details: {
+                                name: approvalDetails.name,
+                                toolName: approvalDetails.toolName,
+                                providerIdentifier: approvalDetails.providerIdentifier,
+                                args: approvalDetails.args,
+                            },
+                            toolCallId: args.toolCallId,
+                        });
+                        */`;
+  
+  const newContent = content.replace(pattern, replacement);
+  
+  if (newContent === content) {
+    console.log('ℹ️  Pattern not found - cursor-agent code structure has changed.');
+    console.log('   This is OKAY! Newer versions might not need this patch.');
+    console.log('   If auto-approval doesn\'t work, cursor-agent team may have fixed it!');
+    return false;
+  }
+  
+  writeFileSync(filePath, newContent, 'utf8');
+  return true;
+}
+
+function addApprovalKeyLogging(filePath) {
+  const content = readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+  
+  // Check if already added
+  if (lines.some(line => line.includes('🔑 APPROVAL KEY'))) {
+    console.log('✅ Approval key logging already enabled!');
+    return false;
+  }
+  
+  // Find the line with generateApprovalKey and add logging after it
+  let targetLineNum = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes('const approvalKey = generateApprovalKey(serverName, server, this.cwd);')) {
+      targetLineNum = i;
+      break;
+    }
+  }
+  
+  if (targetLineNum === -1) {
+    console.log('⚠️  Could not find approval key generation line');
+    return false;
+  }
+  
+  // Insert the console.log after the generateApprovalKey line
+  const indent = '            ';
+  const logLine = `${indent}console.log("🔑 APPROVAL KEY:", serverName, "=>", approvalKey);`;
+  lines.splice(targetLineNum + 1, 0, logLine);
+  
+  writeFileSync(filePath, lines.join('\n'), 'utf8');
+  return true;
+}
+
+function main() {
+  console.log('🔧 Patching cursor-agent for CI/CD MCP usage...\n');
+  console.log('ℹ️  Note: This patch is temporary and may not be needed in future versions.\n');
+  
+  // Find cursor-agent
+  const indexFile = findLatestCursorAgent();
+  console.log(`📍 Found cursor-agent: ${indexFile}\n`);
+  
+  // Backup
+  backupFile(indexFile);
+  console.log();
+  
+  // Apply patches
+  const patchedApproval = patchMcpApproval(indexFile);
+  if (patchedApproval) {
+    console.log('✅ Patched MCP tool auto-approval');
+  }
+  console.log();
+  
+  const patchedLogging = addApprovalKeyLogging(indexFile);
+  if (patchedLogging) {
+    console.log('✅ Added approval key logging');
+  }
+  console.log();
+  
+  if (patchedApproval || patchedLogging) {
+    console.log('🎉 cursor-agent is now ready for CI/CD!');
+    console.log('\nNext steps:');
+    console.log('1. Run: cursor-agent mcp list');
+    console.log('2. Copy the approval key shown');
+    console.log('3. Add it to ~/.cursor/projects/YOUR_PROJECT/mcp-approvals.json');
+    console.log('\n⚠️  If cursor-agent updates break this patch, MCP may work without it.');
+  } else {
+    console.log('ℹ️  No changes needed - already configured or cursor-agent version doesn\'t need patching!');
+  }
+}
+
+main();
+

package/scripts/setup-ci.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+set -e
+
+echo "🚀 Complete CI/CD Setup (from scratch)"
+echo "======================================="
+echo ""
+
+# Get the absolute path to the project
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+echo "📍 Project root: $PROJECT_ROOT"
+echo ""
+
+# Check OS
+OS="$(uname -s)"
+echo "🖥️  Detected OS: $OS"
+echo ""
+
+# Step 1: Check/Install Node.js
+echo "Step 1: Checking Node.js..."
+if command -v node &> /dev/null; then
+  NODE_VERSION=$(node --version)
+  echo "✓ Node.js installed: $NODE_VERSION"
+else
+  echo "✗ Node.js not found!"
+  echo "  Install: https://nodejs.org/ or use nvm"
+  exit 1
+fi
+echo ""
+
+# Step 2: Check/Install Python 3
+echo "Step 2: Checking Python 3..."
+if command -v python3 &> /dev/null; then
+  PYTHON_VERSION=$(python3 --version)
+  echo "✓ Python 3 installed: $PYTHON_VERSION"
+else
+  echo "✗ Python 3 not found!"
+  exit 1
+fi
+echo ""
+
+# Step 3: Install npm dependencies
+echo "Step 3: Installing npm dependencies..."
+cd "$PROJECT_ROOT"
+if [ -f "package.json" ]; then
+  npm install --silent > /dev/null 2>&1
+  echo "✓ npm dependencies installed"
+else
+  echo "✗ package.json not found"
+  exit 1
+fi
+echo ""
+
+# Step 4: Check/Install cursor-agent
+echo "Step 4: Checking cursor-agent..."
+if command -v cursor-agent &> /dev/null; then
+  CURSOR_VERSION=$(cursor-agent --version 2>&1 | head -1 || echo "unknown")
+  echo "✓ cursor-agent installed: $CURSOR_VERSION"
+else
+  echo "⚠️  cursor-agent not found - installing..."
+  
+  if [ "$OS" = "Darwin" ] || [ "$OS" = "Linux" ]; then
+    # Install cursor-agent
+    curl -fsSL https://cursor.com/install | bash
+    
+    # Add to PATH for current session
+    export PATH="$HOME/.local/bin:$PATH"
+    
+    if command -v cursor-agent &> /dev/null; then
+      echo "✓ cursor-agent installed successfully"
+    else
+      echo "✗ cursor-agent installation failed"
+      echo "  Manual install: curl https://cursor.com/install -fsS | bash"
+      exit 1
+    fi
+  else
+    echo "✗ Unsupported OS for automatic cursor-agent installation"
+    echo "  Install manually: https://cursor.com/cli"
+    exit 1
+  fi
+fi
+echo ""
+
+# Step 5: Check CURSOR_API_KEY (REQUIRED for CI/CD)
+echo "Step 5: Checking CURSOR_API_KEY..."
+if [ -z "$CURSOR_API_KEY" ]; then
+  echo "⚠️  CURSOR_API_KEY not set"
+  echo "  ⚠️  REQUIRED for CI/CD - cursor-agent will fail without it!"
+  echo "  Set it as an environment variable in your CI/CD config"
+  echo "  Get your key from: https://cursor.com/settings"
+  echo ""
+  echo "  Example (GitLab CI):"
+  echo "    variables:"
+  echo "      CURSOR_API_KEY: \$CURSOR_API_KEY"
+  echo ""
+else
+  echo "✓ CURSOR_API_KEY is set"
+fi
+echo ""
+
+# Step 6: Run the official Playwright MCP setup
+echo "Step 6: Setting up official Playwright MCP..."
+echo ""
+bash "$SCRIPT_DIR/setup-official-playwright-mcp.sh"
+
+echo ""
+echo "======================================="
+echo "✅ Complete CI/CD setup finished!"
+echo "======================================="
+echo ""
+echo "Ready to use in CI/CD:"
+echo "  cursor-agent -p 'Navigate to google.com' --mcp-server playwright-official"
+echo ""
+

package/scripts/setup-official-playwright-mcp.sh

@@ -0,0 +1,197 @@
+#!/bin/bash
+
+set -e
+
+# Get script directory for relative imports
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Step 1: Check cursor-agent
+if ! command -v cursor-agent &> /dev/null; then
+    echo "⚠️  cursor-agent not found. Installing..."
+    curl https://cursor.com/install -fsS | bash
+    export PATH="$HOME/.cursor/bin:$HOME/.local/bin:$PATH"
+fi
+
+# Step 2: Find Node.js absolute paths (Cursor GUI doesn't have shell PATH)
+NODE_PATH=$(which node 2>/dev/null || echo "")
+NPX_PATH=$(which npx 2>/dev/null || echo "")
+NODE_BIN_DIR=$(dirname "$NODE_PATH" 2>/dev/null || echo "")
+
+if [ -z "$NODE_PATH" ]; then
+    echo "❌ node not found. Please install Node.js"
+    exit 1
+fi
+
+echo "   Using Node: $NODE_PATH"
+
+# Step 3: Install Zibby MCP Browser (forked Playwright MCP with stable ID support)
+echo "Setting up Zibby MCP Browser..."
+ZIBBY_MCP_DIR="$SCRIPT_DIR/../../mcps/browser"
+ZIBBY_MCP_BIN="$ZIBBY_MCP_DIR/bin/mcp-browser-zibby.js"
+
+if [ -f "$ZIBBY_MCP_BIN" ]; then
+  # Install dependencies (skip if already resolvable via workspace hoisting)
+  if [ ! -d "$ZIBBY_MCP_DIR/node_modules" ]; then
+    if "$NODE_PATH" -e "require.resolve('@playwright/mcp', {paths:['$ZIBBY_MCP_DIR']})" 2>/dev/null; then
+      echo "   ✅ Dependencies available"
+    else
+      echo "   📥 Installing dependencies..."
+      (cd "$ZIBBY_MCP_DIR" && npm install --silent > /dev/null 2>&1) || echo "   ⚠️  Could not install dependencies"
+    fi
+  fi
+  echo "Zibby MCP Browser ready"
+else
+  echo "Zibby MCP Browser not found at $ZIBBY_MCP_BIN"
+  exit 1
+fi
+
+# Install ffmpeg for video recording
+echo "🎬 Installing ffmpeg for video recording..."
+if command -v playwright &> /dev/null 2>&1; then
+  playwright install ffmpeg > /dev/null 2>&1 && echo "   ✅ ffmpeg installed" || echo "   ⚠️  Could not install ffmpeg"
+else
+  "$NPX_PATH" --yes playwright install ffmpeg > /dev/null 2>&1 && echo "   ✅ ffmpeg installed" || echo "   ⚠️  Could not install ffmpeg (will disable video)"
+fi
+
+# Step 4: Configure MCP
+echo "Configuring Zibby MCP Browser..."
+mkdir -p ~/.cursor
+
+# Default viewport size (can be overridden via env)
+VIEWPORT_WIDTH="${ZIBBY_VIEWPORT_WIDTH:-1280}"
+VIEWPORT_HEIGHT="${ZIBBY_VIEWPORT_HEIGHT:-720}"
+VIEWPORT_SIZE="${VIEWPORT_WIDTH}x${VIEWPORT_HEIGHT}"
+
+# Build MCP args array
+MCP_ARGS="\"--save-video=${VIEWPORT_SIZE}\", \"--viewport-size=${VIEWPORT_SIZE}\", \"--output-dir=test-results\""
+
+# Check if headless mode requested (default is headed)
+if [ "$ZIBBY_HEADLESS" = "1" ]; then
+  MCP_ARGS="$MCP_ARGS, \"--headless\""
+  echo "   Mode: Headless (hidden browser)"
+else
+  echo "   Mode: Headed (visible browser)"
+fi
+
+# Check if video recording requested (default is on)
+if [ "$ZIBBY_VIDEO" != "off" ]; then
+  echo "   Video: Enabled (${VIEWPORT_SIZE})"
+else
+  MCP_ARGS="\"--viewport-size=${VIEWPORT_SIZE}\", \"--output-dir=test-results\""
+  if [ "$ZIBBY_HEADLESS" = "1" ]; then
+    MCP_ARGS="$MCP_ARGS, \"--headless\""
+  fi
+  echo "   Video: Disabled"
+fi
+
+# Check if Zibby Cloud MCP should be included
+if [ "$ZIBBY_CLOUD_SYNC" = "1" ]; then
+  LOCAL_MCP_PATH="$SCRIPT_DIR/../../mcp-server/src/index.js"
+  
+  if [ -f "$LOCAL_MCP_PATH" ]; then
+    MCP_PKG_DIR="$SCRIPT_DIR/../../mcp-server"
+    if [ -f "$MCP_PKG_DIR/package.json" ]; then
+      echo "   📦 Installing Zibby Cloud MCP dependencies..."
+      (cd "$MCP_PKG_DIR" && npm install --silent > /dev/null 2>&1) || echo "   ⚠️  Warning: Could not install dependencies"
+    fi
+    
+    cat > ~/.cursor/mcp.json <<EOF
+{
+  "mcpServers": {
+    "playwright-official": {
+      "command": "$NODE_PATH",
+      "args": ["$ZIBBY_MCP_BIN", $MCP_ARGS],
+      "env": {
+        "PATH": "$NODE_BIN_DIR:/usr/bin:/bin:/usr/sbin:/sbin"
+      },
+      "description": "Zibby MCP Browser - Forked Playwright MCP with stable ID support"
+    },
+    "zibby": {
+      "command": "$NODE_PATH",
+      "args": ["$LOCAL_MCP_PATH"],
+      "env": {
+        "ZIBBY_API_KEY": "${ZIBBY_API_KEY}",
+        "PATH": "$NODE_BIN_DIR:/usr/bin:/bin:/usr/sbin:/sbin"
+      },
+      "description": "Zibby Cloud Sync - Upload test results and artifacts"
+    }
+  }
+}
+EOF
+    echo "   + Zibby MCP Browser (stable IDs + event recording)"
+    echo "   + Zibby Cloud MCP (cloud sync enabled)"
+  else
+    echo "   ⚠️  Cloud sync requested but local MCP server not found"
+    cat > ~/.cursor/mcp.json <<EOF
+{
+  "mcpServers": {
+    "playwright-official": {
+      "command": "$NODE_PATH",
+      "args": ["$ZIBBY_MCP_BIN", $MCP_ARGS],
+      "env": {
+        "PATH": "$NODE_BIN_DIR:/usr/bin:/bin:/usr/sbin:/sbin"
+      },
+      "description": "Zibby MCP Browser - Forked Playwright MCP with stable ID support"
+    }
+  }
+}
+EOF
+    echo "   + Zibby MCP Browser (stable IDs + event recording)"
+  fi
+else
+  cat > ~/.cursor/mcp.json <<EOF
+{
+  "mcpServers": {
+    "playwright-official": {
+      "command": "$NODE_PATH",
+      "args": ["$ZIBBY_MCP_BIN", $MCP_ARGS],
+      "env": {
+        "PATH": "$NODE_BIN_DIR:/usr/bin:/bin:/usr/sbin:/sbin"
+      },
+      "description": "Zibby MCP Browser - Forked Playwright MCP with stable ID support"
+    }
+  }
+}
+EOF
+  echo "   + Zibby MCP Browser (stable IDs + event recording)"
+fi
+
+# Step 5: Patch cursor-agent
+echo "Patching cursor-agent..."
+node "$SCRIPT_DIR/patch-cursor-mcp.js" > /dev/null 2>&1 || echo "   (patch may not be needed for your version)"
+
+# Step 6: Get approval key
+echo "🔑 Getting approval key..."
+APPROVAL_OUTPUT=$(cursor-agent mcp list 2>&1)
+
+APPROVAL_KEY_LINE=$(echo "$APPROVAL_OUTPUT" | grep "🔑 APPROVAL KEY.*playwright-official" | head -1)
+echo "$APPROVAL_KEY_LINE"
+
+APPROVAL_KEY=$(echo "$APPROVAL_KEY_LINE" | sed -E 's/.*=> ([^ ]+).*/\1/' | head -1)
+
+if [ -z "$APPROVAL_KEY" ]; then
+    APPROVAL_KEY=$(echo "$APPROVAL_OUTPUT" | grep -oE 'playwright-official-[a-f0-9]+' | head -1)
+fi
+
+if [ -z "$APPROVAL_KEY" ]; then
+    echo "⚠️ Could not auto-extract approval key"
+    echo "   This is OK for development - approval key only needed for CI/CD"
+    echo "   For CI/CD: Run 'cursor-agent mcp list' and save the key"
+else
+    # Step 7: Setup workspace approvals (only if we got the key)
+    echo "Configuring approvals..."
+    WORKSPACE_PATH="$PWD"
+    WORKSPACE_ENCODED=$(echo "$WORKSPACE_PATH" | sed 's|^/||' | sed 's|/|-|g')
+    APPROVAL_DIR="$HOME/.cursor/projects/$WORKSPACE_ENCODED"
+    APPROVAL_FILE="$APPROVAL_DIR/mcp-approvals.json"
+
+    mkdir -p "$APPROVAL_DIR"
+    cat > "$APPROVAL_FILE" <<EOF
+["$APPROVAL_KEY"]
+EOF
+    echo "Auto-approval configured for this workspace"
+fi
+
+echo ""
+echo "Zibby MCP Browser ready!"
+echo ""

package/scripts/test-with-video.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+# Run Playwright tests with video recording
+# Usage: ./scripts/test-with-video.sh [test-file] [headed]
+# 
+# Examples:
+#   ./scripts/test-with-video.sh tests/auth/login.spec.js
+#   ./scripts/test-with-video.sh tests/auth/login.spec.js headed
+
+TEST_FILE="${1:-tests/}"
+HEADED_FLAG=""
+
+if [ "$2" = "headed" ]; then
+  HEADED_FLAG="--headed"
+fi
+
+echo "🎥 Running Playwright tests with video recording..."
+echo "   Test: $TEST_FILE"
+echo "   Mode: $([ -n "$HEADED_FLAG" ] && echo "Headed (visible)" || echo "Headless")"
+echo ""
+
+# Run tests (video is configured in playwright.config.js)
+npx playwright test "$TEST_FILE" --project=chromium $HEADED_FLAG
+
+echo ""
+echo "✅ Tests complete!"
+echo ""
+echo "📂 Videos saved in: test-results/"
+echo ""
+
+# List videos if any were created
+if ls test-results/*/video.webm 2>/dev/null 1>&2; then
+  echo "🎬 Videos created:"
+  ls -lh test-results/*/video.webm
+  echo ""
+  echo "To view videos:"
+  echo "  1. Open Finder: open test-results/"
+  echo "  2. Or play directly:"
+  for video in test-results/*/video.webm; do
+    echo "     open \"$video\""
+  done
+else
+  echo "ℹ️  No videos found"
+  echo ""
+  echo "Video is configured in playwright.config.js:"
+  echo "  - video: 'on' (always record)"
+  echo "  - video: 'retain-on-failure' (only failed tests)"
+fi
+

package/src/framework/agents/cursor-strategy.js

@@ -75,18 +75,26 @@ export class CursorAgentStrategy extends AgentStrategy {
       '/Applications/Cursor.app/Contents/Resources/app/bin/cursor'
     ];
     
-    let cursorBin = 'agent';
+    let cursorBin = null;
     for (const bin of possibleBins) {
-      if (bin === 'agent') {
-        cursorBin = bin;
-        break;
-      }
-      if (existsSync(bin)) {
+      try {
+        if (bin.startsWith('/')) {
+          accessSync(bin, constants.X_OK);
+        } else {
+          execSync(`which ${bin} 2>/dev/null`, { stdio: 'ignore', timeout: 2000 });
+        }
         cursorBin = bin;
+        logger.debug(`[Agent] Using binary: ${bin}`);
         break;
+      } catch {
+        continue;
       }
     }
     
+    if (!cursorBin) {
+      throw new Error('Cursor Agent CLI not found. Install it or add it to PATH.');
+    }
+    
     // File-based structured output: agent writes JSON to this file
     let resultFilePath = null;
     if (schema) {