@petukhovart/agent-view 0.1.0 → 0.5.0

package/dist/server/server.js

@@ -5,14 +5,19 @@ import { homedir, tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { mkdirSync } from 'node:fs';
 import { getAdapter } from '../adapters/registry.js';
-import { formatAccessibilityTree } from '../inspectors/dom.js';
+import { formatAccessibilityTree, countAccessibilityNodes, diffDomText } from '../inspectors/dom/index.js';
 import { getSceneGraph, getRawScene, diffScenes } from '../inspectors/scene/index.js';
 import { RefStore } from './ref-store.js';
 import { launch, isRunning } from './launcher.js';
 import { readConfig } from '../config/manager.js';
 import { RuntimeType, WebGLEngine } from '../types.js';
+import { TargetType, ConsoleLevel, EvaluationError, MouseButton, } from '../cdp/types.js';
+import { listSupportedTargets, connectToRuntime } from '../cdp/transport.js';
+import { ConsoleStream } from '../cdp/_tests/console-stream.js';
+import { AxTreeCache } from '../cdp/ax-cache.js';
+import { WatchSession } from './watch-session.js';
+import { StopReason, WATCH_MIN_INTERVAL_MS } from '../inspectors/watch/index.js';
 const SERVER_PORT = 47922;
-const VALID_COMMANDS = new Set(['discover', 'launch', 'dom', 'click', 'fill', 'screenshot', 'scene', 'snap', 'wait', 'stop']);
 const VALID_RUNTIMES = new Set(Object.values(RuntimeType));
 const VALID_ENGINES = new Set(Object.values(WebGLEngine));
 const IDLE_TIMEOUT_MS = 5 * 60 * 1000;
@@ -20,6 +25,13 @@ const DELIMITER = '\n';
 const MAX_BUFFER_SIZE = 1_048_576; // 1 MB
 const TOKEN_DIR = join(homedir(), '.agent-view');
 const TOKEN_PATH = join(TOKEN_DIR, 'token');
+const EVAL_OUTPUT_CAP = 64 * 1024;
+const DEFAULT_CONSOLE_TARGETS = [TargetType.Page, TargetType.SharedWorker, TargetType.ServiceWorker];
+const RUNTIME_ONLY_TARGETS = new Set([
+    TargetType.SharedWorker,
+    TargetType.ServiceWorker,
+    TargetType.Worker,
+]);
 function argStr(args, key) {
     const v = args[key];
     return typeof v === 'string' ? v : undefined;
@@ -32,13 +44,95 @@ function argBool(args, key) {
     const v = args[key];
     return typeof v === 'boolean' ? v : undefined;
 }
+function argStrArray(args, key) {
+    const v = args[key];
+    if (!Array.isArray(v))
+        return undefined;
+    return v.filter((x) => typeof x === 'string');
+}
+const ARIA_ROLES = new Set([
+    'button', 'link', 'menuitem', 'tab', 'checkbox', 'radio',
+    'textbox', 'searchbox', 'combobox', 'spinbutton', 'textarea',
+    'listitem', 'option', 'treeitem', 'cell', 'row', 'heading',
+]);
+export function resolveDepth(filter, explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    if (filter !== undefined)
+        return undefined; // unlimited depth when filtering
+    return 4; // default snapshot depth
+}
+export async function textContentFallback(conn, filter) {
+    const safeFilter = JSON.stringify(filter);
+    const js = `(() => {
+    const q = ${safeFilter};
+    const results = [];
+    for (const el of document.querySelectorAll('body *')) {
+      if (results.length >= 5) break;
+      const directText = Array.from(el.childNodes)
+        .filter(n => n.nodeType === Node.TEXT_NODE)
+        .map(n => n.textContent.trim())
+        .join(' ');
+      if (directText.toLowerCase().includes(q.toLowerCase()) && el.offsetParent !== null) {
+        const id = el.id ? '#' + el.id : '';
+        const cls = el.className && typeof el.className === 'string' && el.className.trim()
+          ? '.' + el.className.trim().split(/\\s+/)[0] : '';
+        results.push(el.tagName.toLowerCase() + id + cls);
+      }
+    }
+    return results.length ? results.join(', ') : null;
+  })()`;
+    const result = await conn.evaluate(js);
+    if (!result || typeof result !== 'string') {
+        return `(no text-match for "${filter}")`;
+    }
+    return result.split(', ')
+        .map(loc => `[text-match] "${filter}" found in ${loc} (no accessible role in AX tree)`)
+        .join('\n');
+}
+export function parseFilter(filter) {
+    const colonIdx = filter.indexOf(':');
+    if (colonIdx > 0) {
+        const role = filter.slice(0, colonIdx).trim().toLowerCase();
+        const name = filter.slice(colonIdx + 1).trim();
+        if (name && ARIA_ROLES.has(role)) {
+            return { kind: 'simple', name, role };
+        }
+    }
+    if (filter.startsWith('~') || /[.*+?^${}()|[\]\\]/.test(filter)) {
+        return { kind: 'heuristic', raw: filter };
+    }
+    return { kind: 'simple', name: filter };
+}
 export class AgentViewServer {
     server = null;
     connections = new Map();
     refStore = new RefStore();
     idleTimer = null;
     sceneCache = new Map();
+    domTextCache = new Map();
+    axTreeCache = new AxTreeCache();
+    consoleStream = new ConsoleStream();
     token = '';
+    activeWatches = new Set();
+    handlers = {
+        discover: (req) => this.handleDiscover(req),
+        launch: (req) => this.handleLaunch(req),
+        dom: (req) => this.handleDom(req),
+        click: (req) => this.handleClick(req),
+        drag: (req) => this.handleDrag(req),
+        fill: (req) => this.handleFill(req),
+        wait: (req) => this.handleWait(req),
+        screenshot: (req) => this.handleScreenshot(req),
+        scene: (req) => this.handleScene(req),
+        snap: (req) => this.handleSnap(req),
+        targets: (req) => this.handleTargets(req),
+        eval: (req) => this.handleEval(req),
+        console: (req) => this.handleConsole(req),
+        stop: () => this.handleStop(),
+    };
+    streamingCommands = new Set(['watch']);
+    validCommands = new Set([...Object.keys(this.handlers), ...this.streamingCommands]);
     async start() {
         mkdirSync(TOKEN_DIR, { recursive: true });
         this.token = randomBytes(32).toString('hex');
@@ -55,6 +149,11 @@ export class AgentViewServer {
     resetIdleTimer() {
         if (this.idleTimer)
             clearTimeout(this.idleTimer);
+        if (this.activeWatches.size > 0) {
+            // Pause idle shutdown while streaming handlers are alive.
+            this.idleTimer = null;
+            return;
+        }
         this.idleTimer = setTimeout(() => this.shutdown(), IDLE_TIMEOUT_MS);
     }
     handleSocket(socket) {
@@ -81,7 +180,7 @@ export class AgentViewServer {
                 socket.end(JSON.stringify({ ok: false, error: 'Unauthorized' }) + DELIMITER);
                 return;
             }
-            if (typeof request.command !== 'string' || !VALID_COMMANDS.has(request.command) ||
+            if (typeof request.command !== 'string' || !this.validCommands.has(request.command) ||
                 (request.command !== 'stop' && (!VALID_RUNTIMES.has(request.runtime) ||
                     typeof request.port !== 'number' || request.port < 1 || request.port > 65535))) {
                 socket.end(JSON.stringify({ ok: false, error: 'Invalid request' }) + DELIMITER);
@@ -95,6 +194,10 @@ export class AgentViewServer {
                 socket.end(JSON.stringify({ ok: false, error: 'Invalid args' }) + DELIMITER);
                 return;
             }
+            if (this.streamingCommands.has(request.command)) {
+                await this.handleWatchStreaming(request, socket);
+                return;
+            }
             const response = await this.handleCommand(request);
             socket.end(JSON.stringify(response) + DELIMITER);
         }
@@ -107,30 +210,10 @@ export class AgentViewServer {
         }
     }
     async handleCommand(req) {
-        switch (req.command) {
-            case 'discover':
-                return this.handleDiscover(req);
-            case 'launch':
-                return this.handleLaunch(req);
-            case 'dom':
-                return this.handleDom(req);
-            case 'click':
-                return this.handleClick(req);
-            case 'fill':
-                return this.handleFill(req);
-            case 'screenshot':
-                return this.handleScreenshot(req);
-            case 'scene':
-                return this.handleScene(req);
-            case 'snap':
-                return this.handleSnap(req);
-            case 'wait':
-                return this.handleWait(req);
-            case 'stop':
-                return this.handleStop();
-            default:
-                return { ok: false, error: `Unknown command: ${req.command}` };
-        }
+        const handler = this.handlers[req.command];
+        if (!handler)
+            return { ok: false, error: `Unknown command: ${req.command}` };
+        return handler(req);
     }
     async resolveWindow(req) {
         const adapter = getAdapter(req.runtime);
@@ -154,38 +237,50 @@ export class AgentViewServer {
         }
         return { targetId, windows };
     }
-    async getConnection(req, targetId) {
+    async getPageSession(req, targetId) {
         const connKey = `${req.port}:${targetId}`;
-        let conn = this.connections.get(connKey);
-        if (!conn) {
-            const adapter = getAdapter(req.runtime);
-            conn = await adapter.connect(req.port, targetId);
-            this.connections.set(connKey, conn);
+        const cached = this.connections.get(connKey);
+        if (cached) {
+            if (cached.kind === 'page')
+                return cached.session;
+            throw new Error(`Cached session for ${targetId} is runtime-only — cannot use page operations.`);
         }
-        return conn;
+        const adapter = getAdapter(req.runtime);
+        const session = await adapter.connect(req.port, targetId, this.axTreeCache);
+        this.connections.set(connKey, { kind: 'page', session });
+        return session;
+    }
+    async getRuntimeSession(req, target) {
+        const connKey = `${req.port}:${target.id}`;
+        const cached = this.connections.get(connKey);
+        if (cached)
+            return cached.session;
+        if (target.type === TargetType.Page || target.type === TargetType.Iframe) {
+            // Page targets can serve runtime requests via their PageSession (it extends RuntimeSession).
+            return this.getPageSession(req, target.id);
+        }
+        if (!RUNTIME_ONLY_TARGETS.has(target.type)) {
+            throw new Error(`Target type "${target.type}" does not support eval/console.`);
+        }
+        const session = await connectToRuntime(req.port, target);
+        this.connections.set(connKey, { kind: 'runtime', session });
+        return session;
     }
     async handleDiscover(req) {
         const adapter = getAdapter(req.runtime);
         const windows = await adapter.discover(req.port);
         return {
             ok: true,
-            data: {
-                runtime: req.runtime,
-                port: req.port,
-                windows,
-            },
+            data: { runtime: req.runtime, port: req.port, windows },
         };
     }
     async handleLaunch(req) {
         const launchCmd = argStr(req.args, 'launch');
         const cwd = argStr(req.args, 'cwd');
-        if (!launchCmd) {
+        if (!launchCmd)
             return { ok: false, error: 'No launch command provided' };
-        }
-        if (!cwd) {
+        if (!cwd)
             return { ok: false, error: 'launch requires cwd to validate config' };
-        }
-        // Validate launch command against on-disk config to prevent injection
         const config = readConfig(resolve(cwd));
         if (!config || config.launch !== launchCmd) {
             return { ok: false, error: 'Launch command does not match project config' };
@@ -198,17 +293,76 @@ export class AgentViewServer {
     }
     async handleDom(req) {
         const { targetId } = await this.resolveWindow(req);
-        const conn = await this.getConnection(req, targetId);
-        const nodes = await conn.getAccessibilityTree();
+        const conn = await this.getPageSession(req, targetId);
+        const filter = argStr(req.args, 'filter');
+        const useText = argBool(req.args, 'text') ?? false;
+        const compact = argBool(req.args, 'compact') ?? false;
+        const useCount = argBool(req.args, 'count') ?? false;
+        const isDiff = argBool(req.args, 'diff') ?? false;
+        const cacheKey = `${req.port}:${targetId}`;
+        const { nodes, fromCache } = await conn.getAccessibilityTreeMeta();
+        if (useCount) {
+            const { count } = countAccessibilityNodes(nodes, {
+                filter,
+                depth: resolveDepth(filter, argNum(req.args, 'depth')),
+            });
+            return { ok: true, data: String(count) };
+        }
         const { text, refs, nextRef } = formatAccessibilityTree(nodes, {
-            filter: argStr(req.args, 'filter'),
-            depth: argNum(req.args, 'depth'),
+            filter,
+            depth: resolveDepth(filter, argNum(req.args, 'depth')),
             startRef: this.refStore.getNextRef(),
+            compact,
+            maxLines: argNum(req.args, 'maxLines'),
         });
         this.refStore.store(refs, req.port, targetId, nextRef);
-        return { ok: true, data: text };
+        if (isDiff) {
+            const prev = this.domTextCache.get(cacheKey);
+            this.domTextCache.set(cacheKey, text);
+            if (prev === undefined) {
+                // First call — no snapshot yet, return full tree
+                return { ok: true, data: text };
+            }
+            return { ok: true, data: diffDomText(prev, text) };
+        }
+        if (useText && filter && text.startsWith('(no matching')) {
+            return { ok: true, data: await textContentFallback(conn, filter) };
+        }
+        const data = fromCache ? `[cache]\n${text}` : text;
+        return { ok: true, data };
     }
     async findByFilter(conn, filter, req, targetId, preferRoles) {
+        const parsed = parseFilter(filter);
+        if (parsed.kind === 'simple') {
+            const queryNodes = await conn.queryAXTree({ accessibleName: parsed.name, role: parsed.role });
+            if (queryNodes !== null) {
+                if (queryNodes.length === 0)
+                    return null;
+                const startRef = this.refStore.getNextRef();
+                let refNum = startRef;
+                const refs = [];
+                for (const node of queryNodes) {
+                    if (node.backendDOMNodeId) {
+                        refs.push({ ref: refNum++, backendDOMNodeId: node.backendDOMNodeId });
+                    }
+                }
+                this.refStore.store(refs, req.port, targetId, refNum);
+                if (refs.length === 0)
+                    return null;
+                if (preferRoles) {
+                    for (let i = 0; i < queryNodes.length; i++) {
+                        const node = queryNodes[i];
+                        if (node.backendDOMNodeId && preferRoles.has(node.role?.value ?? '')) {
+                            return { backendDOMNodeId: node.backendDOMNodeId, name: node.name?.value ?? parsed.name };
+                        }
+                    }
+                }
+                const first = queryNodes.find(n => n.backendDOMNodeId);
+                if (!first?.backendDOMNodeId)
+                    return null;
+                return { backendDOMNodeId: first.backendDOMNodeId, name: first.name?.value ?? parsed.name };
+            }
+        }
         const nodes = await conn.getAccessibilityTree();
         const { refs, nextRef } = formatAccessibilityTree(nodes, {
             filter,
@@ -217,7 +371,6 @@ export class AgentViewServer {
         this.refStore.store(refs, req.port, targetId, nextRef);
         if (refs.length === 0)
             return null;
-        // Build map with fallback name resolution (same logic as dom.ts)
         const nodeById = new Map();
         for (const node of nodes)
             nodeById.set(node.nodeId, node);
@@ -250,7 +403,6 @@ export class AgentViewServer {
             }
         }
         const lowerFilter = filter.toLowerCase();
-        // If preferred roles specified, try those first
         if (preferRoles) {
             for (const entry of refs) {
                 const info = nodeByDOMId.get(entry.backendDOMNodeId);
@@ -259,26 +411,26 @@ export class AgentViewServer {
                 }
             }
         }
-        // Pick the deepest match whose name contains the filter text (leaf-first)
         for (let i = refs.length - 1; i >= 0; i--) {
             const info = nodeByDOMId.get(refs[i].backendDOMNodeId);
             if (info && info.name.toLowerCase().includes(lowerFilter)) {
                 return { backendDOMNodeId: refs[i].backendDOMNodeId, name: info.name };
             }
         }
-        // Fallback: last ref (deepest element in filtered tree)
         const last = refs[refs.length - 1];
         const lastInfo = nodeByDOMId.get(last.backendDOMNodeId);
         return { backendDOMNodeId: last.backendDOMNodeId, name: lastInfo?.name ?? filter };
     }
     async handleClick(req) {
         const { targetId } = await this.resolveWindow(req);
-        const conn = await this.getConnection(req, targetId);
+        const conn = await this.getPageSession(req, targetId);
+        const cacheKey = `${req.port}:${targetId}`;
         if (req.args.pos && typeof req.args.pos === 'object') {
             const pos = req.args.pos;
             const x = typeof pos.x === 'number' ? pos.x : 0;
             const y = typeof pos.y === 'number' ? pos.y : 0;
             await conn.clickAtPosition(x, y);
+            this.axTreeCache.invalidate(cacheKey);
             return { ok: true, data: `Clicked at (${x}, ${y})` };
         }
         const clickFilter = argStr(req.args, 'filter');
@@ -290,6 +442,7 @@ export class AgentViewServer {
                 return { ok: false, error: `No element found matching "${filter}"` };
             }
             await conn.clickByNodeId(found.backendDOMNodeId);
+            this.axTreeCache.invalidate(cacheKey);
             return { ok: true, data: `Clicked "${found.name}"` };
         }
         const ref = argNum(req.args, 'ref');
@@ -301,11 +454,52 @@ export class AgentViewServer {
             return { ok: false, error: `Invalid ref: ${ref}. Run \`agent-view dom\` to get fresh refs.` };
         }
         await conn.clickByNodeId(entry.backendDOMNodeId);
+        this.axTreeCache.invalidate(cacheKey);
         return { ok: true, data: `Clicked ref ${ref}` };
     }
+    async handleDrag(req) {
+        const { targetId } = await this.resolveWindow(req);
+        const conn = await this.getPageSession(req, targetId);
+        const cacheKey = `${req.port}:${targetId}`;
+        const from = await this.resolveDragPoint(req, conn, 'from', { scrollIntoView: true });
+        if ('error' in from)
+            return { ok: false, error: from.error };
+        const to = await this.resolveDragPoint(req, conn, 'to', { scrollIntoView: false });
+        if ('error' in to)
+            return { ok: false, error: to.error };
+        const opts = {
+            steps: argNum(req.args, 'steps'),
+            button: parseMouseButton(argStr(req.args, 'button')),
+            holdMs: argNum(req.args, 'holdMs'),
+        };
+        await conn.dragBetweenPositions(from.point, to.point, opts);
+        this.axTreeCache.invalidate(cacheKey);
+        return {
+            ok: true,
+            data: `Dragged (${from.point.x.toFixed(0)}, ${from.point.y.toFixed(0)}) → (${to.point.x.toFixed(0)}, ${to.point.y.toFixed(0)})`,
+        };
+    }
+    async resolveDragPoint(req, conn, side, opts) {
+        const ref = argNum(req.args, `${side}Ref`);
+        const x = argNum(req.args, `${side}X`);
+        const y = argNum(req.args, `${side}Y`);
+        if (ref !== undefined) {
+            const entry = this.refStore.get(ref);
+            if (!entry) {
+                return { error: `Invalid --${side} ref: ${ref}. Run \`agent-view dom\` to get fresh refs.` };
+            }
+            const point = await conn.getBoxCenter(entry.backendDOMNodeId, opts);
+            return { point };
+        }
+        if (x !== undefined && y !== undefined) {
+            return { point: { x, y } };
+        }
+        return { error: `drag requires --${side} <ref> or --${side}-pos <x,y>` };
+    }
     async handleFill(req) {
         const { targetId } = await this.resolveWindow(req);
-        const conn = await this.getConnection(req, targetId);
+        const conn = await this.getPageSession(req, targetId);
+        const cacheKey = `${req.port}:${targetId}`;
         const value = argStr(req.args, 'value');
         if (value === undefined) {
             return { ok: false, error: 'fill requires --value' };
@@ -319,6 +513,7 @@ export class AgentViewServer {
                 return { ok: false, error: `No element found matching "${filter}"` };
             }
             await conn.fillByNodeId(found.backendDOMNodeId, value);
+            this.axTreeCache.invalidate(cacheKey);
             return { ok: true, data: `Filled "${found.name}" with "${value}"` };
         }
         const fillRef = argNum(req.args, 'ref');
@@ -330,6 +525,7 @@ export class AgentViewServer {
             return { ok: false, error: `Invalid ref: ${fillRef}. Run \`agent-view dom\` to get fresh refs.` };
         }
         await conn.fillByNodeId(entry.backendDOMNodeId, value);
+        this.axTreeCache.invalidate(cacheKey);
         return { ok: true, data: `Filled ref ${fillRef} with "${value}"` };
     }
     async handleWait(req) {
@@ -341,7 +537,7 @@ export class AgentViewServer {
         const interval = 500;
         const maxAttempts = Math.ceil((timeout * 1000) / interval);
         const { targetId } = await this.resolveWindow(req);
-        const conn = await this.getConnection(req, targetId);
+        const conn = await this.getPageSession(req, targetId);
         for (let i = 0; i < maxAttempts; i++) {
             const nodes = await conn.getAccessibilityTree();
             const { refs, text, nextRef } = formatAccessibilityTree(nodes, {
@@ -356,23 +552,42 @@ export class AgentViewServer {
         }
         return { ok: false, error: `Timeout: "${filter}" not found after ${timeout}s` };
     }
-    async handleScreenshot(req) {
-        const { targetId } = await this.resolveWindow(req);
-        const conn = await this.getConnection(req, targetId);
-        const buffer = await conn.captureScreenshot();
-        const filename = `agent-view-screenshot-${Date.now()}.png`;
+    async captureScreenshotToFile(conn, opts = {}) {
+        const { buffer, format } = await conn.captureScreenshot(opts);
+        const ext = format === 'jpeg' ? 'jpg' : format;
+        const filename = `agent-view-screenshot-${Date.now()}.${ext}`;
         const filepath = join(tmpdir(), filename);
         await writeFile(filepath, buffer);
-        return { ok: true, data: filepath };
+        return filepath;
+    }
+    async handleScreenshot(req) {
+        const { targetId } = await this.resolveWindow(req);
+        const conn = await this.getPageSession(req, targetId);
+        const scale = argNum(req.args, 'scale');
+        const cropFilter = argStr(req.args, 'crop');
+        let warning;
+        let clip;
+        if (cropFilter !== undefined) {
+            const found = await this.findByFilter(conn, cropFilter, req, targetId);
+            if (!found) {
+                warning = `crop filter '${cropFilter}' matched nothing — capturing full window`;
+            }
+            else {
+                clip = await conn.getBoxRect(found.backendDOMNodeId, { scrollIntoView: true });
+            }
+        }
+        const filepath = await this.captureScreenshotToFile(conn, { scale, clip });
+        return { ok: true, data: filepath, warning };
     }
     async handleScene(req) {
         const { targetId } = await this.resolveWindow(req);
-        const conn = await this.getConnection(req, targetId);
+        const conn = await this.getPageSession(req, targetId);
         const isDiff = argBool(req.args, 'diff') ?? false;
         const cacheKey = `${req.port}:${targetId}`;
         const sceneFilter = argStr(req.args, 'filter');
         const sceneDepth = argNum(req.args, 'depth');
         const sceneVerbose = argBool(req.args, 'verbose');
+        const sceneCompact = argBool(req.args, 'compact');
         if (isDiff) {
             const curr = await getRawScene(conn, req.engine);
             if (!curr) {
@@ -385,6 +600,7 @@ export class AgentViewServer {
                     filter: sceneFilter,
                     depth: sceneDepth,
                     verbose: sceneVerbose,
+                    compact: sceneCompact,
                 });
                 return { ok: true, data: text };
             }
@@ -394,15 +610,16 @@ export class AgentViewServer {
             filter: sceneFilter,
             depth: sceneDepth,
             verbose: sceneVerbose,
+            compact: sceneCompact,
         });
         return { ok: true, data: text };
     }
     async handleSnap(req) {
         const { targetId } = await this.resolveWindow(req);
-        const conn = await this.getConnection(req, targetId);
+        const conn = await this.getPageSession(req, targetId);
         const snapFilter = argStr(req.args, 'filter');
         const snapDepth = argNum(req.args, 'depth');
-        // DOM section
+        const snapScale = argNum(req.args, 'scale');
         const nodes = await conn.getAccessibilityTree();
         const { text: domText, refs, nextRef } = formatAccessibilityTree(nodes, {
             filter: snapFilter,
@@ -420,8 +637,278 @@ export class AgentViewServer {
                 sections.push(`=== Scene ===\n${sceneText}`);
             }
         }
+        if (snapScale !== undefined) {
+            const filepath = await this.captureScreenshotToFile(conn, { scale: snapScale });
+            sections.push(`=== Screenshot ===\n${filepath}`);
+        }
         return { ok: true, data: sections.join('\n\n') };
     }
+    // ── New v0.3.0 commands ────────────────────────────────────────────────────
+    async handleTargets(req) {
+        const targets = await listSupportedTargets(req.port);
+        const typeFilter = argStrArray(req.args, 'types');
+        const filtered = typeFilter && typeFilter.length > 0
+            ? targets.filter(t => typeFilter.includes(t.type))
+            : targets;
+        return { ok: true, data: { runtime: req.runtime, port: req.port, targets: filtered } };
+    }
+    async resolveTarget(req) {
+        const explicitId = argStr(req.args, 'target');
+        const windowArg = argStr(req.args, 'window');
+        const allTargets = await listSupportedTargets(req.port);
+        if (explicitId) {
+            const found = findTargetByIdOrSubstring(allTargets, explicitId);
+            if (found)
+                return found;
+            throw new Error(`Target not found: "${explicitId}". Run \`agent-view targets\` for the full list.`);
+        }
+        if (windowArg) {
+            const pages = allTargets.filter(t => t.type === TargetType.Page);
+            const byId = pages.find(t => t.id === windowArg);
+            const byTitle = pages.find(t => t.title.toLowerCase().includes(windowArg.toLowerCase()));
+            const found = byId ?? byTitle;
+            if (!found) {
+                throw new Error(`Window not found: "${windowArg}".`);
+            }
+            return found;
+        }
+        const firstPage = allTargets.find(t => t.type === TargetType.Page);
+        if (!firstPage)
+            throw new Error('No page targets found.');
+        return firstPage;
+    }
+    async handleEval(req) {
+        const cwd = argStr(req.args, 'cwd');
+        if (!cwd) {
+            return { ok: false, error: 'eval requires cwd to validate allowEval policy' };
+        }
+        const config = readConfig(resolve(cwd));
+        if (!config?.allowEval) {
+            return {
+                ok: false,
+                error: 'eval is disabled. Set "allowEval": true in agent-view.config.json to enable.',
+            };
+        }
+        const expression = argStr(req.args, 'expression');
+        if (!expression)
+            return { ok: false, error: 'eval requires --expression' };
+        const target = await this.resolveTarget(req);
+        if (!RUNTIME_ONLY_TARGETS.has(target.type) && target.type !== TargetType.Page && target.type !== TargetType.Iframe) {
+            return { ok: false, error: `Target type "${target.type}" does not support eval.` };
+        }
+        const session = await this.getRuntimeSession(req, target);
+        const awaitPromise = argBool(req.args, 'await') ?? false;
+        const asJson = argBool(req.args, 'json') ?? false;
+        try {
+            const value = await session.evaluate(expression, { awaitPromise });
+            const formatted = asJson ? safeJSONStringify(value) : formatEvalValue(value);
+            const capped = formatted.length > EVAL_OUTPUT_CAP
+                ? `${formatted.slice(0, EVAL_OUTPUT_CAP)}\n... <${formatted.length - EVAL_OUTPUT_CAP} more bytes truncated>`
+                : formatted;
+            return { ok: true, data: { target: { id: target.id, type: target.type }, result: capped } };
+        }
+        catch (err) {
+            if (err instanceof EvaluationError) {
+                return { ok: false, error: err.message + (err.stack ? `\n${err.stack}` : '') };
+            }
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    async handleWatchStreaming(req, socket) {
+        const writeFrame = (frame) => {
+            if (socket.writableEnded || socket.destroyed)
+                return false;
+            return socket.write(JSON.stringify(frame) + DELIMITER);
+        };
+        const writeError = (msg) => {
+            if (!socket.writableEnded && !socket.destroyed) {
+                socket.end(JSON.stringify({ ok: false, error: msg }) + DELIMITER);
+            }
+        };
+        const cwd = argStr(req.args, 'cwd');
+        if (!cwd)
+            return writeError('watch requires cwd to validate allowEval policy');
+        const config = readConfig(resolve(cwd));
+        if (!config?.allowEval) {
+            return writeError('watch is disabled. Set "allowEval": true in agent-view.config.json to enable.');
+        }
+        const expression = argStr(req.args, 'expression');
+        if (!expression)
+            return writeError('watch requires --expression');
+        const intervalRaw = argNum(req.args, 'intervalMs') ?? 250;
+        const intervalMs = Math.max(WATCH_MIN_INTERVAL_MS, intervalRaw);
+        const durationS = argNum(req.args, 'durationS') ?? 30;
+        const maxChanges = argNum(req.args, 'maxChanges') ?? 10;
+        const until = argStr(req.args, 'until');
+        if (maxChanges <= 0)
+            return writeError('--max-changes must be > 0');
+        if (durationS <= 0)
+            return writeError('--duration must be > 0');
+        let target;
+        try {
+            target = await this.resolveTarget(req);
+        }
+        catch (err) {
+            return writeError(err instanceof Error ? err.message : String(err));
+        }
+        if (!RUNTIME_ONLY_TARGETS.has(target.type) && target.type !== TargetType.Page && target.type !== TargetType.Iframe) {
+            return writeError(`Target type "${target.type}" does not support watch.`);
+        }
+        let session;
+        try {
+            session = await this.getRuntimeSession(req, target);
+        }
+        catch (err) {
+            return writeError(err instanceof Error ? err.message : String(err));
+        }
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        const watch = new WatchSession(session, {
+            expression,
+            intervalMs,
+            durationS,
+            maxChanges,
+            until,
+            emit: writeFrame,
+        });
+        this.activeWatches.add(watch);
+        const cleanup = () => {
+            if (!this.activeWatches.has(watch))
+                return;
+            this.activeWatches.delete(watch);
+            if (!socket.writableEnded && !socket.destroyed)
+                socket.end();
+            if (this.activeWatches.size === 0)
+                this.resetIdleTimer();
+        };
+        watch.onStop(cleanup);
+        socket.on('close', () => {
+            // Client closed (e.g. SIGINT). Stop watch with sigint reason if not already stopped.
+            watch.stop(StopReason.Sigint, true);
+        });
+        socket.on('error', () => {
+            watch.stop(StopReason.Sigint, true);
+        });
+        try {
+            await watch.start();
+        }
+        catch (err) {
+            writeFrame({ type: 'error', ts: new Date().toISOString(), message: err instanceof Error ? err.message : String(err) });
+            watch.stop(StopReason.EvalFailed, false);
+        }
+    }
+    async handleConsole(req) {
+        const cwd = argStr(req.args, 'cwd');
+        const config = cwd ? readConfig(resolve(cwd)) : null;
+        const bufferSize = config?.consoleBufferSize ?? 500;
+        if (this.consoleStream.attachedCount === 0) {
+            // Recreate with config-tuned capacity on first attach
+            this.consoleStream = new ConsoleStream({ capacity: bufferSize });
+        }
+        const targetQuery = argStr(req.args, 'target');
+        // Fuzzy-resolve the target query once (id exact → title substring → url substring)
+        const all = await listSupportedTargets(req.port);
+        let resolvedTargetId;
+        if (targetQuery) {
+            const resolved = findTargetByIdOrSubstring(all, targetQuery);
+            if (!resolved) {
+                return { ok: false, error: `Target not found: "${targetQuery}". Run \`agent-view targets\` for the full list.` };
+            }
+            resolvedTargetId = resolved.id;
+        }
+        if (argBool(req.args, 'clear')) {
+            this.consoleStream.clear(resolvedTargetId);
+            return { ok: true, data: 'Console buffer cleared' };
+        }
+        const requestedTypes = argStrArray(req.args, 'consoleTargets')
+            ?? config?.consoleTargets
+            ?? DEFAULT_CONSOLE_TARGETS;
+        const allowedTypes = new Set(requestedTypes
+            .filter((t) => typeof t === 'string')
+            .filter((t) => Object.values(TargetType).includes(t)));
+        // Lazy attach: ensure every matching target has a session
+        if (process.env.AV_DEBUG_CONSOLE) {
+            // eslint-disable-next-line no-console
+            console.error(`[av-debug] handleConsole: targets=${all.length} explicit=${resolvedTargetId ?? 'none'} types=${[...allowedTypes].join(',')}`);
+        }
+        for (const t of all) {
+            if (resolvedTargetId && t.id !== resolvedTargetId)
+                continue;
+            if (!resolvedTargetId && !allowedTypes.has(t.type))
+                continue;
+            if (!RUNTIME_ONLY_TARGETS.has(t.type) && t.type !== TargetType.Page && t.type !== TargetType.Iframe)
+                continue;
+            try {
+                const session = await this.getRuntimeSession(req, t);
+                this.consoleStream.attach(session);
+                if (process.env.AV_DEBUG_CONSOLE) {
+                    // eslint-disable-next-line no-console
+                    console.error(`[av-debug] handleConsole: attached ${t.type}:${t.id.slice(0, 8)} (stream now has ${this.consoleStream.attachedCount})`);
+                }
+            }
+            catch (err) {
+                if (process.env.AV_DEBUG_CONSOLE) {
+                    // eslint-disable-next-line no-console
+                    console.error(`[av-debug] handleConsole: SKIP ${t.type}:${t.id.slice(0, 8)} — ${err.message}`);
+                }
+            }
+        }
+        const levelFilter = parseLevelFilter(argStrArray(req.args, 'levels'));
+        const since = argNum(req.args, 'since');
+        const follow = argBool(req.args, 'follow') ?? false;
+        const untilPattern = argStr(req.args, 'until');
+        if (untilPattern && !follow) {
+            return { ok: false, error: '--until requires --follow' };
+        }
+        if (follow) {
+            const timeoutSec = argNum(req.args, 'timeout') ?? 10;
+            const collected = this.consoleStream.drain({
+                since,
+                level: levelFilter,
+                targetId: resolvedTargetId,
+            });
+            const seenAt = collected.length > 0 ? collected[collected.length - 1].ts : (since ?? Date.now());
+            const matcher = untilPattern ? buildMatcher(untilPattern) : null;
+            // Check if pattern already matched in buffered messages
+            const earlyMatch = matcher ? collected.findIndex(m => matcher(m.text)) : -1;
+            if (earlyMatch !== -1) {
+                return { ok: true, data: formatConsoleMessages(collected.slice(0, earlyMatch + 1)) };
+            }
+            const timedOut = await new Promise((resolveFollow) => {
+                const dispose = this.consoleStream.subscribe((msg) => {
+                    if (resolvedTargetId && msg.targetId !== resolvedTargetId)
+                        return;
+                    if (levelFilter && !levelFilter.has(msg.level))
+                        return;
+                    if (msg.ts <= seenAt)
+                        return;
+                    collected.push(msg);
+                    if (matcher && matcher(msg.text)) {
+                        clearTimeout(timer);
+                        dispose();
+                        resolveFollow(false);
+                    }
+                });
+                const timer = setTimeout(() => {
+                    dispose();
+                    resolveFollow(true);
+                }, timeoutSec * 1000);
+                timer.unref?.();
+            });
+            if (timedOut && matcher) {
+                return { ok: false, error: `Timeout: pattern not seen in ${timeoutSec}s` };
+            }
+            return { ok: true, data: formatConsoleMessages(collected) };
+        }
+        const messages = this.consoleStream.drain({
+            since,
+            level: levelFilter,
+            targetId: resolvedTargetId,
+        });
+        return { ok: true, data: formatConsoleMessages(messages) };
+    }
     async handleStop() {
         setTimeout(() => this.shutdown(), 100);
         return { ok: true, data: 'Server stopping' };
@@ -429,10 +916,14 @@ export class AgentViewServer {
     async shutdown() {
         if (this.idleTimer)
             clearTimeout(this.idleTimer);
+        for (const watch of [...this.activeWatches]) {
+            watch.stop(StopReason.ServerShutdown, false);
+        }
         await unlink(TOKEN_PATH).catch(() => { });
-        for (const conn of this.connections.values()) {
+        this.consoleStream.detach();
+        for (const cached of this.connections.values()) {
             try {
-                await conn.close();
+                await cached.session.close();
             }
             catch { /* ignore */ }
         }
@@ -441,4 +932,66 @@ export class AgentViewServer {
         process.exit(0);
     }
 }
+// ── helpers ──────────────────────────────────────────────────────────────────
+export function findTargetByIdOrSubstring(targets, query) {
+    const byId = targets.find(t => t.id === query);
+    if (byId)
+        return byId;
+    const q = query.toLowerCase();
+    return targets.find(t => t.title.toLowerCase().includes(q) || t.url.toLowerCase().includes(q)) ?? null;
+}
+function parseMouseButton(value) {
+    if (!value)
+        return undefined;
+    const valid = Object.values(MouseButton);
+    return valid.includes(value) ? value : undefined;
+}
+function parseLevelFilter(levels) {
+    if (!levels || levels.length === 0)
+        return undefined;
+    const valid = Object.values(ConsoleLevel);
+    const set = new Set();
+    for (const l of levels) {
+        if (valid.includes(l))
+            set.add(l);
+    }
+    return set.size > 0 ? set : undefined;
+}
+function buildMatcher(pattern) {
+    const regexMatch = /^\/(.+)\/([gimsuy]*)$/.exec(pattern);
+    if (regexMatch) {
+        const re = new RegExp(regexMatch[1], regexMatch[2]);
+        return (text) => re.test(text);
+    }
+    return (text) => text.includes(pattern);
+}
+function formatConsoleMessages(msgs) {
+    if (msgs.length === 0)
+        return '(no console messages)';
+    return msgs.map(formatOneConsoleMessage).join('\n');
+}
+function formatOneConsoleMessage(msg) {
+    const time = new Date(msg.ts).toISOString().slice(11, 23);
+    const head = `[${time}] [${msg.level}] [${msg.targetType}:${msg.targetId.slice(0, 8)}] ${msg.text}`;
+    return msg.stack ? `${head}\n${msg.stack}` : head;
+}
+function safeJSONStringify(value) {
+    try {
+        return JSON.stringify(value, null, 2) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function formatEvalValue(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return safeJSONStringify(value);
+}
 //# sourceMappingURL=server.js.map