@skyramp/mcp 0.3.2 → 0.3.4

package/build/services/TestExecutionService.d.ts

@@ -2,7 +2,7 @@ import { TestExecutionResult, BatchExecutionResult, TestExecutionOptions, Progre
 import { EXECUTOR_DOCKER_IMAGE } from "../utils/versions.js";
 export { EXECUTOR_DOCKER_IMAGE };
 export declare const PLAYWRIGHT_CONFIG_FILES: string[];
-export declare const EXCLUDED_MOUNT_ITEMS: string[];
+export declare const MOUNT_SCAN_SKIP_DIRS: string[];
 export declare const TEST_REPO_CONTAINER_SUBDIR = ".skyramp-test-repo";
 export declare const MOUNT_NULL_ITEMS: string[];
 /**
@@ -38,18 +38,23 @@ export declare function detectSessionFiles(testFilePath: string): string[];
  */
 export declare function findExcludedPaths(dir: string, excludedItems: string[]): string[];
 /**
- * Find every nested `node_modules` directory under `dir` — i.e. all except the
- * top-level `<dir>/node_modules` (which the workspace mount already excludes).
- * Never descends into a `node_modules`. Used to shadow repo-local node_modules
- * that ride into the executor inside a parent directory's wholesale bind-mount;
- * a leaked `@playwright/test` becomes a second physical copy and trips
- * Playwright's "Requiring @playwright/test second time" guard.
+ * Find every `node_modules` directory under `dir`, including the top-level
+ * `<dir>/node_modules`. Never descends into a `node_modules`. Used to shadow
+ * SHADOWED_NESTED_PACKAGES inside each one: a repo-local `@playwright/test`
+ * becomes a second physical copy and trips Playwright's "Requiring
+ * @playwright/test second time" guard.
+ *
+ * The top-level one is deliberately NOT special-cased (SKYR-4140). When
+ * `workspacePath` is itself an npm package root — the standard `tests/<suite>/`
+ * layout — its node_modules IS the only one, so skipping it left the shadow
+ * machinery with nothing to act on and no customer dependency resolvable.
+ *
  * Skips `.git` (nothing importable lives there) and does not follow symlinks —
  * by design (a symlinked nested node_modules either dangles in-container,
  * falling through to NODE_PATH's global copy, or its real-path target is
  * walked directly).
  */
-export declare function findNestedNodeModules(dir: string): string[];
+export declare function findNodeModulesDirs(dir: string): string[];
 export declare class TestExecutionService {
     private docker;
     private imageReady;

package/build/services/TestExecutionService.js

@@ -9,6 +9,8 @@ import { logger } from "../utils/logger.js";
 import { TestExecutionStatus, } from "../types/TestExecution.js";
 import { TestType } from "../types/TestTypes.js";
 import { buildContainerEnv } from "./containerEnv.js";
+import { getWorkspaceScopedQueryParams } from "../utils/workspaceAuth.js";
+import { extractEnvVarNames } from "../workspace/queryParamResolution.js";
 import { EXECUTOR_DOCKER_IMAGE } from "../utils/versions.js";
 import { walkDir } from "../utils/fileWalk.js";
 export { EXECUTOR_DOCKER_IMAGE };
@@ -54,8 +56,11 @@ export const PLAYWRIGHT_CONFIG_FILES = [
     "playwright.config.js",
     "playwright.config.mjs",
 ];
-// Directories to skip mounting entirely (cannot bind-mount /dev/null to a directory)
-export const EXCLUDED_MOUNT_ITEMS = [
+// Directories the recursive shadow scans must never descend into. node_modules
+// IS mounted (see mountRepoTree) — but walking it would shadow every package's
+// own package.json with empty JSON via MOUNT_NULL_ITEMS, breaking resolution
+// for the whole tree.
+export const MOUNT_SCAN_SKIP_DIRS = [
     "node_modules",
 ];
 // Reserved container subdir under /home/user where a cross-repo test repository
@@ -354,7 +359,7 @@ export function detectSessionFiles(testFilePath) {
  */
 export function findExcludedPaths(dir, excludedItems) {
     const results = [];
-    const shouldSkipDir = (entry) => excludedItems.includes(entry.name) || EXCLUDED_MOUNT_ITEMS.includes(entry.name);
+    const shouldSkipDir = (entry) => excludedItems.includes(entry.name) || MOUNT_SCAN_SKIP_DIRS.includes(entry.name);
     for (const [entry, fullPath] of walkDir(dir, { shouldSkipDir })) {
         // Only shadow files — mounting /dev/null to a directory target causes Docker errors
         if (excludedItems.includes(entry.name)) {
@@ -364,18 +369,23 @@ export function findExcludedPaths(dir, excludedItems) {
     return results;
 }
 /**
- * Find every nested `node_modules` directory under `dir` — i.e. all except the
- * top-level `<dir>/node_modules` (which the workspace mount already excludes).
- * Never descends into a `node_modules`. Used to shadow repo-local node_modules
- * that ride into the executor inside a parent directory's wholesale bind-mount;
- * a leaked `@playwright/test` becomes a second physical copy and trips
- * Playwright's "Requiring @playwright/test second time" guard.
+ * Find every `node_modules` directory under `dir`, including the top-level
+ * `<dir>/node_modules`. Never descends into a `node_modules`. Used to shadow
+ * SHADOWED_NESTED_PACKAGES inside each one: a repo-local `@playwright/test`
+ * becomes a second physical copy and trips Playwright's "Requiring
+ * @playwright/test second time" guard.
+ *
+ * The top-level one is deliberately NOT special-cased (SKYR-4140). When
+ * `workspacePath` is itself an npm package root — the standard `tests/<suite>/`
+ * layout — its node_modules IS the only one, so skipping it left the shadow
+ * machinery with nothing to act on and no customer dependency resolvable.
+ *
  * Skips `.git` (nothing importable lives there) and does not follow symlinks —
  * by design (a symlinked nested node_modules either dangles in-container,
  * falling through to NODE_PATH's global copy, or its real-path target is
  * walked directly).
  */
-export function findNestedNodeModules(dir) {
+export function findNodeModulesDirs(dir) {
     const results = [];
     const walk = (current) => {
         let entries;
@@ -392,8 +402,7 @@ export function findNestedNodeModules(dir) {
                 continue;
             const full = path.join(current, entry.name);
             if (entry.name === "node_modules") {
-                if (current !== dir)
-                    results.push(full); // skip the top-level node_modules
+                results.push(full);
                 continue; // never descend into a node_modules
             }
             walk(full);
@@ -593,17 +602,16 @@ export class TestExecutionService {
             hostConfig.Mounts.push(mount);
         };
         // Mount one repo tree (the workspace, or a cross-repo test repository) into
-        // the container, skipping EXCLUDED_MOUNT_ITEMS completely.
+        // the container.
         //
         // Each top-level entry is bind-mounted at the canonical container path and —
         // when mirrorToHost is set — at its host-absolute path too. The dual mount
         // lets the test resolve any absolute reference the codegen happens to embed
         // (storageState, fixture paths, snapshots) — including the host workspace
         // path that Playwright's TypeScript loader sometimes produces from
-        // `__dirname` — without needing source-code detection. EXCLUDED_MOUNT_ITEMS
-        // (node_modules) stays excluded at both targets; MOUNT_NULL_ITEMS shadows
-        // (package.json → empty JSON, etc.), nested-package shadows, and
-        // PLAYWRIGHT_CONFIG_FILES shadows (minimal config) are applied at both
+        // `__dirname` — without needing source-code detection. MOUNT_NULL_ITEMS
+        // shadows (package.json → empty JSON, etc.), node_modules package shadows,
+        // and PLAYWRIGHT_CONFIG_FILES shadows (minimal config) are applied at both
         // targets too so the protections survive regardless of which path the test
         // resolves to.
         //
@@ -611,7 +619,7 @@ export class TestExecutionService {
         // later mounts over earlier ones, so the top-level entry mounts must be
         // pushed BEFORE the shadow mounts that override paths inside them.
         //
-        // The three recursive scans (findExcludedPaths × 2 + findNestedNodeModules)
+        // The three recursive scans (findExcludedPaths × 2 + findNodeModulesDirs)
         // are deliberately kept as separate walks rather than fused into one pass:
         // each skips node_modules/.git so the cost is small, and separate walks keep
         // each shadow category's semantics independently testable.
@@ -623,11 +631,13 @@ export class TestExecutionService {
             // otherwise the entry mount would win the dedup race and the repo's own
             // config (which may import dotenv, or simply isn't the minimal/generated
             // one) would leak into the container.
+            //
+            // node_modules is NOT filtered out (SKYR-4140): it carries the customer's
+            // test-support deps, and the per-package shadows below neutralise the only
+            // copies that must not load from the repo.
             const entriesToMount = fs
                 .readdirSync(hostRoot)
-                .filter((file) => !EXCLUDED_MOUNT_ITEMS.includes(file) &&
-                !MOUNT_NULL_ITEMS.includes(file) &&
-                !PLAYWRIGHT_CONFIG_FILES.includes(file));
+                .filter((file) => !MOUNT_NULL_ITEMS.includes(file) && !PLAYWRIGHT_CONFIG_FILES.includes(file));
             for (const file of entriesToMount) {
                 const source = path.join(hostRoot, file);
                 pushMount({ Type: "bind", Target: path.join(containerRoot, file), Source: source });
@@ -644,10 +654,9 @@ export class TestExecutionService {
                     pushMount({ Type: "bind", Source: source, Target: absolutePath });
                 }
             }
-            // Shadow SHADOWED_NESTED_PACKAGES inside every nested node_modules leaked in
-            // via a parent-directory bind-mount (see findNestedNodeModules) — the
-            // top-level node_modules is already excluded above via EXCLUDED_MOUNT_ITEMS.
-            for (const nested of findNestedNodeModules(hostRoot)) {
+            // Shadow SHADOWED_NESTED_PACKAGES inside every mounted node_modules — the
+            // repo's own top-level one included (see findNodeModulesDirs).
+            for (const nested of findNodeModulesDirs(hostRoot)) {
                 for (const pkg of SHADOWED_NESTED_PACKAGES) {
                     const pkgPath = path.join(nested, pkg);
                     if (!fs.existsSync(pkgPath))
@@ -711,6 +720,22 @@ export class TestExecutionService {
         if (crossRepoTestRoot) {
             mountRepoTree(crossRepoTestRoot, path.join(containerMountPath, TEST_REPO_CONTAINER_SUBDIR), true);
         }
+        // runner.sh invokes `npx playwright test`, and npx resolves binaries from
+        // <cwd>/node_modules/.bin before PATH — cwd is always containerMountPath. Now
+        // that node_modules is mounted (SKYR-4140), a repo-local .bin/playwright would
+        // run instead of the image's global CLI. The per-package shadows above do not
+        // cover it under a pnpm layout, where .bin/playwright symlinks into .pnpm/
+        // rather than into node_modules/playwright. Shadow this one .bin — the only
+        // one npx can reach — so binary resolution falls through to PATH as before.
+        // Pushed after mountRepoTree so it layers over the node_modules entry mount.
+        if (fs.existsSync(path.join(workspacePath, "node_modules", ".bin"))) {
+            pushMount({
+                Type: "bind",
+                Source: EMPTY_DIR_PATH,
+                Target: path.join(containerMountPath, "node_modules", ".bin"),
+                ReadOnly: true,
+            });
+        }
         // Mount video output directory for browser tests (writable)
         if (browserTest && videoHostDir) {
             pushMount({
@@ -794,7 +819,29 @@ export class TestExecutionService {
                 mountedPaths.add(saveStorageTarget);
             }
         }
-        const env = buildContainerEnv(options, saveStorageTargetPath);
+        // Forward the environment variables this workspace's query params declare
+        // via `env.VAR` (SKYR-4127). The references resolve where the test runs, so
+        // without this they resolve to nothing inside the container and the query
+        // param is dropped from the request silently.
+        //
+        // getWorkspaceScopedQueryParams already returns undefined on a read or
+        // parse failure, so those degrade quietly to the pre-existing behavior.
+        // This guard covers only an unexpected throw, and must not fail an
+        // otherwise valid execution.
+        let passthroughNames = [];
+        try {
+            const scoped = await getWorkspaceScopedQueryParams(workspacePath);
+            if (scoped) {
+                passthroughNames = extractEnvVarNames(scoped);
+                if (passthroughNames.length > 0) {
+                    logger.debug(`Forwarding workspace-declared environment variables to the executor: ${passthroughNames.join(", ")}`);
+                }
+            }
+        }
+        catch (err) {
+            logger.warning(`Could not resolve workspace environment passthrough: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const env = buildContainerEnv(options, saveStorageTargetPath, process.env, passthroughNames);
         // Capture output
         let output = "";
         class DockerStream extends Writable {

package/build/services/TestGenerationService.js

@@ -2,7 +2,8 @@ import path from "path";
 import fs from "fs";
 import { SkyrampClient } from "@skyramp/skyramp";
 import { analyzeOpenAPIWithGivenEndpoint } from "../utils/analyze-openapi.js";
-import { isAuthorizationHeaderName, KNOWN_AUTH_HEADERS, resolveAuthFromWorkspace, getWorkspaceSkipTLSVerify, getWorkspaceDefaultQueryParams, mergeQueryParamsString, } from "../utils/workspaceAuth.js";
+import { isAuthorizationHeaderName, KNOWN_AUTH_HEADERS, resolveAuthFromWorkspace, getWorkspaceSkipTLSVerify, getWorkspaceScopedQueryParams, mergeQueryParamsString, } from "../utils/workspaceAuth.js";
+import { extractPathname, resolveQueryParamsForPath, contributesNothing } from "../workspace/queryParamResolution.js";
 import { getPathParameterValidationError, OUTPUT_DIR_FIELD_NAME, PATH_PARAMS_FIELD_NAME, QUERY_PARAMS_FIELD_NAME, FORM_PARAMS_FIELD_NAME, validateParams, validatePath, validateRequestData, } from "../utils/utils.js";
 import { getEntryPoint } from "../utils/telemetry.js";
 import { getLanguageSteps } from "../utils/language-helper.js";
@@ -364,17 +365,31 @@ The generated test file remains unchanged and ready to use as-is.
                     logger.warning("Could not resolve skipTLSVerify from workspace config");
                 }
             }
-            // Workspace-declared default query params (SKYR-4050): api.defaultQueryParams
-            // are attached to every generated request for the service. Existing
-            // queryParams entries (explicit caller values) always win on a key collision.
+            // Workspace-declared query params (SKYR-4050, path-scoped in SKYR-4127):
+            // api.defaultQueryParams is the base map; api.queryParamOverrides layers
+            // the most-specific matching pathPattern on top. Existing queryParams
+            // entries (explicit caller values) always win on a key collision.
             if (!SKIP_DEFAULT_QUERY_PARAMS_TEST_TYPES.has(this.getTestType())) {
                 try {
                     const repoPath = generateOptions.outputDir || process.cwd();
-                    const defaults = await getWorkspaceDefaultQueryParams(repoPath);
-                    if (defaults) {
-                        generateOptions.queryParams = mergeQueryParamsString(generateOptions.queryParams, defaults);
-                        logger.info("Merged workspace defaultQueryParams into queryParams", {
-                            keys: Object.keys(defaults),
+                    const scoped = await getWorkspaceScopedQueryParams(repoPath);
+                    // Skip the merge entirely when the resolved config contributes
+                    // nothing — otherwise an empty/null defaultQueryParams declaration
+                    // with no overrides would set queryParams to "" where the old code
+                    // left the field untouched (Finding 4, SKYR-4127 final review).
+                    if (scoped && !contributesNothing(scoped)) {
+                        const pathname = extractPathname(generateOptions.uri);
+                        if (!pathname && scoped.overrides.length > 0) {
+                            logger.warning("queryParamOverrides configured but this generation call has no single endpoint path; " +
+                                "applying api.defaultQueryParams only", { patterns: scoped.overrides.map((o) => o.pathPattern) });
+                        }
+                        const effective = pathname
+                            ? resolveQueryParamsForPath(scoped, pathname)
+                            : { ...scoped.base };
+                        generateOptions.queryParams = mergeQueryParamsString(generateOptions.queryParams, effective);
+                        logger.info("Merged workspace query params into queryParams", {
+                            keys: Object.keys(effective),
+                            pathname,
                         });
                     }
                 }

package/build/services/containerEnv.d.ts

@@ -8,7 +8,18 @@ import { TestExecutionOptions } from "../types/TestExecution.js";
  * host.docker.internal is mapped via ExtraHosts in TestExecutionService.
  */
 export declare function rewriteLocalhostForDocker(url: string): string;
+/** Why a name is refused, or null when it is allowed. The two reasons need
+ *  different messages: a reserved name is already provided by the executor, so
+ *  the declaration is only redundant, while a credential name is refused. */
+export declare function passthroughDenyReason(name: string): "reserved" | "credential" | null;
+/** True when a name is refused regardless of who declared it. */
+export declare function isDeniedPassthroughName(name: string): boolean;
+/** A name is interpolated directly into a Docker `Env` entry, which is a plain
+ *  `NAME=value` string. A name holding `=`, whitespace or a newline produces a
+ *  malformed entry and can inject a second variable. workspace.yml supplies
+ *  these names, so `env.FOO=BAR` would yield the name `FOO=BAR`. */
+export declare function isValidEnvVarName(name: string): boolean;
 /**
  * Build the environment variable array for the Docker executor container.
  */
-export declare function buildContainerEnv(options: Pick<TestExecutionOptions, "token" | "language" | "useHostNetwork">, saveStoragePath?: string, hostEnv?: Record<string, string | undefined>): string[];
+export declare function buildContainerEnv(options: Pick<TestExecutionOptions, "token" | "language" | "useHostNetwork">, saveStoragePath?: string, hostEnv?: Record<string, string | undefined>, passthroughNames?: string[]): string[];

package/build/services/containerEnv.js

@@ -1,3 +1,4 @@
+import { logger } from "../utils/logger.js";
 /**
  * Rewrite localhost / 127.0.0.1 URLs to host.docker.internal so the Docker
  * executor container can reach services running on the host machine.
@@ -9,10 +10,67 @@
 export function rewriteLocalhostForDocker(url) {
     return url.replace(/^(https?:\/\/)(localhost|127\.0\.0\.1)([:/?#]|$)/, (_, scheme, _host, rest) => `${scheme}host.docker.internal${rest}`);
 }
+/** Names a workspace declaration may never forward. Matching is
+ *  case-insensitive: `process.env` is case-insensitive on Windows, so a
+ *  lower-case declaration there returns the real value and would otherwise
+ *  pass the checks below.
+ *
+ *  Two distinct concerns share one list. The first is CI identity: testbot puts
+ *  the workflow's GitHub token in the MCP process env so the agent's `gh` calls
+ *  authenticate, and a declaration naming it would push it into the container
+ *  and from there into a query string — where the SUT's own access log records
+ *  it. The second is internal signals the executor sets for itself, which a
+ *  declaration must not be able to spoof or override.
+ *
+ *  Deliberately NOT a blanket `*_TOKEN`: a token for the customer's own SUT is
+ *  exactly the kind of value an RBAC query param carries, and refusing it would
+ *  break the feature this list exists to protect. */
+// Names the executor sets for itself. API_KEY carries the Skyramp LLM key and
+// is forwarded unconditionally by the built-in block below, so a declaration
+// adds nothing. UI Smart LLM features keep working either way.
+const PASSTHROUGH_RESERVED_EXACT = new Set([
+    "API_KEY",
+    "PYTEST_ADDOPTS",
+    "PLAYWRIGHT_SAVE_STORAGE_PATH",
+]);
+const PASSTHROUGH_RESERVED_PREFIXES = ["SKYRAMP_"];
+// CI identity and secret-shaped names. Testbot puts the workflow GitHub token
+// in the MCP process env, and a declaration would send it to the container and
+// into a query string, where the SUT access log records it.
+const PASSTHROUGH_CREDENTIAL_EXACT = new Set(["GITHUB_TOKEN", "GH_TOKEN"]);
+const PASSTHROUGH_CREDENTIAL_PREFIXES = ["ACTIONS_", "AWS_"];
+const PASSTHROUGH_CREDENTIAL_SUBSTRINGS = ["_SECRET", "_PRIVATE_KEY"];
+/** Why a name is refused, or null when it is allowed. The two reasons need
+ *  different messages: a reserved name is already provided by the executor, so
+ *  the declaration is only redundant, while a credential name is refused. */
+export function passthroughDenyReason(name) {
+    const upper = name.toUpperCase();
+    if (PASSTHROUGH_CREDENTIAL_EXACT.has(upper) ||
+        PASSTHROUGH_CREDENTIAL_PREFIXES.some((p) => upper.startsWith(p)) ||
+        PASSTHROUGH_CREDENTIAL_SUBSTRINGS.some((s) => upper.includes(s))) {
+        return "credential";
+    }
+    if (PASSTHROUGH_RESERVED_EXACT.has(upper) ||
+        PASSTHROUGH_RESERVED_PREFIXES.some((p) => upper.startsWith(p))) {
+        return "reserved";
+    }
+    return null;
+}
+/** True when a name is refused regardless of who declared it. */
+export function isDeniedPassthroughName(name) {
+    return passthroughDenyReason(name) !== null;
+}
+/** A name is interpolated directly into a Docker `Env` entry, which is a plain
+ *  `NAME=value` string. A name holding `=`, whitespace or a newline produces a
+ *  malformed entry and can inject a second variable. workspace.yml supplies
+ *  these names, so `env.FOO=BAR` would yield the name `FOO=BAR`. */
+export function isValidEnvVarName(name) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
+}
 /**
  * Build the environment variable array for the Docker executor container.
  */
-export function buildContainerEnv(options, saveStoragePath, hostEnv = process.env) {
+export function buildContainerEnv(options, saveStoragePath, hostEnv = process.env, passthroughNames = []) {
     const env = [
         // Omit entirely when empty so os.getenv() returns None in the test —
         // unauthenticated endpoints won't send an empty auth header (E7).
@@ -44,6 +102,65 @@ export function buildContainerEnv(options, saveStoragePath, hostEnv = process.en
             env.push(`${key}=${shouldRewrite ? rewriteLocalhostForDocker(val) : val}`);
         }
     }
+    // Credentials that generated UI tests read from the environment instead of
+    // carrying as literals (SKYR-3862). Without this the container never sees
+    // them and every generated login fails its guard.
+    //
+    // Forwarded on presence, not truthiness: the generated guard deliberately
+    // distinguishes an unset variable (a misconfiguration, fails fast) from one
+    // set to "" (valid on forms that accept a blank password). A truthy check —
+    // as used for the URL vars above — would drop the empty case and collapse it
+    // into the failure case.
+    //
+    // TODO(SKYR-4110): only ONE credential pair is forwarded, because testbot
+    // exports only the first credential from its `uiCredentials` input. That input
+    // was designed to carry several, so the agent can pick per test case by
+    // authorization role — so a multi-role suite can get a credential its test did
+    // not expect, surfacing as a false 403. The fix is a keyed form
+    // (SKYRAMP_UI_PASSWORD_<KEY>), which needs no new forwarding logic here: the
+    // loop above already forwards SKYRAMP_TEST_SERVICE_URL_* by prefix, so the
+    // same approach applies. Keep the presence-not-truthiness rule when it lands.
+    for (const key of ["SKYRAMP_UI_USERNAME", "SKYRAMP_UI_PASSWORD"]) {
+        const val = hostEnv[key];
+        if (val !== undefined) {
+            env.push(`${key}=${val}`);
+        }
+    }
+    // Environment variables the workspace's query params declare via `env.VAR`
+    // (SKYR-4127). These references resolve where the test RUNS — inside this
+    // container — so a name that does not reach it resolves to nothing, and an
+    // unresolved query param is dropped from the request silently, yielding a
+    // passing test that exercised the wrong identity.
+    //
+    // The list comes from what workspace.yml declared, never from enumerating the
+    // ambient environment: nothing is forwarded that the workspace did not name.
+    // Forwarded on presence, not truthiness, for the same reason as the
+    // credentials above — an empty value is a legitimate declaration.
+    const seen = new Set();
+    for (const name of passthroughNames) {
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        if (!isValidEnvVarName(name)) {
+            logger.warning(`Ignoring ${JSON.stringify(name)} declared in workspace.yml: it is not a valid environment variable name.`);
+            continue;
+        }
+        const denyReason = passthroughDenyReason(name);
+        if (denyReason === "reserved") {
+            logger.warning(`Ignoring the workspace.yml declaration of ${name}: the executor sets this variable itself. ` +
+                `Its value still reaches the test.`);
+            continue;
+        }
+        if (denyReason === "credential") {
+            logger.warning(`Refusing to forward ${name} to the test executor: the name is credential-shaped. ` +
+                `Declare a variable that carries only the value the request needs.`);
+            continue;
+        }
+        const val = hostEnv[name];
+        if (val !== undefined) {
+            env.push(`${name}=${val}`);
+        }
+    }
     if (hostEnv.SKYRAMP_DEBUG) {
         env.push(`SKYRAMP_DEBUG=${hostEnv.SKYRAMP_DEBUG}`);
     }

package/build/tools/executeSkyrampTestTool.d.ts

@@ -10,4 +10,13 @@ export type ContractExecutionMode = (typeof CONTRACT_EXECUTION_MODES)[number];
  */
 export declare function resolveEffectiveToken(unauthenticated?: boolean, paramToken?: string, envToken?: string): string;
 export declare function shouldInjectSkyrampBaseUrl(testType: TestType, contractMode?: ContractExecutionMode): boolean;
+/**
+ * Append the recorded video path to execution output.
+ *
+ * Applied to the failure return as well as the success one (SKYR-4156): a video is
+ * most useful for a test that just failed, and surfacing it only on success meant a
+ * failing UI test reported no recording at all unless Playwright happened to print
+ * its own attachment line.
+ */
+export declare function withVideoInfo(output: string, videoPath?: string): string;
 export declare function registerExecuteSkyrampTestTool(server: McpServer): void;

package/build/tools/executeSkyrampTestTool.js

@@ -11,6 +11,7 @@ import { StateManager, getTestsRepoDir } from "../utils/AnalysisStateManager.js"
 import { TestSource } from "../types/TestAnalysis.js";
 import { logger } from "../utils/logger.js";
 import { toolError } from "../utils/utils.js";
+import { recordExecutionVideo } from "./execution-video-state.js";
 const TOOL_NAME = "skyramp_execute_test";
 export const CONTRACT_EXECUTION_MODES = ["provider", "consumer"];
 /**
@@ -27,6 +28,17 @@ export function resolveEffectiveToken(unauthenticated, paramToken, envToken) {
 export function shouldInjectSkyrampBaseUrl(testType, contractMode) {
     return testType !== TestType.CONTRACT || contractMode !== "consumer";
 }
+/**
+ * Append the recorded video path to execution output.
+ *
+ * Applied to the failure return as well as the success one (SKYR-4156): a video is
+ * most useful for a test that just failed, and surfacing it only on success meant a
+ * failing UI test reported no recording at all unless Playwright happened to print
+ * its own attachment line.
+ */
+export function withVideoInfo(output, videoPath) {
+    return videoPath ? `${output}\n\nVideo recording: ${videoPath}` : output;
+}
 export function registerExecuteSkyrampTestTool(server) {
     server.registerTool(TOOL_NAME, {
         description: `Execute a Skyramp-generated test in isolated containerized environments for reliable, deterministic testing. Call this once a test file exists on disk (from a skyramp_*_test_generation tool). First-time execution may take longer while Docker images download — this is expected, not a failure.`,
@@ -224,23 +236,25 @@ export function registerExecuteSkyrampTestTool(server) {
                     // Don't fail the tool call if stateFile update fails
                 }
             }
+            // Record the recording for the report before returning, so it happens on the
+            // failure path too (SKYR-4156). skyramp_submit_report reads these records to
+            // populate testResults[].videoPath — testbot uploads only the video
+            // directories the report references, so an unrecorded video is never seen.
+            await recordExecutionVideo(result, params.stateFile);
             // Progress is already reported by TestExecutionService
             // Only report final status if not already at 100%
             if (result.status !== TestExecutionStatus.Pass) {
-                errorResult = toolError(`Test execution failed: ${stripVTControlCharacters(result.output || "")}
+                errorResult = toolError(withVideoInfo(`Test execution failed: ${stripVTControlCharacters(result.output || "")}
 
-If this failed with a 401 status code, ask the user for the authentication token (or where to read it from) and retry — leave the generated test file unchanged.`);
+If this failed with a 401 status code, ask the user for the authentication token (or where to read it from) and retry — leave the generated test file unchanged.`, result.videoPath));
                 return errorResult;
             }
             // Success - progress already reported by TestExecutionService
-            const videoInfo = result.videoPath
-                ? `\n\nVideo recording: ${result.videoPath}`
-                : "";
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Test execution result: ${stripVTControlCharacters(result.output || "")}${videoInfo}`,
+                        text: withVideoInfo(`Test execution result: ${stripVTControlCharacters(result.output || "")}`, result.videoPath),
                     },
                 ],
             };

package/build/tools/execution-video-state.d.ts

@@ -0,0 +1,21 @@
+import type { TestExecutionResult } from "../types/TestExecution.js";
+/**
+ * Persistence for the server-derived video recording of a browser test execution,
+ * keyed by test-file basename (what `newTestsCreated[].fileName` carries, so
+ * `skyramp_submit_report` can match without path normalization).
+ *
+ * Why this exists (SKYR-4156): testbot uploads only the `.skyramp/videos`
+ * directories the submitted report actually references, so a recording nobody
+ * references is a recording nobody ever sees. The path is known only inside
+ * `skyramp_execute_test`, and asking the agent to carry it across tool calls left
+ * the signal prose-mediated — it decayed to zero referenced videos, and every
+ * recording of the run was discarded. Recording it here makes the reference
+ * server-derived, the same line already drawn for POM reuse and maintenance
+ * before/after status.
+ *
+ * Every write is best-effort. Video observability must never fail an execution
+ * that otherwise succeeded, so a missing/unreadable/unwritable state file degrades
+ * to "no video link in the report" — the same outcome as running outside a Testbot
+ * run, where there is no run state to record into.
+ */
+export declare function recordExecutionVideo(result: TestExecutionResult, explicitStateFile?: string): Promise<void>;

package/build/tools/execution-video-state.js

@@ -0,0 +1,51 @@
+import * as path from "path";
+import { logger } from "../utils/logger.js";
+import { resolveRunStatePath, StateManager, } from "../utils/AnalysisStateManager.js";
+/**
+ * Persistence for the server-derived video recording of a browser test execution,
+ * keyed by test-file basename (what `newTestsCreated[].fileName` carries, so
+ * `skyramp_submit_report` can match without path normalization).
+ *
+ * Why this exists (SKYR-4156): testbot uploads only the `.skyramp/videos`
+ * directories the submitted report actually references, so a recording nobody
+ * references is a recording nobody ever sees. The path is known only inside
+ * `skyramp_execute_test`, and asking the agent to carry it across tool calls left
+ * the signal prose-mediated — it decayed to zero referenced videos, and every
+ * recording of the run was discarded. Recording it here makes the reference
+ * server-derived, the same line already drawn for POM reuse and maintenance
+ * before/after status.
+ *
+ * Every write is best-effort. Video observability must never fail an execution
+ * that otherwise succeeded, so a missing/unreadable/unwritable state file degrades
+ * to "no video link in the report" — the same outcome as running outside a Testbot
+ * run, where there is no run state to record into.
+ */
+export async function recordExecutionVideo(result, explicitStateFile) {
+    if (!result.videoPath)
+        return;
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return;
+    try {
+        const manager = StateManager.fromStatePath(stateFile);
+        const data = await manager.readData();
+        if (!data)
+            return;
+        // Last write wins: a retried execution leaves a video directory per attempt,
+        // and the report must reference the attempt whose status it reports.
+        await manager.writeData({
+            ...data,
+            executionVideos: {
+                ...data.executionVideos,
+                [path.basename(result.testFile)]: {
+                    videoPath: result.videoPath,
+                    status: result.status,
+                    executedAt: result.executedAt,
+                },
+            },
+        });
+    }
+    catch (err) {
+        logger.warning("Could not record the test video — the report will omit its video link", { testFile: result.testFile, error: String(err) });
+    }
+}