From 3afc87926be1c7e6061a58ed9ef1559eb40461e4 Mon Sep 17 00:00:00 2001 From: Franklin Castillo Date: Wed, 5 Aug 2026 17:59:59 -0400 Subject: [PATCH] docs(coding-agent): clarify js-debug-adapter install is not an npm package The "js-debug-adapter not available" message and the debug doc only mentioned Mason and JS_DEBUG_DAP_SERVER, leaving users to try `npm i -g js-debug-adapter`, which 404s: js-debug-adapter is the omp adapter id, not an installable package. Surface the supported installs (Mason; the standalone vscode-js-debug release tarball extracted to ~/.local/opt/js-debug/, which resolveJsDebugServerPath already auto-discovers; or JS_DEBUG_DAP_SERVER) in both the error message and docs/tools/debug.md. Refs #7757. --- docs/tools/debug.md | 11 ++++++++++- packages/coding-agent/CHANGELOG.md | 4 ++++ packages/coding-agent/src/tools/debug.ts | 2 +- 3 files changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/tools/debug.md b/docs/tools/debug.md index b96a1824a..f6bc58711 100644 --- a/docs/tools/debug.md +++ b/docs/tools/debug.md @@ -330,7 +330,16 @@ Example `.omp/dap.json`: ## Notes - `packages/coding-agent/src/prompts/tools/debug.md` tells the model only one active root session is supported. Adapter-requested child sessions belong to that root tree. -- The default JavaScript/TypeScript adapter runs vscode-js-debug’s `dapDebugServer.js` over TCP. Install it with Mason or set `JS_DEBUG_DAP_SERVER` to a release-tarball server path. +- The default JavaScript/TypeScript adapter runs vscode-js-debug's `dapDebugServer.js` over TCP. It is **not** an npm package — `npm i -g js-debug-adapter` 404s (`js-debug-adapter` is the omp adapter id, not an installable package). Install `dapDebugServer.js` (requires `node` on `PATH`) one of these ways; the first two are auto-discovered by `resolveJsDebugServerPath()` in `packages/coding-agent/src/dap/config.ts`: + - Mason (`:MasonInstall js-debug-adapter`) → discovered at `~/.local/share/nvim/mason/packages/js-debug-adapter/js-debug/src/dapDebugServer.js`. + - Standalone release tarball, extracted so `dapDebugServer.js` lands at `~/.local/opt/js-debug/src/dapDebugServer.js`: + ```sh + curl -sL -o js-debug-dap.tar.gz \ + https://github.com/microsoft/vscode-js-debug/releases/download/v1.117.0/js-debug-dap-v1.117.0.tar.gz + mkdir -p ~/.local/opt && tar -xzf js-debug-dap.tar.gz -C ~/.local/opt + ``` + Replace `v1.117.0` with the latest tag from the [releases page](https://github.com/microsoft/vscode-js-debug/releases). + - Any other location via `JS_DEBUG_DAP_SERVER=`. - `configurationDone` is sent automatically during root and child launch/attach handshakes and lazily before later requests if the initial handshake did not complete. - `startDebugging` reverse requests create recursive child sessions on the same TCP server; a stopped child becomes the target for thread-level actions. - `output` exposes the active session’s merged `output` event stream only; the tool does not distinguish stdout, stderr, and console categories. diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md index 456e88609..2aa0a5c33 100644 --- a/packages/coding-agent/CHANGELOG.md +++ b/packages/coding-agent/CHANGELOG.md @@ -2,6 +2,10 @@ ## [Unreleased] +### Changed + +- Clarified the JavaScript/TypeScript debug adapter install path: `js-debug-adapter` is the omp adapter id, not an npm package, so `npm i -g js-debug-adapter` 404s. The docs and the "adapter not available" message now point to the supported installs — Mason, the standalone release tarball extracted to `~/.local/opt/js-debug/` (auto-discovered), or `JS_DEBUG_DAP_SERVER` ([#7757](https://github.com/can1357/oh-my-pi/issues/7757)). + ## [17.2.9] - 2026-08-05 ### Breaking Changes diff --git a/packages/coding-agent/src/tools/debug.ts b/packages/coding-agent/src/tools/debug.ts index fce5bca93..1590475da 100644 --- a/packages/coding-agent/src/tools/debug.ts +++ b/packages/coding-agent/src/tools/debug.ts @@ -505,7 +505,7 @@ const ADAPTER_UNAVAILABLE_MESSAGES: Readonly> = { dlv: "adapter 'dlv' is not available: install with 'go install github.com/go-delve/delve/cmd/dlv@latest'", rdbg: "adapter 'rdbg' is not available: install with 'gem install debug'", "js-debug-adapter": - "adapter 'js-debug-adapter' is not available: install vscode-js-debug with Mason or set JS_DEBUG_DAP_SERVER to dapDebugServer.js", + "adapter 'js-debug-adapter' is not available: vscode-js-debug is not an npm package — install via Mason (`:MasonInstall js-debug-adapter`), extract the release tarball (https://github.com/microsoft/vscode-js-debug/releases) to ~/.local/opt/js-debug/, or set JS_DEBUG_DAP_SERVER to dapDebugServer.js", }; const ADAPTER_CANONICAL_COMMANDS: Readonly> = {