unity-mcp-cli 0.70.0 → 0.72.0

package/dist/lib/run-tool.js

@@ -0,0 +1,228 @@
+// Library-safe `runTool` / `runSystemTool` implementations.
+//
+// Constraints (same contract as the rest of `lib/*.ts`):
+// - No commander, no spinners, no process.exit, no console output.
+// - Errors are returned in `{ kind: 'failure', success: false, ... }`,
+//   never thrown past the public boundary.
+import { readConfig, resolveConnectionFromConfig } from '../utils/config.js';
+import { generatePortFromDirectory } from '../utils/port.js';
+import { requireProjectPath } from './validation.js';
+const DEFAULT_TIMEOUT_MS = 60000;
+/**
+ * Invoke a regular MCP tool over the Unity plugin's HTTP API.
+ *
+ * URL/token resolution priority: explicit override → project config →
+ * deterministic localhost port. POSTs to `/api/tools/{name}`. No
+ * console output, no `process.exit`; errors are returned in the
+ * `kind: 'failure'` variant.
+ */
+export async function runTool(opts) {
+    return invokeTool('/api/tools', opts);
+}
+/**
+ * Invoke a system tool (internal tool not exposed to MCP clients) over
+ * the Unity plugin's HTTP API. POSTs to `/api/system-tools/{name}`.
+ */
+export async function runSystemTool(opts) {
+    return invokeTool('/api/system-tools', opts);
+}
+async function invokeTool(routePrefix, opts) {
+    const validationFailure = validateOptions(opts);
+    if (validationFailure)
+        return validationFailure;
+    const resolved = resolveConnection(opts);
+    if (resolved.kind === 'failure')
+        return resolved;
+    const { url, token } = resolved;
+    const body = serializeInput(opts.input);
+    if ('error' in body) {
+        return makeFailure({
+            endpoint: '',
+            reason: 'invalid-input',
+            message: body.error.message,
+            error: body.error,
+        });
+    }
+    const endpoint = `${url}${routePrefix}/${encodeURIComponent(opts.toolName)}`;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const timeoutMs = typeof opts.timeoutMs === 'number' && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const externalAbort = () => controller.abort();
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            controller.abort();
+        else
+            opts.signal.addEventListener('abort', externalAbort, { once: true });
+    }
+    const headers = { 'Content-Type': 'application/json' };
+    if (token)
+        headers['Authorization'] = `Bearer ${token}`;
+    try {
+        const response = await fetchImpl(endpoint, {
+            method: 'POST',
+            headers,
+            body: body.json,
+            signal: controller.signal,
+        });
+        const text = await safeReadText(response);
+        const data = parseJsonOrText(text);
+        if (!response.ok) {
+            return makeFailure({
+                endpoint,
+                reason: 'http-error',
+                httpStatus: response.status,
+                data,
+                message: response.statusText || `HTTP ${response.status}`,
+            });
+        }
+        const success = {
+            kind: 'success',
+            success: true,
+            endpoint,
+            httpStatus: response.status,
+            data,
+        };
+        return success;
+    }
+    catch (err) {
+        return classifyFetchError(err, endpoint, timeoutMs);
+    }
+    finally {
+        clearTimeout(timer);
+        opts.signal?.removeEventListener('abort', externalAbort);
+    }
+}
+function validateOptions(opts) {
+    if (!opts || typeof opts !== 'object') {
+        return makeFailure({
+            endpoint: '',
+            reason: 'invalid-input',
+            message: 'options object is required.',
+        });
+    }
+    if (typeof opts.toolName !== 'string' || opts.toolName.trim().length === 0) {
+        return makeFailure({
+            endpoint: '',
+            reason: 'invalid-input',
+            message: 'toolName is required and must be a non-empty string.',
+        });
+    }
+    const hasUrl = typeof opts.url === 'string' && opts.url.length > 0;
+    const hasProjectPath = typeof opts.unityProjectPath === 'string' && opts.unityProjectPath.trim().length > 0;
+    if (!hasUrl && !hasProjectPath) {
+        return makeFailure({
+            endpoint: '',
+            reason: 'invalid-input',
+            message: 'Either unityProjectPath or url must be provided.',
+        });
+    }
+    return null;
+}
+function resolveConnection(opts) {
+    if (opts.url) {
+        return { kind: 'success', url: opts.url.replace(/\/$/, ''), token: opts.token };
+    }
+    // `unityProjectPath` is library-only — does NOT require an `Assets/`
+    // folder, unlike the CLI's `resolveAndValidateProjectPath`. The
+    // deterministic-port fallback works against the path string alone.
+    const validated = requireProjectPath(opts.unityProjectPath);
+    if (!validated.ok) {
+        return makeFailure({
+            endpoint: '',
+            reason: 'invalid-input',
+            message: validated.error.message,
+            error: validated.error,
+        });
+    }
+    const projectPath = validated.projectPath;
+    const config = readConfig(projectPath);
+    const fromConfig = config
+        ? resolveConnectionFromConfig(config)
+        : { url: undefined, token: undefined };
+    const url = fromConfig.url
+        ? fromConfig.url.replace(/\/$/, '')
+        : `http://localhost:${generatePortFromDirectory(projectPath)}`;
+    return { kind: 'success', url, token: opts.token ?? fromConfig.token };
+}
+function serializeInput(input) {
+    if (input === undefined || input === null)
+        return { json: '{}' };
+    if (typeof input === 'string') {
+        // Validate the round-trip so the server never sees malformed bodies.
+        try {
+            JSON.parse(input);
+            return { json: input };
+        }
+        catch (err) {
+            return {
+                error: new Error(`input string is not valid JSON: ${err instanceof Error ? err.message : String(err)}`),
+            };
+        }
+    }
+    if (typeof input !== 'object') {
+        return {
+            error: new Error('input must be a plain object, JSON string, undefined, or null.'),
+        };
+    }
+    try {
+        return { json: JSON.stringify(input) };
+    }
+    catch (err) {
+        return {
+            error: new Error(`input could not be serialized to JSON: ${err instanceof Error ? err.message : String(err)}`),
+        };
+    }
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '';
+    }
+}
+function parseJsonOrText(text) {
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function getCause(err) {
+    if (!(err instanceof Error) || !('cause' in err))
+        return undefined;
+    return err.cause;
+}
+function classifyFetchError(err, endpoint, timeoutMs) {
+    if (err instanceof Error && err.name === 'AbortError') {
+        return makeFailure({
+            endpoint,
+            reason: 'timeout',
+            message: `Tool call timed out after ${timeoutMs}ms.`,
+            error: err,
+        });
+    }
+    const error = err instanceof Error ? err : new Error(String(err));
+    const causeCode = getCause(err)?.code;
+    let reason = 'unknown';
+    if (causeCode === 'ECONNREFUSED')
+        reason = 'connection-refused';
+    else if (causeCode === 'ECONNRESET')
+        reason = 'connection-reset';
+    else if (causeCode === 'ENOTFOUND' || causeCode === 'EAI_AGAIN')
+        reason = 'network-error';
+    return makeFailure({
+        endpoint,
+        reason,
+        message: error.message,
+        error,
+    });
+}
+function makeFailure(fields) {
+    return { kind: 'failure', success: false, ...fields };
+}
+//# sourceMappingURL=run-tool.js.map

package/dist/lib/run-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-tool.js","sourceRoot":"","sources":["../../src/lib/run-tool.ts"],"names":[],"mappings":"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"}

package/dist/lib/types.d.ts

@@ -42,6 +42,13 @@ export type ProgressEvent = {
     phase: 'editor-launched';
     message: string;
     pid?: number;
+} | {
+    phase: 'launch-errors-dismissed';
+    message: string;
+    /** Button label that was clicked (e.g. `Ignore`). */
+    button: string;
+    /** Platform on which the dismiss was performed (`win32` | `darwin` | `linux`). */
+    platform: string;
 } | {
     phase: 'done';
     message: string;
@@ -251,11 +258,56 @@ export interface OpenProjectOptions {
      * avoid the CLI's stringly-typed `"true"`/`"false"` parse step.
      */
     startServer?: boolean;
+    /**
+     * If `true` (the default), poll for the Unity Editor's
+     * "compile errors at launch" dialog after the editor process has
+     * been spawned and click `Ignore` (or the platform-equivalent
+     * button) so the editor finishes initialising. Set to `false` to
+     * disable the polling loop entirely — corresponds to the CLI's
+     * `--no-auto-dismiss-launch-errors` flag.
+     *
+     * The polling loop runs concurrently with the existing wait-for-
+     * ready logic (which is the authoritative ready signal); when no
+     * dialog appears, behaviour is unchanged from the pre-feature
+     * baseline (no spurious clicks, no extra delay).
+     */
+    autoDismissLaunchErrors?: boolean;
+    /**
+     * Overall timeout (milliseconds) for the launch-errors dismissal
+     * polling loop. The loop ticks every
+     * `launchDismissPollIntervalMs` until either the dialog is
+     * dismissed, this timeout elapses, or `openProject` returns. Default
+     * `30000` (30 s).
+     */
+    launchDismissTimeoutMs?: number;
+    /**
+     * Polling tick interval (milliseconds) for the launch-errors
+     * dismissal loop. Default `1500`.
+     */
+    launchDismissPollIntervalMs?: number;
+    /**
+     * Optional abort signal that, when fired, stops the launch-errors
+     * dismissal polling loop early. Intended for callers that have an
+     * authoritative "Unity is ready" signal in scope (e.g. a parallel
+     * `wait-for-ready` poll) so the dismissal loop does not keep
+     * ticking after Unity has finished initialising.
+     *
+     * When omitted, the loop falls back to a grace window after the
+     * editor process is spawned: if no dialog has been observed within
+     * ~15s of polling, the loop exits early on the assumption that the
+     * dialog is not going to appear for this launch. The grace window
+     * has to cover Unity's full startup phase (process spawn → Package
+     * Manager connect → first compile pass) because the launch-errors
+     * dialog (`"Enter Safe Mode?"` on Unity 2020.2+) appears at the end
+     * of that phase, not the start of it (issue #737).
+     */
+    launchDismissAbortSignal?: AbortSignal;
     /**
      * Optional progress callback — fires for `start`,
      * `detecting-editor-version`, `editors-located`, `editor-resolved`,
-     * `connection-details`, `launching-editor`, `editor-launched`, and
-     * `done`.
+     * `connection-details`, `launching-editor`, `editor-launched`,
+     * `launch-errors-dismissed` (only when a dialog was actually
+     * dismissed), and `done`.
      */
     onProgress?: ProgressCallback;
 }
@@ -324,3 +376,107 @@ export interface OpenEnvInputs {
     transport?: OpenProjectOptions['transport'];
     startServer?: OpenProjectOptions['startServer'];
 }
+/**
+ * Coarse failure category for {@link RunToolFailure}. Mirrors the
+ * branches the CLI's `run-tool` command surfaces in its error path so
+ * library consumers can render the same diagnostics without re-deriving
+ * them from the underlying `Error`.
+ */
+export type RunToolFailureReason = 'invalid-input' | 'connection-refused' | 'connection-reset' | 'network-error' | 'timeout' | 'http-error' | 'unknown';
+/**
+ * Options accepted by both {@link runTool} and {@link runSystemTool}.
+ *
+ * Either `unityProjectPath` (preferred — resolves URL + token from the
+ * project's `UserSettings/AI-Game-Developer-Config.json`, falling back
+ * to a deterministic localhost port when the file is absent) or `url`
+ * (explicit endpoint override) MUST be provided.
+ */
+export interface RunToolOptions {
+    /**
+     * Tool name to invoke. Forwarded as the `{name}` segment of the
+     * route — the function URL-encodes it before issuing the request.
+     */
+    toolName: string;
+    /**
+     * Absolute or relative path to the Unity project. Used to read the
+     * project's config (host + token) and, as a last resort, to derive
+     * the deterministic localhost port mirroring the C# plugin's hash.
+     */
+    unityProjectPath?: string;
+    /** Explicit base URL override (no trailing slash required). */
+    url?: string;
+    /** Bearer token override. */
+    token?: string;
+    /**
+     * Tool arguments, serialized as the JSON request body. When omitted,
+     * the body is `{}`. Anything other than `undefined` / `null` /
+     * `object` is rejected with a `kind: 'failure'` result.
+     */
+    input?: unknown;
+    /**
+     * Per-request timeout in milliseconds. Defaults to `60000` (matching
+     * the CLI command's `--timeout` default). Values <= 0 are treated as
+     * the default to keep accidental "0 = disable" mistakes from
+     * stalling polling callers.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional abort signal. When fired, the in-flight fetch is
+     * cancelled and the result resolves to a `kind: 'failure'` with
+     * `reason: 'timeout'`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional injection point so tests can swap the `fetch`
+     * implementation. Defaults to the global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+/** Successful `runTool` / `runSystemTool` outcome. Narrow with `kind === 'success'`. */
+export interface RunToolSuccess {
+    kind: 'success';
+    /** Always `true` for the success variant. Wire-compatible alias for `kind === 'success'`. */
+    success: true;
+    /** Resolved endpoint URL that was hit (post URL/token resolution). */
+    endpoint: string;
+    /** HTTP status code returned by the Unity plugin. */
+    httpStatus: number;
+    /**
+     * Parsed response body. The Unity plugin returns
+     * `{ status: "success", structured?: <tool output>, content?: <text blocks[]> }`
+     * — consumers typically read `data.structured` or `data.content`
+     * depending on whether the invoked tool returns structured content.
+     * Non-JSON responses surface the raw text string.
+     */
+    data: unknown;
+}
+/** Failed `runTool` / `runSystemTool` outcome. Narrow with `kind === 'failure'`. */
+export interface RunToolFailure {
+    kind: 'failure';
+    /** Always `false` for the failure variant. Wire-compatible alias for `kind === 'failure'`. */
+    success: false;
+    /**
+     * Resolved endpoint URL. Empty string when the failure is
+     * `reason: 'invalid-input'` and resolution never happened.
+     */
+    endpoint: string;
+    /** Coarse cause — see {@link RunToolFailureReason}. */
+    reason: RunToolFailureReason;
+    /** HTTP status code when `reason === 'http-error'`. */
+    httpStatus?: number;
+    /**
+     * Response body for diagnostics on `http-error` (parsed JSON when the
+     * server returned JSON, otherwise the raw text). Omitted on transport
+     * failures where no response was received.
+     */
+    data?: unknown;
+    /** Human-readable failure summary; never thrown past the public boundary. */
+    message: string;
+    /** Captured error, when applicable. */
+    error?: Error;
+}
+export type RunToolResult = RunToolSuccess | RunToolFailure;
+export type RunSystemToolOptions = RunToolOptions;
+export type RunSystemToolResult = RunToolResult;
+export type RunSystemToolSuccess = RunToolSuccess;
+export type RunSystemToolFailure = RunToolFailure;

package/dist/lib.d.ts

@@ -3,4 +3,5 @@ export { removePlugin } from './lib/remove-plugin.js';
 export { configure } from './lib/configure.js';
 export { setupMcp, listAgentIds } from './lib/setup-mcp.js';
 export { openProject } from './lib/open.js';
-export type { ProgressEvent, ProgressCallback, ResultKind, InstallPluginOptions, InstallResult, InstallSuccess, InstallFailure, RemovePluginOptions, RemoveResult, RemoveSuccess, RemoveFailure, ConfigureOptions, ConfigureResult, ConfigureSuccess, ConfigureFailure, ConfigureSnapshot, FeatureAction, McpFeatureSnapshot, SetupMcpOptions, SetupMcpResult, SetupMcpSuccess, SetupMcpFailure, McpTransport, OpenProjectOptions, OpenProjectResult, OpenProjectSuccess, OpenProjectFailure, OpenProjectAuthOption, OpenProjectTransport, } from './lib/types.js';
+export { runTool, runSystemTool } from './lib/run-tool.js';
+export type { ProgressEvent, ProgressCallback, ResultKind, InstallPluginOptions, InstallResult, InstallSuccess, InstallFailure, RemovePluginOptions, RemoveResult, RemoveSuccess, RemoveFailure, ConfigureOptions, ConfigureResult, ConfigureSuccess, ConfigureFailure, ConfigureSnapshot, FeatureAction, McpFeatureSnapshot, SetupMcpOptions, SetupMcpResult, SetupMcpSuccess, SetupMcpFailure, McpTransport, OpenProjectOptions, OpenProjectResult, OpenProjectSuccess, OpenProjectFailure, OpenProjectAuthOption, OpenProjectTransport, RunToolOptions, RunToolResult, RunToolSuccess, RunToolFailure, RunToolFailureReason, RunSystemToolOptions, RunSystemToolResult, RunSystemToolSuccess, RunSystemToolFailure, } from './lib/types.js';

package/dist/lib.js

@@ -20,4 +20,5 @@ export { removePlugin } from './lib/remove-plugin.js';
 export { configure } from './lib/configure.js';
 export { setupMcp, listAgentIds } from './lib/setup-mcp.js';
 export { openProject } from './lib/open.js';
+export { runTool, runSystemTool } from './lib/run-tool.js';
 //# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -1 +1 @@
-{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,qDAAqD;AACrD,iEAAiE;AACjE,sEAAsE;AACtE,oDAAoD;AACpD,yEAAyE;AACzE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,uEAAuE;AACvE,iEAAiE;AACjE,oEAAoE;AACpE,2BAA2B;AAC3B,EAAE;AACF,sEAAsE;AACtE,sDAAsD;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,qDAAqD;AACrD,iEAAiE;AACjE,sEAAsE;AACtE,oDAAoD;AACpD,yEAAyE;AACzE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,uEAAuE;AACvE,iEAAiE;AACjE,oEAAoE;AACpE,2BAA2B;AAC3B,EAAE;AACF,sEAAsE;AACtE,sDAAsD;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/utils/launch-error-dismiss.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Supported `process.platform` values for the launch-errors dialog
+ * dismiss helper. Narrowed alias of NodeJS.Platform — keeps the
+ * platform-dispatch table exhaustive in tests without forcing callers
+ * to import a Node-internal type.
+ */
+export type DismissPlatform = 'win32' | 'darwin' | 'linux';
+/**
+ * Outcome of a single dismiss attempt against the running OS desktop.
+ *
+ * `dismissed`: the dialog was found AND a click was dispatched
+ * successfully. The polling loop should stop and return.
+ *
+ * `not-found`: no matching dialog was visible on this poll tick. The
+ * polling loop should continue ticking until either the overall
+ * timeout elapses or Unity reports ready (the existing wait-for-ready
+ * logic, which runs in parallel, is the authoritative ready signal).
+ *
+ * `error`: an unexpected platform error happened (a required tool was
+ * missing, a syscall failed). The polling loop logs the error once
+ * and continues with `not-found` semantics — the dialog may simply
+ * not be open yet, and a single transient error must not abort the
+ * whole launch flow.
+ */
+export type DismissOutcome = {
+    kind: 'dismissed';
+    button: string;
+} | {
+    kind: 'not-found';
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * Window-title fragments matched against the Unity launch-errors
+ * dialog. Both legacy and current strings are listed so the matcher
+ * stays resilient across Unity versions. The match is case-insensitive
+ * and substring-based — Unity's actual title varies by version but
+ * always contains one of these.
+ *
+ * Exposed so tests can assert the matcher knows about both spellings
+ * without grepping the implementation.
+ */
+export declare const LAUNCH_ERROR_DIALOG_TITLE_FRAGMENTS: readonly string[];
+/** The button label this helper presses to dismiss the dialog. */
+export declare const DISMISS_BUTTON_LABEL = "Ignore";
+/**
+ * Producer-side prefixes for error messages that callers treat as
+ * permanent (the polling loop bails out instead of ticking again).
+ *
+ * Exported so the bailout matcher in `lib/open.ts` and the
+ * error-construction sites below reference the SAME literal — a
+ * future re-word lands in both places at once.
+ *
+ * The matcher in `lib/open.ts` uses `String.includes`, so each
+ * constant just needs to be a stable substring of the full message.
+ */
+export declare const LINUX_XDOTOOL_MISSING_PREFIX = "xdotool not found on PATH";
+export declare const UNSUPPORTED_PLATFORM_PREFIX = "Unsupported platform for launch-errors auto-dismiss";
+/**
+ * Try once to find and dismiss the Unity launch-errors dialog on the
+ * current OS desktop. Pure-ish — performs a single OS call and
+ * returns; never blocks past the underlying syscall's own timeout.
+ *
+ * Library-safe: never throws (errors are returned in the
+ * `DismissOutcome` union), never writes to stdout/stderr, never
+ * mutates global state.
+ *
+ * The helper is platform-dispatched:
+ * - **Windows**: Win32 (`FindWindowW` / `EnumWindows` /
+ *   `EnumChildWindows` / `GetWindowTextW` / `SendMessageW(BM_CLICK)`)
+ *   driven from PowerShell so we do not pull in a native node-gyp
+ *   dependency. UI Automation is the documented fallback if title
+ *   matching breaks on a future Unity release.
+ * - **macOS**: AppleScript via `osascript` (the leaner
+ *   AX-C-API-direct path is a documented follow-up). Requires the
+ *   user to have granted Accessibility permission to the terminal /
+ *   `unity-mcp-cli` binary once.
+ * - **Linux/X11**: `xdotool` (documented as a Linux platform
+ *   dependency; `wmctrl` is acceptable as an alternative window
+ *   enumerator). Wayland is deferred — call out explicitly in the
+ *   error message so the user does not waste time debugging.
+ */
+export declare function tryDismissLaunchErrorsDialog(platform?: DismissPlatform): Promise<DismissOutcome>;
+/**
+ * The PowerShell payload that probes for the Unity launch-errors
+ * dialog and clicks `Ignore` if found. Exported as a string (not a
+ * function) so tests can assert the script shape without launching
+ * PowerShell.
+ *
+ * Strategy:
+ *   1. P/Invoke `EnumWindows` via Add-Type to enumerate every visible
+ *      top-level window owned by `Unity.exe`.
+ *   2. Filter by title fragment (case-insensitive substring).
+ *   3. Walk child windows with `EnumChildWindows`, looking for a
+ *      Button whose text equals `Ignore`.
+ *   4. Send `BM_CLICK` (0x00F5) to the matched button. `BM_CLICK` is
+ *      preferred over a synthesised mouse event — it works even if
+ *      the user is mid-click in another app, and it does not steal
+ *      focus.
+ *
+ * The script writes a single-token result to stdout:
+ *   - `dismissed:<button>` on success
+ *   - `not-found` when no dialog was matched
+ *   - `error:<message>` on an unexpected exception
+ */
+export declare const WINDOWS_DISMISS_PS_SCRIPT: string;
+/**
+ * The AppleScript snippet used for the macOS dismiss path. Exposed as
+ * a string for testability.
+ *
+ * Strategy: iterate every window of the Unity application process and
+ * click the first button titled `Ignore`. If the Unity process is not
+ * running OR no matching button exists, the script reports
+ * `not-found`. Any AppleScript exception (e.g. Accessibility
+ * permission not granted) is reported as `error:<message>` so the
+ * caller can surface it once and continue polling.
+ *
+ * Requires the Terminal / `unity-mcp-cli` binary to have been granted
+ * Accessibility permission in System Settings → Privacy & Security →
+ * Accessibility. Documented in the README.
+ */
+export declare const MACOS_DISMISS_APPLESCRIPT = "\non run\n  try\n    tell application \"System Events\"\n      if not (exists process \"Unity\") then\n        return \"not-found\"\n      end if\n      tell process \"Unity\"\n        repeat with w in windows\n          try\n            if exists (button \"Ignore\" of w) then\n              click button \"Ignore\" of w\n              return \"dismissed:Ignore\"\n            end if\n          end try\n        end repeat\n      end tell\n    end tell\n    return \"not-found\"\n  on error errMsg\n    return \"error:\" & errMsg\n  end try\nend run\n";
+/**
+ * Reset the cached `xdotool` presence flag. Test-only — production
+ * code never needs to call this. Exposed so tests can simulate "the
+ * tool was installed mid-process" without affecting other tests.
+ */
+export declare function _resetXdotoolPresenceForTests(): void;
+/**
+ * Escape a literal string for safe use in `xdotool search --name`.
+ * `xdotool search --name` interprets its argument as a regex; without
+ * escaping, a future fragment containing metacharacters (e.g.
+ * `(Hold On)` or `Compiler Errors v2.0+`) would silently change the
+ * match semantics. The current fragments are regex-safe but this
+ * helper is defensive and zero-runtime-cost.
+ *
+ * Exposed for tests so the regex-safety contract is locked down.
+ */
+export declare function regexEscapeForXdotool(s: string): string;
+/**
+ * Parse the single-token contract every platform-specific dispatcher
+ * writes to stdout. Exposed for tests so we can exhaustively cover
+ * the parser without invoking PowerShell / osascript / xdotool.
+ *
+ * Inspects the LAST non-empty line of stdout, not the whole buffer:
+ * a stray PowerShell warning, `osascript` deprecation notice, or
+ * `xdotool` chatter printed before the contract token must not
+ * misclassify the result as `not-found`.
+ *
+ * Contract:
+ *   - `dismissed:<button>` → `{ kind: 'dismissed', button }`
+ *   - `not-found`          → `{ kind: 'not-found' }`
+ *   - `error:<message>`    → `{ kind: 'error', message }`
+ *   - any other / empty    → `{ kind: 'not-found' }` (defensive — a
+ *     transient parse miss is treated as "not yet visible" rather
+ *     than aborting the polling loop)
+ */
+export declare function parseDismissOutput(stdout: string): DismissOutcome;