@petukhovart/agent-view 0.1.0 → 0.3.0

package/dist/server/server.js

@@ -5,14 +5,17 @@ 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 } 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, } 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';
 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 +23,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 +42,91 @@ 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();
+    axTreeCache = new AxTreeCache();
+    consoleStream = new ConsoleStream();
     token = '';
+    handlers = {
+        discover: (req) => this.handleDiscover(req),
+        launch: (req) => this.handleLaunch(req),
+        dom: (req) => this.handleDom(req),
+        click: (req) => this.handleClick(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(),
+    };
+    validCommands = new Set(Object.keys(this.handlers));
     async start() {
         mkdirSync(TOKEN_DIR, { recursive: true });
         this.token = randomBytes(32).toString('hex');
@@ -81,7 +169,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);
@@ -107,30 +195,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 +222,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.`);
+        }
+        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.`);
         }
-        return conn;
+        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 +278,53 @@ export class AgentViewServer {
     }
     async handleDom(req) {
         const { targetId } = await this.resolveWindow(req);
-        const conn = await this.getConnection(req, targetId);
+        const conn = await this.getPageSession(req, targetId);
+        const filter = argStr(req.args, 'filter');
+        const useText = argBool(req.args, 'text') ?? false;
         const nodes = await conn.getAccessibilityTree();
         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(),
         });
         this.refStore.store(refs, req.port, targetId, nextRef);
+        if (useText && filter && text.startsWith('(no matching')) {
+            return { ok: true, data: await textContentFallback(conn, filter) };
+        }
         return { ok: true, data: text };
     }
     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 +333,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 +365,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 +373,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 +404,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 +416,13 @@ 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 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 +436,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 +448,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 +460,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, {
@@ -358,16 +477,19 @@ export class AgentViewServer {
     }
     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`;
+        const conn = await this.getPageSession(req, targetId);
+        const scale = argNum(req.args, 'scale');
+        const opts = scale !== undefined ? { scale } : undefined;
+        const buffer = await conn.captureScreenshot(opts);
+        const ext = scale !== undefined && scale < 1 ? 'jpg' : 'png';
+        const filename = `agent-view-screenshot-${Date.now()}.${ext}`;
         const filepath = join(tmpdir(), filename);
         await writeFile(filepath, buffer);
         return { ok: true, data: filepath };
     }
     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');
@@ -399,10 +521,9 @@ export class AgentViewServer {
     }
     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 nodes = await conn.getAccessibilityTree();
         const { text: domText, refs, nextRef } = formatAccessibilityTree(nodes, {
             filter: snapFilter,
@@ -422,6 +543,165 @@ export class AgentViewServer {
         }
         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 byId = allTargets.find(t => t.id === explicitId);
+            if (byId)
+                return byId;
+            const bySubstr = allTargets.find(t => t.title.toLowerCase().includes(explicitId.toLowerCase())
+                || t.url.toLowerCase().includes(explicitId.toLowerCase()));
+            if (bySubstr)
+                return bySubstr;
+            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 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 });
+        }
+        if (argBool(req.args, 'clear')) {
+            const targetId = argStr(req.args, 'target');
+            this.consoleStream.clear(targetId);
+            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
+        const all = await listSupportedTargets(req.port);
+        const explicitTarget = argStr(req.args, 'target');
+        if (process.env.AV_DEBUG_CONSOLE) {
+            // eslint-disable-next-line no-console
+            console.error(`[av-debug] handleConsole: targets=${all.length} explicit=${explicitTarget ?? 'none'} types=${[...allowedTypes].join(',')}`);
+        }
+        for (const t of all) {
+            if (explicitTarget && t.id !== explicitTarget)
+                continue;
+            if (!explicitTarget && !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;
+        if (follow) {
+            const timeoutSec = argNum(req.args, 'timeout') ?? 10;
+            const collected = this.consoleStream.drain({
+                since,
+                level: levelFilter,
+                targetId: explicitTarget,
+            });
+            const seenAt = collected.length > 0 ? collected[collected.length - 1].ts : (since ?? Date.now());
+            await new Promise((resolveFollow) => {
+                const dispose = this.consoleStream.subscribe((msg) => {
+                    if (explicitTarget && msg.targetId !== explicitTarget)
+                        return;
+                    if (levelFilter && !levelFilter.has(msg.level))
+                        return;
+                    if (msg.ts <= seenAt)
+                        return;
+                    collected.push(msg);
+                });
+                const timer = setTimeout(() => {
+                    dispose();
+                    resolveFollow();
+                }, timeoutSec * 1000);
+                timer.unref?.();
+            });
+            return { ok: true, data: formatConsoleMessages(collected) };
+        }
+        const messages = this.consoleStream.drain({
+            since,
+            level: levelFilter,
+            targetId: explicitTarget,
+        });
+        return { ok: true, data: formatConsoleMessages(messages) };
+    }
     async handleStop() {
         setTimeout(() => this.shutdown(), 100);
         return { ok: true, data: 'Server stopping' };
@@ -430,9 +710,10 @@ export class AgentViewServer {
         if (this.idleTimer)
             clearTimeout(this.idleTimer);
         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 +722,45 @@ export class AgentViewServer {
         process.exit(0);
     }
 }
+// ── helpers ──────────────────────────────────────────────────────────────────
+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 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