@jshookmcp/jshook 0.2.2 → 0.2.3

package/dist/src/server/domains/graphql/handlers.impl.core.runtime.shared.js

@@ -1,79 +1,79 @@
 export { GRAPHQL_MAX_PREVIEW_CHARS, GRAPHQL_MAX_SCHEMA_CHARS, GRAPHQL_MAX_QUERY_CHARS, GRAPHQL_MAX_GRAPH_NODES, GRAPHQL_MAX_GRAPH_EDGES, } from '../../../constants.js';
-export const INTROSPECTION_QUERY = `
-query IntrospectionQuery {
-  __schema {
-    queryType { name }
-    mutationType { name }
-    subscriptionType { name }
-    types { ...FullType }
-    directives {
-      name
-      description
-      locations
-      args(includeDeprecated: true) { ...InputValue }
-    }
-  }
-}
-fragment FullType on __Type {
-  kind
-  name
-  description
-  fields(includeDeprecated: true) {
-    name
-    description
-    args(includeDeprecated: true) { ...InputValue }
-    type { ...TypeRef }
-    isDeprecated
-    deprecationReason
-  }
-  inputFields(includeDeprecated: true) { ...InputValue }
-  interfaces { ...TypeRef }
-  enumValues(includeDeprecated: true) {
-    name
-    description
-    isDeprecated
-    deprecationReason
-  }
-  possibleTypes { ...TypeRef }
-}
-fragment InputValue on __InputValue {
-  name
-  description
-  type { ...TypeRef }
-  defaultValue
-  isDeprecated
-  deprecationReason
-}
-fragment TypeRef on __Type {
-  kind
-  name
-  ofType {
-    kind
-    name
-    ofType {
-      kind
-      name
-      ofType {
-        kind
-        name
-        ofType {
-          kind
-          name
-          ofType {
-            kind
-            name
-            ofType {
-              kind
-              name
-              ofType {
-                kind
-                name
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
+export const INTROSPECTION_QUERY = `
+query IntrospectionQuery {
+  __schema {
+    queryType { name }
+    mutationType { name }
+    subscriptionType { name }
+    types { ...FullType }
+    directives {
+      name
+      description
+      locations
+      args(includeDeprecated: true) { ...InputValue }
+    }
+  }
+}
+fragment FullType on __Type {
+  kind
+  name
+  description
+  fields(includeDeprecated: true) {
+    name
+    description
+    args(includeDeprecated: true) { ...InputValue }
+    type { ...TypeRef }
+    isDeprecated
+    deprecationReason
+  }
+  inputFields(includeDeprecated: true) { ...InputValue }
+  interfaces { ...TypeRef }
+  enumValues(includeDeprecated: true) {
+    name
+    description
+    isDeprecated
+    deprecationReason
+  }
+  possibleTypes { ...TypeRef }
+}
+fragment InputValue on __InputValue {
+  name
+  description
+  type { ...TypeRef }
+  defaultValue
+  isDeprecated
+  deprecationReason
+}
+fragment TypeRef on __Type {
+  kind
+  name
+  ofType {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+        ofType {
+          kind
+          name
+          ofType {
+            kind
+            name
+            ofType {
+              kind
+              name
+              ofType {
+                kind
+                name
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
 `.trim();

package/dist/src/server/domains/hooks/ai-handlers.js

@@ -125,7 +125,7 @@ export class AIHookToolHandlers {
             const hookId = argStringRequired(args, 'hookId');
             const page = await this.pageController.getPage();
             const hookData = await evaluateWithTimeout(page, (id) => {
-                if (!window.__aiHooks || !window.__aiHooks[id]) {
+                if (!window.__aiHooks?.[id]) {
                     return null;
                 }
                 return {
@@ -222,7 +222,7 @@ export class AIHookToolHandlers {
             const page = await this.pageController.getPage();
             if (hookId) {
                 await evaluateWithTimeout(page, (id) => {
-                    if (window.__aiHooks && window.__aiHooks[id]) {
+                    if (window.__aiHooks?.[id]) {
                         window.__aiHooks[id] = [];
                     }
                 }, hookId);
@@ -280,7 +280,7 @@ export class AIHookToolHandlers {
             const enabled = argBool(args, 'enabled');
             const page = await this.pageController.getPage();
             await evaluateWithTimeout(page, (id, enable) => {
-                if (window.__aiHookMetadata && window.__aiHookMetadata[id]) {
+                if (window.__aiHookMetadata?.[id]) {
                     window.__aiHookMetadata[id].enabled = enable;
                 }
             }, hookId, enabled);

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

@@ -1,5 +1,5 @@
-import { TokenBudgetManager } from '../../../utils/TokenBudgetManager.js';
-import { UnifiedCacheManager } from '../../../utils/UnifiedCacheManager.js';
+import { type TokenBudgetManager } from '../../../utils/TokenBudgetManager.js';
+import { type UnifiedCacheManager } from '../../../utils/UnifiedCacheManager.js';
 import type { ToolResponse } from '../../types.js';
 import { cleanupArtifacts } from '../../../utils/artifactRetention.js';
 import { runEnvironmentDoctor } from '../../../utils/environmentDoctor.js';

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

@@ -1,6 +1,6 @@
 import { logger } from '../../../utils/logger.js';
-import { TokenBudgetManager } from '../../../utils/TokenBudgetManager.js';
-import { UnifiedCacheManager } from '../../../utils/UnifiedCacheManager.js';
+import {} from '../../../utils/TokenBudgetManager.js';
+import {} from '../../../utils/UnifiedCacheManager.js';
 import { asJsonResponse, serializeError } from '../../domains/shared/response.js';
 import { cleanupArtifacts } from '../../../utils/artifactRetention.js';
 import { runEnvironmentDoctor } from '../../../utils/environmentDoctor.js';

package/dist/src/server/domains/platform/handlers/bridge-handlers.d.ts

@@ -1,4 +1,4 @@
-import { ExternalToolRunner } from '../../../domains/shared/modules.js';
+import { type ExternalToolRunner } from '../../../domains/shared/modules.js';
 export declare class BridgeHandlers {
     private runner;
     constructor(runner: ExternalToolRunner);

package/dist/src/server/domains/platform/handlers/bridge-handlers.js

@@ -1,6 +1,6 @@
 import { basename, extname, resolve } from 'node:path';
 import { argStringArray } from '../../../domains/shared/parse-args.js';
-import { ExternalToolRunner } from '../../../domains/shared/modules.js';
+import {} from '../../../domains/shared/modules.js';
 import { toTextResponse, toErrorResponse, parseStringArg, resolveOutputDirectory, checkExternalCommand, } from '../../../domains/platform/handlers/platform-utils.js';
 function generateFridaTemplate(hookType, functionName) {
     const templates = {

package/dist/src/server/domains/platform/handlers/miniapp-handlers.d.ts

@@ -1,5 +1,5 @@
 import type { CodeCollector } from '../../../domains/shared/modules.js';
-import { ExternalToolRunner } from '../../../domains/shared/modules.js';
+import { type ExternalToolRunner } from '../../../domains/shared/modules.js';
 export declare class MiniappHandlers {
     private runner;
     private collector;

package/dist/src/server/domains/platform/handlers/miniapp-handlers.js

@@ -1,6 +1,6 @@
 import { readFile, mkdir, writeFile, stat } from 'node:fs/promises';
 import { basename, dirname, extname, relative, resolve } from 'node:path';
-import { ExternalToolRunner } from '../../../domains/shared/modules.js';
+import {} from '../../../domains/shared/modules.js';
 import { logger } from '../../../../utils/logger.js';
 import { toTextResponse, toErrorResponse, getCollectorState, parseStringArg, isRecord, toStringArray, toDisplayPath, getDefaultSearchPaths, walkDirectory, resolveOutputDirectory, resolveSafeOutputPath, readJsonFileSafe, extractAppIdFromPath, } from '../../../domains/platform/handlers/platform-utils.js';
 function parseMiniappPkgBuffer(buffer) {

package/dist/src/server/domains/process/handlers.impl.core.runtime.inject.js

@@ -297,7 +297,7 @@ export class ProcessToolHandlersRuntime extends ProcessHandlersBase {
                 };
             }
             const target = filtered[0];
-            if (!target || !target.webSocketDebuggerUrl) {
+            if (!target?.webSocketDebuggerUrl) {
                 return {
                     content: [
                         {

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.tools.js

@@ -1,19 +1,19 @@
 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()
+        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',
@@ -32,16 +32,16 @@ start_trace_recording(cdpDomains=["Debugger", "Network"])`,
     },
     {
         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:
+        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',
@@ -50,19 +50,19 @@ stop_trace_recording()`,
     },
     {
         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")
+        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',
@@ -81,18 +81,18 @@ query_trace_sql(sql="SELECT * FROM events WHERE timestamp BETWEEN 1000 AND 2000"
     },
     {
         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)
+        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',
@@ -115,18 +115,18 @@ seek_to_timestamp(timestamp=1711000000000, dbPath="artifacts/traces/my-trace.db"
     },
     {
         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)
+        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',
@@ -149,17 +149,17 @@ diff_heap_snapshots(snapshotId1=1, snapshotId2=3, dbPath="artifacts/traces/my-tr
     },
     {
         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")
+        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',
@@ -175,4 +175,34 @@ export_trace(outputPath="my-export.json")`,
             },
         },
     },
+    {
+        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

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