@extension.dev/mcp 7.0.0 → 10.0.0

package/dist/src/lib/act.d.ts

@@ -1,5 +1,8 @@
 export declare function toMcpSpeak(text: string): string;
-export declare function runActVerb(args: string[], projectPath: string, timeoutMs?: number): Promise<string>;
+export declare function runActVerb(args: string[], projectPath: string, timeoutMs?: number, tool?: string): Promise<string>;
+export declare function addWarning(frame: any, text: unknown): void;
+export declare function actFrameJson(frame: unknown): string;
+export declare function patchValue(frame: any, patch: Record<string, unknown>): void;
 export interface ActArgs {
     projectPath: string;
     browser?: string;

package/dist/src/lib/boot-verdict.d.ts

@@ -0,0 +1,53 @@
+import type { ChildProcess } from "node:child_process";
+export interface ProfileLockOwner {
+    host?: string;
+    pid?: number;
+}
+export type BootVerdict = {
+    kind: "alive";
+} | {
+    kind: "exited";
+    exitCode: number | null;
+    signal: string | null;
+} | {
+    kind: "compile-failed";
+    message?: string;
+    compileErrors: string[];
+} | {
+    kind: "browser-exited";
+    stamp: {
+        code?: string;
+        browserExitCode?: number | null;
+        browserExitedAt?: string;
+    };
+} | {
+    kind: "profile-locked";
+    owner: ProfileLockOwner | null;
+    message?: string;
+    lockedAt?: string;
+};
+export interface BootReading {
+    verdict: BootVerdict;
+    /** The CLI stamped a schema-1 ready contract, so no prose was read. */
+    machineContract: boolean;
+    /** Denoised session-log tail, evidence of last resort. Never branched on. */
+    output: string;
+    warnings: string[];
+}
+export interface PollOptions {
+    child: ChildProcess;
+    readOutput: () => string;
+    budgetMs: number;
+    since: number;
+    /** A build-only session never launches a browser, so it has no browser legs. */
+    noBrowser?: boolean;
+    intervalMs?: number;
+}
+export declare function readyContractPath(projectPath: string, browser: string): string;
+export declare function speaksMachineContract(contract: unknown): boolean;
+/**
+ * Poll the dev server's own contract for a boot verdict, and only fall back to
+ * reading its output when the contract never lands. Replaces a blind sleep plus
+ * a regex over first-party copy.
+ */
+export declare function pollBootVerdict(projectPath: string, browser: string, options: PollOptions): Promise<BootReading>;

package/dist/src/lib/bridge-tabs.d.ts

@@ -3,12 +3,12 @@ export interface BridgeTab {
     url: string;
     title: string;
 }
-export declare function listBridgeTabs(projectPath: string, browser: string, timeout?: number): Promise<{
+export declare function listBridgeTabs(projectPath: string, browser: string, timeout?: number, tool?: string): Promise<{
     tabs: BridgeTab[];
 } | {
     error: string;
 }>;
 export declare function matchTabsByUrl(tabs: BridgeTab[], needle: string): BridgeTab[];
 export declare function pollForBridgeTab(projectPath: string, browser: string, url: string, budgetMs: number): Promise<BridgeTab | null>;
-export declare function navigateToUrlViaBridge(projectPath: string, browser: string, url: string, timeout?: number): Promise<string>;
+export declare function navigateToUrlViaBridge(projectPath: string, browser: string, url: string, timeout?: number, tool?: string): Promise<string>;
 export declare function resolveBridgeBaseUrl(projectPath: string, browser: string, timeout?: number): Promise<string | null>;

package/dist/src/lib/common-schema.d.ts

@@ -0,0 +1,28 @@
+export declare const LAUNCHABLE_BROWSERS: readonly ["chrome", "chromium", "edge", "brave", "opera", "vivaldi", "yandex", "firefox", "waterfox", "librewolf", "safari", "chromium-based", "gecko-based", "firefox-based", "webkit-based"];
+export declare const REAL_BROWSERS: readonly ["chrome", "chromium", "edge", "brave", "opera", "vivaldi", "yandex", "firefox", "waterfox", "librewolf", "safari"];
+export declare const MANAGED_BROWSERS: readonly ["chrome", "chromium", "edge", "firefox"];
+export declare const PROJECT_PATH: {
+    readonly type: "string";
+    readonly description: "Extension project root";
+};
+export declare const SESSION_PROJECT_PATH: {
+    readonly type: "string";
+    readonly description: "Extension project root (needs a live dev session)";
+};
+export declare const SESSION_BROWSER: {
+    readonly type: "string";
+    readonly description: "Session browser; defaults to this project's live session";
+};
+export declare const CALL_TIMEOUT: {
+    readonly type: "number";
+    readonly description: "Command timeout in ms (default 5000)";
+};
+export declare const API_BASE: {
+    readonly type: "string";
+    readonly description: "Platform base URL (default EXTENSION_DEV_API_URL, else https://www.extension.dev)";
+};
+export declare const LAUNCH_BROWSER: {
+    readonly type: "string";
+    readonly enum: readonly ["chrome", "chromium", "edge", "brave", "opera", "vivaldi", "yandex", "firefox", "waterfox", "librewolf", "safari", "chromium-based", "gecko-based", "firefox-based", "webkit-based"];
+    readonly default: "chrome";
+};

package/dist/src/lib/envelope.d.ts

@@ -0,0 +1,35 @@
+export declare const ENVELOPE_SCHEMA: 1;
+export type ErrorCode = "E_AMBIGUOUS_TARGET" | "E_AUTH_DENIED" | "E_AUTH_EXPIRED" | "E_AUTH_FAILED" | "E_AUTH_PENDING" | "E_AUTH_REQUIRED" | "E_BAD_MANIFEST" | "E_BAD_REQUEST" | "E_BRIDGE" | "E_BROWSER_EXITED" | "E_BROWSER_INSTALL" | "E_BROWSER_UNINSTALL" | "E_BUILD_FAILED" | "E_CARRIER_IN_DIST" | "E_CDP" | "E_CLI" | "E_COMPILE" | "E_CONFIG" | "E_CONTRACT_ERROR" | "E_CONTROL_CHANNEL" | "E_ENTRYPOINT_MISSING" | "E_FIRST_COMPILE" | "E_INPUT_VALIDATION" | "E_INTERNAL" | "E_LOGS_MISSING" | "E_MANIFEST_BLOCKING" | "E_MANIFEST_NOT_FOUND" | "E_NAVIGATE_ERROR" | "E_NAVIGATE_FAILED" | "E_NETWORK" | "E_NO_CONTROL_CHANNEL" | "E_NO_DIST" | "E_NO_EXTENSION_ID" | "E_NO_MATCHING_TARGET" | "E_NO_REFERENCE_TEMPLATE" | "E_NO_SESSION" | "E_NO_SURFACE_DOCUMENT" | "E_NO_TARGET" | "E_NOT_ATTACHED" | "E_PARSE" | "E_PLATFORM" | "E_PROFILE_LOCKED" | "E_RDP" | "E_SCAFFOLD_FAILED" | "E_SCAFFOLD_INCOMPLETE" | "E_SESSION_EXISTS" | "E_SESSION_EXITED" | "E_STALE_CONTRACT" | "E_SURFACE_DID_NOT_OPEN" | "E_TEMPLATE_FETCH" | "E_TEMPLATE_NOT_FOUND" | "E_UNKNOWN_COMMAND" | "E_UNKNOWN_TOOL" | "E_UNSUPPORTED_BROWSER" | "E_WAIT_TIMEOUT";
+export declare const ERROR_CODES: ErrorCode[];
+export interface EnvelopeError {
+    code: ErrorCode | string;
+    message: string;
+    name?: string;
+    engine?: string | null;
+    hint?: string;
+    [key: string]: unknown;
+}
+export interface Envelope {
+    schema: typeof ENVELOPE_SCHEMA;
+    ok: boolean;
+    command: string;
+    status: string;
+    value: unknown;
+    error: EnvelopeError | null;
+    truncated?: boolean;
+    hint?: string;
+    warnings: string[];
+}
+export interface EnvelopeInit {
+    ok: boolean;
+    command: string;
+    status: string;
+    value?: unknown;
+    error?: EnvelopeError | null;
+    truncated?: boolean;
+    hint?: string;
+    warnings?: (string | null | undefined | false)[];
+}
+export declare function envelopeObject(init: EnvelopeInit): Envelope;
+export declare function envelope(init: EnvelopeInit): string;
+export declare function isEnvelope(frame: unknown): frame is Envelope;

package/dist/src/lib/launch-flags.d.ts

@@ -1,7 +1,7 @@
 export declare const LAUNCH_FLAG_SCHEMA: {
     readonly profile: {
         readonly type: "string";
-        readonly description: "Browser profile path, or \"false\" to reuse the default user profile. Omit for a fresh throwaway profile.";
+        readonly description: "Profile path, or \"false\" to reuse the real user profile. Omit for a throwaway one.";
     };
     readonly startingUrl: {
         readonly type: "string";
@@ -9,26 +9,26 @@ export declare const LAUNCH_FLAG_SCHEMA: {
     };
     readonly chromiumBinary: {
         readonly type: "string";
-        readonly description: "Path to a custom Chromium-based binary (overrides browser)";
+        readonly description: "Custom Chromium-based binary (overrides browser)";
     };
     readonly geckoBinary: {
         readonly type: "string";
-        readonly description: "Path to a custom Gecko/Firefox binary (overrides browser)";
+        readonly description: "Custom Gecko/Firefox binary (overrides browser)";
     };
     readonly host: {
         readonly type: "string";
-        readonly description: "Dev server bind host. Use 0.0.0.0 for Docker or devcontainers. Defaults to 127.0.0.1";
+        readonly description: "Bind host, default 127.0.0.1. Use 0.0.0.0 in Docker or devcontainers.";
     };
     readonly publicHost: {
         readonly type: "string";
-        readonly description: "Connectable host the browser dials for HMR and reload when it differs from the bind host";
+        readonly description: "Host the browser dials for HMR and reload when it differs from the bind host";
     };
     readonly extensions: {
         readonly type: "array";
         readonly items: {
             readonly type: "string";
         };
-        readonly description: "Companion extension paths or store URLs to load alongside the project";
+        readonly description: "Extra extension paths or store URLs to load alongside the project";
     };
 };
 export interface LaunchFlagArgs {

package/dist/src/lib/legacy-stdout.d.ts

@@ -0,0 +1,7 @@
+/** @deprecated see the module note. */
+export declare function denoiseCliLog(raw: string): string;
+/** @deprecated Replaced by `ready.json` `status:"error"`. */
+export declare function legacyCompileScrape(cleanOutput: string): boolean;
+/** @deprecated Replaced by `ready.json` `code:"profile_locked"`. */
+export declare function legacyProfileLockScrape(cleanOutput: string): boolean;
+export declare const LEGACY_FIDELITY_WARNING = "This session ran a CLI that does not stamp the machine contract, so the boot verdict was read from the dev server's output instead of its ready contract. Diagnostics are less precise: compile errors come back as a text tail rather than a list. Upgrade the project's extension dependency to get the precise verdict.";

package/dist/src/lib/session-identity.d.ts

@@ -0,0 +1,16 @@
+export declare const INSTALL_HEADER = "x-extensiondev-install";
+export declare const SESSION_HEADER = "x-extensiondev-session";
+export declare const TOOL_HEADER = "x-extensiondev-tool";
+export declare const ROTATE_AFTER_MS: number;
+export interface StoredInstallIdentity {
+    version: 1;
+    installId: string;
+    rotatedAt: number;
+}
+export declare function installIdentityDir(): string;
+export declare function installIdentityPath(): string;
+export declare function telemetryDisabled(): boolean;
+export declare function resolveInstallId(now?: number): string;
+export declare function sessionId(): string;
+export declare function resetSessionIdentityForTests(): void;
+export declare function identityHeaders(tool: string): Record<string, string>;

package/dist/src/tools/add-feature.d.ts

@@ -5,8 +5,8 @@ export declare const schema: {
         type: "object";
         properties: {
             projectPath: {
-                type: string;
-                description: string;
+                readonly type: "string";
+                readonly description: "Extension project root";
             };
             feature: {
                 type: string;

package/dist/src/tools/analyze.d.ts

@@ -0,0 +1,29 @@
+export declare const schema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectPath: {
+                readonly type: "string";
+                readonly description: "Extension project root";
+            };
+            browser: {
+                type: string;
+                default: string;
+                description: string;
+            };
+            format: {
+                type: string;
+                enum: string[];
+                default: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handler(args: {
+    projectPath: string;
+    browser?: string;
+    format?: string;
+}): Promise<string>;

package/dist/src/tools/auth.d.ts

@@ -0,0 +1,33 @@
+export declare const schema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                default: string;
+            };
+            project: {
+                type: string;
+                description: string;
+            };
+            deviceCode: {
+                type: string;
+                description: string;
+            };
+            api: {
+                readonly type: "string";
+                readonly description: "Platform base URL (default EXTENSION_DEV_API_URL, else https://www.extension.dev)";
+            };
+        };
+        required: never[];
+    };
+};
+export declare function handler(args: {
+    action?: string;
+    project?: string;
+    deviceCode?: string;
+    api?: string;
+}): Promise<string>;

package/dist/src/tools/browsers.d.ts

@@ -0,0 +1,39 @@
+export declare const schema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                default: string;
+            };
+            browsers: {
+                type: string;
+                items: {
+                    type: string;
+                    enum: readonly ["chrome", "chromium", "edge", "brave", "opera", "vivaldi", "yandex", "firefox", "waterfox", "librewolf", "safari"];
+                };
+                description: string;
+            };
+            browser: {
+                type: string;
+                enum: readonly ["chrome", "chromium", "edge", "firefox"];
+                description: string;
+            };
+            all: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+};
+export declare function handler(args: {
+    action?: string;
+    browsers?: string[];
+    browser?: string;
+    all?: boolean;
+}): Promise<string>;

package/dist/src/tools/build.d.ts

@@ -5,14 +5,13 @@ export declare const schema: {
         type: "object";
         properties: {
             projectPath: {
-                type: string;
-                description: string;
+                readonly type: "string";
+                readonly description: "Extension project root";
             };
             browser: {
-                type: string;
-                enum: string[];
-                default: string;
-                description: string;
+                readonly type: "string";
+                readonly enum: readonly ["chrome", "chromium", "edge", "brave", "opera", "vivaldi", "yandex", "firefox", "waterfox", "librewolf", "safari", "chromium-based", "gecko-based", "firefox-based", "webkit-based"];
+                readonly default: "chrome";
             };
             zip: {
                 type: string;

package/dist/src/tools/detect-browsers.d.ts

@@ -1,20 +1 @@
-export declare const schema: {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            browsers: {
-                type: string;
-                items: {
-                    type: string;
-                    enum: string[];
-                };
-                description: string;
-            };
-        };
-    };
-};
-export declare function handler(args: {
-    browsers?: string[];
-}): Promise<string>;
+export declare function detectBrowsers(browsers?: string[]): Promise<string>;

package/dist/src/tools/dev.d.ts

@@ -27,7 +27,7 @@ export declare const schema: {
             };
             profile: {
                 readonly type: "string";
-                readonly description: "Browser profile path, or \"false\" to reuse the default user profile. Omit for a fresh throwaway profile.";
+                readonly description: "Profile path, or \"false\" to reuse the real user profile. Omit for a throwaway one.";
             };
             startingUrl: {
                 readonly type: "string";
@@ -35,35 +35,35 @@ export declare const schema: {
             };
             chromiumBinary: {
                 readonly type: "string";
-                readonly description: "Path to a custom Chromium-based binary (overrides browser)";
+                readonly description: "Custom Chromium-based binary (overrides browser)";
             };
             geckoBinary: {
                 readonly type: "string";
-                readonly description: "Path to a custom Gecko/Firefox binary (overrides browser)";
+                readonly description: "Custom Gecko/Firefox binary (overrides browser)";
             };
             host: {
                 readonly type: "string";
-                readonly description: "Dev server bind host. Use 0.0.0.0 for Docker or devcontainers. Defaults to 127.0.0.1";
+                readonly description: "Bind host, default 127.0.0.1. Use 0.0.0.0 in Docker or devcontainers.";
             };
             publicHost: {
                 readonly type: "string";
-                readonly description: "Connectable host the browser dials for HMR and reload when it differs from the bind host";
+                readonly description: "Host the browser dials for HMR and reload when it differs from the bind host";
             };
             extensions: {
                 readonly type: "array";
                 readonly items: {
                     readonly type: "string";
                 };
-                readonly description: "Companion extension paths or store URLs to load alongside the project";
+                readonly description: "Extra extension paths or store URLs to load alongside the project";
             };
             projectPath: {
-                type: string;
-                description: string;
+                readonly type: "string";
+                readonly description: "Extension project root";
             };
             browser: {
-                type: string;
-                enum: string[];
-                default: string;
+                readonly type: "string";
+                readonly enum: readonly ["chrome", "chromium", "edge", "brave", "opera", "vivaldi", "yandex", "firefox", "waterfox", "librewolf", "safari", "chromium-based", "gecko-based", "firefox-based", "webkit-based"];
+                readonly default: "chrome";
             };
             port: {
                 type: string;

package/dist/src/tools/{dom-inspect.d.ts → dom-snapshot.d.ts}

@@ -6,8 +6,8 @@ export declare const schema: {
         type: "object";
         properties: {
             projectPath: {
-                type: string;
-                description: string;
+                readonly type: "string";
+                readonly description: "Extension project root (needs a live dev session)";
             };
             tab: {
                 type: string;
@@ -55,12 +55,12 @@ export declare const schema: {
                 description: string;
             };
             browser: {
-                type: string;
-                description: string;
+                readonly type: "string";
+                readonly description: "Session browser; defaults to this project's live session";
             };
             timeout: {
-                type: string;
-                description: string;
+                readonly type: "number";
+                readonly description: "Command timeout in ms (default 5000)";
             };
         };
         required: string[];

package/dist/src/tools/eval.d.ts

@@ -6,8 +6,8 @@ export declare const schema: {
         type: "object";
         properties: {
             projectPath: {
-                type: string;
-                description: string;
+                readonly type: "string";
+                readonly description: "Extension project root (needs a live dev session)";
             };
             expression: {
                 type: string;
@@ -27,12 +27,12 @@ export declare const schema: {
                 description: string;
             };
             browser: {
-                type: string;
-                description: string;
+                readonly type: "string";
+                readonly description: "Session browser; defaults to this project's live session";
             };
             timeout: {
-                type: string;
-                description: string;
+                readonly type: "number";
+                readonly description: "Command timeout in ms (default 5000)";
             };
         };
         required: string[];

package/dist/src/tools/get-template-source.d.ts

@@ -1,25 +1,4 @@
-export declare const schema: {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            slug: {
-                type: string;
-                description: string;
-            };
-            files: {
-                type: string;
-                items: {
-                    type: string;
-                };
-                description: string;
-            };
-        };
-        required: string[];
-    };
-};
-export declare function handler(args: {
+export declare function readTemplateSource(args: {
     slug: string;
     files?: string[];
 }): Promise<string>;

package/dist/src/tools/inspect.d.ts

@@ -5,18 +5,42 @@ export declare const schema: {
         type: "object";
         properties: {
             projectPath: {
+                readonly type: "string";
+                readonly description: "Extension project root (needs a live dev session)";
+            };
+            url: {
                 type: string;
                 description: string;
             };
+            probe: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            include: {
+                type: string;
+                items: {
+                    type: string;
+                    enum: string[];
+                };
+                default: string[];
+                description: string;
+            };
             browser: {
+                readonly type: "string";
+                readonly description: "Session browser; defaults to this project's live session";
+            };
+            maxBytes: {
                 type: string;
-                default: string;
+                default: number;
                 description: string;
             };
-            format: {
+            deepDom: {
                 type: string;
-                enum: string[];
-                default: string;
+                default: boolean;
+                description: string;
             };
         };
         required: string[];
@@ -24,6 +48,10 @@ export declare const schema: {
 };
 export declare function handler(args: {
     projectPath: string;
+    url?: string;
+    probe?: string[];
+    include?: string[];
     browser?: string;
-    format?: string;
+    maxBytes?: number;
+    deepDom?: boolean;
 }): Promise<string>;

package/dist/src/tools/install-browser.d.ts

@@ -1,18 +1 @@
-export declare const schema: {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            browser: {
-                type: string;
-                enum: string[];
-                description: string;
-            };
-        };
-        required: string[];
-    };
-};
-export declare function handler(args: {
-    browser: string;
-}): Promise<string>;
+export declare function installManagedBrowser(browser: string): Promise<string>;

package/dist/src/tools/list-browsers.d.ts

@@ -1,9 +1 @@
-export declare const schema: {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {};
-    };
-};
-export declare function handler(): Promise<string>;
+export declare function listManagedBrowsers(): Promise<string>;

package/dist/src/tools/list-extensions.d.ts

@@ -5,12 +5,12 @@ export declare const schema: {
         type: "object";
         properties: {
             projectPath: {
-                type: string;
-                description: string;
+                readonly type: "string";
+                readonly description: "Extension project root (needs a live dev session)";
             };
             browser: {
-                type: string;
-                description: string;
+                readonly type: "string";
+                readonly description: "Session browser; defaults to this project's live session";
             };
         };
         required: string[];