@jshookmcp/jshook 0.2.1 → 0.2.3

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;

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

@@ -0,0 +1,109 @@
+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()]
+        .sort((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()]
+            .sort((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()].sort((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

@@ -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,208 @@
+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.',
+                },
+            },
+        },
+    },
+    {
+        name: 'summarize_trace',
+        description: `Generate a compact, LLM-friendly summary of a trace database.
+
+Avoids sending raw trace data that may exceed context windows. Three detail levels:
+- compact: category aggregation + timeline overview (~10% of raw size)
+- balanced: compact + key moments (breakpoints, exceptions, network completions) [DEFAULT]
+- full: passthrough — returns all events without compression
+
+Also detects memory anomalies: addresses with significantly more writes than average.
+
+Examples:
+summarize_trace()
+summarize_trace(detail="compact")
+summarize_trace(detail="balanced", dbPath="artifacts/traces/my-trace.db")`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                detail: {
+                    type: 'string',
+                    enum: ['compact', 'balanced', 'full'],
+                    description: 'Summary detail level (default: balanced)',
+                },
+                dbPath: {
+                    type: 'string',
+                    description: 'Path to trace DB file. Uses the active recording if omitted.',
+                },
+            },
+        },
+    },
+];

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

@@ -0,0 +1,17 @@
+import type { MCPServerContext } from '../../MCPServer.context.js';
+import { type 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;
+    handleSummarizeTrace(args: Record<string, unknown>): Promise<unknown>;
+}