@ian-pascoe/pi-dap 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-dap",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Configured Debug Adapter Protocol sessions for Pi",
   "keywords": [
@@ -23,6 +23,7 @@
   },
   "files": [
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -31,16 +32,9 @@
     "access": "public",
     "provenance": true
   },
-  "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
-  },
   "dependencies": {
     "@vscode/debugprotocol": "^1.68.0"
   },
-  "devDependencies": {
-    "vscode-js-debug": "https://github.com/microsoft/vscode-js-debug/releases/download/v1.117.0/js-debug-dap-v1.117.0.tar.gz"
-  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
@@ -52,6 +46,13 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
+  },
+  "scripts": {
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   }
-}
+}

package/skills/pi-dap/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: pi-dap
+description: Configure or diagnose Pi DAP when an Adapter Definition or Launch Profile fails, a Debug Session is stuck, or breakpoints do not bind.
+license: MIT
+---
+
+# Pi DAP
+
+1. Read [`../../README.md`](../../README.md)'s Settings section and identify the effective Adapter Definition and Launch Profile.
+2. Call `dap` with `{"operation":"status"}`, then inspect settings warnings and retained adapter stderr.
+3. Verify the configured command and referenced files without launching.
+4. Classify the failure as settings, adapter startup, protocol, state, timeout, or source mapping.
+5. For a requested change, edit one settings layer, validate JSON, and reload Pi.
+6. With approval, run one representative launch. Finish when it reaches the expected Debug Session state or one exact adapter or protocol failure remains.
+
+Ask before starting, pausing, stopping, or otherwise changing a Debuggee. An execution timeout may leave it running, so inspect `status` first.

package/src/dap-protocol-client.ts

@@ -126,8 +126,6 @@ export interface DapProtocolEventWaitOptions {
   readonly signal?: AbortSignal | undefined;
   /** Override the configured ordinary request budget. */
   readonly timeoutMs?: number | undefined;
-  /** Accept only matching event payloads after matching the event name. */
-  readonly predicate?: (event: DebugProtocol.Event) => boolean;
 }
 
 /** Overrides used when a TCP Debug Adapter asks for its primary target channel. */
@@ -139,8 +137,6 @@ export interface DapProtocolTargetChannelOptions {
 
 /** Classified Debug Adapter process, transport, protocol, timeout, and cancellation failure. */
 export class DapProtocolClientError extends Error {
-  readonly _tag = "DapProtocolClientError" as const;
-
   /** Construct a searchable DAP client failure that always names its stderr capture. */
   constructor(
     readonly kind:
@@ -252,7 +248,8 @@ function isDapStartupCancelled(options: DapProtocolClientOptions): boolean {
   return options.startupSignal?.aborted ?? false;
 }
 
-function resolvedAdapterEnvironment(
+/** Merge configured environment overrides over the parent environment; null removes an inherited key. */
+export function resolvedAdapterEnvironment(
   configured: Readonly<Record<string, string | null>>,
 ): NodeJS.ProcessEnv {
   const environment: NodeJS.ProcessEnv = { ...process.env };
@@ -468,7 +465,8 @@ function processExitPromise(child: ChildProcessWithoutNullStreams): Promise<void
   return new Promise((resolve) => child.once("exit", () => resolve()));
 }
 
-function signalOwnedProcessGroup(
+/** Signal one owned child's Linux process group (or the process itself elsewhere). */
+export function signalOwnedProcessGroup(
   child: ChildProcessWithoutNullStreams,
   signal: NodeJS.Signals,
 ): void {
@@ -724,11 +722,6 @@ export class DapProtocolClient {
     return this.options.stderrPath;
   }
 
-  /** Whether the transport has failed or shutdown has begun. */
-  get isClosed(): boolean {
-    return this.failure !== undefined || this.shuttingDown;
-  }
-
   /** Connect the primary adapter-owned target channel without spawning another process. */
   async connectTargetChannel(
     overrides: DapProtocolTargetChannelOptions = {},
@@ -787,7 +780,7 @@ export class DapProtocolClient {
         this.pendingEventWaitRejectors.delete(rejectWait);
       };
       const onEvent = (event: DebugProtocol.Event) => {
-        if (event.event !== eventName || options.predicate?.(event) === false) return;
+        if (event.event !== eventName) return;
         cleanup();
         // SAFETY: The caller chooses TEvent for the named DAP event; every envelope was parsed before this protocol boundary.
         resolve(event as TEvent);
@@ -918,7 +911,6 @@ export class DapProtocolClient {
     if (this.socket === undefined) this.child?.stdin.end();
 
     if (this.child === undefined) {
-      this.shuttingDown = true;
       this.reader.removeAllListeners();
       this.writer.destroy();
       return;

package/src/dap-session-files.ts

@@ -11,29 +11,11 @@ export interface DapOutputDrain {
 }
 
 /** Retains only bounded unread Debuggee output until a tool operation drains it. */
-export interface DapOutputBuffer {
-  /** Append Debuggee output in protocol event order. */
-  append(output: string): void;
-  /** Return and clear all currently unread Debuggee output. */
-  drain(): DapOutputDrain;
-}
-
-/** Owns private Result Spill and adapter stderr paths for one Pi session. */
-export interface DapSessionFiles {
-  /** Private directory removed when the Pi session shuts down. */
-  readonly directoryPath: string;
-  /** Write complete truncated tool output to a Result Spill file. */
-  writeResultSpill(output: string): Promise<string>;
-  /** Create a private stderr file path for one Debug Adapter launch. */
-  getAdapterStderrPath(adapterId: string): Promise<string>;
-  /** Remove all session files after queued writes finish. */
-  close(): Promise<void>;
-}
-
-class RetainedDapOutput implements DapOutputBuffer {
+export class RetainedDapOutput {
   private content = Buffer.alloc(0);
   private discardedBytes = 0;
 
+  /** Append Debuggee output in protocol event order. */
   append(output: string): void {
     const combined = Buffer.concat([this.content, Buffer.from(output)]);
     const overflow = Math.max(0, combined.length - MAX_DAP_RETAINED_BYTES);
@@ -41,6 +23,7 @@ class RetainedDapOutput implements DapOutputBuffer {
     this.content = overflow === 0 ? combined : Buffer.from(combined.subarray(overflow));
   }
 
+  /** Return and clear all currently unread Debuggee output. */
   drain(): DapOutputDrain {
     const drained = { discardedBytes: this.discardedBytes, text: this.content.toString("utf8") };
     this.content = Buffer.alloc(0);
@@ -49,6 +32,18 @@ class RetainedDapOutput implements DapOutputBuffer {
   }
 }
 
+/** Owns private Result Spill and adapter stderr paths for one Pi session. */
+export interface DapSessionFiles {
+  /** Private directory removed when the Pi session shuts down. */
+  readonly directoryPath: string;
+  /** Write complete truncated tool output to a Result Spill file. */
+  writeResultSpill(output: string): Promise<string>;
+  /** Create a private stderr file path for one Debug Adapter launch. */
+  getAdapterStderrPath(): Promise<string>;
+  /** Remove all session files after queued writes finish. */
+  close(): Promise<void>;
+}
+
 class DapSessionFileStore implements DapSessionFiles {
   private closed = false;
   private closePromise: Promise<void> | undefined;
@@ -66,7 +61,7 @@ class DapSessionFileStore implements DapSessionFiles {
     });
   }
 
-  getAdapterStderrPath(_adapterId: string): Promise<string> {
+  getAdapterStderrPath(): Promise<string> {
     const path = join(this.directoryPath, `adapter-stderr-${this.nextFileIndex++}.log`);
     return this.enqueueWrite(async () => {
       await writeFile(path, "", { mode: 0o600 });
@@ -96,11 +91,6 @@ class DapSessionFileStore implements DapSessionFiles {
   }
 }
 
-/** Create a bounded unread Debuggee output buffer. */
-export function createDapOutputBuffer(): DapOutputBuffer {
-  return new RetainedDapOutput();
-}
-
 /** Create a private directory for Result Spills and Debug Adapter stderr. */
 export async function createDapSessionFiles(sessionDirectory: string): Promise<DapSessionFiles> {
   await mkdir(sessionDirectory, { mode: 0o700, recursive: true });

package/src/dap-session.ts

@@ -7,15 +7,13 @@ import { Value } from "typebox/value";
 import {
   DapProtocolClient,
   DapProtocolClientError,
+  resolvedAdapterEnvironment,
+  signalOwnedProcessGroup,
   type DapProtocolRequestOptions,
   type DapProtocolTransport,
   type DapReverseRequestResult,
 } from "./dap-protocol-client.js";
-import {
-  createDapOutputBuffer,
-  type DapOutputBuffer,
-  type DapSessionFiles,
-} from "./dap-session-files.js";
+import { RetainedDapOutput, type DapSessionFiles } from "./dap-session-files.js";
 import type {
   DapAdapterDefinition,
   DapLaunchProfile,
@@ -162,8 +160,6 @@ const JsDebugPrimaryTargetArgumentsSchema = Type.Object(
 
 /** Classified configuration, state, protocol, or Debug Adapter failure. */
 export class DapSessionError extends Error {
-  readonly _tag = "DapSessionError" as const;
-
   /** Construct a stable Debug Session failure for the Pi tool boundary. */
   constructor(
     readonly kind: "adapter" | "configuration" | "protocol" | "state",
@@ -282,14 +278,6 @@ export interface DapSessionOptions {
   readonly onUnexpectedFailure?: (error: Error) => void;
 }
 
-type DapLaunchArgumentValue =
-  | null
-  | boolean
-  | number
-  | string
-  | readonly DapLaunchArgumentValue[]
-  | { readonly [key: string]: DapLaunchArgumentValue };
-
 interface ActiveDapSession {
   readonly adapter: DapAdapterDefinition;
   readonly profile: DapLaunchProfile;
@@ -308,19 +296,17 @@ interface ActiveDapSession {
   stopping: boolean;
 }
 
-interface TerminatedDapSessionState {
-  readonly kind: "terminated";
-  readonly adapterId: string;
-  readonly profileId: string;
-  readonly exitCode?: number;
-  readonly terminationReason?: string;
-  readonly cleanupPromise: Promise<void>;
-}
-
 type InternalDapSessionState =
   | { readonly kind: "idle" }
   | { readonly kind: "active"; readonly active: ActiveDapSession }
-  | TerminatedDapSessionState;
+  | {
+      readonly kind: "terminated";
+      readonly adapterId: string;
+      readonly profileId: string;
+      readonly exitCode?: number;
+      readonly terminationReason?: string;
+      readonly cleanupPromise: Promise<void>;
+    };
 
 interface ExecutionWait {
   readonly promise: Promise<"cancelled" | "timeout" | "transition">;
@@ -352,7 +338,8 @@ function supportsJsDebugPrimaryTarget(
   return adapter.transport.type === "tcp" && profile.arguments.type === "pwa-node";
 }
 
-function isProtocolCancellation(error: Error): boolean {
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- The only check is an instanceof narrow against the classified protocol error.
+function isProtocolCancellation(error: unknown): boolean {
   return error instanceof DapProtocolClientError && error.kind === "cancelled";
 }
 
@@ -366,47 +353,6 @@ function dapRequestOptions(
   return { signal, timeoutMs };
 }
 
-function terminatedDapSessionState(
-  active: ActiveDapSession,
-  cleanupPromise: Promise<void>,
-  terminationReason: string,
-): TerminatedDapSessionState {
-  if (active.exitCode !== undefined && terminationReason.length > 0) {
-    return {
-      kind: "terminated",
-      adapterId: active.adapter.id,
-      profileId: active.profile.id,
-      cleanupPromise,
-      exitCode: active.exitCode,
-      terminationReason,
-    };
-  }
-  if (active.exitCode !== undefined) {
-    return {
-      kind: "terminated",
-      adapterId: active.adapter.id,
-      profileId: active.profile.id,
-      cleanupPromise,
-      exitCode: active.exitCode,
-    };
-  }
-  if (terminationReason.length > 0) {
-    return {
-      kind: "terminated",
-      adapterId: active.adapter.id,
-      profileId: active.profile.id,
-      cleanupPromise,
-      terminationReason,
-    };
-  }
-  return {
-    kind: "terminated",
-    adapterId: active.adapter.id,
-    profileId: active.profile.id,
-    cleanupPromise,
-  };
-}
-
 function isProcessAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -422,9 +368,8 @@ async function stopOwnedDebuggeeProcess(
 ): Promise<void> {
   const pid = child.pid;
   if (pid === undefined || !isProcessAlive(pid)) return;
-  const processId = process.platform === "linux" ? -pid : pid;
   try {
-    process.kill(processId, "SIGTERM");
+    signalOwnedProcessGroup(child, "SIGTERM");
   } catch {
     return;
   }
@@ -432,7 +377,7 @@ async function stopOwnedDebuggeeProcess(
   while (Date.now() < deadline && isProcessAlive(pid)) await delay(10);
   if (!isProcessAlive(pid)) return;
   try {
-    process.kill(processId, "SIGKILL");
+    signalOwnedProcessGroup(child, "SIGKILL");
   } catch {
     // The Debuggee exited between the liveness check and the signal.
   }
@@ -440,7 +385,7 @@ async function stopOwnedDebuggeeProcess(
 
 /** Own one configured Debug Session at a time and retain Desired Breakpoints across launches. */
 export class DapSession {
-  private readonly output: DapOutputBuffer = createDapOutputBuffer();
+  private readonly output = new RetainedDapOutput();
   private readonly desiredBreakpoints = new Map<string, readonly DapDesiredBreakpoint[]>();
   private readonly executionWaiters = new Set<() => void>();
   private state: InternalDapSessionState = { kind: "idle" };
@@ -465,9 +410,8 @@ export class DapSession {
         `Launch Profile ${profile.id} references unavailable Adapter Definition ${profile.adapterId}`,
       );
     }
-    const launchArguments: { [key: string]: DapLaunchArgumentValue } = structuredClone(
-      profile.arguments,
-    );
+    // ponytail: shallow copy suffices — only top-level launch keys are replaced below.
+    const launchArguments = { ...profile.arguments };
     const adapterProtocolId = Value.Check(DapAdapterProtocolIdSchema, profile.arguments.type)
       ? profile.arguments.type
       : adapter.id;
@@ -477,7 +421,7 @@ export class DapSession {
     if (input.cwd !== undefined) launchArguments.cwd = resolve(this.options.cwd, input.cwd);
 
     const debuggeeProcesses = new Set<ChildProcessWithoutNullStreams>();
-    const stderrPath = await this.options.sessionFiles.getAdapterStderrPath(adapter.id);
+    const stderrPath = await this.options.sessionFiles.getAdapterStderrPath();
     let active: ActiveDapSession | undefined;
     try {
       const client = await DapProtocolClient.start({
@@ -581,7 +525,6 @@ export class DapSession {
       return this.result();
     } catch (cause) {
       if (active !== undefined) {
-        active.stopping = true;
         await this.finishActiveSession(active, "launch failed");
       } else {
         await Promise.all(
@@ -592,7 +535,7 @@ export class DapSession {
         this.state = { kind: "idle" };
         this.publishSnapshot();
       }
-      if (cause instanceof Error && isProtocolCancellation(cause)) {
+      if (isProtocolCancellation(cause)) {
         throw new DapSessionError("adapter", "launch was cancelled and cleaned up", { cause });
       }
       if (cause instanceof DapSessionError) throw cause;
@@ -623,39 +566,27 @@ export class DapSession {
 
   /** Continue a stopped Debuggee and wait for its next stop or termination. */
   continue(signal?: AbortSignal): Promise<DapSessionResult> {
-    return this.executeStoppedRequest("continue", signal);
+    return this.executeLifecycleRequest("continue", signal);
   }
 
   /** Step over in a stopped Debuggee and wait for its next stop or termination. */
   next(signal?: AbortSignal): Promise<DapSessionResult> {
-    return this.executeStoppedRequest("next", signal);
+    return this.executeLifecycleRequest("next", signal);
   }
 
   /** Step into in a stopped Debuggee and wait for its next stop or termination. */
   stepIn(signal?: AbortSignal): Promise<DapSessionResult> {
-    return this.executeStoppedRequest("stepIn", signal);
+    return this.executeLifecycleRequest("stepIn", signal);
   }
 
   /** Step out in a stopped Debuggee and wait for its next stop or termination. */
   stepOut(signal?: AbortSignal): Promise<DapSessionResult> {
-    return this.executeStoppedRequest("stepOut", signal);
+    return this.executeLifecycleRequest("stepOut", signal);
   }
 
   /** Pause a running Debuggee and wait for its stopped event. */
-  async pause(signal?: AbortSignal): Promise<DapSessionResult> {
-    const active = this.requireActivePhase("running", "pause");
-    const threadId = await this.resolveThreadId(active, signal);
-    const wait = this.waitForExecutionTransition(signal);
-    try {
-      await active.client.request("pause", { threadId }, dapRequestOptions(signal));
-    } catch (cause) {
-      wait.cancel();
-      if (cause instanceof Error && isProtocolCancellation(cause)) return this.result();
-      throw cause;
-    }
-    await wait.promise;
-    await active.cleanupPromise;
-    return this.result();
+  pause(signal?: AbortSignal): Promise<DapSessionResult> {
+    return this.executeLifecycleRequest("pause", signal);
   }
 
   /** Retrieve a page of Stack Frames from the stopped thread. */
@@ -745,13 +676,12 @@ export class DapSession {
   }
 
   /** Idempotently stop the active Debug Session and preserve Desired Breakpoints. */
-  async stop(_signal?: AbortSignal): Promise<DapSessionResult> {
+  async stop(): Promise<DapSessionResult> {
     const active = this.currentActive();
     if (active === undefined) {
       if (this.state.kind === "terminated") await this.state.cleanupPromise;
       return this.result();
     }
-    active.stopping = true;
     await this.finishActiveSession(active, "stopped by request");
     return this.result();
   }
@@ -762,7 +692,6 @@ export class DapSession {
     this.shutdownPromise = (async () => {
       const active = this.currentActive();
       if (active !== undefined) {
-        active.stopping = true;
         await this.finishActiveSession(active, "Pi session shutdown");
       } else if (this.state.kind === "terminated") {
         await this.state.cleanupPromise;
@@ -824,19 +753,19 @@ export class DapSession {
     return response;
   }
 
-  private async executeStoppedRequest(
-    command: "continue" | "next" | "stepIn" | "stepOut",
+  private async executeLifecycleRequest(
+    command: "continue" | "next" | "stepIn" | "stepOut" | "pause",
     signal: AbortSignal | undefined,
   ): Promise<DapSessionResult> {
-    const active = this.requireActivePhase("stopped", command);
+    const active = this.requireActivePhase(command === "pause" ? "running" : "stopped", command);
     const threadId = await this.resolveThreadId(active, signal);
-    this.transitionActiveToRunning(active);
+    if (command !== "pause") this.transitionActiveToRunning(active);
     const wait = this.waitForExecutionTransition(signal);
     try {
       await active.client.request(command, { threadId }, dapRequestOptions(signal));
     } catch (cause) {
       wait.cancel();
-      if (cause instanceof Error && isProtocolCancellation(cause)) return this.result();
+      if (isProtocolCancellation(cause)) return this.result();
       throw cause;
     }
     await wait.promise;
@@ -1029,11 +958,7 @@ export class DapSession {
     argumentsValue: Static<typeof RunInTerminalArgumentsSchema>,
     debuggeeProcesses: Set<ChildProcessWithoutNullStreams>,
   ): Promise<DapReverseRequestResult> {
-    const environment: NodeJS.ProcessEnv = { ...process.env };
-    for (const [name, value] of Object.entries(argumentsValue.env ?? {})) {
-      if (value === null) delete environment[name];
-      else environment[name] = value;
-    }
+    const environment = resolvedAdapterEnvironment(argumentsValue.env ?? {});
     const interpretedByShell = argumentsValue.argsCanBeInterpretedByShell === true;
     const command = interpretedByShell ? argumentsValue.args.join(" ") : argumentsValue.args[0];
     if (command === undefined)
@@ -1121,7 +1046,14 @@ export class DapSession {
     })();
     active.cleanupPromise = cleanup;
     if (this.isCurrentActive(active)) {
-      this.state = terminatedDapSessionState(active, cleanup, terminationReason);
+      this.state = {
+        kind: "terminated",
+        adapterId: active.adapter.id,
+        profileId: active.profile.id,
+        cleanupPromise: cleanup,
+        ...(active.exitCode !== undefined && { exitCode: active.exitCode }),
+        ...(terminationReason.length > 0 && { terminationReason }),
+      };
       this.publishSnapshot();
     }
     this.settleExecutionWaiters();
@@ -1155,53 +1087,25 @@ export class DapSession {
   private snapshot(): DapSessionSnapshot {
     if (this.state.kind === "idle") return { state: "idle" };
     if (this.state.kind === "terminated") {
-      if (this.state.exitCode !== undefined && this.state.terminationReason !== undefined) {
-        return {
-          state: "terminated",
-          adapterId: this.state.adapterId,
-          profileId: this.state.profileId,
-          exitCode: this.state.exitCode,
-          terminationReason: this.state.terminationReason,
-        };
-      }
-      if (this.state.exitCode !== undefined) {
-        return {
-          state: "terminated",
-          adapterId: this.state.adapterId,
-          profileId: this.state.profileId,
-          exitCode: this.state.exitCode,
-        };
-      }
-      if (this.state.terminationReason !== undefined) {
-        return {
-          state: "terminated",
-          adapterId: this.state.adapterId,
-          profileId: this.state.profileId,
-          terminationReason: this.state.terminationReason,
-        };
-      }
+      const terminated = this.state;
       return {
         state: "terminated",
-        adapterId: this.state.adapterId,
-        profileId: this.state.profileId,
+        adapterId: terminated.adapterId,
+        profileId: terminated.profileId,
+        ...(terminated.exitCode !== undefined && { exitCode: terminated.exitCode }),
+        ...(terminated.terminationReason !== undefined && {
+          terminationReason: terminated.terminationReason,
+        }),
       };
     }
     const active = this.state.active;
     if (active.phase === "stopped") {
-      if (active.threadId !== undefined) {
-        return {
-          state: "stopped",
-          adapterId: active.adapter.id,
-          profileId: active.profile.id,
-          stopReason: active.stopReason ?? "unknown",
-          threadId: active.threadId,
-        };
-      }
       return {
         state: "stopped",
         adapterId: active.adapter.id,
         profileId: active.profile.id,
         stopReason: active.stopReason ?? "unknown",
+        ...(active.threadId !== undefined && { threadId: active.threadId }),
       };
     }
     return {

package/src/dap-tool.ts

@@ -4,7 +4,6 @@ import {
   DEFAULT_MAX_LINES,
   truncateHead,
   type AgentToolResult,
-  type ExtensionAPI,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Value } from "typebox/value";
@@ -14,7 +13,6 @@ import type {
   DapSession,
   DapSessionResult,
   DapStackInput,
-  DapVariablesInput,
 } from "./dap-session.js";
 import type { DapSessionFiles } from "./dap-session-files.js";
 import {
@@ -27,6 +25,10 @@ import {
 } from "./dap-tool-contract.js";
 import { renderDapToolCall, renderDapToolResult } from "./dap-tool-rendering.js";
 
+type DapToolDefinition = ToolDefinition<typeof DapToolParametersSchema, DapToolRenderDetails> & {
+  readonly outputSchema: typeof DapToolResultDetailsSchema;
+};
+
 type DapToolSession = Pick<
   DapSession,
   | "launch"
@@ -288,13 +290,14 @@ async function dispatchDapOperation(
 ): Promise<DapSessionResult> {
   switch (parameters.operation) {
     case "launch": {
-      let input: DapLaunchInput = {};
-      if (parameters.profile !== undefined) input = { ...input, profile: parameters.profile };
-      if (parameters.program !== undefined) {
-        input = { ...input, program: resolve(cwd, parameters.program) };
-      }
-      if (parameters.args !== undefined) input = { ...input, args: parameters.args };
-      if (parameters.cwd !== undefined) input = { ...input, cwd: resolve(cwd, parameters.cwd) };
+      const input: DapLaunchInput = {
+        ...(parameters.profile !== undefined && { profile: parameters.profile }),
+        ...(parameters.program !== undefined && {
+          program: resolve(cwd, parameters.program),
+        }),
+        ...(parameters.args !== undefined && { args: parameters.args }),
+        ...(parameters.cwd !== undefined && { cwd: resolve(cwd, parameters.cwd) }),
+      };
       return session.launch(input, signal);
     }
     case "set_breakpoints":
@@ -313,16 +316,18 @@ async function dispatchDapOperation(
     case "pause":
       return session.pause(signal);
     case "stack": {
-      let input: DapStackInput = {};
-      if (parameters.thread_id !== undefined) input = { ...input, threadId: parameters.thread_id };
-      if (parameters.start !== undefined) input = { ...input, start: parameters.start };
-      if (parameters.count !== undefined) input = { ...input, count: parameters.count };
+      const input: DapStackInput = {
+        ...(parameters.thread_id !== undefined && { threadId: parameters.thread_id }),
+        ...(parameters.start !== undefined && { start: parameters.start }),
+        ...(parameters.count !== undefined && { count: parameters.count }),
+      };
       return session.stack(input, signal);
     }
     case "variables": {
-      let page: Pick<DapVariablesInput, "start" | "count"> = {};
-      if (parameters.start !== undefined) page = { ...page, start: parameters.start };
-      if (parameters.count !== undefined) page = { ...page, count: parameters.count };
+      const page = {
+        ...(parameters.start !== undefined && { start: parameters.start }),
+        ...(parameters.count !== undefined && { count: parameters.count }),
+      };
       return "frame_id" in parameters
         ? session.variables({ ...page, frameId: parameters.frame_id }, signal)
         : session.variables(
@@ -331,8 +336,10 @@ async function dispatchDapOperation(
           );
     }
     case "evaluate": {
-      let input: DapEvaluateInput = { expression: parameters.expression };
-      if (parameters.frame_id !== undefined) input = { ...input, frameId: parameters.frame_id };
+      const input: DapEvaluateInput = {
+        expression: parameters.expression,
+        ...(parameters.frame_id !== undefined && { frameId: parameters.frame_id }),
+      };
       return session.evaluate(input, signal);
     }
     case "status":
@@ -353,7 +360,7 @@ function notifyDapToolObserver(operation: () => void): void {
 /** Create the single strict Pi DAP ToolDefinition bound to current session resources. */
 export function createDapToolDefinition(
   getRuntime: () => DapToolRuntime | undefined,
-): ToolDefinition<typeof DapToolParametersSchema, DapToolRenderDetails> {
+): DapToolDefinition {
   return {
     name: "dap",
     label: "DAP",
@@ -364,6 +371,7 @@ export function createDapToolDefinition(
       "Use dap to set source breakpoints, launch a configured Debug Session, control the Debuggee, and inspect stopped Stack Frames and variables.",
     ],
     parameters: DapToolParametersSchema,
+    outputSchema: DapToolResultDetailsSchema,
     renderCall: (argumentsValue, theme, context) =>
       renderDapToolCall(argumentsValue, theme, context.expanded, context.cwd),
     renderResult: (result, options, theme, context) =>
@@ -410,11 +418,3 @@ export function createDapToolDefinition(
     },
   };
 }
-
-/** Register exactly one strict `dap` tool whose runtime follows Pi session reloads. */
-export function registerDapTool(
-  pi: Pick<ExtensionAPI, "registerTool">,
-  getRuntime: () => DapToolRuntime | undefined,
-): void {
-  pi.registerTool(createDapToolDefinition(getRuntime));
-}

package/src/pi-dap-extension.ts

@@ -8,35 +8,25 @@ import {
 import { DapSession } from "./dap-session.js";
 import { createDapSessionFiles, type DapSessionFiles } from "./dap-session-files.js";
 import { DapObserverUiController } from "./dap-observer-ui.js";
-import { registerDapTool, type DapToolRuntime } from "./dap-tool.js";
+import { createDapToolDefinition, type DapToolRuntime } from "./dap-tool.js";
 import { resolveDapSettings } from "./pi-dap-settings.js";
 
-/** Runtime construction effect kept narrow so lifecycle tests use an isolated Pi agent directory. */
-export interface PiDapLifecycleEffects {
-  /** Return Pi's trust-aware global settings directory. */
-  getAgentDirectory(): string;
-}
-
 interface ActivePiDapSession extends DapToolRuntime {
   readonly observer: DapObserverUiController;
   readonly session: DapSession;
   readonly sessionFiles: DapSessionFiles;
 }
 
-const productionPiDapLifecycleEffects: PiDapLifecycleEffects = {
-  getAgentDirectory: getAgentDir,
-};
-
 /** Own settings, one Debug Session, one registered tool, and cleanup for a Pi conversation session. */
 export class PiDapLifecycleController {
   private activeSession: ActivePiDapSession | undefined;
   private shutdownPromise: Promise<void> | undefined;
   private toolRegistered = false;
 
-  /** Bind lifecycle handlers to Pi without starting a Debug Adapter. */
+  /** Bind lifecycle handlers to Pi; `getAgentDirectory` may be overridden by tests to isolate settings. */
   constructor(
     private readonly pi: ExtensionAPI,
-    private readonly effects: PiDapLifecycleEffects,
+    private readonly getAgentDirectory: () => string = getAgentDir,
   ) {}
 
   /** Register the Pi conversation session start and shutdown handlers. */
@@ -47,7 +37,7 @@ export class PiDapLifecycleController {
 
   private async startSession(context: ExtensionContext): Promise<void> {
     await this.shutdownSession();
-    const settingsManager = SettingsManager.create(context.cwd, this.effects.getAgentDirectory(), {
+    const settingsManager = SettingsManager.create(context.cwd, this.getAgentDirectory(), {
       projectTrusted: context.isProjectTrusted(),
     });
     const settings = resolveDapSettings(settingsManager);
@@ -69,7 +59,7 @@ export class PiDapLifecycleController {
       sessionFiles,
     };
     if (!this.toolRegistered) {
-      registerDapTool(this.pi, () => this.activeSession);
+      this.pi.registerTool(createDapToolDefinition(() => this.activeSession));
       this.toolRegistered = true;
     }
   }
@@ -100,9 +90,9 @@ export class PiDapLifecycleController {
 
 /** Compose the source-TypeScript Pi DAP extension without starting a Debug Adapter at load time. */
 export function createPiDapExtension(
-  effects: PiDapLifecycleEffects = productionPiDapLifecycleEffects,
+  getAgentDirectory: () => string = getAgentDir,
 ): ExtensionFactory {
-  return (pi) => new PiDapLifecycleController(pi, effects).register();
+  return (pi) => new PiDapLifecycleController(pi, getAgentDirectory).register();
 }
 
 const piDapExtension = createPiDapExtension();

package/src/pi-dap-settings.ts

@@ -109,7 +109,6 @@ type ParsedDapAdapter =
   | { readonly kind: "excluded" }
   | {
       readonly kind: "valid";
-      readonly scope: SettingsScope;
       readonly value: DapAdapterDefinitionWire;
       readonly transport: DapAdapterTransport;
     };
@@ -216,7 +215,6 @@ function parseDapAdapters(
     }
     adapters.set(id, {
       kind: "valid",
-      scope,
       transport: parsedTransport.transport,
       value: adapter,
     });
@@ -329,32 +327,22 @@ function readDapLayer(settings: DapSettingsDocumentInput, scope: SettingsScope):
   };
 }
 
-function mergeDapAdapters(
-  globalEntries: ReadonlyMap<string, ParsedDapAdapter>,
-  projectEntries: ReadonlyMap<string, ParsedDapAdapter>,
-): ReadonlyMap<string, Extract<ParsedDapAdapter, { readonly kind: "valid" }>> {
-  const entries = new Map<string, Extract<ParsedDapAdapter, { readonly kind: "valid" }>>();
-  for (const [id, entry] of globalEntries) {
-    if (entry.kind === "valid") entries.set(id, entry);
-  }
-  for (const [id, entry] of projectEntries) {
-    entries.delete(id);
-    if (entry.kind === "valid") entries.set(id, entry);
-  }
-  return new Map([...entries].sort(([left], [right]) => left.localeCompare(right)));
-}
-
-function mergeDapProfiles(
-  globalEntries: ReadonlyMap<string, ParsedDapProfile>,
-  projectEntries: ReadonlyMap<string, ParsedDapProfile>,
-): ReadonlyMap<string, Extract<ParsedDapProfile, { readonly kind: "valid" }>> {
-  const entries = new Map<string, Extract<ParsedDapProfile, { readonly kind: "valid" }>>();
+/** Merge one settings layer over another by map key, keeping only valid entries in sorted order. */
+function mergeValidDapEntries<
+  Entry extends { readonly kind: "excluded" } | { readonly kind: "valid" },
+>(
+  globalEntries: ReadonlyMap<string, Entry>,
+  projectEntries: ReadonlyMap<string, Entry>,
+): ReadonlyMap<string, Extract<Entry, { readonly kind: "valid" }>> {
+  type Valid = Extract<Entry, { readonly kind: "valid" }>;
+  const isValid = (entry: Entry): entry is Valid => entry.kind === "valid";
+  const entries = new Map<string, Valid>();
   for (const [id, entry] of globalEntries) {
-    if (entry.kind === "valid") entries.set(id, entry);
+    if (isValid(entry)) entries.set(id, entry);
   }
   for (const [id, entry] of projectEntries) {
     entries.delete(id);
-    if (entry.kind === "valid") entries.set(id, entry);
+    if (isValid(entry)) entries.set(id, entry);
   }
   return new Map([...entries].sort(([left], [right]) => left.localeCompare(right)));
 }
@@ -376,8 +364,8 @@ function resolveDapAdapter(
 export function resolveDapSettings(reader: DapSettingsReader): ResolvedDapSettings {
   const globalLayer = readDapLayer(reader.getGlobalSettings(), "global");
   const projectLayer = readDapLayer(reader.getProjectSettings(), "project");
-  const mergedAdapters = mergeDapAdapters(globalLayer.adapters, projectLayer.adapters);
-  const mergedProfiles = mergeDapProfiles(globalLayer.profiles, projectLayer.profiles);
+  const mergedAdapters = mergeValidDapEntries(globalLayer.adapters, projectLayer.adapters);
+  const mergedProfiles = mergeValidDapEntries(globalLayer.profiles, projectLayer.profiles);
   const adapters = new Map(
     [...mergedAdapters].map(([id, adapter]) => [id, resolveDapAdapter(id, adapter)]),
   );