@jshookmcp/jshook 0.2.2 → 0.2.5

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

@@ -1,151 +1,52 @@
+import { tool } from '../../registry/tool-builder.js';
 export const coordinationTools = [
-    {
-        name: 'create_task_handoff',
-        description: 'Create a sub-task handoff for specialist agent delegation.\n\n' +
-            'Use this as a Planner Agent to delegate work to a Specialist. ' +
-            'Automatically captures the current page URL (if any) and injects it into the task context.\n\n' +
-            'Returns:\n' +
-            '- taskId: unique identifier to track this handoff\n' +
-            '- status: "pending"\n' +
-            '- pageUrl: auto-captured active page URL\n\n' +
-            'Example:\n' +
-            '  create_task_handoff({ description: "Analyze API surface of current page", targetDomain: "network" })',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                description: {
-                    type: 'string',
-                    description: 'Clear description of what the specialist should accomplish',
-                },
-                constraints: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Optional constraints for the specialist (e.g. "do not navigate away", "read-only analysis")',
-                },
-                targetDomain: {
-                    type: 'string',
-                    description: 'Suggested domain for the specialist (e.g. "network", "debugger", "browser"). Advisory only.',
-                },
-            },
-            required: ['description'],
-        },
-        annotations: {
-            title: 'Create Task Handoff',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'complete_task_handoff',
-        description: 'Complete a previously created task handoff with results.\n\n' +
-            'Use this as a Specialist Agent to report execution results back to the Planner. ' +
-            'Once completed, the handoff status transitions to "completed" and cannot be modified.\n\n' +
-            'Example:\n' +
-            '  complete_task_handoff({\n' +
-            '    taskId: "abc-123",\n' +
-            '    summary: "Found 5 API endpoints with Bearer auth",\n' +
-            '    keyFindings: ["POST /api/v1/login uses JWT", "X-Signature header is HMAC-SHA256"]\n' +
-            '  })',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                taskId: {
-                    type: 'string',
-                    description: 'Task ID from create_task_handoff',
-                },
-                summary: {
-                    type: 'string',
-                    description: 'Concise summary of what was accomplished',
-                },
-                keyFindings: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Key discoveries or results from the task',
-                },
-                artifacts: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Paths to generated artifact files (HAR exports, reports, etc.)',
-                },
-            },
-            required: ['taskId', 'summary'],
-        },
-        annotations: {
-            title: 'Complete Task Handoff',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'get_task_context',
-        description: 'Read the context of a task handoff.\n\n' +
-            'Returns the full handoff record including description, constraints, status, ' +
-            'page URL, and any completion data. If no taskId is provided, returns all active handoffs.\n\n' +
-            'Also returns accumulated session insights when no taskId is specified.\n\n' +
-            'Example:\n' +
-            '  get_task_context()                  // list all handoffs + session insights\n' +
-            '  get_task_context({ taskId: "abc" }) // specific handoff details',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                taskId: {
-                    type: 'string',
-                    description: 'Specific task ID to retrieve (omit for all active handoffs)',
-                },
-            },
-        },
-        annotations: {
-            title: 'Get Task Context',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'append_session_insight',
-        description: 'Append a discovery to the session-level knowledge accumulator.\n\n' +
-            'Session insights persist for the lifetime of the MCP session and are shared ' +
-            'across all handoffs. Use this to record cross-cutting findings that any agent ' +
-            'in the session should know about.\n\n' +
-            'Categories: "auth", "crypto", "api", "anti_debug", "architecture", "vulnerability", "other"\n\n' +
-            'Example:\n' +
-            '  append_session_insight({\n' +
-            '    category: "auth",\n' +
-            '    content: "JWT stored in localStorage under key \'access_token\'",\n' +
-            '    confidence: 0.95\n' +
-            '  })',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                category: {
-                    type: 'string',
-                    enum: ['auth', 'crypto', 'api', 'anti_debug', 'architecture', 'vulnerability', 'other'],
-                    description: 'Category of the insight',
-                },
-                content: {
-                    type: 'string',
-                    description: 'The insight content',
-                },
-                confidence: {
-                    type: 'number',
-                    description: 'Confidence level 0.0-1.0 (default: 1.0)',
-                    minimum: 0,
-                    maximum: 1,
-                },
-            },
-            required: ['category', 'content'],
-        },
-        annotations: {
-            title: 'Append Session Insight',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
+    tool('create_task_handoff')
+        .desc('Create a sub-task handoff for specialist agent delegation. Auto-captures active page URL.')
+        .string('description', 'What the specialist should accomplish')
+        .array('constraints', { type: 'string' }, 'Constraints for the specialist')
+        .string('targetDomain', 'Suggested domain for the specialist')
+        .required('description')
+        .build(),
+    tool('complete_task_handoff')
+        .desc('Complete a task handoff with results. Transitions status to completed.')
+        .string('taskId', 'Task ID from create_task_handoff')
+        .string('summary', 'Concise summary of what was accomplished')
+        .array('keyFindings', { type: 'string' }, 'Key discoveries or results')
+        .array('artifacts', { type: 'string' }, 'Paths to generated artifact files')
+        .required('taskId', 'summary')
+        .build(),
+    tool('get_task_context')
+        .desc('Read task handoff context. Without taskId returns all active handoffs + session insights.')
+        .string('taskId', 'Specific task ID to retrieve')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('append_session_insight')
+        .desc('Append a discovery to the session-level knowledge accumulator shared across handoffs')
+        .enum('category', ['auth', 'crypto', 'api', 'anti_debug', 'architecture', 'vulnerability', 'other'], 'Insight category')
+        .string('content', 'The insight content')
+        .prop('confidence', {
+        type: 'number',
+        description: 'Confidence level 0.0-1.0',
+        minimum: 0,
+        maximum: 1,
+    })
+        .required('category', 'content')
+        .build(),
+    tool('save_page_snapshot')
+        .desc('Save current page state (URL, cookies, storage) for checkpoint/restore workflows')
+        .string('label', 'Human-readable label for this snapshot')
+        .readOnly()
+        .build(),
+    tool('restore_page_snapshot')
+        .desc('Restore a saved page snapshot — navigates to URL and reinjects cookies and storage')
+        .string('snapshotId', 'Snapshot ID from save_page_snapshot')
+        .required('snapshotId')
+        .idempotent()
+        .build(),
+    tool('list_page_snapshots')
+        .desc('List all saved page snapshots in the current session')
+        .readOnly()
+        .idempotent()
+        .build(),
 ];

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

@@ -1,4 +1,5 @@
-import type { MCPServerContext } from '../../MCPServer.context.js';
+import type { MCPServerContext } from '../../domains/shared/registry.js';
+export * from './definitions.js';
 export interface TaskHandoff {
     id: string;
     status: 'pending' | 'in_progress' | 'completed' | 'failed';
@@ -31,4 +32,22 @@ export declare class CoordinationHandlers {
     handleAppendSessionInsight(args: Record<string, unknown>): Promise<unknown>;
     private serializeHandoff;
     private getInsightCountByCategory;
+    private readonly snapshots;
+    handleSavePageSnapshot(args: Record<string, unknown>): Promise<unknown>;
+    handleRestorePageSnapshot(args: Record<string, unknown>): Promise<unknown>;
+    handleListPageSnapshots(): Promise<unknown>;
+}
+export interface PageSnapshot {
+    id: string;
+    url: string;
+    cookies: Array<{
+        name: string;
+        value: string;
+        domain: string;
+        path: string;
+    }>;
+    localStorage: Record<string, string>;
+    sessionStorage: Record<string, string>;
+    timestamp: number;
+    label?: string;
 }

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

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+export * from './definitions.js';
 export class CoordinationHandlers {
     handoffs = new Map();
     insights = [];
@@ -142,4 +143,136 @@ export class CoordinationHandlers {
         }
         return counts;
     }
+    snapshots = new Map();
+    async handleSavePageSnapshot(args) {
+        const label = args.label;
+        const pc = this.ctx.pageController;
+        if (!pc)
+            throw new Error('No page controller available');
+        const page = await pc.getPage();
+        if (!page)
+            throw new Error('No active page to snapshot');
+        const url = page.url();
+        let cookies = [];
+        try {
+            const cdp = await page.createCDPSession();
+            const result = (await cdp.send('Network.getAllCookies'));
+            cookies = result.cookies.map((c) => ({
+                name: c.name,
+                value: c.value,
+                domain: c.domain,
+                path: c.path,
+            }));
+            await cdp.detach();
+        }
+        catch {
+        }
+        let localStorage = {};
+        let sessionStorage = {};
+        try {
+            localStorage = await page.evaluate(() => {
+                const ls = {};
+                for (let i = 0; i < window.localStorage.length; i++) {
+                    const key = window.localStorage.key(i);
+                    if (key)
+                        ls[key] = window.localStorage.getItem(key) ?? '';
+                }
+                return ls;
+            });
+            sessionStorage = await page.evaluate(() => {
+                const ss = {};
+                for (let i = 0; i < window.sessionStorage.length; i++) {
+                    const key = window.sessionStorage.key(i);
+                    if (key)
+                        ss[key] = window.sessionStorage.getItem(key) ?? '';
+                }
+                return ss;
+            });
+        }
+        catch {
+        }
+        const snapshot = {
+            id: randomUUID().slice(0, 8),
+            url,
+            cookies,
+            localStorage,
+            sessionStorage,
+            timestamp: Date.now(),
+            label,
+        };
+        this.snapshots.set(snapshot.id, snapshot);
+        return {
+            snapshotId: snapshot.id,
+            url: snapshot.url,
+            cookieCount: snapshot.cookies.length,
+            localStorageKeys: Object.keys(snapshot.localStorage).length,
+            sessionStorageKeys: Object.keys(snapshot.sessionStorage).length,
+            label: snapshot.label,
+        };
+    }
+    async handleRestorePageSnapshot(args) {
+        const snapshotId = args.snapshotId;
+        if (!snapshotId)
+            throw new Error('snapshotId is required');
+        const snapshot = this.snapshots.get(snapshotId);
+        if (!snapshot)
+            throw new Error(`Snapshot "${snapshotId}" not found`);
+        const pc = this.ctx.pageController;
+        if (!pc)
+            throw new Error('No page controller available');
+        const page = await pc.getPage();
+        if (!page)
+            throw new Error('No active page for restoration');
+        await page.goto(snapshot.url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+        if (snapshot.cookies.length > 0) {
+            try {
+                const cdp = await page.createCDPSession();
+                await cdp.send('Network.setCookies', {
+                    cookies: snapshot.cookies.map((c) => ({
+                        name: c.name,
+                        value: c.value,
+                        domain: c.domain,
+                        path: c.path,
+                    })),
+                });
+                await cdp.detach();
+            }
+            catch {
+            }
+        }
+        try {
+            await page.evaluate((ls, ss) => {
+                window.localStorage.clear();
+                for (const [k, v] of Object.entries(ls)) {
+                    window.localStorage.setItem(k, v);
+                }
+                window.sessionStorage.clear();
+                for (const [k, v] of Object.entries(ss)) {
+                    window.sessionStorage.setItem(k, v);
+                }
+            }, snapshot.localStorage, snapshot.sessionStorage);
+        }
+        catch {
+        }
+        return {
+            restored: true,
+            snapshotId: snapshot.id,
+            url: snapshot.url,
+            cookiesRestored: snapshot.cookies.length,
+            localStorageKeysRestored: Object.keys(snapshot.localStorage).length,
+            sessionStorageKeysRestored: Object.keys(snapshot.sessionStorage).length,
+        };
+    }
+    async handleListPageSnapshots() {
+        const list = [...this.snapshots.values()].map((s) => ({
+            id: s.id,
+            url: s.url,
+            label: s.label,
+            cookieCount: s.cookies.length,
+            localStorageKeys: Object.keys(s.localStorage).length,
+            sessionStorageKeys: Object.keys(s.sessionStorage).length,
+            createdAt: new Date(s.timestamp).toISOString(),
+        }));
+        return { snapshots: list, total: list.length };
+    }
 }

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

@@ -39,6 +39,21 @@ const manifest = {
             domain: DOMAIN,
             bind: b((h, a) => h.handleAppendSessionInsight(a)),
         },
+        {
+            tool: t('save_page_snapshot'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleSavePageSnapshot(a)),
+        },
+        {
+            tool: t('restore_page_snapshot'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleRestorePageSnapshot(a)),
+        },
+        {
+            tool: t('list_page_snapshots'),
+            domain: DOMAIN,
+            bind: b((h) => h.handleListPageSnapshots()),
+        },
     ],
 };
 export default manifest;