@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/commands/localDevTestChangesCommand.js

@@ -111,13 +111,14 @@ Fallback service routing inputs from the one-click invocation:
 Three rules apply in fallback mode at all times:
 1. **No hand-written tests or mocks**: do NOT use Write, Edit, or any file-writing tool to create test or mock files manually. ALL test and mock files MUST be produced by Skyramp MCP generation tools (\`skyramp_batch_scenario_test_generation\`, \`skyramp_integration_test_generation\`, \`skyramp_generate_enriched_integration_test\`, \`skyramp_contract_test_generation\`, \`skyramp_mock_generation\`, \`skyramp_batch_mock_generation\`). If a generation tool fails, fix the inputs and retry — do not fall back to writing tests by hand.
 2. **Mock scope**: if the user said "mock all downstream services", "mock all", "mock everything", or "mock all except X", treat all discovered downstream dependencies as selected for mocking (same as passing \`servicesToMock: "all"\`). Do not silently default to the third-party-only policy when the user expressed broad mock intent.
-3. **No pytest fallback**: if \`skyramp_execute_test\` becomes unavailable at any point (tool not found, MCP disconnected, context compaction), stop immediately and ask the user to reconnect the Skyramp MCP server. Do not fall back to \`pytest\`, \`python3\`, or any direct runtime — doing so bypasses mock deployment and produces results that cannot be trusted as Skyramp-validated.
+3. **Prefer skyramp_execute_test**: run tests through \`skyramp_execute_test\` rather than the repository's test runner directly: the server records the run, and a run it did not record cannot appear in the report.
 
 ---
 
 `;
     const ctx = {
         repositoryPath: "<REPOSITORY_PATH>",
+        repository: "<OWNER/REPO of the checkout, from its origin remote>",
         baseCommit: "<BASE_BRANCH from one-click baseBranch, default main>",
         maxRecommendations: 8,
         maxGenerate: 5,

package/build/commands/recommendTestsAndExecuteCommand.js

@@ -1,3 +1,4 @@
+import { RUN_TEST_COMMAND_RULES } from "../skills/runTestSkill.js";
 /**
  * Predefined One-Click Command: Recommend tests and generate and execute top recommended tests
  *
@@ -65,13 +66,24 @@ const fullRepoRecommendGenerateExecuteSteps = [
             toolName: "skyramp_execute_test",
             description: "Execute each generated test; resolve token before calling. For each generated test file path returned directly by the generation tools in step 2, invoke this tool with testFile set to that path.",
             inputs: {
-                workspacePath: { source: "user", paramKey: "repositoryPath" },
+                commandOverride: {
+                    source: "literal",
+                    value: `the shell command that runs this one test file with the repository's own test runner (${RUN_TEST_COMMAND_RULES})`,
+                },
+                cwd: { source: "user", paramKey: "repositoryPath" },
                 language: { source: "literal", value: "from workspace" },
-                testType: { source: "literal", value: "from test file / recommendation" },
+                testType: {
+                    source: "literal",
+                    value: "from test file / recommendation",
+                },
                 testFile: {
                     source: "literal",
                     value: "path to a single generated test file; for each test path returned by generation tools in step 2, call skyramp_execute_test separately with testFile set to that path",
                 },
+                repository: {
+                    source: "literal",
+                    value: "owner/repo of the checkout, from its origin remote",
+                },
                 token: { source: "user", paramKey: "token" },
             },
         },
@@ -110,10 +122,6 @@ export const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TESTS_COMMAND = {
     steps: fullRepoRecommendGenerateExecuteSteps,
     inputParams: {
         required: ["repositoryPath"],
-        optional: [
-            "token",
-            "endpointURL",
-            "apiSchema",
-        ],
+        optional: ["token", "endpointURL", "apiSchema"],
     },
 };

package/build/commands/testThisEndpointCommand.js

@@ -1,3 +1,4 @@
+import { RUN_TEST_COMMAND_RULES } from "../skills/runTestSkill.js";
 /**
  * Predefined One-Click Command: Test this endpoint
  *
@@ -73,13 +74,24 @@ const comprehensivelyTestGivenEndpointSteps = [
             toolName: "skyramp_execute_test",
             description: "Execute each generated test; resolve token before calling. For each generated test file path returned directly by the generation tools in step 3, invoke this tool with testFile set to that path.",
             inputs: {
-                workspacePath: { source: "user", paramKey: "repositoryPath" },
+                commandOverride: {
+                    source: "literal",
+                    value: `the shell command that runs this one test file with the repository's own test runner (${RUN_TEST_COMMAND_RULES})`,
+                },
+                cwd: { source: "user", paramKey: "repositoryPath" },
                 language: { source: "literal", value: "from workspace" },
-                testType: { source: "literal", value: "from generated test / recommendation" },
+                testType: {
+                    source: "literal",
+                    value: "from generated test / recommendation",
+                },
                 testFile: {
                     source: "literal",
                     value: "path to a single generated test file; for each test path returned by generation tools in step 3, call skyramp_execute_test separately with testFile set to that path",
                 },
+                repository: {
+                    source: "literal",
+                    value: "owner/repo of the checkout, from its origin remote",
+                },
                 token: { source: "user", paramKey: "token" },
             },
         },
@@ -107,10 +119,27 @@ const comprehensivelyTestGivenEndpointSteps = [
             toolName: "skyramp_execute_test",
             description: "Optionally run existing tests individually; iterate over tests from stateFile and write results back",
             inputs: {
-                workspacePath: { source: "user", paramKey: "repositoryPath" },
-                testFile: { source: "literal", value: "path from stateFile existingTests array" },
-                language: { source: "literal", value: "language from stateFile existingTests array" },
-                testType: { source: "literal", value: "testType from stateFile existingTests array" },
+                commandOverride: {
+                    source: "literal",
+                    value: `the shell command that runs this one test file with the repository's own test runner (${RUN_TEST_COMMAND_RULES})`,
+                },
+                cwd: { source: "user", paramKey: "repositoryPath" },
+                testFile: {
+                    source: "literal",
+                    value: "path from stateFile existingTests array",
+                },
+                language: {
+                    source: "literal",
+                    value: "language from stateFile existingTests array",
+                },
+                testType: {
+                    source: "literal",
+                    value: "testType from stateFile existingTests array",
+                },
+                repository: {
+                    source: "literal",
+                    value: "owner/repo of the checkout, from its origin remote",
+                },
                 token: { source: "user", paramKey: "token" },
                 stateFile: { source: "step", stepIndex: 1, outputKey: "stateFile" },
             },

package/build/execution/wrapperConfig.d.ts

@@ -0,0 +1,56 @@
+/** Playwright's `--browser` names the implicit project itself, so the wrapper must not
+ *  declare one: it refuses the flag when the config defines projects. */
+export declare function commandPassesBrowserFlag(command: string): boolean;
+/** The nearest Playwright config at or above the test file, up to the git root of `cwd`. */
+export declare function findRepoPlaywrightConfig(testFile: string, cwd: string): string | undefined;
+/**
+ * A config that imports the repo's own and overlays only:
+ * - `video: "on"`, top level and per project — Playwright has no `--video` flag, and a
+ *   project's `use` overrides the top level.
+ * - a per-run `outputDir`, so two runs in one checkout keep their videos apart.
+ * - `reuseExistingServer: true` on every `webServer` — the app is already running, and
+ *   `!process.env.CI` would refuse its port.
+ * - the file under test appended to a declared `testMatch`. A repository that names its
+ *   tests `*.test.ts` collects no `*.spec.ts`, so the file Skyramp generated is not a
+ *   test to it and Playwright answers "No tests found" whatever the config or filter.
+ *   Only the top level is widened: a project that declares its own `testMatch` keeps it,
+ *   so the file runs once.
+ * - a project named `chromium`, ONLY when the repository declares no projects and the
+ *   command passes no `--browser`. The Skyramp executor always runs
+ *   `--browser=chromium`, which Playwright turns into a project of that name, so every
+ *   baseline it has written is `<stem>-chromium-linux.png`. With neither a project nor
+ *   the flag the host resolves `<stem>-linux.png`, finds no baseline, and writes a fresh
+ *   one instead of comparing -- a visual regression then passes silently.
+ *   The flag case needs nothing: `--browser=firefox` names the project `firefox` by
+ *   itself. Declaring a project there would not help but throw, because Playwright
+ *   refuses `--browser` when the config defines projects (`common/config.js`:
+ *   "Cannot use --browser option when configuration file defines projects").
+ *   See `utils/rebaselineSnapshots.ts` for the layout.
+ * No reporter: the verdict is the exit code.
+ */
+export declare function buildWrapperConfig(opts: {
+    repoConfigBasename?: string;
+    outputDir: string;
+    /** Absolute path of the file this run executes. */
+    testFile?: string;
+    /** True when the command already passes `--browser`, which names the project itself. */
+    commandPassesBrowserFlag: boolean;
+}): string;
+/**
+ * Writes the wrapper beside the config it imports, because Playwright resolves `testDir`,
+ * `globalSetup` and `webServer.cwd` from the config file's directory. A dotfile with a
+ * random suffix: runs cannot collide and `testMatch` cannot collect it.
+ */
+export declare function writeWrapperConfig(opts: {
+    repoConfigPath?: string;
+    /** Where to write when there is no repo config. */
+    fallbackDir: string;
+    outputDir: string;
+    /** Absolute path of the file this run executes. */
+    testFile?: string;
+    /** True when the command already passes `--browser`, which names the project itself. */
+    commandPassesBrowserFlag: boolean;
+}): {
+    path: string;
+    cleanup: () => void;
+};

package/build/execution/wrapperConfig.js

@@ -0,0 +1,155 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { detectGitRoot } from "../utils/gitStaging.js";
+import { samePath } from "../tools/code-refactor/reuse-state.js";
+/** Playwright's own config names, in its probe order (1.59.1 `configLoader.js:314`).
+ *  A missing name silently drops the repo's config. */
+const CONFIG_NAMES = [
+    "playwright.config.ts",
+    "playwright.config.js",
+    "playwright.config.mts",
+    "playwright.config.mjs",
+    "playwright.config.cts",
+    "playwright.config.cjs",
+];
+/** Playwright's `--browser` names the implicit project itself, so the wrapper must not
+ *  declare one: it refuses the flag when the config defines projects. */
+export function commandPassesBrowserFlag(command) {
+    return /(^|\s)--browser(=|\s)/.test(command);
+}
+/** The nearest Playwright config at or above the test file, up to the git root of `cwd`. */
+export function findRepoPlaywrightConfig(testFile, cwd) {
+    const stop = detectGitRoot(cwd);
+    let dir = path.dirname(path.resolve(testFile));
+    for (;;) {
+        for (const name of CONFIG_NAMES) {
+            const candidate = path.join(dir, name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir || (stop && samePath(dir, stop)))
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * A config that imports the repo's own and overlays only:
+ * - `video: "on"`, top level and per project — Playwright has no `--video` flag, and a
+ *   project's `use` overrides the top level.
+ * - a per-run `outputDir`, so two runs in one checkout keep their videos apart.
+ * - `reuseExistingServer: true` on every `webServer` — the app is already running, and
+ *   `!process.env.CI` would refuse its port.
+ * - the file under test appended to a declared `testMatch`. A repository that names its
+ *   tests `*.test.ts` collects no `*.spec.ts`, so the file Skyramp generated is not a
+ *   test to it and Playwright answers "No tests found" whatever the config or filter.
+ *   Only the top level is widened: a project that declares its own `testMatch` keeps it,
+ *   so the file runs once.
+ * - a project named `chromium`, ONLY when the repository declares no projects and the
+ *   command passes no `--browser`. The Skyramp executor always runs
+ *   `--browser=chromium`, which Playwright turns into a project of that name, so every
+ *   baseline it has written is `<stem>-chromium-linux.png`. With neither a project nor
+ *   the flag the host resolves `<stem>-linux.png`, finds no baseline, and writes a fresh
+ *   one instead of comparing -- a visual regression then passes silently.
+ *   The flag case needs nothing: `--browser=firefox` names the project `firefox` by
+ *   itself. Declaring a project there would not help but throw, because Playwright
+ *   refuses `--browser` when the config defines projects (`common/config.js`:
+ *   "Cannot use --browser option when configuration file defines projects").
+ *   See `utils/rebaselineSnapshots.ts` for the layout.
+ * No reporter: the verdict is the exit code.
+ */
+export function buildWrapperConfig(opts) {
+    const outputDir = JSON.stringify(opts.outputDir);
+    const overlay = `outputDir: ${outputDir},`;
+    // Widen only what the repository declared: with no `testMatch`, Playwright's own
+    // default already collects both spellings, and setting one would narrow it.
+    // One chromium project, used by both branches below. The Skyramp executor runs
+    // --browser=chromium, so every baseline it has written is <stem>-chromium-linux.png;
+    // a wrapper with no project resolves <stem>-linux.png and compares against nothing.
+    // A command that passes --browser names the project itself, and Playwright refuses
+    // the flag when the config declares projects, so there it must stay empty.
+    const chromiumProject = (useExpr) => opts.commandPassesBrowserFlag
+        ? ""
+        : `{ name: "chromium", outputDir: ${outputDir}, use: { ...${useExpr}, browserName: "chromium" } }`;
+    const testMatchOverlay = opts.testFile
+        ? `...(base.testMatch ? { testMatch: [...asList(base.testMatch), ${JSON.stringify(opts.testFile)}] } : {}),`
+        : "";
+    if (!opts.repoConfigBasename) {
+        // No repo config: a minimal one, so video still records.
+        return `const config = {
+  testDir: ".",
+  ${overlay}
+  use: { video: "on" },${chromiumProject('{ video: "on" }')
+            ? `\n  projects: [${chromiumProject('{ video: "on" }')}],`
+            : ""}
+};
+
+export default config;
+`;
+    }
+    return `import base from ${JSON.stringify(`./${opts.repoConfigBasename}`)};
+
+const withVideo = (use) => ({ ...(use ?? {}), video: "on" });
+const reuseServer = (server) => ({ ...server, reuseExistingServer: true });
+
+const asList = (m) => (Array.isArray(m) ? m : [m]);
+
+const config = {
+  ...base,
+  ${overlay}
+  ${testMatchOverlay}
+  use: withVideo(base.use),
+  ...(base.webServer
+    ? {
+        webServer: Array.isArray(base.webServer)
+          ? base.webServer.map(reuseServer)
+          : reuseServer(base.webServer),
+      }
+    : {}),
+  ...(Array.isArray(base.projects) && base.projects.length > 0
+    ? {
+        projects: base.projects.map((p) => ({
+          ...p,
+          outputDir: ${outputDir},
+          use: withVideo(p.use),
+        })),
+      }
+    : ${chromiumProject("withVideo(base.use)")
+        ? `{ projects: [${chromiumProject("withVideo(base.use)")}] }`
+        : "{}"}),
+};
+
+export default config;
+`;
+}
+/**
+ * Writes the wrapper beside the config it imports, because Playwright resolves `testDir`,
+ * `globalSetup` and `webServer.cwd` from the config file's directory. A dotfile with a
+ * random suffix: runs cannot collide and `testMatch` cannot collect it.
+ */
+export function writeWrapperConfig(opts) {
+    const dir = opts.repoConfigPath
+        ? path.dirname(opts.repoConfigPath)
+        : opts.fallbackDir;
+    const wrapperPath = path.join(dir, `.skyramp-sut-${crypto.randomBytes(6).toString("hex")}.config.ts`);
+    fs.writeFileSync(wrapperPath, buildWrapperConfig({
+        repoConfigBasename: opts.repoConfigPath
+            ? path.basename(opts.repoConfigPath)
+            : undefined,
+        outputDir: opts.outputDir,
+        testFile: opts.testFile,
+        commandPassesBrowserFlag: opts.commandPassesBrowserFlag,
+    }));
+    return {
+        path: wrapperPath,
+        cleanup: () => {
+            try {
+                fs.rmSync(wrapperPath, { force: true });
+            }
+            catch {
+                // Best effort: never fail the run over cleanup.
+            }
+        },
+    };
+}

package/build/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { runnableLanguagesText } from "./types/TestTypes.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerStartTraceCollectionPrompt } from "./prompts/startTraceCollectionPrompts.js";
 import { registerTraceTool } from "./tools/trace/startTraceCollectionTool.js";
 import { registerTraceStopTool } from "./tools/trace/stopTraceCollectionTool.js";
 import { registerExecuteSkyrampTestTool } from "./tools/executeSkyrampTestTool.js";
-import { registerRunExistingTestsTool } from "./tools/runExistingTestsTool.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";
@@ -19,10 +19,13 @@ import { registerE2ETestTool } from "./tools/generate-tests/generateE2ERestTool.
 import { registerLoginTool } from "./tools/auth/loginTool.js";
 import { registerLogoutTool } from "./tools/auth/logoutTool.js";
 import { registerFixErrorTool } from "./tools/fixErrorTool.js";
+import { registerVerifyTestDependenciesTool } from "./tools/verifyTestDependenciesTool.js";
 import { registerRecommendTestsPrompt } from "./prompts/test-recommendation/registerRecommendTestsPrompt.js";
 import { registerModularizationTool } from "./tools/code-refactor/modularizationTool.js";
 import { registerCodeReuseTool } from "./tools/code-refactor/codeReuseTool.js";
 import { registerEnhanceAssertionsTool } from "./tools/code-refactor/enhanceAssertionsTool.js";
+import { registerAlignAssertionsTool } from "./tools/code-refactor/alignAssertionsTool.js";
+import { registerAssertionSnapshotTool, registerAssertionVerifyTool, } from "./tools/code-refactor/assertionSkillTools.js";
 import { registerBatchScenarioTestTool } from "./tools/generate-tests/generateBatchScenarioRestTool.js";
 import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js";
 import { registerBatchMockTool } from "./tools/generate-tests/batchMockGenerationTool.js";
@@ -68,6 +71,18 @@ else if (oneClickEnabled) {
 else if (localDevEnabled) {
     oneClickInstructions = localDevInstructions;
 }
+// Global workspace-init nudge for bare MCP usage. Suppressed in testbot mode,
+// which runs its own INIT_WORKSPACE step (buildWorkspaceInitSection()) instead.
+const workspaceInitInstructions = isTestbotEnabled() || oneClickEnabled || localDevEnabled
+    ? ""
+    : `
+## Workspace Initialization (REQUIRED before the first Skyramp tool call)
+If the workspace root is a git repo AND \`.skyramp/workspace.yml\` does not exist:
+1. Call \`skyramp_init_scan\` with \`workspacePath\` set to the current repository root → follow the returned instructions to discover all services.
+2. Call \`skyramp_init_workspace\` with that SAME \`workspacePath\`, \`services\`, and the \`scanToken\` from step 1.
+3. Proceed with the originally requested tool, if it is not one of the two workspace-init tools above.
+Skip only if: not a git repo, \`.skyramp/workspace.yml\` already exists, or user explicitly declines.
+`;
 const server = new McpServer({
     name: "Skyramp MCP Server",
     version: "1.0.0",
@@ -84,7 +99,7 @@ const server = new McpServer({
         },
     },
     instructions: `Skyramp MCP Server — generates and executes API tests (fuzz, contract, integration, E2E, UI).
-
+${workspaceInitInstructions}
 ## Rules
 - NEVER show CLI commands. NEVER attempt to install or configure the Skyramp CLI. ALWAYS use the MCP tools provided.
 - For UI and E2E tests, there are TWO recording modes:
@@ -99,11 +114,12 @@ Use \`skyramp_analyze_changes\` as the single entry point for both test recommen
 1. Call \`skyramp_analyze_changes\` with \`repositoryPath\` and \`scope\` → scans endpoints, computes branch diff, discovers existing tests → returns a \`stateFile\` **and** inline ranked test recommendations.
 2. (Optional) Use the \`skyramp_recommend_tests\` prompt with \`stateFile\` in Cursor/IDE chat for a focused recommendation view.
 
-### Health Analysis (4-step)
+### Health Analysis (5-step)
 1. Call \`skyramp_analyze_changes\` with \`repositoryPath\` and \`scope\` → returns a \`stateFile\`.
-2. Call \`skyramp_analyze_test_health\` with \`stateFile\` → runs drift analysis + health scoring + LLM semantic assessment.
-3. (Optional) Execute tests using \`skyramp_execute_test\` with \`stateFile\` param → validates test status live and writes results back to stateFile for health scoring.
-4. Call \`skyramp_actions\` with \`stateFile\` → executes UPDATE/REGENERATE/ADD recommendations (with execution-aware prioritization if step 3 ran).
+2. Run each external test in ${runnableLanguagesText()} with \`skyramp_execute_test\`, \`phase: "before"\`, and \`stateFile\` → the server runs your command and writes the verdict back to stateFile. The tool takes no other language, and the gate in step 3 does not ask for those.
+3. Call \`skyramp_analyze_test_health\` with \`stateFile\` → runs drift analysis + health scoring + LLM semantic assessment. It refuses until step 2 has run.
+4. (Optional) Run Skyramp-generated tests with \`skyramp_execute_test\` and \`stateFile\` → writes each verdict back for health scoring.
+5. Call \`skyramp_actions\` with \`stateFile\` → executes UPDATE/REGENERATE/ADD recommendations (with execution-aware prioritization if step 4 ran).
 
 After \`skyramp_analyze_changes\`, inspect enriched data via MCP Resources (use the \`sessionId\` returned in the output):
 - \`skyramp://analysis/{sessionId}/summary\` — high-level overview
@@ -172,12 +188,22 @@ const codeQualityTools = [
     registerModularizationTool,
     registerCodeReuseTool,
     registerEnhanceAssertionsTool,
+    registerAssertionVerifyTool,
+    registerVerifyTestDependenciesTool,
 ];
 // With the Skyramp plugin loaded the agent already has the
 // fix-test-import-errors skill; the tool would be a second copy of
 // the same text (SKYR-4296).
 if (!isSkillsLoaded()) {
-    codeQualityTools.push(registerFixErrorTool);
+    // Same reasoning as fix-test-import-errors: with the plugin loaded the agent
+    // has the validate-assertion-alignment-post-execution skill directly; this
+    // tool exists so an agent without skill support still gets the same
+    // procedure, rendered from the same markdown with real arguments filled in.
+    codeQualityTools.push(registerFixErrorTool, registerAlignAssertionsTool);
+}
+else {
+    // The enhance-assertions skill drives its own snapshot step itself (SKYR-4310).
+    codeQualityTools.push(registerAssertionSnapshotTool);
 }
 codeQualityTools.forEach((registerTool) => registerTool(server));
 // Register analysis resources (MCP Resources for enriched data access)
@@ -216,7 +242,6 @@ if (isLocalDevEnabled()) {
 }
 if (isTestbotEnabled()) {
     infrastructureTools.push(registerSubmitReportTool);
-    infrastructureTools.push(registerRunExistingTestsTool);
     logger.info("Testbot tools enabled via SKYRAMP_FEATURE_TESTBOT");
 }
 infrastructureTools.forEach((registerTool) => registerTool(server));
@@ -256,12 +281,17 @@ infrastructureTools.forEach((registerTool) => registerTool(server));
                 // Editing the repo's own Playwright config is the wrong instruction: a
                 // suite may have several, and none of them at the root.
                 logger.info("No testIdAttribute declared or discovered — capture stays on Playwright's data-testid. " +
-                    "Set PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE to override.", { attributesSeenInSelectors: discovered.observed, filesScanned: discovered.filesScanned });
+                    "Set PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE to override.", {
+                    attributesSeenInSelectors: discovered.observed,
+                    filesScanned: discovered.filesScanned,
+                });
             }
         }
     }
     catch (err) {
-        logger.warning("Could not determine this repository's testIdAttribute", { error: err });
+        logger.warning("Could not determine this repository's testIdAttribute", {
+            error: err,
+        });
     }
     await registerPlaywrightTools(server, { testIdAttribute });
 })().catch((err) => {

package/build/playwright/blueprintDigest.js

@@ -15,7 +15,9 @@ export function blueprintJsonSpan(text) {
 const MAX_DEPTH = 12;
 export const MAX_ELEMENTS = 2000;
 function text(value) {
-    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+    return typeof value === "string" && value.trim().length > 0
+        ? value
+        : undefined;
 }
 function rowText(value) {
     if (!Array.isArray(value))
@@ -32,13 +34,21 @@ function fillTemplate(template, parameters) {
     const values = parameters;
     return template.replace(/\{([^{}]+)\}/g, (placeholder, name) => {
         const value = values[name];
-        return typeof value === "string" || typeof value === "number" ? String(value) : placeholder;
+        return typeof value === "string" || typeof value === "number"
+            ? String(value)
+            : placeholder;
     });
 }
 function identity(element) {
     // Serialised rather than joined on a separator: a row's context text is page
     // content and can hold any character, so any separator could be in it.
-    return JSON.stringify([element.role, element.accessibleName, element.testId ?? "", element.stableId ?? "", element.contextText ?? []]);
+    return JSON.stringify([
+        element.role,
+        element.accessibleName,
+        element.testId ?? "",
+        element.stableId ?? "",
+        element.contextText ?? [],
+    ]);
 }
 /** Every element this record describes. A repeating one keeps BOTH its template
  *  and each filled-in row, because the agent lifts a row's rendered name. */
@@ -80,7 +90,9 @@ function collectElements(root) {
     const found = [];
     let truncated = false;
     const seen = new Set();
-    const stack = [{ value: root, depth: 0 }];
+    const stack = [
+        { value: root, depth: 0 },
+    ];
     while (stack.length > 0) {
         if (found.length >= MAX_ELEMENTS) {
             truncated = true;
@@ -117,12 +129,16 @@ function collectElements(root) {
 }
 function urlOf(parsed) {
     const blueprint = parsed.blueprint;
-    const inner = blueprint && typeof blueprint === "object" ? blueprint : undefined;
+    const inner = blueprint && typeof blueprint === "object"
+        ? blueprint
+        : undefined;
     return text(parsed.url) ?? (inner ? text(inner.url) : undefined);
 }
 function pageHashOf(parsed) {
     const blueprint = parsed.blueprint;
-    const inner = blueprint && typeof blueprint === "object" ? blueprint : undefined;
+    const inner = blueprint && typeof blueprint === "object"
+        ? blueprint
+        : undefined;
     return text(parsed.pageHash) ?? (inner ? text(inner.pageHash) : undefined);
 }
 /** The digest of one payload, or undefined when nothing in it keys to a page.
@@ -148,5 +164,10 @@ export function digestFromBlueprintText(payload, previousUrl) {
         return undefined;
     const pageHash = pageHashOf(record);
     const { elements, truncated } = collectElements(record);
-    return { url, ...(pageHash ? { pageHash } : {}), elements, ...(truncated ? { elementsTruncated: true } : {}) };
+    return {
+        url,
+        ...(pageHash ? { pageHash } : {}),
+        elements,
+        ...(truncated ? { elementsTruncated: true } : {}),
+    };
 }

package/build/playwright/registerPlaywrightTools.js

@@ -6,7 +6,8 @@ import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
 import { blueprintJsonSpan } from "./blueprintDigest.js";
-import { recordBlueprintCapture, recordBrowserNavigation } from "./blueprintDigestStore.js";
+import { recordBlueprintCapture, recordBrowserNavigation, } from "./blueprintDigestStore.js";
+import { recordTraceExport } from "./traceExportStore.js";
 let _service = null;
 export function getPlaywrightTraceService() {
     return _service;
@@ -21,6 +22,14 @@ const BLUEPRINT_TOOL = "browser_blueprint";
  * withAssertReminder.
  */
 const NAVIGATE_TOOL = "browser_navigate";
+/**
+ * The one browser tool whose CALL is counted — see traceExportStore.
+ *
+ * The count is what lets `skyramp_submit_report` tell "recorded, and it did not
+ * work" apart from "never recorded". Those two deserve opposite answers, and
+ * without the count the report check can only see the second as the first.
+ */
+const EXPORT_TOOL = "skyramp_export_zip";
 /**
  * The line the agent reads the moment it has reached a page.
  *
@@ -44,11 +53,16 @@ function withAssertReminder(result) {
     const content = result?.content ?? [];
     const last = content.map((block) => block?.type).lastIndexOf("text");
     if (last < 0) {
-        return { ...result, content: [...content, { type: "text", text: ASSERT_REMINDER }] };
+        return {
+            ...result,
+            content: [...content, { type: "text", text: ASSERT_REMINDER }],
+        };
     }
     return {
         ...result,
-        content: content.map((block, i) => i === last && block?.type === "text" ? { ...block, text: `${block.text}\n\n${ASSERT_REMINDER}` } : block),
+        content: content.map((block, i) => i === last && block?.type === "text"
+            ? { ...block, text: `${block.text}\n\n${ASSERT_REMINDER}` }
+            : block),
     };
 }
 /**
@@ -171,32 +185,32 @@ export async function registerPlaywrightTools(server, options) {
     // The widgetType field on blueprint elements still signals "custom" to
     // the agent — no guidance is lost.
     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',
+        "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",
         // DOM Analyzer: blueprint capture (capture-act-capture pattern)
-        'browser_blueprint',
+        "browser_blueprint",
     ]);
     const filteredTools = tools.filter((t) => ESSENTIAL_TOOLS.has(t.name));
     logger.info(`Filtering to ${filteredTools.length} essential tools (from ${tools.length} total)`);
@@ -220,6 +234,11 @@ export async function registerPlaywrightTools(server, options) {
                 };
             }
             const result = await _service.callTool(tool.name, params);
+            // Counted BEFORE any early return and REGARDLESS of isError: an export
+            // that failed still cost the agent a recording, and the report gate that
+            // reads this has to be satisfiable by trying. Returns nothing, never throws.
+            if (tool.name === EXPORT_TOOL)
+                recordTraceExport();
             if (isNavigate) {
                 // The destination this server forwarded, so `skyramp_resolve_screen`
                 // can say where the browser actually is without asking the agent.