@i-scope/mcp-server 0.4.2

package/src/bridge-driver.ts

@@ -0,0 +1,328 @@
+// BridgeDriver — direct (non-DAP) RPC access to iScopeBridge.exe.
+//
+// Live home of:
+//   - ui_modal_list  / click / fill / dismiss          (MCP UI plan)
+//   - system_preflight_check                            (Phase 1, MDM detection)
+//   - system_abi_check                                  (wire ABI via protocol/version)
+//
+// Reserved for Phase 2/3 expansion:
+//   - control_open_file       (BridgeDriver.openFile)
+//   - control_get_status      (BridgeDriver.getStatus)
+//   - control_run_script      (BridgeDriver.executeFile without debug)
+//   - control_close_application
+//   - data_* (TBD — needs helper-cpp extensions)
+//
+// Why a separate class from DapDriver:
+//   DapDriver OWNS a `debug-server.js` child which in turn owns its
+//   own iScopeBridge.exe (via `extension/.../com/bridge.ts`). For
+//   non-debug operations we don't want to pay the cost of a full DAP
+//   session — a direct helper child is plenty. The two drivers may
+//   coexist: COM lets multiple clients attach to Oscilloscope, so an
+//   AI agent can simultaneously hold a DAP session AND poll modal
+//   state via `ui_modal_list`.
+//
+// Lifecycle (two-stage state machine):
+//
+//                ensureSpawned        ensureReady
+//                ────────────►        ────────────►
+//      'idle'  ─────────────► 'spawned' ──────────► 'ready'
+//        ▲                      │                     │
+//        │     disconnect()     │   disconnect()      │
+//        └──────────────────────┴─────────────────────┘
+//
+//   - `ensureSpawned()` — guarantees the helper child is running and its
+//     stdio JSON-RPC loop is alive. Required for the `preflight/check`
+//     method which is registry-only and does NOT need a live COM
+//     connection (the MCP `system_preflight_check` tool runs even on a
+//     box where Oscilloscope is not installed).
+//   - `ensureReady()`   — additionally guarantees `bridge.initialize()`
+//     has succeeded, i.e. the helper is connected to Oscilloscope's COM
+//     server. Required for every ui_modal_* method. Internally calls
+//     `ensureSpawned()` first so it works from a cold start AND from a
+//     warm state where preflight already spawned the helper.
+//   - `disconnect()`    — full teardown. Resets state to `idle`.
+//
+//   Both methods are idempotent and serialise concurrent callers via
+//   a single `lifecyclePromise` mutex — two parallel `ensureReady()`
+//   calls (one from a `ui_modal_list` tool, one from `ui_modal_click`
+//   chained right behind it) share the same spawn AND the same
+//   initialize. Failed transitions reset the relevant boolean so the
+//   next caller retries from the appropriate stage.
+//
+//   `attachPolicy='attachOnly'` by default — we never auto-launch
+//   Oscilloscope just because the agent asked to list modals; if
+//   osc isn't running, `initialize()` returns connected=false and the
+//   calling tool surfaces a friendly "Oscilloscope is not running"
+//   error to the AI.
+
+import {
+    IScopeBridge,
+    resolveHelperPath,
+    type AbiPolicy,
+    type PreflightCheckResponse,
+    type UIModalClickRequest,
+    type UIModalClickResponse,
+    type UIModalDismissRequest,
+    type UIModalDismissResponse,
+    type UIModalFillRequest,
+    type UIModalFillResponse,
+    type UIModalListResponse,
+} from '@i-scope/iscope-bridge-client';
+
+import { evaluateAbiCheck, type AbiCheckResult } from './abi-check.js';
+
+export type { AbiCheckResult } from './abi-check.js';
+
+export interface BridgeDriverOptions {
+    /** Explicit override; otherwise resolveHelperPath() runs. */
+    helperPath?: string;
+    /** Optional bundledRoot forwarded to resolveHelperPath. */
+    bundledRoot?: string;
+    /** Per-RPC timeout. Defaults to 10 000 ms. */
+    requestTimeoutMs?: number;
+    /** Diagnostic line sink (typically stderr writer). */
+    log?: (line: string) => void;
+}
+
+/**
+ * Lightweight wrapper around `IScopeBridge` that exposes the
+ * UI-modal-control + pre-flight surface to MCP tools. Spawns its own
+ * helper child on demand; safe to coexist with an active DAP session
+ * that also holds an iScopeBridge.exe.
+ */
+export class BridgeDriver {
+    private readonly opts: BridgeDriverOptions;
+
+    // ---- State-machine fields ------------------------------------------------
+    //
+    // Two booleans rather than a single discriminated enum because the
+    // transitions are linear (idle → spawned → ready) and we frequently
+    // need to ask "are we at-or-past stage X?" — booleans answer that
+    // in one read. Invariant: `initialized` implies `spawned`, which
+    // implies `bridge !== null`.
+    private bridge: IScopeBridge | null = null;
+    private spawned = false;
+    private initialized = false;
+    /**
+     * Single mutex protecting any in-flight transition (spawn or
+     * initialize). Non-null while a transition is running. Concurrent
+     * callers await the same promise instead of starting a second
+     * transition, which would race against the first (e.g. two spawn
+     * calls would leak a second helper child; a spawn racing an init
+     * could initialize a stale handle). `disconnect()` also awaits
+     * this so we never tear the helper down mid-transition.
+     */
+    private lifecyclePromise: Promise<void> | null = null;
+
+    constructor(opts: BridgeDriverOptions = {}) {
+        this.opts = opts;
+    }
+
+    /**
+     * Ensure the helper child is spawned + its JSON-RPC loop alive.
+     * Does NOT call `initialize()`. Idempotent. Use this for the
+     * `preflight/check` path which is registry-only and must work on
+     * machines where Oscilloscope is not installed or not running.
+     */
+    private async ensureSpawned(): Promise<IScopeBridge> {
+        // Wait until any in-flight transition (spawn or init) settles
+        // so our state read below is consistent.
+        await this.awaitLifecycleSettled();
+        if (this.spawned && this.bridge) return this.bridge;
+
+        // Serialise the spawn behind the mutex so a parallel caller
+        // does not start a SECOND helper child. Re-check inside the
+        // critical section in case another caller spawned while we
+        // were queued.
+        const transition = (async (): Promise<void> => {
+            if (this.spawned && this.bridge) return;
+            const br = this.spawnHelper();
+            br.start();
+            this.bridge = br;
+            this.spawned = true;
+        })();
+        await this.runTransition(transition);
+
+        if (!this.bridge) throw new Error('BridgeDriver spawn failed');
+        return this.bridge;
+    }
+
+    /**
+     * Ensure the helper child is spawned AND `initialize()`d (i.e.
+     * connected to Oscilloscope's COM server). Idempotent. Calls
+     * `ensureSpawned()` internally so it works from a cold start AND
+     * from a warm state where `preflightCheck()` already spawned the
+     * helper.
+     */
+    private async ensureReady(): Promise<IScopeBridge> {
+        const br = await this.ensureSpawned();
+        await this.awaitLifecycleSettled();
+        if (this.initialized && this.bridge) return this.bridge;
+
+        // Serialise the initialize call behind the mutex. Failure
+        // leaves `spawned=true, initialized=false` so the next caller
+        // can retry the initialize step without re-spawning.
+        const transition = (async (): Promise<void> => {
+            if (this.initialized && this.bridge) return;
+            if (!this.spawned || !this.bridge) {
+                // disconnect() ran between ensureSpawned and the mutex
+                // becoming available. Surface a clear error so the
+                // caller knows to retry from scratch.
+                throw new Error(
+                    'BridgeDriver: helper not spawned (lost race with disconnect)',
+                );
+            }
+            // autoLaunch=false: we never auto-spawn Oscilloscope from a
+            // UI tool. If osc is not running, `initialize` will throw
+            // (or return connected=false depending on helper config)
+            // and the calling tool surfaces a friendly "Oscilloscope
+            // is not running" error to the AI.
+            await this.bridge.initialize({ autoLaunch: false });
+            this.initialized = true;
+        })();
+        await this.runTransition(transition);
+
+        if (!this.bridge) throw new Error('BridgeDriver init failed');
+        return br;
+    }
+
+    /**
+     * Block until any in-flight `lifecyclePromise` resolves or rejects.
+     * Loops because a fresh transition may start while we await the
+     * current one (e.g. parallel callers chained through the mutex).
+     * Swallows rejections — the caller re-reads the boolean state and
+     * decides whether to retry. */
+    private async awaitLifecycleSettled(): Promise<void> {
+        while (this.lifecyclePromise) {
+            const p = this.lifecyclePromise;
+            try {
+                await p;
+            } catch {
+                /* let the caller re-inspect spawned/initialized */
+            }
+            if (this.lifecyclePromise === p) this.lifecyclePromise = null;
+        }
+    }
+
+    /** Install `promise` as the current `lifecyclePromise`, await it,
+     *  and clear the slot on completion. The caller has already
+     *  awaited the previous transition via `awaitLifecycleSettled()`,
+     *  so installing here is race-free. */
+    private async runTransition(promise: Promise<void>): Promise<void> {
+        // Guard form — never store a rejected promise in the slot.
+        // Without this, a concurrent `await this.lifecyclePromise`
+        // would synchronously re-throw the same rejection.
+        const guard = promise.then(() => {}, () => {});
+        this.lifecyclePromise = guard;
+        try {
+            await promise;
+        } finally {
+            if (this.lifecyclePromise === guard) this.lifecyclePromise = null;
+        }
+    }
+
+    /** Construct an IScopeBridge with our standard wiring. Does NOT
+     *  start the helper child — the caller decides between
+     *  `start()` only (preflight path) and `start() + initialize()`
+     *  (full ready path). */
+    private spawnHelper(): IScopeBridge {
+        const helperPath =
+            this.opts.helperPath
+            ?? resolveHelperPath({ bundledRoot: this.opts.bundledRoot });
+        this.log(`[BridgeDriver] spawning helper: ${helperPath}`);
+        return new IScopeBridge({
+            helperPath,
+            requestTimeoutMs: this.opts.requestTimeoutMs ?? 10_000,
+            onStderr: (chunk) => this.log(`[helper-stderr] ${chunk.trimEnd()}`),
+        });
+    }
+
+    private log(line: string): void {
+        if (this.opts.log) this.opts.log(line);
+    }
+
+    // ---- UI modal control ----------------------------------------------------
+
+    async uiModalList(): Promise<UIModalListResponse> {
+        const br = await this.ensureReady();
+        return br.uiModalList();
+    }
+
+    async uiModalClick(args: UIModalClickRequest): Promise<UIModalClickResponse> {
+        const br = await this.ensureReady();
+        return br.uiModalClick(args);
+    }
+
+    async uiModalFill(args: UIModalFillRequest): Promise<UIModalFillResponse> {
+        const br = await this.ensureReady();
+        return br.uiModalFill(args);
+    }
+
+    async uiModalDismiss(args: UIModalDismissRequest): Promise<UIModalDismissResponse> {
+        const br = await this.ensureReady();
+        return br.uiModalDismiss(args);
+    }
+
+    // ---- Pre-flight check (Phase 1, MDM detection) -------------------------
+    // Uses `ensureSpawned` rather than `ensureReady` because the C++
+    // `preflight/check` handler is registry-only and must work on a
+    // machine where Oscilloscope is not installed or not running.
+    // The state-machine contract guarantees that any subsequent
+    // `ui_modal_*` call from the same MCP server session will then
+    // promote the helper from `spawned` to `ready` via `ensureReady`,
+    // running `initialize()` exactly once — without this two-stage
+    // design, `preflightCheck` would set `bridge !== null` and a
+    // single-flag `ensureReady` would short-circuit, leaving the
+    // helper un-initialised when the first ui_modal_* call arrives
+    // (B1 regression, fixed 2026-05-19; see test 23-preflight-then-ui).
+
+    async preflightCheck(): Promise<PreflightCheckResponse> {
+        const br = await this.ensureSpawned();
+        return br.preflightCheck();
+    }
+
+    /** Wire ABI probe via `protocol/version` — no `initialize()`, no COM. */
+    async abiCheck(policy?: AbiPolicy): Promise<AbiCheckResult> {
+        const br = await this.ensureSpawned();
+        const version = await br.protocolVersion();
+        return evaluateAbiCheck(version, policy ?? 'strict');
+    }
+
+    // ---- Phase 2/3 placeholders ---------------------------------------------
+
+    async openFile(_path: string): Promise<void> {
+        throw new Error('BridgeDriver.openFile not yet implemented (Phase 2)');
+    }
+
+    async getStatus(): Promise<{ status: number; name: string }> {
+        throw new Error('BridgeDriver.getStatus not yet implemented (Phase 2)');
+    }
+
+    async runScript(_args: { file: string; mwfFile?: string }): Promise<void> {
+        throw new Error('BridgeDriver.runScript not yet implemented (Phase 2)');
+    }
+
+    // ---- Lifecycle -----------------------------------------------------------
+
+    /** Tear down the helper child. Idempotent. Resets state to `idle`.
+     *  Waits for any in-flight transition (spawn or initialize) to
+     *  settle first so we never `forceStop` a helper mid-handshake. */
+    async disconnect(): Promise<void> {
+        await this.awaitLifecycleSettled();
+        const br = this.bridge;
+        this.bridge = null;
+        this.spawned = false;
+        this.initialized = false;
+        if (!br) return;
+        try {
+            await br.shutdown({ closePolicy: 'ifWeLaunched' });
+        } catch (e) {
+            this.log(`[BridgeDriver] shutdown error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        try {
+            br.forceStop();
+        } catch {
+            /* helper might already be dead */
+        }
+    }
+}

package/src/dap-client.ts

@@ -0,0 +1,336 @@
+// Minimal stand-alone Debug Adapter Protocol client.
+//
+// Why we don't reuse @vscode/debugadapter-testsupport:
+//   That package is Microsoft's own test harness — fine for the
+//   adapter author, BUT (a) the name screams "test only" and scares
+//   anyone reading our published package.json, and (b) it's a
+//   *testsupport* artefact: Microsoft do not promise API stability
+//   across minor versions. A breaking change in a 1.69.x → 1.70.x
+//   bump would silently break every npm install of our MCP server.
+//
+//   The wire is just JSON-over-stdio with a `Content-Length: N\r\n
+//   \r\n<body>` framing — too small to justify a runtime dependency
+//   for a public package. Hence: ~250 LOC of our own, tailored to
+//   the surface DapDriver actually needs.
+//
+// Surface (intentionally narrower than DebugClient's):
+//   - `start()` / `stop()` lifecycle.
+//   - `request<T>(command, args?, timeoutMs?)` → resolves with
+//     `response.body` (or rejects with the response.message).
+//   - `waitForEvent<T>(name, timeoutMs?)` → resolves with the next
+//     event of that name.
+//   - EventEmitter semantics for unsolicited events (`output`,
+//     `stopped`, `continued`, `terminated`, `exited`, ...) — callers
+//     attach `.on(name, handler)` like they would on any Node
+//     EventEmitter.
+//
+// Out of scope (versus DebugClient):
+//   - Convenience wrappers like `initializeRequest(args)` —
+//     `dc.request('initialize', args)` is enough.
+//   - Reverse requests (the server's `request` direction, e.g.
+//     `runInTerminal`). The iScope adapter never issues those.
+//   - `hitBreakpoint()` / `assertStoppedLocation()` test helpers.
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+
+import type { DebugProtocol } from '@vscode/debugprotocol';
+
+export interface DapClientOptions {
+    /** Runtime to spawn (typically 'node'). Defaults to 'node'. */
+    runtime?: string;
+    /** Absolute path to the .js / .cjs adapter entry point. */
+    executable: string;
+    /** Extra argv for the runtime, AFTER `executable`. Rarely used —
+     *  DAP adapters typically take no argv. */
+    args?: string[];
+    /** Environment for the child. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Working directory for the child. */
+    cwd?: string;
+    /** Per-request default timeout. Defaults to 30 000 ms. */
+    defaultTimeoutMs?: number;
+    /** Inherit the child's stderr into the parent's stderr. true is
+     *  the right default for production (we surface adapter logs).
+     *  Set false in unit tests if the log noise bothers you. */
+    inheritStderr?: boolean;
+    /** Diagnostic logger. Defaults to no-op. */
+    log?: (line: string) => void;
+}
+
+/** Internal record for an in-flight DAP request, keyed by `seq`. */
+interface PendingRequest {
+    resolve: (body: unknown) => void;
+    reject:  (err: Error) => void;
+    timer:   NodeJS.Timeout;
+    command: string;
+}
+
+const NO_LOG = (_: string): void => { /* no-op */ };
+
+/**
+ * Stand-alone DAP client. Inherits from EventEmitter for event
+ * subscription. Type-safe `request<T>` and `waitForEvent<T>` give
+ * callers the response body / event payload directly.
+ */
+export class DapClient extends EventEmitter {
+    private readonly runtime: string;
+    private readonly executable: string;
+    private readonly args: string[];
+    private readonly env: NodeJS.ProcessEnv;
+    private readonly cwd: string | undefined;
+    private readonly inheritStderr: boolean;
+    private readonly log: (line: string) => void;
+
+    private child: ChildProcess | null = null;
+    private childExited = false;
+
+    /** Monotonic outgoing message id. DAP spec: `seq` is per-sender
+     *  and increases by one per message; the OTHER side has its own
+     *  `seq` axis we ignore. */
+    private nextSeq = 1;
+
+    /** Accumulating stdout buffer. We pull complete frames out of
+     *  it as they arrive. Type widened to ArrayBufferLike to match
+     *  what `Buffer.concat` and `Buffer#subarray` return in
+     *  @types/node 22+. */
+    private rxBuffer: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+    /** Once we see `Content-Length: N\r\n\r\n` we remember N here
+     *  until we've consumed exactly N bytes of body. -1 = "still
+     *  parsing the header". */
+    private rxContentLength = -1;
+
+    /** seq → outstanding request. We never await a response by
+     *  `command` alone — two simultaneous `stackTrace`s would
+     *  collide. `seq` is the only safe key. */
+    private readonly pending = new Map<number, PendingRequest>();
+
+    public defaultTimeoutMs: number;
+
+    constructor(opts: DapClientOptions) {
+        super();
+        this.runtime          = opts.runtime ?? 'node';
+        this.executable       = opts.executable;
+        this.args             = opts.args ?? [];
+        this.env              = opts.env ?? process.env;
+        this.cwd              = opts.cwd;
+        this.inheritStderr    = opts.inheritStderr ?? true;
+        this.log              = opts.log ?? NO_LOG;
+        this.defaultTimeoutMs = opts.defaultTimeoutMs ?? 30_000;
+    }
+
+    /** Spawn the adapter child. Returns once `spawn()` has been
+     *  called — the child may still be initialising. Callers
+     *  immediately issue `request('initialize', ...)` and the DAP
+     *  request/response framing handles the rest. */
+    async start(): Promise<void> {
+        if (this.child) {
+            throw new Error('DapClient.start: already started');
+        }
+        const argv = [this.executable, ...this.args];
+        const child = spawn(this.runtime, argv, {
+            env:         this.env,
+            cwd:         this.cwd,
+            stdio:       ['pipe', 'pipe', this.inheritStderr ? 'inherit' : 'pipe'],
+            windowsHide: true,
+        });
+        this.child = child;
+        this.childExited = false;
+
+        // Stdout is the DAP wire. Stderr (if piped) is diagnostic
+        // chatter — we forward it via `log` so it doesn't poison the
+        // wire by accident.
+        const stdout = child.stdout;
+        const stdin  = child.stdin;
+        if (!stdout || !stdin) {
+            throw new Error('DapClient.start: child has no stdio pipes');
+        }
+        stdout.on('data',  (chunk: Buffer) => this.onStdoutChunk(chunk));
+        stdout.on('error', (e: Error)      => this.log(`[dap-client] stdout error: ${e.message}`));
+        stdin .on('error', (e: Error)      => this.log(`[dap-client] stdin error: ${e.message}`));
+
+        if (!this.inheritStderr && child.stderr) {
+            child.stderr.on('data', (chunk: Buffer) => {
+                this.log(`[dap-child stderr] ${chunk.toString('utf8').replace(/\n$/, '')}`);
+            });
+        }
+
+        child.on('exit', (code, signal) => {
+            this.childExited = true;
+            this.log(`[dap-client] child exited code=${code} signal=${signal ?? '-'}`);
+            // Fail any in-flight requests. Without this they would
+            // hang on the timeout — bad UX when the child crashed
+            // 200 ms ago.
+            const reason = `child process exited (code=${code} signal=${signal ?? '-'})`;
+            for (const p of this.pending.values()) {
+                clearTimeout(p.timer);
+                p.reject(new Error(`DAP request '${p.command}' failed: ${reason}`));
+            }
+            this.pending.clear();
+            this.emit('exited', { code, signal });
+        });
+        child.on('error', (err) => {
+            this.log(`[dap-client] spawn error: ${err.message}`);
+            this.emit('error', err);
+        });
+    }
+
+    /** Send a request and resolve with `response.body`. Rejects on
+     *  - timeout (after `timeoutMs ?? this.defaultTimeoutMs`),
+     *  - protocol-level failure (`response.success === false`),
+     *  - child process exit (the exit handler nukes pending). */
+    request<T = unknown>(command: string, args?: unknown, timeoutMs?: number): Promise<T> {
+        if (!this.child || this.childExited || !this.child.stdin) {
+            return Promise.reject(new Error(`DAP request '${command}': no live child`));
+        }
+        const seq = this.nextSeq++;
+        const message = { seq, type: 'request', command, arguments: args };
+        const json = JSON.stringify(message);
+        const header = `Content-Length: ${Buffer.byteLength(json, 'utf8')}\r\n\r\n`;
+        try {
+            this.child.stdin.write(header + json, 'utf8');
+        } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return Promise.reject(new Error(`DAP request '${command}' write failed: ${msg}`));
+        }
+        const wait = timeoutMs ?? this.defaultTimeoutMs;
+        return new Promise<T>((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(seq);
+                reject(new Error(`DAP request '${command}' timed out after ${wait}ms`));
+            }, wait);
+            this.pending.set(seq, {
+                resolve: (body) => resolve(body as T),
+                reject,
+                timer,
+                command,
+            });
+        });
+    }
+
+    /** Resolve with the next event of the given name. Honours a
+     *  timeout to avoid hanging on tests that never fire the event
+     *  they expect. */
+    waitForEvent<T extends DebugProtocol.Event = DebugProtocol.Event>(name: string, timeoutMs?: number): Promise<T> {
+        const wait = timeoutMs ?? this.defaultTimeoutMs;
+        return new Promise<T>((resolve, reject) => {
+            const handler = (ev: T): void => {
+                clearTimeout(timer);
+                resolve(ev);
+            };
+            const timer = setTimeout(() => {
+                this.off(name, handler);
+                reject(new Error(`DAP event '${name}' did not arrive within ${wait}ms`));
+            }, wait);
+            this.once(name, handler);
+        });
+    }
+
+    /** Tear the child down. Graceful path: close stdin → child sees
+     *  EOF → exits → we resolve. Fallback path: after `gracefulMs`,
+     *  SIGTERM; after another second, SIGKILL. Either way the
+     *  Promise always resolves; we never throw from cleanup. */
+    async stop(gracefulMs = 2_000): Promise<void> {
+        const child = this.child;
+        if (!child) return;
+        if (this.childExited) { this.child = null; return; }
+
+        try { child.stdin?.end(); } catch { /* already closed */ }
+
+        await new Promise<void>((resolve) => {
+            const onExit = (): void => {
+                clearTimeout(termTimer);
+                clearTimeout(killTimer);
+                resolve();
+            };
+            const termTimer = setTimeout(() => {
+                try { child.kill('SIGTERM'); } catch { /* ignore */ }
+            }, gracefulMs);
+            const killTimer = setTimeout(() => {
+                try { child.kill('SIGKILL'); } catch { /* ignore */ }
+                // Whether or not SIGKILL got through, give Node one
+                // more tick to fire 'exit'; otherwise resolve anyway.
+                setTimeout(resolve, 100);
+            }, gracefulMs + 1_000);
+            child.once('exit', onExit);
+        });
+        this.child = null;
+    }
+
+    // ---- internals --------------------------------------------------
+
+    private onStdoutChunk(chunk: Buffer): void {
+        this.rxBuffer = this.rxBuffer.length === 0
+            ? chunk
+            : Buffer.concat([this.rxBuffer, chunk]);
+
+        // Drain as many complete frames as fit in the buffer right
+        // now. One stdout chunk can carry many frames (e.g. a flood
+        // of output events after launch); equally one frame can
+        // arrive in several chunks (when the adapter writes a big
+        // variables[] body).
+        while (true) {
+            if (this.rxContentLength < 0) {
+                const headerEnd = this.rxBuffer.indexOf('\r\n\r\n');
+                if (headerEnd < 0) break;
+                const headers = this.rxBuffer.subarray(0, headerEnd).toString('ascii');
+                let length = -1;
+                for (const line of headers.split('\r\n')) {
+                    const m = /^Content-Length:\s*(\d+)$/i.exec(line);
+                    if (m) length = parseInt(m[1] as string, 10);
+                }
+                if (length < 0) {
+                    this.log(`[dap-client] missing Content-Length in headers; dropping ${headerEnd + 4} bytes and resyncing`);
+                    this.rxBuffer = this.rxBuffer.subarray(headerEnd + 4);
+                    continue;
+                }
+                this.rxContentLength = length;
+                this.rxBuffer = this.rxBuffer.subarray(headerEnd + 4);
+            }
+            if (this.rxBuffer.length < this.rxContentLength) break;
+            const body = this.rxBuffer.subarray(0, this.rxContentLength).toString('utf8');
+            this.rxBuffer = this.rxBuffer.subarray(this.rxContentLength);
+            this.rxContentLength = -1;
+            try {
+                this.dispatch(JSON.parse(body) as DapAnyMessage);
+            } catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                this.log(`[dap-client] failed to parse incoming message (${body.length}B): ${msg}`);
+            }
+        }
+    }
+
+    private dispatch(msg: DapAnyMessage): void {
+        if (msg.type === 'response') {
+            const seq = msg.request_seq ?? -1;
+            const p = this.pending.get(seq);
+            if (!p) return;
+            this.pending.delete(seq);
+            clearTimeout(p.timer);
+            if (msg.success === false) {
+                p.reject(new Error(msg.message || `DAP request '${p.command}' failed`));
+            } else {
+                p.resolve(msg.body);
+            }
+            return;
+        }
+        if (msg.type === 'event' && typeof msg.event === 'string') {
+            this.emit(msg.event, msg);
+            return;
+        }
+        // type='request' from the server (e.g. runInTerminal) is the
+        // only other DAP message kind. The iScope adapter never sends
+        // those; ignore.
+    }
+}
+
+/** Internal: all three DAP message shapes flattened into one. */
+interface DapAnyMessage {
+    type?:        'request' | 'response' | 'event';
+    command?:     string;
+    event?:       string;
+    success?:     boolean;
+    request_seq?: number;
+    body?:        unknown;
+    message?:     string;
+}