@i-scope/dap-adapter

Part of the @i-scope/debugger SDK — one of seven leaf packages aggregated by the @i-scope/debugger meta-umbrella. Most users should install the meta (npm install @i-scope/debugger), which transitively pulls this package in together with the MCP server and the rest of the SDK. Install @i-scope/dap-adapter directly only when you embed the DAP adapter into a non-MCP host (custom IDE, WebStorm plugin, @vscode/debugadapter-testsupport harness) and have no need for the MCP layer on top.

Debug Adapter Protocol (DAP) implementation for iScope .ajs scripts running in Oscilloscope.exe.

Ships two ways to consume:

• Stand-alone stdio DAP server — npx iscope-debug-server (or node node_modules/@i-scope/dap-adapter/dist/src/server.js). Any DAP client (VS Code, Cursor, @vscode/debugadapter-testsupport, @i-scope/mcp-server, plain raw clients) can drive it.
• Embeddable AjsDebugSession — new AjsDebugSession(deps) inside your own process. Used by the iScope VS Code extension through vscode.DebugAdapterInlineImplementation.

Either way the protocol on stdio is identical — only the dependency- injection shape varies.

Install

npm install @i-scope/dap-adapter

Windows only (the underlying @i-scope/iscope-bridge helper is a Win32 native binary). A working install of Oscilloscope.exe v5+ is required at runtime.

Quick start — headless DAP server

# From a shell:
npx iscope-debug-server          # speaks DAP on stdin/stdout

Most users do NOT drive the server by hand — they connect a DAP client (VS Code, Cursor, an MCP agent). The minimal hand-driven session is:

// → initialize
{ "seq": 1, "type": "request", "command": "initialize",
  "arguments": { "adapterID": "iscope-ajs",
                 "linesStartAt1": true, "columnsStartAt1": true } }
// → launch
{ "seq": 2, "type": "request", "command": "launch",
  "arguments": { "type": "iscope-ajs", "program": "C:/scripts/probe.ajs",
                 "mwfFile": "C:/Oscillograms/sample.mwf",
                 "autoLaunch": true } }
// ... handle DAP responses + events as per the spec

Quick start — embedded AjsDebugSession

import {
    AjsDebugSession,
    type AjsSessionDeps,
} from '@i-scope/dap-adapter';
import { resolveHelperPath } from '@i-scope/iscope-bridge-client';

const deps: AjsSessionDeps = {
    resolveHelperPath: (userOverride) => resolveHelperPath({ userOverride }),
    getSetting:        <T>(_key: string, fallback: T) => fallback,
    getWorkspaceState: () => undefined,
    setWorkspaceState: () => { /* no-op */ },
    log:               (line) => process.stderr.write(`[adapter] ${line}\n`),
    // Optional UX callback. Headless callers omit it; VS Code wires a
    // Browse-for-Oscilloscope.exe dialog here.
    promptOscMissing:  undefined,
};

const session = new AjsDebugSession(deps);
session.start(process.stdin, process.stdout);

What's supported

• Lifecycle: initialize, launch (.ajs + .ts→.ajs resolution), configurationDone, disconnect (graceful + cancel).
• Breakpoints: setBreakpointsRequest per-source, buffered until configurationDone or installed mid-run via SetResetBrkPnt RPCs.
• Execution: continue, next (step over), stepIn, stepOut.
• Inspection: stackTrace (multi-frame), scopes (Locals per frame), variables (compound drill-down via VLST), evaluate (Watch/Hover/REPL), exceptionInfoRequest.
• Source maps: TS↔AJS bidirectional via @i-scope/source-map-bridge.
• Diagnostic output: Host.ReportOut traces routed by level (1 → stdout [INFO], 2 → stdout [WARN], 3+ → stderr [ERR]), helper.exe lifecycle / setup chatter on category=console.

Architecture

DAP client (VS Code / MCP / inspect.cjs / raw)
        ↕ stdio (DAP wire)
AjsDebugSession  ◄────────── extends LoggingDebugSession from @vscode/debugadapter
    │
    ├── IScopeBridge        ◄──── @i-scope/iscope-bridge-client (this package's RPC peer)
    │     ↕ stdio (JSON-RPC framed)
    │   iScopeBridge.exe    ◄──── @i-scope/iscope-bridge (native Win32 helper)
    │     ↕ COM / IConnectionPoint
    │   Oscilloscope.exe
    │
    └── SourceMapManager    ◄──── @i-scope/source-map-bridge

AjsSessionDeps

Dependency-injection contract. Required:

| Field | Purpose | |-----------------------|---------------------------------------------------| | resolveHelperPath | Locate iScopeBridge.exe given a user override. | | getSetting | Look up a setting key with a fallback. | | getWorkspaceState | Read persistent kv state (last-script-run, …). | | setWorkspaceState | Write the same kv state. |

Optional:

| Field | Purpose | |-----------------------------|------------------------------------------------------------------------| | log(line) | Adapter-internal diagnostic channel (separate from the Debug Console). | | showErrorWithDownloadLink | Surface a pre-flight error with a "Download" button. | | promptOscMissing() | UX flow when Oscilloscope.exe path resolution fails (OSC_NOT_FOUND). |

Headless callers can leave every optional field unset — the adapter falls back to sane defaults (write to stderr, propagate errors as DAP failures).

Related packages

This package is one of seven leaves of the @i-scope/debugger SDK meta-umbrella. The full family:

| Package | Role | |---------|------| | @i-scope/debugger | meta — one-install entry point for the whole SDK | | @i-scope/mcp-server | MCP server for AI agents (22 tools) | | @i-scope/dap-adapter (you are here) | DAP server (AjsDebugSession) — embeddable + stdio | | @i-scope/iscope-bridge-client | Node JSON-RPC client to the native helper | | @i-scope/iscope-bridge | Win32 native helper binary (iScopeBridge.exe) | | @i-scope/source-map-bridge | TS ↔ AJS source-map manager | | @i-scope/vlst-parser | Parser for VLST locals/Watch blobs | | @i-scope/com-protocol-types | TS-mirror of COM DISPID / event constants |

License

MIT — see LICENSE.

Repository

Part of the iScope Debugger monorepo: https://gitlab.com/i-scope/Debugger