@jshookmcp/jshook 0.2.0 → 0.2.2

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

@@ -1,7 +1,57 @@
-import type { DomainManifest } from '../../domains/shared/registry.js';
+import type { MCPServerContext } from '../../domains/shared/registry.js';
 import { SourcemapToolHandlers } from '../../domains/sourcemap/index.js';
-declare const DOMAIN: "sourcemap";
-declare const DEP_KEY: "sourcemapHandlers";
 type H = SourcemapToolHandlers;
-declare const manifest: DomainManifest<typeof DEP_KEY, H, typeof DOMAIN>;
+declare function ensure(ctx: MCPServerContext): H;
+declare const manifest: {
+    kind: "domain-manifest";
+    version: 1;
+    domain: "sourcemap";
+    depKey: "sourcemapHandlers";
+    profiles: "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: "sourcemap";
+        bind: (deps: import("../../domains/shared/registry.js").ToolHandlerDeps) => (args: import("../../types.js").ToolArgs) => Promise<unknown>;
+    }[];
+};
 export default manifest;

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

@@ -16,16 +16,38 @@ function ensure(ctx) {
     return ctx.sourcemapHandlers;
 }
 const manifest = {
-    kind: 'domain-manifest', version: 1,
-    domain: DOMAIN, depKey: DEP_KEY,
+    kind: 'domain-manifest',
+    version: 1,
+    domain: DOMAIN,
+    depKey: DEP_KEY,
     profiles: ['full'],
     ensure,
     registrations: [
-        { tool: t('sourcemap_discover'), domain: DOMAIN, bind: b((h, a) => h.handleSourcemapDiscover(a)) },
-        { tool: t('sourcemap_fetch_and_parse'), domain: DOMAIN, bind: b((h, a) => h.handleSourcemapFetchAndParse(a)) },
-        { tool: t('sourcemap_reconstruct_tree'), domain: DOMAIN, bind: b((h, a) => h.handleSourcemapReconstructTree(a)) },
-        { tool: t('extension_list_installed'), domain: DOMAIN, bind: b((h, a) => h.handleExtensionListInstalled(a)) },
-        { tool: t('extension_execute_in_context'), domain: DOMAIN, bind: b((h, a) => h.handleExtensionExecuteInContext(a)) },
+        {
+            tool: t('sourcemap_discover'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleSourcemapDiscover(a)),
+        },
+        {
+            tool: t('sourcemap_fetch_and_parse'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleSourcemapFetchAndParse(a)),
+        },
+        {
+            tool: t('sourcemap_reconstruct_tree'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleSourcemapReconstructTree(a)),
+        },
+        {
+            tool: t('extension_list_installed'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleExtensionListInstalled(a)),
+        },
+        {
+            tool: t('extension_execute_in_context'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleExtensionExecuteInContext(a)),
+        },
     ],
 };
 export default manifest;

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

@@ -16,6 +16,12 @@ export const streamingTools = [
                 },
             },
         },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
     },
     {
         name: 'ws_monitor_disable',
@@ -24,6 +30,12 @@ export const streamingTools = [
             type: 'object',
             properties: {},
         },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
     },
     {
         name: 'ws_get_frames',
@@ -53,6 +65,12 @@ export const streamingTools = [
                 },
             },
         },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
     },
     {
         name: 'ws_get_connections',
@@ -61,10 +79,16 @@ export const streamingTools = [
             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.',
+        description: 'Enable SSE monitoring by injecting an EventSource constructor interceptor in page context. Supports persistent mode to survive navigations.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -77,8 +101,18 @@ export const streamingTools = [
                     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',
@@ -106,5 +140,11 @@ export const streamingTools = [
                 },
             },
         },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
     },
 ];

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

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

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

@@ -1,7 +1,9 @@
 import type { SseEnableResult, TextToolResponse } from '../../domains/streaming/handlers.impl.streaming-base.js';
 import { StreamingToolHandlersWs } from '../../domains/streaming/handlers.impl.streaming-ws.js';
 export declare class StreamingToolHandlersSse extends StreamingToolHandlersWs {
-    protected enableSseInterceptor(maxEvents: number, urlFilterRaw?: string): Promise<SseEnableResult | {
+    protected enableSseInterceptor(maxEvents: number, urlFilterRaw?: string, options?: {
+        persistent?: boolean;
+    }): Promise<SseEnableResult | {
         success: false;
         error: string;
     }>;

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

@@ -1,8 +1,9 @@
 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) {
+    async enableSseInterceptor(maxEvents, urlFilterRaw, options) {
         const page = await this.collector.getActivePage();
-        const result = await page.evaluate((config) => {
+        const injectionFn = (config) => {
             const globalWindow = window;
             if (!globalWindow.__jshookSSEMonitor) {
                 globalWindow.__jshookSSEMonitor = {
@@ -175,7 +176,19 @@ export class StreamingToolHandlersSse extends StreamingToolHandlersWs {
                 maxEvents: state.maxEvents,
                 existingEvents: state.events.length,
             };
-        }, { maxEvents, urlFilterRaw });
+        };
+        if (options?.persistent) {
+            await evaluateOnNewDocumentWithTimeout(page, injectionFn, { maxEvents, urlFilterRaw });
+            return {
+                success: true,
+                message: 'SSE monitor enabled (persistent — survives navigations)',
+                patched: true,
+                urlFilter: urlFilterRaw,
+                maxEvents,
+                existingEvents: 0,
+            };
+        }
+        const result = await evaluateWithTimeout(page, injectionFn, { maxEvents, urlFilterRaw });
         return result;
     }
     async handleSseMonitorEnable(args) {
@@ -195,7 +208,8 @@ export class StreamingToolHandlersSse extends StreamingToolHandlersWs {
                 });
             }
         }
-        const result = await this.enableSseInterceptor(maxEvents, urlFilterRaw);
+        const persistent = args.persistent === true;
+        const result = await this.enableSseInterceptor(maxEvents, urlFilterRaw, { persistent });
         if (!result.success) {
             return this.asJson(result);
         }
@@ -230,7 +244,7 @@ export class StreamingToolHandlersSse extends StreamingToolHandlersWs {
             integer: true,
         });
         const page = await this.collector.getActivePage();
-        const result = await page.evaluate((query) => {
+        const result = await evaluateWithTimeout(page, (query) => {
             const globalWindow = window;
             const state = globalWindow.__jshookSSEMonitor;
             if (!state) {
@@ -260,9 +274,7 @@ export class StreamingToolHandlersSse extends StreamingToolHandlersWs {
                     returned: paged.length,
                     totalAfterFilter,
                     hasMore: query.offset + paged.length < totalAfterFilter,
-                    nextOffset: query.offset + paged.length < totalAfterFilter
-                        ? query.offset + paged.length
-                        : null,
+                    nextOffset: query.offset + paged.length < totalAfterFilter ? query.offset + paged.length : null,
                 },
                 monitor: {
                     enabled: state.enabled,

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

@@ -1,6 +1,7 @@
 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];
@@ -89,8 +90,8 @@ export class StreamingToolHandlersWs extends StreamingToolHandlersBase {
         const response = getRecordField(params, 'response');
         const opcode = getNumberField(response, 'opcode') ?? -1;
         const payloadData = getStringField(response, 'payloadData') ?? '';
-        const payloadPreviewLimit = 200;
-        const payloadSampleLimit = 2000;
+        const payloadPreviewLimit = WS_PAYLOAD_PREVIEW_LIMIT;
+        const payloadSampleLimit = WS_PAYLOAD_SAMPLE_LIMIT;
         const payloadPreview = payloadData.length > payloadPreviewLimit
             ? `${payloadData.slice(0, payloadPreviewLimit)}…`
             : payloadData;
@@ -275,10 +276,11 @@ export class StreamingToolHandlersWs extends StreamingToolHandlersBase {
             }
             payloadFilter = compiled.regex;
         }
-        const filtered = this.wsFrameOrder.toArray()
+        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);
+            .filter((frame) => (payloadFilter ? payloadFilter.test(frame.payloadSample) : true));
         const pageItems = filtered.slice(offset, offset + limit).map((frame) => ({
             requestId: frame.requestId,
             timestamp: frame.timestamp,
@@ -301,9 +303,7 @@ export class StreamingToolHandlersWs extends StreamingToolHandlersBase {
                 returned: pageItems.length,
                 totalAfterFilter: filtered.length,
                 hasMore: offset + pageItems.length < filtered.length,
-                nextOffset: offset + pageItems.length < filtered.length
-                    ? offset + pageItems.length
-                    : null,
+                nextOffset: offset + pageItems.length < filtered.length ? offset + pageItems.length : null,
             },
             frames: pageItems,
         });

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

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

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

@@ -1,7 +1,57 @@
-import type { DomainManifest } from '../../domains/shared/registry.js';
+import type { MCPServerContext } from '../../domains/shared/registry.js';
 import { StreamingToolHandlers } from '../../domains/streaming/index.js';
-declare const DOMAIN: "streaming";
-declare const DEP_KEY: "streamingHandlers";
 type H = StreamingToolHandlers;
-declare const manifest: DomainManifest<typeof DEP_KEY, H, typeof DOMAIN>;
+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

@@ -12,16 +12,30 @@ function ensure(ctx) {
     return ctx.streamingHandlers;
 }
 const manifest = {
-    kind: 'domain-manifest', version: 1,
-    domain: DOMAIN, depKey: DEP_KEY,
+    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_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('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)) },
     ],
 };

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

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

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

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

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

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

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

@@ -0,0 +1,178 @@
+export const TRACE_TOOLS = [
+    {
+        name: 'start_trace_recording',
+        description: `Start recording CDP events, debugger state, and memory writes into a SQLite trace database.
+
+Recording captures events from:
+- Debugger: breakpoints, pauses, script parsing
+- Runtime: console calls, exceptions
+- Network: requests, responses
+- Page: navigation events
+- EventBus: tool calls, memory scans, browser events
+
+Call stop_trace_recording to end the recording session.
+
+Examples:
+start_trace_recording()
+start_trace_recording(cdpDomains=["Debugger", "Network"])`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cdpDomains: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'CDP domains to record (default: Debugger, Runtime, Network, Page)',
+                },
+                recordMemoryDeltas: {
+                    type: 'boolean',
+                    description: 'Record memory write deltas (default: true)',
+                },
+            },
+        },
+    },
+    {
+        name: 'stop_trace_recording',
+        description: `Stop the active trace recording and finalize the SQLite database.
+
+Returns session summary including:
+- Database file path
+- Total event count
+- Memory delta count
+- Heap snapshot count
+- Recording duration
+
+Examples:
+stop_trace_recording()`,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'query_trace_sql',
+        description: `Execute a read-only SQL query against a trace database.
+
+Available tables:
+- events(id, timestamp, category, event_type, data, script_id, line_number)
+- memory_deltas(id, timestamp, address, old_value, new_value, size, value_type)
+- heap_snapshots(id, timestamp, snapshot_data, summary)
+- metadata(key, value)
+
+Returns columns, rows, and row count.
+
+Examples:
+query_trace_sql(sql="SELECT * FROM events WHERE category='debugger' ORDER BY timestamp")
+query_trace_sql(sql="SELECT address, COUNT(*) as writes FROM memory_deltas GROUP BY address ORDER BY writes DESC LIMIT 10")
+query_trace_sql(sql="SELECT * FROM events WHERE timestamp BETWEEN 1000 AND 2000", dbPath="artifacts/traces/my-trace.db")`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sql: {
+                    type: 'string',
+                    description: 'SQL query to execute (SELECT only — write operations are rejected)',
+                },
+                dbPath: {
+                    type: 'string',
+                    description: 'Path to trace DB file. Uses the active recording if omitted.',
+                },
+            },
+            required: ['sql'],
+        },
+    },
+    {
+        name: 'seek_to_timestamp',
+        description: `Reconstruct application state at a specific timestamp from a recorded trace.
+
+Returns a structured snapshot including:
+- Events near the timestamp
+- Debugger state (last pause, call stack)
+- Memory state (latest values per address)
+- Network state (completed requests)
+- Nearest heap snapshot
+
+Examples:
+seek_to_timestamp(timestamp=1711000000000)
+seek_to_timestamp(timestamp=1711000000000, windowMs=500)
+seek_to_timestamp(timestamp=1711000000000, dbPath="artifacts/traces/my-trace.db")`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                timestamp: {
+                    type: 'number',
+                    description: 'Target timestamp in milliseconds since epoch',
+                },
+                dbPath: {
+                    type: 'string',
+                    description: 'Path to trace DB file. Uses the active recording if omitted.',
+                },
+                windowMs: {
+                    type: 'number',
+                    description: 'Time window around timestamp to include in ms (default: 100)',
+                },
+            },
+            required: ['timestamp'],
+        },
+    },
+    {
+        name: 'diff_heap_snapshots',
+        description: `Compare two heap snapshots from a trace and return the differences.
+
+Shows:
+- New object types (in snapshot 2 but not 1)
+- Deleted object types (in snapshot 1 but not 2)
+- Changed objects (count or size differs)
+- Total size delta
+
+Useful for identifying state changes in obfuscated code.
+
+Examples:
+diff_heap_snapshots(snapshotId1=1, snapshotId2=2)
+diff_heap_snapshots(snapshotId1=1, snapshotId2=3, dbPath="artifacts/traces/my-trace.db")`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                snapshotId1: {
+                    type: 'number',
+                    description: 'First snapshot ID (earlier)',
+                },
+                snapshotId2: {
+                    type: 'number',
+                    description: 'Second snapshot ID (later)',
+                },
+                dbPath: {
+                    type: 'string',
+                    description: 'Path to trace DB file. Uses the active recording if omitted.',
+                },
+            },
+            required: ['snapshotId1', 'snapshotId2'],
+        },
+    },
+    {
+        name: 'export_trace',
+        description: `Export a trace database to Chrome Trace Event JSON format.
+
+The resulting file can be loaded in:
+- chrome://tracing
+- Perfetto UI (ui.perfetto.dev)
+
+Maps events to the standard trace event format with name, category, phase, timestamp.
+
+Examples:
+export_trace()
+export_trace(dbPath="artifacts/traces/my-trace.db")
+export_trace(outputPath="my-export.json")`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                dbPath: {
+                    type: 'string',
+                    description: 'Path to trace DB file. Uses the active recording if omitted.',
+                },
+                outputPath: {
+                    type: 'string',
+                    description: 'Output JSON file path. Auto-generated if omitted.',
+                },
+            },
+        },
+    },
+];

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

@@ -0,0 +1,16 @@
+import type { MCPServerContext } from '../../MCPServer.context.js';
+import { TraceRecorder } from '../../../modules/trace/TraceRecorder.js';
+export declare class TraceToolHandlers {
+    private readonly recorder;
+    private readonly ctx;
+    constructor(recorder: TraceRecorder, ctx: MCPServerContext);
+    handleStartTraceRecording(args: Record<string, unknown>): Promise<unknown>;
+    handleStopTraceRecording(): Promise<unknown>;
+    handleQueryTraceSql(args: Record<string, unknown>): Promise<unknown>;
+    handleSeekToTimestamp(args: Record<string, unknown>): Promise<unknown>;
+    handleDiffHeapSnapshots(args: Record<string, unknown>): Promise<unknown>;
+    handleExportTrace(args: Record<string, unknown>): Promise<unknown>;
+    private getDbForReading;
+    private rowToObject;
+    private safeParseJSON;
+}