Make variable_filter required. Debug sessions always end now by default singleShot versus inspect modes

Author: dkattan

.vscode/settings.json

@@ -9,7 +9,7 @@
   // Turn off tsc task auto detection since we have the necessary tasks as npm scripts
   "typescript.tsc.autoDetect": "off",
   // Prettier formatting settings
-  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.defaultFormatter": "vscode.typescript-language-features",
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": {},
   // Ensure Prettier is used for all supported file types
@@ -41,5 +41,6 @@
         "cmd": "npm run update"
       }
     ]
-  }
+  },
+  "editor.formatOnPaste": true
 }

CHANGELOG.md

@@ -4,7 +4,12 @@ All notable changes to the "copilot-debugger" extension will be documented in th
 
 Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how to structure this file.
 
-## [Unreleased]
+## 2025-12-29
+
+**Changed:** Start Debugger tool sessions now default to **singleShot** behavior: when the debugger is paused at a breakpoint, the tool will terminate the debug session before returning. This is a safe-by-default guardrail to prevent out-of-band actions against a paused debuggee.
+
+- To keep the session alive for follow-up inspection (variables/expressions/resume), set `mode: "inspect"` in the Start Debugger tool input.
+- Note: This behavior applies to sessions started via the tool flow; it does not change normal manual VS Code debugging behavior.
 
 ## [0.0.21] - 2025-11-21
 

README.md

@@ -94,6 +94,11 @@ Description
 Type     : `integer`  
 Default        : `50`  
 
+#### `copilot-debugger.maxOutputChars`
+Description                                                                                                                                                                                        : Maximum number of characters returned by Copilot debugger tools (tool output is truncated with a suffix when exceeded).  
+Type     : `integer`  
+Default        : `8192`  
+
 #### `copilot-debugger.consoleLogLevel`
 Description                                                                                                                                                                                        : Controls how verbosely logs are mirrored to the developer console (Output panel always receives every log; this only gates console.* mirroring). Changes take effect immediately without reloading.  
 Type     : `string`  
@@ -129,6 +134,10 @@ Example settings snippet:
 
 You may supply a `serverReady` object when starting the debugger to run an automated action (shell command, HTTP request, or VS Code command) once the target is "ready".
 
+> **Important (don’t use `curl` with breakpoints):** If any breakpoint `onHit` is `break`, **do not** use `serverReady.action.type = "shellCommand"` with `curl`/`wget`/etc to call an endpoint that can hit that breakpoint. The request will often **hang** because the debuggee is paused and cannot finish responding.
+>
+> Prefer `serverReady.action.type = "httpRequest"` when you intend to **trigger a breakpoint** and capture state.
+
 Structure (legacy union still accepted; new flat shape preferred):
 
 ```ts
@@ -177,6 +186,18 @@ Actions:
 - `httpRequest` – Issues a fetch; dispatched fire‑and‑forget so a slow service cannot block debugger continuation.
 - `vscodeCommand` – Invokes a VS Code command (e.g. telemetry-free internal toggles or extension commands) with optional `args`.
 
+**Blocking behavior:**
+
+- `shellCommand` runs in a terminal and can block forever if it launches an HTTP client (like `curl`) while your debug target is paused at a `break` breakpoint.
+- `httpRequest` is executed by the tool (with timeout handling) and is the recommended way to trigger a request that is expected to hit a breakpoint.
+
+**Recommended patterns:**
+
+- **To hit a breakpoint (and capture state):** use `serverReady.action.type = "httpRequest"`.
+- **To run a smoke command after you’ve resumed:** use `shellCommand` **after** you resume (e.g., via a separate task/command), not as `serverReady`.
+
+**Common failure mode:** configuring `serverReady` with `curl http://localhost/...` while also setting a `break` breakpoint on the request handler causes the `curl` command to hang and the debug session to appear stuck.
+
 Examples:
 
 ```jsonc
@@ -190,13 +211,13 @@ Examples:
 ````
 
 ```jsonc
-// Breakpoint-triggered shell command
+// Breakpoint-triggered shell command (use for non-HTTP actions)
 {
   "serverReady": {
     "trigger": { "path": "src/server.ts", "line": 27 },
     "action": {
       "type": "shellCommand",
-      "shellCommand": "curl http://localhost:3000/health"
+      "shellCommand": "echo serverReady action executed"
     }
   }
 }

eslint.config.mjs

@@ -234,6 +234,7 @@ export default antfu(
       "out/**",
       "**/*.yml",
       "test-workspace/**",
+      "src/generated-meta.ts",
     ],
   }
 );

package-lock.json

@@ -94,6 +94,12 @@
           "description": "Maximum number of output lines (stderr/stdout) to buffer per debug session for runtime error reporting.",
           "scope": "resource"
         },
+        "copilot-debugger.maxOutputChars": {
+          "type": "integer",
+          "default": 8192,
+          "description": "Maximum number of characters returned by Copilot debugger tools (tool output is truncated with a suffix when exceeded).",
+          "scope": "resource"
+        },
         "copilot-debugger.consoleLogLevel": {
           "type": "string",
           "enum": [
@@ -122,8 +128,8 @@
         "displayName": "Start Debugger",
         "toolReferenceName": "startDebugSessionWithBreakpoints",
         "canBeReferencedInPrompt": true,
-        "userDescription": "Start a debug session, set breakpoints, and wait until a breakpoint is hit. Supports onHit behaviors: break (pause & return), captureAndContinue (collect variables & interpolated log messages then resume automatically), stopDebugging (terminate after hit). Supports serverReady.action types: httpRequest | shellCommand | vscodeCommand (auto-run after readiness trigger). Exact numeric hitCount pauses on that occurrence.",
-        "modelDescription": "Start a debug session using the configured default launch configuration or an explicitly provided configurationName. Auto-selects sole launch config when none specified and no default setting is present. Each breakpoint can specify an onHit: break (pause), captureAndContinue (non-blocking gather of variables & interpolation of {var} placeholders in logMessage then continue), or stopDebugging (terminate immediately after hit). Supports serverReady with trigger {path+line | pattern | omitted attach} and action.type httpRequest | shellCommand | vscodeCommand. Conditional expressions and exact numeric hitCount only. variableFilter required only for captureAndContinue; omit to capture all locals up to captureMaxVariables.",
+        "userDescription": "Start a debug session, set breakpoints, and wait until a breakpoint is hit. Supports onHit behaviors: break (pause), captureAndContinue (collect variables then auto-resume), stopDebugging (terminate after hit). Default mode is singleShot: the tool terminates the session before returning so the model cannot accidentally run external curl/browser probes against a paused debuggee. If you need an interactive paused workflow, set mode=inspect.",
+        "modelDescription": "Start a debug session using the configured default launch configuration or an explicitly provided configurationName. Auto-selects sole launch config when none specified and no default setting is present. Each breakpoint can specify an onHit: break (pause), captureAndContinue (collect variables & interpolate {var} placeholders then continue automatically), or stopDebugging (terminate immediately after hit). IMPORTANT protocol: if the tool returns while paused (inspect mode), you must NOT run external HTTP requests (curl/wget/browser/fetch) against the debuggee; only use debugger operations (evaluateExpression/getVariables/expandVariable/resume/stop) until resumed. Supports serverReady with trigger {path+line | pattern | omitted attach} and action.type httpRequest | shellCommand | vscodeCommand. httpRequest is the recommended canonical way to trigger a request intended to hit breakpoints because it is executed by the tool with timeout handling. shellCommand runs in a terminal and can block if it performs a request that hits a break breakpoint. Conditional expressions and exact numeric hitCount only. variableFilter required only for captureAndContinue; omit to capture all locals up to captureMaxVariables.",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -135,6 +141,14 @@
               "type": "string",
               "description": "Name of launch configuration to start. If omitted uses copilot-debugger.defaultLaunchConfiguration or auto-selects sole configuration if exactly one exists."
             },
+            "mode": {
+              "type": "string",
+              "enum": [
+                "singleShot",
+                "inspect"
+              ],
+              "description": "Tool mode. singleShot (default): terminate the session before returning. inspect: allow returning while paused for iterative inspection/resume workflows."
+            },
             "breakpointConfig": {
               "type": "object",
               "properties": {
@@ -157,8 +171,7 @@
                         "items": {
                           "type": "string"
                         },
-                        "minItems": 1,
-                        "description": "List of exact variable names to include when reporting variables for this breakpoint or for interpolation in captureAndContinue onHit. Required only if onHit=captureAndContinue and you want a subset; when omitted for captureAndContinue all locals (up to captureMaxVariables) are auto-collected. Ignored for break/stopDebugging. Case-sensitive."
+                        "description": "Required list of exact variable names to include when reporting variables for this breakpoint or for interpolation in captureAndContinue onHit. Use an empty array to opt into auto-capture (up to captureMaxVariables). Ignored for break/stopDebugging. Case-sensitive."
                       },
                       "onHit": {
                         "type": "string",
@@ -189,7 +202,8 @@
                     "required": [
                       "path",
                       "line",
-                      "onHit"
+                      "onHit",
+                      "variableFilter"
                     ]
                   },
                   "description": "Breakpoints to add before starting session."
@@ -198,7 +212,7 @@
             },
             "serverReady": {
               "type": "object",
-              "description": "Optional server readiness automation. New flat schema: trigger {path+line | pattern | omitted attach}; action.type in httpRequest | shellCommand | vscodeCommand. Backward compatible with legacy shape.",
+              "description": "Optional server readiness automation (trigger + action). Canonical pattern for driving a request into a breakpoint is action.type=httpRequest (tool-executed with timeout handling). shellCommand is allowed (including curl), but it can block if it performs a request that hits a break breakpoint. NOTE: the most common failure mode is external curl AFTER the tool returned while paused (inspect mode).",
               "properties": {
                 "trigger": {
                   "type": "object",
@@ -220,7 +234,7 @@
                 },
                 "action": {
                   "type": "object",
-                  "description": "Action executed when ready. Flat schema with discriminator 'type'.",
+                  "description": "Action executed when ready. Flat schema with discriminator 'type'. Blocking behavior: shellCommand runs in a terminal and may block if it performs a request that hits a break breakpoint; httpRequest is executed by the tool with timeout handling and is recommended for triggering breakpoints.",
                   "properties": {
                     "type": {
                       "type": "string",
@@ -229,7 +243,7 @@
                         "shellCommand",
                         "vscodeCommand"
                       ],
-                      "description": "Action type discriminator."
+                      "description": "Action type discriminator. Prefer httpRequest to trigger requests intended to hit breakpoints. shellCommand is allowed (including curl), but may block if it triggers a break breakpoint."
                     },
                     "url": {
                       "type": "string",
@@ -252,7 +266,7 @@
                     },
                     "shellCommand": {
                       "type": "string",
-                      "description": "Shell command executed in a new terminal (shellCommand)."
+                      "description": "Shell command executed in a new terminal (shellCommand). Allowed to run curl/wget/etc, but may block if it triggers a break breakpoint."
                     },
                     "command": {
                       "type": "string",
@@ -284,6 +298,7 @@
             {
               "workspaceFolder": "/abs/path/project",
               "configurationName": "Run test.js",
+              "mode": "singleShot",
               "breakpointConfig": {
                 "breakpoints": [
                   {
@@ -309,6 +324,7 @@
             },
             {
               "workspaceFolder": "/abs/path/project",
+              "mode": "inspect",
               "breakpointConfig": {
                 "breakpoints": [
                   {
@@ -320,7 +336,7 @@
               "serverReady": {
                 "action": {
                   "type": "shellCommand",
-                  "shellCommand": "curl http://localhost:3000/health"
+                  "shellCommand": "curl -sS http://localhost:3000/health || exit 1"
                 }
               }
             }
@@ -364,7 +380,6 @@
                         "items": {
                           "type": "string"
                         },
-                        "minItems": 1,
                         "description": "Variable names to include in reporting or interpolation for capture action."
                       },
                       "action": {
@@ -391,7 +406,8 @@
                     },
                     "required": [
                       "path",
-                      "line"
+                      "line",
+                      "variableFilter"
                     ]
                   }
                 }
@@ -503,6 +519,7 @@
     "@anthropic-ai/sdk": "^0.27.3",
     "@reactive-vscode/reactivity": "^0.4.1",
     "@vscode/prompt-tsx": "^0.4.0-alpha.5",
+    "markdown-table": "^3.0.4",
     "mocha": "^10.7.3",
     "reactive-vscode": "^0.4.1",
     "strip-ansi": "^7.1.2"

package.json

@@ -7,7 +7,7 @@
 export interface BreakpointDefinition {
   path: string;
   line: number;
-  variableFilter?: string[]; // Optional: when action=capture and omitted we auto-capture all locals (bounded by captureMaxVariables setting)
+  variableFilter: string[];
   onHit?: 'break' | 'stopDebugging' | 'captureAndContinue'; // captureAndContinue returns data then continues (non-blocking)
   condition?: string; // Expression evaluated at breakpoint; stop only if true
   hitCount?: number; // Exact numeric hit count (3 means pause on 3rd hit)

src/BreakpointDefinition.ts

@@ -20,6 +20,8 @@ const configDefaults = {
     5) as number,
   maxOutputLines: (Meta.configs.copilotDebuggerMaxOutputLines.default ??
     50) as number,
+  maxOutputChars: (Meta.configs.copilotDebuggerMaxOutputChars.default ??
+    8192) as number,
   consoleLogLevel: (Meta.configs.copilotDebuggerConsoleLogLevel.default ??
     'info') as ConsoleLogLevel,
   enableTraceLogging: (Meta.configs.copilotDebuggerEnableTraceLogging.default ??
@@ -32,6 +34,7 @@ const configDefaults = {
   serverReadyDefaultActionType: ServerReadyActionType;
   maxBuildErrors: number;
   maxOutputLines: number;
+  maxOutputChars: number;
   consoleLogLevel: ConsoleLogLevel;
   enableTraceLogging: boolean;
 };

src/config.ts

@@ -1,6 +1,7 @@
 import type { DebugProtocol } from '@vscode/debugprotocol';
 import type * as vscode from 'vscode';
 import { LanguageModelTextPart, LanguageModelToolResult } from 'vscode';
+import { truncateToolOutputText } from './outputTruncation';
 
 // Re-export DAP types for convenience
 export type Thread = DebugProtocol.Thread;
@@ -153,12 +154,16 @@ export class DAPHelpers {
   }
 
   static createSuccessResult(message: string): LanguageModelToolResult {
-    const textPart = new LanguageModelTextPart(message);
+    const textPart = new LanguageModelTextPart(
+      truncateToolOutputText(message).text
+    );
     return new LanguageModelToolResult([textPart]);
   }
 
   static createErrorResult(message: string): LanguageModelToolResult {
-    const textPart = new LanguageModelTextPart(`Error: ${message}`);
+    const textPart = new LanguageModelTextPart(
+      truncateToolOutputText(`Error: ${message}`).text
+    );
     return new LanguageModelToolResult([textPart]);
   }
 }