@ian-pascoe/pi-dap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Pascoe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @ian-pascoe/pi-dap
+
+Configured [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)
+(DAP) sessions for [Pi](https://github.com/earendil-works/pi).
+
+## Install
+
+```bash
+pi install npm:@ian-pascoe/pi-dap
+# or
+pi install git:github.com/ian-pascoe/pi-extensions
+```
+
+For a local checkout, run `pi -e ./packages/pi-dap/src/index.ts`.
+
+Debug Adapter executables are user-managed. Pi DAP has no adapter discovery,
+installer, or catalog. The repository-only `vscode-js-debug` development
+dependency supports this repository's Node smoke test; its files are not packed
+or installed with the package.
+
+## Settings
+
+Pi DAP reads only the `dap` key from Pi's global `settings.json` and trusted
+project `.pi/settings.json`:
+
+```json
+{
+  "dap": {
+    "timeouts": {
+      "startupMs": 10000,
+      "requestMs": 10000,
+      "executionMs": 30000,
+      "shutdownMs": 5000
+    },
+    "adapters": {
+      "node": {
+        "command": "node",
+        "args": ["/absolute/path/to/dapDebugServer.js", "$PORT", "127.0.0.1"],
+        "environment": {},
+        "transport": {
+          "type": "tcp",
+          "host": "127.0.0.1",
+          "port": 0
+        }
+      }
+    },
+    "profiles": {
+      "node": {
+        "adapter": "node",
+        "arguments": {
+          "type": "pwa-node",
+          "console": "internalConsole",
+          "stopOnEntry": true
+        }
+      }
+    }
+  }
+}
+```
+
+An Adapter Definition needs a non-empty `command` and `transport`; `args` and
+`environment` default to an empty array and object, respectively. `transport` is either `"stdio"` or a
+TCP object with `type: "tcp"`; its host defaults to `127.0.0.1`, and a missing
+or zero port selects a local port. TCP arguments may use `$PORT` anywhere in an
+argument, and Pi DAP also supplies that selected port as `PORT` in the adapter
+environment. `$PORT` is invalid for stdio adapters. Environment strings overlay
+the inherited environment; `null` removes an inherited variable.
+
+A Launch Profile needs an existing Adapter Definition ID and opaque JSON-object
+`arguments`. Global and trusted-project timeouts merge by field. Adapter and
+profile maps merge by ID: a project entry replaces the complete global entry;
+`null` removes it. Invalid project replacements still shadow global entries.
+Invalid entries are quarantined independently and produce path-qualified
+warnings at session start, while unrelated valid entries stay available.
+Untrusted project settings are ignored. Use Pi `/reload` to reload settings.
+
+### Node and TypeScript
+
+Node/TypeScript through Microsoft `vscode-js-debug` is the Supported Adapter
+workflow. For example, set the Node adapter command to `node` and point its TCP
+arguments at `dapDebugServer.js` followed by `$PORT`, as above. Other
+standards-based adapters are Experimental: they may work through DAP but have
+no compatibility promise.
+
+## `dap` tool
+
+Pi DAP registers one strict `dap` tool with exactly these operations:
+
+```text
+launch            set_breakpoints   continue          next
+step_in           step_out          pause             stack
+variables         evaluate          status            stop
+```
+
+`launch` selects a profile (it may be omitted only when exactly one valid
+profile exists). `program`, `args`, and `cwd` replace the same profile
+arguments; relative `program` and `cwd` paths resolve from Pi's project working
+directory. A Debug Session is single-active: launching while one is active
+fails. Desired Breakpoints are complete per-file lists and survive `stop` and
+later launches in the same Pi conversation session; `[]` clears a file.
+Relative breakpoint paths also resolve from Pi's project working directory.
+
+Execution and inspection require a stopped Debuggee: `continue`, `next`,
+`step_in`, `step_out`, `stack`, `variables`, and `evaluate`. `pause` requires a
+running Debuggee. `status` and `stop` are idempotent. `stack` defaults to the
+stopped thread, offset `0`, and count `20`; `variables` takes exactly one
+`frame_id` or `variables_reference` and defaults its count to `100`; `evaluate`
+defaults to the top Stack Frame.
+
+Execution waits end on a stop, exit, cancellation, or `executionMs`; an
+execution timeout reports `running`. Request, startup, and shutdown timeouts
+are errors. A natural exit leaves a terminal snapshot available from `status`
+until the next launch.
+
+## Output and lifecycle
+
+Each successful operation drains currently unread Debuggee output. Pi DAP
+retains at most 1 MiB of unread output, reporting discarded older bytes. Tool
+text follows Pi's 2,000-line/50-KB visible limit; when truncated, the retained
+complete result is written to a Result Spill and its path appears in the
+result. Adapter stderr retains its newest 1 MiB in the session directory and
+process or protocol failures name that path.
+
+Adapters start lazily at `launch`, use the project working directory, and are
+owned by one Pi conversation session. `stop`, launch cancellation, adapter
+failure, and session shutdown attempt DAP termination and disconnect before
+terminating owned Linux process groups. Session shutdown removes session files.
+Cancelling an execution wait only ends that wait; the live Debug Session remains
+recoverable.
+
+### Observer UI
+
+In TUI mode, calls and results use compact semantic transcript rows. Expanding a
+row shows only explicitly supplied arguments and bounded Breakpoint, Stack Frame,
+variable, or evaluation details. Long execution waits update once per second.
+Malformed or historical rows fall back to their original tool text.
+
+One widget above the editor follows launching, running, stopped, and terminated
+activity. It is derived only from lifecycle transitions and successful results
+Pi DAP has already received; it sends no additional DAP request and provides no
+human debugger controls. Stopped source locations clear on resume. The terminal
+snapshot remains for ten seconds, while idle sessions have no widget. RPC, JSON,
+and print modes do not mount it.
+
+The model still receives the unchanged raw `DAP <operation>: <JSON>` text,
+Debuggee output, truncation, and Result Spill notice. Only the human-visible copy
+of Debuggee output is stripped of terminal sequences and unsafe controls; the raw
+tool result and Result Spill retain the original bytes.
+
+## V1 boundary
+
+V1 supports configured stdio and TCP adapters on Linux, one active Debug
+Session, source breakpoints, core execution control, stack/variables/evaluation,
+and headless `runInTerminal`. The Supported `vscode-js-debug` workflow uses one
+adapter-owned primary target channel; it is not a second model-facing Debug
+Session, and unrelated, second, or nested `startDebugging` requests are rejected.
+V1 excludes attach, restart, function/data/instruction breakpoints, hit counts,
+logpoints, memory, disassembly, modules, user-requested child Debug Sessions, raw
+DAP requests, `launch.json`, WebSocket, persistence, and a directly operated
+debugger UI.
+
+Trusted project settings can run arbitrary local executables with Pi's
+permissions. Review adapter commands and configuration before trusting a
+project.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@ian-pascoe/pi-dap",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Configured Debug Adapter Protocol sessions for Pi",
+  "keywords": [
+    "dap",
+    "debug-adapter-protocol",
+    "pi",
+    "pi-extension",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/ian-pascoe/pi-extensions#readme",
+  "bugs": {
+    "url": "https://github.com/ian-pascoe/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Ian Pascoe <ian.g.pascoe@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ian-pascoe/pi-extensions.git",
+    "directory": "packages/pi-dap"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "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": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/dap-observer-ui.ts

@@ -0,0 +1,337 @@
+import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  sliceByColumn,
+  truncateToWidth,
+  visibleWidth,
+  type Component,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import type { DapSessionResult, DapSessionSnapshot } from "./dap-session.js";
+import type { DapToolParameters } from "./dap-tool-contract.js";
+import { workspaceRelativeDapPath } from "./dap-tool-rendering.js";
+import type { DapToolObserver } from "./dap-tool.js";
+
+const DAP_OBSERVER_UI_KEY = "pi-dap";
+const DAP_OBSERVER_REFRESH_MS = 1_000;
+const DAP_OBSERVER_TERMINAL_COOLDOWN_MS = 10_000;
+const DAP_OBSERVER_SEPARATOR = "  ";
+
+/** Theme operations used by the one-line Pi DAP Observer widget. */
+export type DapObserverWidgetTheme = Pick<Theme, "bold" | "fg">;
+
+/** Projected values rendered by the non-authoritative Observer widget. */
+export interface DapObserverWidgetView {
+  /** Current observed lifecycle state; idle has no widget view. */
+  readonly state: "launching" | "running" | "stopped" | "terminated";
+  readonly adapterId?: string;
+  readonly profileId?: string;
+  readonly stopReason?: string;
+  /** Current stopped Stack Frame location, falling back to the explicitly launched program. */
+  readonly path?: string;
+  /** Milliseconds since launch, frozen when termination is observed. */
+  readonly elapsedMs?: number;
+  readonly exitCode?: number;
+}
+
+/** Narrow Pi context needed to mount and notify the Observer UI. */
+export interface DapObserverUiContext {
+  readonly mode: "tui" | "rpc" | "json" | "print";
+  readonly cwd: string;
+  readonly ui: Pick<ExtensionUIContext, "notify" | "setWidget">;
+}
+
+interface DapObserverStateParts {
+  readonly full: string;
+  readonly short: string;
+}
+
+function dapObserverStateParts(
+  view: DapObserverWidgetView,
+  theme: DapObserverWidgetTheme,
+): DapObserverStateParts {
+  switch (view.state) {
+    case "launching":
+      return {
+        full: theme.fg("accent", "▶ launching"),
+        short: theme.fg("accent", "▶ launching"),
+      };
+    case "running":
+      return {
+        full: theme.fg("accent", "▶ running"),
+        short: theme.fg("accent", "▶ running"),
+      };
+    case "stopped": {
+      const short = theme.fg("accent", "● stopped");
+      return {
+        full:
+          view.stopReason === undefined
+            ? short
+            : `${short}${theme.fg("dim", ` · ${view.stopReason}`)}`,
+        short,
+      };
+    }
+    case "terminated": {
+      const short = theme.fg("success", "■ terminated");
+      return {
+        full:
+          view.exitCode === undefined
+            ? short
+            : `${short}${theme.fg("dim", ` · exit ${view.exitCode}`)}`,
+        short,
+      };
+    }
+  }
+}
+
+function formatDapObserverDuration(elapsedMs: number | undefined): string | undefined {
+  if (elapsedMs === undefined) return undefined;
+  const seconds = Math.max(0, Math.floor(elapsedMs / 1_000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes}m ${String(seconds % 60).padStart(2, "0")}s`;
+}
+
+function joinDapObserverParts(parts: readonly (string | undefined)[]): string {
+  return parts.filter((part): part is string => part !== undefined).join(DAP_OBSERVER_SEPARATOR);
+}
+
+/** Render one responsive Observer snapshot without exceeding the terminal width. */
+export function renderDapObserverWidgetLine(
+  view: DapObserverWidgetView,
+  width: number,
+  theme: DapObserverWidgetTheme,
+): string {
+  if (width <= 0) return "";
+  const title = theme.fg("toolTitle", theme.bold("DAP"));
+  const state = dapObserverStateParts(view, theme);
+  const profile =
+    view.adapterId === undefined && view.profileId === undefined
+      ? undefined
+      : theme.fg("muted", `${view.adapterId ?? "?"}/${view.profileId ?? "?"}`);
+  const path = view.path === undefined ? undefined : theme.fg("muted", view.path);
+  const durationValue = formatDapObserverDuration(view.elapsedMs);
+  const duration = durationValue === undefined ? undefined : theme.fg("muted", durationValue);
+  const candidates = [
+    joinDapObserverParts([title, state.full, profile, path, duration]),
+    joinDapObserverParts([title, state.full, profile, path]),
+    joinDapObserverParts([title, state.full, profile]),
+    joinDapObserverParts([title, state.full]),
+    joinDapObserverParts([title, state.short]),
+  ];
+  const fitting = candidates.find((candidate) => visibleWidth(candidate) <= width);
+  if (fitting !== undefined) return fitting;
+
+  if (visibleWidth(title) >= width) return truncateToWidth(title, width, "…");
+  const stateWidth = Math.max(
+    0,
+    width - visibleWidth(title) - visibleWidth(DAP_OBSERVER_SEPARATOR),
+  );
+  const shortenedState = sliceByColumn(state.short, 0, stateWidth, true);
+  return truncateToWidth(joinDapObserverParts([title, shortenedState || undefined]), width, "…");
+}
+
+class DapObserverWidgetComponent implements Component {
+  constructor(
+    private view: DapObserverWidgetView,
+    private readonly tui: TUI,
+    private readonly theme: DapObserverWidgetTheme,
+  ) {}
+
+  update(view: DapObserverWidgetView): void {
+    this.view = view;
+    this.tui.requestRender();
+  }
+
+  render(width: number): string[] {
+    return [renderDapObserverWidgetLine(this.view, width, this.theme)];
+  }
+
+  invalidate(): void {}
+}
+
+/** Own one TUI-only Observer snapshot, widget, refresh interval, cooldown, and cleanup. */
+export class DapObserverUiController implements DapToolObserver {
+  private activeToolCalls = 0;
+  private disposed = false;
+  private launchStartedAt: number | undefined;
+  private terminalElapsedMs: number | undefined;
+  private launchedProgram: string | undefined;
+  private sourceLocation: string | undefined;
+  private snapshot: DapSessionSnapshot = { state: "idle" };
+  private currentView: DapObserverWidgetView | undefined;
+  private widgetComponent: DapObserverWidgetComponent | undefined;
+  private widgetMounted = false;
+  private refreshInterval: ReturnType<typeof setInterval> | undefined;
+  private cooldownTimeout: ReturnType<typeof setTimeout> | undefined;
+
+  /** Construct an inert Observer UI; the first launch tool call mounts its widget. */
+  constructor(private readonly context: DapObserverUiContext) {}
+
+  /** Record tool activity without dispatching any Debug Adapter operation. */
+  onToolStart(parameters: DapToolParameters): void {
+    if (this.disposed) return;
+    this.activeToolCalls++;
+    if (parameters.operation !== "launch") return;
+    this.clearCooldown();
+    this.launchStartedAt = Date.now();
+    this.terminalElapsedMs = undefined;
+    this.launchedProgram =
+      parameters.program === undefined
+        ? undefined
+        : workspaceRelativeDapPath(this.context.cwd, parameters.program);
+    this.sourceLocation = undefined;
+    this.snapshot = { state: "launching", adapterId: "?", profileId: parameters.profile ?? "?" };
+    this.ensureRefreshInterval();
+    this.refreshWidget();
+  }
+
+  /** Learn source location only from a successful result already returned by the tool. */
+  onToolSuccess(_parameters: DapToolParameters, result: DapSessionResult): void {
+    if (this.disposed) return;
+    this.activeToolCalls = Math.max(0, this.activeToolCalls - 1);
+    if (this.snapshot.state === "stopped") {
+      const frame = result.stackFrames?.[0];
+      const source = frame?.source?.path ?? frame?.source?.name;
+      if (frame !== undefined && source !== undefined) {
+        this.sourceLocation = `${workspaceRelativeDapPath(this.context.cwd, source)}:${frame.line}`;
+      }
+    }
+    this.refreshWidget();
+  }
+
+  /** Complete failed tool activity while leaving model-facing failure behavior unchanged. */
+  onToolFailure(parameters: DapToolParameters, _error: Error): void {
+    if (this.disposed) return;
+    this.activeToolCalls = Math.max(0, this.activeToolCalls - 1);
+    if (parameters.operation === "launch" && this.snapshot.state === "launching") {
+      this.snapshot = { state: "idle" };
+      this.clearRefreshInterval();
+      this.hideWidget();
+    }
+  }
+
+  /** Project one actual Debug Session lifecycle transition into the Observer snapshot. */
+  onSessionSnapshot(snapshot: DapSessionSnapshot): void {
+    if (this.disposed) return;
+    if (snapshot.state !== "stopped" || this.snapshot.state !== "stopped") {
+      this.sourceLocation = undefined;
+    }
+    this.snapshot = snapshot;
+    if (snapshot.state === "idle") {
+      this.clearRefreshInterval();
+      this.clearCooldown();
+      this.hideWidget();
+      return;
+    }
+    if (snapshot.state === "terminated") {
+      this.terminalElapsedMs =
+        this.launchStartedAt === undefined ? undefined : Date.now() - this.launchStartedAt;
+      this.clearRefreshInterval();
+      this.refreshWidget();
+      this.ensureCooldown();
+      return;
+    }
+    this.clearCooldown();
+    this.ensureRefreshInterval();
+    this.refreshWidget();
+  }
+
+  /** Notify only an actionable asynchronous failure not represented by an active tool result. */
+  onUnexpectedFailure(error: Error): void {
+    if (this.disposed || this.activeToolCalls > 0) return;
+    const message = error.message.startsWith("Pi DAP:")
+      ? error.message
+      : `Pi DAP: ${error.message}`;
+    this.context.ui.notify(message, "error");
+  }
+
+  /** Dispose timers and the widget immediately; repeated disposal is inert. */
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.clearRefreshInterval();
+    this.clearCooldown();
+    this.hideWidget();
+  }
+
+  private observerWidgetView(): DapObserverWidgetView | undefined {
+    if (this.snapshot.state === "idle") return undefined;
+    const elapsedMs =
+      this.snapshot.state === "terminated"
+        ? this.terminalElapsedMs
+        : this.launchStartedAt === undefined
+          ? undefined
+          : Date.now() - this.launchStartedAt;
+    const path = this.sourceLocation ?? this.launchedProgram;
+    let view: DapObserverWidgetView = { state: this.snapshot.state };
+    if ("adapterId" in this.snapshot) view = { ...view, adapterId: this.snapshot.adapterId };
+    if ("profileId" in this.snapshot) view = { ...view, profileId: this.snapshot.profileId };
+    if (this.snapshot.state === "stopped") {
+      view = { ...view, stopReason: this.snapshot.stopReason };
+    }
+    if (this.snapshot.state === "terminated" && this.snapshot.exitCode !== undefined) {
+      view = { ...view, exitCode: this.snapshot.exitCode };
+    }
+    if (path !== undefined) view = { ...view, path };
+    if (elapsedMs !== undefined) view = { ...view, elapsedMs };
+    return view;
+  }
+
+  private refreshWidget(): void {
+    if (this.context.mode !== "tui") return;
+    const view = this.observerWidgetView();
+    this.currentView = view;
+    if (view === undefined) {
+      this.hideWidget();
+      return;
+    }
+    if (this.widgetMounted) {
+      this.widgetComponent?.update(view);
+      return;
+    }
+    this.context.ui.setWidget(
+      DAP_OBSERVER_UI_KEY,
+      (tui, theme) => {
+        this.widgetComponent = new DapObserverWidgetComponent(this.currentView ?? view, tui, theme);
+        return this.widgetComponent;
+      },
+      { placement: "aboveEditor" },
+    );
+    this.widgetMounted = true;
+  }
+
+  private hideWidget(): void {
+    if (this.context.mode !== "tui" || !this.widgetMounted) return;
+    this.context.ui.setWidget(DAP_OBSERVER_UI_KEY, undefined);
+    this.widgetMounted = false;
+    this.widgetComponent = undefined;
+  }
+
+  private ensureRefreshInterval(): void {
+    if (this.context.mode !== "tui" || this.refreshInterval !== undefined) return;
+    this.refreshInterval = setInterval(() => this.refreshWidget(), DAP_OBSERVER_REFRESH_MS);
+    this.refreshInterval.unref?.();
+  }
+
+  private clearRefreshInterval(): void {
+    if (this.refreshInterval === undefined) return;
+    clearInterval(this.refreshInterval);
+    this.refreshInterval = undefined;
+  }
+
+  private ensureCooldown(): void {
+    if (this.context.mode !== "tui") return;
+    this.clearCooldown();
+    this.cooldownTimeout = setTimeout(() => {
+      this.cooldownTimeout = undefined;
+      this.hideWidget();
+    }, DAP_OBSERVER_TERMINAL_COOLDOWN_MS);
+    this.cooldownTimeout.unref?.();
+  }
+
+  private clearCooldown(): void {
+    if (this.cooldownTimeout === undefined) return;
+    clearTimeout(this.cooldownTimeout);
+    this.cooldownTimeout = undefined;
+  }
+}