@jshookmcp/jshook 0.2.2 → 0.2.5

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

@@ -0,0 +1,112 @@
+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.tools.js

@@ -1,178 +1,53 @@
+import { tool } from '../../registry/tool-builder.js';
 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.',
-                },
-            },
-        },
-    },
+    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(),
 ];

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

@@ -1,5 +1,5 @@
 import type { MCPServerContext } from '../../MCPServer.context.js';
-import { TraceRecorder } from '../../../modules/trace/TraceRecorder.js';
+import { type TraceRecorder } from '../../../modules/trace/TraceRecorder.js';
 export declare class TraceToolHandlers {
     private readonly recorder;
     private readonly ctx;
@@ -13,4 +13,5 @@ export declare class TraceToolHandlers {
     private getDbForReading;
     private rowToObject;
     private safeParseJSON;
+    handleSummarizeTrace(args: Record<string, unknown>): Promise<unknown>;
 }

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

@@ -1,7 +1,8 @@
 import { writeFile } from 'node:fs/promises';
 import { TraceDB } from '../../../modules/trace/TraceDB.js';
-import { TraceRecorder } from '../../../modules/trace/TraceRecorder.js';
+import {} from '../../../modules/trace/TraceRecorder.js';
 import { resolveArtifactPath } from '../../../utils/artifacts.js';
+import { summarizeEvents, summarizeMemoryDeltas, } from '../../domains/trace/TraceSummarizer.js';
 export class TraceToolHandlers {
     recorder;
     ctx;
@@ -41,9 +42,7 @@ export class TraceToolHandlers {
     }
     async handleStopTraceRecording() {
         const session = this.recorder.stop();
-        const duration = session.stoppedAt
-            ? session.stoppedAt - session.startedAt
-            : 0;
+        const duration = session.stoppedAt ? session.stoppedAt - session.startedAt : 0;
         return {
             status: 'stopped',
             sessionId: session.sessionId,
@@ -111,7 +110,7 @@ export class TraceToolHandlers {
             return {
                 seekTimestamp: timestamp,
                 windowMs,
-                events: events.map(e => ({
+                events: events.map((e) => ({
                     timestamp: e.timestamp,
                     category: e.category,
                     eventType: e.eventType,
@@ -120,13 +119,13 @@ export class TraceToolHandlers {
                     lineNumber: e.lineNumber,
                 })),
                 debuggerState: {
-                    recentEvents: debuggerEventsResult.rows.map(row => this.rowToObject(debuggerEventsResult.columns, row)),
+                    recentEvents: debuggerEventsResult.rows.map((row) => this.rowToObject(debuggerEventsResult.columns, row)),
                 },
                 memoryState: {
-                    addressValues: memoryStateResult.rows.map(row => this.rowToObject(memoryStateResult.columns, row)),
+                    addressValues: memoryStateResult.rows.map((row) => this.rowToObject(memoryStateResult.columns, row)),
                 },
                 networkState: {
-                    completedRequests: networkResult.rows.map(row => this.rowToObject(networkResult.columns, row)),
+                    completedRequests: networkResult.rows.map((row) => this.rowToObject(networkResult.columns, row)),
                 },
                 nearestHeapSnapshot: snapshotResult.rows.length > 0
                     ? this.rowToObject(snapshotResult.columns, snapshotResult.rows[0])
@@ -224,7 +223,7 @@ export class TraceToolHandlers {
             const allEvents = db.query('SELECT timestamp, category, event_type, data, script_id, line_number FROM events ORDER BY timestamp ASC');
             const PAIRED_BEGIN = new Set(['Debugger.paused']);
             const PAIRED_END = new Set(['Debugger.resumed']);
-            const traceEvents = allEvents.rows.map(row => {
+            const traceEvents = allEvents.rows.map((row) => {
                 const ts = row[0] * 1000;
                 const cat = row[1];
                 const name = row[2];
@@ -297,4 +296,58 @@ export class TraceToolHandlers {
             return str;
         }
     }
+    async handleSummarizeTrace(args) {
+        const detail = args['detail'] ?? 'balanced';
+        const dbPath = args['dbPath'];
+        let db;
+        let shouldClose = false;
+        if (dbPath) {
+            db = new TraceDB({ dbPath });
+            shouldClose = true;
+        }
+        else if (this.recorder.getState() === 'recording') {
+            const activeDb = this.recorder.getDB();
+            if (!activeDb)
+                throw new Error('Active recording has no database');
+            db = activeDb;
+        }
+        else {
+            throw new Error('No trace database specified and no active recording');
+        }
+        try {
+            const eventsResult = db.query('SELECT timestamp, category, event_type, data, script_id, line_number FROM events ORDER BY timestamp');
+            const events = eventsResult.rows.map((row) => ({
+                timestamp: row[0],
+                category: row[1],
+                eventType: row[2],
+                data: typeof row[3] === 'string' ? this.safeParseJSON(row[3]) : row[3],
+                scriptId: row[4],
+                lineNumber: row[5],
+            }));
+            const deltasResult = db.query('SELECT timestamp, address, old_value, new_value, size, value_type FROM memory_deltas ORDER BY timestamp');
+            const deltas = deltasResult.rows.map((row) => ({
+                timestamp: row[0],
+                address: row[1],
+                oldValue: row[2],
+                newValue: row[3],
+                size: row[4],
+                valueType: row[5],
+            }));
+            const eventSummary = summarizeEvents(events, detail);
+            const memorySummary = summarizeMemoryDeltas(deltas);
+            return {
+                events: eventSummary,
+                memory: memorySummary,
+                metadata: {
+                    dbPath: dbPath ?? 'active recording',
+                    generatedAt: new Date().toISOString(),
+                },
+            };
+        }
+        finally {
+            if (shouldClose) {
+                db.close();
+            }
+        }
+    }
 }

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

@@ -1 +1,2 @@
-export { TraceToolHandlers } from '../../domains/trace/handlers.js';
+export * from './definitions.tools.js';
+export { TraceToolHandlers } from './handlers.js';

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

@@ -1 +1,2 @@
-export { TraceToolHandlers } from '../../domains/trace/handlers.js';
+export * from './definitions.tools.js';
+export { TraceToolHandlers } from './handlers.js';

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

@@ -33,16 +33,30 @@ const manifest = {
             'seek_to_timestamp',
             'diff_heap_snapshots',
             'export_trace',
+            'summarize_trace',
         ],
-        hint: 'Start recording → perform actions → stop recording → query/seek/diff/export',
+        hint: 'Start recording → perform actions → stop recording → summarize/query/seek/diff/export',
     },
     registrations: [
-        { tool: t('start_trace_recording'), domain: DOMAIN, bind: b((h, a) => h.handleStartTraceRecording(a)) },
-        { tool: t('stop_trace_recording'), domain: DOMAIN, bind: b((h) => h.handleStopTraceRecording()) },
+        {
+            tool: t('start_trace_recording'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleStartTraceRecording(a)),
+        },
+        {
+            tool: t('stop_trace_recording'),
+            domain: DOMAIN,
+            bind: b((h) => h.handleStopTraceRecording()),
+        },
         { tool: t('query_trace_sql'), domain: DOMAIN, bind: b((h, a) => h.handleQueryTraceSql(a)) },
         { tool: t('seek_to_timestamp'), domain: DOMAIN, bind: b((h, a) => h.handleSeekToTimestamp(a)) },
-        { tool: t('diff_heap_snapshots'), domain: DOMAIN, bind: b((h, a) => h.handleDiffHeapSnapshots(a)) },
+        {
+            tool: t('diff_heap_snapshots'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleDiffHeapSnapshots(a)),
+        },
         { tool: t('export_trace'), domain: DOMAIN, bind: b((h, a) => h.handleExportTrace(a)) },
+        { tool: t('summarize_trace'), domain: DOMAIN, bind: b((h, a) => h.handleSummarizeTrace(a)) },
     ],
 };
 export default manifest;