@jshookmcp/jshook 0.2.2 → 0.2.5

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

@@ -1,150 +1,38 @@
+import { tool } from '../../registry/tool-builder.js';
 export const streamingTools = [
-    {
-        name: 'ws_monitor_enable',
-        description: 'Enable WebSocket frame capture via CDP Network events (webSocketFrameSent / webSocketFrameReceived).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                urlFilter: {
-                    type: 'string',
-                    description: 'Optional regex filter for WebSocket URL (only matching connections are tracked).',
-                },
-                maxFrames: {
-                    type: 'number',
-                    description: 'Maximum frames to keep in memory (default: 1000).',
-                    default: 1000,
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'ws_monitor_disable',
-        description: 'Disable WebSocket monitoring and return capture summary.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'ws_get_frames',
-        description: 'Get captured WebSocket frames with pagination and optional payload regex filter.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                direction: {
-                    type: 'string',
-                    enum: ['sent', 'received', 'all'],
-                    description: 'Frame direction filter (default: all).',
-                    default: 'all',
-                },
-                limit: {
-                    type: 'number',
-                    description: 'Maximum frames to return (default: 100, max: 5000).',
-                    default: 100,
-                },
-                offset: {
-                    type: 'number',
-                    description: 'Pagination offset (default: 0).',
-                    default: 0,
-                },
-                payloadFilter: {
-                    type: 'string',
-                    description: 'Optional regex filter applied to frame payload sample.',
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'ws_get_connections',
-        description: 'Get tracked WebSocket connections and frame counts.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'sse_monitor_enable',
-        description: 'Enable SSE monitoring by injecting an EventSource constructor interceptor in page context. Supports persistent mode to survive navigations.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                urlFilter: {
-                    type: 'string',
-                    description: 'Optional regex filter for EventSource URL.',
-                },
-                maxEvents: {
-                    type: 'number',
-                    description: 'Maximum SSE events to keep in memory (default: 2000).',
-                    default: 2000,
-                },
-                persistent: {
-                    type: 'boolean',
-                    description: 'When true, interceptor survives page navigations (uses evaluateOnNewDocument). Default: false.',
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'sse_get_events',
-        description: 'Get captured SSE events with filters and pagination.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                sourceUrl: {
-                    type: 'string',
-                    description: 'Filter by EventSource URL (exact match).',
-                },
-                eventType: {
-                    type: 'string',
-                    description: 'Filter by SSE event type (e.g. "message", custom event name).',
-                },
-                limit: {
-                    type: 'number',
-                    description: 'Maximum events to return (default: 100, max: 5000).',
-                    default: 100,
-                },
-                offset: {
-                    type: 'number',
-                    description: 'Pagination offset (default: 0).',
-                    default: 0,
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
+    tool('ws_monitor_enable')
+        .desc('Enable WebSocket frame capture via CDP Network events')
+        .string('urlFilter', 'Regex filter for WebSocket URL')
+        .number('maxFrames', 'Maximum frames in memory', { default: 1000 })
+        .build(),
+    tool('ws_monitor_disable')
+        .desc('Disable WebSocket monitoring and return capture summary')
+        .destructive()
+        .build(),
+    tool('ws_get_frames')
+        .desc('Get captured WebSocket frames with pagination and payload filter')
+        .enum('direction', ['sent', 'received', 'all'], 'Frame direction filter', { default: 'all' })
+        .number('limit', 'Maximum frames to return', { default: 100 })
+        .number('offset', 'Pagination offset', { default: 0 })
+        .string('payloadFilter', 'Regex filter on frame payload')
+        .readOnly()
+        .build(),
+    tool('ws_get_connections')
+        .desc('Get tracked WebSocket connections and frame counts')
+        .readOnly()
+        .build(),
+    tool('sse_monitor_enable')
+        .desc('Enable SSE monitoring by injecting EventSource interceptor')
+        .string('urlFilter', 'Regex filter for EventSource URL')
+        .number('maxEvents', 'Maximum SSE events in memory', { default: 2000 })
+        .boolean('persistent', 'Survive page navigations via evaluateOnNewDocument')
+        .build(),
+    tool('sse_get_events')
+        .desc('Get captured SSE events with filters and pagination')
+        .string('sourceUrl', 'Filter by EventSource URL')
+        .string('eventType', 'Filter by SSE event type')
+        .number('limit', 'Maximum events', { default: 100 })
+        .number('offset', 'Pagination offset', { default: 0 })
+        .readOnly()
+        .build(),
 ];

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

@@ -1,184 +1,183 @@
 import { StreamingToolHandlersWs } from '../../domains/streaming/handlers.impl.streaming-ws.js';
 import { evaluateWithTimeout, evaluateOnNewDocumentWithTimeout, } from '../../../modules/collector/PageController.js';
-export class StreamingToolHandlersSse extends StreamingToolHandlersWs {
-    async enableSseInterceptor(maxEvents, urlFilterRaw, options) {
-        const page = await this.collector.getActivePage();
-        const injectionFn = (config) => {
-            const globalWindow = window;
-            if (!globalWindow.__jshookSSEMonitor) {
-                globalWindow.__jshookSSEMonitor = {
-                    enabled: true,
-                    patched: false,
-                    maxEvents: config.maxEvents,
-                    urlFilterRaw: config.urlFilterRaw,
-                    events: [],
-                    sources: {},
-                };
-            }
-            const state = globalWindow.__jshookSSEMonitor;
-            state.enabled = true;
-            state.maxEvents = config.maxEvents;
-            state.urlFilterRaw = config.urlFilterRaw;
-            if (state.events.length > state.maxEvents) {
-                state.events = state.events.slice(-state.maxEvents);
-            }
-            const shouldCapture = (sourceUrl) => {
-                if (!state.urlFilterRaw) {
-                    return true;
-                }
-                try {
-                    return new RegExp(state.urlFilterRaw).test(sourceUrl);
-                }
-                catch {
-                    return true;
-                }
-            };
-            const toDataString = (value) => {
-                if (typeof value === 'string') {
-                    return value;
-                }
-                if (value === null || value === undefined) {
-                    return '';
-                }
-                if (typeof value === 'object') {
-                    try {
-                        return JSON.stringify(value);
-                    }
-                    catch {
-                        return '[unserializable]';
-                    }
-                }
-                return String(value);
+function toDataString(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (typeof value === 'object') {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return '[unserializable]';
+        }
+    }
+    return String(value);
+}
+function sseInjectionFn(config) {
+    const globalWindow = window;
+    if (!globalWindow.__jshookSSEMonitor) {
+        globalWindow.__jshookSSEMonitor = {
+            enabled: true,
+            patched: false,
+            maxEvents: config.maxEvents,
+            urlFilterRaw: config.urlFilterRaw,
+            events: [],
+            sources: {},
+        };
+    }
+    const state = globalWindow.__jshookSSEMonitor;
+    state.enabled = true;
+    state.maxEvents = config.maxEvents;
+    state.urlFilterRaw = config.urlFilterRaw;
+    if (state.events.length > state.maxEvents) {
+        state.events = state.events.slice(-state.maxEvents);
+    }
+    const shouldCapture = (sourceUrl) => {
+        if (!state.urlFilterRaw) {
+            return true;
+        }
+        try {
+            return new RegExp(state.urlFilterRaw).test(sourceUrl);
+        }
+        catch {
+            return true;
+        }
+    };
+    const pushEvent = (sourceUrl, eventType, rawData, lastEventId) => {
+        if (!state.enabled || !shouldCapture(sourceUrl)) {
+            return;
+        }
+        const dataString = toDataString(rawData);
+        const preview = dataString.length > 200 ? `${dataString.slice(0, 200)}…` : dataString;
+        const record = {
+            sourceUrl,
+            eventType,
+            dataPreview: preview,
+            dataLength: dataString.length,
+            lastEventId,
+            timestamp: Date.now(),
+        };
+        state.events.push(record);
+        while (state.events.length > state.maxEvents) {
+            state.events.shift();
+        }
+        const source = state.sources[sourceUrl] ??
+            {
+                url: sourceUrl,
+                status: 'connecting',
+                eventCount: 0,
             };
-            const pushEvent = (sourceUrl, eventType, rawData, lastEventId) => {
-                if (!state.enabled || !shouldCapture(sourceUrl)) {
-                    return;
-                }
-                const dataString = toDataString(rawData);
-                const preview = dataString.length > 200 ? `${dataString.slice(0, 200)}…` : dataString;
-                const record = {
-                    sourceUrl,
-                    eventType,
-                    dataPreview: preview,
-                    dataLength: dataString.length,
-                    lastEventId,
-                    timestamp: Date.now(),
-                };
-                state.events.push(record);
-                while (state.events.length > state.maxEvents) {
-                    state.events.shift();
-                }
+        source.eventCount += 1;
+        source.lastEventTimestamp = record.timestamp;
+        state.sources[sourceUrl] = source;
+    };
+    if (typeof globalWindow.EventSource === 'undefined') {
+        return {
+            success: false,
+            error: 'EventSource is not available in current page context',
+        };
+    }
+    if (!state.patched) {
+        const OriginalEventSource = globalWindow.EventSource;
+        const WrappedEventSource = function (url, eventSourceInitDict) {
+            const sourceUrl = String(url);
+            const es = new OriginalEventSource(url, eventSourceInitDict);
+            if (shouldCapture(sourceUrl)) {
                 const source = state.sources[sourceUrl] ??
                     {
                         url: sourceUrl,
                         status: 'connecting',
                         eventCount: 0,
                     };
-                source.eventCount += 1;
-                source.lastEventTimestamp = record.timestamp;
                 state.sources[sourceUrl] = source;
-            };
-            if (typeof globalWindow.EventSource === 'undefined') {
-                return {
-                    success: false,
-                    error: 'EventSource is not available in current page context',
-                };
             }
-            if (!state.patched) {
-                const OriginalEventSource = globalWindow.EventSource;
-                const WrappedEventSource = function (url, eventSourceInitDict) {
-                    const sourceUrl = String(url);
-                    const es = new OriginalEventSource(url, eventSourceInitDict);
-                    if (shouldCapture(sourceUrl)) {
-                        const source = state.sources[sourceUrl] ??
-                            {
-                                url: sourceUrl,
-                                status: 'connecting',
-                                eventCount: 0,
-                            };
-                        state.sources[sourceUrl] = source;
-                    }
-                    es.addEventListener('open', () => {
-                        const source = state.sources[sourceUrl];
-                        if (source) {
-                            source.status = 'open';
-                        }
-                        pushEvent(sourceUrl, 'open', '', null);
-                    });
-                    es.addEventListener('error', () => {
-                        const source = state.sources[sourceUrl];
-                        if (source) {
-                            source.status = 'error';
-                        }
-                        pushEvent(sourceUrl, 'error', '', null);
-                    });
-                    es.addEventListener('message', (event) => {
-                        const lastEventId = typeof event.lastEventId === 'string' && event.lastEventId.length > 0
-                            ? event.lastEventId
+            es.addEventListener('open', () => {
+                const source = state.sources[sourceUrl];
+                if (source) {
+                    source.status = 'open';
+                }
+                pushEvent(sourceUrl, 'open', '', null);
+            });
+            es.addEventListener('error', () => {
+                const source = state.sources[sourceUrl];
+                if (source) {
+                    source.status = 'error';
+                }
+                pushEvent(sourceUrl, 'error', '', null);
+            });
+            es.addEventListener('message', (event) => {
+                const lastEventId = typeof event.lastEventId === 'string' && event.lastEventId.length > 0
+                    ? event.lastEventId
+                    : null;
+                pushEvent(sourceUrl, event.type || 'message', event.data, lastEventId);
+            });
+            const originalAddEventListener = es.addEventListener.bind(es);
+            const callOriginalAddEventListener = (type, listener, listenerOpts) => {
+                originalAddEventListener(type, listener, listenerOpts);
+            };
+            const wrappedAddEventListener = (type, listener, listenerOpts) => {
+                if (type !== 'message' && type !== 'open' && type !== 'error' && listener) {
+                    const wrapped = (evt) => {
+                        const messageEvent = evt;
+                        const lastEventId = typeof messageEvent.lastEventId === 'string' && messageEvent.lastEventId.length > 0
+                            ? messageEvent.lastEventId
                             : null;
-                        pushEvent(sourceUrl, event.type || 'message', event.data, lastEventId);
-                    });
-                    const originalAddEventListener = es.addEventListener.bind(es);
-                    const callOriginalAddEventListener = (type, listener, options) => {
-                        originalAddEventListener(type, listener, options);
-                    };
-                    const wrappedAddEventListener = (type, listener, options) => {
-                        if (type !== 'message' && type !== 'open' && type !== 'error' && listener) {
-                            const wrapped = (evt) => {
-                                const messageEvent = evt;
-                                const lastEventId = typeof messageEvent.lastEventId === 'string' &&
-                                    messageEvent.lastEventId.length > 0
-                                    ? messageEvent.lastEventId
-                                    : null;
-                                pushEvent(sourceUrl, type, messageEvent.data, lastEventId);
-                                if (typeof listener === 'function') {
-                                    listener.call(es, evt);
-                                }
-                                else {
-                                    listener.handleEvent(evt);
-                                }
-                            };
-                            callOriginalAddEventListener(type, wrapped, options);
-                            return;
+                        pushEvent(sourceUrl, type, messageEvent.data, lastEventId);
+                        if (typeof listener === 'function') {
+                            listener.call(es, evt);
+                        }
+                        else {
+                            listener.handleEvent(evt);
                         }
-                        callOriginalAddEventListener(type, listener, options);
                     };
-                    Object.defineProperty(es, 'addEventListener', {
-                        value: wrappedAddEventListener,
-                        configurable: true,
-                        writable: true,
-                    });
-                    return es;
-                };
-                WrappedEventSource.prototype = OriginalEventSource.prototype;
-                try {
-                    Object.defineProperty(WrappedEventSource, 'CONNECTING', {
-                        value: OriginalEventSource.CONNECTING,
-                    });
-                    Object.defineProperty(WrappedEventSource, 'OPEN', {
-                        value: OriginalEventSource.OPEN,
-                    });
-                    Object.defineProperty(WrappedEventSource, 'CLOSED', {
-                        value: OriginalEventSource.CLOSED,
-                    });
-                }
-                catch {
+                    callOriginalAddEventListener(type, wrapped, listenerOpts);
+                    return;
                 }
-                globalWindow.EventSource = WrappedEventSource;
-                state.originalEventSource = OriginalEventSource;
-                state.patched = true;
-            }
-            return {
-                success: true,
-                message: 'SSE monitor enabled',
-                patched: state.patched,
-                urlFilter: state.urlFilterRaw,
-                maxEvents: state.maxEvents,
-                existingEvents: state.events.length,
+                callOriginalAddEventListener(type, listener, listenerOpts);
             };
+            Object.defineProperty(es, 'addEventListener', {
+                value: wrappedAddEventListener,
+                configurable: true,
+                writable: true,
+            });
+            return es;
         };
+        WrappedEventSource.prototype = OriginalEventSource.prototype;
+        try {
+            Object.defineProperty(WrappedEventSource, 'CONNECTING', {
+                value: OriginalEventSource.CONNECTING,
+            });
+            Object.defineProperty(WrappedEventSource, 'OPEN', {
+                value: OriginalEventSource.OPEN,
+            });
+            Object.defineProperty(WrappedEventSource, 'CLOSED', {
+                value: OriginalEventSource.CLOSED,
+            });
+        }
+        catch {
+        }
+        globalWindow.EventSource = WrappedEventSource;
+        state.originalEventSource = OriginalEventSource;
+        state.patched = true;
+    }
+    return {
+        success: true,
+        message: 'SSE monitor enabled',
+        patched: state.patched,
+        urlFilter: state.urlFilterRaw,
+        maxEvents: state.maxEvents,
+        existingEvents: state.events.length,
+    };
+}
+export class StreamingToolHandlersSse extends StreamingToolHandlersWs {
+    async enableSseInterceptor(maxEvents, urlFilterRaw, options) {
+        const page = await this.collector.getActivePage();
         if (options?.persistent) {
-            await evaluateOnNewDocumentWithTimeout(page, injectionFn, { maxEvents, urlFilterRaw });
+            await evaluateOnNewDocumentWithTimeout(page, sseInjectionFn, { maxEvents, urlFilterRaw });
             return {
                 success: true,
                 message: 'SSE monitor enabled (persistent — survives navigations)',
@@ -188,7 +187,7 @@ export class StreamingToolHandlersSse extends StreamingToolHandlersWs {
                 existingEvents: 0,
             };
         }
-        const result = await evaluateWithTimeout(page, injectionFn, { maxEvents, urlFilterRaw });
+        const result = await evaluateWithTimeout(page, sseInjectionFn, { maxEvents, urlFilterRaw });
         return result;
     }
     async handleSseMonitorEnable(args) {

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

@@ -310,7 +310,7 @@ export class StreamingToolHandlersWs extends StreamingToolHandlersBase {
     }
     async handleWsGetConnections(_args) {
         const connections = Array.from(this.wsConnections.values())
-            .sort((a, b) => a.createdTimestamp - b.createdTimestamp)
+            .toSorted((a, b) => a.createdTimestamp - b.createdTimestamp)
             .map((conn) => ({
             requestId: conn.requestId,
             url: conn.url,

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

@@ -0,0 +1,60 @@
+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;