Add 'Connect to Actions Job Debugger' command

Registers a new debug adapter type (github-actions-job) and a command-palette
command that connects to an Actions runner's Dev Tunnel endpoint using
DAP-over-WebSocket.

The flow:
1. User runs 'GitHub Actions: Connect to Actions Job Debugger...'
2. Prompted for the wss:// tunnel URL (manual entry for now)
3. Extension acquires the current GitHub auth token
4. Opens a WebSocket to the tunnel with Authorization: Bearer <token>
5. Launches a standard VS Code debug session using an inline adapter

The WebSocketDapAdapter implements vscode.DebugAdapter and forwards DAP
JSON messages as individual text WebSocket frames — matching the runner's
WebSocketDapBridge and the gh-actions-debugger CLI bridge. Keepalive pings
run every 25s. On remote close, a DAP 'terminated' event is synthesized
so VS Code tears down the session cleanly.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: rentziass

README.md

@@ -1,6 +1,8 @@
 # GitHub Actions for VS Code
 
 > **🐛 Actions Job Debugger (Preview):** To try the latest debugger build, download the `.vsix` artifact from the most recent [Build Debugger Extension](https://github.com/github/vscode-github-actions/actions/workflows/debugger-build.yml) workflow run. On the workflow run page, scroll to **Artifacts** and download **vscode-github-actions-debugger**. Then install it in VS Code by running `code --install-extension <path-to-downloaded.vsix>` or via the Extensions view → `⋯` menu → **Install from VSIX…**.
+>
+> Once installed, open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run **GitHub Actions: Connect to Actions Job Debugger…**. Paste the `wss://` tunnel URL from a debug-mode job and the extension will open a full debug session using your current GitHub credentials.
 
 The GitHub Actions extension lets you manage your workflows, view the workflow run history, and helps with authoring workflows.
 

package-lock.json

@@ -25,6 +25,7 @@
   "activationEvents": [
     "onView:workflows",
     "onView:settings",
+    "onDebugResolve:github-actions-job",
     "workspaceContains:**/.github/workflows/**",
     "workspaceContains:**/action.yml",
     "workspaceContains:**/action.yaml"
@@ -97,7 +98,19 @@
         }
       }
     },
+    "debuggers": [
+      {
+        "type": "github-actions-job",
+        "label": "GitHub Actions Job Debugger",
+        "languages": []
+      }
+    ],
     "commands": [
+      {
+        "command": "github-actions.debugger.connect",
+        "category": "GitHub Actions",
+        "title": "Connect to Actions Job Debugger..."
+      },
       {
         "command": "github-actions.explorer.refresh",
         "category": "GitHub Actions",
@@ -544,6 +557,7 @@
     "@types/libsodium-wrappers": "^0.7.10",
     "@types/uuid": "^3.4.6",
     "@types/vscode": "^1.72.0",
+    "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^5.40.0",
     "@typescript-eslint/parser": "^5.40.0",
     "@vscode/test-web": "^0.0.69",
@@ -579,7 +593,8 @@
     "tunnel": "0.0.6",
     "util": "^0.12.1",
     "uuid": "^3.3.3",
-    "vscode-languageclient": "^8.0.2"
+    "vscode-languageclient": "^8.0.2",
+    "ws": "^8.20.0"
   },
   "overrides": {
     "browserify-sign": {

package.json

@@ -0,0 +1,113 @@
+import * as vscode from "vscode";
+import {newSession} from "../auth/auth";
+import {log, logError} from "../log";
+import {validateTunnelUrl} from "./tunnelUrl";
+import {WebSocketDapAdapter} from "./webSocketDapAdapter";
+
+/** The custom debug type registered in package.json contributes.debuggers. */
+export const DEBUG_TYPE = "github-actions-job";
+
+/**
+ * Registers the Actions Job Debugger command and debug adapter factory.
+ *
+ * Contributes:
+ * - A command-palette command that prompts for a tunnel URL and starts a debug session.
+ * - A DebugAdapterDescriptorFactory that returns an inline DAP-over-WS adapter.
+ */
+export function registerDebugger(context: vscode.ExtensionContext): void {
+  // Register the inline adapter factory for our debug type.
+  context.subscriptions.push(
+    vscode.debug.registerDebugAdapterDescriptorFactory(DEBUG_TYPE, new ActionsDebugAdapterFactory())
+  );
+
+  // Register the connect command.
+  context.subscriptions.push(
+    vscode.commands.registerCommand("github-actions.debugger.connect", () => connectToDebugger())
+  );
+}
+
+// ── Connect command ──────────────────────────────────────────────────
+
+async function connectToDebugger(): Promise<void> {
+  // 1. Prompt for the tunnel URL.
+  const rawUrl = await vscode.window.showInputBox({
+    title: "Connect to Actions Job Debugger",
+    prompt: "Enter the debugger tunnel URL (wss://…)",
+    placeHolder: "wss://xxxx-4711.region.devtunnels.ms/",
+    ignoreFocusOut: true,
+    validateInput: input => {
+      if (!input) {
+        return "A tunnel URL is required";
+      }
+      const result = validateTunnelUrl(input);
+      return result.valid ? null : result.reason;
+    }
+  });
+
+  if (!rawUrl) {
+    return; // user cancelled
+  }
+
+  const validation = validateTunnelUrl(rawUrl);
+  if (!validation.valid) {
+    void vscode.window.showErrorMessage(`Invalid tunnel URL: ${validation.reason}`);
+    return;
+  }
+
+  // 2. Acquire a GitHub auth session. The token is used as a Bearer token
+  //    against the Dev Tunnel relay, which accepts VS Code's GitHub app tokens.
+  let session: vscode.AuthenticationSession;
+  try {
+    session = await newSession("Sign in to GitHub to connect to the Actions job debugger.");
+  } catch (e) {
+    void vscode.window.showErrorMessage(`GitHub authentication required: ${(e as Error).message}`);
+    return;
+  }
+
+  // 3. Launch the debug session. The factory will use the tunnel URL and token
+  //    from the configuration to create the websocket adapter.
+  const config: vscode.DebugConfiguration = {
+    type: DEBUG_TYPE,
+    name: "Actions Job Debugger",
+    request: "attach",
+    tunnelUrl: validation.url,
+    __token: session.accessToken
+  };
+
+  log(`Starting debug session for ${validation.url}`);
+
+  const started = await vscode.debug.startDebugging(undefined, config);
+  if (!started) {
+    void vscode.window.showErrorMessage("Failed to start the debug session. Check the GitHub Actions output for details.");
+  }
+}
+
+// ── Debug adapter factory ────────────────────────────────────────────
+
+class ActionsDebugAdapterFactory implements vscode.DebugAdapterDescriptorFactory {
+  async createDebugAdapterDescriptor(
+    session: vscode.DebugSession
+  ): Promise<vscode.DebugAdapterDescriptor> {
+    const tunnelUrl = session.configuration.tunnelUrl as string | undefined;
+    const token = session.configuration.__token as string | undefined;
+
+    if (!tunnelUrl || !token) {
+      throw new Error(
+        "Missing tunnel URL or authentication token. Use the 'Connect to Actions Job Debugger' command to start a session."
+      );
+    }
+
+    const adapter = new WebSocketDapAdapter(tunnelUrl, token);
+
+    try {
+      await adapter.connect();
+    } catch (e) {
+      adapter.dispose();
+      const msg = (e as Error).message;
+      logError(e as Error, "Failed to connect debugger adapter");
+      throw new Error(`Could not connect to the debugger tunnel: ${msg}`);
+    }
+
+    return new vscode.DebugAdapterInlineImplementation(adapter);
+  }
+}

src/debugger/debugger.ts

@@ -0,0 +1,57 @@
+import {validateTunnelUrl} from "./tunnelUrl";
+
+describe("validateTunnelUrl", () => {
+  it("accepts a valid wss:// URL", () => {
+    const result = validateTunnelUrl("wss://abcdef-4711.uks1.devtunnels.ms/");
+    expect(result).toEqual({valid: true, url: "wss://abcdef-4711.uks1.devtunnels.ms/"});
+  });
+
+  it("accepts a valid ws:// URL", () => {
+    const result = validateTunnelUrl("ws://abcdef-4711.uks1.devtunnels.ms/");
+    expect(result).toEqual({valid: true, url: "ws://abcdef-4711.uks1.devtunnels.ms/"});
+  });
+
+  it("accepts a URL without trailing slash", () => {
+    const result = validateTunnelUrl("wss://abcdef-4711.uks1.devtunnels.ms");
+    expect(result.valid).toBe(true);
+  });
+
+  it("accepts a URL with a path", () => {
+    const result = validateTunnelUrl("wss://abcdef-4711.uks1.devtunnels.ms/connect");
+    expect(result.valid).toBe(true);
+  });
+
+  it("rejects http:// scheme", () => {
+    const result = validateTunnelUrl("http://abcdef-4711.uks1.devtunnels.ms/");
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.reason).toContain("ws://");
+    }
+  });
+
+  it("rejects https:// scheme", () => {
+    const result = validateTunnelUrl("https://abcdef-4711.uks1.devtunnels.ms/");
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.reason).toContain("ws://");
+    }
+  });
+
+  it("rejects empty string", () => {
+    const result = validateTunnelUrl("");
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects invalid URL format", () => {
+    const result = validateTunnelUrl("not a url at all");
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.reason).toContain("Invalid URL");
+    }
+  });
+
+  it("rejects URL with just a scheme", () => {
+    const result = validateTunnelUrl("wss://");
+    expect(result.valid).toBe(false);
+  });
+});

src/debugger/tunnelUrl.test.ts

@@ -0,0 +1,27 @@
+/**
+ * Validates a Dev Tunnel websocket URL for the Actions job debugger.
+ *
+ * Accepted formats:
+ *   wss://xxxx-4711.region.devtunnels.ms/
+ *   ws://xxxx-4711.region.devtunnels.ms/
+ *
+ * The URL must use a websocket scheme and include a non-empty host.
+ */
+export function validateTunnelUrl(raw: string): {valid: true; url: string} | {valid: false; reason: string} {
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return {valid: false, reason: "Invalid URL format"};
+  }
+
+  if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+    return {valid: false, reason: `URL must use ws:// or wss:// scheme, got "${parsed.protocol.replace(":", "")}://"`};
+  }
+
+  if (!parsed.host) {
+    return {valid: false, reason: "URL must include a host"};
+  }
+
+  return {valid: true, url: parsed.toString()};
+}