@jshookmcp/jshook 0.2.1 → 0.2.2

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;
+}

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

@@ -0,0 +1,300 @@
+import { writeFile } from 'node:fs/promises';
+import { TraceDB } from '../../../modules/trace/TraceDB.js';
+import { TraceRecorder } from '../../../modules/trace/TraceRecorder.js';
+import { resolveArtifactPath } from '../../../utils/artifacts.js';
+export class TraceToolHandlers {
+    recorder;
+    ctx;
+    constructor(recorder, ctx) {
+        this.recorder = recorder;
+        this.ctx = ctx;
+    }
+    async handleStartTraceRecording(args) {
+        const cdpDomains = args['cdpDomains'];
+        const recordMemoryDeltas = args['recordMemoryDeltas'];
+        const eventBus = this.ctx.eventBus;
+        if (!eventBus) {
+            throw new Error('EventBus not available on server context');
+        }
+        let cdpSession = null;
+        try {
+            if (this.ctx.collector) {
+                const page = await this.ctx.collector.getActivePage();
+                const pageAny = page;
+                if (typeof pageAny.createCDPSession === 'function') {
+                    cdpSession = await pageAny.createCDPSession();
+                }
+            }
+        }
+        catch {
+        }
+        const session = await this.recorder.start(eventBus, cdpSession, {
+            cdpDomains,
+            recordMemoryDeltas: recordMemoryDeltas ?? true,
+        });
+        return {
+            status: 'recording',
+            sessionId: session.sessionId,
+            dbPath: session.dbPath,
+            message: `Recording started. CDP session: ${cdpSession ? 'active' : 'not available'}`,
+        };
+    }
+    async handleStopTraceRecording() {
+        const session = this.recorder.stop();
+        const duration = session.stoppedAt
+            ? session.stoppedAt - session.startedAt
+            : 0;
+        return {
+            status: 'stopped',
+            sessionId: session.sessionId,
+            dbPath: session.dbPath,
+            eventCount: session.eventCount,
+            memoryDeltaCount: session.memoryDeltaCount,
+            heapSnapshotCount: session.heapSnapshotCount,
+            durationMs: duration,
+            message: `Recording stopped. ${session.eventCount} events, ${session.memoryDeltaCount} memory deltas, ${session.heapSnapshotCount} heap snapshots recorded.`,
+        };
+    }
+    async handleQueryTraceSql(args) {
+        const sql = args['sql'];
+        const dbPath = args['dbPath'];
+        if (!sql) {
+            throw new Error('sql parameter is required');
+        }
+        let result;
+        let tempDb = null;
+        try {
+            if (dbPath) {
+                tempDb = new TraceDB({ dbPath });
+                result = tempDb.query(sql);
+            }
+            else {
+                const activeDb = this.recorder.getDB();
+                if (!activeDb) {
+                    throw new Error('No active recording and no dbPath specified. Start a recording or provide a dbPath.');
+                }
+                activeDb.flush();
+                result = activeDb.query(sql);
+            }
+            return {
+                columns: result.columns,
+                rows: result.rows,
+                rowCount: result.rowCount,
+            };
+        }
+        finally {
+            if (tempDb) {
+                tempDb.close();
+            }
+        }
+    }
+    async handleSeekToTimestamp(args) {
+        const timestamp = args['timestamp'];
+        const dbPath = args['dbPath'];
+        const windowMs = args['windowMs'] ?? 100;
+        if (!timestamp) {
+            throw new Error('timestamp parameter is required');
+        }
+        let tempDb = null;
+        try {
+            const db = this.getDbForReading(dbPath);
+            if (dbPath)
+                tempDb = db;
+            const events = db.getEventsByTimeRange(timestamp - windowMs, timestamp + windowMs);
+            const debuggerEventsResult = db.query(`SELECT * FROM events WHERE category = 'debugger' AND timestamp <= ${timestamp} ORDER BY timestamp DESC LIMIT 5`);
+            const memoryStateResult = db.query(`SELECT m1.* FROM memory_deltas m1
+         INNER JOIN (SELECT address, MAX(timestamp) as max_ts FROM memory_deltas WHERE timestamp <= ${timestamp} GROUP BY address) m2
+         ON m1.address = m2.address AND m1.timestamp = m2.max_ts
+         ORDER BY m1.address`);
+            const networkResult = db.query(`SELECT * FROM events WHERE category = 'network' AND event_type = 'Network.loadingFinished' AND timestamp <= ${timestamp} ORDER BY timestamp DESC LIMIT 20`);
+            const snapshotResult = db.query(`SELECT id, timestamp, summary FROM heap_snapshots WHERE timestamp <= ${timestamp} ORDER BY timestamp DESC LIMIT 1`);
+            return {
+                seekTimestamp: timestamp,
+                windowMs,
+                events: events.map(e => ({
+                    timestamp: e.timestamp,
+                    category: e.category,
+                    eventType: e.eventType,
+                    data: this.safeParseJSON(e.data),
+                    scriptId: e.scriptId,
+                    lineNumber: e.lineNumber,
+                })),
+                debuggerState: {
+                    recentEvents: debuggerEventsResult.rows.map(row => this.rowToObject(debuggerEventsResult.columns, row)),
+                },
+                memoryState: {
+                    addressValues: memoryStateResult.rows.map(row => this.rowToObject(memoryStateResult.columns, row)),
+                },
+                networkState: {
+                    completedRequests: networkResult.rows.map(row => this.rowToObject(networkResult.columns, row)),
+                },
+                nearestHeapSnapshot: snapshotResult.rows.length > 0
+                    ? this.rowToObject(snapshotResult.columns, snapshotResult.rows[0])
+                    : null,
+            };
+        }
+        finally {
+            if (tempDb)
+                tempDb.close();
+        }
+    }
+    async handleDiffHeapSnapshots(args) {
+        const snapshotId1 = args['snapshotId1'];
+        const snapshotId2 = args['snapshotId2'];
+        const dbPath = args['dbPath'];
+        if (!snapshotId1 || !snapshotId2) {
+            throw new Error('snapshotId1 and snapshotId2 are required');
+        }
+        let tempDb = null;
+        try {
+            const db = this.getDbForReading(dbPath);
+            if (dbPath)
+                tempDb = db;
+            const snap1Result = db.query(`SELECT id, timestamp, summary FROM heap_snapshots WHERE id = ${snapshotId1}`);
+            const snap2Result = db.query(`SELECT id, timestamp, summary FROM heap_snapshots WHERE id = ${snapshotId2}`);
+            if (snap1Result.rowCount === 0) {
+                throw new Error(`Snapshot with id ${snapshotId1} not found`);
+            }
+            if (snap2Result.rowCount === 0) {
+                throw new Error(`Snapshot with id ${snapshotId2} not found`);
+            }
+            const snap1Row = this.rowToObject(snap1Result.columns, snap1Result.rows[0]);
+            const snap2Row = this.rowToObject(snap2Result.columns, snap2Result.rows[0]);
+            const summary1 = this.safeParseJSON(snap1Row['summary']);
+            const summary2 = this.safeParseJSON(snap2Row['summary']);
+            const counts1 = (summary1['objectCounts'] ?? {});
+            const counts2 = (summary2['objectCounts'] ?? {});
+            const allKeys = new Set([...Object.keys(counts1), ...Object.keys(counts2)]);
+            const added = [];
+            const removed = [];
+            const changed = [];
+            for (const key of allKeys) {
+                const c1 = counts1[key] ?? 0;
+                const c2 = counts2[key] ?? 0;
+                if (c1 === 0 && c2 > 0) {
+                    added.push({ name: key, count: c2 });
+                }
+                else if (c1 > 0 && c2 === 0) {
+                    removed.push({ name: key, count: c1 });
+                }
+                else if (c1 !== c2) {
+                    changed.push({ name: key, countBefore: c1, countAfter: c2, delta: c2 - c1 });
+                }
+            }
+            changed.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+            const totalSize1 = summary1['totalSize'] ?? 0;
+            const totalSize2 = summary2['totalSize'] ?? 0;
+            return {
+                snapshot1: {
+                    id: snap1Row['id'],
+                    timestamp: snap1Row['timestamp'],
+                    totalSize: totalSize1,
+                    nodeCount: summary1['nodeCount'] ?? 0,
+                },
+                snapshot2: {
+                    id: snap2Row['id'],
+                    timestamp: snap2Row['timestamp'],
+                    totalSize: totalSize2,
+                    nodeCount: summary2['nodeCount'] ?? 0,
+                },
+                diff: {
+                    added: added.slice(0, 50),
+                    removed: removed.slice(0, 50),
+                    changed: changed.slice(0, 100),
+                    totalSizeDelta: totalSize2 - totalSize1,
+                    addedCount: added.length,
+                    removedCount: removed.length,
+                    changedCount: changed.length,
+                },
+            };
+        }
+        finally {
+            if (tempDb)
+                tempDb.close();
+        }
+    }
+    async handleExportTrace(args) {
+        const dbPath = args['dbPath'];
+        const outputPath = args['outputPath'];
+        let tempDb = null;
+        try {
+            const db = this.getDbForReading(dbPath);
+            if (dbPath)
+                tempDb = db;
+            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 ts = row[0] * 1000;
+                const cat = row[1];
+                const name = row[2];
+                const dataStr = row[3];
+                let ph = 'i';
+                if (PAIRED_BEGIN.has(name))
+                    ph = 'B';
+                else if (PAIRED_END.has(name))
+                    ph = 'E';
+                return {
+                    name,
+                    cat,
+                    ph,
+                    ts,
+                    pid: 1,
+                    tid: 1,
+                    args: this.safeParseJSON(dataStr),
+                    ...(ph === 'i' ? { s: 'g' } : {}),
+                };
+            });
+            let finalOutputPath;
+            if (outputPath) {
+                finalOutputPath = outputPath;
+            }
+            else {
+                const { absolutePath } = await resolveArtifactPath({
+                    category: 'traces',
+                    toolName: 'trace_export',
+                    ext: 'json',
+                });
+                finalOutputPath = absolutePath;
+            }
+            const output = JSON.stringify(traceEvents, null, 2);
+            await writeFile(finalOutputPath, output, 'utf-8');
+            return {
+                exportedPath: finalOutputPath,
+                eventCount: traceEvents.length,
+                format: 'Chrome Trace Event JSON',
+                message: `Exported ${traceEvents.length} events to ${finalOutputPath}. Open in chrome://tracing or ui.perfetto.dev`,
+            };
+        }
+        finally {
+            if (tempDb)
+                tempDb.close();
+        }
+    }
+    getDbForReading(dbPath) {
+        if (dbPath) {
+            return new TraceDB({ dbPath });
+        }
+        const activeDb = this.recorder.getDB();
+        if (!activeDb) {
+            throw new Error('No active recording and no dbPath specified. Start a recording or provide a dbPath.');
+        }
+        activeDb.flush();
+        return activeDb;
+    }
+    rowToObject(columns, row) {
+        const obj = {};
+        for (let i = 0; i < columns.length; i++) {
+            obj[columns[i]] = row[i];
+        }
+        return obj;
+    }
+    safeParseJSON(str) {
+        try {
+            return JSON.parse(str);
+        }
+        catch {
+            return str;
+        }
+    }
+}

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

@@ -0,0 +1 @@
+export { TraceToolHandlers } from '../../domains/trace/handlers.js';

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

@@ -0,0 +1 @@
+export { TraceToolHandlers } from '../../domains/trace/handlers.js';

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

@@ -0,0 +1,64 @@
+import type { MCPServerContext } from '../../domains/shared/registry.js';
+import { TraceToolHandlers } from '../../domains/trace/handlers.js';
+type H = TraceToolHandlers;
+declare function ensure(ctx: MCPServerContext): H;
+declare const manifest: {
+    kind: "domain-manifest";
+    version: 1;
+    domain: "trace";
+    depKey: "traceHandlers";
+    profiles: ("workflow" | "full")[];
+    ensure: typeof ensure;
+    prerequisites: {};
+    workflowRule: {
+        patterns: RegExp[];
+        priority: number;
+        tools: string[];
+        hint: string;
+    };
+    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: "trace";
+        bind: (deps: import("../../domains/shared/registry.js").ToolHandlerDeps) => (args: import("../../types.js").ToolArgs) => Promise<unknown>;
+    }[];
+};
+export default manifest;

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

@@ -0,0 +1,48 @@
+import { bindByDepKey, toolLookup } from '../../domains/shared/registry.js';
+import { TRACE_TOOLS } from '../../domains/trace/definitions.tools.js';
+import { TraceToolHandlers } from '../../domains/trace/handlers.js';
+import { TraceRecorder } from '../../../modules/trace/TraceRecorder.js';
+const DOMAIN = 'trace';
+const DEP_KEY = 'traceHandlers';
+const t = toolLookup(TRACE_TOOLS);
+const b = (invoke) => bindByDepKey(DEP_KEY, invoke);
+function ensure(ctx) {
+    if (!ctx.traceRecorder) {
+        ctx.traceRecorder = new TraceRecorder();
+    }
+    if (!ctx.traceHandlers) {
+        ctx.traceHandlers = new TraceToolHandlers(ctx.traceRecorder, ctx);
+    }
+    return ctx.traceHandlers;
+}
+const manifest = {
+    kind: 'domain-manifest',
+    version: 1,
+    domain: DOMAIN,
+    depKey: DEP_KEY,
+    profiles: ['workflow', 'full'],
+    ensure,
+    prerequisites: {},
+    workflowRule: {
+        patterns: [/trace/i, /time.?travel/i, /replay/i, /recorded?\s+events?/i],
+        priority: 70,
+        tools: [
+            'start_trace_recording',
+            'stop_trace_recording',
+            'query_trace_sql',
+            'seek_to_timestamp',
+            'diff_heap_snapshots',
+            'export_trace',
+        ],
+        hint: 'Start recording → perform actions → stop recording → 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('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('export_trace'), domain: DOMAIN, bind: b((h, a) => h.handleExportTrace(a)) },
+    ],
+};
+export default manifest;

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

@@ -31,6 +31,12 @@ export const transformTools = [
             },
             required: ['code', 'transforms'],
         },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
     },
     {
         name: 'ast_transform_chain',
@@ -63,6 +69,12 @@ export const transformTools = [
             },
             required: ['name', 'transforms'],
         },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
     },
     {
         name: 'ast_transform_apply',
@@ -99,6 +111,12 @@ export const transformTools = [
             },
             required: [],
         },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
     },
     {
         name: 'crypto_extract_standalone',
@@ -118,6 +136,12 @@ export const transformTools = [
             },
             required: ['targetFunction'],
         },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
     },
     {
         name: 'crypto_test_harness',
@@ -143,6 +167,12 @@ export const transformTools = [
             },
             required: ['code', 'functionName', 'testInputs'],
         },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
     },
     {
         name: 'crypto_compare',
@@ -172,5 +202,11 @@ export const transformTools = [
             },
             required: ['code1', 'code2', 'functionName', 'testInputs'],
         },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
     },
 ];