@cutleryapp/agent 1.0.3

package/dist/cli.js

@@ -0,0 +1,873 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runConnect = runConnect;
+const chalk_1 = __importDefault(require("chalk"));
+const commander_1 = require("commander");
+const dotenv_1 = __importDefault(require("dotenv"));
+const fs_1 = require("fs");
+const ora_1 = __importDefault(require("ora"));
+const path_1 = require("path");
+const http = __importStar(require("http"));
+const os = __importStar(require("os"));
+const child_process_1 = require("child_process");
+const ws_1 = __importDefault(require("ws"));
+const playwright_1 = require("playwright");
+const mcp_executor_js_1 = require("./mcp-executor.js");
+const AGENT_VERSION = "1.0.0";
+// First-run browser bootstrap. Playwright ships its driver via npm but the
+// browser binaries are downloaded separately (~300MB for chromium). Without
+// this, the first `connect` from a fresh `npx @cutleryapp/agent` install fails
+// with "Executable doesn't exist" the moment it tries to launch a test.
+async function ensureBrowsersInstalled() {
+    if (process.env.CUTLERY_SKIP_BROWSER_INSTALL === "1")
+        return;
+    // Containers (our Docker image) bake browsers into the layer — skip the check.
+    if ((0, fs_1.existsSync)("/.dockerenv"))
+        return;
+    try {
+        if ((0, fs_1.existsSync)(playwright_1.chromium.executablePath()))
+            return;
+    }
+    catch { /* path lookup failed — fall through to install */ }
+    const spinner = (0, ora_1.default)("Installing Playwright Chromium (one-time, ~300MB)…").start();
+    await new Promise((resolveInstall, rejectInstall) => {
+        const child = (0, child_process_1.spawn)("npx", ["--yes", "playwright", "install", "chromium"], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+        });
+        let stderr = "";
+        child.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+        child.on("error", rejectInstall);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolveInstall();
+            else
+                rejectInstall(new Error(`playwright install exited ${code}: ${stderr.slice(-400)}`));
+        });
+    })
+        .then(() => spinner.succeed("Playwright Chromium installed"))
+        .catch((err) => {
+        spinner.fail("Failed to install Playwright Chromium");
+        console.error(chalk_1.default.red(`   ${err.message}`));
+        console.error(chalk_1.default.gray("   Run manually: npx playwright install chromium"));
+        console.error(chalk_1.default.gray("   Or set CUTLERY_SKIP_BROWSER_INSTALL=1 if browsers live elsewhere."));
+        process.exit(1);
+    });
+}
+function buildIdentity(args) {
+    return {
+        version: AGENT_VERSION,
+        hostname: os.hostname(),
+        platform: process.platform,
+        arch: process.arch,
+        nodeVersion: process.version,
+        capabilities: {
+            // Today the executor only drives Chromium. When that changes, advertise
+            // the actual list — the server's capability matcher consumes this.
+            browsers: args.browsers ?? ["chromium"],
+            // "Can it run headed?" — false in containers (no display server).
+            headless: !args.headless ? true : !process.env.CUTLERY_NO_DISPLAY,
+            maxConcurrency: args.maxConcurrency ?? 1,
+            tags: args.tags ?? [],
+        },
+    };
+}
+// Load environment variables
+dotenv_1.default.config();
+const program = new commander_1.Command();
+program
+    .name("cutlery-agent")
+    .description("Standalone AI-powered test execution agent")
+    .version("1.0.0");
+program
+    .command("run")
+    .description("Run a test case from a JSON file")
+    .argument("<file>", "Path to test case JSON file")
+    .option("-h, --headless", "Run in headless mode", false)
+    .option("-b, --browser <type>", "Browser type (chromium, firefox, webkit)", "chromium")
+    .option("-u, --base-url <url>", "Base URL for the application", "http://localhost:3000")
+    .option("-o, --output <path>", "Output directory for screenshots/videos", "./test-results")
+    .option("-v, --verbose", "Verbose output", false)
+    .option("--openai-key <key>", "OpenAI API key (or set OPENAI_API_KEY env var)")
+    .action(async (file, options) => {
+    const spinner = (0, ora_1.default)("Loading test case...").start();
+    try {
+        // Resolve file path
+        const filePath = (0, path_1.resolve)(process.cwd(), file);
+        if (!(0, fs_1.existsSync)(filePath)) {
+            spinner.fail(chalk_1.default.red(`Test case file not found: ${filePath}`));
+            process.exit(1);
+        }
+        // Read test case
+        const testCaseContent = (0, fs_1.readFileSync)(filePath, "utf-8");
+        const testCase = JSON.parse(testCaseContent);
+        spinner.succeed(chalk_1.default.green(`Loaded test case: ${testCase.name || "Unnamed"}`));
+        // Validate test case
+        if (!testCase.automated_steps || testCase.automated_steps.length === 0) {
+            console.log(chalk_1.default.red("❌ No automated_steps found in test case"));
+            process.exit(1);
+        }
+        console.log(chalk_1.default.blue(`\n📊 Test Case: ${testCase.name}`));
+        console.log(chalk_1.default.gray(`   Steps: ${testCase.automated_steps.length}`));
+        console.log(chalk_1.default.gray(`   Browser: ${options.browser}`));
+        console.log(chalk_1.default.gray(`   Headless: ${options.headless}`));
+        console.log(chalk_1.default.gray(`   Base URL: ${options.baseUrl}\n`));
+        // Get OpenAI key
+        const openaiKey = options.openaiKey || process.env.OPENAI_API_KEY;
+        if (!openaiKey) {
+            console.log(chalk_1.default.yellow("⚠️  No OpenAI API key provided. AI features will be limited."));
+            console.log(chalk_1.default.gray("   Set OPENAI_API_KEY environment variable or use --openai-key option\n"));
+        }
+        // Create executor
+        const executor = new mcp_executor_js_1.TestExecutor({
+            headless: options.headless,
+            browserType: options.browser,
+            baseUrl: options.baseUrl,
+            outputDir: options.output,
+            verbose: options.verbose,
+            openaiKey: openaiKey,
+        });
+        // Run test
+        spinner.start("Executing test case...");
+        const result = await executor.execute(testCase);
+        if (result.success) {
+            spinner.succeed(chalk_1.default.green("✅ Test PASSED"));
+            console.log(chalk_1.default.green(`\n📊 Test Results:`));
+            console.log(chalk_1.default.gray(`   Total Steps: ${result.steps.length}`));
+            console.log(chalk_1.default.green(`   Passed: ${result.steps.filter((s) => !s.error).length}`));
+            if (result.steps.some((s) => s.error)) {
+                console.log(chalk_1.default.red(`   Failed: ${result.steps.filter((s) => s.error).length}`));
+            }
+            if (result.screenshots && result.screenshots.length > 0) {
+                console.log(chalk_1.default.gray(`   Screenshots: ${result.screenshots.length}`));
+            }
+            if (options.verbose) {
+                console.log(chalk_1.default.blue("\n📝 Step Details:"));
+                result.steps.forEach((step, i) => {
+                    const icon = step.error ? "❌" : "✅";
+                    console.log(chalk_1.default.gray(`   ${i + 1}. ${icon} ${step.step || step.action || "Unknown"}`));
+                    if (step.error) {
+                        console.log(chalk_1.default.red(`      Error: ${step.error}`));
+                    }
+                });
+            }
+            process.exit(0);
+        }
+        else {
+            spinner.fail(chalk_1.default.red("❌ Test FAILED"));
+            console.log(chalk_1.default.red(`\n📊 Test Results:`));
+            console.log(chalk_1.default.gray(`   Total Steps: ${result.steps.length}`));
+            console.log(chalk_1.default.green(`   Passed: ${result.steps.filter((s) => !s.error).length}`));
+            console.log(chalk_1.default.red(`   Failed: ${result.steps.filter((s) => s.error).length}`));
+            console.log(chalk_1.default.red("\n❌ Failed Steps:"));
+            result.steps.forEach((step, i) => {
+                if (step.error) {
+                    console.log(chalk_1.default.red(`   ${i + 1}. ${step.step || step.action || "Unknown"}`));
+                    console.log(chalk_1.default.red(`      Error: ${step.error}`));
+                }
+            });
+            if (result.error) {
+                console.log(chalk_1.default.red(`\n💥 Error: ${result.error}`));
+            }
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        spinner.fail(chalk_1.default.red("Error executing test"));
+        console.error(chalk_1.default.red(error.message));
+        if (options.verbose && error.stack) {
+            console.error(chalk_1.default.gray(error.stack));
+        }
+        process.exit(1);
+    }
+});
+program
+    .command("validate")
+    .description("Validate a test case JSON file")
+    .argument("<file>", "Path to test case JSON file")
+    .action((file) => {
+    try {
+        const filePath = (0, path_1.resolve)(process.cwd(), file);
+        if (!(0, fs_1.existsSync)(filePath)) {
+            console.log(chalk_1.default.red(`❌ File not found: ${filePath}`));
+            process.exit(1);
+        }
+        const content = (0, fs_1.readFileSync)(filePath, "utf-8");
+        const testCase = JSON.parse(content);
+        console.log(chalk_1.default.blue("📋 Validating test case...\n"));
+        // Check required fields
+        const checks = [
+            { field: "name", exists: !!testCase.name, message: "Test case name" },
+            {
+                field: "automated_steps",
+                exists: !!testCase.automated_steps,
+                message: "Automated steps array",
+            },
+            {
+                field: "automated_steps.length",
+                exists: testCase.automated_steps?.length > 0,
+                message: "At least one step",
+            },
+        ];
+        let valid = true;
+        checks.forEach((check) => {
+            if (check.exists) {
+                console.log(chalk_1.default.green(`✅ ${check.message}`));
+            }
+            else {
+                console.log(chalk_1.default.red(`❌ ${check.message}`));
+                valid = false;
+            }
+        });
+        if (valid) {
+            console.log(chalk_1.default.green(`\n✅ Test case is valid!`));
+            console.log(chalk_1.default.gray(`   Name: ${testCase.name}`));
+            console.log(chalk_1.default.gray(`   Steps: ${testCase.automated_steps.length}`));
+            process.exit(0);
+        }
+        else {
+            console.log(chalk_1.default.red(`\n❌ Test case validation failed`));
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.log(chalk_1.default.red(`❌ Error: ${error.message}`));
+        process.exit(1);
+    }
+});
+program
+    .command("example")
+    .description("Create an example test case JSON file")
+    .argument("[output]", "Output file path", "example-test.json")
+    .action((output) => {
+    const { writeFileSync } = require("fs");
+    const example = {
+        name: "Login Test Example",
+        test_case_id: "TC_EXAMPLE_001",
+        automated_steps: [
+            "Navigate to https://example.com",
+            "Wait 1 second",
+            'Fill "user@example.com" in "input[name=\'email\']"',
+            'Fill "password123" in "input[name=\'password\']"',
+            "Click \"button[type='submit']\"",
+            'Wait for "h1" to be visible',
+            'Check if "Welcome" is visible',
+        ],
+        test_variables: {
+            email: "user@example.com",
+            password: "password123",
+        },
+    };
+    writeFileSync(output, JSON.stringify(example, null, 2));
+    console.log(chalk_1.default.green(`✅ Created example test case: ${output}`));
+    console.log(chalk_1.default.gray(`\nRun it with: cutlery-agent run ${output}`));
+});
+function runConnect(opts) {
+    const agentName = opts.name;
+    const webAppUrl = opts.url.replace(/\/$/, "");
+    const wsUrl = webAppUrl.replace(/^http/, "ws") + "/api/test-agent";
+    const startedAt = new Date().toISOString();
+    const log = (msg) => { if (!opts.silent)
+        console.log(msg); };
+    if (!opts.silent) {
+        console.log(chalk_1.default.blue("🚀 Cutlery Test Agent"));
+        console.log(chalk_1.default.gray(`   Agent Name: ${agentName}`));
+        console.log(chalk_1.default.gray(`   Web App:    ${webAppUrl}`));
+        console.log(chalk_1.default.gray(`   WebSocket:  ${wsUrl}`));
+        console.log(chalk_1.default.gray(`   Browser:    ${opts.headless ? 'headless' : 'visible (use --headless to hide)'}\n`));
+    }
+    let stopping = false;
+    let reconnectDelay = 2000;
+    let attempt = 0;
+    let currentWs = null;
+    let registered = false;
+    let activeExecutor = null;
+    let reconnectTimer = null;
+    const identity = buildIdentity({
+        headless: opts.headless,
+        maxConcurrency: opts.maxConcurrency,
+        tags: opts.tags,
+    });
+    const running = new Map();
+    let lastErrorAt = 0;
+    const snapshot = () => ({
+        status: lastErrorAt > Date.now() - 30_000
+            ? "error"
+            : running.size > 0
+                ? "busy"
+                : "idle",
+        currentTests: Array.from(running.values()).map(t => ({
+            testCaseId: t.testCaseId,
+            testCaseName: t.testCaseName,
+            startedAt: t.startedAt,
+            currentStep: t.currentStep,
+            totalSteps: t.totalSteps,
+            currentStepText: t.currentStepText,
+            elapsedMs: Date.now() - t.startedAtMs,
+        })),
+        queueDepth: 0, // single-test executor today; bump when we add a queue
+    });
+    // Coalesce burst updates — multiple step events in the same tick produce one
+    // status message. Keeps the wire quiet during fast-running tests.
+    let statusFlushScheduled = false;
+    const sendStatus = () => {
+        if (statusFlushScheduled)
+            return;
+        statusFlushScheduled = true;
+        setImmediate(() => {
+            statusFlushScheduled = false;
+            if (currentWs?.readyState !== ws_1.default.OPEN)
+                return;
+            try {
+                currentWs.send(JSON.stringify({
+                    type: "agent-status",
+                    agentName,
+                    timestamp: new Date().toISOString(),
+                    snapshot: snapshot(),
+                }));
+            }
+            catch { /* ignore */ }
+        });
+    };
+    // Periodic status keepalive — keeps elapsedMs fresh in the UI even if the
+    // agent is idle. 5s is plenty for an ops dashboard; cheap on the wire.
+    const statusInterval = setInterval(() => {
+        if (currentWs?.readyState === ws_1.default.OPEN && registered)
+            sendStatus();
+    }, 5000);
+    const connect = () => {
+        if (stopping)
+            return;
+        attempt++;
+        const spinner = !opts.silent && attempt === 1 ? (0, ora_1.default)("Connecting to Cutlery...").start() : null;
+        if (!opts.silent && !spinner)
+            process.stdout.write(chalk_1.default.gray(`   Reconnecting… (attempt ${attempt})\r`));
+        registered = false;
+        const ws = new ws_1.default(wsUrl);
+        currentWs = ws;
+        ws.on("open", () => {
+            reconnectDelay = 2000;
+            attempt = 0;
+            if (spinner) {
+                spinner.succeed(chalk_1.default.green("✅ Connected to Cutlery"));
+            }
+            else if (!opts.silent) {
+                process.stdout.write("\n");
+                console.log(chalk_1.default.green("✅ Reconnected to Cutlery"));
+            }
+            registered = false;
+            ws.send(JSON.stringify({
+                type: "agent-register",
+                agentName,
+                timestamp: new Date().toISOString(),
+                identity,
+                initialStatus: snapshot(),
+            }));
+            log(chalk_1.default.green(`\n✓ Agent "${agentName}" is ready to receive tests`));
+            if (!opts.silent)
+                console.log(chalk_1.default.gray("   Press Ctrl+C to disconnect\n"));
+        });
+        ws.on("message", async (data) => {
+            try {
+                const message = JSON.parse(data.toString());
+                if (opts.verbose) {
+                    log(chalk_1.default.gray(`📨 Received: ${JSON.stringify(message, null, 2)}`));
+                }
+                if (message.type === "registered") {
+                    registered = true;
+                    log(chalk_1.default.green(`✓ Registration confirmed by server`));
+                    opts.onRegistered?.();
+                }
+                else if (message.type === "evicted") {
+                    log(chalk_1.default.red(`\n✗ Server evicted this agent: ${message.reason || "duplicate name"}\n` +
+                        `  Re-run with a unique --name to connect multiple agents from the same machine.`));
+                    stopping = true;
+                    try {
+                        ws.close();
+                    }
+                    catch { /* ignore */ }
+                    opts.onEvicted?.(message.reason || "duplicate name");
+                }
+                else if (message.type === "ping") {
+                    ws.send(JSON.stringify({ type: "pong" }));
+                }
+                else if (message.type === "cancel-test") {
+                    if (activeExecutor) {
+                        log(chalk_1.default.yellow(`\n⏹  Cancelling test ${message.testCaseId}…`));
+                        activeExecutor.cancel();
+                        activeExecutor = null;
+                        running.delete(message.testCaseId);
+                        sendStatus();
+                    }
+                }
+                else if (message.type === "execute-test" || message.type === "run-test") {
+                    // Normalise both message formats:
+                    //   execute-test: { testCaseId, testCaseName, steps[], variables, baseUrl, ... }
+                    //   run-test (legacy): { testCase: { id, name, parsedSteps[], steps[], ... } }
+                    const isFlat = message.type === "execute-test";
+                    const testCaseId = isFlat ? message.testCaseId : (message.testCase?.id || message.testCase?.testCaseId);
+                    const testCaseName = isFlat ? (message.testCaseName || testCaseId) : message.testCase?.name;
+                    const baseUrl = isFlat ? message.baseUrl : message.testCase?.baseUrl;
+                    const automated_steps = isFlat
+                        ? (message.steps || [])
+                        : (message.testCase?.parsedSteps?.map((s) => s.description) || message.testCase?.steps || []);
+                    const variables = isFlat
+                        ? (message.variables || {})
+                        : (message.testCase?.test_variables || {});
+                    log(chalk_1.default.blue(`\n📋 Received test: ${testCaseName}`));
+                    log(chalk_1.default.gray(`   Test ID: ${testCaseId}`));
+                    log(chalk_1.default.gray(`   Steps: ${automated_steps.length}`));
+                    const testSpinner = !opts.silent ? (0, ora_1.default)("Executing test...").start() : null;
+                    // Track this test in the live status snapshot — the UI's agent
+                    // card / live viewer reads from here.
+                    const startedAtMs = Date.now();
+                    running.set(testCaseId, {
+                        testCaseId,
+                        testCaseName,
+                        startedAt: new Date(startedAtMs).toISOString(),
+                        startedAtMs,
+                        currentStep: 0,
+                        totalSteps: automated_steps.length,
+                        currentStepText: "starting…",
+                    });
+                    sendStatus();
+                    try {
+                        const executor = new mcp_executor_js_1.TestExecutor({
+                            headless: opts.headless,
+                            browserType: "chromium",
+                            baseUrl: baseUrl || "http://localhost:3000",
+                            outputDir: "./test-results",
+                            verbose: opts.verbose,
+                            onProgress: (update) => {
+                                // Update the running-test snapshot so the UI sees real-time
+                                // step progression on the agent card without having to
+                                // subscribe to per-test progress events.
+                                const entry = running.get(testCaseId);
+                                if (entry) {
+                                    if (typeof update.step === "number")
+                                        entry.currentStep = update.step;
+                                    if (typeof update.total === "number")
+                                        entry.totalSteps = update.total;
+                                    if (update.message)
+                                        entry.currentStepText = update.message;
+                                    sendStatus();
+                                }
+                                ws.send(JSON.stringify({
+                                    type: "test-update",
+                                    testCaseId,
+                                    data: {
+                                        type: "progress",
+                                        step: update.step,
+                                        total: update.total,
+                                        message: update.message,
+                                        status: update.type === "step-start"
+                                            ? "running"
+                                            : update.type === "step-complete"
+                                                ? "success"
+                                                : "failed",
+                                        error: update.error,
+                                        screenshot: update.screenshot,
+                                    },
+                                }));
+                            },
+                        });
+                        activeExecutor = executor;
+                        const result = await executor.execute({
+                            name: testCaseName,
+                            test_case_id: testCaseId,
+                            automated_steps,
+                            test_variables: variables,
+                        });
+                        activeExecutor = null;
+                        if (result.success) {
+                            testSpinner?.succeed(chalk_1.default.green("✅ Test PASSED"));
+                            ws.send(JSON.stringify({
+                                type: "test-result",
+                                testCaseId,
+                                success: true,
+                                steps: result.steps,
+                                screenshots: result.screenshots,
+                                timestamp: new Date().toISOString(),
+                            }));
+                            log(chalk_1.default.green(`   Passed: ${result.steps.filter((s) => !s.error).length}/${result.steps.length} steps`));
+                        }
+                        else {
+                            testSpinner?.fail(chalk_1.default.red("❌ Test FAILED"));
+                            ws.send(JSON.stringify({
+                                type: "test-result",
+                                testCaseId,
+                                success: false,
+                                steps: result.steps,
+                                error: result.error,
+                                screenshots: result.screenshots,
+                                timestamp: new Date().toISOString(),
+                            }));
+                            log(chalk_1.default.red(`   Failed: ${result.steps.filter((s) => s.error).length}/${result.steps.length} steps`));
+                        }
+                        log(chalk_1.default.gray("\n   Waiting for next test...\n"));
+                        running.delete(testCaseId);
+                        sendStatus();
+                    }
+                    catch (error) {
+                        testSpinner?.fail(chalk_1.default.red("❌ Test execution error"));
+                        if (!opts.silent)
+                            console.error(chalk_1.default.red(`   Error: ${error.message}`));
+                        ws.send(JSON.stringify({
+                            type: "test-result",
+                            testCaseId,
+                            success: false,
+                            error: error.message,
+                            timestamp: new Date().toISOString(),
+                        }));
+                        running.delete(testCaseId);
+                        lastErrorAt = Date.now();
+                        sendStatus();
+                    }
+                }
+            }
+            catch (error) {
+                if (!opts.silent)
+                    console.error(chalk_1.default.red(`Error processing message: ${error.message}`));
+            }
+        });
+        ws.on("error", (error) => {
+            const code = error.code || "";
+            const hint = code === "ECONNREFUSED"
+                ? `Connection refused — is the Cutlery app running at ${webAppUrl}?`
+                : code === "ENOTFOUND"
+                    ? `Host not found — check the URL: ${webAppUrl}`
+                    : code === "ETIMEDOUT"
+                        ? `Connection timed out — check the URL and network`
+                        : error.message || code || String(error);
+            if (spinner?.isSpinning) {
+                spinner.fail(chalk_1.default.red(hint));
+            }
+            // subsequent attempts: close handler will log the retry
+        });
+        ws.on("close", (code) => {
+            currentWs = null;
+            opts.onClose?.(code);
+            if (stopping)
+                return;
+            if (registered) {
+                log(chalk_1.default.yellow(`\n⚠️  Disconnected (code ${code}).`));
+            }
+            const delay = reconnectDelay;
+            reconnectDelay = Math.min(reconnectDelay * 1.5, 30000);
+            reconnectTimer = setTimeout(connect, delay);
+        });
+    };
+    connect();
+    return {
+        agentName,
+        url: webAppUrl,
+        startedAt,
+        isConnected: () => currentWs?.readyState === ws_1.default.OPEN,
+        isRegistered: () => registered,
+        stop: async () => {
+            stopping = true;
+            clearInterval(statusInterval);
+            if (reconnectTimer) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = null;
+            }
+            if (activeExecutor) {
+                try {
+                    activeExecutor.cancel();
+                }
+                catch { /* ignore */ }
+                activeExecutor = null;
+            }
+            if (currentWs) {
+                try {
+                    currentWs.close(1000, "stop");
+                }
+                catch { /* ignore */ }
+            }
+        },
+    };
+}
+program
+    .command("connect")
+    .description("Connect to Cutlery web app and execute tests remotely")
+    .option("-u, --url <url>", "Cutlery web app URL", process.env.CUTLERY_URL || "http://localhost:3002")
+    .option("-n, --name <name>", "Agent name (must be unique per connection)", process.env.AGENT_NAME || `agent-${require("os").hostname()}-${process.pid}`)
+    .option("--headless", "Run tests in headless mode (default: browser is visible)", false)
+    .option("-t, --tag <tag...>", "Capability tag(s) for routing (repeatable). Also reads AGENT_TAGS (comma-separated).")
+    .option("--max-concurrency <n>", "Max tests this agent will accept at once (default: 1)", (v) => parseInt(v, 10))
+    .option("-v, --verbose", "Verbose output", false)
+    .action(async (options) => {
+    const envTags = (process.env.AGENT_TAGS || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const tags = [...(options.tag || []), ...envTags];
+    await ensureBrowsersInstalled();
+    const handle = runConnect({
+        url: options.url,
+        name: options.name,
+        headless: !!options.headless,
+        verbose: !!options.verbose,
+        tags: tags.length ? tags : undefined,
+        maxConcurrency: options.maxConcurrency,
+        onEvicted: () => setTimeout(() => process.exit(1), 200),
+    });
+    process.on("SIGINT", () => {
+        console.log(chalk_1.default.yellow("\n\n⏸️  Disconnecting agent..."));
+        handle.stop().finally(() => setTimeout(() => process.exit(0), 200));
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// `serve` — local supervisor.
+//
+// Starts a tiny HTTP API on http://localhost:<port> that the Cutlery web UI
+// can call to spawn / stop / list `connect` child processes. This lets QAs
+// click "Start Agent" in Settings instead of pasting commands into a terminal.
+//
+// Usage:
+//   ./cutlery-agent-macos serve                     # default port 39007
+//   ./cutlery-agent-macos serve --port 39007 -v
+//
+// Endpoints (all CORS-enabled, including PNA preflight for HTTPS origins):
+//   GET  /health                              → { ok, version, agents: [...] }
+//   GET  /list                                → { agents: [{ name, pid, ... }] }
+//   POST /spawn  { name, url, headless? }     → { ok, name, pid }
+//   POST /stop   { name }                     → { ok }
+// ─────────────────────────────────────────────────────────────────────────────
+program
+    .command("serve")
+    .description("Run a local supervisor HTTP API so the Cutlery UI can start/stop agents")
+    .option("-p, --port <port>", "Local port to listen on", "39007")
+    .option("-v, --verbose", "Verbose logs", false)
+    .action(async (options) => {
+    const port = parseInt(options.port, 10);
+    const agents = new Map();
+    const log = (msg) => console.log(chalk_1.default.gray(`[serve ${new Date().toISOString()}] `) + msg);
+    // Per-agent log buffer for the /logs endpoint. We patch console while the
+    // agent is starting so any banner/error output is attributed to it; once
+    // running, the runConnect callbacks feed status lines in here too.
+    const LINE_BUFFER = 100;
+    const lastOutput = new Map();
+    const pushLine = (name, tag, text) => {
+        const trimmed = String(text).replace(/\r?\n$/, "");
+        if (!trimmed)
+            return;
+        const buf = lastOutput.get(name) || [];
+        buf.push(`[${new Date().toISOString()}] [${tag}] ${trimmed}`);
+        while (buf.length > LINE_BUFFER)
+            buf.shift();
+        lastOutput.set(name, buf);
+        if (options.verbose) {
+            console.log(chalk_1.default.gray(`  ${name} ${tag}: `) + trimmed);
+        }
+    };
+    const spawnAgent = (name, url, headless) => {
+        if (agents.has(name)) {
+            return { ok: false, error: `Agent "${name}" is already running here.` };
+        }
+        try {
+            lastOutput.set(name, []);
+            pushLine(name, "info", `starting agent → ${url} (headless=${headless})`);
+            const handle = runConnect({
+                url,
+                name,
+                headless,
+                verbose: !!options.verbose,
+                silent: true, // suppress banner/spinner; we capture status via callbacks
+                onRegistered: () => {
+                    pushLine(name, "ok", `registered with ${url}`);
+                    log(chalk_1.default.green(`✓ agent "${name}" registered with server`));
+                },
+                onClose: (code) => {
+                    pushLine(name, "warn", `websocket closed (code=${code}); will retry`);
+                },
+                onEvicted: (reason) => {
+                    pushLine(name, "err", `evicted by server: ${reason}`);
+                    log(chalk_1.default.red(`✗ agent "${name}" evicted: ${reason}`));
+                    // Drop the agent — runConnect.stop() also flips its internal stopping flag.
+                    const a = agents.get(name);
+                    if (a) {
+                        a.handle.stop().catch(() => { });
+                        agents.delete(name);
+                    }
+                },
+            });
+            agents.set(name, {
+                name,
+                url,
+                headless,
+                startedAt: new Date().toISOString(),
+                handle,
+            });
+            log(chalk_1.default.green(`▶ started agent "${name}" (in-process)`));
+            return { ok: true };
+        }
+        catch (err) {
+            pushLine(name, "err", `failed to start: ${err.message || err}`);
+            return { ok: false, error: err.message || String(err) };
+        }
+    };
+    const stopAgent = async (name) => {
+        const agent = agents.get(name);
+        if (!agent)
+            return { ok: false, error: `No agent "${name}" running here.` };
+        try {
+            await agent.handle.stop();
+            agents.delete(name);
+            pushLine(name, "info", "stopped by user");
+            log(chalk_1.default.yellow(`⏹ stopped agent "${name}"`));
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: err.message || String(err) };
+        }
+    };
+    const listAgents = () => Array.from(agents.values()).map(({ handle, ...rest }) => ({
+        ...rest,
+        connected: handle.isConnected(),
+        registered: handle.isRegistered(),
+    }));
+    const sendJson = (res, status, body, origin) => {
+        res.writeHead(status, {
+            "Content-Type": "application/json",
+            // Permissive CORS — supervisor binds to localhost only, so this is safe.
+            "Access-Control-Allow-Origin": origin || "*",
+            "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type, Authorization",
+            "Access-Control-Allow-Private-Network": "true",
+            Vary: "Origin",
+        });
+        res.end(JSON.stringify(body));
+    };
+    const readBody = (req) => new Promise((resolve, reject) => {
+        let data = "";
+        req.on("data", (chunk) => (data += chunk));
+        req.on("end", () => {
+            if (!data)
+                return resolve({});
+            try {
+                resolve(JSON.parse(data));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        req.on("error", reject);
+    });
+    const server = http.createServer(async (req, res) => {
+        const origin = req.headers.origin;
+        // CORS preflight — must include PNA header for HTTPS → http://localhost.
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, {
+                "Access-Control-Allow-Origin": origin || "*",
+                "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+                "Access-Control-Allow-Headers": "Content-Type, Authorization",
+                "Access-Control-Allow-Private-Network": "true",
+                "Access-Control-Max-Age": "600",
+                Vary: "Origin",
+            });
+            res.end();
+            return;
+        }
+        const url = req.url || "/";
+        try {
+            if (req.method === "GET" && (url === "/health" || url === "/")) {
+                return sendJson(res, 200, {
+                    ok: true,
+                    service: "cutlery-agent-supervisor",
+                    version: program.version() || "1.0.0",
+                    agents: listAgents(),
+                }, origin);
+            }
+            if (req.method === "GET" && url === "/list") {
+                return sendJson(res, 200, { agents: listAgents() }, origin);
+            }
+            // GET /logs/<agent-name> — tail of captured stdout/stderr for that agent.
+            if (req.method === "GET" && url.startsWith("/logs/")) {
+                const name = decodeURIComponent(url.slice("/logs/".length));
+                const lines = lastOutput.get(name) || [];
+                return sendJson(res, 200, { name, running: agents.has(name), lines }, origin);
+            }
+            if (req.method === "POST" && url === "/spawn") {
+                const body = await readBody(req);
+                const name = String(body.name || "").trim();
+                const targetUrl = String(body.url || "").trim();
+                const headless = !!body.headless;
+                if (!name)
+                    return sendJson(res, 400, { ok: false, error: "name required" }, origin);
+                if (!targetUrl)
+                    return sendJson(res, 400, { ok: false, error: "url required" }, origin);
+                const result = spawnAgent(name, targetUrl, headless);
+                return sendJson(res, result.ok ? 200 : 409, { ...result, name }, origin);
+            }
+            if (req.method === "POST" && url === "/stop") {
+                const body = await readBody(req);
+                const name = String(body.name || "").trim();
+                if (!name)
+                    return sendJson(res, 400, { ok: false, error: "name required" }, origin);
+                const result = await stopAgent(name);
+                return sendJson(res, result.ok ? 200 : 404, result, origin);
+            }
+            return sendJson(res, 404, { error: "Not found" }, origin);
+        }
+        catch (err) {
+            return sendJson(res, 500, { error: err.message || String(err) }, origin);
+        }
+    });
+    server.listen(port, "127.0.0.1", () => {
+        console.log(chalk_1.default.blue("🛰  Cutlery Agent Supervisor"));
+        console.log(chalk_1.default.gray(`   Listening on http://localhost:${port}`));
+        console.log(chalk_1.default.gray(`   Open Cutlery → Settings → Local Agent → Agent Profiles to start agents.`));
+        console.log(chalk_1.default.gray("   Press Ctrl+C to stop the supervisor."));
+    });
+    const shutdown = () => {
+        console.log(chalk_1.default.yellow("\n⏸  Shutting down supervisor…"));
+        for (const agent of agents.values()) {
+            agent.handle.stop().catch(() => { });
+        }
+        server.close(() => process.exit(0));
+        // Hard-exit if children don't release the port.
+        setTimeout(() => process.exit(0), 2000);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+});
+program.parse();
+//# sourceMappingURL=cli.js.map