agentmb 0.1.1 → 0.3.1

package/dist/daemon/routes/actions.js

@@ -38,6 +38,9 @@ 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"));
 require("../types"); // T11: Fastify type augmentation
 const Actions = __importStar(require("../../browser/actions"));
 const actions_1 = require("../../browser/actions");
@@ -146,6 +149,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 +228,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 +243,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;
             }
@@ -225,12 +286,16 @@ function registerActionRoutes(server, registry) {
         return Actions.navigate(s.page, url, wait_until, getLogger(), s.id, purpose, inferOperator(req, s, operator));
     });
     // 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);
         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 +304,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);
         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,7 +369,12 @@ 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) => {
@@ -291,7 +392,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,7 +412,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;
         }
     });
@@ -326,7 +427,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;
         }
     });
@@ -350,7 +451,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;
         }
     });
@@ -373,7 +474,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 +492,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 +513,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 +531,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 +546,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 +562,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 +582,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;
         }
     });
@@ -516,13 +630,13 @@ function registerActionRoutes(server, registry) {
         const s = resolve(req.params.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 +661,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 +686,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 +703,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 +725,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 +744,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 +763,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,7 +782,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;
         }
     });
@@ -688,7 +802,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 +821,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 +829,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 +884,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 +898,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 +912,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 +926,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 +943,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 +957,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 +971,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 +988,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 +1002,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 +1016,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 +1030,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 +1045,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;
         }
     });
@@ -928,10 +1061,10 @@ function registerActionRoutes(server, registry) {
         const s = resolve(req.params.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 +1073,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