browser-debugging-daemon 1.0.0

package/daemon.js

@@ -0,0 +1,931 @@
+#!/usr/bin/env node
+import express from 'express';
+import cors from 'cors';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import fs from 'fs';
+import { BrowserRuntime } from './runtime/BrowserRuntime.js';
+import { BrowserSubagent } from './subagent/BrowserSubagent.js';
+import { TaskRunner } from './orchestrator/TaskRunner.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const DAEMON_HOST = process.env.BROWSER_DAEMON_HOST || '127.0.0.1';
+const DAEMON_PORT = Number.parseInt(process.env.BROWSER_DAEMON_PORT, 10) || 3005;
+const DAEMON_TOKEN = typeof process.env.BROWSER_DAEMON_TOKEN === 'string'
+    ? process.env.BROWSER_DAEMON_TOKEN.trim()
+    : '';
+const CORS_ORIGINS_RAW = typeof process.env.BROWSER_DAEMON_CORS_ORIGINS === 'string'
+    ? process.env.BROWSER_DAEMON_CORS_ORIGINS.trim()
+    : '';
+const CORS_ALLOWED_ORIGINS = CORS_ORIGINS_RAW
+    ? CORS_ORIGINS_RAW.split(',').map((item) => item.trim()).filter(Boolean)
+    : [
+        `http://${DAEMON_HOST}:${DAEMON_PORT}`,
+        `http://127.0.0.1:${DAEMON_PORT}`,
+        `http://localhost:${DAEMON_PORT}`,
+    ];
+
+const app = express();
+app.use(cors({
+    origin(origin, callback) {
+        if (!origin) {
+            callback(null, true);
+            return;
+        }
+        if (CORS_ALLOWED_ORIGINS.includes(origin)) {
+            callback(null, true);
+            return;
+        }
+        callback(null, false);
+    },
+    methods: ['GET', 'POST', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'Authorization'],
+}));
+app.use(express.json());
+const runtime = new BrowserRuntime(__dirname);
+const subagent = new BrowserSubagent(runtime);
+const taskRunner = new TaskRunner(__dirname, { runtime, subagent });
+const dashboardDir = path.join(__dirname, 'dashboard');
+const artifactsDir = path.join(__dirname, 'artifacts');
+const traceViewerDir = path.join(__dirname, 'node_modules', 'playwright-core', 'lib', 'vite', 'traceViewer');
+const SUPPORTED_BROWSER_SOURCES = new Set(['auto', 'managed', 'attached']);
+
+function normalizeBrowserSource(value) {
+    const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    if (SUPPORTED_BROWSER_SOURCES.has(normalized)) {
+        return normalized;
+    }
+    return 'auto';
+}
+
+function normalizeOptionalBrowserSource(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        return null;
+    }
+    return normalizeBrowserSource(value);
+}
+
+function resolveAuthToken(req) {
+    const authorization = req.headers.authorization || '';
+    if (authorization.startsWith('Bearer ')) {
+        return authorization.slice('Bearer '.length).trim();
+    }
+    if (typeof req.query?.token === 'string') {
+        return req.query.token.trim();
+    }
+    if (typeof req.body?.token === 'string') {
+        return req.body.token.trim();
+    }
+    return '';
+}
+
+function apiAuthMiddleware(req, res, next) {
+    if (!DAEMON_TOKEN || req.method === 'OPTIONS') {
+        return next();
+    }
+
+    const token = resolveAuthToken(req);
+    if (token === DAEMON_TOKEN) {
+        return next();
+    }
+
+    return res.status(401).json({
+        error: 'Unauthorized. Provide Bearer token or token query parameter.',
+    });
+}
+
+function toPublicAssetUrl(filePath) {
+    if (!filePath) return null;
+    const relativePath = path.relative(__dirname, filePath);
+    if (relativePath.startsWith('..')) {
+        return null;
+    }
+    return `/${relativePath.split(path.sep).join('/')}`;
+}
+
+function readTextFileSafe(filePath) {
+    if (!filePath || !fs.existsSync(filePath)) {
+        return null;
+    }
+    return fs.readFileSync(filePath, 'utf8');
+}
+
+function readJsonFileSafe(filePath) {
+    if (!filePath || !fs.existsSync(filePath)) {
+        return null;
+    }
+
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    } catch (error) {
+        return null;
+    }
+}
+
+function readJsonLinesSafe(filePath, limit = 120) {
+    if (!filePath || !fs.existsSync(filePath)) {
+        return [];
+    }
+
+    const lines = fs.readFileSync(filePath, 'utf8')
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+
+    return lines.slice(-limit).map((line) => {
+        try {
+            return JSON.parse(line);
+        } catch (error) {
+            return {
+                timestamp: new Date().toISOString(),
+                type: 'invalid_event',
+                payload: {
+                    raw: line,
+                    error: error.message,
+                },
+            };
+        }
+    });
+}
+
+function serializeRun(run, { includeDetails = false } = {}) {
+    if (!run) return null;
+
+    const lastHistoryEntry = run.result?.history?.[run.result.history.length - 1] || null;
+    const reportJsonUrl = toPublicAssetUrl(run.reports?.reportJsonPath);
+    const walkthroughUrl = toPublicAssetUrl(run.reports?.walkthroughPath);
+    const timelineJsonUrl = toPublicAssetUrl(run.reports?.timelineJsonPath);
+
+    const serialized = {
+        id: run.id,
+        taskInstruction: run.taskInstruction,
+        maxSteps: run.maxSteps,
+        browserSource: run.browserSource || "managed",
+        cdpEndpoint: run.cdpEndpoint || null,
+        status: run.status,
+        createdAt: run.createdAt,
+        startedAt: run.startedAt,
+        finishedAt: run.finishedAt,
+        summary: run.summary,
+        error: run.error,
+        pendingInput: run.pendingInput,
+        template: run.template ? {
+            id: run.template.id,
+            name: run.template.name,
+            description: run.template.description || "",
+        } : null,
+        templateEvaluation: run.templateEvaluation || run.result?.templateEvaluation || null,
+        artifacts: run.artifacts ? {
+            ...run.artifacts,
+            currentViewUrl: toPublicAssetUrl(run.artifacts.currentViewPath),
+            traceUrl: toPublicAssetUrl(run.artifacts.tracePath),
+            traceUrls: (run.artifacts.traceFiles || []).map((filePath) => toPublicAssetUrl(filePath)).filter(Boolean),
+            eventsUrl: toPublicAssetUrl(run.artifacts.eventsPath),
+            videoUrls: (run.artifacts.videoFiles || []).map((filePath) => toPublicAssetUrl(filePath)).filter(Boolean),
+        } : null,
+        reports: run.reports ? {
+            reportJsonPath: run.reports.reportJsonPath,
+            walkthroughPath: run.reports.walkthroughPath,
+            timelineJsonPath: run.reports.timelineJsonPath || null,
+            reportJsonUrl,
+            walkthroughUrl,
+            timelineJsonUrl,
+        } : null,
+        latestScreenshotUrl: toPublicAssetUrl(lastHistoryEntry?.actionResult?.screenshotPath) || toPublicAssetUrl(run.artifacts?.currentViewPath),
+    };
+
+    if (!includeDetails) {
+        return serialized;
+    }
+
+    return {
+        ...serialized,
+        walkthroughContent: readTextFileSafe(run.reports?.walkthroughPath),
+        timelineContent: readJsonFileSafe(run.reports?.timelineJsonPath),
+        recentEvents: readJsonLinesSafe(run.artifacts?.eventsPath, 120),
+        result: run.result ? {
+            status: run.result.status,
+            step: run.result.step,
+            summary: run.result.summary,
+            page: run.result.page,
+            verification: run.result.verification,
+            operatorMessages: run.result.operatorMessages,
+            pendingInput: run.result.pendingInput,
+            templateEvaluation: run.result.templateEvaluation || null,
+            debug: run.result.debug,
+            capabilities: run.result.debug?.capabilities || null,
+            history: (run.result.history || []).map((entry) => ({
+                step: entry.step,
+                stepStartedAt: entry.stepStartedAt || null,
+                stepFinishedAt: entry.stepFinishedAt || null,
+                actionDurationMs: entry.actionDurationMs ?? null,
+                elapsedMs: entry.elapsedMs ?? null,
+                videoOffsetSeconds: entry.videoOffsetSeconds ?? null,
+                thinking: entry.thinking,
+                summary: entry.summary,
+                action: entry.action,
+                page: entry.page || null,
+                actionResult: {
+                    ...entry.actionResult,
+                    screenshotUrl: toPublicAssetUrl(entry.actionResult?.screenshotPath),
+                },
+                verification: entry.verification,
+                debug: entry.debug,
+            })),
+        } : null,
+    };
+}
+
+app.use('/dashboard-assets', express.static(dashboardDir));
+
+app.get('/dashboard', async (req, res) => {
+    res.sendFile(path.join(dashboardDir, 'index.html'));
+});
+
+app.use((req, res, next) => {
+    if (
+        req.path === '/dashboard'
+        || req.path.startsWith('/dashboard-assets')
+        || req.path.startsWith('/trace-viewer')
+        || req.path.startsWith('/trace-zip')
+    ) {
+        return next();
+    }
+    return apiAuthMiddleware(req, res, next);
+});
+
+app.use('/artifacts', express.static(artifactsDir));
+
+// Serve Playwright's built-in trace viewer SPA directly from node_modules
+if (fs.existsSync(traceViewerDir)) {
+    app.use('/trace-viewer', express.static(traceViewerDir));
+}
+
+// Redirect to trace viewer with the correct trace URL
+app.get('/trace/:sessionId/:traceFile', (req, res) => {
+    const { sessionId, traceFile } = req.params;
+    if (!sessionId || !traceFile) {
+        return res.status(400).json({ error: 'sessionId and traceFile are required.' });
+    }
+
+    // Build the trace zip URL using the auth-aware proxy route
+    const token = resolveAuthToken(req);
+    const proxyUrl = `${req.protocol}://${req.get('host')}/trace-zip/${sessionId}/${encodeURIComponent(traceFile)}`;
+    const traceUrl = token ? `${proxyUrl}?token=${encodeURIComponent(token)}` : proxyUrl;
+    const viewerUrl = `/trace-viewer/?trace=${encodeURIComponent(traceUrl)}`;
+    res.redirect(viewerUrl);
+});
+
+// Auth-aware proxy for trace zip files (service worker cannot send Bearer tokens)
+app.get('/trace-zip/:sessionId/:traceFile', (req, res) => {
+    const { sessionId, traceFile } = req.params;
+    if (!sessionId || !traceFile) {
+        return res.status(400).json({ error: 'sessionId and traceFile are required.' });
+    }
+
+    // Validate token via query param (same as SSE)
+    if (DAEMON_TOKEN) {
+        const token = resolveAuthToken(req);
+        if (token !== DAEMON_TOKEN) {
+            return res.status(401).json({ error: 'Unauthorized.' });
+        }
+    }
+
+    // Prevent path traversal
+    const safeSessionId = path.basename(sessionId);
+    const safeTraceFile = path.basename(traceFile);
+    const tracePath = path.join(artifactsDir, safeSessionId, 'traces', safeTraceFile);
+
+    if (!tracePath.startsWith(artifactsDir)) {
+        return res.status(403).json({ error: 'Invalid path.' });
+    }
+
+    if (!fs.existsSync(tracePath)) {
+        return res.status(404).json({ error: 'Trace file not found.' });
+    }
+
+    res.setHeader('Content-Type', 'application/zip');
+    res.setHeader('Content-Disposition', `inline; filename="${safeTraceFile}"`);
+    fs.createReadStream(tracePath).pipe(res);
+});
+
+app.get('/current_view.png', async (req, res) => {
+    res.sendFile(path.join(__dirname, 'current_view.png'));
+});
+
+app.post('/start', async (req, res) => {
+    try {
+        const browserSource = normalizeBrowserSource(req.body?.browser_source);
+        const result = await runtime.start({
+            source: browserSource,
+            cdpEndpoint: req.body?.cdp_endpoint || undefined,
+        });
+        if (result.alreadyRunning) {
+            return res.json({ status: "ok", message: "Browser already running" });
+        }
+        res.json({
+            status: "ok",
+            message: "Browser started successfully",
+            runtime: {
+                requested_source: result.requestedSource,
+                effective_source: result.sessionSource,
+                fallback_reason: result.autoFallbackReason || null,
+            },
+            artifacts: result.artifacts,
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.get('/cdp-health', async (req, res) => {
+    try {
+        const health = await runtime.getCdpHealth({
+            endpoint: req.query.cdp_endpoint || undefined,
+            timeoutMs: Number.parseInt(req.query.timeout_ms, 10) || 3000,
+        });
+        res.json({
+            status: health.ok ? "ok" : "error",
+            health,
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.get('/attach-diagnostics', async (req, res) => {
+    try {
+        const diagnostics = await runtime.getCdpDiagnostics({
+            endpoint: req.query.cdp_endpoint || undefined,
+            timeoutMs: Number.parseInt(req.query.timeout_ms, 10) || 3000,
+        });
+        res.json({
+            status: diagnostics.ok ? "ok" : "warn",
+            diagnostics,
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/goto', async (req, res) => {
+    try {
+        const { url } = req.body;
+        console.log(`🌐 Navigating to ${url}...`);
+        const result = await runtime.goto(url);
+        res.json({ status: "ok", message: `Navigated to ${url}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.get('/observe', async (req, res) => {
+    try {
+        console.log(`👁️ Injecting Set-of-Mark (SoM) indicators...`);
+        const result = await runtime.observe();
+
+        console.log(`📸 Screenshot with ${result.elements.length} markers saved to ${result.screenshotPath}`);
+        res.json({
+            status: "ok",
+            elements: result.elements,
+            screenshot_path: result.screenshotPath,
+            message: `Observed ${result.elements.length} interactive elements.`
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/click', async (req, res) => {
+    try {
+        const { id } = req.body;
+        const result = await runtime.click(parseInt(id, 10));
+
+        console.log(`🖱️ Clicking element ID ${id} at (${result.target.x}, ${result.target.y}) [${result.target.tag}]`);
+        res.json({ status: "ok", message: `Clicked element ${id}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/type', async (req, res) => {
+    try {
+        const { id, text, submit } = req.body;
+        const result = await runtime.type(parseInt(id, 10), text, { submit: !!submit });
+        console.log(`⌨️ Typing into element ID ${id} at (${result.target.x}, ${result.target.y}): "${text}"${submit ? " +Enter" : ""}`);
+        res.json({ status: "ok", message: `Typed text into element ${id}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/hover', async (req, res) => {
+    try {
+        const { id } = req.body;
+        const result = await runtime.hover(parseInt(id, 10));
+
+        console.log(`✨ Hovering element ID ${id} at (${result.target.x}, ${result.target.y})`);
+
+        res.json({ status: "ok", message: `Hovered over element ${id}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/scroll', async (req, res) => {
+    try {
+        const { direction } = req.body; // 'up', 'down', 'top', 'bottom'
+        console.log(`📜 Scrolling ${direction}...`);
+        const result = await runtime.scroll(direction);
+        res.json({ status: "ok", message: `Scrolled ${direction}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/keypress', async (req, res) => {
+    try {
+        const { key } = req.body;
+        console.log(`🎯 Pressing key: ${key}`);
+        const result = await runtime.keypress(key);
+        res.json({ status: "ok", message: `Pressed key ${key}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/upload', async (req, res) => {
+    try {
+        const { id, paths, files } = req.body;
+        const result = await runtime.upload(parseInt(id, 10), { paths: paths || [], files: files || [] });
+        console.log(`📎 Uploaded ${result.fileCount} file(s) to element ID ${id}`);
+        res.json({ status: "ok", message: `Uploaded ${result.fileCount} file(s) to element ${id}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/drag', async (req, res) => {
+    try {
+        const { fromId, toId } = req.body;
+        const result = await runtime.drag(parseInt(fromId, 10), parseInt(toId, 10));
+        console.log(`↔️ Dragged element ID ${fromId} to element ID ${toId}`);
+        res.json({ status: "ok", message: `Dragged element ${fromId} to ${toId}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/drag-file', async (req, res) => {
+    try {
+        const { toId, paths, files } = req.body;
+        const result = await runtime.dragFile({ paths: paths || [], files: files || [], toId: parseInt(toId, 10) });
+        console.log(`📂 Dragged ${result.fileCount} file(s) to element ID ${toId}`);
+        res.json({ status: "ok", message: `Dragged ${result.fileCount} file(s) to element ${toId}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/wait-for', async (req, res) => {
+    try {
+        const { text, textGone, selector, timeout } = req.body;
+        console.log(`⏳ Waiting for: ${text || textGone || selector || "unknown"} (timeout: ${timeout || 30000}ms)`);
+        const result = await runtime.waitFor({ text, textGone, selector, timeout });
+        if (result.timedOut) {
+            res.json({ status: "timeout", message: `Condition not met after ${result.waitedMs}ms`, ...result });
+        } else {
+            res.json({ status: "ok", message: `Wait condition met: ${result.matched}`, ...result });
+        }
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/evaluate', async (req, res) => {
+    try {
+        const { expression } = req.body;
+        if (!expression) throw new Error("'expression' is required.");
+        console.log(`🔧 Evaluating JS (${expression.length} chars)`);
+        const result = await runtime.evaluate(expression);
+        res.json({ status: "ok", ...result });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/select-option', async (req, res) => {
+    try {
+        const { id, values } = req.body;
+        const result = await runtime.selectOption(parseInt(id, 10), values);
+        console.log(`📋 Selected option(s) ${JSON.stringify(values)} in element ID ${id}`);
+        res.json({ status: "ok", message: `Selected option(s) in element ${id}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/dialog', async (req, res) => {
+    try {
+        const { action, promptText } = req.body;
+        console.log(`💬 Handling dialog: ${action || "accept"}`);
+        const result = await runtime.handleDialog({ action: action || "accept", promptText: promptText || "" });
+        res.json({ status: "ok", ...result });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/navigate-back', async (req, res) => {
+    try {
+        console.log(`◀️ Navigating back`);
+        const result = await runtime.goBack();
+        res.json({ status: "ok", message: `Navigated back to ${result.url}`, screenshot_path: result.screenshotPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/tabs', async (req, res) => {
+    try {
+        const { action, index, url } = req.body;
+        console.log(`📑 Tab action: ${action}`);
+        const result = await runtime.tabAction(action, { index, url });
+        res.json({ status: "ok", ...result });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.get('/debug-state', async (req, res) => {
+    try {
+        const limit = Number.parseInt(req.query.limit, 10) || 20;
+        res.json({
+            status: "ok",
+            debug_state: runtime.getDebugState(limit),
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.get('/text-layout-audit', async (req, res) => {
+    try {
+        const limit = Number.parseInt(req.query.limit, 10) || 80;
+        const selectors = typeof req.query.selectors === "string" ? req.query.selectors : undefined;
+        const overflowThreshold = Number.parseFloat(req.query.overflow_threshold);
+        const audit = await runtime.auditTextLayout({
+            limit,
+            selectors,
+            overflowThreshold: Number.isFinite(overflowThreshold) ? overflowThreshold : undefined,
+        });
+        res.json({
+            status: "ok",
+            audit,
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/delegate', async (req, res) => {
+    try {
+        const {
+            task_instruction: taskInstruction,
+            max_steps: maxSteps,
+            browser_source: browserSource,
+            cdp_endpoint: cdpEndpoint,
+            auto_stop: autoStopInput,
+        } = req.body;
+        const autoStop = autoStopInput !== false;
+        if (!taskInstruction) {
+            throw new Error("task_instruction is required.");
+        }
+
+        let result = await subagent.delegateTask(taskInstruction, {
+            maxSteps,
+            startOptions: {
+                source: normalizeBrowserSource(browserSource),
+                cdpEndpoint: cdpEndpoint || undefined,
+            },
+        });
+
+        if (autoStop) {
+            const stopResult = await runtime.stop().catch(() => null);
+            if (stopResult?.artifacts) {
+                result.artifacts = stopResult.artifacts;
+                result.debug = {
+                    ...(result.debug || {}),
+                    artifacts: stopResult.artifacts,
+                };
+                const refreshedReports = subagent.writeReports(result);
+                result.reports = refreshedReports;
+            }
+        }
+
+        res.json({
+            status: "ok",
+            result,
+            runtime: {
+                auto_stop: autoStop,
+            },
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.get('/run-templates', async (req, res) => {
+    try {
+        const limit = Number.parseInt(req.query.limit, 10) || 100;
+        res.json({
+            status: "ok",
+            templates: taskRunner.listTemplates(limit),
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/run-templates', async (req, res) => {
+    try {
+        const timeoutPolicyInput = req.body?.timeout_policy || req.body?.timeoutPolicy || {};
+        const template = taskRunner.saveTemplate({
+            id: req.body?.id || null,
+            name: req.body?.name,
+            description: req.body?.description,
+            taskInstruction: req.body?.task_instruction ?? req.body?.taskInstruction,
+            browserSource: normalizeOptionalBrowserSource(req.body?.browser_source ?? req.body?.browserSource) || "auto",
+            cdpEndpoint: req.body?.cdp_endpoint ?? req.body?.cdpEndpoint ?? null,
+            startUrl: req.body?.start_url ?? req.body?.startUrl ?? "",
+            preLoginChecks: req.body?.pre_login_checks ?? req.body?.preLoginChecks ?? [],
+            assertionRules: req.body?.assertion_rules ?? req.body?.assertionRules ?? [],
+            timeoutPolicy: {
+                maxSteps: timeoutPolicyInput.max_steps ?? timeoutPolicyInput.maxSteps,
+                handoffTimeoutMs: timeoutPolicyInput.handoff_timeout_ms ?? timeoutPolicyInput.handoffTimeoutMs,
+            },
+        });
+        res.json({
+            status: "ok",
+            template,
+        });
+    } catch (err) {
+        res.status(400).json({ error: err.message });
+    }
+});
+
+app.delete('/run-templates/:templateId', async (req, res) => {
+    try {
+        const template = taskRunner.deleteTemplate(req.params.templateId);
+        res.json({
+            status: "ok",
+            template,
+        });
+    } catch (err) {
+        res.status(404).json({ error: err.message });
+    }
+});
+
+app.get('/run-templates/:templateId/compare', async (req, res) => {
+    try {
+        const templateId = req.params.templateId;
+        const comparison = taskRunner.compareTemplateRuns(templateId, {
+            limit: Number.parseInt(req.query.limit, 10) || 8,
+        });
+        if (!comparison.template) {
+            res.status(404).json({ error: `Template not found: ${templateId}` });
+            return;
+        }
+        res.json({
+            status: "ok",
+            comparison: {
+                ...comparison,
+                runs: comparison.runs.map((run) => serializeRun(run)),
+            },
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/run-templates/:templateId/runs', async (req, res) => {
+    try {
+        const run = taskRunner.createRunFromTemplate(req.params.templateId, {
+            taskInstruction: req.body?.task_instruction || req.body?.taskInstruction || "",
+            maxSteps: req.body?.max_steps ?? req.body?.maxSteps,
+            browserSource: normalizeOptionalBrowserSource(req.body?.browser_source ?? req.body?.browserSource) || undefined,
+            cdpEndpoint: req.body?.cdp_endpoint ?? req.body?.cdpEndpoint ?? null,
+            handoffTimeoutMs: req.body?.handoff_timeout_ms ?? req.body?.handoffTimeoutMs,
+        });
+        res.json({
+            status: "ok",
+            run: serializeRun(run),
+        });
+    } catch (err) {
+        res.status(400).json({ error: err.message });
+    }
+});
+
+app.post('/runs', async (req, res) => {
+    try {
+        const {
+            task_instruction: taskInstruction,
+            max_steps: maxSteps,
+            browser_source: browserSource,
+            cdp_endpoint: cdpEndpoint,
+            template_id: templateId,
+            handoff_timeout_ms: handoffTimeoutMs,
+        } = req.body;
+        let run = null;
+        if (templateId) {
+            run = taskRunner.createRunFromTemplate(templateId, {
+                taskInstruction: taskInstruction || "",
+                maxSteps,
+                browserSource: normalizeOptionalBrowserSource(browserSource) || undefined,
+                cdpEndpoint: cdpEndpoint || null,
+                handoffTimeoutMs,
+            });
+        } else if (!taskInstruction) {
+            throw new Error("task_instruction is required.");
+        } else {
+            run = taskRunner.createRun(taskInstruction, {
+                maxSteps,
+                browserSource: normalizeBrowserSource(browserSource),
+                cdpEndpoint: cdpEndpoint || null,
+                handoffTimeoutMs,
+            });
+        }
+        res.json({
+            status: "ok",
+            run: serializeRun(run),
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.get('/runs', async (req, res) => {
+    try {
+        const limit = Number.parseInt(req.query.limit, 10) || 20;
+        res.json({
+            status: "ok",
+            runs: taskRunner.listRuns(limit).map((run) => serializeRun(run)),
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.get('/runs/stream', async (req, res) => {
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.flushHeaders?.();
+
+    const send = (payload) => {
+        res.write(`data: ${JSON.stringify(payload)}\n\n`);
+    };
+
+    send({
+        type: 'snapshot',
+        timestamp: new Date().toISOString(),
+    });
+
+    const unsubscribe = taskRunner.subscribe((event) => {
+        send(event);
+    });
+
+    const keepAlive = setInterval(() => {
+        res.write(': ping\n\n');
+    }, 15000);
+
+    req.on('close', () => {
+        clearInterval(keepAlive);
+        unsubscribe();
+        res.end();
+    });
+});
+
+app.get('/runs/:runId', async (req, res) => {
+    try {
+        const run = taskRunner.getRun(req.params.runId);
+        if (!run) {
+            res.status(404).json({ error: `Run not found: ${req.params.runId}` });
+            return;
+        }
+
+        res.json({
+            status: "ok",
+            run: serializeRun(run, { includeDetails: true }),
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/runs/:runId/reply', async (req, res) => {
+    try {
+        const { instruction } = req.body;
+        if (!instruction || !String(instruction).trim()) {
+            throw new Error("instruction is required.");
+        }
+
+        const run = await taskRunner.replyToRun(req.params.runId, String(instruction).trim());
+        res.json({
+            status: "ok",
+            run: serializeRun(run, { includeDetails: true }),
+        });
+    } catch (err) {
+        res.status(400).json({ error: err.message });
+    }
+});
+
+app.post('/runs/:runId/manual-control', async (req, res) => {
+    try {
+        const reason = String(req.body?.reason || "Manual control requested by operator.").trim();
+        const run = await taskRunner.requestManualControl(req.params.runId, reason);
+        res.json({
+            status: "ok",
+            run: serializeRun(run, { includeDetails: true }),
+        });
+    } catch (err) {
+        res.status(400).json({ error: err.message });
+    }
+});
+
+app.post('/runs/:runId/resume', async (req, res) => {
+    try {
+        const instruction = String(req.body?.instruction || "Manual control complete. Continue from the current page.").trim();
+        const run = await taskRunner.resumeRun(req.params.runId, instruction);
+        res.json({
+            status: "ok",
+            run: serializeRun(run, { includeDetails: true }),
+        });
+    } catch (err) {
+        res.status(400).json({ error: err.message });
+    }
+});
+
+app.post('/runs/:runId/abort', async (req, res) => {
+    try {
+        const reason = String(req.body?.reason || "Run aborted by operator.").trim();
+        const run = taskRunner.abortRun(req.params.runId, reason);
+        res.json({
+            status: "ok",
+            run: serializeRun(run, { includeDetails: true }),
+        });
+    } catch (err) {
+        res.status(400).json({ error: err.message });
+    }
+});
+
+app.post('/stop', async (req, res) => {
+    try {
+        const result = await runtime.stop();
+        if (result.alreadyStopped) {
+            return res.json({ status: "ok", message: "Browser not running" });
+        }
+        console.log(`🛑 Stopping browser daemon...`);
+        res.json({ status: "ok", message: `Browser stopped. Trace saved to ${result.artifacts?.tracePath}`, artifacts: result.artifacts });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.listen(DAEMON_PORT, DAEMON_HOST, () => {
+    console.log(`=========================================`);
+    console.log(`🤖 Browser Agent Daemon running on ${DAEMON_HOST}:${DAEMON_PORT}`);
+    console.log(`   - Auth token required: ${DAEMON_TOKEN ? 'yes' : 'no'}`);
+    console.log(`   - Allowed CORS origins: ${CORS_ALLOWED_ORIGINS.join(', ') || 'none'}`);
+    console.log(`   - /artifacts and API routes are protected when auth token is enabled`);
+    console.log(`   - POST /start`);
+    console.log(`   - GET  /cdp-health?cdp_endpoint=http://127.0.0.1:9222`);
+    console.log(`   - GET  /attach-diagnostics?cdp_endpoint=http://127.0.0.1:9222`);
+    console.log(`   - POST /goto { "url": "..." }`);
+    console.log(`   - GET  /observe`);
+    console.log(`   - POST /click { "id": 1 }`);
+    console.log(`   - POST /hover { "id": 1 }`);
+    console.log(`   - POST /type { "id": 1, "text": "..." }`);
+    console.log(`   - POST /keypress { "key": "Enter" }`);
+    console.log(`   - POST /scroll { "direction": "down|up|top|bottom" }`);
+    console.log(`   - GET  /debug-state?limit=20`);
+    console.log(`   - GET  /text-layout-audit?limit=80`);
+    console.log(`   - POST /delegate { "task_instruction": "...", "max_steps": 12 }`);
+    console.log(`   - POST /runs { "task_instruction": "...", "max_steps": 12 }`);
+    console.log(`   - GET  /run-templates`);
+    console.log(`   - POST /run-templates { "name": "...", "start_url": "...", "pre_login_checks": [], "assertion_rules": [] }`);
+    console.log(`   - POST /run-templates/:templateId/runs`);
+    console.log(`   - GET  /run-templates/:templateId/compare`);
+    console.log(`   - GET  /runs?limit=20`);
+    console.log(`   - GET  /runs/:runId`);
+    console.log(`   - POST /runs/:runId/reply { "instruction": "..." }`);
+    console.log(`   - POST /runs/:runId/manual-control { "reason": "..." }`);
+    console.log(`   - POST /runs/:runId/resume { "instruction": "..." }`);
+    console.log(`   - POST /runs/:runId/abort { "reason": "..." }`);
+    console.log(`   - GET  /dashboard`);
+    console.log(`   - GET  /trace/:sessionId/:traceFile  (Playwright Trace Viewer)`);
+    console.log(`   - POST /stop`);
+    console.log(`=========================================`);
+});