camofox-browser 2.1.1 → 2.4.1

package/dist/src/routes/core.js

@@ -47,11 +47,13 @@ const rate_limit_1 = require("../middleware/rate-limit");
 const config_1 = require("../utils/config");
 const presets_1 = require("../utils/presets");
 const context_pool_1 = require("../services/context-pool");
+const lifecycle_controller_1 = require("../services/lifecycle-controller");
 const vnc_1 = require("../services/vnc");
 const session_1 = require("../services/session");
 const tab_1 = require("../services/tab");
 const download_1 = require("../services/download");
 const resource_extractor_1 = require("../services/resource-extractor");
+const structured_extractor_1 = require("../services/structured-extractor");
 const batch_downloader_1 = require("../services/batch-downloader");
 const tracing_1 = require("../services/tracing");
 const CONFIG = (0, config_1.loadConfig)();
@@ -82,6 +84,27 @@ function getTracingErrorStatus(err) {
         return 409;
     if (message.includes('No active chunk'))
         return 400;
+    if (message.includes('Invalid trace output path'))
+        return 400;
+    return 500;
+}
+function getTraceArtifactErrorStatus(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes('Invalid trace filename'))
+        return 400;
+    if (message.includes('does not belong to this user'))
+        return 404;
+    if (typeof err === 'object' && err !== null && 'code' in err && err.code === 'ENOENT')
+        return 404;
+    return 500;
+}
+function getRouteErrorStatus(err) {
+    if (typeof err === 'object' && err !== null && 'statusCode' in err && typeof err.statusCode === 'number') {
+        return err.statusCode;
+    }
+    if (typeof err === 'object' && err !== null && 'status' in err && typeof err.status === 'number') {
+        return err.status;
+    }
     return 500;
 }
 // Import cookies into a user's browser context (Playwright cookies format)
@@ -147,7 +170,23 @@ router.post('/sessions/:userId/cookies', express_1.default.json({ limit: '512kb'
             session = found.session;
         }
         else {
-            session = await (0, session_1.getSession)(userId);
+            const canonical = (0, session_1.getCanonicalProfile)(userId);
+            if (!canonical) {
+                (0, logging_1.log)('warn', 'cookie import rejected: no canonical profile', { userId: String(userId) });
+                return res.status(409).json({
+                    error: 'No canonical profile',
+                    message: 'Cannot import cookies without an established canonical profile. Create a tab via POST /tabs first.',
+                });
+            }
+            const existingSessions = (0, session_1.getSessionsForUser)(userId);
+            if (existingSessions.length === 0) {
+                (0, logging_1.log)('warn', 'cookie import rejected: no active session', { userId: String(userId) });
+                return res.status(409).json({
+                    error: 'No active session',
+                    message: 'Cannot import cookies without an active session. Create a tab via POST /tabs first.',
+                });
+            }
+            session = existingSessions[0][1];
         }
         await session.context.addCookies(sanitized);
         const result = { ok: true, userId: String(userId), count: sanitized.length };
@@ -232,12 +271,53 @@ router.get('/presets', (_req, res) => {
 });
 // Create new tab
 router.post('/tabs', async (req, res) => {
+    let createUserId;
+    let isFirstCreator = false;
+    let stagedGeneration;
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
+        // Record activity at START to prevent idle cleanup race during tab creation
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         const { userId, sessionKey, listItemId, url, preset, locale, timezoneId, geolocation, viewport } = req.body;
+        const { proxy, proxyProfile, geoMode } = req.body;
         const resolvedSessionKey = sessionKey || listItemId;
         if (!userId || !resolvedSessionKey) {
             return res.status(400).json({ error: 'userId and sessionKey required' });
         }
+        createUserId = String(userId);
+        // Check for session profile conflict (proxy/geo drift)
+        if (proxy || proxyProfile || geoMode) {
+            const { resolveSessionProfileInput, getConfiguredServerProxy, loadProxyProfiles } = await Promise.resolve().then(() => __importStar(require('../utils/proxy-profiles')));
+            const { establishSessionProfile } = await Promise.resolve().then(() => __importStar(require('../services/session')));
+            const profileInput = {
+                preset,
+                locale,
+                timezoneId,
+                geolocation: geolocation,
+                viewport: viewport,
+                proxy: proxy,
+                proxyProfile,
+                geoMode,
+            };
+            const deps = {
+                serverProxy: getConfiguredServerProxy(CONFIG.proxy),
+                proxyProfiles: loadProxyProfiles(CONFIG.proxyProfilesFile),
+            };
+            try {
+                const resolvedProfileBase = resolveSessionProfileInput(profileInput, deps);
+                const resolvedProfile = { ...resolvedProfileBase, sessionKey: resolvedSessionKey };
+                establishSessionProfile(userId, resolvedSessionKey, resolvedProfile);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (message === 'Session profile conflict') {
+                    return res.status(409).json({ error: 'Session profile conflict' });
+                }
+                return res.status(400).json({ error: message });
+            }
+        }
         let contextOverrides = null;
         try {
             contextOverrides = (0, presets_1.resolveContextOptions)({ preset, locale, timezoneId, geolocation, viewport });
@@ -251,40 +331,125 @@ router.post('/tabs', async (req, res) => {
             if (validationError)
                 return res.status(400).json({ error: validationError });
         }
-        const sessionMapKey = (0, session_1.getSessionMapKey)(userId, contextOverrides);
-        const session = await (0, session_1.getSession)(userId, contextOverrides);
-        const totalTabs = (0, session_1.countTotalTabsForSessions)([[sessionMapKey, session]]);
-        if (totalTabs >= session_1.MAX_TABS_PER_SESSION) {
-            return res.status(429).json({ error: 'Maximum tabs per session reached' });
-        }
-        const group = (0, session_1.getTabGroup)(session, resolvedSessionKey);
-        const page = await session.context.newPage();
-        const tabId = node_crypto_1.default.randomUUID();
-        page.__camofox_tabId = tabId;
-        const tabState = (0, tab_1.createTabState)(page);
-        group.set(tabId, tabState);
-        (0, session_1.indexTab)(tabId, sessionMapKey);
-        (0, download_1.registerDownloadListener)(tabId, String(userId), page);
         if (url) {
-            const urlErr = (0, tab_1.validateUrl)(url);
+            const urlErr = await (0, tab_1.validateNavigationUrl)(url, {
+                allowPrivateNetworkTargets: CONFIG.allowPrivateNetworkTargets,
+            });
             if (urlErr)
                 return res.status(400).json({ error: urlErr });
-            await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
-            tabState.visitedUrls.add(url);
+        }
+        const requestedProfile = (0, session_1.createCanonicalProfile)(contextOverrides);
+        const requestHash = requestedProfile.hash;
+        const MAX_CANONICAL_RETRIES = 3;
+        for (let attempt = 0; attempt < MAX_CANONICAL_RETRIES; attempt++) {
+            const existingProfile = (0, session_1.getCanonicalProfile)(userId);
+            if (existingProfile) {
+                if (contextOverrides === null) {
+                    contextOverrides = existingProfile.resolvedOverrides;
+                }
+                else if (requestHash !== existingProfile.hash) {
+                    (0, logging_1.log)('warn', 'canonical profile conflict', { userId: String(userId) });
+                    return res.status(409).json({
+                        error: 'Context override conflict',
+                        message: 'A canonical profile already exists for this user with different overrides. Close the session first to reconfigure.',
+                    });
+                }
+                else {
+                    contextOverrides = existingProfile.resolvedOverrides;
+                }
+                break;
+            }
+            const mutex = (0, session_1.acquireFirstCreateMutex)(userId);
+            if (mutex.acquired) {
+                isFirstCreator = true;
+                break;
+            }
+            await mutex.wait;
+        }
+        if (!(0, session_1.getCanonicalProfile)(userId) && !isFirstCreator) {
+            (0, logging_1.log)('error', 'canonical profile acquisition failed after retries', { userId: String(userId) });
+            return res.status(503).json({ error: 'Could not acquire canonical profile, try again' });
+        }
+        const sessionMapKey = (0, session_1.getSessionMapKey)(userId, contextOverrides);
+        let tabId;
+        let pageUrl;
+        if (isFirstCreator) {
+            const staged = await (0, session_1.createStagedSession)(userId, contextOverrides);
+            stagedGeneration = staged.generation;
+            const { session, generation } = staged;
+            const page = await session.context.newPage();
+            tabId = node_crypto_1.default.randomUUID();
+            page.__camofox_tabId = tabId;
+            const tabState = await (0, tab_1.createTabState)(page);
+            (0, download_1.registerDownloadListener)(tabId, String(userId), page);
+            (0, download_1.markDownloadsStaged)(tabId);
+            if (url) {
+                await (0, tab_1.navigateWithSafetyGuard)(page, url, {
+                    allowPrivateNetworkTargets: CONFIG.allowPrivateNetworkTargets,
+                    waitUntil: 'domcontentloaded',
+                    timeout: 30000,
+                });
+                tabState.visitedUrls.add(url);
+            }
+            const committed = (0, session_1.commitStagedFirstUse)(userId, session, contextOverrides, {
+                tabId,
+                sessionMapKey,
+                sessionKey: resolvedSessionKey,
+                tabState,
+            }, generation);
+            if (!committed) {
+                await (0, session_1.rollbackStagedFirstUse)(createUserId ?? userId, generation).catch(() => { });
+                return res.status(409).json({ error: 'Session closed during creation' });
+            }
+            (0, download_1.commitStagedDownloads)(tabId);
+            pageUrl = page.url();
+        }
+        else {
+            const session = await (0, session_1.getSession)(userId, contextOverrides);
+            const totalTabs = (0, session_1.countTotalTabsForSessions)([[sessionMapKey, session]]);
+            if (totalTabs >= session_1.MAX_TABS_PER_SESSION) {
+                return res.status(429).json({ error: 'Maximum tabs per session reached' });
+            }
+            const group = (0, session_1.getTabGroup)(session, resolvedSessionKey);
+            const page = await session.context.newPage();
+            tabId = node_crypto_1.default.randomUUID();
+            page.__camofox_tabId = tabId;
+            const tabState = await (0, tab_1.createTabState)(page);
+            group.set(tabId, tabState);
+            (0, session_1.indexTab)(tabId, sessionMapKey);
+            (0, download_1.registerDownloadListener)(tabId, String(userId), page);
+            if (url) {
+                await (0, tab_1.navigateWithSafetyGuard)(page, url, {
+                    allowPrivateNetworkTargets: CONFIG.allowPrivateNetworkTargets,
+                    waitUntil: 'domcontentloaded',
+                    timeout: 30000,
+                });
+                tabState.visitedUrls.add(url);
+            }
+            pageUrl = page.url();
         }
         (0, logging_1.log)('info', 'tab created', {
             reqId: req.reqId,
             tabId,
             userId,
             sessionKey: resolvedSessionKey,
-            url: page.url(),
+            url: pageUrl,
         });
-        return res.json({ tabId, url: page.url() });
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
+        return res.json({ tabId, url: pageUrl });
     }
     catch (err) {
+        if (isFirstCreator && createUserId) {
+            if (stagedGeneration) {
+                await (0, session_1.rollbackStagedFirstUse)(createUserId, stagedGeneration).catch(() => { });
+            }
+            else {
+                (0, session_1.rollbackCanonicalMutex)(createUserId);
+            }
+        }
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'tab create failed', { reqId: req.reqId, error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // GET /tabs - List all tabs (OpenClaw expects this)
@@ -320,6 +485,9 @@ router.get('/tabs', async (req, res) => {
 router.post('/tabs/:tabId/navigate', async (req, res) => {
     const tabId = req.params.tabId;
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId, url, macro, query } = req.body;
         if (!userId)
             return res.status(400).json({ error: 'userId required' });
@@ -336,24 +504,30 @@ router.post('/tabs/:tabId/navigate', async (req, res) => {
             }
             if (!targetUrl)
                 return { status: 400, body: { error: 'url or macro required' } };
-            const urlErr = (0, tab_1.validateUrl)(targetUrl);
+            const urlErr = await (0, tab_1.validateNavigationUrl)(targetUrl, {
+                allowPrivateNetworkTargets: CONFIG.allowPrivateNetworkTargets,
+            });
             if (urlErr)
                 return { status: 400, body: { error: urlErr } };
-            await tabState.page.goto(targetUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
+            await (0, tab_1.navigateWithSafetyGuard)(tabState.page, targetUrl, {
+                allowPrivateNetworkTargets: CONFIG.allowPrivateNetworkTargets,
+                waitUntil: 'domcontentloaded',
+                timeout: 30000,
+            });
             tabState.visitedUrls.add(targetUrl);
             tabState.refs = await (0, tab_1.buildRefs)(tabState.page);
             return { status: 200, body: { ok: true, url: tabState.page.url() } };
         }), CONFIG.handlerTimeoutMs, 'navigate'));
         if (result.status !== 200)
             return res.status(result.status).json(result.body);
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         (0, logging_1.log)('info', 'navigated', { reqId: req.reqId, tabId, url: result.body.url });
         return res.json(result.body);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'navigate failed', { reqId: req.reqId, tabId, error: message });
-        const status = err instanceof Error && err.message?.startsWith('Blocked URL scheme') ? 400 : 500;
-        return res.status(status).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Snapshot
@@ -368,12 +542,15 @@ router.get('/tabs/:tabId/snapshot', async (req, res) => {
             return res.status(404).json({ error: 'Tab not found' });
         const { tabState } = found;
         tabState.toolCalls++;
-        const result = await (0, session_1.withUserLimit)(String(userId), CONFIG.maxConcurrentPerUser, () => (0, tab_1.withTimeout)((0, tab_1.snapshotTab)(tabState), CONFIG.handlerTimeoutMs, 'snapshot'));
+        const rawOffset = Number(req.query.offset);
+        const offset = Number.isFinite(rawOffset) && rawOffset > 0 ? Math.floor(rawOffset) : 0;
+        const raw = await (0, session_1.withUserLimit)(String(userId), CONFIG.maxConcurrentPerUser, () => (0, tab_1.withTimeout)((0, tab_1.snapshotTab)(tabState), CONFIG.handlerTimeoutMs, 'snapshot'));
+        const result = (0, tab_1.buildSnapshotPayload)(raw, offset);
         (0, logging_1.log)('info', 'snapshot', {
             reqId: req.reqId,
             tabId,
             url: result.url,
-            snapshotLen: result.snapshot?.length,
+            snapshotLen: result.snapshot.length,
             refsCount: result.refsCount,
         });
         return res.json(result);
@@ -381,30 +558,37 @@ router.get('/tabs/:tabId/snapshot', async (req, res) => {
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'snapshot failed', { reqId: req.reqId, tabId: req.params.tabId, error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Wait for page ready
 router.post('/tabs/:tabId/wait', async (req, res) => {
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId, timeout = 10000, waitForNetwork = true } = req.body;
         const found = (0, session_1.findTabById)(req.params.tabId, userId);
         if (!found)
             return res.status(404).json({ error: 'Tab not found' });
         const { tabState } = found;
         const ready = await (0, tab_1.waitForPageReady)(tabState.page, { timeout, waitForNetwork });
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json({ ok: true, ready });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'wait failed', { reqId: req.reqId, error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Click
 router.post('/tabs/:tabId/click', async (req, res) => {
     const tabId = req.params.tabId;
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId, ref, selector } = req.body;
         if (!userId)
             return res.status(400).json({ error: 'userId required' });
@@ -425,21 +609,22 @@ router.post('/tabs/:tabId/click', async (req, res) => {
             }));
         }
         (0, logging_1.log)('info', 'clicked', { reqId: req.reqId, tabId, url: result.url });
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json(responseObj);
     }
     catch (err) {
-        const statusCode = err?.statusCode;
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'click failed', { reqId: req.reqId, tabId, error: message });
-        if (statusCode === 400)
-            return res.status(400).json({ error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Type
 router.post('/tabs/:tabId/type', async (req, res) => {
     const tabId = req.params.tabId;
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId, ref, selector, text } = req.body;
         const found = (0, session_1.findTabById)(tabId, userId);
         if (!found)
@@ -448,21 +633,22 @@ router.post('/tabs/:tabId/type', async (req, res) => {
         tabState.toolCalls++;
         const textValue = String(text ?? '');
         const result = await (0, tab_1.withTimeout)((0, tab_1.typeTab)(tabId, tabState, { ref, selector, text: textValue }), (0, tab_1.calculateTypeTimeoutMs)(textValue), 'type');
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json(result);
     }
     catch (err) {
-        const statusCode = err?.statusCode;
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'type failed', { reqId: req.reqId, error: message });
-        if (statusCode === 400)
-            return res.status(400).json({ error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Press key
 router.post('/tabs/:tabId/press', async (req, res) => {
     const tabId = req.params.tabId;
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId, key } = req.body;
         const found = (0, session_1.findTabById)(tabId, userId);
         if (!found)
@@ -470,38 +656,44 @@ router.post('/tabs/:tabId/press', async (req, res) => {
         const { tabState } = found;
         tabState.toolCalls++;
         await (0, tab_1.withTimeout)((0, tab_1.pressTab)(tabId, tabState, String(key ?? '')), CONFIG.handlerTimeoutMs, 'press');
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json({ ok: true });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'press failed', { reqId: req.reqId, error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Scroll
 router.post('/tabs/:tabId/scroll', async (req, res) => {
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId, direction = 'down', amount = 500 } = req.body;
         const found = (0, session_1.findTabById)(req.params.tabId, userId);
         if (!found)
             return res.status(404).json({ error: 'Tab not found' });
         const { tabState } = found;
         tabState.toolCalls++;
-        const delta = direction === 'up' ? -amount : amount;
-        await tabState.page.mouse.wheel(0, delta);
-        await tabState.page.waitForTimeout(300);
-        return res.json({ ok: true });
+        const result = await (0, tab_1.withTimeout)((0, tab_1.scrollTab)(tabState, { direction, amount }), CONFIG.handlerTimeoutMs, 'scroll');
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
+        return res.json(result);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'scroll failed', { reqId: req.reqId, error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Scroll element (selector or ref)
 router.post('/tabs/:tabId/scroll-element', async (req, res) => {
     const tabId = req.params.tabId;
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId, selector, ref, deltaX, deltaY, scrollTo } = req.body;
         const found = (0, session_1.findTabById)(tabId, userId);
         if (!found)
@@ -509,15 +701,13 @@ router.post('/tabs/:tabId/scroll-element', async (req, res) => {
         const { tabState } = found;
         tabState.toolCalls++;
         const result = await (0, tab_1.scrollElementTab)(tabId, tabState, { selector, ref, deltaX, deltaY, scrollTo });
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json(result);
     }
     catch (err) {
-        const statusCode = err?.statusCode;
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'scroll-element failed', { reqId: req.reqId, tabId, error: message });
-        if (statusCode === 400)
-            return res.status(400).json({ error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Evaluate JS (API key optional)
@@ -540,12 +730,13 @@ router.post('/tabs/:tabId/evaluate', express_1.default.json({ limit: '64kb' }),
         const { tabState } = found;
         tabState.toolCalls++;
         const result = await (0, tab_1.evaluateTab)(tabId, tabState, { expression, timeout });
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json(result);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'evaluate failed', { reqId: req.reqId, tabId, error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Evaluate JS extended (API key optional)
@@ -586,6 +777,7 @@ router.post('/tabs/:tabId/evaluate-extended', express_1.default.json({ limit: '6
         const outerTimeout = effectiveTimeout + 10000;
         const result = await (0, session_1.withUserLimit)(String(userId), CONFIG.maxConcurrentPerUser, async () => (0, tab_1.withTimeout)((0, tab_1.evaluateTabExtended)(tabId, tabState, { expression, timeout: effectiveTimeout }), outerTimeout, `Evaluate-extended timed out after ${outerTimeout}ms`));
         if (result.ok) {
+            lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
             return res.json(result);
         }
         if (result.errorType === 'timeout') {
@@ -596,6 +788,10 @@ router.post('/tabs/:tabId/evaluate-extended', express_1.default.json({ limit: '6
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'evaluate-extended failed', { reqId: req.reqId, tabId, error: message });
+        const status = getRouteErrorStatus(err);
+        if (status === 400) {
+            return res.status(400).json({ ok: false, error: (0, errors_1.safeError)(err), errorType: 'js_error' });
+        }
         if (message.includes('timed out') || message.includes('Timeout')) {
             return res.status(408).json({ ok: false, error: message, errorType: 'timeout' });
         }
@@ -611,6 +807,9 @@ router.post('/tabs/:tabId/evaluate-extended', express_1.default.json({ limit: '6
 router.post('/tabs/:tabId/back', async (req, res) => {
     const tabId = req.params.tabId;
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId } = req.body;
         const found = (0, session_1.findTabById)(tabId, userId);
         if (!found)
@@ -618,18 +817,22 @@ router.post('/tabs/:tabId/back', async (req, res) => {
         const { tabState } = found;
         tabState.toolCalls++;
         const result = await (0, tab_1.withTimeout)((0, tab_1.backTab)(tabId, tabState), CONFIG.handlerTimeoutMs, 'back');
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json(result);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'back failed', { reqId: req.reqId, error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Forward
 router.post('/tabs/:tabId/forward', async (req, res) => {
     const tabId = req.params.tabId;
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId } = req.body;
         const found = (0, session_1.findTabById)(tabId, userId);
         if (!found)
@@ -637,18 +840,22 @@ router.post('/tabs/:tabId/forward', async (req, res) => {
         const { tabState } = found;
         tabState.toolCalls++;
         const result = await (0, tab_1.withTimeout)((0, tab_1.forwardTab)(tabId, tabState), CONFIG.handlerTimeoutMs, 'forward');
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json(result);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'forward failed', { reqId: req.reqId, error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Refresh
 router.post('/tabs/:tabId/refresh', async (req, res) => {
     const tabId = req.params.tabId;
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId } = req.body;
         const found = (0, session_1.findTabById)(tabId, userId);
         if (!found)
@@ -656,12 +863,13 @@ router.post('/tabs/:tabId/refresh', async (req, res) => {
         const { tabState } = found;
         tabState.toolCalls++;
         const result = await (0, tab_1.withTimeout)((0, tab_1.refreshTab)(tabId, tabState), CONFIG.handlerTimeoutMs, 'refresh');
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json(result);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         (0, logging_1.log)('error', 'refresh failed', { reqId: req.reqId, error: message });
-        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+        return res.status(getRouteErrorStatus(err)).json({ error: (0, errors_1.safeError)(err) });
     }
 });
 // Get links
@@ -708,6 +916,54 @@ router.get('/tabs/:tabId/screenshot', async (req, res) => {
         return res.status(500).json({ error: (0, errors_1.safeError)(err) });
     }
 });
+// Images
+router.get('/tabs/:tabId/images', async (req, res) => {
+    try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ ok: false, error: 'Forbidden' });
+        }
+        const userId = req.query.userId;
+        const found = (0, session_1.findTabById)(req.params.tabId, userId);
+        if (!found) {
+            (0, logging_1.log)('warn', 'images: tab not found', { reqId: req.reqId, tabId: req.params.tabId, userId });
+            return res.status(404).json({ error: 'Tab not found' });
+        }
+        const selector = typeof req.query.selector === 'string' && req.query.selector ? req.query.selector : undefined;
+        const extensions = Array.isArray(req.query.extensions)
+            ? req.query.extensions.map((value) => String(value)).filter(Boolean)
+            : typeof req.query.extensions === 'string' && req.query.extensions
+                ? req.query.extensions
+                    .split(',')
+                    .map((value) => value.trim())
+                    .filter(Boolean)
+                : undefined;
+        const resolveBlobs = String(req.query.resolveBlobs || '').toLowerCase() === 'true';
+        const triggerLazyLoad = String(req.query.triggerLazyLoad || '').toLowerCase() === 'true';
+        const { tabState } = found;
+        tabState.toolCalls++;
+        const result = await (0, session_1.withUserLimit)(String(userId), CONFIG.maxConcurrentPerUser, () => (0, tab_1.withTimeout)((0, tab_1.withTabLock)(req.params.tabId, async () => (0, resource_extractor_1.extractImages)(tabState.page, {
+            selector,
+            extensions,
+            resolveBlobs,
+            triggerLazyLoad,
+        })), CONFIG.handlerTimeoutMs, 'images'));
+        return res.json({
+            ok: result.ok,
+            container: result.container,
+            images: result.resources.images,
+            totals: {
+                images: result.totals.images,
+                total: result.totals.images,
+            },
+            metadata: result.metadata,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        (0, logging_1.log)('error', 'images failed', { reqId: req.reqId, error: message });
+        return res.status(500).json({ error: (0, errors_1.safeError)(err) });
+    }
+});
 // Stats
 router.get('/tabs/:tabId/stats', async (req, res) => {
     try {
@@ -735,6 +991,9 @@ router.get('/tabs/:tabId/stats', async (req, res) => {
 // Close tab
 router.delete('/tabs/:tabId', async (req, res) => {
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId } = req.body;
         const found = (0, session_1.findTabById)(req.params.tabId, userId);
         if (found) {
@@ -746,6 +1005,7 @@ router.delete('/tabs/:tabId', async (req, res) => {
             }
             (0, logging_1.log)('info', 'tab closed', { reqId: req.reqId, tabId: req.params.tabId, userId });
         }
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json({ ok: true });
     }
     catch (err) {
@@ -757,6 +1017,9 @@ router.delete('/tabs/:tabId', async (req, res) => {
 // Close tab group
 router.delete('/tabs/group/:listItemId', async (req, res) => {
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { userId } = req.body;
         const sessionsForUser = (0, session_1.getSessionsForUser)(userId);
         for (const [sessionKey, session] of sessionsForUser) {
@@ -775,6 +1038,7 @@ router.delete('/tabs/group/:listItemId', async (req, res) => {
                 sessionKey,
             });
         }
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json({ ok: true });
     }
     catch (err) {
@@ -786,10 +1050,14 @@ router.delete('/tabs/group/:listItemId', async (req, res) => {
 // Close session
 router.delete('/sessions/:userId', async (req, res) => {
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const userId = (0, session_1.normalizeUserId)(req.params.userId);
         await (0, session_1.closeSessionsForUser)(userId);
         // Ensure downloads are cleaned even if the session was already partially removed.
         (0, download_1.cleanupUserDownloads)(userId);
+        lifecycle_controller_1.lifecycleController.recordInteractiveActivity();
         return res.json({ ok: true });
     }
     catch (err) {
@@ -801,6 +1069,9 @@ router.delete('/sessions/:userId', async (req, res) => {
 // Toggle display mode (headless/headed/virtual) for a user session
 router.post('/sessions/:userId/toggle-display', async (req, res) => {
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const userId = (0, session_1.normalizeUserId)(req.params.userId);
         const { headless } = req.body ?? {};
         if (typeof headless !== 'boolean' && headless !== 'virtual') {
@@ -952,6 +1223,9 @@ router.get('/downloads/:downloadId/content', async (req, res) => {
 // Downloads: delete
 router.delete('/downloads/:downloadId', async (req, res) => {
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const userId = req.body?.userId || req.query.userId;
         if (!userId)
             return res.status(400).json({ ok: false, error: 'userId required' });
@@ -969,6 +1243,9 @@ router.delete('/downloads/:downloadId', async (req, res) => {
 // Extract resources from a scoped container
 router.post('/tabs/:tabId/extract-resources', async (req, res) => {
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { tabId } = req.params;
         const { userId, selector, types, extensions, resolveBlobs, triggerLazyLoad } = req.body;
         if (!userId)
@@ -994,9 +1271,50 @@ router.post('/tabs/:tabId/extract-resources', async (req, res) => {
         res.status(500).json({ ok: false, error: (0, errors_1.safeError)(err) });
     }
 });
+router.post('/tabs/:tabId/extract-structured', async (req, res) => {
+    try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
+        const { tabId } = req.params;
+        const { userId, schema } = req.body;
+        if (!userId || typeof userId !== 'string') {
+            return res.status(400).json({ ok: false, error: 'userId required' });
+        }
+        if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+            return res.status(400).json({ ok: false, error: 'schema must be an object' });
+        }
+        const found = (0, session_1.findTabById)(tabId, userId);
+        if (!found)
+            return res.status(404).json({ ok: false, error: 'Tab not found' });
+        const { tabState } = found;
+        tabState.toolCalls++;
+        const result = await (0, session_1.withUserLimit)(String(userId), CONFIG.maxConcurrentPerUser, () => (0, tab_1.withTimeout)((0, tab_1.withTabLock)(tabId, async () => (0, structured_extractor_1.extractStructuredData)(tabState.page, schema)), CONFIG.handlerTimeoutMs, 'extract-structured'));
+        return res.json(result);
+    }
+    catch (err) {
+        if (err instanceof structured_extractor_1.StructuredExtractSchemaError) {
+            return res.status(err.statusCode).json({ ok: false, error: err.message });
+        }
+        if (err instanceof structured_extractor_1.StructuredExtractRuntimeError) {
+            return res.status(err.statusCode).json({
+                ok: false,
+                error: 'Structured extraction failed',
+                fieldPath: err.fieldPath,
+                reason: err.reason,
+            });
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        (0, logging_1.log)('error', 'structured extract failed', { error: message });
+        return res.status(500).json({ ok: false, error: (0, errors_1.safeError)(err) });
+    }
+});
 // Batch download from a scoped container
 router.post('/tabs/:tabId/batch-download', async (req, res) => {
     try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
         const { tabId } = req.params;
         const body = req.body;
         const userId = body?.userId;
@@ -1093,12 +1411,13 @@ router.post('/tabs/:tabId/trace/stop', async (req, res) => {
             return res.json({
                 ok: true,
                 path: result.path,
+                filename: result.path ? (0, node_path_1.basename)(result.path) : undefined,
                 size: result.size,
                 alreadyStopped: true,
                 message: 'Trace was already stopped by chunk stop',
             });
         }
-        return res.json({ ok: true, ...result });
+        return res.json({ ok: true, ...result, filename: (0, node_path_1.basename)(result.path) });
     }
     catch (err) {
         const status = getTracingErrorStatus(err);
@@ -1143,7 +1462,7 @@ router.post('/tabs/:tabId/trace/chunk/stop', async (req, res) => {
         if (!tab)
             return res.status(404).json({ ok: false, error: 'Tab not found' });
         const result = await (0, tracing_1.stopTracingChunk)(userId, tab.page.context(), path);
-        return res.json({ ok: true, ...result });
+        return res.json({ ok: true, ...result, filename: (0, node_path_1.basename)(result.path) });
     }
     catch (err) {
         const status = getTracingErrorStatus(err);
@@ -1170,6 +1489,62 @@ router.get('/tabs/:tabId/trace/status', async (req, res) => {
         return res.status(500).json({ ok: false, error: (0, errors_1.safeError)(err) });
     }
 });
+router.get('/sessions/:userId/traces', async (req, res) => {
+    try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
+        const userId = (0, session_1.normalizeUserId)(req.params.userId);
+        return res.json({ ok: true, traces: (0, tracing_1.listTraceArtifacts)(userId) });
+    }
+    catch (err) {
+        return res.status(500).json({ ok: false, error: (0, errors_1.safeError)(err) });
+    }
+});
+router.get('/sessions/:userId/traces/:filename', async (req, res) => {
+    try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
+        const userId = (0, session_1.normalizeUserId)(req.params.userId);
+        const filename = req.params.filename;
+        const filePath = (0, tracing_1.resolveTraceArtifactPath)(userId, filename);
+        const safeName = filename.replace(/[\r\n\0"]/g, '');
+        res.setHeader('Content-Type', 'application/zip');
+        res.setHeader('Content-Disposition', `attachment; filename="${safeName}"; filename*=UTF-8''${encodeURIComponent(safeName)}`);
+        const stream = node_fs_1.default.createReadStream(filePath);
+        stream.on('error', (streamErr) => {
+            if (!res.headersSent) {
+                const status = getTraceArtifactErrorStatus(streamErr);
+                res.removeHeader('Content-Disposition');
+                res.removeHeader('Content-Type');
+                res.status(status).json({ ok: false, error: (0, errors_1.safeError)(streamErr) });
+                return;
+            }
+            res.destroy();
+        });
+        stream.pipe(res);
+    }
+    catch (err) {
+        const status = getTraceArtifactErrorStatus(err);
+        return res.status(status).json({ ok: false, error: (0, errors_1.safeError)(err) });
+    }
+});
+router.delete('/sessions/:userId/traces/:filename', async (req, res) => {
+    try {
+        if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {
+            return res.status(403).json({ error: 'Forbidden' });
+        }
+        const userId = (0, session_1.normalizeUserId)(req.params.userId);
+        const filename = req.params.filename;
+        (0, tracing_1.deleteTraceArtifact)(userId, filename);
+        return res.json({ ok: true });
+    }
+    catch (err) {
+        const status = getTraceArtifactErrorStatus(err);
+        return res.status(status).json({ ok: false, error: (0, errors_1.safeError)(err) });
+    }
+});
 router.get('/tabs/:tabId/console', async (req, res) => {
     try {
         if (CONFIG.apiKey && !(0, auth_1.isAuthorizedWithApiKey)(req, CONFIG.apiKey)) {