@jshookmcp/jshook 0.2.2 → 0.2.5

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

@@ -1,77 +1,11 @@
-import { AIHookGenerator } from '../../domains/shared/modules.js';
-import { evaluateWithTimeout, evaluateOnNewDocumentWithTimeout } from '../../../modules/collector/PageController.js';
+import { evaluateWithTimeout, evaluateOnNewDocumentWithTimeout, } from '../../../modules/collector/PageController.js';
 import { logger } from '../../../utils/logger.js';
 import { argString, argStringRequired, argBool } from '../../domains/shared/parse-args.js';
 export class AIHookToolHandlers {
     pageController;
-    hookGenerator;
     injectedHooks = new Map();
     constructor(pageController) {
         this.pageController = pageController;
-        this.hookGenerator = new AIHookGenerator();
-    }
-    async handleAIHookGenerate(args) {
-        try {
-            let target;
-            if (args.target) {
-                target = args.target;
-            }
-            else {
-                const pattern = argString(args, 'pattern', '');
-                let targetType = 'function';
-                let targetName = pattern;
-                if (pattern === 'fetch' || pattern === 'XMLHttpRequest') {
-                    targetType = 'api';
-                }
-                else if (pattern.includes('.')) {
-                    targetType = 'object-method';
-                    targetName = pattern.split('.').pop() || pattern;
-                }
-                target = { type: targetType, name: targetName };
-            }
-            const request = {
-                description: argString(args, 'description') || `Hook ${target.name || 'target'}`,
-                target,
-                behavior: args.behavior || {
-                    captureArgs: true,
-                    captureReturn: true,
-                    logToConsole: true,
-                },
-                condition: args.condition,
-                customCode: args.customCode,
-            };
-            const response = this.hookGenerator.generateHook(request);
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            success: response.success,
-                            hookId: response.hookId,
-                            generatedCode: response.generatedCode,
-                            explanation: response.explanation,
-                            injectionMethod: response.injectionMethod,
-                            warnings: response.warnings,
-                            usage: ` ai_hook_inject(hookId: "${response.hookId}") Hook`,
-                        }, null, 2),
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            logger.error('AI Hook generation failed', error);
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            success: false,
-                            error: error instanceof Error ? error.message : String(error),
-                        }, null, 2),
-                    },
-                ],
-            };
-        }
     }
     async handleAIHookInject(args) {
         try {
@@ -125,7 +59,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 +156,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 +214,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/hooks/definitions.js

@@ -1,343 +1,77 @@
+import { tool } from '../../registry/tool-builder.js';
 export const aiHookTools = [
-    {
-        name: 'ai_hook_generate',
-        description: 'Generate hook code for a target function, API, or object method.\n\nHook types:\n- function: Hook a named global function (e.g. window.btoa)\n- object-method: Hook a method on an object (e.g. crypto.subtle.encrypt)\n- api: Hook a built-in API (e.g. fetch, XMLHttpRequest)\n- property: Hook a property getter/setter\n- event: Hook an event listener\n- custom: Provide custom hook code\n\nAfter generating, inject the hook with ai_hook_inject.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                description: {
-                    type: 'string',
-                    description: 'What the hook should do (e.g., "Capture all fetch requests to /api")',
-                },
-                target: {
-                    type: 'object',
-                    description: 'Hook target specification',
-                    properties: {
-                        type: {
-                            type: 'string',
-                            enum: ['function', 'object-method', 'api', 'property', 'event', 'custom'],
-                            description: 'Hook type',
-                        },
-                        name: {
-                            type: 'string',
-                            description: 'Function or API name (e.g., "btoa", "fetch")',
-                        },
-                        pattern: {
-                            type: 'string',
-                            description: 'Pattern for matching (used with api type)',
-                        },
-                        object: {
-                            type: 'string',
-                            description: 'Object path (e.g., "window.crypto.subtle")',
-                        },
-                        property: {
-                            type: 'string',
-                            description: 'Property name to hook',
-                        },
-                    },
-                    required: ['type'],
-                },
-                behavior: {
-                    type: 'object',
-                    description: 'Hook behavior configuration',
-                    properties: {
-                        captureArgs: {
-                            type: 'boolean',
-                            description: 'Capture function arguments',
-                            default: true,
-                        },
-                        captureReturn: {
-                            type: 'boolean',
-                            description: 'Capture return value',
-                            default: true,
-                        },
-                        captureStack: {
-                            type: 'boolean',
-                            description: 'Capture call stack',
-                            default: false,
-                        },
-                        modifyArgs: {
-                            type: 'boolean',
-                            description: 'Allow argument modification',
-                            default: false,
-                        },
-                        modifyReturn: {
-                            type: 'boolean',
-                            description: 'Allow return value modification',
-                            default: false,
-                        },
-                        blockExecution: {
-                            type: 'boolean',
-                            description: 'Block the original function from executing',
-                            default: false,
-                        },
-                        logToConsole: {
-                            type: 'boolean',
-                            description: 'Log hook events to console',
-                            default: true,
-                        },
-                    },
-                },
-                condition: {
-                    type: 'object',
-                    description: 'Conditional trigger for the hook',
-                    properties: {
-                        argFilter: {
-                            type: 'string',
-                            description: 'JS expression to filter by args (e.g., "args[0].includes(\'password\')")',
-                        },
-                        returnFilter: {
-                            type: 'string',
-                            description: 'JS expression to filter by return value',
-                        },
-                        urlPattern: {
-                            type: 'string',
-                            description: 'Regex pattern to match request URL',
-                        },
-                        maxCalls: {
-                            type: 'number',
-                            description: 'Stop capturing after this many calls',
-                        },
-                    },
-                },
-                customCode: {
-                    type: 'object',
-                    description: 'Custom code to inject at hook points',
-                    properties: {
-                        before: {
-                            type: 'string',
-                            description: 'Code to run before the original function',
-                        },
-                        after: {
-                            type: 'string',
-                            description: 'Code to run after the original function',
-                        },
-                        replace: {
-                            type: 'string',
-                            description: 'Code to replace the original function entirely',
-                        },
-                    },
-                },
-            },
-            required: ['description', 'target', 'behavior'],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'ai_hook_inject',
-        description: 'Inject a generated hook into the page.\n\nMethods:\n- evaluateOnNewDocument: Runs before page scripts (use for API hooks like fetch/XHR)\n- evaluate: Runs in current page context (use for hooking already-loaded code)',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                hookId: {
-                    type: 'string',
-                    description: 'Hook ID returned by ai_hook_generate',
-                },
-                code: {
-                    type: 'string',
-                    description: 'Hook code returned by ai_hook_generate',
-                },
-                method: {
-                    type: 'string',
-                    enum: ['evaluateOnNewDocument', 'evaluate'],
-                    description: 'Injection method',
-                    default: 'evaluate',
-                },
-            },
-            required: ['hookId', 'code'],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'ai_hook_get_data',
-        description: 'Retrieve captured data from an active hook (arguments, return values, timestamps, call count)',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                hookId: {
-                    type: 'string',
-                    description: 'Hook ID',
-                },
-            },
-            required: ['hookId'],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'ai_hook_list',
-        description: 'List all active hooks with their IDs, types, creation time, and call counts',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'ai_hook_clear',
-        description: 'Remove one hook by ID or clear all hooks and their captured data',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                hookId: {
-                    type: 'string',
-                    description: 'Hook ID to clear (omit to clear all hooks)',
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'ai_hook_toggle',
-        description: 'Enable or disable a hook without removing it',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                hookId: {
-                    type: 'string',
-                    description: 'Hook ID',
-                },
-                enabled: {
-                    type: 'boolean',
-                    description: 'true to enable, false to disable',
-                },
+    tool('ai_hook_inject')
+        .desc('Inject a generated hook into the page.\n\nMethods:\n- evaluateOnNewDocument: Runs before page scripts (use for API hooks like fetch/XHR)\n- evaluate: Runs in current page context (use for hooking already-loaded code)')
+        .string('hookId', 'Hook ID for injection')
+        .string('code', 'Hook code to inject')
+        .enum('method', ['evaluateOnNewDocument', 'evaluate'], 'Injection method', {
+        default: 'evaluate',
+    })
+        .required('hookId', 'code')
+        .build(),
+    tool('ai_hook_get_data')
+        .desc('Retrieve captured data from an active hook (arguments, return values, timestamps, call count)')
+        .string('hookId', 'Hook ID')
+        .required('hookId')
+        .build(),
+    tool('ai_hook_list')
+        .desc('List all active hooks with their IDs, types, creation time, and call counts')
+        .build(),
+    tool('ai_hook_clear')
+        .desc('Remove one hook by ID or clear all hooks and their captured data')
+        .string('hookId', 'Hook ID to clear (omit to clear all hooks)')
+        .build(),
+    tool('ai_hook_toggle')
+        .desc('Enable or disable a hook without removing it')
+        .string('hookId', 'Hook ID')
+        .boolean('enabled', 'true to enable, false to disable')
+        .required('hookId', 'enabled')
+        .build(),
+    tool('ai_hook_export')
+        .desc('Export captured hook data in JSON or CSV format')
+        .string('hookId', 'Hook ID to export (omit to export all hooks)')
+        .enum('format', ['json', 'csv'], 'Export format', { default: 'json' })
+        .build(),
+];
+export const hookPresetTools = [
+    tool('hook_preset')
+        .desc('Install a pre-built JavaScript hook from 20+ built-in presets (eval, atob/btoa, Proxy, Reflect, Object.defineProperty, etc.), or provide customTemplate/customTemplates to install your own reusable hook bodies. Use listPresets=true to see all available preset descriptions.')
+        .string('preset', 'Single preset name to install. Accepts built-in preset ids or ids provided by customTemplate/customTemplates.')
+        .array('presets', { type: 'string' }, 'List of preset names to install simultaneously. Accepts built-in ids and custom template ids.')
+        .prop('customTemplate', {
+        type: 'object',
+        properties: {
+            id: { type: 'string', description: 'Stable preset id, for example deobfuscation-sinks' },
+            description: {
+                type: 'string',
+                description: 'Human-readable description for listPresets output.',
             },
-            required: ['hookId', 'enabled'],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'ai_hook_export',
-        description: 'Export captured hook data in JSON or CSV format',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                hookId: {
-                    type: 'string',
-                    description: 'Hook ID to export (omit to export all hooks)',
-                },
-                format: {
-                    type: 'string',
-                    enum: ['json', 'csv'],
-                    description: 'Export format',
-                    default: 'json',
-                },
+            body: {
+                type: 'string',
+                description: 'Hook body snippet inserted into the preset wrapper.',
             },
         },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-];
-export const hookPresetTools = [
-    {
-        name: 'hook_preset',
-        description: 'Install a pre-built JavaScript hook from 20+ built-in presets (eval, atob/btoa, Proxy, Reflect, Object.defineProperty, etc.), or provide customTemplate/customTemplates to install your own reusable hook bodies. Use listPresets=true to see all available preset descriptions.',
-        inputSchema: {
+        required: ['id', 'body'],
+        description: 'Inline custom template. body should contain the hook body inserted into the standard buildHookCode wrapper. Use {{STACK_CODE}} and {{LOG_FN}} placeholders when needed.',
+    })
+        .prop('customTemplates', {
+        type: 'array',
+        items: {
             type: 'object',
             properties: {
-                preset: {
-                    type: 'string',
-                    description: 'Single preset name to install. Accepts built-in preset ids or ids provided by customTemplate/customTemplates.',
-                },
-                presets: {
-                    type: 'array',
-                    description: 'List of preset names to install simultaneously. Accepts built-in ids and custom template ids.',
-                    items: { type: 'string' },
-                },
-                customTemplate: {
-                    type: 'object',
-                    description: 'Inline custom template. body should contain the hook body inserted into the standard buildHookCode wrapper. Use {{STACK_CODE}} and {{LOG_FN}} placeholders when needed.',
-                    properties: {
-                        id: {
-                            type: 'string',
-                            description: 'Stable preset id, for example deobfuscation-sinks',
-                        },
-                        description: {
-                            type: 'string',
-                            description: 'Human-readable description for listPresets output.',
-                        },
-                        body: {
-                            type: 'string',
-                            description: 'Hook body snippet inserted into the preset wrapper.',
-                        },
-                    },
-                    required: ['id', 'body'],
-                },
-                customTemplates: {
-                    type: 'array',
-                    description: 'List of inline custom templates to register for this invocation.',
-                    items: {
-                        type: 'object',
-                        properties: {
-                            id: { type: 'string' },
-                            description: { type: 'string' },
-                            body: { type: 'string' },
-                        },
-                        required: ['id', 'body'],
-                    },
-                },
-                captureStack: {
-                    type: 'boolean',
-                    description: 'Include call stack in captured data (default: false, has performance impact).',
-                    default: false,
-                },
-                logToConsole: {
-                    type: 'boolean',
-                    description: 'Log hook events to browser console (default: true).',
-                    default: true,
-                },
-                method: {
-                    type: 'string',
-                    enum: ['evaluate', 'evaluateOnNewDocument'],
-                    description: 'Injection method: evaluate=current page, evaluateOnNewDocument=before page scripts (default: evaluate).',
-                    default: 'evaluate',
-                },
-                listPresets: {
-                    type: 'boolean',
-                    description: 'Set to true to list all available presets with descriptions instead of installing.',
-                    default: false,
-                },
+                id: { type: 'string' },
+                description: { type: 'string' },
+                body: { type: 'string' },
             },
-            required: [],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
+            required: ['id', 'body'],
+        },
+        description: 'List of inline custom templates to register for this invocation.',
+    })
+        .boolean('captureStack', 'Include call stack in captured data (has performance impact)', {
+        default: false,
+    })
+        .boolean('logToConsole', 'Log hook events to browser console', { default: true })
+        .enum('method', ['evaluate', 'evaluateOnNewDocument'], 'Injection method: evaluate=current page, evaluateOnNewDocument=before page scripts', { default: 'evaluate' })
+        .boolean('listPresets', 'Set to true to list all available presets with descriptions instead of installing.', { default: false })
+        .build(),
 ];

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

@@ -9,7 +9,7 @@ declare const manifest: {
     domain: "hooks";
     depKey: "aiHookHandlers";
     secondaryDepKeys: string[];
-    profiles: "full"[];
+    profiles: ("workflow" | "full")[];
     ensure: typeof ensure;
     registrations: {
         tool: {

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

@@ -22,10 +22,9 @@ const manifest = {
     domain: DOMAIN,
     depKey: DEP_KEY,
     secondaryDepKeys: ['hookPresetHandlers'],
-    profiles: ['full'],
+    profiles: ['workflow', 'full'],
     ensure,
     registrations: [
-        { tool: t('ai_hook_generate'), domain: DOMAIN, bind: b((h, a) => h.handleAIHookGenerate(a)) },
         { tool: t('ai_hook_inject'), domain: DOMAIN, bind: b((h, a) => h.handleAIHookInject(a)) },
         { tool: t('ai_hook_get_data'), domain: DOMAIN, bind: b((h, a) => h.handleAIHookGetData(a)) },
         { tool: t('ai_hook_list'), domain: DOMAIN, bind: b((h, a) => h.handleAIHookList(a)) },

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

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

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

@@ -0,0 +1,99 @@
+import { tool } from '../../registry/tool-builder.js';
+const queryTypes = [
+    'before-load-inject',
+    'runtime-hook',
+    'network-intercept',
+    'function-trace',
+];
+export const instrumentationTools = [
+    tool('instrumentation_session_create')
+        .desc('Create a new instrumentation session that groups hooks, intercepts, and traces into a single queryable container.\n\nAll subsequent instrumentation operations can be associated with this session for unified management and artifact export.')
+        .string('name', 'Optional human-readable name for the session')
+        .build(),
+    tool('instrumentation_session_list')
+        .desc('List all active instrumentation sessions with their operation and artifact counts.')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('instrumentation_session_destroy')
+        .desc('Destroy an instrumentation session, marking all its operations as completed. Session data is retained for querying but no new operations can be added.')
+        .string('sessionId', 'Session ID returned by instrumentation_session_create')
+        .required('sessionId')
+        .destructive()
+        .idempotent()
+        .build(),
+    tool('instrumentation_session_status')
+        .desc('Get detailed status for an instrumentation session including operation count, artifact count, and active/destroyed state.')
+        .string('sessionId', 'Session ID')
+        .required('sessionId')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('instrumentation_operation_register')
+        .desc('Register a new instrumentation operation within a session so hooks, intercepts, and traces become queryable evidence-producing work items.')
+        .string('sessionId', 'Session ID returned by instrumentation_session_create')
+        .enum('type', queryTypes, 'Instrumentation type to register')
+        .string('target', 'Function name, URL pattern, or script target for the operation')
+        .object('config', {}, 'Operation-specific configuration payload')
+        .required('sessionId', 'type', 'target')
+        .build(),
+    tool('instrumentation_operation_list')
+        .desc('List all operations (hooks, intercepts, traces) registered within a session, optionally filtered by type.')
+        .string('sessionId', 'Session ID')
+        .enum('type', queryTypes, 'Optional filter by instrumentation type')
+        .required('sessionId')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('instrumentation_artifact_record')
+        .desc('Record a captured artifact for an instrumentation operation so the session and evidence graph reflect observed runtime data.')
+        .string('operationId', 'Operation ID returned by instrumentation_operation_register')
+        .object('data', {}, 'Captured artifact payload such as args, returnValue, headers, or body')
+        .required('operationId', 'data')
+        .build(),
+    tool('instrumentation_artifact_query')
+        .desc('Query captured artifacts (args, return values, intercepted requests, trace data) from a session, optionally filtered by type and limited.')
+        .string('sessionId', 'Session ID')
+        .enum('type', queryTypes, 'Optional filter by artifact type')
+        .number('limit', 'Maximum number of artifacts to return', { default: 50 })
+        .required('sessionId')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('instrumentation_hook_preset')
+        .desc('Apply hooks domain preset hooks within an instrumentation session and persist the injected preset summary as session artifacts.')
+        .string('sessionId', 'Session ID returned by instrumentation_session_create')
+        .string('preset', 'Single preset id to inject')
+        .array('presets', { type: 'string' }, 'Multiple preset ids to inject in one call')
+        .boolean('captureStack', 'Whether injected presets should capture stack traces', {
+        default: false,
+    })
+        .boolean('logToConsole', 'Whether injected presets should log to console', { default: true })
+        .enum('method', ['evaluate', 'evaluateOnNewDocument'], 'Injection method forwarded to hook_preset', { default: 'evaluate' })
+        .prop('customTemplate', {
+        type: 'object',
+        additionalProperties: true,
+        description: 'Optional inline custom preset definition',
+    })
+        .prop('customTemplates', {
+        type: 'array',
+        items: { type: 'object', additionalProperties: true },
+        description: 'Optional inline custom preset definitions',
+    })
+        .required('sessionId')
+        .openWorld()
+        .build(),
+    tool('instrumentation_network_replay')
+        .desc('Replay a previously captured network request inside an instrumentation session and persist the replay result or dry-run preview as session artifacts.')
+        .string('sessionId', 'Session ID returned by instrumentation_session_create')
+        .string('requestId', 'Captured request ID returned by network_get_requests')
+        .object('headerPatch', { additionalProperties: { type: 'string' } }, 'Optional request header overrides')
+        .string('bodyPatch', 'Optional raw request body override')
+        .string('methodOverride', 'Optional HTTP method override')
+        .string('urlOverride', 'Optional destination URL override')
+        .number('timeoutMs', 'Optional replay timeout in milliseconds')
+        .boolean('dryRun', 'Preview the replay without sending the request', { default: true })
+        .required('sessionId', 'requestId')
+        .openWorld()
+        .build(),
+];