@i-scope/mcp-server 0.4.2

package/src/dap-driver.ts

@@ -0,0 +1,810 @@
+// 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.
+
+import { resolve as resolvePath, dirname, basename, extname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+import type { DebugProtocol } from '@vscode/debugprotocol';
+import { SourceMapManager } from '@i-scope/source-map-bridge';
+import { ISCOPE_TRACE_CATEGORY } from '@i-scope/dap-adapter';
+
+import { DapClient } from './dap-client.js';
+
+import type {
+    FrameInfo,
+    OutputEntry,
+    SessionState,
+    StoppedInfo,
+    StoppedReason,
+    SourceOrigin,
+    ExecutionTransition,
+    TerminationInfo,
+} from './state.js';
+
+// ---- Public option / argument types ---------------------------------------
+
+export interface DapDriverOptions {
+    /** Optional bundled-root override forwarded to the spawned DAP
+     *  server as `ISCOPE_EXTENSION_PATH`. Useful only when the caller
+     *  ships its own copy of `iScopeBridge.exe` and wants it to win
+     *  over the npm-installed `@i-scope/iscope-bridge`. Leave undefined
+     *  for the standard "everything via npm" deployment — the
+     *  bridge-client will resolve the binary from the installed
+     *  `@i-scope/iscope-bridge` package automatically. */
+    extensionPath?: string;
+    /** Default per-DAP-request timeout. Defaults to 30 000 ms. */
+    defaultTimeoutMs?: number;
+    /** Maximum buffered Host.ReportOut + console entries before the
+     *  oldest get dropped. Defaults to 2000. */
+    outputBufferSize?: number;
+    /** Optional log function for MCP-server-side diagnostics. Writes
+     *  go to stderr by default (stdout is reserved for the MCP wire).
+     *  Use this if you want to redirect to a file. */
+    log?: (line: string) => void;
+}
+
+export interface LaunchToolArgs {
+    program: string;
+    mwfFile?: string;
+    autoLaunch?: boolean;
+    openFileBeforeRun?: boolean | null;
+    stopOnEntry?: boolean | 'auto';
+    oscilloscopePath?: string;
+    helperPath?: string;
+    outFiles?: string[];
+    /** Override per-request timeout for this `launch` (covers the
+     *  initial spawn + initialize round-trip). */
+    timeoutMs?: number;
+}
+
+// ---- 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.
+ */
+export class Mutex {
+    private tail: Promise<unknown> = Promise.resolve();
+    runExclusive<T>(fn: () => Promise<T>): Promise<T> {
+        const prev = this.tail;
+        let resolveCurrent!: (v: T | PromiseLike<T>) => void;
+        let rejectCurrent!: (e: unknown) => void;
+        const current = new Promise<T>((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;
+    }
+}
+
+// ---- DapDriver -------------------------------------------------------------
+
+/** Resolves when the next `stopped` / `terminated` event arrives, OR
+ *  the timer expires. Used by step/continue/wait_for_paused. */
+type PendingWait = {
+    resolve: (t: ExecutionTransition) => void;
+    timer: NodeJS.Timeout;
+};
+
+export class DapDriver {
+    private readonly extensionPath: string | undefined;
+    private readonly debugServerJs: string;
+    private readonly defaultTimeoutMs: number;
+    private readonly outputBufferSize: number;
+    private readonly log: (line: string) => void;
+
+    private client: DapClient | null = null;
+    private state: SessionState = '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. */
+    private sourceMaps: SourceMapManager | null = 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`). */
+    private generatedAjs: string | null = 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>`. */
+    private readonly unmappedWarned = new Set<string>();
+
+    /** Args from the most recent launch. Used to classify
+     *  `sourceOrigin` on frames returned by stackTrace. */
+    private launchArgs: LaunchToolArgs | null = null;
+    /** Lower-case basename extension of `launchArgs.program`, e.g.
+     *  `.ts` or `.ajs`. Cached so frame-mapping doesn't repeat
+     *  `path.extname()` per frame. */
+    private programIsTs: boolean = false;
+
+    /** Circular output buffer; oldest entries dropped first when full. */
+    private readonly outputBuffer: OutputEntry[] = [];
+    private 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. */
+    private lastStopped: StoppedInfo | null = null;
+
+    /** Termination metadata captured when DAP emits `terminated`. */
+    private terminationInfo: TerminationInfo | null = null;
+
+    /** Pending step/continue/wait_for_paused awaiters. Resolved on
+     *  the next state transition. */
+    private pendingWaits: PendingWait[] = [];
+
+    private readonly mutex = new Mutex();
+
+    constructor(opts: DapDriverOptions) {
+        this.extensionPath    = opts.extensionPath ? resolvePath(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(): SessionState { return this.state; }
+    getStoppedSnapshot(): StoppedInfo | null { return this.lastStopped; }
+    getTerminationInfo(): TerminationInfo | null { 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(): boolean { 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: number, limit = 1000): { entries: OutputEntry[]; nextCursor: number } {
+        const out: OutputEntry[] = [];
+        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: LaunchToolArgs): Promise<ExecutionTransition> {
+        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 (!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: Record<string, string> = { ...process.env } as Record<string, string>;
+            if (this.extensionPath) {
+                childEnv['ISCOPE_EXTENSION_PATH'] = this.extensionPath;
+            }
+
+            const dc = new 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<DebugProtocol.InitializeResponse['body']>('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: Record<string, unknown> = {
+                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<DebugProtocol.LaunchResponse['body']>('launch', dapLaunchArgs);
+
+            await initialized;
+            await dc.request<DebugProtocol.ConfigurationDoneResponse['body']>('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(): Promise<void> {
+        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<DebugProtocol.DisconnectResponse['body']>(
+                    '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: string, lines: number[]): Promise<DebugProtocol.SetBreakpointsResponse['body']> {
+        return this.mutex.runExclusive(async () => {
+            const dc = this.requireClient();
+            return dc.request<DebugProtocol.SetBreakpointsResponse['body']>('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: ((dc: DapClient) => Promise<unknown>) | null,
+        timeoutMs?: number,
+    ): Promise<ExecutionTransition> {
+        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(): Promise<DebugProtocol.StackTraceResponse['body']> {
+        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<DebugProtocol.StackTraceResponse['body']>('stackTrace', { threadId: 1 });
+        });
+    }
+
+    async scopes(frameId: number): Promise<DebugProtocol.ScopesResponse['body']> {
+        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<DebugProtocol.ScopesResponse['body']>('scopes', { frameId });
+        });
+    }
+
+    async variables(variablesReference: number): Promise<DebugProtocol.VariablesResponse['body']> {
+        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<DebugProtocol.VariablesResponse['body']>('variables', { variablesReference });
+        });
+    }
+
+    async evaluate(
+        expression: string,
+        frameId: number | undefined,
+        context: 'watch' | 'hover' | 'repl',
+    ): Promise<DebugProtocol.EvaluateResponse['body']> {
+        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: DebugProtocol.EvaluateArguments = { expression, context };
+            if (frameId !== undefined) args.frameId = frameId;
+            return dc.request<DebugProtocol.EvaluateResponse['body']>('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: DebugProtocol.StackFrame): Promise<FrameInfo> {
+        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: SourceOrigin;
+        let generatedSource: string | undefined;
+        let generatedLine:   number | undefined;
+        let generatedColumn: number | undefined;
+
+        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: FrameInfo = {
+            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. */
+    private warnUnmappedFallback(source: string, line: number, column: number): void {
+        const key = `${source}:${line}:${column}`;
+        if (this.unmappedWarned.has(key)) return;
+        this.unmappedWarned.add(key);
+        const text =
+            `[source-map] unmapped-fallback at ${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 ----------------------------------------------------
+
+    private wireClientEvents(dc: DapClient): void {
+        dc.on('output', (ev: DebugProtocol.OutputEvent) => {
+            const body = ev.body || ({} as DebugProtocol.OutputEvent['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 === ISCOPE_TRACE_CATEGORY) return;
+            const entry: OutputEntry = {
+                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: DebugProtocol.StoppedEvent) => {
+            const body = ev.body || ({} as DebugProtocol.StoppedEvent['body']);
+            const reason: StoppedReason =
+                typeof body.reason === 'string' ? (body.reason as StoppedReason) : '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: FrameInfo[] = [];
+            try {
+                const st = await dc.request<DebugProtocol.StackTraceResponse['body']>(
+                    '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: StoppedInfo = 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: DebugProtocol.TerminatedEvent) => {
+            const body = (ev?.body ?? {}) as Record<string, unknown>;
+            const reason = typeof body['reason'] === 'string'
+                ? body['reason'] as string
+                : 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 -------------------------------------------------
+
+    private waitForTransition(timeoutMs: number): Promise<ExecutionTransition> {
+        // 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: ExecutionTransition = { state: 'terminated' };
+            if (this.terminationInfo) out.exitInfo = this.terminationInfo;
+            return Promise.resolve(out);
+        }
+        return new Promise<ExecutionTransition>((resolve) => {
+            const timer = setTimeout(() => {
+                this.removePending(entry);
+                resolve({ state: 'timeout', waitedMs: timeoutMs });
+            }, timeoutMs);
+            const entry: PendingWait = { resolve, timer };
+            this.pendingWaits.push(entry);
+        });
+    }
+
+    private resolvePendingWaits(t: ExecutionTransition): void {
+        const list = this.pendingWaits.splice(0);
+        for (const w of list) {
+            clearTimeout(w.timer);
+            w.resolve(t);
+        }
+    }
+
+    private failPendingWaits(reason: string): void {
+        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}`);
+    }
+
+    private removePending(target: PendingWait): void {
+        const i = this.pendingWaits.indexOf(target);
+        if (i >= 0) this.pendingWaits.splice(i, 1);
+    }
+
+    private snapshotTransition(): ExecutionTransition {
+        if (this.state === 'paused' && this.lastStopped) {
+            return { state: 'paused', stopped: this.lastStopped };
+        }
+        if (this.state === 'terminated') {
+            const out: ExecutionTransition = { 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 --------------------------------------------------------
+
+    private requireClient(): DapClient {
+        if (!this.client) {
+            throw new Error('no active debug session — call debug_launch first');
+        }
+        return this.client;
+    }
+
+    private resetSessionState(): void {
+        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. */
+    private async initSourceMaps(args: LaunchToolArgs): Promise<void> {
+        const mgr = new 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: string;
+        if (this.programIsTs) {
+            const dir  = dirname(args.program);
+            const base = basename(args.program, extname(args.program));
+            ajsPath = join(dir, base + '.ajs');
+        } else {
+            ajsPath = args.program;
+        }
+        ajsPath = resolvePath(ajsPath);
+
+        if (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 = dirname(args.program);
+            await mgr.preload(args.outFiles, workspaceRoot);
+        }
+    }
+
+    private basename(p: string): string {
+        const i = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'));
+        return i >= 0 ? p.slice(i + 1) : p;
+    }
+
+    private errMsg(e: unknown): string {
+        if (e instanceof Error) return e.message;
+        if (typeof e === 'string') return e;
+        try { return JSON.stringify(e); } catch { return String(e); }
+    }
+}