@i-scope/mcp-server 0.4.2

package/dist/src/dap-driver.js

@@ -0,0 +1,703 @@
+"use strict";
+// DapDriver — the heart of the MCP server.
+//
+// Responsibilities:
+//   1. Spawn the iScope DAP adapter (the `server.js` shipped inside
+//      `@i-scope/dap-adapter`) as a Node child process via our own
+//      minimal `DapClient` (see `./dap-client.ts`). We avoid
+//      `@vscode/debugadapter-testsupport` so the published package
+//      doesn't depend on a "testsupport" artefact with no API stability
+//      guarantees across minor versions.
+//   2. Translate one debug session's DAP wire into a small, stable
+//      surface for the MCP tools (launch / set-breakpoints / step /
+//      inspect / disconnect).
+//   3. Hold the session state machine
+//      (`idle → launching → running ⇄ paused → terminated`) and gate
+//      tool calls against it (you cannot `variables` while running).
+//   4. Buffer asynchronous DAP events:
+//        - `output` into a circular log with monotonic ids (consumed
+//          by `debug_read_output`),
+//        - `stopped` / `terminated` into a "pending-wait" Promise that
+//          step/continue tools `await` on.
+//   5. Serialise DAP requests through an internal mutex so two MCP
+//      tools called concurrently from the client don't trample each
+//      other on the wire (`stack_trace` issued while a `continue`
+//      response is still in flight would corrupt the state machine).
+//   6. Clean up the child process tree on `disconnect` and on hard
+//      shutdown — DAP disconnectRequest → debug-server exits → helper
+//      shuts down with closePolicy='ifWeLaunched' → Oscilloscope
+//      either closes (we launched it) or stays alive (user did). Same
+//      contract as Phase B'-6.
+//
+// Concurrency contract:
+//   - All exclusive DAP operations go through `runExclusive()`.
+//   - Snapshot-only operations (`getState`, `getStoppedSnapshot`,
+//     `readOutput`) are lock-free; they read fields synchronously.
+//   - Events arrive on the event-loop microtask, so anything we do
+//     inside a handler must be O(small). We push transitions into the
+//     state and notify pending waiters; the actual heavy work
+//     (mapping frames, fetching scopes) happens lazily on the next
+//     tool call.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DapDriver = exports.Mutex = void 0;
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const source_map_bridge_1 = require("@i-scope/source-map-bridge");
+const dap_adapter_1 = require("@i-scope/dap-adapter");
+const dap_client_js_1 = require("./dap-client.js");
+// ---- Internal mutex --------------------------------------------------------
+/** Promise-chain mutex. Each `runExclusive(fn)` waits for the prior
+ *  one to settle, then runs `fn`. No re-entrancy — if a tool handler
+ *  re-enters runExclusive from inside its own callback it WILL
+ *  deadlock. (Tools are designed to never do that.)
+ *
+ *  Exported for unit testing. The MCP server itself doesn't need to
+ *  re-export it.
+ */
+class Mutex {
+    tail = Promise.resolve();
+    runExclusive(fn) {
+        const prev = this.tail;
+        let resolveCurrent;
+        let rejectCurrent;
+        const current = new Promise((res, rej) => {
+            resolveCurrent = res;
+            rejectCurrent = rej;
+        });
+        this.tail = current.catch(() => undefined);
+        prev.then(async () => {
+            try {
+                resolveCurrent(await fn());
+            }
+            catch (e) {
+                rejectCurrent(e);
+            }
+        }, 
+        // The prior call rejected; we still want to run.
+        async () => {
+            try {
+                resolveCurrent(await fn());
+            }
+            catch (e) {
+                rejectCurrent(e);
+            }
+        });
+        return current;
+    }
+}
+exports.Mutex = Mutex;
+class DapDriver {
+    extensionPath;
+    debugServerJs;
+    defaultTimeoutMs;
+    outputBufferSize;
+    log;
+    client = null;
+    state = 'idle';
+    /** Source-map manager used to fill `generatedSource`/`generatedLine`
+     *  on mapped frames (and to surface unmapped-fallback warnings).
+     *  Lazily created on first launch and reset on disconnect so a
+     *  fresh session always parses the current `.ajs.map` from disk. */
+    sourceMaps = null;
+    /** Absolute path to the generated `.ajs` for the current launch.
+     *  Used by `classifyFrame` to ask the manager for reverse mappings
+     *  without re-resolving the sibling each call. Empty when launch
+     *  was against a `.ajs` (then `generatedAjs === program`). */
+    generatedAjs = null;
+    /** Once-per-launch dedup for unmapped-fallback warning messages.
+     *  Without it the same warning would land in the output buffer on
+     *  every stack_trace call. Key: `<source>:<line>:<col>`. */
+    unmappedWarned = new Set();
+    /** Args from the most recent launch. Used to classify
+     *  `sourceOrigin` on frames returned by stackTrace. */
+    launchArgs = null;
+    /** Lower-case basename extension of `launchArgs.program`, e.g.
+     *  `.ts` or `.ajs`. Cached so frame-mapping doesn't repeat
+     *  `path.extname()` per frame. */
+    programIsTs = false;
+    /** Circular output buffer; oldest entries dropped first when full. */
+    outputBuffer = [];
+    outputNextId = 1;
+    /** Last `stopped` snapshot — refreshed on every StoppedEvent.
+     *  Used by `current_state` tool and by step/continue tools that
+     *  want to read frames straight from cache before calling
+     *  stack_trace explicitly. */
+    lastStopped = null;
+    /** Termination metadata captured when DAP emits `terminated`. */
+    terminationInfo = null;
+    /** Pending step/continue/wait_for_paused awaiters. Resolved on
+     *  the next state transition. */
+    pendingWaits = [];
+    mutex = new Mutex();
+    constructor(opts) {
+        this.extensionPath = opts.extensionPath ? (0, node_path_1.resolve)(opts.extensionPath) : undefined;
+        // The DAP entry-point lives inside `@i-scope/dap-adapter`. Use
+        // Node's resolver so the same code path works in published
+        // installs (npm node_modules) AND inside this monorepo
+        // (workspaces symlink the package into place). No file-system
+        // path arithmetic — that is now the adapter package's
+        // responsibility.
+        this.debugServerJs = require.resolve('@i-scope/dap-adapter/dist/src/server.js');
+        this.defaultTimeoutMs = opts.defaultTimeoutMs ?? 30_000;
+        this.outputBufferSize = opts.outputBufferSize ?? 2000;
+        this.log = opts.log ?? ((line) => process.stderr.write(line + '\n'));
+    }
+    // ---- Public read-only API (lock-free, snapshot) ----------------------
+    getState() { return this.state; }
+    getStoppedSnapshot() { return this.lastStopped; }
+    getTerminationInfo() { return this.terminationInfo; }
+    /** Was the most recent launch against a `.ts` file? Tool layer
+     *  uses this to bake `sourceOrigin` into frames without
+     *  re-inspecting `launchArgs`. */
+    isTsLaunch() { return this.programIsTs; }
+    /** Snapshot of buffered Output entries with id > cursor.
+     *  AI passes `nextCursor` from the previous read to get the tail.
+     *  Lock-free; never mutates state. */
+    readOutput(cursor, limit = 1000) {
+        const out = [];
+        let max = cursor;
+        for (const e of this.outputBuffer) {
+            if (e.id > cursor) {
+                out.push(e);
+                if (e.id > max)
+                    max = e.id;
+                if (out.length >= limit)
+                    break;
+            }
+        }
+        return { entries: out, nextCursor: max };
+    }
+    // ---- Lifecycle -------------------------------------------------------
+    async launch(args) {
+        return this.mutex.runExclusive(async () => {
+            if (this.state !== 'idle' && this.state !== 'terminated') {
+                throw new Error(`cannot launch in state '${this.state}'; call debug_disconnect first`);
+            }
+            if (!(0, node_fs_1.existsSync)(this.debugServerJs)) {
+                throw new Error(`dap-adapter server.js not found at ${this.debugServerJs}\n` +
+                    `Did the @i-scope/dap-adapter install complete? Try: npm install @i-scope/dap-adapter`);
+            }
+            this.resetSessionState();
+            this.launchArgs = args;
+            this.programIsTs = /\.ts$/i.test(args.program);
+            // Wire a fresh source-map manager for this session and
+            // preload the relevant `.ajs.map`s. Failures here are
+            // warnings, not hard errors — debug still works without
+            // mapping, the AI just sees `sourceOrigin: 'generated'`
+            // or `'unmapped-fallback'` for every frame.
+            await this.initSourceMaps(args).catch((e) => {
+                this.log(`[mcp] source-map preload failed: ${this.errMsg(e)}`);
+            });
+            const timeoutMs = args.timeoutMs ?? this.defaultTimeoutMs;
+            // The adapter package is a pure Node module — no
+            // `require('vscode')` lives in its runtime path any more,
+            // so we spawn its `server.js` directly. `ISCOPE_EXTENSION_PATH`
+            // is forwarded only when explicitly provided (it acts as a
+            // `bundledRoot` override for the bridge-client helper
+            // resolver). When unset, the spawned adapter falls back to
+            // the npm-installed `@i-scope/iscope-bridge` package.
+            const childEnv = { ...process.env };
+            if (this.extensionPath) {
+                childEnv['ISCOPE_EXTENSION_PATH'] = this.extensionPath;
+            }
+            const dc = new dap_client_js_1.DapClient({
+                runtime: 'node',
+                executable: this.debugServerJs,
+                env: childEnv,
+                inheritStderr: true,
+                defaultTimeoutMs: timeoutMs,
+                log: this.log,
+            });
+            this.client = dc;
+            this.wireClientEvents(dc);
+            this.state = 'launching';
+            await dc.start();
+            await dc.request('initialize', {
+                adapterID: 'iscope-ajs',
+                linesStartAt1: true,
+                columnsStartAt1: true,
+                pathFormat: 'path',
+            });
+            // Phase D-1 finding #11: launchRequest is buffered by the
+            // adapter until configurationDone; arrange the wait BEFORE
+            // sending launchRequest so we don't lose the `initialized`
+            // event.
+            const initialized = dc.waitForEvent('initialized', timeoutMs);
+            const dapLaunchArgs = {
+                type: 'iscope-ajs',
+                request: 'launch',
+                name: 'mcp-launch',
+                program: args.program,
+            };
+            if (args.mwfFile !== undefined)
+                dapLaunchArgs['mwfFile'] = args.mwfFile;
+            if (args.autoLaunch !== undefined)
+                dapLaunchArgs['autoLaunch'] = args.autoLaunch;
+            if (args.openFileBeforeRun !== undefined)
+                dapLaunchArgs['openFileBeforeRun'] = args.openFileBeforeRun;
+            if (args.stopOnEntry !== undefined)
+                dapLaunchArgs['stopOnEntry'] = args.stopOnEntry;
+            if (args.oscilloscopePath !== undefined)
+                dapLaunchArgs['oscilloscopePath'] = args.oscilloscopePath;
+            if (args.helperPath !== undefined)
+                dapLaunchArgs['helperPath'] = args.helperPath;
+            if (args.outFiles !== undefined)
+                dapLaunchArgs['outFiles'] = args.outFiles;
+            const launchP = dc.request('launch', dapLaunchArgs);
+            await initialized;
+            await dc.request('configurationDone', {});
+            await launchP;
+            // Post-launch state: either we hit stopOnEntry / startup
+            // halt right away, or we are running. Wait briefly for a
+            // stopped/terminated; otherwise consider ourselves running.
+            if (this.state === 'launching') {
+                // Race with a small timeout so a long-running script
+                // doesn't block this tool indefinitely. Tools then use
+                // wait_for_paused / step_* to advance.
+                const settle = await this.waitForTransition(/*timeoutMs*/ 1500);
+                return settle;
+            }
+            return this.snapshotTransition();
+        });
+    }
+    async disconnect() {
+        return this.mutex.runExclusive(async () => {
+            if (!this.client) {
+                this.state = 'idle';
+                return;
+            }
+            const dc = this.client;
+            try {
+                // terminateDebuggee semantics: the adapter (D-1 finding
+                // #14) coerces this into closePolicy='ifWeLaunched'
+                // unconditionally, so we just send true.
+                await dc.request('disconnect', { terminateDebuggee: true });
+            }
+            catch (e) {
+                this.log(`[mcp] disconnect request failed: ${this.errMsg(e)}`);
+            }
+            try {
+                await dc.stop();
+            }
+            catch (e) {
+                this.log(`[mcp] dc.stop() failed: ${this.errMsg(e)}`);
+            }
+            // Fail any awaiters that were waiting for the next stop.
+            this.failPendingWaits('disconnected');
+            this.client = null;
+            this.state = 'idle';
+        });
+    }
+    // ---- Breakpoints / execution / inspection (exclusive) --------------
+    async setBreakpoints(source, lines) {
+        return this.mutex.runExclusive(async () => {
+            const dc = this.requireClient();
+            return dc.request('setBreakpoints', {
+                source: { path: source, name: this.basename(source) },
+                breakpoints: lines.map((l) => ({ line: l })),
+                lines,
+                sourceModified: false,
+            });
+        });
+    }
+    /** continue / step_* / wait_for_paused all funnel through this
+     *  helper. `dapCall` returns the DAP response Promise; we await
+     *  the resulting state transition (stopped / terminated / timeout)
+     *  and return it.
+     *
+     *  `dapCall` may be null for `wait_for_paused` (no request to
+     *  send — just observe). */
+    async resumeAndWait(dapCall, timeoutMs) {
+        return this.mutex.runExclusive(async () => {
+            const dc = this.requireClient();
+            if (dapCall) {
+                if (this.state !== 'paused') {
+                    throw new Error(`cannot resume in state '${this.state}' (must be 'paused')`);
+                }
+                this.state = 'running';
+                // Eagerly invalidate frame state — DAP responses for
+                // stackTrace etc. would be stale until the next stop.
+                this.lastStopped = null;
+                await dapCall(dc);
+            }
+            else {
+                if (this.state !== 'running' && this.state !== 'launching') {
+                    // Already paused / terminated — return current
+                    // snapshot without arming a wait.
+                    return this.snapshotTransition();
+                }
+            }
+            return this.waitForTransition(timeoutMs ?? this.defaultTimeoutMs);
+        });
+    }
+    async stackTrace() {
+        return this.mutex.runExclusive(async () => {
+            const dc = this.requireClient();
+            if (this.state !== 'paused') {
+                throw new Error(`stack_trace requires 'paused' state, got '${this.state}'`);
+            }
+            return dc.request('stackTrace', { threadId: 1 });
+        });
+    }
+    async scopes(frameId) {
+        return this.mutex.runExclusive(async () => {
+            const dc = this.requireClient();
+            if (this.state !== 'paused') {
+                throw new Error(`scopes requires 'paused' state, got '${this.state}'`);
+            }
+            return dc.request('scopes', { frameId });
+        });
+    }
+    async variables(variablesReference) {
+        return this.mutex.runExclusive(async () => {
+            const dc = this.requireClient();
+            if (this.state !== 'paused') {
+                throw new Error(`variables requires 'paused' state, got '${this.state}'`);
+            }
+            return dc.request('variables', { variablesReference });
+        });
+    }
+    async evaluate(expression, frameId, context) {
+        return this.mutex.runExclusive(async () => {
+            const dc = this.requireClient();
+            if (this.state !== 'paused') {
+                throw new Error(`evaluate requires 'paused' state, got '${this.state}'`);
+            }
+            const args = { expression, context };
+            if (frameId !== undefined)
+                args.frameId = frameId;
+            return dc.request('evaluate', args);
+        });
+    }
+    // ---- Frame mapping (pure, no DAP traffic) ----------------------------
+    /** Convert a DAP StackFrame into our richer FrameInfo with
+     *  sourceOrigin annotation AND fully-populated generatedSource/
+     *  generatedLine/generatedColumn fields.
+     *
+     *  Algorithm:
+     *    - launch with `.ajs`  → frame is always `generated`.
+     *      generatedSource = frame.source.
+     *    - launch with `.ts` and frame.source ends in `.ts` →
+     *      `mapped`. Reverse-look the TS coords up in our SourceMap
+     *      Manager to get the corresponding `.ajs` coords (so the AI
+     *      can cross-reference engine offsets even when reading TS).
+     *      If the reverse lookup fails we still classify as mapped
+     *      but leave generatedSource/Line undefined.
+     *    - launch with `.ts` and frame.source ends in `.ajs` →
+     *      `unmapped-fallback` (adapter could not translate this
+     *      specific line; AI sees raw engine position). We also
+     *      buffer ONE console-category OutputEntry per unique
+     *      <source:line:col> tuple so `debug_read_output` surfaces
+     *      the gap as a visible warning. */
+    async classifyFrame(f) {
+        const sourcePath = f.source?.path ?? f.source?.name ?? '<unknown>';
+        const isTsFrame = /\.ts$/i.test(sourcePath);
+        const isAjsFrame = /\.ajs$/i.test(sourcePath)
+            || /\.apn$/i.test(sourcePath)
+            || /\.aps$/i.test(sourcePath);
+        let sourceOrigin;
+        let generatedSource;
+        let generatedLine;
+        let generatedColumn;
+        if (!this.programIsTs) {
+            sourceOrigin = 'generated';
+            generatedSource = sourcePath;
+            generatedLine = f.line;
+            generatedColumn = f.column ?? 1;
+        }
+        else if (isTsFrame) {
+            sourceOrigin = 'mapped';
+            // Reverse-map TS → AJS via SourceMapManager so the AI
+            // gets engine coordinates alongside the TS view.
+            if (this.sourceMaps) {
+                try {
+                    const pos = await this.sourceMaps.toGenerated(sourcePath, f.line, f.column ?? 1);
+                    if (pos) {
+                        generatedSource = pos.generatedPath;
+                        generatedLine = pos.line;
+                        generatedColumn = pos.column;
+                    }
+                }
+                catch (e) {
+                    // Reverse-lookup is best-effort. Log and move on.
+                    this.log(`[mcp] reverse source-map lookup failed for ${sourcePath}:${f.line}: ${this.errMsg(e)}`);
+                }
+            }
+        }
+        else if (isAjsFrame) {
+            sourceOrigin = 'unmapped-fallback';
+            generatedSource = sourcePath;
+            generatedLine = f.line;
+            generatedColumn = f.column ?? 1;
+            this.warnUnmappedFallback(sourcePath, f.line, f.column ?? 1);
+        }
+        else {
+            // Shouldn't happen — but be defensive.
+            sourceOrigin = 'generated';
+            generatedSource = sourcePath;
+            generatedLine = f.line;
+            generatedColumn = f.column ?? 1;
+        }
+        const out = {
+            id: f.id,
+            name: f.name,
+            source: sourcePath,
+            sourceOrigin,
+            line: f.line,
+            column: f.column ?? 1,
+        };
+        if (f.endLine !== undefined)
+            out.endLine = f.endLine;
+        if (f.endColumn !== undefined)
+            out.endColumn = f.endColumn;
+        if (generatedSource !== undefined)
+            out.generatedSource = generatedSource;
+        if (generatedLine !== undefined)
+            out.generatedLine = generatedLine;
+        if (generatedColumn !== undefined)
+            out.generatedColumn = generatedColumn;
+        return out;
+    }
+    /** Buffer a single console-category warning per unique
+     *  <source:line:col>. AI sees it via `debug_read_output` and can
+     *  decide whether to ignore or to ask the user to rebuild with
+     *  better source-map coverage. */
+    warnUnmappedFallback(source, line, column) {
+        const key = `${source}:${line}:${column}`;
+        if (this.unmappedWarned.has(key))
+            return;
+        this.unmappedWarned.add(key);
+        const text = `[source-map] unmapped-fallback at ${(0, node_path_1.basename)(source)}:${line}:${column} ` +
+            `— the .ajs.map has no mapping for this line; AI sees raw .ajs coordinates.\n`;
+        this.outputBuffer.push({
+            id: this.outputNextId++,
+            category: 'console',
+            text,
+            timestamp: Date.now(),
+        });
+        while (this.outputBuffer.length > this.outputBufferSize) {
+            this.outputBuffer.shift();
+        }
+    }
+    // ---- Event wiring ----------------------------------------------------
+    wireClientEvents(dc) {
+        dc.on('output', (ev) => {
+            const body = ev.body || {};
+            if (typeof body.output !== 'string')
+                return;
+            // De-duplication: the Phase 3 adapter emits every
+            // `Host.ReportOut(level, text)` TWICE on the DAP wire — once
+            // as a normal `stdout`/`stderr` OutputEvent (so the Debug
+            // Console keeps showing it for human users) and once with
+            // the custom `iScopeTrace` category carrying the structured
+            // `{ level, text }` payload (for the extension's Trace
+            // OutputChannel, see `adapter.ts` around line 1299-1327).
+            // The MCP `debug_read_output` consumer only wants the
+            // user-visible form, so we drop the structured duplicate
+            // here. The trace category is still observable by other
+            // consumers that listen on the DAP wire directly.
+            if (body.category === dap_adapter_1.ISCOPE_TRACE_CATEGORY)
+                return;
+            const entry = {
+                id: this.outputNextId++,
+                category: body.category ?? 'console',
+                text: body.output,
+                timestamp: Date.now(),
+            };
+            this.outputBuffer.push(entry);
+            while (this.outputBuffer.length > this.outputBufferSize) {
+                this.outputBuffer.shift();
+            }
+        });
+        dc.on('stopped', async (ev) => {
+            const body = ev.body || {};
+            const reason = typeof body.reason === 'string' ? body.reason : 'breakpoint';
+            const description = typeof body.description === 'string'
+                ? body.description
+                : (typeof body.text === 'string' ? body.text : undefined);
+            // Fetch stack trace eagerly so `current_state` / step
+            // responses can return frames without an extra round-trip.
+            // This is on the wire even when the AI does not need it —
+            // acceptable because (a) JScript engine is fast,
+            // (b) keeps the public API ergonomic.
+            let frames = [];
+            try {
+                const st = await dc.request('stackTrace', { threadId: 1 });
+                frames = await Promise.all((st.stackFrames ?? []).map((f) => this.classifyFrame(f)));
+            }
+            catch (e) {
+                this.log(`[mcp] post-stopped stackTrace failed: ${this.errMsg(e)}`);
+            }
+            const stopped = description !== undefined
+                ? { reason, description, frames }
+                : { reason, frames };
+            this.lastStopped = stopped;
+            this.state = 'paused';
+            this.resolvePendingWaits({ state: 'paused', stopped });
+        });
+        dc.on('continued', () => {
+            // Some adapters emit `continued` to signal "no longer
+            // paused"; the iScope adapter does on every resume. We
+            // shift to running so step tools can re-arm.
+            if (this.state === 'paused')
+                this.state = 'running';
+        });
+        dc.on('terminated', (ev) => {
+            const body = (ev?.body ?? {});
+            const reason = typeof body['reason'] === 'string'
+                ? body['reason']
+                : undefined;
+            this.terminationInfo = reason !== undefined ? { reason } : {};
+            this.state = 'terminated';
+            this.resolvePendingWaits({ state: 'terminated', exitInfo: this.terminationInfo });
+        });
+        dc.on('exited', () => {
+            if (this.state !== 'terminated') {
+                this.terminationInfo = this.terminationInfo ?? { reason: 'process exited' };
+                this.state = 'terminated';
+                this.resolvePendingWaits({ state: 'terminated', exitInfo: this.terminationInfo });
+            }
+        });
+    }
+    // ---- Wait management -------------------------------------------------
+    waitForTransition(timeoutMs) {
+        // If state already advanced past `running` while we were
+        // arming the wait, short-circuit.
+        if (this.state === 'paused' && this.lastStopped) {
+            return Promise.resolve({ state: 'paused', stopped: this.lastStopped });
+        }
+        if (this.state === 'terminated') {
+            const out = { state: 'terminated' };
+            if (this.terminationInfo)
+                out.exitInfo = this.terminationInfo;
+            return Promise.resolve(out);
+        }
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.removePending(entry);
+                resolve({ state: 'timeout', waitedMs: timeoutMs });
+            }, timeoutMs);
+            const entry = { resolve, timer };
+            this.pendingWaits.push(entry);
+        });
+    }
+    resolvePendingWaits(t) {
+        const list = this.pendingWaits.splice(0);
+        for (const w of list) {
+            clearTimeout(w.timer);
+            w.resolve(t);
+        }
+    }
+    failPendingWaits(reason) {
+        const list = this.pendingWaits.splice(0);
+        for (const w of list) {
+            clearTimeout(w.timer);
+            // We can't reject a tool promise from here (it would
+            // surface as an MCP error before the disconnect response).
+            // Returning a synthetic timeout-with-marker keeps the
+            // contract simple: tool sees `state:'timeout'` and the AI
+            // can decide.
+            w.resolve({ state: 'timeout', waitedMs: 0 });
+        }
+        // log for our own benefit
+        this.log(`[mcp] flushed ${list.length} pending wait(s): ${reason}`);
+    }
+    removePending(target) {
+        const i = this.pendingWaits.indexOf(target);
+        if (i >= 0)
+            this.pendingWaits.splice(i, 1);
+    }
+    snapshotTransition() {
+        if (this.state === 'paused' && this.lastStopped) {
+            return { state: 'paused', stopped: this.lastStopped };
+        }
+        if (this.state === 'terminated') {
+            const out = { state: 'terminated' };
+            if (this.terminationInfo)
+                out.exitInfo = this.terminationInfo;
+            return out;
+        }
+        // running / launching / idle — we have nothing to report yet.
+        return { state: 'timeout', waitedMs: 0 };
+    }
+    // ---- Helpers --------------------------------------------------------
+    requireClient() {
+        if (!this.client) {
+            throw new Error('no active debug session — call debug_launch first');
+        }
+        return this.client;
+    }
+    resetSessionState() {
+        this.outputBuffer.length = 0;
+        this.outputNextId = 1;
+        this.lastStopped = null;
+        this.terminationInfo = null;
+        this.pendingWaits = [];
+        this.launchArgs = null;
+        this.programIsTs = false;
+        this.generatedAjs = null;
+        this.unmappedWarned.clear();
+        // Dispose the prior manager to free its WASM-backed consumers.
+        // Best-effort — if it fails we just leak a few MB until process
+        // exit.
+        if (this.sourceMaps) {
+            const prior = this.sourceMaps;
+            this.sourceMaps = null;
+            prior.dispose().catch((e) => this.log(`[mcp] source-map dispose error: ${this.errMsg(e)}`));
+        }
+    }
+    /** Resolve and preload `.ajs.map` candidates for this launch.
+     *  Stores the resolved generated `.ajs` path in `generatedAjs` so
+     *  `classifyFrame` can run reverse-mapping lookups without re-
+     *  guessing the sibling each time. */
+    async initSourceMaps(args) {
+        const mgr = new source_map_bridge_1.SourceMapManager({
+            log: (line) => this.log(`[mcp/sourcemap] ${line}`),
+        });
+        this.sourceMaps = mgr;
+        // Resolve the generated `.ajs` path. If user launched a `.ts`,
+        // we look for a sibling with the same basename. If neither
+        // file actually exists we still try the load — `loadFor`
+        // returns false and we move on (no maps, no harm).
+        let ajsPath;
+        if (this.programIsTs) {
+            const dir = (0, node_path_1.dirname)(args.program);
+            const base = (0, node_path_1.basename)(args.program, (0, node_path_1.extname)(args.program));
+            ajsPath = (0, node_path_1.join)(dir, base + '.ajs');
+        }
+        else {
+            ajsPath = args.program;
+        }
+        ajsPath = (0, node_path_1.resolve)(ajsPath);
+        if ((0, node_fs_1.existsSync)(ajsPath)) {
+            this.generatedAjs = ajsPath;
+            await mgr.loadFor(ajsPath);
+        }
+        // Honour the launch.json `outFiles` array exactly like the
+        // adapter does — preload maps for every bundle the user
+        // points us at. Useful for multi-bundle workspaces where
+        // breakpoints sit in `.ts` whose `.ajs` we haven't met yet.
+        if (args.outFiles && args.outFiles.length > 0) {
+            const workspaceRoot = (0, node_path_1.dirname)(args.program);
+            await mgr.preload(args.outFiles, workspaceRoot);
+        }
+    }
+    basename(p) {
+        const i = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'));
+        return i >= 0 ? p.slice(i + 1) : p;
+    }
+    errMsg(e) {
+        if (e instanceof Error)
+            return e.message;
+        if (typeof e === 'string')
+            return e;
+        try {
+            return JSON.stringify(e);
+        }
+        catch {
+            return String(e);
+        }
+    }
+}
+exports.DapDriver = DapDriver;
+//# sourceMappingURL=dap-driver.js.map