@skyramp/mcp 0.5.0-rc.1 → 0.5.0-rc.11

package/build/entitlements/entitlementGate.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { type RunCodes } from "./runCodes.js";
+/**
+ * Makes every tool registered on `server` after this call check the run's
+ * entitlement codes before it runs. Without a run token it does nothing, so
+ * every tool behaves as before. Must be called before any tool is registered.
+ */
+export declare function installEntitlementGate(server: McpServer, readCodes?: () => Promise<RunCodes>, token?: string | undefined): void;

package/build/entitlements/entitlementGate.js

@@ -0,0 +1,57 @@
+import { readRunCodes } from "./runCodes.js";
+import { NOT_GATED, TOOLS } from "../tool-phases.js";
+const FEATURE_NAMES = {
+    analyze: "change analysis",
+    recommend: "test recommendations",
+    generate: "test generation",
+    execute: "test execution",
+};
+function refusal(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+/** Returns why `tool` may not run with these codes, or undefined if it may. */
+function refusalReason(tool, code, run) {
+    if ("refused" in run) {
+        return `Tool ${tool} is not available: Skyramp could not confirm what this run is allowed to do. ${run.refused}`;
+    }
+    if (run.codes.has(code))
+        return undefined;
+    return `Tool ${tool} is not available: your Skyramp plan does not include ${FEATURE_NAMES[code]}.`;
+}
+/**
+ * Makes every tool registered on `server` after this call check the run's
+ * entitlement codes before it runs. Without a run token it does nothing, so
+ * every tool behaves as before. Must be called before any tool is registered.
+ */
+export function installEntitlementGate(server, readCodes = readRunCodes, token = process.env.SKYRAMP_RUN_TOKEN) {
+    if (!token?.trim())
+        return;
+    let codes;
+    const runCodes = () => (codes ??= readCodes()
+        .catch((err) => ({
+        refused: err instanceof Error ? err.message : String(err),
+    }))
+        .then((run) => {
+        // A refusal can be temporary, so the next tool call reads again.
+        if ("refused" in run)
+            codes = undefined;
+        return run;
+    }));
+    // Typed loosely: the gate forwards every argument as it came, whatever
+    // overload the tool used.
+    const target = server;
+    const register = target.registerTool.bind(target);
+    target.registerTool = (name, config, cb) => {
+        const code = TOOLS[name]?.entitlement;
+        if (code === NOT_GATED)
+            return register(name, config, cb);
+        const handler = cb;
+        return register(name, config, async (...args) => {
+            if (code === undefined) {
+                return refusal(`Tool ${name} is not available in this run.`);
+            }
+            const reason = refusalReason(name, code, await runCodes());
+            return reason ? refusal(reason) : handler(...args);
+        });
+    };
+}

package/build/entitlements/runCodes.d.ts

@@ -0,0 +1,18 @@
+export type RunCodes = {
+    codes: ReadonlySet<string>;
+}
+/** Core refused the run token; `refused` is its reason. */
+ | {
+    refused: string;
+};
+type Entitlements = {
+    codes: string[];
+} | {
+    error: string;
+};
+/** The part of SkyrampClient this file uses. Core releases before getEntitlements lack it. */
+export interface Core {
+    getEntitlements?: (repository: string) => Promise<Entitlements>;
+}
+export declare function readRunCodes(core?: Core, env?: NodeJS.ProcessEnv): Promise<RunCodes>;
+export {};

package/build/entitlements/runCodes.js

@@ -0,0 +1,16 @@
+/**
+ * The only file that may ask Skyramp core for the run's entitlement codes.
+ * Everything else in MCP reads them through `readRunCodes`, so a change on the
+ * core side changes this file and nothing else.
+ */
+import { SkyrampClient } from "@skyramp/skyramp";
+import { runRepository } from "../utils/repositorySlug.js";
+export async function readRunCodes(core = new SkyrampClient(), env = process.env) {
+    if (!core.getEntitlements) {
+        return { refused: "This Skyramp version does not support it yet." };
+    }
+    const answer = await core.getEntitlements(runRepository(env) ?? "");
+    return "error" in answer
+        ? { refused: answer.error }
+        : { codes: new Set(answer.codes) };
+}

package/build/index.js

@@ -7,9 +7,12 @@ import { registerTraceTool } from "./tools/trace/startTraceCollectionTool.js";
 import { registerTraceStopTool } from "./tools/trace/stopTraceCollectionTool.js";
 import { registerExecuteSkyrampTestTool } from "./tools/executeSkyrampTestTool.js";
 import { registerExecuteFleetTool } from "./tools/executeFleetTool.js";
+import { registerFleetLifecycleTools } from "./tools/fleetLifecycleTools.js";
+import { fleetRuns } from "./services/FleetRunRegistry.js";
 import { AUTH_PLACEHOLDER_TOKEN } from "./types/TestTypes.js";
 import { AUTH_CONFLICT_ERROR_MSG } from "./prompts/test-recommendation/recommendationSections.js";
 import { logger } from "./utils/logger.js";
+import { installEntitlementGate } from "./entitlements/entitlementGate.js";
 import { registerUITestTool } from "./tools/generate-tests/generateUIRestTool.js";
 import { registerUILoadTestTool } from "./tools/generate-tests/generateUILoadRestTool.js";
 import { registerSmokeTestTool } from "./tools/generate-tests/generateSmokeRestTool.js";
@@ -52,6 +55,7 @@ import { isTestbotEnabled, isLocalDevEnabled, isSkillsLoaded, } from "./utils/fe
 import { findRoot, readTestIdAttribute } from "./utils/pom-scope/index.js";
 import { discoverTestIdAttribute } from "./utils/pom-scope/testIdDiscovery.js";
 import { registerPlaywrightTools, registerTraceRecordingPrompt, getPlaywrightTraceService, } from "./playwright/index.js";
+import { resolveDataSafetyOptions, playwrightToolOptionsFor, } from "./playwright/dataSafetyConfig.js";
 // One-click routing instructions — injected into MCP server instructions so agents
 // know to delegate to the one-click tool rather than self-orchestrating.
 // Suppressed in testbot mode where the testbot prompt drives orchestration.
@@ -155,6 +159,8 @@ async function createServer({ era }) {
   8. The user can always override workspace defaults by explicitly specifying values in their request.
   `,
     });
+    // Before any tool registers, so every tool goes through the check.
+    installEntitlementGate(server);
     // Register prompts
     logger.info("Starting prompt registration process");
     const prompts = [
@@ -239,6 +245,7 @@ async function createServer({ era }) {
         registerLogoutTool,
         registerExecuteSkyrampTestTool,
         registerExecuteFleetTool,
+        registerFleetLifecycleTools,
         registerTraceTool,
         registerTraceStopTool,
     ];
@@ -253,6 +260,11 @@ async function createServer({ era }) {
     infrastructureTools.forEach((registerTool) => registerTool(server));
     // Register Playwright browser tools (trace recording via browser automation).
     //
+    // PlaywrightTraceService (and the fork's network-layer data-safety guard it
+    // wraps) is constructed here, before any per-call `repositoryPath` exists,
+    // and `browser_navigate` itself takes no `repositoryPath` param, so
+    // process.cwd() is the only path data-safety config resolves from.
+    //
     // Tell the capture which attribute this repository uses for test ids. Without
     // it the capture assumes Playwright's `data-testid`, and a repo using anything
     // else gets no test-id anchor and a positional xpath for every element — which
@@ -309,7 +321,13 @@ async function createServer({ era }) {
                 error: err,
             });
         }
-        await registerPlaywrightTools(server, { testIdAttribute });
+        // SKYR-4047: thread data-safety options; resolveDataSafetyOptions returns
+        // undefined in the testbot lane (SKYRAMP_DATA_SAFETY env) so the fork reads env.
+        const dataSafety = await resolveDataSafetyOptions(process.cwd());
+        await registerPlaywrightTools(server, {
+            ...playwrightToolOptionsFor(dataSafety),
+            testIdAttribute,
+        });
     })().catch((err) => {
         logger.error("Failed to register Playwright tools", { error: err });
     });
@@ -325,11 +343,18 @@ async function createServer({ era }) {
         runInitTrigger();
     return server;
 }
+// A crashing process must not stay alive anywhere near the full graceful
+// shutdown's 30s grace — it still gives workers a moment to cancel, but caps
+// it low enough that a crash can't hang the process.
+const CRASH_CLEANUP_WAIT_MS = 3_000;
+/** Interrupt running fleets (bounded wait) so an exit does not leave workers loading. */
+const cancelFleets = () => fleetRuns.cancelAll(CRASH_CLEANUP_WAIT_MS).catch(() => { });
 // Global error handlers for crash telemetry
 process.on("uncaughtException", async (error) => {
     // Don't send analytics for EPIPE errors
     const isEpipeError = "code" in error && error.code === "EPIPE";
     if (isEpipeError) {
+        await cancelFleets();
         process.exit(0);
     }
     logger.critical("Uncaught exception - MCP server crashing", {
@@ -342,6 +367,7 @@ process.on("uncaughtException", async (error) => {
     catch (telemetryError) {
         logger.error("Failed to send crash telemetry", { telemetryError });
     }
+    await cancelFleets();
     process.exit(1);
 });
 // Handle unhandled promise rejections — without this handler Node.js 15+
@@ -351,6 +377,7 @@ process.on("unhandledRejection", async (reason) => {
     const error = reason instanceof Error ? reason : new Error(String(reason));
     // EPIPE means the client already disconnected — exit cleanly
     if ("code" in error && error.code === "EPIPE") {
+        await cancelFleets();
         process.exit(0);
     }
     // gRPC/Docker connectivity errors — log and survive.
@@ -397,7 +424,9 @@ async function main() {
         const cleanupPlaywright = playwrightService
             ? playwrightService.shutdown().catch(() => { })
             : Promise.resolve();
-        cleanupPlaywright.finally(() => {
+        // A running fleet is interrupted so it can cancel its workers, not left loading them.
+        const cleanupFleets = fleetRuns.cancelAll().catch(() => { });
+        Promise.all([cleanupPlaywright, cleanupFleets]).finally(() => {
             handle.close().finally(() => {
                 process.exit(0);
             });

package/build/playwright/PlaywrightTraceService.d.ts

@@ -6,6 +6,7 @@
  * to bridge the module systems.
  */
 import type { CallToolResult } from "@modelcontextprotocol/server";
+import type { DataSafetyOptions } from "./dataSafetyConfig.js";
 interface McpTool {
     name: string;
     description?: string;
@@ -25,6 +26,8 @@ export interface PlaywrightTraceOptions {
      * against, so only this server can supply it.
      */
     testIdAttribute?: string;
+    /** Data safety: the workspace section, for the fork to validate. */
+    dataSafety?: DataSafetyOptions;
 }
 export declare class PlaywrightTraceService {
     private _backend;
@@ -35,6 +38,20 @@ export declare class PlaywrightTraceService {
     isInitialized(): boolean;
     getTools(): McpTool[];
     callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    /**
+     * How long shutdown() waits for the fork's session-end teardown, so a hung
+     * target cannot hold the process forever. Teardown runs after a 5 s
+     * body-read settle, in up to 3 DELETE passes; each DELETE times out after
+     * 10 s, and a pass in which every DELETE timed out is not retried. Several
+     * hung DELETEs can still use up this bound. The fork writes the ledger after
+     * each deletion, so the ledger file is still correct when the bound runs out.
+     */
+    static shutdownTeardownTimeoutMs: number;
+    /**
+     * The fork's serverClosed() starts data-safety teardown and returns at
+     * once. The caller exits the process right after this resolves, so wait
+     * for that work (bounded) — or the teardown DELETEs never reach the target.
+     */
     shutdown(): Promise<void>;
 }
 export {};

package/build/playwright/PlaywrightTraceService.js

@@ -27,6 +27,7 @@ export class PlaywrightTraceService {
                 headless: this._options.headless,
                 outputDir: this._options.outputDir || process.cwd(),
                 testIdAttribute: this._options.testIdAttribute,
+                dataSafety: this._options.dataSafety,
             });
             // Initialize with a synthetic client info
             await this._backend.initialize({
@@ -64,11 +65,38 @@ export class PlaywrightTraceService {
         }
         return this._backend.callTool(name, args);
     }
+    /**
+     * How long shutdown() waits for the fork's session-end teardown, so a hung
+     * target cannot hold the process forever. Teardown runs after a 5 s
+     * body-read settle, in up to 3 DELETE passes; each DELETE times out after
+     * 10 s, and a pass in which every DELETE timed out is not retried. Several
+     * hung DELETEs can still use up this bound. The fork writes the ledger after
+     * each deletion, so the ledger file is still correct when the bound runs out.
+     */
+    static shutdownTeardownTimeoutMs = 30_000;
+    /**
+     * The fork's serverClosed() starts data-safety teardown and returns at
+     * once. The caller exits the process right after this resolves, so wait
+     * for that work (bounded) — or the teardown DELETEs never reach the target.
+     */
     async shutdown() {
         if (this._backend) {
-            this._backend.serverClosed?.();
+            const backend = this._backend;
             this._backend = null;
             this._tools = [];
+            backend.serverClosed?.();
+            const pending = backend.autoExportPromise;
+            if (pending) {
+                let timer;
+                const bound = new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        logger.warning(`Data-safety teardown did not finish within ${PlaywrightTraceService.shutdownTeardownTimeoutMs} ms; exiting anyway`);
+                        resolve();
+                    }, PlaywrightTraceService.shutdownTeardownTimeoutMs);
+                });
+                await Promise.race([pending.catch(() => { }), bound]);
+                clearTimeout(timer);
+            }
             logger.info("PlaywrightTraceService shut down");
         }
     }

package/build/playwright/dataSafetyConfig.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Mcp-side data-safety config resolution + off-limits URL check.
+ *
+ * Resolution stack — which function a caller should reach for:
+ *   - `resolveDataSafetyOptions` (this file): reads the workspace.yml
+ *     `dataSafety` section, honoring the env-var precedence rule below.
+ *     Lowest-level; used to build the fork's `options` argument.
+ *   - `effectiveDataSafetyConfig` (this file): resolves through the fork's
+ *     own `parseDataSafetyConfig` so the result matches exactly what the
+ *     fork's network-layer guard will enforce. Can throw (unguarded require
+ *     of the vendored fork).
+ *   - `safeResolveDataSafety` (safeResolveDataSafety.ts): fail-open wrapper
+ *     around `effectiveDataSafetyConfig`.
+ *   - `resolveDataSafetyForRegistration` (registerPlaywrightTools.ts):
+ *     fail-open wrapper for the enforcement lane specifically — resolves via
+ *     `safeResolveDataSafety` and additionally normalizes an inert result
+ *     (mode "off", no offLimits) to `null` for the navigate pre-check.
+ *
+ * The vendored Playwright fork's DataSafetyGuard/parseDataSafetyConfig read
+ * their config with precedence `options ?? env ?? inert`. Testbot resolves
+ * the full precedence chain (action input > workspace > auto-default) itself
+ * and ships the result via the SKYRAMP_DATA_SAFETY env var, which the fork
+ * reads directly. If mcp ALSO passed options derived from the workspace file
+ * in that lane, options would win over env and silently override testbot's
+ * resolution. So `resolveDataSafetyOptions` returns undefined whenever
+ * SKYRAMP_DATA_SAFETY is set — only the env-less lane (local/manual MCP
+ * usage, no testbot in the loop) reads the workspace section itself.
+ *
+ * The dataSafety section is read out of the raw YAML rather than through the
+ * full strict workspace schema (see workspace/workspace.ts), so an old or
+ * unrelated workspace.yml that fails full schema validation for reasons that
+ * have nothing to do with data safety cannot flip anyone to strict by
+ * accident. A PRESENT dataSafety section goes to the fork as written, and the
+ * fork's validateConfig checks each field on its own: a bad mode fails closed
+ * to strict, and a bad offLimits entry stops every tool call, so a bad field
+ * never drops the fields next to it. A workspace.yml that does not parse but
+ * has a top-level dataSafety key fails closed to strict.
+ */
+export type DataSafetyConfig = {
+    mode: "strict" | "readonly" | "off";
+    offLimits: string[];
+};
+/**
+ * The fork's `options` argument: the workspace.yml dataSafety section as
+ * written, unvalidated. The fork's parseDataSafetyConfig validates it.
+ */
+export type DataSafetyOptions = unknown;
+/**
+ * Resolve mcp-side options for the trace backend. Returns undefined when
+ * SKYRAMP_DATA_SAFETY is set (testbot's resolution wins — see module
+ * docstring) or when no dataSafety signal exists in the workspace file.
+ * Only `mode` (absent means "off") and `offLimits` are passed on, so a field
+ * added to the section later cannot change what the fork enforces.
+ */
+export declare function resolveDataSafetyOptions(workspaceRoot: string): Promise<DataSafetyOptions | undefined>;
+/** The config exactly as the fork's parseDataSafetyConfig will resolve it. */
+export declare function effectiveDataSafetyConfig(workspaceRoot: string): Promise<DataSafetyConfig>;
+/** offLimits check via the fork's own pure matcher so mcp and fork can never disagree. */
+export declare function isOffLimitsUrl(url: string, config: DataSafetyConfig): boolean;
+/**
+ * Maps a resolved data-safety config to the `options` argument
+ * `registerPlaywrightTools` expects, for the enforcement-lane wiring in
+ * index.ts: `resolveDataSafetyOptions(cwd).then(ds => registerPlaywrightTools(server, playwrightToolOptionsFor(ds)))`.
+ * Extracted (rather than an inline arrow at the call site) so the mapping is
+ * directly unit-testable without booting the McpServer — mirrors
+ * `resolveDataSafetyForRegistration`'s existing test approach
+ * (registerPlaywrightTools.dataSafety.test.ts). The return type is left
+ * structural (not `PlaywrightTraceOptions`) to avoid a circular import with
+ * PlaywrightTraceService.ts, which itself imports `DataSafetyConfig` from
+ * this module.
+ */
+export declare function playwrightToolOptionsFor(dataSafety: DataSafetyOptions | undefined): {
+    dataSafety: DataSafetyOptions;
+} | undefined;

package/build/playwright/dataSafetyConfig.js

@@ -0,0 +1,109 @@
+/**
+ * Mcp-side data-safety config resolution + off-limits URL check.
+ *
+ * Resolution stack — which function a caller should reach for:
+ *   - `resolveDataSafetyOptions` (this file): reads the workspace.yml
+ *     `dataSafety` section, honoring the env-var precedence rule below.
+ *     Lowest-level; used to build the fork's `options` argument.
+ *   - `effectiveDataSafetyConfig` (this file): resolves through the fork's
+ *     own `parseDataSafetyConfig` so the result matches exactly what the
+ *     fork's network-layer guard will enforce. Can throw (unguarded require
+ *     of the vendored fork).
+ *   - `safeResolveDataSafety` (safeResolveDataSafety.ts): fail-open wrapper
+ *     around `effectiveDataSafetyConfig`.
+ *   - `resolveDataSafetyForRegistration` (registerPlaywrightTools.ts):
+ *     fail-open wrapper for the enforcement lane specifically — resolves via
+ *     `safeResolveDataSafety` and additionally normalizes an inert result
+ *     (mode "off", no offLimits) to `null` for the navigate pre-check.
+ *
+ * The vendored Playwright fork's DataSafetyGuard/parseDataSafetyConfig read
+ * their config with precedence `options ?? env ?? inert`. Testbot resolves
+ * the full precedence chain (action input > workspace > auto-default) itself
+ * and ships the result via the SKYRAMP_DATA_SAFETY env var, which the fork
+ * reads directly. If mcp ALSO passed options derived from the workspace file
+ * in that lane, options would win over env and silently override testbot's
+ * resolution. So `resolveDataSafetyOptions` returns undefined whenever
+ * SKYRAMP_DATA_SAFETY is set — only the env-less lane (local/manual MCP
+ * usage, no testbot in the loop) reads the workspace section itself.
+ *
+ * The dataSafety section is read out of the raw YAML rather than through the
+ * full strict workspace schema (see workspace/workspace.ts), so an old or
+ * unrelated workspace.yml that fails full schema validation for reasons that
+ * have nothing to do with data safety cannot flip anyone to strict by
+ * accident. A PRESENT dataSafety section goes to the fork as written, and the
+ * fork's validateConfig checks each field on its own: a bad mode fails closed
+ * to strict, and a bad offLimits entry stops every tool call, so a bad field
+ * never drops the fields next to it. A workspace.yml that does not parse but
+ * has a top-level dataSafety key fails closed to strict.
+ */
+import fs from "fs";
+import path from "path";
+import { createRequire } from "module";
+import yaml from "js-yaml";
+import { logger } from "../utils/logger.js";
+const require = createRequire(import.meta.url);
+const TOP_LEVEL_DATA_SAFETY_KEY = /^["']?dataSafety["']?\s*:/m;
+/**
+ * Resolve mcp-side options for the trace backend. Returns undefined when
+ * SKYRAMP_DATA_SAFETY is set (testbot's resolution wins — see module
+ * docstring) or when no dataSafety signal exists in the workspace file.
+ * Only `mode` (absent means "off") and `offLimits` are passed on, so a field
+ * added to the section later cannot change what the fork enforces.
+ */
+export async function resolveDataSafetyOptions(workspaceRoot) {
+    if (process.env.SKYRAMP_DATA_SAFETY?.trim())
+        return undefined;
+    const configPath = path.join(workspaceRoot, ".skyramp", "workspace.yml");
+    let text;
+    try {
+        text = fs.readFileSync(configPath, "utf8");
+    }
+    catch {
+        return undefined; // no file: no signal
+    }
+    let raw;
+    try {
+        raw = yaml.load(text);
+    }
+    catch (error) {
+        if (!TOP_LEVEL_DATA_SAFETY_KEY.test(text))
+            return undefined;
+        logger.warning("workspace.yml is not valid YAML and has a dataSafety section — failing closed to strict, with no offLimits", { error: error instanceof Error ? error.message : String(error) });
+        return { mode: "strict" };
+    }
+    const section = raw?.["dataSafety"];
+    if (section === undefined || section === null)
+        return undefined;
+    if (typeof section !== "object" || Array.isArray(section))
+        return section;
+    const { mode, offLimits } = section;
+    return { mode: mode === undefined ? "off" : mode, offLimits };
+}
+/** The config exactly as the fork's parseDataSafetyConfig will resolve it. */
+export async function effectiveDataSafetyConfig(workspaceRoot) {
+    const options = await resolveDataSafetyOptions(workspaceRoot);
+    const { parseDataSafetyConfig } = require("playwright/lib/mcp/skyramp");
+    return parseDataSafetyConfig(options, process.env.SKYRAMP_DATA_SAFETY);
+}
+/** offLimits check via the fork's own pure matcher so mcp and fork can never disagree. */
+export function isOffLimitsUrl(url, config) {
+    if (!config.offLimits.length)
+        return false;
+    const { matchesOffLimits } = require("playwright/lib/mcp/skyramp");
+    return matchesOffLimits(url, config.offLimits);
+}
+/**
+ * Maps a resolved data-safety config to the `options` argument
+ * `registerPlaywrightTools` expects, for the enforcement-lane wiring in
+ * index.ts: `resolveDataSafetyOptions(cwd).then(ds => registerPlaywrightTools(server, playwrightToolOptionsFor(ds)))`.
+ * Extracted (rather than an inline arrow at the call site) so the mapping is
+ * directly unit-testable without booting the McpServer — mirrors
+ * `resolveDataSafetyForRegistration`'s existing test approach
+ * (registerPlaywrightTools.dataSafety.test.ts). The return type is left
+ * structural (not `PlaywrightTraceOptions`) to avoid a circular import with
+ * PlaywrightTraceService.ts, which itself imports `DataSafetyConfig` from
+ * this module.
+ */
+export function playwrightToolOptionsFor(dataSafety) {
+    return dataSafety !== undefined ? { dataSafety } : undefined;
+}

package/build/playwright/essentialTools.d.ts

@@ -0,0 +1 @@
+export declare const ESSENTIAL_TOOLS: ReadonlySet<string>;

package/build/playwright/essentialTools.js

@@ -0,0 +1,44 @@
+// Only expose essential browser tools to reduce LLM confusion.
+// The full set (23 tools) overwhelms the LLM and causes it to use
+// browser_evaluate/browser_run_code instead of the simpler tools.
+//
+// browser_blueprint is the only DOM Analyzer tool registered — it handles
+// both full captures and same-URL deltas via the URL-cache (isFullCapture).
+// browser_blueprint_diff, browser_sitemap_build, browser_sitemap_query fire
+// 0 times in production evals and have no active call path in the testbot prompt.
+//
+// browser_widget_contract_lookup / browser_widget_contract_cache are
+// intentionally excluded: the curated fingerprint library only covers
+// test fixtures (not production widgets), and the LLM can handle custom
+// widgets via snapshot-driven trial-and-error without the tool.
+// The widgetType field on blueprint elements still signals "custom" to
+// the agent — no guidance is lost.
+export const ESSENTIAL_TOOLS = new Set([
+    "browser_navigate",
+    "browser_snapshot",
+    "browser_click",
+    "browser_type",
+    "browser_press_key",
+    "browser_select_option",
+    "browser_hover",
+    "browser_drag",
+    "browser_file_upload",
+    "browser_evaluate",
+    "browser_tabs",
+    "browser_navigate_back",
+    "browser_wait_for",
+    "browser_take_screenshot",
+    "browser_assert",
+    "browser_assert_hidden",
+    "browser_assert_api_request",
+    "browser_assert_table_cell",
+    "browser_mouse_action",
+    "browser_visual_snapshot",
+    "browser_gojs_add_node",
+    "browser_gojs_link",
+    "skyramp_export_zip",
+    "skyramp_load_trace",
+    "skyramp_finish_test_setup",
+    // DOM Analyzer: blueprint capture (capture-act-capture pattern)
+    "browser_blueprint",
+]);

package/build/playwright/registerPlaywrightTools.d.ts

@@ -3,6 +3,41 @@
  * tools in the Skyramp MCP server, delegating calls to PlaywrightTraceService.
  */
 import { PlaywrightTraceService, type PlaywrightTraceOptions } from "./PlaywrightTraceService.js";
-import type { McpServer } from "@modelcontextprotocol/server";
+import type { DataSafetyConfig } from "./dataSafetyConfig.js";
+import type { McpServer, CallToolResult } from "@modelcontextprotocol/server";
 export declare function getPlaywrightTraceService(): PlaywrightTraceService | null;
+/** Courtesy pre-check so the agent gets an immediate, readable refusal
+ *  instead of a page-level network error. The fork's network layer remains
+ *  the hard guarantee — this is UX, not enforcement — so a throw from the
+ *  matcher (e.g. the vendored fork's require() resolving a partial install)
+ *  must degrade to "not off-limits" rather than block navigation outright. */
+export declare function precheckNavigate(url: string, config: DataSafetyConfig): string | null;
+/**
+ * Pure regression guard for the per-call browser_navigate pre-check: the
+ * `tool.name === "browser_navigate" && config` gate, the params.url
+ * extraction, and the isError result shape, all extracted out of the tool
+ * handler closure so they can be exercised directly under Jest without a
+ * real McpServer/PlaywrightTraceService. The registration call site becomes
+ * `const refusal = maybeRefuseNavigate(...); if (refusal) return refusal;`.
+ * Returns undefined for every "let the call through" case: wrong tool, no
+ * url param, or no config (data safety not configured for this run).
+ */
+export declare function maybeRefuseNavigate(toolName: string, params: unknown, config: DataSafetyConfig | undefined): CallToolResult | undefined;
+/**
+ * Resolves the data-safety pre-check config for `registerPlaywrightTools`
+ * and normalizes an inert result (mode "off" with
+ * no offLimits) to `null`. MUST go through `safeResolveDataSafety` — this
+ * runs after `_service.initialize()` has already succeeded, so an unguarded
+ * rejection here (e.g. the vendored fork's `require()` resolving a partial
+ * install) would abort registration of all 23 Playwright browser tools, not
+ * just the advisory pre-check. The inner try/catch is defense in depth in
+ * case `safeResolveDataSafety` itself ever regresses its no-throw contract —
+ * either way, an undefined/failed resolution degrades to "pre-check inert"
+ * (`null`), never a thrown error.
+ *
+ * Exported (rather than inlined) so it can be exercised directly under Jest
+ * without driving the McpServer-dependent registration flow — see
+ * `registerPlaywrightTools.dataSafety.test.ts`.
+ */
+export declare function resolveDataSafetyForRegistration(cwd: string): Promise<DataSafetyConfig | null>;
 export declare function registerPlaywrightTools(server: McpServer, options?: PlaywrightTraceOptions): Promise<void>;