agentmb 0.1.1 → 0.3.2

package/dist/cli/commands/actions.js

@@ -11,6 +11,27 @@ const client_1 = require("../client");
 function collectValues(val, prev) {
     return prev.concat([val]);
 }
+// T09: extension → MIME mapping for upload auto-inference
+const EXT_TO_MIME = {
+    jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', gif: 'image/gif',
+    webp: 'image/webp', avif: 'image/avif', svg: 'image/svg+xml',
+    pdf: 'application/pdf',
+    mp4: 'video/mp4', mov: 'video/quicktime', avi: 'video/x-msvideo', webm: 'video/webm',
+    mp3: 'audio/mpeg', wav: 'audio/wav', ogg: 'audio/ogg', m4a: 'audio/mp4',
+    txt: 'text/plain', csv: 'text/csv', html: 'text/html', css: 'text/css', js: 'text/javascript',
+    json: 'application/json', xml: 'application/xml',
+    zip: 'application/zip', gz: 'application/gzip', tar: 'application/x-tar',
+    doc: 'application/msword',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xls: 'application/vnd.ms-excel',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    ppt: 'application/vnd.ms-powerpoint',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+};
+function inferMime(filePath) {
+    const ext = path_1.default.extname(filePath).slice(1).toLowerCase();
+    return EXT_TO_MIME[ext] ?? 'application/octet-stream';
+}
 function printDiagnostics(res) {
     console.error('Error:', res.error);
     if (res.url)
@@ -29,11 +50,12 @@ function actionCommands(program) {
         .command('navigate <session-id> <url>')
         .description('Navigate to URL')
         .option('--wait-until <event>', 'Wait until event (load|networkidle|commit)', 'load')
+        .option('--page-id <id>', 'Target a specific page/tab by page_id (default: active tab)')
         .action(async (sessionId, url, opts) => {
-        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/navigate`, {
-            url,
-            wait_until: opts.waitUntil,
-        });
+        const body = { url, wait_until: opts.waitUntil };
+        if (opts.pageId)
+            body.page_id = opts.pageId;
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/navigate`, body);
         if (res.error) {
             console.error('Error:', res.error);
             process.exit(1);
@@ -47,11 +69,12 @@ function actionCommands(program) {
         .option('-o, --out <file>', 'Output file path', './screenshot.png')
         .option('--full-page', 'Capture full page')
         .option('--format <fmt>', 'Format: png|jpeg', 'png')
+        .option('--page-id <id>', 'Target a specific page/tab by page_id (default: active tab)')
         .action(async (sessionId, opts) => {
-        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/screenshot`, {
-            format: opts.format,
-            full_page: opts.fullPage,
-        });
+        const body = { format: opts.format, full_page: opts.fullPage };
+        if (opts.pageId)
+            body.page_id = opts.pageId;
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/screenshot`, body);
         if (res.error) {
             printDiagnostics(res);
             process.exit(1);
@@ -63,8 +86,12 @@ function actionCommands(program) {
     program
         .command('eval <session-id> <expression>')
         .description('Evaluate JavaScript expression in browser')
-        .action(async (sessionId, expression) => {
-        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/eval`, { expression });
+        .option('--page-id <id>', 'Target a specific page/tab by page_id (default: active tab)')
+        .action(async (sessionId, expression, opts) => {
+        const body = { expression };
+        if (opts.pageId)
+            body.page_id = opts.pageId;
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/eval`, body);
         if (res.error) {
             printDiagnostics(res);
             process.exit(1);
@@ -91,11 +118,16 @@ function actionCommands(program) {
     });
     program
         .command('click <session-id> <selector-or-eid>')
-        .description('Click an element (use --element-id to treat arg as element_id from element-map)')
+        .description('Click an element (use --element-id or --ref-id to identify element)')
         .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
+        .option('--page-id <id>', 'Target a specific page/tab by page_id (default: active tab)')
         .action(async (sessionId, selectorOrEid, opts) => {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const body = opts.elementId ? { element_id: selectorOrEid } : { selector: selectorOrEid };
+        const body = opts.refId
+            ? { ref_id: selectorOrEid }
+            : opts.elementId ? { element_id: selectorOrEid } : { selector: selectorOrEid };
+        if (opts.pageId)
+            body.page_id = opts.pageId;
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/click`, body);
         if (res.error) {
             console.error('Error:', res.error);
@@ -105,13 +137,25 @@ function actionCommands(program) {
     });
     program
         .command('fill <session-id> <selector-or-eid> <value>')
-        .description('Fill a form field (use --element-id to treat first arg as element_id from element-map)')
+        .description('Fill a form field (use --element-id or --ref-id to identify element)')
         .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
+        .option('--fill-strategy <type>', 'Fill strategy: normal (default) | type (simulate keystrokes)', 'normal')
+        .option('--char-delay-ms <ms>', 'Delay between characters when --fill-strategy=type', '0')
+        .option('--page-id <id>', 'Target a specific page/tab by page_id (default: active tab)')
         .action(async (sessionId, selectorOrEid, value, opts) => {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const body = opts.elementId
-            ? { element_id: selectorOrEid, value }
-            : { selector: selectorOrEid, value };
+        const body = opts.refId
+            ? { ref_id: selectorOrEid, value }
+            : opts.elementId
+                ? { element_id: selectorOrEid, value }
+                : { selector: selectorOrEid, value };
+        if (opts.fillStrategy && opts.fillStrategy !== 'normal')
+            body.fill_strategy = opts.fillStrategy;
+        const charDelay = parseInt(opts.charDelayMs ?? '0');
+        if (charDelay > 0)
+            body.char_delay_ms = charDelay;
+        if (opts.pageId)
+            body.page_id = opts.pageId;
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/fill`, body);
         if (res.error) {
             console.error('Error:', res.error);
@@ -155,27 +199,48 @@ function actionCommands(program) {
         console.log(`✓ Session ${sessionId} returned to headless mode. Automation can resume.`);
     });
     program
-        .command('type <session-id> <selector> <text>')
-        .description('Type text into an element character by character')
+        .command('type <session-id> <selector-or-eid> <text>')
+        .description('Type text character by character (use --element-id or --ref-id to identify element)')
+        .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
         .option('--delay-ms <ms>', 'Delay between keystrokes (ms)', '0')
-        .action(async (sessionId, selector, text, opts) => {
-        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/type`, { selector, text, delay_ms: parseInt(opts.delayMs) });
+        .option('--page-id <id>', 'Target a specific page/tab by page_id (default: active tab)')
+        .action(async (sessionId, selectorOrEid, text, opts) => {
+        const delay_ms = parseInt(opts.delayMs);
+        const body = opts.refId
+            ? { ref_id: selectorOrEid, text, delay_ms }
+            : opts.elementId
+                ? { element_id: selectorOrEid, text, delay_ms }
+                : { selector: selectorOrEid, text, delay_ms };
+        if (opts.pageId)
+            body.page_id = opts.pageId;
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/type`, body);
         if (res.error) {
             printDiagnostics(res);
             process.exit(1);
         }
-        console.log(`✓ Typed into "${selector}" (${res.duration_ms}ms)`);
+        console.log(`✓ Typed into "${selectorOrEid}" (${res.duration_ms}ms)`);
     });
     program
-        .command('press <session-id> <selector> <key>')
-        .description('Press a key or combo (e.g. Enter, Tab, Control+a)')
-        .action(async (sessionId, selector, key) => {
-        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/press`, { selector, key });
+        .command('press <session-id> <selector-or-eid> <key>')
+        .description('Press a key or combo (e.g. Enter, Tab, Control+a) (use --element-id or --ref-id to identify element)')
+        .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
+        .option('--page-id <id>', 'Target a specific page/tab by page_id (default: active tab)')
+        .action(async (sessionId, selectorOrEid, key, opts) => {
+        const body = opts.refId
+            ? { ref_id: selectorOrEid, key }
+            : opts.elementId
+                ? { element_id: selectorOrEid, key }
+                : { selector: selectorOrEid, key };
+        if (opts.pageId)
+            body.page_id = opts.pageId;
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/press`, body);
         if (res.error) {
             printDiagnostics(res);
             process.exit(1);
         }
-        console.log(`✓ Pressed "${key}" on "${selector}" (${res.duration_ms}ms)`);
+        console.log(`✓ Pressed "${key}" on "${selectorOrEid}" (${res.duration_ms}ms)`);
     });
     program
         .command('select <session-id> <selector> <value...>')
@@ -189,15 +254,22 @@ function actionCommands(program) {
         console.log(`✓ Selected [${res.selected.join(', ')}] in "${selector}" (${res.duration_ms}ms)`);
     });
     program
-        .command('hover <session-id> <selector>')
-        .description('Hover over an element')
-        .action(async (sessionId, selector) => {
-        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/hover`, { selector });
+        .command('hover <session-id> <selector-or-eid>')
+        .description('Hover over an element (use --element-id or --ref-id to identify element)')
+        .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
+        .action(async (sessionId, selectorOrEid, opts) => {
+        const body = opts.refId
+            ? { ref_id: selectorOrEid }
+            : opts.elementId
+                ? { element_id: selectorOrEid }
+                : { selector: selectorOrEid };
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/hover`, body);
         if (res.error) {
             printDiagnostics(res);
             process.exit(1);
         }
-        console.log(`✓ Hovered over "${selector}" (${res.duration_ms}ms)`);
+        console.log(`✓ Hovered over "${selectorOrEid}" (${res.duration_ms}ms)`);
     });
     program
         .command('wait-selector <session-id> <selector>')
@@ -246,33 +318,45 @@ function actionCommands(program) {
     });
     program
         .command('upload <session-id> <selector> <file>')
-        .description('Upload a local file to a file input element')
-        .option('--mime-type <type>', 'MIME type', 'application/octet-stream')
+        .description('Upload a local file to a file input element (MIME auto-inferred from extension)')
+        .option('--mime-type <type>', 'Override MIME type (default: inferred from file extension)')
         .action(async (sessionId, selector, file, opts) => {
         const buf = fs_1.default.readFileSync(file);
+        const mime_type = opts.mimeType ?? inferMime(file);
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/upload`, {
             selector,
             content: buf.toString('base64'),
             filename: path_1.default.basename(file),
-            mime_type: opts.mimeType,
+            mime_type,
         });
         if (res.error) {
             printDiagnostics(res);
             process.exit(1);
         }
-        console.log(`✓ Uploaded "${res.filename}" (${res.size_bytes} bytes, ${res.duration_ms}ms)`);
+        console.log(`✓ Uploaded "${res.filename}" (${res.size_bytes} bytes, mime=${mime_type}, ${res.duration_ms}ms)`);
     });
     program
-        .command('download <session-id> <selector>')
-        .description('Click a download link and save the file')
+        .command('download <session-id> <selector-or-eid>')
+        .description('Click a download link and save the file (requires session --accept-downloads; use --element-id or --ref-id to identify element)')
         .option('-o, --out <file>', 'Output file path (default: suggested filename)')
         .option('--timeout-ms <ms>', 'Timeout in ms', '30000')
-        .action(async (sessionId, selector, opts) => {
-        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/download`, {
-            selector, timeout_ms: parseInt(opts.timeoutMs),
-        });
+        .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
+        .action(async (sessionId, selectorOrEid, opts) => {
+        const body = opts.refId
+            ? { ref_id: selectorOrEid }
+            : opts.elementId ? { element_id: selectorOrEid } : { selector: selectorOrEid };
+        body.timeout_ms = parseInt(opts.timeoutMs);
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/download`, body);
         if (res.error) {
-            printDiagnostics(res);
+            if (res.error === 'download_not_enabled') {
+                console.error('Error: Downloads are disabled for this session.');
+                console.error('  Create the session with --accept-downloads flag:');
+                console.error('  agentmb session new --accept-downloads');
+            }
+            else {
+                printDiagnostics(res);
+            }
             process.exit(1);
         }
         const outPath = opts.out ?? res.filename;
@@ -361,14 +445,20 @@ function actionCommands(program) {
     // ---------------------------------------------------------------------------
     program
         .command('element-map <session-id>')
-        .description('Scan the page and return a numbered element map (assigns stable element IDs)')
+        .description('Scan the page and return a numbered element map (assigns stable element IDs). Note: icon-only elements without aria-label/title/text will have an empty label unless --include-unlabeled is set.')
         .option('--scope <selector>', 'Limit scan to elements inside this CSS selector')
         .option('--limit <n>', 'Max elements to return', '500')
+        .option('--include-unlabeled', 'Include icon-only elements with no accessible text; synthesizes [tag @ x,y] label as fallback')
         .option('--json', 'Output raw JSON instead of a table')
+        .option('--page-id <id>', 'Target a specific page/tab by page_id (default: active tab)')
         .action(async (sessionId, opts) => {
         const body = { limit: parseInt(opts.limit) };
         if (opts.scope)
             body.scope = opts.scope;
+        if (opts.includeUnlabeled)
+            body.include_unlabeled = true;
+        if (opts.pageId)
+            body.page_id = opts.pageId;
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/element_map`, body);
         if (res.error) {
             console.error('Error:', res.error);
@@ -386,8 +476,9 @@ function actionCommands(program) {
         console.log(`Found ${elements.length} element(s) on ${res.url}:`);
         for (const el of elements) {
             const blocked = el.overlay_blocked ? ' [overlay-blocked]' : '';
-            const text = String(el.text ?? '').slice(0, 60).replace(/\n/g, ' ');
-            console.log(`  ${el.element_id}  <${el.tag}> role=${el.role}${blocked}  ${text}`);
+            const label = String(el.label ?? el.text ?? '').slice(0, 60).replace(/\n/g, ' ');
+            const src = el.label_source && el.label_source !== 'none' ? ` [${el.label_source}]` : '';
+            console.log(`  ${el.element_id}  <${el.tag}> role=${el.role}${blocked}${src}  ${label}`);
         }
     });
     program
@@ -395,9 +486,13 @@ function actionCommands(program) {
         .description('Read a property from an element (text|html|value|attr|count|box)')
         .option('--attr-name <name>', 'Attribute name (required when property=attr)')
         .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
         .action(async (sessionId, property, target, opts) => {
         const body = { property };
-        if (opts.elementId) {
+        if (opts.refId) {
+            body.ref_id = target;
+        }
+        else if (opts.elementId) {
             body.element_id = target;
         }
         else {
@@ -416,10 +511,14 @@ function actionCommands(program) {
         .command('assert <session-id> <property> <selector-or-eid>')
         .description('Assert element state: visible|enabled|checked')
         .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
         .option('--expected <bool>', 'Expected value (true|false)', 'true')
         .action(async (sessionId, property, target, opts) => {
         const body = { property, expected: opts.expected !== 'false' };
-        if (opts.elementId) {
+        if (opts.refId) {
+            body.ref_id = target;
+        }
+        else if (opts.elementId) {
             body.element_id = target;
         }
         else {
@@ -460,14 +559,22 @@ function actionCommands(program) {
     // ---------------------------------------------------------------------------
     program
         .command('snapshot-map <session-id>')
-        .description('Snapshot the page element map with page_rev tracking (returns ref_ids for stable targeting)')
+        .description('Snapshot the page element map with page_rev tracking (returns ref_ids for stable targeting).\n' +
+        'Limitation: elements with no accessible text (aria-label/title/placeholder/innerText) will have\n' +
+        'an empty label. Use --include-unlabeled to synthesize a [tag @ x,y] fallback for icon-only elements.')
         .option('--scope <selector>', 'Limit scan to elements inside this CSS selector')
         .option('--limit <n>', 'Max elements to return', '500')
+        .option('--include-unlabeled', 'Include icon-only elements with no accessible text; synthesizes [tag @ x,y] fallback label')
         .option('--json', 'Output raw JSON instead of a table')
+        .option('--page-id <id>', 'Target a specific page/tab by page_id (default: active tab)')
         .action(async (sessionId, opts) => {
         const body = { limit: parseInt(opts.limit) };
         if (opts.scope)
             body.scope = opts.scope;
+        if (opts.includeUnlabeled)
+            body.include_unlabeled = true;
+        if (opts.pageId)
+            body.page_id = opts.pageId;
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/snapshot_map`, body);
         if (res.error) {
             console.error('Error:', res.error);
@@ -481,8 +588,9 @@ function actionCommands(program) {
         console.log(`Snapshot ${res.snapshot_id} (page_rev=${res.page_rev}) — ${elements.length} element(s) on ${res.url}:`);
         for (const el of elements) {
             const blocked = el.overlay_blocked ? ' [overlay-blocked]' : '';
-            const text = String(el.text ?? '').slice(0, 60).replace(/\n/g, ' ');
-            console.log(`  ${el.ref_id}  <${el.tag}> role=${el.role}${blocked}  ${text}`);
+            const label = String(el.label ?? el.text ?? '').slice(0, 60).replace(/\n/g, ' ');
+            const src = el.label_source && el.label_source !== 'none' ? ` [${el.label_source}]` : '';
+            console.log(`  ${el.ref_id}  <${el.tag}> role=${el.role}${blocked}${src}  ${label}`);
         }
     });
     // ---------------------------------------------------------------------------
@@ -492,11 +600,14 @@ function actionCommands(program) {
         .command('dblclick <session-id> <selector-or-eid>')
         .description('Double-click an element')
         .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
         .option('--timeout-ms <ms>', 'Timeout in ms', '5000')
         .action(async (sessionId, selectorOrEid, opts) => {
-        const body = opts.elementId
-            ? { element_id: selectorOrEid }
-            : { selector: selectorOrEid };
+        const body = opts.refId
+            ? { ref_id: selectorOrEid }
+            : opts.elementId
+                ? { element_id: selectorOrEid }
+                : { selector: selectorOrEid };
         body.timeout_ms = parseInt(opts.timeoutMs);
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/dblclick`, body);
         if (res.error) {
@@ -509,10 +620,13 @@ function actionCommands(program) {
         .command('focus <session-id> <selector-or-eid>')
         .description('Focus an element')
         .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
         .action(async (sessionId, selectorOrEid, opts) => {
-        const body = opts.elementId
-            ? { element_id: selectorOrEid }
-            : { selector: selectorOrEid };
+        const body = opts.refId
+            ? { ref_id: selectorOrEid }
+            : opts.elementId
+                ? { element_id: selectorOrEid }
+                : { selector: selectorOrEid };
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/focus`, body);
         if (res.error) {
             console.error('Error:', res.error);
@@ -524,10 +638,13 @@ function actionCommands(program) {
         .command('check <session-id> <selector-or-eid>')
         .description('Check a checkbox or radio button')
         .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
         .action(async (sessionId, selectorOrEid, opts) => {
-        const body = opts.elementId
-            ? { element_id: selectorOrEid }
-            : { selector: selectorOrEid };
+        const body = opts.refId
+            ? { ref_id: selectorOrEid }
+            : opts.elementId
+                ? { element_id: selectorOrEid }
+                : { selector: selectorOrEid };
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/check`, body);
         if (res.error) {
             console.error('Error:', res.error);
@@ -539,10 +656,13 @@ function actionCommands(program) {
         .command('uncheck <session-id> <selector-or-eid>')
         .description('Uncheck a checkbox')
         .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
         .action(async (sessionId, selectorOrEid, opts) => {
-        const body = opts.elementId
-            ? { element_id: selectorOrEid }
-            : { selector: selectorOrEid };
+        const body = opts.refId
+            ? { ref_id: selectorOrEid }
+            : opts.elementId
+                ? { element_id: selectorOrEid }
+                : { selector: selectorOrEid };
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/uncheck`, body);
         if (res.error) {
             console.error('Error:', res.error);
@@ -554,14 +674,20 @@ function actionCommands(program) {
         .command('scroll <session-id> <selector-or-eid>')
         .description('Scroll an element by delta pixels')
         .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
         .option('--dx <px>', 'Horizontal scroll delta', '0')
         .option('--dy <px>', 'Vertical scroll delta', '300')
+        .option('--page-id <id>', 'Target a specific page/tab by page_id (default: active tab)')
         .action(async (sessionId, selectorOrEid, opts) => {
-        const body = opts.elementId
-            ? { element_id: selectorOrEid }
-            : { selector: selectorOrEid };
+        const body = opts.refId
+            ? { ref_id: selectorOrEid }
+            : opts.elementId
+                ? { element_id: selectorOrEid }
+                : { selector: selectorOrEid };
         body.delta_x = parseInt(opts.dx);
         body.delta_y = parseInt(opts.dy);
+        if (opts.pageId)
+            body.page_id = opts.pageId;
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/scroll`, body);
         if (res.error) {
             console.error('Error:', res.error);
@@ -573,10 +699,13 @@ function actionCommands(program) {
         .command('scroll-into-view <session-id> <selector-or-eid>')
         .description('Scroll element into view')
         .option('--element-id', 'Treat selector-or-eid as an element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as a snapshot ref_id (snap_XXXXXX:eN)')
         .action(async (sessionId, selectorOrEid, opts) => {
-        const body = opts.elementId
-            ? { element_id: selectorOrEid }
-            : { selector: selectorOrEid };
+        const body = opts.refId
+            ? { ref_id: selectorOrEid }
+            : opts.elementId
+                ? { element_id: selectorOrEid }
+                : { selector: selectorOrEid };
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/scroll_into_view`, body);
         if (res.error) {
             console.error('Error:', res.error);
@@ -586,26 +715,68 @@ function actionCommands(program) {
     });
     program
         .command('drag <session-id> <source> <target>')
-        .description('Drag an element from source to target (CSS selectors)')
+        .description('Drag from source to target. <source>/<target> are CSS selectors unless --source-ref-id/--target-ref-id used.')
+        .option('--source-ref-id <ref_id>', 'Use snapshot ref_id as drag source instead of CSS selector')
+        .option('--target-ref-id <ref_id>', 'Use snapshot ref_id as drag target instead of CSS selector')
         .option('--timeout-ms <ms>', 'Timeout in ms', '5000')
         .action(async (sessionId, source, target, opts) => {
-        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/drag`, { source, target, timeout_ms: parseInt(opts.timeoutMs) });
+        const body = { timeout_ms: parseInt(opts.timeoutMs) };
+        if (opts.sourceRefId) {
+            body.source_ref_id = opts.sourceRefId;
+        }
+        else {
+            body.source = source;
+        }
+        if (opts.targetRefId) {
+            body.target_ref_id = opts.targetRefId;
+        }
+        else {
+            body.target = target;
+        }
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/drag`, body);
         if (res.error) {
             console.error('Error:', res.error);
             process.exit(1);
         }
-        console.log(`✓ Dragged "${source}" → "${target}" (${res.duration_ms}ms)`);
+        const srcLabel = opts.sourceRefId ?? source;
+        const tgtLabel = opts.targetRefId ?? target;
+        console.log(`✓ Dragged "${srcLabel}" → "${tgtLabel}" (${res.duration_ms}ms)`);
     });
     program
-        .command('mouse-move <session-id> <x> <y>')
-        .description('Move mouse to absolute page coordinates')
-        .action(async (sessionId, x, y) => {
-        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/mouse_move`, { x: parseFloat(x), y: parseFloat(y) });
+        .command('mouse-move <session-id> [x] [y]')
+        .description('Move mouse to coordinates or element center (use --selector/--element-id/--ref-id to resolve from element)')
+        .option('--selector <sel>', 'Move to center of element matching CSS selector')
+        .option('--element-id <id>', 'Move to center of element by element_id from element-map')
+        .option('--ref-id <id>', 'Move to center of element by snapshot ref_id (snap_XXXXXX:eN)')
+        .option('--steps <n>', 'Number of intermediate mouse steps for smooth movement', '1')
+        .action(async (sessionId, x, y, opts) => {
+        const body = {};
+        if (opts.refId) {
+            body.ref_id = opts.refId;
+        }
+        else if (opts.elementId) {
+            body.element_id = opts.elementId;
+        }
+        else if (opts.selector) {
+            body.selector = opts.selector;
+        }
+        else if (x !== undefined && y !== undefined) {
+            body.x = parseFloat(x);
+            body.y = parseFloat(y);
+        }
+        else {
+            console.error('Error: provide x/y or --selector/--element-id/--ref-id');
+            process.exit(1);
+        }
+        const steps = parseInt(opts.steps ?? '1');
+        if (steps > 1)
+            body.steps = steps;
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/mouse_move`, body);
         if (res.error) {
             console.error('Error:', res.error);
             process.exit(1);
         }
-        console.log(`✓ Mouse moved to (${x},${y}) (${res.duration_ms}ms)`);
+        console.log(`✓ Mouse moved to (${res.x},${res.y}) steps=${res.steps ?? 1} (${res.duration_ms}ms)`);
     });
     program
         .command('mouse-down <session-id>')
@@ -745,6 +916,7 @@ function actionCommands(program) {
         .option('--max-scrolls <n>', 'Maximum scroll steps', '50')
         .option('--scroll-delta <px>', 'Pixels per scroll step', '300')
         .option('--stall-ms <ms>', 'Stop if page height unchanged for this many ms', '1500')
+        .option('--step-delay-ms <ms>', 'Delay in ms between each scroll step', '0')
         .action(async (sessionId, opts) => {
         const body = {
             direction: opts.direction,
@@ -752,6 +924,9 @@ function actionCommands(program) {
             scroll_delta: parseInt(opts.scrollDelta),
             stall_ms: parseInt(opts.stallMs),
         };
+        const stepDelay = parseInt(opts.stepDelayMs ?? '0');
+        if (stepDelay > 0)
+            body.step_delay_ms = stepDelay;
         if (opts.scrollSelector)
             body.scroll_selector = opts.scrollSelector;
         if (opts.stopSelector)
@@ -983,10 +1158,13 @@ function actionCommands(program) {
     // ---------------------------------------------------------------------------
     program
         .command('bbox <session-id> <selector-or-eid>')
-        .description('Return the bounding box of an element (selector or element_id)')
+        .description('Return the bounding box of an element (selector, element_id, or ref_id)')
         .option('--element-id', 'Treat arg as element_id from element-map')
+        .option('--ref-id', 'Treat arg as a snapshot ref_id (snap_XXXXXX:eN)')
         .action(async (sessionId, target, opts) => {
-        const body = opts.elementId ? { element_id: target } : { selector: target };
+        const body = opts.refId
+            ? { ref_id: target }
+            : opts.elementId ? { element_id: target } : { selector: target };
         const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/bbox`, body);
         if (res.error) {
             console.error('Error:', res.error);
@@ -1097,5 +1275,89 @@ function actionCommands(program) {
         const r = await (0, client_1.apiDelete)(`/api/v1/sessions/${sessionId}/network_conditions`);
         console.log(`✓ Network conditions reset (status ${r.statusCode})`);
     });
+    // ---------------------------------------------------------------------------
+    // r08-c07 P2 — CLI 新命令补齐
+    // ---------------------------------------------------------------------------
+    program
+        .command('find <session-id> <query-type> <query>')
+        .description('Semantic element find: query-type is role|text|label|placeholder|alt_text')
+        .option('--nth <n>', 'Zero-based index when multiple matches exist', '0')
+        .option('--json', 'Output raw JSON')
+        .action(async (sessionId, queryType, query, opts) => {
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/find`, {
+            query_type: queryType,
+            query,
+            nth: parseInt(opts.nth ?? '0'),
+        });
+        if (res.error) {
+            console.error('Error:', res.error);
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        if (!res.found) {
+            console.log(`(not found: ${queryType}="${query}")`);
+            return;
+        }
+        const b = res.bbox;
+        console.log(`✓ Found: tag=${res.tag} text="${res.text ?? ''}" query_type=${res.query_type}${b ? ` bbox=(${b.x},${b.y} ${b.width}×${b.height})` : ''} (${res.duration_ms}ms)`);
+    });
+    program
+        .command('settings <session-id>')
+        .description('Get current browser settings for a session (viewport, UA, url, headless, profile)')
+        .option('--json', 'Output raw JSON')
+        .action(async (sessionId, opts) => {
+        const res = await (0, client_1.apiGet)(`/api/v1/sessions/${sessionId}/settings`);
+        if (res.error) {
+            console.error('Error:', res.error);
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const vp = res.viewport ?? {};
+        console.log(`Session: ${res.session_id}`);
+        console.log(`  Viewport: ${vp.width ?? '?'}×${vp.height ?? '?'}`);
+        console.log(`  URL:      ${res.url ?? '(none)'}`);
+        console.log(`  Headless: ${res.headless}`);
+        console.log(`  Profile:  ${res.profile}`);
+        console.log(`  UA:       ${res.user_agent ?? '(default)'}`);
+    });
+    program
+        .command('cookie-delete <session-id> <name>')
+        .description('Delete a cookie by name for a session')
+        .option('--domain <domain>', 'Restrict deletion to this domain')
+        .action(async (sessionId, name, opts) => {
+        const body = { name };
+        if (opts.domain)
+            body.domain = opts.domain;
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/cookies/delete`, body);
+        if (res.error) {
+            console.error('Error:', res.error);
+            process.exit(1);
+        }
+        console.log(`✓ Deleted ${res.deleted_count} cookie(s) named "${name}" (${res.duration_ms}ms)`);
+    });
+    program
+        .command('upload-url <session-id> <url> <selector-or-eid>')
+        .description('Fetch an asset from URL and upload it to a file input element')
+        .option('--element-id', 'Treat selector-or-eid as element_id from element-map')
+        .option('--ref-id', 'Treat selector-or-eid as snapshot ref_id (snap_XXXXXX:eN)')
+        .action(async (sessionId, url, selectorOrEid, opts) => {
+        const body = opts.refId
+            ? { url, ref_id: selectorOrEid }
+            : opts.elementId
+                ? { url, element_id: selectorOrEid }
+                : { url, selector: selectorOrEid };
+        const res = await (0, client_1.apiPost)(`/api/v1/sessions/${sessionId}/upload_url`, body);
+        if (res.error) {
+            console.error('Error:', res.error);
+            process.exit(1);
+        }
+        console.log(`✓ Uploaded from URL: ${res.filename} (${res.size_bytes}B, ${res.mime_type ?? 'unknown'}, ${res.duration_ms}ms)`);
+    });
 }
 //# sourceMappingURL=actions.js.map