Add 'Connect to Actions Job Debugger' command

This is the first step toward bringing the Actions job debugging
experience into VS Code. The full vision is described in the ADR
(c2c-actions/docs/adrs/9758-actions-job-debugger-mvp.md): users will be
able to re-run a job with a debugger attached and connect their editor
to inspect variables, evaluate expressions, and run commands in the
job's runtime context — all through the standard Debug Adapter Protocol.

This PR adds the extension-side connect flow:

- A new command ('GitHub Actions: Connect to Actions Job Debugger...')
  that prompts for a Dev Tunnel wss:// URL and starts a debug session.
- A WebSocket-based inline debug adapter (DebugAdapterInlineImplementation)
  that speaks DAP-over-WebSocket directly to the runner — no local TCP
  bridge needed.
- Authentication using the existing VS Code GitHub session token, sent
  as a Bearer token on the WebSocket handshake.

The tunnel URL is entered manually for now. Once the server-side
endpoint that serves the debugger URL for a job is deployed, we can
automate this (and eventually add 're-run with debugger' directly from
the extension).

Security hardening from code review:
- Tunnel URLs are restricted to wss://*.devtunnels.ms (no cleartext,
  no arbitrary hosts receiving the GitHub token).
- Auth tokens are kept in extension-private memory, never exposed
  through DebugConfiguration.
- 30s connection timeout prevents indefinite hangs.
- WebSocket send errors trigger clean session teardown.

Workarounds for VS Code quirks (to be removed as the runner evolves):
- Synthetic source references on stack frames so VS Code auto-focuses
  the top frame and loads variables on connect/step.
- Buffering of early 'stopped' events that the runner sends before
  VS Code completes the DAP handshake.

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,171 @@
+import * as vscode from "vscode";
+import {getSession} from "../auth/auth";
+import {log, logDebug, 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";
+
+/**
+ * Extension-private store for auth tokens, keyed by a one-time session
+ * nonce. Tokens are never placed in DebugConfiguration (which is readable
+ * by other extensions via vscode.debug.activeDebugSession.configuration).
+ */
+const pendingTokens = new Map<string, string>();
+let nextNonce = 0;
+
+/**
+ * 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 a tracker to log all DAP traffic for diagnostics.
+  context.subscriptions.push(
+    vscode.debug.registerDebugAdapterTrackerFactory(DEBUG_TYPE, new ActionsDebugTrackerFactory())
+  );
+
+  // 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.
+  //    getSession() silently reuses the existing session; it only prompts if
+  //    the user has never signed in.
+  const session = await getSession();
+  if (!session) {
+    void vscode.window.showErrorMessage(
+      "GitHub authentication is required to connect to the Actions job debugger. Please sign in and try again."
+    );
+    return;
+  }
+
+  // 3. Launch the debug session. The token is stored in extension-private
+  //    memory (not in the configuration) to avoid exposing it to other extensions.
+  const nonce = String(++nextNonce);
+  pendingTokens.set(nonce, session.accessToken);
+
+  const config: vscode.DebugConfiguration = {
+    type: DEBUG_TYPE,
+    name: "Actions Job Debugger",
+    request: "attach",
+    tunnelUrl: validation.url,
+    __tokenNonce: nonce
+  };
+
+  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 nonce = session.configuration.__tokenNonce as string | undefined;
+    const token = nonce ? pendingTokens.get(nonce) : undefined;
+
+    // Consume the token immediately so it cannot be replayed.
+    if (nonce) {
+      pendingTokens.delete(nonce);
+    }
+
+    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);
+  }
+}
+
+// ── Debug adapter tracker (diagnostics) ──────────────────────────────
+
+class ActionsDebugTrackerFactory implements vscode.DebugAdapterTrackerFactory {
+  createDebugAdapterTracker(): vscode.DebugAdapterTracker {
+    return {
+      onWillReceiveMessage(message: unknown) {
+        const m = message as Record<string, unknown>;
+        logDebug(`[tracker] VS Code → DA: ${String(m.type)}${m.command ? `:${String(m.command)}` : ""} (seq ${String(m.seq)})`);
+      },
+      onDidSendMessage(message: unknown) {
+        const m = message as Record<string, unknown>;
+        const body = m.body as Record<string, unknown> | undefined;
+        let detail = String(m.type);
+        if (m.command) {
+          detail += `:${String(m.command)}`;
+        }
+        if (m.event) {
+          detail += `:${String(m.event)}`;
+        }
+        if (m.event === "stopped" && body) {
+          detail += ` threadId=${String(body.threadId)} allThreadsStopped=${String(body.allThreadsStopped)}`;
+        }
+        logDebug(`[tracker] DA → VS Code: ${detail} (seq ${String(m.seq)})`);
+      },
+      onError(error: Error) {
+        logError(error, "[tracker] DAP error");
+      },
+      onExit(code: number | undefined, signal: string | undefined) {
+        log(`[tracker] DAP session exited: code=${String(code)} signal=${String(signal)}`);
+      }
+    };
+  }
+}

src/debugger/debugger.ts

@@ -0,0 +1,68 @@
+import {validateTunnelUrl} from "./tunnelUrl";
+
+describe("validateTunnelUrl", () => {
+  it("accepts a valid wss:// devtunnels 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 devtunnels URL without trailing slash", () => {
+    const result = validateTunnelUrl("wss://abcdef-4711.uks1.devtunnels.ms");
+    expect(result.valid).toBe(true);
+  });
+
+  it("accepts a devtunnels URL with a path", () => {
+    const result = validateTunnelUrl("wss://abcdef-4711.uks1.devtunnels.ms/connect");
+    expect(result.valid).toBe(true);
+  });
+
+  it("rejects ws:// (cleartext)", () => {
+    const result = validateTunnelUrl("ws://abcdef-4711.uks1.devtunnels.ms/");
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.reason).toContain("wss://");
+    }
+  });
+
+  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("wss://");
+    }
+  });
+
+  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("wss://");
+    }
+  });
+
+  it("rejects non-devtunnels host", () => {
+    const result = validateTunnelUrl("wss://evil.example.com/");
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.reason).toContain("not an allowed tunnel domain");
+    }
+  });
+
+  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);
+  });
+});