@i-scope/mcp-server 0.4.2

package/dist/src/bridge-driver.d.ts

@@ -0,0 +1,90 @@
+import { 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 { 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 declare class BridgeDriver {
+    private readonly opts;
+    private bridge;
+    private spawned;
+    private initialized;
+    /**
+     * 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;
+    constructor(opts?: BridgeDriverOptions);
+    /**
+     * 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 ensureSpawned;
+    /**
+     * 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 ensureReady;
+    /**
+     * 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 awaitLifecycleSettled;
+    /** 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 runTransition;
+    /** 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;
+    private log;
+    uiModalList(): Promise<UIModalListResponse>;
+    uiModalClick(args: UIModalClickRequest): Promise<UIModalClickResponse>;
+    uiModalFill(args: UIModalFillRequest): Promise<UIModalFillResponse>;
+    uiModalDismiss(args: UIModalDismissRequest): Promise<UIModalDismissResponse>;
+    preflightCheck(): Promise<PreflightCheckResponse>;
+    /** Wire ABI probe via `protocol/version` — no `initialize()`, no COM. */
+    abiCheck(policy?: AbiPolicy): Promise<AbiCheckResult>;
+    openFile(_path: string): Promise<void>;
+    getStatus(): Promise<{
+        status: number;
+        name: string;
+    }>;
+    runScript(_args: {
+        file: string;
+        mwfFile?: string;
+    }): Promise<void>;
+    /** 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. */
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=bridge-driver.d.ts.map

package/dist/src/bridge-driver.js

@@ -0,0 +1,290 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BridgeDriver = void 0;
+const iscope_bridge_client_1 = require("@i-scope/iscope-bridge-client");
+const abi_check_js_1 = require("./abi-check.js");
+/**
+ * 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.
+ */
+class BridgeDriver {
+    opts;
+    // ---- 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`.
+    bridge = null;
+    spawned = false;
+    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.
+     */
+    lifecyclePromise = null;
+    constructor(opts = {}) {
+        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.
+     */
+    async ensureSpawned() {
+        // 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 () => {
+            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.
+     */
+    async ensureReady() {
+        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 () => {
+            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. */
+    async awaitLifecycleSettled() {
+        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. */
+    async runTransition(promise) {
+        // 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). */
+    spawnHelper() {
+        const helperPath = this.opts.helperPath
+            ?? (0, iscope_bridge_client_1.resolveHelperPath)({ bundledRoot: this.opts.bundledRoot });
+        this.log(`[BridgeDriver] spawning helper: ${helperPath}`);
+        return new iscope_bridge_client_1.IScopeBridge({
+            helperPath,
+            requestTimeoutMs: this.opts.requestTimeoutMs ?? 10_000,
+            onStderr: (chunk) => this.log(`[helper-stderr] ${chunk.trimEnd()}`),
+        });
+    }
+    log(line) {
+        if (this.opts.log)
+            this.opts.log(line);
+    }
+    // ---- UI modal control ----------------------------------------------------
+    async uiModalList() {
+        const br = await this.ensureReady();
+        return br.uiModalList();
+    }
+    async uiModalClick(args) {
+        const br = await this.ensureReady();
+        return br.uiModalClick(args);
+    }
+    async uiModalFill(args) {
+        const br = await this.ensureReady();
+        return br.uiModalFill(args);
+    }
+    async uiModalDismiss(args) {
+        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() {
+        const br = await this.ensureSpawned();
+        return br.preflightCheck();
+    }
+    /** Wire ABI probe via `protocol/version` — no `initialize()`, no COM. */
+    async abiCheck(policy) {
+        const br = await this.ensureSpawned();
+        const version = await br.protocolVersion();
+        return (0, abi_check_js_1.evaluateAbiCheck)(version, policy ?? 'strict');
+    }
+    // ---- Phase 2/3 placeholders ---------------------------------------------
+    async openFile(_path) {
+        throw new Error('BridgeDriver.openFile not yet implemented (Phase 2)');
+    }
+    async getStatus() {
+        throw new Error('BridgeDriver.getStatus not yet implemented (Phase 2)');
+    }
+    async runScript(_args) {
+        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() {
+        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 */
+        }
+    }
+}
+exports.BridgeDriver = BridgeDriver;
+//# sourceMappingURL=bridge-driver.js.map

package/dist/src/dap-client.d.ts

@@ -0,0 +1,80 @@
+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;
+}
+/**
+ * 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 declare class DapClient extends EventEmitter {
+    private readonly runtime;
+    private readonly executable;
+    private readonly args;
+    private readonly env;
+    private readonly cwd;
+    private readonly inheritStderr;
+    private readonly log;
+    private child;
+    private childExited;
+    /** 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;
+    /** 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;
+    /** 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;
+    /** 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;
+    defaultTimeoutMs: number;
+    constructor(opts: DapClientOptions);
+    /** 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. */
+    start(): Promise<void>;
+    /** 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>;
+    /** 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>;
+    /** 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. */
+    stop(gracefulMs?: number): Promise<void>;
+    private onStdoutChunk;
+    private dispatch;
+}
+//# sourceMappingURL=dap-client.d.ts.map