@i-scope/mcp-server 0.4.2

package/src/tools/source-maps.ts

@@ -0,0 +1,222 @@
+// debug_resolve_source — stand-alone source-map translator.
+//
+// Why it exists separate from the debug session tools:
+//   - AI workflows often need .ts <-> .ajs translation OUTSIDE of an
+//     active debug session — e.g. when inspecting a previously-saved
+//     engine error log (`L4 mhd::core/foo.ajs(123): TypeError ...`)
+//     and wanting to know what TS line that corresponds to.
+//   - No debug-server process, no Oscilloscope dependency. Just disk
+//     reads and the SourceMapManager.
+//
+//   The Phase 1 implementation loads maps on demand (idempotent
+//   cache); Phase 2 may share the cache with DapDriver to avoid
+//   double-parsing the same .ajs.map.
+
+import * as path from 'node:path';
+import { existsSync } from 'node:fs';
+
+import { z } from 'zod';
+
+import { SourceMapManager } from '@i-scope/source-map-bridge';
+
+import { fail, ok, pruneUndefined } from './helpers.js';
+import type { ToolGroupRegistrar } from './registry.js';
+
+// One manager per process. Loads are cached internally, so calling
+// resolve_source repeatedly for the same .ajs is O(1) after the
+// first hit.
+let sharedManager: SourceMapManager | null = null;
+function getManager(): SourceMapManager {
+    if (!sharedManager) {
+        sharedManager = new SourceMapManager({
+            log: (line) => process.stderr.write(`[mcp/sourcemap] ${line}\n`),
+        });
+    }
+    return sharedManager;
+}
+
+const resolveInput = {
+    file: z.string().describe(
+        'Path to a source file. Either a `.ts` (forward direction — looks for `<base>.ajs` next to it OR via `generatedHint`) or a `.ajs` / `.apn` / `.aps` (reverse direction — loads its sidecar .map).',
+    ),
+    line: z.number().int().positive().describe(
+        '1-based line in `file`. DAP / engine convention.',
+    ),
+    column: z.number().int().positive().optional().describe(
+        '1-based column in `file`. Defaults to 1.',
+    ),
+    generatedHint: z.string().optional().describe(
+        'When `file` is `.ts` and the generated `.ajs` is NOT a direct sibling, pass the absolute or relative path to the `.ajs` here. Otherwise this MCP tool guesses `<dirname>/<basename>.ajs`.',
+    ),
+    direction: z.enum(['original->generated', 'generated->original', 'auto']).optional().describe(
+        'Translation direction. "auto" (default) picks based on `file` extension: `.ts` → original->generated, `.ajs`/`.apn`/`.aps` → generated->original. Pass explicitly when you have an unusual extension or want to force a direction (e.g. ask a `.ts` for its OWN line in the SAME file — pass "generated->original" with a `.ts`, the tool will reject it with reason `wrong-direction`).',
+    ),
+};
+
+export const registerSourceMapTools: ToolGroupRegistrar = (server, _drivers) => {
+    void _drivers;
+
+    server.registerTool(
+        'debug_resolve_source',
+        {
+            title: 'Resolve .ts ↔ .ajs source position',
+            description:
+                'Stand-alone source-map translator. NO debug session required. Pass a `.ts` position to get the `.ajs` it compiles to, or a `.ajs` position to get the `.ts` it came from. Useful for: (1) interpreting engine error logs that reference `.ajs` coordinates, (2) sanity-checking that a `.ts` line you plan to set a breakpoint on actually maps to executable `.ajs` code (otherwise the breakpoint will be `verified: false` after debug_set_breakpoints).',
+            inputSchema: resolveInput,
+            outputSchema: {
+                direction: z.enum(['ts->ajs', 'ajs->ts', 'no-map']),
+                input: z.object({ file: z.string(), line: z.number(), column: z.number() }),
+                resolved: z.object({
+                    file:   z.string(),
+                    line:   z.number(),
+                    column: z.number(),
+                }).optional(),
+                reason: z.string().optional(),
+            },
+            annotations: {
+                title: 'Resolve source position',
+                readOnlyHint: true,
+                idempotentHint: true,
+            },
+        },
+        async (args) => {
+            try {
+                const result = await resolve(args);
+                return ok(result);
+            } catch (e) {
+                return fail(`debug_resolve_source failed: ${errMsg(e)}`);
+            }
+        },
+    );
+};
+
+async function resolve(args: {
+    file: string;
+    line: number;
+    column?: number;
+    generatedHint?: string;
+    direction?: 'original->generated' | 'generated->original' | 'auto';
+}): Promise<Record<string, unknown>> {
+    const mgr   = getManager();
+    const file  = path.resolve(args.file);
+    const col   = args.column ?? 1;
+    const isTs       = /\.ts$/i.test(file);
+    const isGen      = /\.(ajs|apn|aps)$/i.test(file);
+    const requested  = args.direction ?? 'auto';
+
+    // Resolve direction from `requested` + file extension.
+    let direction: 'original->generated' | 'generated->original';
+    if (requested === 'auto') {
+        if (isTs) direction = 'original->generated';
+        else if (isGen) direction = 'generated->original';
+        else {
+            return pruneUndefined({
+                direction: 'no-map' as const,
+                input:     { file, line: args.line, column: col },
+                reason:    `cannot auto-detect direction for file extension; pass direction explicitly. file=${file}`,
+            });
+        }
+    } else {
+        direction = requested;
+        // Mismatched explicit direction is a hard error so AI doesn't
+        // silently get nonsense (a .ts asked as generated->original
+        // would either fail later or fall through to the wrong code
+        // path).
+        if (direction === 'original->generated' && !isTs && isGen) {
+            return pruneUndefined({
+                direction: 'no-map' as const,
+                input:     { file, line: args.line, column: col },
+                reason:    `wrong-direction: file ${path.basename(file)} looks generated but direction='original->generated'`,
+            });
+        }
+        if (direction === 'generated->original' && isTs) {
+            return pruneUndefined({
+                direction: 'no-map' as const,
+                input:     { file, line: args.line, column: col },
+                reason:    `wrong-direction: file ${path.basename(file)} is .ts but direction='generated->original'`,
+            });
+        }
+    }
+    const input = { file, line: args.line, column: col };
+
+    if (direction === 'original->generated') {
+        // Forward direction: load the (hinted-or-sibling) .ajs's map
+        // first, THEN ask the manager for the .ts -> .ajs translation.
+        const ajsCandidate = args.generatedHint
+            ? path.resolve(args.generatedHint)
+            : guessSibling(file, '.ajs');
+
+        if (!existsSync(ajsCandidate)) {
+            return pruneUndefined({
+                direction: 'no-map' as const,
+                input,
+                reason:    `generated bundle not found: ${ajsCandidate}. Pass an explicit generatedHint if the .ajs is elsewhere.`,
+            });
+        }
+
+        const loaded = await mgr.loadFor(ajsCandidate);
+        if (!loaded) {
+            return pruneUndefined({
+                direction: 'no-map' as const,
+                input,
+                reason:    `no source map found for ${ajsCandidate}`,
+            });
+        }
+
+        const pos = await mgr.toGenerated(file, args.line, col);
+        if (!pos) {
+            return pruneUndefined({
+                direction: 'ts->ajs' as const,
+                input,
+                reason:    `no mapping for ${path.basename(file)}:${args.line}:${col} in ${path.basename(ajsCandidate)}.map`,
+            });
+        }
+        return pruneUndefined({
+            direction: 'ts->ajs' as const,
+            input,
+            resolved: { file: pos.generatedPath, line: pos.line, column: pos.column },
+        });
+    }
+
+    // Reverse direction (`generated->original`): load file's own map.
+    if (!existsSync(file)) {
+        return pruneUndefined({
+            direction: 'no-map' as const,
+            input,
+            reason:    `file not found: ${file}`,
+        });
+    }
+    const loaded = await mgr.loadFor(file);
+    if (!loaded) {
+        return pruneUndefined({
+            direction: 'no-map' as const,
+            input,
+            reason:    `no source map found for ${file}`,
+        });
+    }
+    const orig = await mgr.toOriginal({ generatedPath: file, line: args.line, column: col });
+    if (!orig) {
+        return pruneUndefined({
+            direction: 'ajs->ts' as const,
+            input,
+            reason:    `no mapping for ${path.basename(file)}:${args.line}:${col} (engine-injected helper or non-emitted statement)`,
+        });
+    }
+    return pruneUndefined({
+        direction: 'ajs->ts' as const,
+        input,
+        resolved: { file: orig.originalPath, line: orig.line, column: orig.column },
+    });
+}
+
+function guessSibling(tsPath: string, generatedExt: string): string {
+    const dir  = path.dirname(tsPath);
+    const base = path.basename(tsPath, path.extname(tsPath));
+    return path.join(dir, base + generatedExt);
+}
+
+function 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); }
+}

package/src/tools/sync.ts

@@ -0,0 +1,90 @@
+// debug_wait_for_paused / debug_read_output.
+
+import { z } from 'zod';
+
+import { fail, ok, shapeOutputEntry, shapeTransition } from './helpers.js';
+import type { ToolGroupRegistrar } from './registry.js';
+
+const transitionShape = z.object({
+    state: z.enum(['paused', 'terminated', 'timeout']),
+    stopped:  z.unknown().optional(),
+    exitInfo: z.unknown().optional(),
+    waitedMs: z.number().optional(),
+});
+
+export const registerSyncTools: ToolGroupRegistrar = (server, { dap }) => {
+    server.registerTool(
+        'debug_wait_for_paused',
+        {
+            title: 'Wait for next pause',
+            description:
+                'Block until the script next pauses (breakpoint, step done, exception) or terminates. Useful when a long-running script is past the timeout of debug_continue / debug_step_*. If the session is already paused / terminated the tool returns immediately.',
+            inputSchema: {
+                timeoutMs: z.number().int().positive().optional().describe(
+                    'Max ms to wait. Defaults to 30 000. Returns {state:"timeout"} when exceeded; the session remains running and you can call again.',
+                ),
+            },
+            outputSchema: { transition: transitionShape },
+            annotations: {
+                title: 'Wait for next pause',
+                idempotentHint: true,
+                readOnlyHint: true,
+            },
+        },
+        async (args) => {
+            try {
+                // Pass `null` as dapCall — we are observing, not
+                // resuming. resumeAndWait short-circuits to a
+                // snapshot if state is already paused / terminated.
+                const t = await dap.resumeAndWait(null, args.timeoutMs);
+                return ok({ transition: shapeTransition(t) });
+            } catch (e) {
+                return fail(`debug_wait_for_paused failed: ${errMsg(e)}`);
+            }
+        },
+    );
+
+    server.registerTool(
+        'debug_read_output',
+        {
+            title: 'Read buffered output',
+            description:
+                'Read `Host.ReportOut(...)` traces and adapter diagnostics emitted since `cursor`. Cursor-based pagination: pass the `nextCursor` from the previous call to read only new entries. Categories: "stdout" (INFO+WARN), "stderr" (ERR + L4+), "console" (adapter diagnostics / break markers). Buffer holds the last 2000 entries by default — older ones are dropped to keep memory bounded.',
+            inputSchema: {
+                cursor: z.number().int().nonnegative().optional().describe(
+                    'Highest entry id you have already read. Defaults to 0 (read from start).',
+                ),
+                limit: z.number().int().positive().optional().describe(
+                    'Max entries to return in one call. Defaults to 1000.',
+                ),
+            },
+            outputSchema: {
+                entries: z.array(z.object({
+                    id:        z.number(),
+                    category:  z.string(),
+                    text:      z.string(),
+                    timestamp: z.number(),
+                })),
+                nextCursor: z.number(),
+            },
+            annotations: {
+                title: 'Read buffered output',
+                idempotentHint: true,
+                readOnlyHint: true,
+            },
+        },
+        async (args) => {
+            const { entries, nextCursor } = dap.readOutput(args.cursor ?? 0, args.limit ?? 1000);
+            return ok({
+                entries:    entries.map(shapeOutputEntry),
+                nextCursor,
+            });
+        },
+    );
+};
+
+function 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); }
+}

package/src/tools/ui-modal.ts

@@ -0,0 +1,201 @@
+// ui_modal_* — interactive control over Oscilloscope's child dialogs.
+//
+// The C++ helper (iScopeBridge.exe) enforces every safety check
+// (oscPid match, main-HWND reject, SendMessageTimeout 500ms); these
+// tools are thin typed wrappers + AI-friendly descriptions.
+//
+// Typical AI workflow when a debug step / continue times out:
+//   1. `ui_modal_list` — is Oscilloscope showing a modal?
+//      → If `modals[].signature === 'configure'`, the script is
+//        blocked on a `Host.Configure()` form.
+//      → If `signature === 'diagnostic'`, Oscilloscope itself is
+//        reporting an error; close it with `ui_modal_dismiss`.
+//   2. `ui_modal_fill` for each Edit/ComboBox to enter values.
+//   3. `ui_modal_click({controlId: 1 /* IDOK */})` to submit.
+//   4. Resume the original `debug_continue` — engine should proceed.
+
+import { z } from 'zod';
+
+import { fail, ok } from './helpers.js';
+import type { ToolGroupRegistrar } from './registry.js';
+
+const controlInfoShape = z.object({
+    hwnd:      z.string(),
+    controlId: z.number(),
+    className: z.string(),
+    text:      z.string(),
+    isVisible: z.boolean(),
+    isEnabled: z.boolean(),
+    isChecked: z.boolean().optional(),
+});
+
+const modalInfoShape = z.object({
+    hwnd:      z.string(),
+    title:     z.string(),
+    className: z.string(),
+    ownerHwnd: z.string(),
+    threadId:  z.number(),
+    signature: z.enum(['configure', 'diagnostic', 'unknown']),
+    controls:  z.array(controlInfoShape),
+});
+
+export const registerUIModalTools: ToolGroupRegistrar = (server, { bridge }) => {
+
+    // ---- ui_modal_list -----------------------------------------------------
+
+    server.registerTool(
+        'ui_modal_list',
+        {
+            title: 'List Oscilloscope modal dialogs',
+            description:
+                'Enumerate every visible top-level dialog owned by Oscilloscope and the controls inside it. ' +
+                'Use this when a debug_continue / debug_step_* unexpectedly times out — the script is most ' +
+                'likely blocked on a Host.Configure() form (signature="configure") or a diagnostic prompt ' +
+                '(signature="diagnostic"). Returns oscPid=0 and empty modals[] when Oscilloscope is not ' +
+                'running. SAFE to call regardless of debug session state; never auto-launches Oscilloscope.',
+            inputSchema: {},
+            outputSchema: {
+                oscPid:   z.number(),
+                mainHwnd: z.string(),
+                modals:   z.array(modalInfoShape),
+            },
+            annotations: {
+                title:          'List Oscilloscope modal dialogs',
+                readOnlyHint:   true,
+                idempotentHint: true,
+            },
+        },
+        async () => {
+            try {
+                const result = await bridge.uiModalList();
+                return ok(result as unknown as Record<string, unknown>);
+            } catch (e) {
+                return fail(`ui_modal_list failed: ${errMsg(e)}`);
+            }
+        },
+    );
+
+    // ---- ui_modal_click ----------------------------------------------------
+
+    server.registerTool(
+        'ui_modal_click',
+        {
+            title: 'Click a button in an Oscilloscope modal',
+            description:
+                'Programmatically click a button (Win32 WM_COMMAND + BN_CLICKED). Standard controlIds: ' +
+                '1=IDOK, 2=IDCANCEL, 6=IDYES, 7=IDNO. Custom buttons in Host.Configure() forms have IDs ' +
+                'reported by ui_modal_list. Always call ui_modal_list first to learn current state and ' +
+                'the right hwnd. Errors -32602 if hwnd belongs to a different process, is the main ' +
+                'window, or the control is disabled.',
+            inputSchema: {
+                hwnd: z.string().describe('Dialog hwnd from ui_modal_list result (e.g. "0x007D185E").'),
+                controlId: z.number().int().describe('Button controlId (1=IDOK, 2=IDCANCEL, 6=IDYES, 7=IDNO, ...).'),
+            },
+            outputSchema: {
+                ok:        z.boolean(),
+                lastError: z.number().optional(),
+            },
+            annotations: {
+                title:           'Click a button in an Oscilloscope modal',
+                destructiveHint: true,
+            },
+        },
+        async (args) => {
+            try {
+                const result = await bridge.uiModalClick({
+                    hwnd: args.hwnd,
+                    controlId: args.controlId,
+                });
+                return ok(result as unknown as Record<string, unknown>);
+            } catch (e) {
+                return fail(`ui_modal_click failed: ${errMsg(e)}`);
+            }
+        },
+    );
+
+    // ---- ui_modal_fill -----------------------------------------------------
+
+    server.registerTool(
+        'ui_modal_fill',
+        {
+            title: 'Fill an Edit or ComboBox in an Oscilloscope modal',
+            description:
+                'Set the text of a child Edit control (WM_SETTEXT) or a ComboBox (CB_FINDSTRINGEXACT + ' +
+                'CB_SETCURSEL when the value matches an existing item, WM_SETTEXT fallback otherwise). ' +
+                'Returns previousText for diffing/verification. Errors -32602 if the control class is ' +
+                'not Edit/ComboBox, the control is disabled, or the dialog is not Oscilloscope-owned.',
+            inputSchema: {
+                hwnd:      z.string().describe('Dialog hwnd from ui_modal_list.'),
+                controlId: z.number().int().describe('Control id from ui_modal_list[*].controls[*].controlId.'),
+                text:      z.string().describe('New text. UTF-8.'),
+            },
+            outputSchema: {
+                ok:           z.boolean(),
+                previousText: z.string(),
+                lastError:    z.number().optional(),
+            },
+            annotations: {
+                title:           'Fill an Edit or ComboBox in an Oscilloscope modal',
+                destructiveHint: true,
+            },
+        },
+        async (args) => {
+            try {
+                const result = await bridge.uiModalFill({
+                    hwnd: args.hwnd,
+                    controlId: args.controlId,
+                    text: args.text,
+                });
+                return ok(result as unknown as Record<string, unknown>);
+            } catch (e) {
+                return fail(`ui_modal_fill failed: ${errMsg(e)}`);
+            }
+        },
+    );
+
+    // ---- ui_modal_dismiss --------------------------------------------------
+
+    server.registerTool(
+        'ui_modal_dismiss',
+        {
+            title: 'Dismiss an Oscilloscope modal',
+            description:
+                'Explicitly close a modal: ' +
+                'mode="close" → PostMessage(WM_CLOSE) (= the X button); ' +
+                'mode="cancel" → SendMessage(WM_COMMAND, IDCANCEL) (= Esc / Cancel button); ' +
+                'mode="ok" → SendMessage(WM_COMMAND, IDOK) (= Enter / OK button). ' +
+                'Default mode is "close". Prefer ui_modal_click for explicit button-by-id semantics when ' +
+                'the dialog has multiple buttons; use this tool when you just need the modal gone.',
+            inputSchema: {
+                hwnd: z.string().describe('Dialog hwnd from ui_modal_list.'),
+                mode: z.enum(['close', 'cancel', 'ok']).optional().describe('Default "close".'),
+            },
+            outputSchema: {
+                ok:        z.boolean(),
+                mode:      z.enum(['close', 'cancel', 'ok']),
+                lastError: z.number().optional(),
+            },
+            annotations: {
+                title:           'Dismiss an Oscilloscope modal',
+                destructiveHint: true,
+            },
+        },
+        async (args) => {
+            try {
+                const result = await bridge.uiModalDismiss({
+                    hwnd: args.hwnd,
+                    mode: args.mode,
+                });
+                return ok(result as unknown as Record<string, unknown>);
+            } catch (e) {
+                return fail(`ui_modal_dismiss failed: ${errMsg(e)}`);
+            }
+        },
+    );
+};
+
+function 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); }
+}