Code-quality pass on DAP refactor

Addresses review feedback on the initial refactor:

- DapClient JSDoc: explain wire format, responsibilities, and link to the
  canonical DAP spec at microsoft.github.io/debug-adapter-protocol/overview.
  JSDoc on `pid` explaining why it's undefined for TCP transports.

- Zod-validated message envelopes: `handleMessage` now parses via
  schemas in `src/dap/protocol.ts` (ProtocolMessage / Response / Event)
  instead of casting. JSON parse and schema errors are logged via the
  existing dap logger (warn level) instead of silently swallowed.

- `handleIncomingData` extracted from the inline transport callback.

- Strongly-typed `DapClient.send`: new `DapCommandMap` / `DapEventMap` in
  `src/dap/protocol.ts` give typed args and return the response body
  directly (drops `response.body as X` at ~13 call sites in session.ts).
  Optional-args commands (`configurationDone`, `disconnect`) get a
  rest-tuple conditional type so they remain callable without `undefined`.
  Vendor extensions like Java's `redefineClasses` fall through to the
  untyped string overload.

- `DapClient.waitForEvent(name, timeoutMs)` helper replaces the
  hand-rolled `armInitializedWaiter` — listener + timer cleanup live in
  one place.

- Session features moved to a strategy pattern:
  `SessionCapabilities` → `SessionFeatures` (rename avoids collision
  with DAP's `DebugProtocol.Capabilities` on the adapter side).
  `DapRuntimeConfig.features` is now `Partial<SessionFeatures>` — runtime
  configs only list overrides on top of `DEFAULT_DAP_FEATURES`.
  `DapSession` no longer has the `isJava` conditional.

- Transport description in `wsUrl`: `dap://python/tcp(127.0.0.1:5678)` vs
  `dap://lldb/spawn(lldb-dap)` makes `dbg status` clear about whether
  the adapter is spawned or attached.

- `_runtime` narrowed via zod: new `CanonicalRuntimeSchema` derives a
  `CanonicalRuntime` union from a single const tuple. `RUNTIME_CONFIGS`
  is typed `Record<CanonicalRuntime, DapRuntimeConfig>` so adding a new
  runtime without a config is a compile error. `resolveRuntime` now
  narrows `string` → `CanonicalRuntime`.

- `getDap()` → `client` getter on `DapSession`. All ~20 call sites read
  `this.client.send(...)`. Throw semantics preserved.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: waltoss

src/cdp/session.ts

@@ -5,7 +5,7 @@ import type { RemoteObject } from "../formatter/values.ts";
 import { formatValue } from "../formatter/values.ts";
 import { createLogger, type Logger } from "../logger/index.ts";
 import { BaseSession, type WaitForStopOptions } from "../session/base-session.ts";
-import type { BreakpointListItem, SessionCapabilities, SourceMapInfo } from "../session/session.ts";
+import type { BreakpointListItem, SessionFeatures, SourceMapInfo } from "../session/session.ts";
 import type {
 	AttachResult,
 	ConsoleMessage,
@@ -102,7 +102,7 @@ export class CdpSession extends BaseSession {
 	private log: Logger<"session">;
 	private cdpLog: Logger<"cdp">;
 
-	readonly capabilities: SessionCapabilities = {
+	readonly features: SessionFeatures = {
 		functionBreakpoints: false,
 		logpoints: true,
 		hotpatch: true,

src/daemon/entry.ts

@@ -150,7 +150,7 @@ server.onRequest(async (req: DaemonRequest): Promise<DaemonResponse> => {
 		case "break-fn": {
 			const session = requireSession();
 			if (isError(session)) return session;
-			if (!session.capabilities.functionBreakpoints || !session.setFunctionBreakpoint) {
+			if (!session.features.functionBreakpoints || !session.setFunctionBreakpoint) {
 				return {
 					ok: false,
 					error: "Function breakpoints are only supported with DAP runtimes (e.g. --runtime lldb)",
@@ -365,7 +365,7 @@ server.onRequest(async (req: DaemonRequest): Promise<DaemonResponse> => {
 		case "modules": {
 			const session = requireSession();
 			if (isError(session)) return session;
-			if (!session.capabilities.modules || !session.getModules) {
+			if (!session.features.modules || !session.getModules) {
 				return {
 					ok: false,
 					error: "Modules are only available in DAP mode (e.g. --runtime lldb)",

src/dap/client.ts

@@ -2,22 +2,67 @@ import type { DebugProtocol } from "@vscode/debugprotocol";
 
 import { REQUEST_TIMEOUT_MS } from "../constants.ts";
 import type { Logger } from "../logger/index.ts";
+import {
+	type DapBody,
+	type DapCommand,
+	type DapEventMap,
+	type DapEventName,
+	type DapSendRest,
+	parseProtocolMessage,
+} from "./protocol.ts";
 import type { DapTransport } from "./transport.ts";
 
-// biome-ignore lint/suspicious/noExplicitAny: Required for handler map that stores both typed and untyped handlers
+// biome-ignore lint/suspicious/noExplicitAny: handler map stores heterogeneous typed handlers
 type AnyHandler = (...args: any[]) => void;
 
 interface PendingRequest {
-	resolve: (result: DebugProtocol.Response) => void;
+	command: string;
+	resolve: (body: unknown) => void;
 	reject: (error: Error) => void;
 	timer: ReturnType<typeof setTimeout>;
 }
 
 /**
- * DAP (Debug Adapter Protocol) client. Owns the wire format (Content-Length
- * headers + JSON) and the request/response/event bookkeeping. Bytes flow
- * through a DapTransport, so this class is agnostic to whether the adapter
- * is a spawned subprocess or a remote TCP server.
+ * Framed, request/response/event DAP (Debug Adapter Protocol) client.
+ *
+ * DAP is Microsoft's language-agnostic debugger wire protocol. The payloads
+ * here — `Content-Length`-framed JSON messages split into three types
+ * (request, response, event) correlated via `seq` / `request_seq` — are
+ * exactly what the spec defines. For the full protocol reference see:
+ *
+ *   - Overview: https://microsoft.github.io/debug-adapter-protocol/overview
+ *   - Specification: https://microsoft.github.io/debug-adapter-protocol/specification
+ *
+ * Typed requests/responses come from {@link DapCommandMap} in `protocol.ts`
+ * (derived from `@vscode/debugprotocol`); typed events from {@link DapEventMap}.
+ *
+ * What this class owns:
+ *   - **Wire format**: framing bytes in/out of a {@link DapTransport}
+ *     (Content-Length header + JSON body).
+ *   - **Request/response correlation**: each outgoing request gets a fresh
+ *     `seq`, and the matching response (or a per-request timeout) resolves
+ *     the promise returned by {@link send}.
+ *   - **Event fan-out**: incoming events are routed to listeners registered
+ *     via {@link on} / {@link off}. Typed via {@link DapEventMap}.
+ *   - **Connection lifecycle**: on transport close, pending requests reject
+ *     and new {@link send} calls throw.
+ *
+ * What this class does NOT own:
+ *   - **Byte transport**: how those bytes travel (stdio vs TCP) is the
+ *     {@link DapTransport} implementation's concern. See
+ *     {@link StdioTransport} and {@link TcpTransport}.
+ *   - **Protocol semantics**: ordering `initialize` → launch/attach →
+ *     `configurationDone`, waiting for the `initialized` event, mapping
+ *     DAP stopped-events to session state, etc. — that's `DapSession`.
+ *
+ * @example
+ * ```ts
+ * const transport = await new SpawnAdapterConnector(["lldb-dap"]).connect();
+ * const dap = new DapClient(transport);
+ * const caps = await dap.send("initialize", { adapterID: "lldb", ... });
+ * dap.on("stopped", (body) => console.log("stopped at", body));
+ * await dap.send("launch", { program: "./a.out" });
+ * ```
  */
 export class DapClient {
 	private nextSeq = 1;
@@ -34,47 +79,48 @@ export class DapClient {
 		this.logger = logger ?? null;
 		this.isConnected = true;
 		transport.start({
-			onData: (chunk) => {
-				this.buffer += chunk;
-				this.processBuffer();
-			},
+			onData: (chunk) => this.handleIncomingData(chunk),
 			onClose: () => this.handleClose(),
 		});
 	}
 
 	/**
-	 * Send a DAP request and wait for the response.
+	 * Send a typed DAP request and resolve with the response body. Known
+	 * commands (see {@link DapCommandMap}) type both `args` and the returned
+	 * body. Unknown command strings fall through to the untyped overload for
+	 * vendor extensions (e.g. Java's `redefineClasses`).
+	 *
+	 * Rejects if the adapter returns `success: false`, the per-request
+	 * timeout elapses, or the transport closes before the response arrives.
 	 */
-	async send(command: string, args?: Record<string, unknown>): Promise<DebugProtocol.Response> {
+	async send<C extends DapCommand>(command: C, ...rest: DapSendRest<C>): Promise<DapBody<C>>;
+	async send(command: string, args?: Record<string, unknown>): Promise<unknown>;
+	async send(command: string, args?: Record<string, unknown>): Promise<unknown> {
 		if (!this.isConnected) {
 			throw new Error("DAP client is not connected");
 		}
 
 		const seq = this.nextSeq++;
-		const request: DebugProtocol.Request = {
-			seq,
-			type: "request",
-			command,
-		};
-		if (args !== undefined) {
-			request.arguments = args;
-		}
+		const request: DebugProtocol.Request = { seq, type: "request", command };
+		if (args !== undefined) request.arguments = args;
 
 		this.logger?.trace("send", { command, seq, args });
 
-		return new Promise<DebugProtocol.Response>((resolve, reject) => {
+		return new Promise<unknown>((resolve, reject) => {
 			const timer = setTimeout(() => {
 				this.pending.delete(seq);
 				reject(new Error(`DAP request timed out: ${command} (seq=${seq})`));
 			}, REQUEST_TIMEOUT_MS);
 
-			this.pending.set(seq, { resolve, reject, timer });
+			this.pending.set(seq, { command, resolve, reject, timer });
 			this.writeMessage(request);
 		});
 	}
 
-	/** Register an event listener for a DAP event type (e.g. "stopped", "output"). */
-	on(event: string, handler: (body: unknown) => void): void {
+	/** Register a typed event listener. */
+	on<E extends DapEventName>(event: E, handler: (body: DapEventMap[E]) => void): void;
+	on(event: string, handler: (body: unknown) => void): void;
+	on(event: string, handler: AnyHandler): void {
 		let handlers = this.listeners.get(event);
 		if (!handlers) {
 			handlers = new Set();
@@ -84,16 +130,36 @@ export class DapClient {
 	}
 
 	/** Remove an event listener. */
-	off(event: string, handler: (body: unknown) => void): void {
+	off<E extends DapEventName>(event: E, handler: (body: DapEventMap[E]) => void): void;
+	off(event: string, handler: (body: unknown) => void): void;
+	off(event: string, handler: AnyHandler): void {
 		const handlers = this.listeners.get(event);
 		if (handlers) {
 			handlers.delete(handler);
-			if (handlers.size === 0) {
-				this.listeners.delete(event);
-			}
+			if (handlers.size === 0) this.listeners.delete(event);
 		}
 	}
 
+	/**
+	 * Register a one-shot listener for `event` and resolve when it fires, or
+	 * reject after `timeoutMs`. Cleans up both the listener and the timer in
+	 * either outcome so there's no leak on timeout.
+	 */
+	waitForEvent<E extends DapEventName>(event: E, timeoutMs: number): Promise<DapEventMap[E]> {
+		return new Promise<DapEventMap[E]>((resolve, reject) => {
+			const handler = (body: DapEventMap[E]) => {
+				clearTimeout(timer);
+				this.off(event, handler);
+				resolve(body);
+			};
+			const timer = setTimeout(() => {
+				this.off(event, handler);
+				reject(new Error(`Timed out waiting for DAP "${event}" event (${timeoutMs}ms)`));
+			}, timeoutMs);
+			this.on(event, handler);
+		});
+	}
+
 	/** Disconnect from the debug adapter, releasing the transport. */
 	disconnect(): void {
 		if (!this.isConnected) return;
@@ -109,10 +175,16 @@ export class DapClient {
 		this.transport.close();
 	}
 
+	/** Whether the underlying transport is still open. */
 	get connected(): boolean {
 		return this.isConnected;
 	}
 
+	/**
+	 * PID of the adapter subprocess. Undefined for TCP transports since the
+	 * adapter is a separate process owned by the user (e.g. the Python process
+	 * started with `python -m debugpy --listen`).
+	 */
 	get pid(): number | undefined {
 		return this.transport.pid;
 	}
@@ -130,6 +202,11 @@ export class DapClient {
 		this.transport.write(header + json);
 	}
 
+	private handleIncomingData(chunk: string): void {
+		this.buffer += chunk;
+		this.processBuffer();
+	}
+
 	private processBuffer(): void {
 		while (true) {
 			// Look for Content-Length header
@@ -139,7 +216,8 @@ export class DapClient {
 			const header = this.buffer.slice(0, headerEnd);
 			const match = /Content-Length:\s*(\d+)/i.exec(header);
 			if (!match?.[1]) {
-				// Malformed header, skip past it
+				// Malformed header; skip past it and log so we know something's off.
+				this.logger?.warn("malformed_header", { header: header.slice(0, 120) });
 				this.buffer = this.buffer.slice(headerEnd + 4);
 				continue;
 			}
@@ -159,43 +237,51 @@ export class DapClient {
 	}
 
 	private handleMessage(data: string): void {
-		let parsed: DebugProtocol.ProtocolMessage;
+		let raw: unknown;
 		try {
-			parsed = JSON.parse(data) as DebugProtocol.ProtocolMessage;
-		} catch {
+			raw = JSON.parse(data);
+		} catch (err) {
+			this.logger?.warn("json_parse_error", {
+				error: err instanceof Error ? err.message : String(err),
+				data: data.slice(0, 200),
+			});
+			return;
+		}
+
+		const parsed = parseProtocolMessage(raw);
+		if (!parsed) {
+			this.logger?.warn("schema_parse_error", { data: data.slice(0, 200) });
 			return;
 		}
+
 		if (parsed.type === "response") {
-			const response = parsed as DebugProtocol.Response;
 			this.logger?.trace("recv", {
-				command: response.command,
-				seq: response.request_seq,
-				success: response.success,
-				body: response.body,
+				command: parsed.command,
+				seq: parsed.request_seq,
+				success: parsed.success,
+				body: parsed.body,
 			});
 
-			const pending = this.pending.get(response.request_seq);
+			const pending = this.pending.get(parsed.request_seq);
 			if (!pending) return;
-			this.pending.delete(response.request_seq);
+			this.pending.delete(parsed.request_seq);
 			clearTimeout(pending.timer);
 
-			if (!response.success) {
+			if (!parsed.success) {
 				pending.reject(
-					new Error(`DAP error (${response.command}): ${response.message ?? "unknown error"}`),
+					new Error(`DAP error (${parsed.command}): ${parsed.message ?? "unknown error"}`),
 				);
 			} else {
-				pending.resolve(response);
-			}
-		} else if (parsed.type === "event") {
-			const event = parsed as DebugProtocol.Event;
-			this.logger?.trace("event", { event: event.event, body: event.body });
-
-			const handlers = this.listeners.get(event.event);
-			if (handlers) {
-				for (const handler of handlers) {
-					handler(event.body);
-				}
+				pending.resolve(parsed.body);
 			}
+			return;
+		}
+
+		// Event
+		this.logger?.trace("event", { event: parsed.event, body: parsed.body });
+		const handlers = this.listeners.get(parsed.event);
+		if (handlers) {
+			for (const handler of handlers) handler(parsed.body);
 		}
 	}