feat: Enhance debugger robustness by adding session cleanup and pre-enablement checks, along with relocating breakpoint debugging skill documentation.

Author: natorion

skills/breakpoint-debugging.md skills/breakpoint-debugging/SKILL.mdskills/breakpoint-debugging.md renamed to skills/breakpoint-debugging/SKILL.md

@@ -38,6 +38,12 @@ async function getSession(page: Page): Promise<CDPSession> {
     pausedState.delete(session);
   });
 
+  session.on('closed', () => {
+    sessions.delete(page);
+    scriptMap.delete(session);
+    pausedState.delete(session);
+  });
+
   // We intentionally do NOT auto-enable here to give users control,
   // but many tools will check or imply functionality that requires it.
   return session;
@@ -217,6 +223,10 @@ export const getPausedState = definePageTool({
   },
   schema: {},
   handler: async (request, response) => {
+    if (!sessions.has(request.page.pptrPage)) {
+      response.appendResponseLine('Debugger is not enabled (or no active session).');
+      return;
+    }
     const session = await getSession(request.page.pptrPage);
     const state = pausedState.get(session);
 
@@ -254,6 +264,9 @@ export const getScopeVariables = definePageTool({
         scopeIndex: zod.number().default(0).describe('The scope index (0 is typically local)'),
     },
     handler: async (request, response) => {
+      if (!sessions.has(request.page.pptrPage)) {
+        throw new Error('Debugger is not enabled.');
+      }
         const session = await getSession(request.page.pptrPage);
         const {callFrameId, scopeIndex} = request.params;
 
@@ -305,6 +318,9 @@ export const evaluateOnCallFrame = definePageTool({
         expression: zod.string().describe('The expression to evaluate'),
     },
     handler: async (request, response) => {
+      if (!sessions.has(request.page.pptrPage)) {
+        throw new Error('Debugger is not enabled.');
+      }
         const session = await getSession(request.page.pptrPage);
         const {callFrameId, expression} = request.params;
 
@@ -334,6 +350,9 @@ export const getScriptSource = definePageTool({
         scriptId: zod.string().describe('The script ID'),
     },
     handler: async (request, response) => {
+      if (!sessions.has(request.page.pptrPage)) {
+        throw new Error('Debugger is not enabled.');
+      }
         const session = await getSession(request.page.pptrPage);
         const {scriptId} = request.params;
 
@@ -355,6 +374,9 @@ export const getCodeLines = definePageTool({
         count: zod.number().default(10).describe('Number of lines to retrieve (default 10)'),
     },
     handler: async (request, response) => {
+      if (!sessions.has(request.page.pptrPage)) {
+        throw new Error('Debugger is not enabled.');
+      }
         const session = await getSession(request.page.pptrPage);
         const {scriptId, lineNumber, count} = request.params;
 

src/tools/debugger.ts

@@ -144,7 +144,31 @@ describe('debugger', () => {
       }
     });
   });
-  
+
+  it('reports not enabled when calling getPausedState without enabling', async () => {
+    await withMcpContext(async (response, context) => {
+      const page = context.getSelectedMcpPage();
+      await getPausedState.handler({ params: {}, page }, response, context);
+      assert.ok(response.responseLines[0].includes('Debugger is not enabled'));
+    });
+  });
+
+  it('throws when calling getScopeVariables without enabling', async () => {
+    await withMcpContext(async (response, context) => {
+      const page = context.getSelectedMcpPage();
+      try {
+        await getScopeVariables.handler({ params: { callFrameId: '1', scopeIndex: 0 }, page }, response, context);
+        assert.fail('Should have thrown');
+      } catch (e: any) {
+        if (!e.message.includes('Debugger is not enabled')) {
+          console.error('Unexpected error:', e);
+          assert.fail(`Expected "Debugger is not enabled", got: ${e.message}`);
+        }
+        assert.ok(true);
+      }
+    });
+  });
+
   it('evaluates on call frame (mock check)', async () => {
       // This is hard to test e2e without actually being paused.
       // We verified "not paused" error in getPausedState.