agentmb 0.1.1 → 0.3.2

package/dist/daemon/routes/actions.js

@@ -38,10 +38,48 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerActionRoutes = registerActionRoutes;
 const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const url_1 = require("url");
 require("../types"); // T11: Fastify type augmentation
 const Actions = __importStar(require("../../browser/actions"));
 const actions_1 = require("../../browser/actions");
 const engine_1 = require("../../policy/engine");
+// ---------------------------------------------------------------------------
+// R09-C04-T12: Sensitive domain detection
+// ---------------------------------------------------------------------------
+const SENSITIVE_DOMAIN_PATTERNS = [
+    { re: /bank|banking|finance|financial|payment|paypal|stripe/i, category: 'financial' },
+    { re: /medical|health|hospital|clinic|pharma/i, category: 'medical' },
+    { re: /gambling|casino|betting|poker/i, category: 'gambling' },
+    { re: /adult|porn|nsfw|xxx/i, category: 'adult' },
+    { re: /crypto|bitcoin|wallet|exchange/i, category: 'crypto' },
+];
+// Append extra patterns from env (comma-separated regexes)
+const _envPatterns = process.env.AGENTMB_SENSITIVE_DOMAINS;
+if (_envPatterns) {
+    for (const p of _envPatterns.split(',').map(s => s.trim()).filter(Boolean)) {
+        try {
+            SENSITIVE_DOMAIN_PATTERNS.push({ re: new RegExp(p, 'i'), category: 'custom' });
+        }
+        catch { /* ignore invalid regex */ }
+    }
+}
+function detectSensitiveDomain(url) {
+    let domain = '';
+    try {
+        domain = new URL(url).hostname;
+    }
+    catch {
+        return { sensitive: false };
+    }
+    for (const { re, category } of SENSITIVE_DOMAIN_PATTERNS) {
+        if (re.test(domain))
+            return { sensitive: true, category, domain };
+    }
+    return { sensitive: false };
+}
 /** Structured error when a frame selector matches no frame in the page. */
 class FrameResolutionError extends Error {
     selector;
@@ -146,6 +184,59 @@ async function applyPolicy(server, sessionId, domain, action, opts, reply) {
     }
     return true;
 }
+function pfRange(field, value, min, max) {
+    if (value === undefined)
+        return null;
+    return value < min || value > max ? { field, constraint: `must be ${min}–${max}`, value } : null;
+}
+function pfMaxLen(field, value, max) {
+    if (!value)
+        return null;
+    return value.length > max ? { field, constraint: `max length ${max} chars`, value: value.length } : null;
+}
+/** Run an ordered list of checks; sends 400 + returns false on first violation. */
+function preflight(checks, reply) {
+    const v = checks.find(Boolean);
+    if (v) {
+        reply.code(400).send({ error: 'preflight_failed', field: v.field, constraint: v.constraint, value: v.value });
+        return false;
+    }
+    return true;
+}
+async function applyStabilityPre(page, opts) {
+    if (!opts)
+        return;
+    if (opts.wait_before_ms)
+        await new Promise(r => setTimeout(r, opts.wait_before_ms));
+    if (opts.wait_dom_stable_ms) {
+        try {
+            await page.waitForFunction('document.readyState === "complete"', undefined, { timeout: opts.wait_dom_stable_ms });
+        }
+        catch { /* timeout is acceptable */ }
+    }
+}
+async function applyStabilityPost(page, opts) {
+    if (!opts)
+        return;
+    if (opts.wait_after_ms)
+        await new Promise(r => setTimeout(r, opts.wait_after_ms));
+}
+// ---------------------------------------------------------------------------
+// R08-R13: Error recovery hints — enrich 422 ActionDiagnostics with hint
+// ---------------------------------------------------------------------------
+function enrichDiag(diag) {
+    const msg = diag.error.toLowerCase();
+    let recovery_hint;
+    if (msg.includes('timeout') || msg.includes('waiting for'))
+        recovery_hint = 'Increase timeout_ms or add stability.wait_before_ms; ensure element is visible before acting';
+    else if (msg.includes('target closed') || msg.includes('execution context') || msg.includes('detached'))
+        recovery_hint = 'Page may have navigated or element was removed; re-navigate or re-snapshot';
+    else if (msg.includes('not found') || msg.includes('no element') || msg.includes('failed to find'))
+        recovery_hint = 'Check selector; use snapshot_map to verify element exists on current page';
+    else if (msg.includes('intercept') || msg.includes('overlap') || msg.includes('obscur'))
+        recovery_hint = 'Element may be covered by overlay; try executor=auto_fallback or scroll into view first';
+    return recovery_hint ? { ...diag, recovery_hint } : diag;
+}
 function registerActionRoutes(server, registry) {
     function getLogger() {
         return server.auditLogger;
@@ -172,7 +263,11 @@ function registerActionRoutes(server, registry) {
             const eid = input.ref_id.slice(colonIdx + 1);
             const snapshot = bm.getSnapshot(sessionId, snapshotId);
             if (!snapshot) {
-                reply.code(409).send({ error: 'stale_ref', ref_id: input.ref_id, message: 'Snapshot not found or expired; call snapshot_map again' });
+                reply.code(409).send({
+                    error: 'stale_ref', ref_id: input.ref_id,
+                    message: 'Snapshot not found or expired; call snapshot_map again',
+                    suggestions: ['call snapshot_map to get fresh ref_ids', 'use selector or element_id as fallback'],
+                });
                 return null;
             }
             const currentRev = bm.getPageRev(sessionId);
@@ -183,6 +278,7 @@ function registerActionRoutes(server, registry) {
                     snapshot_page_rev: snapshot.page_rev,
                     current_page_rev: currentRev,
                     message: 'Page has changed since snapshot was taken; call snapshot_map again',
+                    suggestions: ['call snapshot_map to get fresh ref_ids', 'if page is stable, the navigation event incremented page_rev — wait and resnapshot'],
                 });
                 return null;
             }
@@ -213,24 +309,78 @@ function registerActionRoutes(server, registry) {
         }
         return result;
     }
+    /** Resolve a live session with optional page_id override (R09-C03 multi-page targeting). */
+    function resolveWithPage(id, pageId, reply) {
+        const s = resolve(id, reply);
+        if (!s)
+            return null;
+        if (!pageId)
+            return s;
+        const bm = server.browserManager;
+        const page = bm?.getPageById(id, pageId);
+        if (!page) {
+            reply.code(404).send({ error: `Page ${pageId} not found in session ${id}. Use GET /api/v1/sessions/${id}/pages to list available pages.` });
+            return null;
+        }
+        return { ...s, page };
+    }
     // POST /api/v1/sessions/:id/navigate
     server.post('/api/v1/sessions/:id/navigate', async (req, reply) => {
-        const s = resolve(req.params.id, reply);
+        const s = resolveWithPage(req.params.id, req.body?.page_id, reply);
         if (!s)
             return;
-        const { url, wait_until = 'load', purpose, operator, sensitive, retry } = req.body;
+        const { url, wait_until = 'load', timeout_ms = 30_000, purpose, operator, sensitive, retry } = req.body;
+        // R09-C07-P0: validate timeout_ms to prevent abuse (0 disables, max 60 s)
+        if (!preflight([pfRange('timeout_ms', timeout_ms, 0, 60_000)], reply))
+            return;
+        // R09-C06-P1: file:// URL guard — require allow_dirs whitelist
+        // R09-C07-P0: use fs.realpath to resolve symlinks before whitelist check (symlink traversal fix)
+        if (url.startsWith('file://')) {
+            const bm = server.browserManager;
+            const allowDirs = bm?.getAllowDirs(req.params.id) ?? [];
+            if (allowDirs.length === 0) {
+                return reply.code(403).send({ error: 'file:// navigation requires allow_dirs on the session. Set allow_dirs when creating session.' });
+            }
+            let filePath;
+            try {
+                filePath = (0, url_1.fileURLToPath)(url);
+            }
+            catch {
+                return reply.code(400).send({ error: 'Invalid file:// URL format' });
+            }
+            let abs;
+            try {
+                abs = await fs_1.default.promises.realpath(filePath);
+            }
+            catch {
+                return reply.code(404).send({ error: `file:// path does not exist: ${filePath}` });
+            }
+            const allowed = allowDirs.some(d => abs === d || abs.startsWith(d + path_1.default.sep));
+            if (!allowed) {
+                return reply.code(403).send({ error: `file:// path ${abs} is not within allowed directories.` });
+            }
+        }
         const domain = (0, engine_1.extractDomain)(url);
         if (!await applyPolicy(server, req.params.id, domain, 'navigate', { sensitive, retry }, reply))
             return;
-        return Actions.navigate(s.page, url, wait_until, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+        const navResult = await Actions.navigate(s.page, url, wait_until, getLogger(), s.id, purpose, inferOperator(req, s, operator), timeout_ms);
+        const sensitiveInfo = detectSensitiveDomain(url);
+        const sensitive_warning = sensitiveInfo.sensitive
+            ? { domain: sensitiveInfo.domain, category: sensitiveInfo.category, message: `Navigating to potentially sensitive domain: ${sensitiveInfo.domain}` }
+            : undefined;
+        return { ...navResult, ...(sensitive_warning ? { sensitive_warning } : {}) };
     });
     // POST /api/v1/sessions/:id/click
-    // T21: add fallback_x / fallback_y — if DOM click fails, retry via page.mouse.click()
+    // R08-R06: executor='auto_fallback' automatically retries via bbox coords on DOM failure
+    // R08-R02: stability.wait_before_ms / wait_after_ms / wait_dom_stable_ms
+    // R08-R09: preflight validates timeout_ms range
     server.post('/api/v1/sessions/:id/click', async (req, reply) => {
-        const s = resolve(req.params.id, reply);
+        const s = resolveWithPage(req.params.id, req.body?.page_id, reply);
         if (!s)
             return;
-        const { timeout_ms = 5000, frame, purpose, operator, sensitive, retry, fallback_x, fallback_y } = req.body;
+        const { timeout_ms = 5000, frame, purpose, operator, sensitive, retry, fallback_x, fallback_y, executor = 'strict', stability } = req.body;
+        if (!preflight([pfRange('timeout_ms', timeout_ms, 50, 60000)], reply))
+            return;
         const selector = resolveTarget(req.body, reply, s.id);
         if (!selector)
             return;
@@ -239,32 +389,63 @@ function registerActionRoutes(server, registry) {
         const target = resolveOrReply(s.page, frame, reply);
         if (!target)
             return;
+        await applyStabilityPre(s.page, stability);
         try {
-            return await Actions.click(target, selector, timeout_ms, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+            const result = await Actions.click(target, selector, timeout_ms, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+            await applyStabilityPost(s.page, stability);
+            return { ...result, executed_via: 'high_level' };
         }
         catch (domErr) {
-            // T21 dual-track: if fallback coordinates provided, retry via mouse.click()
-            if (fallback_x !== undefined && fallback_y !== undefined && s.page) {
+            // auto_fallback: resolve element bbox and retry via mouse.click()
+            if (executor === 'auto_fallback') {
                 try {
-                    await s.page.mouse.click(fallback_x, fallback_y);
-                    const duration_ms = 0;
-                    return { status: 'ok', selector, track: 'coords', fallback_x, fallback_y, duration_ms };
+                    const bbox = await target.locator(selector).boundingBox();
+                    if (bbox) {
+                        let cx = Math.round(bbox.x + bbox.width / 2);
+                        let cy = Math.round(bbox.y + bbox.height / 2);
+                        // Frame offset compensation: when target is a Frame (not the Page),
+                        // boundingBox() coords are relative to the frame viewport; add the
+                        // frame element's page-level offset so mouse.click lands correctly.
+                        if (frame && target !== s.page) {
+                            try {
+                                const frameRect = await target.evaluate('(() => { const el = window.frameElement; if (!el) return {x:0,y:0}; const r = el.getBoundingClientRect(); return {x: r.x, y: r.y}; })()');
+                                cx += Math.round(frameRect.x);
+                                cy += Math.round(frameRect.y);
+                            }
+                            catch { /* best-effort; proceed with uncompensated coords */ }
+                        }
+                        await s.page.mouse.click(cx, cy);
+                        await applyStabilityPost(s.page, stability);
+                        return { status: 'ok', selector, executed_via: 'low_level', fallback_x: cx, fallback_y: cy, duration_ms: 0 };
+                    }
                 }
-                catch (coordErr) {
-                    // Both tracks failed — report original DOM error
+                catch { /* fallback also failed — fall through to original error */ }
+            }
+            // explicit fallback coordinates (legacy T21 path)
+            if (fallback_x !== undefined && fallback_y !== undefined) {
+                try {
+                    await s.page.mouse.click(fallback_x, fallback_y);
+                    return { status: 'ok', selector, executed_via: 'low_level', track: 'coords', fallback_x, fallback_y, duration_ms: 0 };
                 }
+                catch { /* both tracks failed */ }
+            }
+            if (domErr instanceof Actions.ActionDiagnosticsError) {
+                const diag = enrichDiag({ ...domErr.diagnostics, suggested_fallback: 'retry with executor="auto_fallback" to attempt coordinates-based click' });
+                return reply.code(422).send(diag);
             }
-            if (domErr instanceof Actions.ActionDiagnosticsError)
-                return reply.code(422).send(domErr.diagnostics);
             throw domErr;
         }
     });
     // POST /api/v1/sessions/:id/fill
+    // R08-R01: fill_strategy='type' uses pressSequentially with char_delay_ms (humanization)
+    // R08-R02: stability options; R08-R09: preflight value length
     server.post('/api/v1/sessions/:id/fill', async (req, reply) => {
-        const s = resolve(req.params.id, reply);
+        const s = resolveWithPage(req.params.id, req.body?.page_id, reply);
         if (!s)
             return;
-        const { value, frame, purpose, operator, sensitive, retry } = req.body;
+        const { value, frame, purpose, operator, sensitive, retry, stability, fill_strategy = 'instant', char_delay_ms = 0 } = req.body;
+        if (!preflight([pfMaxLen('value', value, 100_000)], reply))
+            return;
         const selector = resolveTarget(req.body, reply, s.id);
         if (!selector)
             return;
@@ -273,11 +454,16 @@ function registerActionRoutes(server, registry) {
         const target = resolveOrReply(s.page, frame, reply);
         if (!target)
             return;
-        return Actions.fill(target, selector, value, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+        await applyStabilityPre(s.page, stability);
+        const result = fill_strategy === 'type'
+            ? await Actions.typeText(target, selector, value, char_delay_ms, getLogger(), s.id, purpose, inferOperator(req, s, operator))
+            : await Actions.fill(target, selector, value, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+        await applyStabilityPost(s.page, stability);
+        return result;
     });
     // POST /api/v1/sessions/:id/eval
     server.post('/api/v1/sessions/:id/eval', async (req, reply) => {
-        const s = resolve(req.params.id, reply);
+        const s = resolveWithPage(req.params.id, req.body?.page_id, reply);
         if (!s)
             return;
         const { expression, frame, purpose, operator, sensitive, retry } = req.body;
@@ -291,7 +477,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -311,13 +497,13 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
     // POST /api/v1/sessions/:id/screenshot
     server.post('/api/v1/sessions/:id/screenshot', async (req, reply) => {
-        const s = resolve(req.params.id, reply);
+        const s = resolveWithPage(req.params.id, req.body?.page_id, reply);
         if (!s)
             return;
         const { format = 'png', full_page = false, purpose, operator } = req.body ?? {};
@@ -326,13 +512,13 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
     // POST /api/v1/sessions/:id/type
     server.post('/api/v1/sessions/:id/type', async (req, reply) => {
-        const s = resolve(req.params.id, reply);
+        const s = resolveWithPage(req.params.id, req.body?.page_id, reply);
         if (!s)
             return;
         const { text, delay_ms = 0, frame, purpose, operator, sensitive, retry } = req.body;
@@ -350,13 +536,13 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
     // POST /api/v1/sessions/:id/press
     server.post('/api/v1/sessions/:id/press', async (req, reply) => {
-        const s = resolve(req.params.id, reply);
+        const s = resolveWithPage(req.params.id, req.body?.page_id, reply);
         if (!s)
             return;
         const { key, frame, purpose, operator, sensitive, retry } = req.body;
@@ -373,7 +559,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -391,7 +577,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -412,7 +598,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -430,7 +616,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -445,7 +631,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -461,7 +647,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -481,22 +667,35 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
     // POST /api/v1/sessions/:id/download
+    // T07: guard on accept_downloads; T08: element_id / ref_id support
     server.post('/api/v1/sessions/:id/download', async (req, reply) => {
         const s = resolve(req.params.id, reply);
         if (!s)
             return;
-        const { selector, timeout_ms = 30000, max_bytes = 50 * 1024 * 1024, purpose, operator } = req.body;
+        // T07: check accept_downloads is enabled
+        const bm = server.browserManager;
+        if (bm && !bm.getAcceptDownloads(s.id)) {
+            return reply.code(422).send({
+                error: 'download_not_enabled',
+                message: 'Downloads are disabled for this session. Create the session with accept_downloads=true (CLI: agentmb session new --accept-downloads).',
+            });
+        }
+        const { timeout_ms = 30000, max_bytes = 50 * 1024 * 1024, purpose, operator } = req.body;
+        // T08: resolve selector/element_id/ref_id to CSS selector
+        const selector = resolveTarget(req.body, reply, s.id);
+        if (!selector)
+            return;
         try {
             return await Actions.downloadFile(s.page, selector, timeout_ms, max_bytes, getLogger(), s.id, purpose, inferOperator(req, s, operator));
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -513,16 +712,16 @@ function registerActionRoutes(server, registry) {
     // R07-T01: element_map — scan page, assign stable element IDs
     // ---------------------------------------------------------------------------
     server.post('/api/v1/sessions/:id/element_map', async (req, reply) => {
-        const s = resolve(req.params.id, reply);
+        const s = resolveWithPage(req.params.id, req.body?.page_id, reply);
         if (!s)
             return;
-        const { scope, limit = 500, purpose, operator } = req.body ?? {};
+        const { scope, limit = 500, include_unlabeled = false, purpose, operator } = req.body ?? {};
         try {
-            return await Actions.elementMap(s.page, { scope, limit }, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+            return await Actions.elementMap(s.page, { scope, limit, include_unlabeled }, getLogger(), s.id, purpose, inferOperator(req, s, operator));
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -547,7 +746,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -572,7 +771,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -589,7 +788,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -611,7 +810,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -630,7 +829,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -649,7 +848,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -668,12 +867,12 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
     server.post('/api/v1/sessions/:id/scroll', async (req, reply) => {
-        const s = resolve(req.params.id, reply);
+        const s = resolveWithPage(req.params.id, req.body?.page_id, reply);
         if (!s)
             return;
         const selector = resolveTarget(req.body, reply, s.id);
@@ -688,7 +887,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -707,7 +906,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -715,31 +914,48 @@ function registerActionRoutes(server, registry) {
         const s = resolve(req.params.id, reply);
         if (!s)
             return;
-        const { source, source_element_id, target, target_element_id, purpose, operator } = req.body;
-        const src = source_element_id ? `[data-agentmb-eid="${source_element_id}"]` : source;
-        const tgt = target_element_id ? `[data-agentmb-eid="${target_element_id}"]` : target;
-        if (!src || !tgt)
-            return reply.code(400).send({ error: 'source and target are required (selector or element_id)' });
+        const { source, source_element_id, source_ref_id, target, target_element_id, target_ref_id, purpose, operator } = req.body;
+        const src = resolveTarget({ selector: source, element_id: source_element_id, ref_id: source_ref_id }, reply, s.id);
+        if (!src)
+            return;
+        const tgt = resolveTarget({ selector: target, element_id: target_element_id, ref_id: target_ref_id }, reply, s.id);
+        if (!tgt)
+            return;
         try {
             return await Actions.drag(s.page, src, tgt, getLogger(), s.id, purpose, inferOperator(req, s, operator));
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
+    // R08-R05/R08: Ref->Box->Input — mouse_move accepts ref_id + steps for smooth trajectory
     server.post('/api/v1/sessions/:id/mouse_move', async (req, reply) => {
         const s = resolve(req.params.id, reply);
         if (!s)
             return;
-        const { x, y, purpose, operator } = req.body;
+        const { purpose, operator, steps } = req.body;
+        let { x, y } = req.body;
+        // Ref->Box->Input: if ref_id/element_id/selector provided, resolve to bbox center coords
+        if (req.body.ref_id || req.body.element_id || req.body.selector) {
+            const cssSelector = resolveTarget(req.body, reply, s.id);
+            if (!cssSelector)
+                return;
+            const bbox = await s.page.locator(cssSelector).boundingBox();
+            if (!bbox)
+                return reply.code(404).send({ error: 'Element not found or not visible for mouse_move', selector: cssSelector });
+            x = Math.round(bbox.x + bbox.width / 2);
+            y = Math.round(bbox.y + bbox.height / 2);
+        }
+        if (x === undefined || y === undefined)
+            return reply.code(400).send({ error: 'Either x+y coordinates or ref_id/element_id/selector is required' });
         try {
-            return await Actions.mouseMove(s.page, x, y, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+            return await Actions.mouseMove(s.page, x, y, steps ?? 1, getLogger(), s.id, purpose, inferOperator(req, s, operator));
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -753,7 +969,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -767,7 +983,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -781,7 +997,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -795,7 +1011,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -812,7 +1028,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -826,7 +1042,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -840,7 +1056,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -857,7 +1073,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -871,7 +1087,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -885,7 +1101,7 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -899,11 +1115,12 @@ function registerActionRoutes(server, registry) {
         const { purpose, operator, ...opts } = req.body ?? {};
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         try {
-            return await Actions.scrollUntil(s.page, opts, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+            const result = await Actions.scrollUntil(s.page, opts, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+            return { ...result, session_id: s.id };
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -913,11 +1130,12 @@ function registerActionRoutes(server, registry) {
             return;
         const { purpose, operator, ...opts } = req.body;
         try {
-            return await Actions.loadMoreUntil(s.page, opts, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+            const result = await Actions.loadMoreUntil(s.page, opts, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+            return { ...result, session_id: s.id };
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
     });
@@ -925,13 +1143,13 @@ function registerActionRoutes(server, registry) {
     // R07-T13: snapshot_map — versioned element scan with page_rev tracking
     // ---------------------------------------------------------------------------
     server.post('/api/v1/sessions/:id/snapshot_map', async (req, reply) => {
-        const s = resolve(req.params.id, reply);
+        const s = resolveWithPage(req.params.id, req.body?.page_id, reply);
         if (!s)
             return;
-        const { scope, limit = 500, purpose, operator } = req.body ?? {};
+        const { scope, limit = 500, include_unlabeled = false, purpose, operator } = req.body ?? {};
         const bm = server.browserManager;
         try {
-            const elemResult = await Actions.elementMap(s.page, { scope, limit }, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+            const elemResult = await Actions.elementMap(s.page, { scope, limit, include_unlabeled }, getLogger(), s.id, purpose, inferOperator(req, s, operator));
             const snapshotId = 'snap_' + crypto_1.default.randomBytes(4).toString('hex');
             const pageRev = bm?.getPageRev(s.id) ?? 0;
             const elements = elemResult.elements.map((el) => ({ ...el, ref_id: `${snapshotId}:${el.element_id}` }));
@@ -940,9 +1158,229 @@ function registerActionRoutes(server, registry) {
         }
         catch (e) {
             if (e instanceof actions_1.ActionDiagnosticsError)
-                return reply.code(422).send(e.diagnostics);
+                return reply.code(422).send(enrichDiag(e.diagnostics));
+            throw e;
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // R08-R10: Semantic element locator — find by role/text/label/placeholder/alt_text
+    // ---------------------------------------------------------------------------
+    server.post('/api/v1/sessions/:id/find', async (req, reply) => {
+        const s = resolve(req.params.id, reply);
+        if (!s)
+            return;
+        const { query_type, query, name, exact = false, nth = 0 } = req.body;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            let locator;
+            if (query_type === 'role')
+                locator = s.page.getByRole(query, { name, exact });
+            else if (query_type === 'text')
+                locator = s.page.getByText(query, { exact });
+            else if (query_type === 'label')
+                locator = s.page.getByLabel(query, { exact });
+            else if (query_type === 'placeholder')
+                locator = s.page.getByPlaceholder(query, { exact });
+            else if (query_type === 'alt_text')
+                locator = s.page.getByAltText(query, { exact });
+            else
+                return reply.code(400).send({ error: `Unknown query_type: ${query_type}`, valid: ['role', 'text', 'label', 'placeholder', 'alt_text'] });
+            const count = await locator.count();
+            if (count === 0)
+                return { status: 'ok', found: false, count: 0, nth: 0, query_type, query };
+            const target = locator.nth(nth);
+            const bbox = await target.boundingBox().catch(() => null);
+            const text = await target.textContent().catch(() => null);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const tag = await target.evaluate((el) => el.tagName.toLowerCase()).catch(() => null);
+            return { status: 'ok', found: true, count, nth, query_type, query, tag, text: text?.trim() || null, bbox };
+        }
+        catch (e) {
+            if (e instanceof actions_1.ActionDiagnosticsError)
+                return reply.code(422).send(enrichDiag(e.diagnostics));
+            throw e;
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // R08-R16: Upload URL — fetch remote URL and upload as file input
+    // ---------------------------------------------------------------------------
+    server.post('/api/v1/sessions/:id/upload_url', async (req, reply) => {
+        const s = resolve(req.params.id, reply);
+        if (!s)
+            return;
+        const { url, filename: filenameHint, mime_type, purpose, operator } = req.body;
+        if (!url)
+            return reply.code(400).send({ error: 'url is required' });
+        const cssSelector = resolveTarget(req.body, reply, s.id);
+        if (!cssSelector)
+            return;
+        let resp;
+        try {
+            resp = await fetch(url);
+        }
+        catch (e) {
+            return reply.code(422).send({ error: 'fetch_failed', message: e.message, url });
+        }
+        if (!resp.ok)
+            return reply.code(422).send({ error: 'fetch_failed', http_status: resp.status, url });
+        const buf = Buffer.from(await resp.arrayBuffer());
+        const filename = filenameHint ?? url.split('/').pop()?.split('?')[0] ?? 'file';
+        const ext = path_1.default.extname(filename) || '.bin';
+        const tmpPath = path_1.default.join(os_1.default.tmpdir(), `agentmb_${crypto_1.default.randomBytes(4).toString('hex')}${ext}`);
+        try {
+            await fs_1.default.promises.writeFile(tmpPath, buf);
+            const b64 = buf.toString('base64');
+            const result = await Actions.uploadFile(s.page, cssSelector, b64, filename, mime_type, getLogger(), s.id, purpose, inferOperator(req, s, operator));
+            return { ...result, url, fetched_bytes: buf.length };
+        }
+        catch (e) {
+            if (e instanceof actions_1.ActionDiagnosticsError)
+                return reply.code(422).send(enrichDiag(e.diagnostics));
             throw e;
         }
+        finally {
+            fs_1.default.promises.unlink(tmpPath).catch(() => { });
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // R08-R18: run_steps — batch action dispatcher
+    // Supported actions: navigate, click, fill, type, press, hover, scroll,
+    //   wait_for_selector, wait_text, screenshot, eval
+    // r08-c07: resolveRefIdForStep — throws (instead of reply) for use inside step loops
+    // ---------------------------------------------------------------------------
+    function resolveRefIdForStep(params, sessionId) {
+        if (params.ref_id) {
+            const bm = server.browserManager;
+            if (!bm)
+                throw new Error('ref_id resolution requires BrowserManager');
+            const colonIdx = params.ref_id.lastIndexOf(':');
+            if (colonIdx === -1)
+                throw new Error(`Invalid ref_id format: "${params.ref_id}"; expected "snap_XXXXXX:eN"`);
+            const snapshotId = params.ref_id.slice(0, colonIdx);
+            const eid = params.ref_id.slice(colonIdx + 1);
+            const snapshot = bm.getSnapshot(sessionId, snapshotId);
+            if (!snapshot)
+                throw new Error(`stale_ref: snapshot "${snapshotId}" not found or expired; call snapshot_map again`);
+            const currentRev = bm.getPageRev(sessionId);
+            if (snapshot.page_rev !== currentRev)
+                throw new Error(`stale_ref: page changed (snapshot_rev=${snapshot.page_rev}, current=${currentRev}); call snapshot_map again`);
+            return `[data-agentmb-eid="${eid}"]`;
+        }
+        if (params.element_id)
+            return `[data-agentmb-eid="${params.element_id}"]`;
+        return params.selector;
+    }
+    server.post('/api/v1/sessions/:id/run_steps', async (req, reply) => {
+        const s = resolve(req.params.id, reply);
+        if (!s)
+            return;
+        const { steps, stop_on_error = true, purpose, operator } = req.body;
+        if (!Array.isArray(steps) || steps.length === 0)
+            return reply.code(400).send({ error: 'steps must be a non-empty array' });
+        if (steps.length > 100)
+            return reply.code(400).send({ error: 'steps must not exceed 100' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const results = [];
+        const op = inferOperator(req, s, operator);
+        for (let i = 0; i < steps.length; i++) {
+            const step = steps[i];
+            const { action, params = {} } = step;
+            const stepPurpose = params.purpose ?? purpose;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                let result;
+                switch (action) {
+                    case 'navigate':
+                        result = await Actions.navigate(s.page, params.url, params.wait_until ?? 'load', getLogger(), s.id, stepPurpose, op);
+                        break;
+                    case 'click': {
+                        if (!params.selector && !params.element_id && !params.ref_id)
+                            throw new Error('click requires selector, element_id, or ref_id');
+                        const sel = resolveRefIdForStep(params, s.id);
+                        result = await Actions.click(s.page, sel, params.timeout_ms ?? 5000, getLogger(), s.id, stepPurpose, op);
+                        break;
+                    }
+                    case 'fill': {
+                        if (!params.selector && !params.element_id && !params.ref_id)
+                            throw new Error('fill requires selector, element_id, or ref_id');
+                        const sel = resolveRefIdForStep(params, s.id);
+                        result = await Actions.fill(s.page, sel, params.value ?? '', getLogger(), s.id, stepPurpose, op);
+                        break;
+                    }
+                    case 'type': {
+                        if (!params.selector && !params.element_id && !params.ref_id)
+                            throw new Error('type requires selector, element_id, or ref_id');
+                        const sel = resolveRefIdForStep(params, s.id);
+                        result = await Actions.typeText(s.page, sel, params.text ?? '', params.delay_ms ?? 0, getLogger(), s.id, stepPurpose, op);
+                        break;
+                    }
+                    case 'press': {
+                        if (!params.selector && !params.element_id && !params.ref_id)
+                            throw new Error('press requires selector, element_id, or ref_id');
+                        const sel = resolveRefIdForStep(params, s.id);
+                        result = await Actions.press(s.page, sel, params.key ?? '', getLogger(), s.id, stepPurpose, op);
+                        break;
+                    }
+                    case 'hover': {
+                        if (!params.selector && !params.element_id && !params.ref_id)
+                            throw new Error('hover requires selector, element_id, or ref_id');
+                        const sel = resolveRefIdForStep(params, s.id);
+                        result = await Actions.hover(s.page, sel, getLogger(), s.id, stepPurpose, op);
+                        break;
+                    }
+                    case 'scroll': {
+                        if (!params.selector && !params.element_id && !params.ref_id)
+                            throw new Error('scroll requires selector, element_id, or ref_id');
+                        const sel = resolveRefIdForStep(params, s.id);
+                        result = await Actions.scroll(s.page, sel, { delta_x: params.delta_x ?? 0, delta_y: params.delta_y ?? 300 }, getLogger(), s.id, stepPurpose, op);
+                        break;
+                    }
+                    case 'wait_for_selector':
+                        result = await Actions.waitForSelector(s.page, params.selector, params.state ?? 'visible', params.timeout_ms ?? 5000, getLogger(), s.id, stepPurpose, op);
+                        break;
+                    case 'wait_text':
+                        result = await Actions.waitForText(s.page, params.text, params.timeout_ms ?? 5000, getLogger(), s.id, stepPurpose, op);
+                        break;
+                    case 'screenshot':
+                        result = await Actions.screenshot(s.page, params.format ?? 'png', params.full_page ?? false, getLogger(), s.id, stepPurpose, op);
+                        break;
+                    case 'eval':
+                        result = await Actions.evaluate(s.page, params.expression, getLogger(), s.id, stepPurpose, op);
+                        break;
+                    default:
+                        throw new Error(`unsupported action: ${action}`);
+                }
+                results.push({ step: i + 1, action, result });
+            }
+            catch (e) {
+                const errPayload = e instanceof actions_1.ActionDiagnosticsError
+                    ? enrichDiag(e.diagnostics)
+                    : { error: e.message ?? String(e) };
+                results.push({ step: i + 1, action, error: errPayload });
+                if (stop_on_error)
+                    break;
+            }
+        }
+        const failed = results.filter(r => r.error);
+        return {
+            status: failed.length === 0 ? 'ok' : (results.filter(r => r.result).length > 0 ? 'partial' : 'failed'),
+            total_steps: steps.length,
+            completed_steps: results.filter(r => r.result).length,
+            failed_steps: failed.length,
+            results,
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // R08-R12: Snapshot Ref 强化 — GET page_rev endpoint
+    // Lets clients cheaply check if the page has changed since last snapshot.
+    // ---------------------------------------------------------------------------
+    server.get('/api/v1/sessions/:id/page_rev', async (req, reply) => {
+        const s = resolve(req.params.id, reply);
+        if (!s)
+            return;
+        const bm = server.browserManager;
+        const page_rev = bm?.getPageRev(s.id) ?? 0;
+        return { status: 'ok', session_id: req.params.id, page_rev, url: s.page.url() };
     });
 }
 //# sourceMappingURL=actions.js.map