@jshookmcp/jshook 0.2.6 → 0.2.8

package/dist/src/server/domains/streaming/handlers.impl.streaming-ws.js

@@ -1,327 +0,0 @@
-import { logger } from '../../../utils/logger.js';
-import { RingBuffer } from '../../../utils/RingBuffer.js';
-import { StreamingToolHandlersBase } from '../../domains/streaming/handlers.impl.streaming-base.js';
-import { WS_PAYLOAD_PREVIEW_LIMIT, WS_PAYLOAD_SAMPLE_LIMIT } from '../../../constants.js';
-const asRecord = (value) => typeof value === 'object' && value !== null ? value : undefined;
-const getStringField = (value, key) => {
-    const field = asRecord(value)?.[key];
-    return typeof field === 'string' ? field : undefined;
-};
-const getNumberField = (value, key) => {
-    const field = asRecord(value)?.[key];
-    return typeof field === 'number' ? field : undefined;
-};
-const getRecordField = (value, key) => {
-    const nested = asRecord(value)?.[key];
-    return asRecord(nested);
-};
-export class StreamingToolHandlersWs extends StreamingToolHandlersBase {
-    async teardownWsSession() {
-        if (this.wsSession && this.wsListeners) {
-            try {
-                this.wsSession.off('Network.webSocketCreated', this.wsListeners.created);
-            }
-            catch (e) {
-                logger.debug('[ws-teardown] Failed to remove webSocketCreated listener', e);
-            }
-            try {
-                this.wsSession.off('Network.webSocketClosed', this.wsListeners.closed);
-            }
-            catch (e) {
-                logger.debug('[ws-teardown] Failed to remove webSocketClosed listener', e);
-            }
-            try {
-                this.wsSession.off('Network.webSocketHandshakeResponseReceived', this.wsListeners.handshake);
-            }
-            catch (e) {
-                logger.debug('[ws-teardown] Failed to remove handshakeResponseReceived listener', e);
-            }
-            try {
-                this.wsSession.off('Network.webSocketFrameSent', this.wsListeners.frameSent);
-            }
-            catch (e) {
-                logger.debug('[ws-teardown] Failed to remove webSocketFrameSent listener', e);
-            }
-            try {
-                this.wsSession.off('Network.webSocketFrameReceived', this.wsListeners.frameReceived);
-            }
-            catch (e) {
-                logger.debug('[ws-teardown] Failed to remove webSocketFrameReceived listener', e);
-            }
-        }
-        if (this.wsSession) {
-            try {
-                await this.wsSession.detach();
-            }
-            catch (e) {
-                logger.debug('[ws-teardown] Failed to detach CDP session', e);
-            }
-        }
-        this.wsSession = null;
-        this.wsListeners = null;
-    }
-    handleWsFrame(direction, params) {
-        const requestId = getStringField(params, 'requestId');
-        if (!requestId) {
-            return;
-        }
-        const tracked = this.wsConnections.get(requestId);
-        if (!tracked) {
-            if (this.wsConfig.urlFilter) {
-                return;
-            }
-            this.wsConnections.set(requestId, {
-                requestId,
-                url: 'unknown',
-                status: 'open',
-                framesCount: 0,
-                createdTimestamp: Date.now() / 1000,
-            });
-        }
-        const connection = this.wsConnections.get(requestId);
-        if (!connection) {
-            return;
-        }
-        if (this.wsConfig.urlFilter &&
-            connection.url !== 'unknown' &&
-            !this.wsConfig.urlFilter.test(connection.url)) {
-            return;
-        }
-        const response = getRecordField(params, 'response');
-        const opcode = getNumberField(response, 'opcode') ?? -1;
-        const payloadData = getStringField(response, 'payloadData') ?? '';
-        const payloadPreviewLimit = WS_PAYLOAD_PREVIEW_LIMIT;
-        const payloadSampleLimit = WS_PAYLOAD_SAMPLE_LIMIT;
-        const payloadPreview = payloadData.length > payloadPreviewLimit
-            ? `${payloadData.slice(0, payloadPreviewLimit)}…`
-            : payloadData;
-        const payloadSample = payloadData.length > payloadSampleLimit
-            ? payloadData.slice(0, payloadSampleLimit)
-            : payloadData;
-        const timestamp = getNumberField(params, 'timestamp') ?? Date.now() / 1000;
-        const frame = {
-            requestId,
-            timestamp,
-            direction,
-            opcode,
-            payloadLength: payloadData.length,
-            payloadPreview,
-            payloadSample,
-            isBinary: opcode === 2,
-        };
-        this.appendWsFrame(requestId, frame);
-    }
-    async handleWsMonitorEnable(args) {
-        const maxFrames = this.parseNumberArg(args.maxFrames, {
-            defaultValue: 1000,
-            min: 1,
-            max: 20000,
-            integer: true,
-        });
-        const urlFilterRaw = this.parseOptionalStringArg(args.urlFilter);
-        let urlFilter;
-        if (urlFilterRaw) {
-            const compiled = this.compileRegex(urlFilterRaw);
-            if (compiled.error) {
-                return this.asJson({
-                    success: false,
-                    error: `Invalid urlFilter regex: ${compiled.error}`,
-                });
-            }
-            urlFilter = compiled.regex;
-        }
-        await this.teardownWsSession();
-        this.wsFramesByRequest.clear();
-        this.wsFrameOrder = new RingBuffer(maxFrames);
-        this.wsConnections.clear();
-        const page = await this.collector.getActivePage();
-        const session = (await page.createCDPSession());
-        await session.send('Network.enable');
-        const listeners = {
-            created: (params) => {
-                const requestId = getStringField(params, 'requestId');
-                const url = getStringField(params, 'url');
-                if (!requestId || !url) {
-                    return;
-                }
-                if (urlFilter && !urlFilter.test(url)) {
-                    return;
-                }
-                const existing = this.wsConnections.get(requestId);
-                this.wsConnections.set(requestId, {
-                    requestId,
-                    url,
-                    status: existing?.status ?? 'connecting',
-                    framesCount: existing?.framesCount ?? 0,
-                    createdTimestamp: existing?.createdTimestamp ?? Date.now() / 1000,
-                    closedTimestamp: existing?.closedTimestamp,
-                    handshakeStatus: existing?.handshakeStatus,
-                });
-            },
-            closed: (params) => {
-                const requestId = getStringField(params, 'requestId');
-                if (!requestId) {
-                    return;
-                }
-                const connection = this.wsConnections.get(requestId);
-                if (!connection) {
-                    return;
-                }
-                connection.status = 'closed';
-                const timestamp = getNumberField(params, 'timestamp');
-                if (timestamp !== undefined) {
-                    connection.closedTimestamp = timestamp;
-                }
-                else {
-                    connection.closedTimestamp = Date.now() / 1000;
-                }
-            },
-            handshake: (params) => {
-                const requestId = getStringField(params, 'requestId');
-                if (!requestId) {
-                    return;
-                }
-                const connection = this.wsConnections.get(requestId);
-                if (!connection) {
-                    return;
-                }
-                const status = getNumberField(getRecordField(params, 'response'), 'status');
-                if (status !== undefined) {
-                    connection.handshakeStatus = status;
-                    connection.status = status >= 100 && status < 400 ? 'open' : 'error';
-                }
-            },
-            frameSent: (params) => {
-                this.handleWsFrame('sent', params);
-            },
-            frameReceived: (params) => {
-                this.handleWsFrame('received', params);
-            },
-        };
-        session.on('Network.webSocketCreated', listeners.created);
-        session.on('Network.webSocketClosed', listeners.closed);
-        session.on('Network.webSocketHandshakeResponseReceived', listeners.handshake);
-        session.on('Network.webSocketFrameSent', listeners.frameSent);
-        session.on('Network.webSocketFrameReceived', listeners.frameReceived);
-        this.wsSession = session;
-        this.wsListeners = listeners;
-        this.wsConfig = {
-            enabled: true,
-            maxFrames,
-            urlFilterRaw,
-            urlFilter,
-        };
-        return this.asJson({
-            success: true,
-            message: 'WebSocket monitor enabled',
-            config: {
-                maxFrames,
-                urlFilter: urlFilterRaw ?? null,
-            },
-            stats: {
-                trackedConnections: this.wsConnections.size,
-                capturedFrames: this.wsFrameOrder.length,
-            },
-        });
-    }
-    async handleWsMonitorDisable(_args) {
-        const stats = this.getWsFrameStats();
-        const connections = Array.from(this.wsConnections.values());
-        const summary = {
-            success: true,
-            message: 'WebSocket monitor disabled',
-            config: {
-                maxFrames: this.wsConfig.maxFrames,
-                urlFilter: this.wsConfig.urlFilterRaw ?? null,
-            },
-            summary: {
-                trackedConnections: connections.length,
-                activeConnections: connections.filter((c) => c.status === 'open' || c.status === 'connecting').length,
-                closedConnections: connections.filter((c) => c.status === 'closed').length,
-                totalFrames: stats.total,
-                sentFrames: stats.sent,
-                receivedFrames: stats.received,
-            },
-        };
-        await this.teardownWsSession();
-        this.wsConfig = {
-            ...this.wsConfig,
-            enabled: false,
-        };
-        return this.asJson(summary);
-    }
-    async handleWsGetFrames(args) {
-        const direction = this.parseWsDirection(args.direction);
-        const limit = this.parseNumberArg(args.limit, {
-            defaultValue: 100,
-            min: 1,
-            max: 5000,
-            integer: true,
-        });
-        const offset = this.parseNumberArg(args.offset, {
-            defaultValue: 0,
-            min: 0,
-            max: Number.MAX_SAFE_INTEGER,
-            integer: true,
-        });
-        const payloadFilterRaw = this.parseOptionalStringArg(args.payloadFilter);
-        let payloadFilter;
-        if (payloadFilterRaw) {
-            const compiled = this.compileRegex(payloadFilterRaw);
-            if (compiled.error) {
-                return this.asJson({
-                    success: false,
-                    error: `Invalid payloadFilter regex: ${compiled.error}`,
-                });
-            }
-            payloadFilter = compiled.regex;
-        }
-        const filtered = this.wsFrameOrder
-            .toArray()
-            .map((entry) => entry.frame)
-            .filter((frame) => (direction === 'all' ? true : frame.direction === direction))
-            .filter((frame) => (payloadFilter ? payloadFilter.test(frame.payloadSample) : true));
-        const pageItems = filtered.slice(offset, offset + limit).map((frame) => ({
-            requestId: frame.requestId,
-            timestamp: frame.timestamp,
-            direction: frame.direction,
-            opcode: frame.opcode,
-            payloadLength: frame.payloadLength,
-            payloadPreview: frame.payloadPreview,
-            isBinary: frame.isBinary,
-        }));
-        return this.asJson({
-            success: true,
-            monitorEnabled: this.wsConfig.enabled,
-            filters: {
-                direction,
-                payloadFilter: payloadFilterRaw ?? null,
-            },
-            page: {
-                offset,
-                limit,
-                returned: pageItems.length,
-                totalAfterFilter: filtered.length,
-                hasMore: offset + pageItems.length < filtered.length,
-                nextOffset: offset + pageItems.length < filtered.length ? offset + pageItems.length : null,
-            },
-            frames: pageItems,
-        });
-    }
-    async handleWsGetConnections(_args) {
-        const connections = Array.from(this.wsConnections.values())
-            .toSorted((a, b) => a.createdTimestamp - b.createdTimestamp)
-            .map((conn) => ({
-            requestId: conn.requestId,
-            url: conn.url,
-            status: conn.status,
-            framesCount: conn.framesCount,
-        }));
-        return this.asJson({
-            success: true,
-            monitorEnabled: this.wsConfig.enabled,
-            total: connections.length,
-            connections,
-        });
-    }
-}

package/dist/src/server/domains/streaming/handlers.js

@@ -1 +0,0 @@
-export { StreamingToolHandlers } from '../../domains/streaming/handlers.impl.core.js';

package/dist/src/server/domains/streaming/index.d.ts

@@ -1,2 +0,0 @@
-export { streamingTools } from '../../domains/streaming/definitions.js';
-export { StreamingToolHandlers } from '../../domains/streaming/handlers.js';

package/dist/src/server/domains/streaming/index.js

@@ -1,2 +0,0 @@
-export { streamingTools } from '../../domains/streaming/definitions.js';
-export { StreamingToolHandlers } from '../../domains/streaming/handlers.js';

package/dist/src/server/domains/streaming/manifest.d.ts

@@ -1,57 +0,0 @@
-import type { MCPServerContext } from '../../domains/shared/registry.js';
-import { StreamingToolHandlers } from '../../domains/streaming/index.js';
-type H = StreamingToolHandlers;
-declare function ensure(ctx: MCPServerContext): H;
-declare const manifest: {
-    kind: "domain-manifest";
-    version: 1;
-    domain: "streaming";
-    depKey: "streamingHandlers";
-    profiles: ("workflow" | "full")[];
-    ensure: typeof ensure;
-    registrations: {
-        tool: {
-            inputSchema: {
-                [x: string]: unknown;
-                type: "object";
-                properties?: {
-                    [x: string]: object;
-                } | undefined;
-                required?: string[] | undefined;
-            };
-            name: string;
-            description?: string | undefined;
-            outputSchema?: {
-                [x: string]: unknown;
-                type: "object";
-                properties?: {
-                    [x: string]: object;
-                } | undefined;
-                required?: string[] | undefined;
-            } | undefined;
-            annotations?: {
-                title?: string | undefined;
-                readOnlyHint?: boolean | undefined;
-                destructiveHint?: boolean | undefined;
-                idempotentHint?: boolean | undefined;
-                openWorldHint?: boolean | undefined;
-            } | undefined;
-            execution?: {
-                taskSupport?: "optional" | "required" | "forbidden" | undefined;
-            } | undefined;
-            _meta?: {
-                [x: string]: unknown;
-            } | undefined;
-            icons?: {
-                src: string;
-                mimeType?: string | undefined;
-                sizes?: string[] | undefined;
-                theme?: "light" | "dark" | undefined;
-            }[] | undefined;
-            title?: string | undefined;
-        };
-        domain: "streaming";
-        bind: (deps: import("../../domains/shared/registry.js").ToolHandlerDeps) => (args: import("../../types.js").ToolArgs) => Promise<unknown>;
-    }[];
-};
-export default manifest;

package/dist/src/server/domains/streaming/manifest.js

@@ -1,42 +0,0 @@
-import { bindByDepKey, ensureBrowserCore, toolLookup } from '../../domains/shared/registry.js';
-import { streamingTools } from '../../domains/streaming/definitions.js';
-import { StreamingToolHandlers } from '../../domains/streaming/index.js';
-const DOMAIN = 'streaming';
-const DEP_KEY = 'streamingHandlers';
-const t = toolLookup(streamingTools);
-const b = (invoke) => bindByDepKey(DEP_KEY, invoke);
-function ensure(ctx) {
-    ensureBrowserCore(ctx);
-    if (!ctx.streamingHandlers)
-        ctx.streamingHandlers = new StreamingToolHandlers(ctx.collector);
-    return ctx.streamingHandlers;
-}
-const manifest = {
-    kind: 'domain-manifest',
-    version: 1,
-    domain: DOMAIN,
-    depKey: DEP_KEY,
-    profiles: ['workflow', 'full'],
-    ensure,
-    registrations: [
-        { tool: t('ws_monitor_enable'), domain: DOMAIN, bind: b((h, a) => h.handleWsMonitorEnable(a)) },
-        {
-            tool: t('ws_monitor_disable'),
-            domain: DOMAIN,
-            bind: b((h, a) => h.handleWsMonitorDisable(a)),
-        },
-        { tool: t('ws_get_frames'), domain: DOMAIN, bind: b((h, a) => h.handleWsGetFrames(a)) },
-        {
-            tool: t('ws_get_connections'),
-            domain: DOMAIN,
-            bind: b((h, a) => h.handleWsGetConnections(a)),
-        },
-        {
-            tool: t('sse_monitor_enable'),
-            domain: DOMAIN,
-            bind: b((h, a) => h.handleSseMonitorEnable(a)),
-        },
-        { tool: t('sse_get_events'), domain: DOMAIN, bind: b((h, a) => h.handleSseGetEvents(a)) },
-    ],
-};
-export default manifest;

package/dist/src/server/domains/trace/TraceSummarizer.d.ts

@@ -1,60 +0,0 @@
-export type SummaryDetail = 'compact' | 'balanced' | 'full';
-export interface TraceEvent {
-    timestamp: number;
-    category: string;
-    eventType: string;
-    data?: unknown;
-    scriptId?: string;
-    lineNumber?: number;
-}
-export interface MemoryDelta {
-    timestamp: number;
-    address: string;
-    oldValue: string;
-    newValue: string;
-    size: number;
-    valueType: string;
-}
-export interface CategorySummary {
-    category: string;
-    count: number;
-    firstTimestamp: number;
-    lastTimestamp: number;
-    topEventTypes: Array<{
-        type: string;
-        count: number;
-    }>;
-}
-export interface KeyMoment {
-    timestamp: number;
-    type: 'breakpoint' | 'network_complete' | 'memory_anomaly' | 'exception' | 'navigation';
-    description: string;
-    data?: unknown;
-}
-export interface TraceSummary {
-    detail: SummaryDetail;
-    totalEvents: number;
-    timeRange: {
-        start: number;
-        end: number;
-        durationMs: number;
-    };
-    categories: CategorySummary[];
-    keyMoments?: KeyMoment[];
-}
-export interface MemorySummary {
-    totalDeltas: number;
-    uniqueAddresses: number;
-    anomalies: Array<{
-        address: string;
-        writeCount: number;
-        description: string;
-    }>;
-    topAddresses: Array<{
-        address: string;
-        writeCount: number;
-    }>;
-}
-export declare function summarizeEvents(events: TraceEvent[], detail?: SummaryDetail): TraceSummary;
-export declare function extractKeyMoments(events: TraceEvent[]): KeyMoment[];
-export declare function summarizeMemoryDeltas(deltas: MemoryDelta[]): MemorySummary;

package/dist/src/server/domains/trace/TraceSummarizer.js

@@ -1,112 +0,0 @@
-export function summarizeEvents(events, detail = 'balanced') {
-    if (events.length === 0) {
-        return {
-            detail,
-            totalEvents: 0,
-            timeRange: { start: 0, end: 0, durationMs: 0 },
-            categories: [],
-            keyMoments: detail !== 'compact' ? [] : undefined,
-        };
-    }
-    const timestamps = events.map((e) => e.timestamp);
-    const start = Math.min(...timestamps);
-    const end = Math.max(...timestamps);
-    const catMap = new Map();
-    for (const event of events) {
-        let cat = catMap.get(event.category);
-        if (!cat) {
-            cat = { count: 0, first: event.timestamp, last: event.timestamp, types: new Map() };
-            catMap.set(event.category, cat);
-        }
-        cat.count++;
-        cat.first = Math.min(cat.first, event.timestamp);
-        cat.last = Math.max(cat.last, event.timestamp);
-        cat.types.set(event.eventType, (cat.types.get(event.eventType) ?? 0) + 1);
-    }
-    const categories = [...catMap.entries()]
-        .toSorted((a, b) => b[1].count - a[1].count)
-        .map(([category, info]) => ({
-        category,
-        count: info.count,
-        firstTimestamp: info.first,
-        lastTimestamp: info.last,
-        topEventTypes: [...info.types.entries()]
-            .toSorted((a, b) => b[1] - a[1])
-            .slice(0, 5)
-            .map(([type, count]) => ({ type, count })),
-    }));
-    const summary = {
-        detail,
-        totalEvents: events.length,
-        timeRange: { start, end, durationMs: end - start },
-        categories,
-    };
-    if (detail === 'balanced' || detail === 'full') {
-        summary.keyMoments = extractKeyMoments(events);
-    }
-    return summary;
-}
-export function extractKeyMoments(events) {
-    const moments = [];
-    for (const event of events) {
-        if (event.eventType === 'Debugger.paused') {
-            moments.push({
-                timestamp: event.timestamp,
-                type: 'breakpoint',
-                description: `Debugger paused${event.scriptId ? ` at script ${event.scriptId}` : ''}${event.lineNumber ? `:${event.lineNumber}` : ''}`,
-                data: event.data,
-            });
-        }
-        else if (event.eventType === 'Network.loadingFinished') {
-            moments.push({
-                timestamp: event.timestamp,
-                type: 'network_complete',
-                description: 'Network request completed',
-                data: event.data,
-            });
-        }
-        else if (event.eventType === 'Runtime.exceptionThrown') {
-            moments.push({
-                timestamp: event.timestamp,
-                type: 'exception',
-                description: 'Runtime exception thrown',
-                data: event.data,
-            });
-        }
-        else if (event.eventType === 'Page.frameNavigated' ||
-            event.eventType === 'Page.navigatedWithinDocument') {
-            moments.push({
-                timestamp: event.timestamp,
-                type: 'navigation',
-                description: 'Page navigation',
-                data: event.data,
-            });
-        }
-    }
-    return moments;
-}
-export function summarizeMemoryDeltas(deltas) {
-    if (deltas.length === 0) {
-        return { totalDeltas: 0, uniqueAddresses: 0, anomalies: [], topAddresses: [] };
-    }
-    const writeMap = new Map();
-    for (const delta of deltas) {
-        writeMap.set(delta.address, (writeMap.get(delta.address) ?? 0) + 1);
-    }
-    const uniqueAddresses = writeMap.size;
-    const totalWrites = deltas.length;
-    const meanWrites = totalWrites / uniqueAddresses;
-    const sorted = [...writeMap.entries()].toSorted((a, b) => b[1] - a[1]);
-    const topAddresses = sorted
-        .slice(0, 10)
-        .map(([address, writeCount]) => ({ address, writeCount }));
-    const anomalyThreshold = meanWrites * 3;
-    const anomalies = sorted
-        .filter(([, count]) => count > anomalyThreshold)
-        .map(([address, writeCount]) => ({
-        address,
-        writeCount,
-        description: `${writeCount} writes (${(writeCount / meanWrites).toFixed(1)}× average)`,
-    }));
-    return { totalDeltas: totalWrites, uniqueAddresses, anomalies, topAddresses };
-}

package/dist/src/server/domains/trace/definitions.d.ts

@@ -1 +0,0 @@
-export { TRACE_TOOLS as traceTools } from '../../domains/trace/definitions.tools.js';

package/dist/src/server/domains/trace/definitions.js

@@ -1 +0,0 @@
-export { TRACE_TOOLS as traceTools } from '../../domains/trace/definitions.tools.js';

package/dist/src/server/domains/trace/definitions.tools.d.ts

@@ -1,2 +0,0 @@
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-export declare const TRACE_TOOLS: Tool[];

package/dist/src/server/domains/trace/definitions.tools.js

@@ -1,53 +0,0 @@
-import { tool } from '../../registry/tool-builder.js';
-export const TRACE_TOOLS = [
-    tool('start_trace_recording')
-        .desc('Start recording CDP events, debugger state, and memory writes into a SQLite trace database.\n\nRecording captures events from:\n- Debugger: breakpoints, pauses, script parsing\n- Runtime: console calls, exceptions\n- Network: requests, responses\n- Page: navigation events\n- EventBus: tool calls, memory scans, browser events\n\nCall stop_trace_recording to end the recording session.\n\nExamples:\nstart_trace_recording()\nstart_trace_recording(cdpDomains=["Debugger", "Network"])')
-        .array('cdpDomains', { type: 'string' }, 'CDP domains to record (default: Debugger, Runtime, Network, Page)')
-        .boolean('recordMemoryDeltas', 'Record memory write deltas', { default: true })
-        .idempotent()
-        .build(),
-    tool('stop_trace_recording')
-        .desc('Stop the active trace recording and finalize the SQLite database.\n\nReturns session summary including:\n- Database file path\n- Total event count\n- Memory delta count\n- Heap snapshot count\n- Recording duration\n\nExamples:\nstop_trace_recording()')
-        .build(),
-    tool('query_trace_sql')
-        .desc('Execute a read-only SQL query against a trace database.\n\nAvailable tables:\n- events(id, timestamp, category, event_type, data, script_id, line_number)\n- memory_deltas(id, timestamp, address, old_value, new_value, size, value_type)\n- heap_snapshots(id, timestamp, snapshot_data, summary)\n- metadata(key, value)\n\nReturns columns, rows, and row count.\n\nExamples:\nquery_trace_sql(sql="SELECT * FROM events WHERE category=\'debugger\' ORDER BY timestamp")\nquery_trace_sql(sql="SELECT address, COUNT(*) as writes FROM memory_deltas GROUP BY address ORDER BY writes DESC LIMIT 10")\nquery_trace_sql(sql="SELECT * FROM events WHERE timestamp BETWEEN 1000 AND 2000", dbPath="artifacts/traces/my-trace.db")')
-        .string('sql', 'SQL query to execute (SELECT only — write operations are rejected)')
-        .string('dbPath', 'Path to trace DB file. Uses the active recording if omitted.')
-        .required('sql')
-        .readOnly()
-        .idempotent()
-        .build(),
-    tool('seek_to_timestamp')
-        .desc('Reconstruct application state at a specific timestamp from a recorded trace.\n\nReturns a structured snapshot including:\n- Events near the timestamp\n- Debugger state (last pause, call stack)\n- Memory state (latest values per address)\n- Network state (completed requests)\n- Nearest heap snapshot\n\nExamples:\nseek_to_timestamp(timestamp=1711000000000)\nseek_to_timestamp(timestamp=1711000000000, windowMs=500)\nseek_to_timestamp(timestamp=1711000000000, dbPath="artifacts/traces/my-trace.db")')
-        .number('timestamp', 'Target timestamp in milliseconds since epoch')
-        .string('dbPath', 'Path to trace DB file. Uses the active recording if omitted.')
-        .number('windowMs', 'Time window around timestamp to include in ms', { default: 100 })
-        .required('timestamp')
-        .readOnly()
-        .idempotent()
-        .build(),
-    tool('diff_heap_snapshots')
-        .desc('Compare two heap snapshots from a trace and return the differences.\n\nShows:\n- New object types (in snapshot 2 but not 1)\n- Deleted object types (in snapshot 1 but not 2)\n- Changed objects (count or size differs)\n- Total size delta\n\nUseful for identifying state changes in obfuscated code.\n\nExamples:\ndiff_heap_snapshots(snapshotId1=1, snapshotId2=2)\ndiff_heap_snapshots(snapshotId1=1, snapshotId2=3, dbPath="artifacts/traces/my-trace.db")')
-        .number('snapshotId1', 'First snapshot ID (earlier)')
-        .number('snapshotId2', 'Second snapshot ID (later)')
-        .string('dbPath', 'Path to trace DB file. Uses the active recording if omitted.')
-        .required('snapshotId1', 'snapshotId2')
-        .readOnly()
-        .idempotent()
-        .build(),
-    tool('export_trace')
-        .desc('Export a trace database to Chrome Trace Event JSON format.\n\nThe resulting file can be loaded in:\n- chrome://tracing\n- Perfetto UI (ui.perfetto.dev)\n\nMaps events to the standard trace event format with name, category, phase, timestamp.\n\nExamples:\nexport_trace()\nexport_trace(dbPath="artifacts/traces/my-trace.db")\nexport_trace(outputPath="my-export.json")')
-        .string('dbPath', 'Path to trace DB file. Uses the active recording if omitted.')
-        .string('outputPath', 'Output JSON file path. Auto-generated if omitted.')
-        .idempotent()
-        .build(),
-    tool('summarize_trace')
-        .desc('Generate a compact, LLM-friendly summary of a trace database.\n\nAvoids sending raw trace data that may exceed context windows. Three detail levels:\n- compact: category aggregation + timeline overview (~10% of raw size)\n- balanced: compact + key moments (breakpoints, exceptions, network completions) [DEFAULT]\n- full: passthrough — returns all events without compression\n\nAlso detects memory anomalies: addresses with significantly more writes than average.\n\nExamples:\nsummarize_trace()\nsummarize_trace(detail="compact")\nsummarize_trace(detail="balanced", dbPath="artifacts/traces/my-trace.db")')
-        .enum('detail', ['compact', 'balanced', 'full'], 'Summary detail level', {
-        default: 'balanced',
-    })
-        .string('dbPath', 'Path to trace DB file. Uses the active recording if omitted.')
-        .readOnly()
-        .idempotent()
-        .build(),
-];