@skyramp/mcp 0.1.8 → 0.2.0-rc.2

package/build/tools/test-management/analyzeTestHealthTool.js

@@ -5,9 +5,16 @@ import path from "path";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { buildDriftAnalysisPrompt } from "../../prompts/test-maintenance/drift-analysis-prompt.js";
 import { TestSource } from "../../types/TestAnalysis.js";
+import { toolError } from "../../utils/utils.js";
 const TOOL_NAME = "skyramp_analyze_test_health";
 export function registerAnalyzeTestHealthTool(server) {
     server.registerTool(TOOL_NAME, {
+        annotations: {
+            readOnlyHint: false, // deletes old state files via StateManager.cleanupOldFiles
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Generate drift and health assessment instructions for existing tests — second step of the unified Test Health Analysis Flow.
 
 **PREREQUISITE:** Call \`skyramp_analyze_changes\` first to get a stateFile.
@@ -15,19 +22,16 @@ export function registerAnalyzeTestHealthTool(server) {
 This tool reads existing tests, the branch diff, and scanned endpoints from the stateFile,
 then returns a structured prompt for the LLM to assess each test for drift and health.
 
-The LLM follows the returned prompt to assign health scores (0–100), drift details, and
-actions (UPDATE / REGENERATE / VERIFY / DELETE) for each test, then calls \`skyramp_actions\`.
-
-**This tool does not write drift or health data to the stateFile.** Assessment results
-exist only in the LLM's reasoning context and are acted on by \`skyramp_actions\`.
+The LLM follows the returned prompt to assign drift details and actions (UPDATE / REGENERATE / VERIFY / DELETE / IGNORE) for each test, then calls \`skyramp_actions\`.
 
-(Optional) Execute tests using \`skyramp_execute_test\` with \`stateFile\` parameter before \`skyramp_actions\` to validate tests live. Pass the stateFile path so execution results are written back for execution-aware health scoring and prioritization.
-
-**Output:** LLM drift analysis prompt and assessment instructions.`,
+(Optional) Execute tests using \`skyramp_execute_test\` with \`stateFile\` parameter before \`skyramp_actions\` to validate tests live.`,
         inputSchema: {
             stateFile: z
                 .string()
-                .describe("Path to state file from skyramp_analyze_changes"),
+                .describe("Path to state file from skyramp_analyze_changes. Assessment results exist only in the LLM's reasoning context — this tool does not write back to the stateFile."),
+        },
+        outputSchema: {
+            prompt: z.string().describe("LLM drift analysis prompt and assessment instructions."),
         },
     }, async (args) => {
         let errorResult;
@@ -39,19 +43,7 @@ exist only in the LLM's reasoning context and are acted on by \`skyramp_actions\
             const fullState = await stateManager.readFullState();
             const repositoryPath = fullState?.metadata.repositoryPath || "";
             if (!stateData) {
-                errorResult = {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: "State file is empty or invalid",
-                                stateFile: args.stateFile,
-                            }, null, 2),
-                        },
-                    ],
-                    isError: true,
-                };
-                return errorResult;
+                return toolError(`State file is empty or invalid: ${args.stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
             }
             // Only Skyramp tests are candidates for drift analysis and maintenance actions.
             // External (user-written) tests are used only for recommendation deduplication.
@@ -59,83 +51,40 @@ exist only in the LLM's reasoning context and are acted on by \`skyramp_actions\
             const existingTests = (stateData.existingTests || []).filter((t) => (t.source ?? TestSource.Skyramp) !== TestSource.External);
             logger.info(`Loaded ${existingTests.length} existing Skyramp tests from state file (excluded external)`);
             if (!repositoryPath || typeof repositoryPath !== "string") {
-                errorResult = {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: "repositoryPath not found in state file metadata",
-                                details: "State file must contain repositoryPath in metadata",
-                            }, null, 2),
-                        },
-                    ],
-                    isError: true,
-                };
-                return errorResult;
+                return toolError(`repositoryPath not found in state file metadata. The state file was likely created by an older version — re-run skyramp_analyze_changes to regenerate it.`);
             }
             const absoluteRepoPath = path.resolve(repositoryPath);
-            // ── Build and return drift analysis prompt ──
-            const diff = stateData.repositoryAnalysis?.diff;
-            // Build structured diff summary for the prompt
-            let parsedDiffText = "";
-            if (diff) {
-                const lines = [];
-                if (diff.currentBranch)
-                    lines.push(`**Branch**: ${diff.currentBranch} → base: ${diff.baseBranch}`);
-                if (diff.changedFiles?.length > 0)
-                    lines.push(`**Changed Files** (${diff.changedFiles.length}): ${diff.changedFiles.join(", ")}`);
-                if (diff.newEndpoints?.length > 0) {
-                    lines.push(`**New Endpoints** (${diff.newEndpoints.length}): ${diff.newEndpoints
-                        .map((e) => e.methods ? e.methods.map((m) => `${m.method} ${e.path}`).join(", ") : `${e.method} ${e.path}`)
-                        .join(", ")}`);
-                }
-                if (diff.modifiedEndpoints?.length > 0) {
-                    lines.push(`**Modified Endpoints** (${diff.modifiedEndpoints.length}): ${diff.modifiedEndpoints
-                        .map((e) => e.methods ? e.methods.map((m) => `${m.method} ${e.path}`).join(", ") : `${e.method} ${e.path}`)
-                        .join(", ")}`);
-                }
-                if (diff.removedEndpoints?.length > 0) {
-                    lines.push(`**Removed Endpoints** (${diff.removedEndpoints.length}): ${diff.removedEndpoints
-                        .map((e) => e.methods ? e.methods.map((m) => `${m.method} ${e.path}`).join(", ") : `${e.method} ${e.path}`)
-                        .join(", ")}`);
-                }
-                parsedDiffText = lines.join("\n");
-            }
             const scannedEndpoints = stateData.repositoryAnalysis?.skeletonEndpoints || [];
             const routerMountContext = stateData.repositoryAnalysis?.routerMountContext;
             const candidateRouteFiles = stateData.repositoryAnalysis?.candidateRouteFiles;
+            const diffFilePath = stateData.repositoryAnalysis?.diffFilePath;
+            // Sweep stale diff files on this natural follow-up call so they don't accumulate.
+            // Pass [] for stateTypes so only skyramp-diff-*.diff files are deleted — state files
+            // (skyramp-analysis-*, skyramp-recommendation-*) must not be removed here because the
+            // caller still needs args.stateFile to pass to skyramp_actions.
+            try {
+                await StateManager.cleanupOldFiles(24, undefined, []);
+            }
+            catch (error) {
+                logger.warning(`Failed to cleanup old diff files: ${error.message}`);
+            }
             const promptText = buildDriftAnalysisPrompt({
                 existingTests,
-                parsedDiff: parsedDiffText || undefined,
                 scannedEndpoints,
                 repositoryPath: absoluteRepoPath,
                 stateFile: stateManager.getStatePath(),
                 routerMountContext,
                 candidateRouteFiles,
+                diffFilePath,
             });
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: promptText,
-                    },
-                ],
+                structuredContent: { prompt: promptText },
+                content: [{ type: "text", text: "Drift analysis prompt generated. Follow the prompt field to assess each test." }],
             };
         }
         catch (error) {
             logger.error(`Test health analysis failed: ${error.message}`, error);
-            errorResult = {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            error: error.message,
-                            details: error.stack,
-                        }, null, 2),
-                    },
-                ],
-                isError: true,
-            };
+            errorResult = toolError(`Test health analysis failed: ${error.message}`);
             return errorResult;
         }
         finally {

package/build/tools/test-management/index.js

@@ -1,3 +1,4 @@
 export { registerAnalyzeChangesTool } from "./analyzeChangesTool.js";
+export { registerUiAnalyzeChangesTool } from "./uiAnalyzeChangesTool.js";
 export { registerAnalyzeTestHealthTool } from "./analyzeTestHealthTool.js";
 export { registerActionsTool } from "./actionsTool.js";

package/build/tools/test-management/uiAnalyzeChangesTool.js

@@ -0,0 +1,149 @@
+import * as fs from "fs";
+import * as path from "path";
+import { z } from "zod";
+import { logger } from "../../utils/logger.js";
+import { enumerateCandidateUiPages } from "../../utils/uiPageEnumerator.js";
+import { isFrontendFile, isTestFile } from "../../prompts/test-recommendation/scopeAssessment.js";
+import { parseChangedFilesFromDiff } from "../../utils/branchDiff.js";
+import { toolText } from "../../utils/utils.js";
+import { isTestbotEnabled } from "../../utils/featureFlags.js";
+/**
+ * skyramp_ui_analyze_changes — runs before skyramp_analyze_changes when the
+ * caller (typically the testbot agent) wants blueprint-grounded recommendations.
+ *
+ * Computes candidateUiPages[] using the same source-grounded logic that
+ * analyze_changes uses internally (shared enumerator), then emits explicit
+ * instructions for the agent: navigate to each candidate URL, capture a
+ * browser_blueprint, then call skyramp_analyze_changes with the captures
+ * available as element vocabulary when the agent writes UI rec reasoning.
+ *
+ * Graceful degradation: backend-only PRs produce a "no UI work" instruction;
+ * unresolvable frontend baseUrl produces "skip captures, call analyze_changes
+ * with empty array." analyze_changes still works in either case — same
+ * source-grounded output as before slice 4.
+ */
+export async function runUiAnalyzeChanges(params) {
+    const repoPath = params.repositoryPath;
+    // Read changedFiles from the canonical PR diff file. The testbot runtime
+    // writes this before the prompt runs.
+    const diffPath = path.join(repoPath, ".skyramp_git_diff");
+    let changedFiles = [];
+    let diffFileMissing = false;
+    try {
+        const raw = fs.readFileSync(diffPath, "utf-8");
+        changedFiles = parseChangedFilesFromDiff(raw);
+    }
+    catch {
+        // No diff file — for testbot this would be a runtime bug (it always
+        // writes one); for non-testbot callers it means "diff unavailable",
+        // which is NOT the same as "no UI changes". Surface that distinction.
+        diffFileMissing = true;
+    }
+    if (diffFileMissing) {
+        const uiContext = {
+            changedFrontendFiles: [],
+            candidateUiPages: [],
+        };
+        return {
+            uiContext,
+            instructions: DIFF_FILE_MISSING_INSTRUCTIONS,
+        };
+    }
+    const frontendFiles = changedFiles.filter((f) => isFrontendFile(f) && !isTestFile(f));
+    if (frontendFiles.length === 0) {
+        const uiContext = {
+            changedFrontendFiles: [],
+            candidateUiPages: [],
+        };
+        return {
+            uiContext,
+            instructions: NO_UI_INSTRUCTIONS,
+        };
+    }
+    const candidateUiPages = await enumerateCandidateUiPages(repoPath, frontendFiles);
+    const uiContext = {
+        changedFrontendFiles: frontendFiles,
+        candidateUiPages,
+    };
+    const instructions = candidateUiPages.length === 0
+        ? NO_RESOLVABLE_URLS_INSTRUCTIONS
+        : buildCaptureInstructions(candidateUiPages, params.uiCredentials);
+    logger.info("ui_analyze_changes computed candidate UI pages", {
+        repositoryPath: repoPath,
+        frontendFileCount: frontendFiles.length,
+        candidateUiPageCount: candidateUiPages.length,
+        hasUiCredentials: !!params.uiCredentials,
+    });
+    return { uiContext, instructions };
+}
+const NO_UI_INSTRUCTIONS = `No UI changes detected in this PR. Proceed directly to \`skyramp_analyze_changes\`.`;
+const NO_RESOLVABLE_URLS_INSTRUCTIONS = `Frontend changes detected but no candidate URLs could be resolved (workspace baseUrl missing or no router files matched). Proceed to \`skyramp_analyze_changes\`; UI recommendations will be source-grounded only.`;
+const DIFF_FILE_MISSING_INSTRUCTIONS = `\`.skyramp_git_diff\` not found in the repository. This file is normally written by the testbot runtime before the prompt runs; without it, this tool cannot determine which files changed. **Do not skip blueprint capture on the assumption there are no UI changes** — that conclusion is not supported by the available data. If you have access to the changed-files list elsewhere (e.g. a \`gh pr diff\` command, an environment variable), determine UI candidates yourself and capture their blueprints before proceeding. Otherwise proceed to \`skyramp_analyze_changes\` and add an \`issuesFound\` info entry: "ui_analyze_changes could not read .skyramp_git_diff; recommendations are source-grounded only".`;
+function buildCaptureInstructions(pages, uiCredentials) {
+    // The `<ui-credentials>` tag is only emitted by the testbot orchestration
+    // prompt. When this tool is called from an IDE (Cursor, etc.) outside
+    // testbot, the agent has no such tag — embed the credentials inline
+    // instead. uiCredentials is "email:password" formatted by the caller.
+    const loginStep = uiCredentials
+        ? (isTestbotEnabled()
+            ? `\n0. **Log in first.** \`browser_navigate\` to the app's login URL, then use \`<ui-credentials>\` from the testbot prompt to authenticate (you have those credentials in context). Without authentication, the candidate URLs below may redirect to login and the captured blueprints will be of the login page, not the feature.\n`
+            : `\n0. **Log in first.** \`browser_navigate\` to the app's login URL, then authenticate with the credentials \`${uiCredentials}\` (formatted as \`email:password\`). Without authentication, the candidate URLs below may redirect to login and the captured blueprints will be of the login page, not the feature.\n`)
+        : "";
+    const pagesYaml = pages
+        .map((p, i) => `  ${i + 1}. ${p.url}  (sourcedFrom: ${p.sourcedFrom.join(", ") || "(none)"}, strategy: ${p.strategy})`)
+        .join("\n");
+    return `Frontend changes detected. **Before calling \`skyramp_analyze_changes\`, capture blueprints on the candidate UI pages below.** Those captures stay in your tool-result history and serve as element vocabulary when you write UI test recommendations — \`skyramp_analyze_changes\` returns the authoring rules; you bring the observed elements.
+${loginStep}
+**Candidate URLs:**
+${pagesYaml}
+
+**For each candidate URL:**
+  - \`browser_navigate\` to the URL
+  - \`browser_blueprint\` to capture the page
+
+You don't need to thread the blueprints back into a tool call — they're in your context once captured. **Then call \`skyramp_analyze_changes\`** to get the recommendation catalog and the UI authoring rules.
+
+If a candidate URL 404s or redirects unexpectedly, navigate from the workspace baseUrl and explore (admin apps mount routes under base prefixes the source extraction can't see). If the page rendered but lacks the changed feature (gated UI: modal, dropdown, accordion), do NOT iterate further during this step — UI recs will fall back to source-grounded prose for those, and the agent's later trace recording (Task 2) will navigate into the gate via capture-act-capture.
+
+If \`browser_blueprint\` fails on every candidate URL (app unreachable, all 404s), proceed to \`skyramp_analyze_changes\` and log an \`issuesFound\` info entry. Recommendations will be source-grounded; non-UI work is unaffected.`;
+}
+export const uiAnalyzeChangesInputSchema = {
+    repositoryPath: z
+        .string()
+        .describe("Absolute path to the repository root"),
+    uiCredentials: z
+        .string()
+        .optional()
+        .describe("Optional ui-credentials for authed apps. When present, the returned " +
+        "instructions include a login step before blueprint capture."),
+};
+export function registerUiAnalyzeChangesTool(server) {
+    server.registerTool("skyramp_ui_analyze_changes", {
+        description: [
+            "Run BEFORE skyramp_analyze_changes when the PR may contain frontend changes.",
+            "Enumerates candidate UI pages from the diff and instructs the agent to",
+            "capture browser_blueprints on each before calling analyze_changes. The",
+            "captures stay in the agent's tool-result history and serve as the",
+            "element vocabulary for UI rec reasoning.",
+            "",
+            "On backend-only PRs, returns a 'no UI work' instruction — caller can",
+            "proceed directly to skyramp_analyze_changes.",
+        ].join("\n"),
+        inputSchema: uiAnalyzeChangesInputSchema,
+        annotations: {
+            readOnlyHint: true, // reads .skyramp_git_diff + workspace.yml; no writes
+            idempotentHint: true, // pure function of repo state + uiCredentials
+            openWorldHint: false, // no external service calls
+        },
+    }, async (params) => {
+        const result = await runUiAnalyzeChanges(params);
+        const summary = JSON.stringify({ uiContext: result.uiContext }, null, 2);
+        return toolText(`<summary>
+${summary}
+</summary>
+
+<instructions>
+${result.instructions}
+</instructions>`);
+    });
+}

package/build/tools/test-management/uiAnalyzeChangesTool.test.js

@@ -0,0 +1,100 @@
+jest.mock("@skyramp/skyramp", () => ({
+    WorkspaceConfigManager: { create: jest.fn() },
+}));
+import { runUiAnalyzeChanges } from "./uiAnalyzeChangesTool.js";
+import * as workspaceAuth from "../../utils/workspaceAuth.js";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+function makeRepoWithDiff(changedFiles) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-uiac-test-"));
+    // Write .skyramp_git_diff with the requested file changes — match the
+    // format the runtime uses (raw `diff --git a/X b/X` block).
+    const diff = changedFiles
+        .map((f) => `diff --git a/${f} b/${f}\n+++ b/${f}\n@@ -0,0 +1,1 @@\n+x`)
+        .join("\n");
+    fs.writeFileSync(path.join(dir, ".skyramp_git_diff"), diff);
+    return dir;
+}
+describe("runUiAnalyzeChanges", () => {
+    let readSpy;
+    beforeEach(() => {
+        readSpy = jest.spyOn(workspaceAuth, "readWorkspaceConfigRaw");
+    });
+    afterEach(() => {
+        readSpy.mockRestore();
+    });
+    it("returns empty changedFrontendFiles for backend-only diffs", async () => {
+        readSpy.mockResolvedValue({ services: [] });
+        const repo = makeRepoWithDiff(["api/handlers/users.ts"]);
+        const result = await runUiAnalyzeChanges({ repositoryPath: repo });
+        expect(result.uiContext.changedFrontendFiles).toEqual([]);
+        expect(result.uiContext.candidateUiPages).toEqual([]);
+        expect(result.instructions).toMatch(/no UI changes/i);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("returns candidateUiPages and capture instructions for frontend diffs", async () => {
+        readSpy.mockResolvedValue({
+            services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
+        });
+        const repo = makeRepoWithDiff(["frontend/src/components/Cart.tsx"]);
+        const result = await runUiAnalyzeChanges({ repositoryPath: repo });
+        expect(result.uiContext.changedFrontendFiles.length).toBeGreaterThan(0);
+        expect(result.uiContext.candidateUiPages.length).toBeGreaterThan(0);
+        expect(result.instructions).toMatch(/browser_navigate/);
+        expect(result.instructions).toMatch(/browser_blueprint/);
+        expect(result.instructions).toMatch(/skyramp_analyze_changes/);
+        // Captures stay in agent's tool-result history; we no longer thread them
+        // back through analyze_changes as a param.
+        expect(result.instructions).not.toMatch(/capturedBlueprints/);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("includes inline-credentials login step in non-testbot mode", async () => {
+        // SKYRAMP_FEATURE_TESTBOT is not set here, so the tool emits the
+        // credentials inline rather than referencing the testbot's
+        // <ui-credentials> context tag (which doesn't exist outside testbot).
+        delete process.env.SKYRAMP_FEATURE_TESTBOT;
+        readSpy.mockResolvedValue({
+            services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
+        });
+        const repo = makeRepoWithDiff(["frontend/src/components/Cart.tsx"]);
+        const result = await runUiAnalyzeChanges({
+            repositoryPath: repo,
+            uiCredentials: "admin@example.com:admin",
+        });
+        expect(result.instructions).toMatch(/log in/i);
+        expect(result.instructions).toContain("admin@example.com:admin");
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("references the <ui-credentials> testbot context tag in testbot mode", async () => {
+        process.env.SKYRAMP_FEATURE_TESTBOT = "1";
+        try {
+            readSpy.mockResolvedValue({
+                services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
+            });
+            const repo = makeRepoWithDiff(["frontend/src/components/Cart.tsx"]);
+            const result = await runUiAnalyzeChanges({
+                repositoryPath: repo,
+                uiCredentials: "admin@example.com:admin",
+            });
+            expect(result.instructions).toMatch(/log in/i);
+            expect(result.instructions).toContain("ui-credentials");
+            // Inline credentials should NOT leak in testbot mode (the
+            // <ui-credentials> tag is the secure carrier in that flow).
+            expect(result.instructions).not.toContain("admin@example.com:admin");
+            fs.rmSync(repo, { recursive: true, force: true });
+        }
+        finally {
+            delete process.env.SKYRAMP_FEATURE_TESTBOT;
+        }
+    });
+    it("instructs the agent to proceed to analyze_changes (source-grounded) when frontend baseUrl unresolvable", async () => {
+        readSpy.mockResolvedValue(null); // no workspace yml
+        const repo = makeRepoWithDiff(["frontend/src/components/Cart.tsx"]);
+        const result = await runUiAnalyzeChanges({ repositoryPath: repo });
+        expect(result.uiContext.changedFrontendFiles.length).toBeGreaterThan(0);
+        expect(result.uiContext.candidateUiPages).toEqual([]);
+        expect(result.instructions).toMatch(/source-grounded/i);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+});

package/build/tools/trace/resolveSaveStoragePath.js

@@ -0,0 +1,16 @@
+import path from "path";
+/**
+ * Resolve the user-supplied `playwrightSaveStoragePath` against `outputDir`:
+ *   - A bare filename (no separators, not absolute) is joined with `outputDir`.
+ *   - Anything else (absolute path, or a relative path containing separators)
+ *     is returned unchanged.
+ */
+export function resolveSaveStoragePath(input, outputDir) {
+    if (!outputDir) {
+        return input;
+    }
+    if (!path.isAbsolute(input) && !input.includes(path.sep)) {
+        return path.join(outputDir, input);
+    }
+    return input;
+}

package/build/tools/trace/resolveSaveStoragePath.test.js

@@ -0,0 +1,17 @@
+import path from "path";
+import { resolveSaveStoragePath } from "./resolveSaveStoragePath.js";
+describe("resolveSaveStoragePath", () => {
+    const outputDir = "/abs/output";
+    it("joins a bare filename with outputDir", () => {
+        expect(resolveSaveStoragePath("auth.json", outputDir)).toBe(path.join(outputDir, "auth.json"));
+    });
+    it("returns an absolute path unchanged", () => {
+        expect(resolveSaveStoragePath("/tmp/storage.json", outputDir)).toBe("/tmp/storage.json");
+    });
+    it("returns a relative path with separators unchanged", () => {
+        expect(resolveSaveStoragePath("subdir/storage.json", outputDir)).toBe("subdir/storage.json");
+    });
+    it("returns input unchanged when outputDir is undefined", () => {
+        expect(resolveSaveStoragePath("auth.json", undefined)).toBe("auth.json");
+    });
+});

package/build/tools/trace/resolveSessionPaths.js

@@ -0,0 +1,39 @@
+import path from "path";
+import { SESSION_STORAGE_FILENAME } from "../../types/TestTypes.js";
+import { resolveSaveStoragePath } from "./resolveSaveStoragePath.js";
+export function resolveSessionPaths(args) {
+    const defaultPath = path.join(args.outputDir, SESSION_STORAGE_FILENAME);
+    const explicitLoad = args.loadOverride
+        ? resolveSaveStoragePath(args.loadOverride, args.outputDir)
+        : undefined;
+    const explicitSave = args.saveOverride
+        ? resolveSaveStoragePath(args.saveOverride, args.outputDir)
+        : undefined;
+    switch (args.mode) {
+        case "capture":
+            // Login capture: clean slate (never load), save at default unless overridden.
+            return { savePath: explicitSave ?? defaultPath };
+        case "reuse":
+            // Reuse existing session: load by default, do NOT save (preserves the file).
+            // Caller may force a save by setting `playwrightSaveStoragePath` explicitly.
+            return {
+                loadPath: explicitLoad ?? defaultPath,
+                savePath: explicitSave,
+            };
+        case "ignore":
+            // Honor only explicit overrides; otherwise neither load nor save.
+            return { loadPath: explicitLoad, savePath: explicitSave };
+        case "auto":
+        default:
+            // Explicit overrides win.
+            if (explicitLoad || explicitSave) {
+                return { loadPath: explicitLoad, savePath: explicitSave };
+            }
+            // No overrides — decide from filesystem state. If a session file is
+            // already present, reuse it without overwriting; otherwise capture
+            // into the default location.
+            return args.sessionExists
+                ? { loadPath: defaultPath }
+                : { savePath: defaultPath };
+    }
+}

package/build/tools/trace/resolveSessionPaths.test.js

@@ -0,0 +1,103 @@
+import path from "path";
+import { SESSION_STORAGE_FILENAME } from "../../types/TestTypes.js";
+import { resolveSessionPaths } from "./resolveSessionPaths.js";
+describe("resolveSessionPaths", () => {
+    const outputDir = "/abs/output";
+    const defaultPath = path.join(outputDir, SESSION_STORAGE_FILENAME);
+    const baseArgs = {
+        loadOverride: undefined,
+        saveOverride: undefined,
+        outputDir,
+        sessionExists: false,
+    };
+    describe("mode=auto", () => {
+        it("captures into the default path when no session exists", () => {
+            expect(resolveSessionPaths({ ...baseArgs, mode: "auto" })).toEqual({
+                savePath: defaultPath,
+            });
+        });
+        it("reuses (loads) the default path when a session exists, without saving", () => {
+            expect(resolveSessionPaths({ ...baseArgs, mode: "auto", sessionExists: true })).toEqual({ loadPath: defaultPath });
+        });
+        it("respects an explicit load override when given (auto + sessionExists)", () => {
+            expect(resolveSessionPaths({
+                ...baseArgs,
+                mode: "auto",
+                sessionExists: true,
+                loadOverride: "/elsewhere/session.json",
+            })).toEqual({ loadPath: "/elsewhere/session.json" });
+        });
+        it("respects an explicit save override (auto + no session)", () => {
+            expect(resolveSessionPaths({
+                ...baseArgs,
+                mode: "auto",
+                saveOverride: "auth.json",
+            })).toEqual({ savePath: path.join(outputDir, "auth.json") });
+        });
+    });
+    describe("mode=capture", () => {
+        it("always saves at the default path, never loads", () => {
+            expect(resolveSessionPaths({ ...baseArgs, mode: "capture" })).toEqual({
+                savePath: defaultPath,
+            });
+        });
+        it("ignores a load override (capture is a clean slate)", () => {
+            expect(resolveSessionPaths({
+                ...baseArgs,
+                mode: "capture",
+                loadOverride: "/elsewhere/session.json",
+            })).toEqual({ savePath: defaultPath });
+        });
+        it("honors an explicit save override", () => {
+            expect(resolveSessionPaths({
+                ...baseArgs,
+                mode: "capture",
+                saveOverride: "/tmp/custom.json",
+            })).toEqual({ savePath: "/tmp/custom.json" });
+        });
+        it("still captures even when a session file already exists (we're recapturing)", () => {
+            expect(resolveSessionPaths({
+                ...baseArgs,
+                mode: "capture",
+                sessionExists: true,
+            })).toEqual({ savePath: defaultPath });
+        });
+    });
+    describe("mode=reuse", () => {
+        it("loads the default path, does not save (preserves the session file)", () => {
+            expect(resolveSessionPaths({ ...baseArgs, mode: "reuse" })).toEqual({
+                loadPath: defaultPath,
+            });
+        });
+        it("honors an explicit load override", () => {
+            expect(resolveSessionPaths({
+                ...baseArgs,
+                mode: "reuse",
+                loadOverride: "/elsewhere/session.json",
+            })).toEqual({ loadPath: "/elsewhere/session.json" });
+        });
+        it("allows an explicit save override even in reuse (caller wants to refresh)", () => {
+            expect(resolveSessionPaths({
+                ...baseArgs,
+                mode: "reuse",
+                saveOverride: "/tmp/refreshed.json",
+            })).toEqual({ loadPath: defaultPath, savePath: "/tmp/refreshed.json" });
+        });
+    });
+    describe("mode=ignore", () => {
+        it("loads and saves nothing by default", () => {
+            expect(resolveSessionPaths({ ...baseArgs, mode: "ignore" })).toEqual({});
+        });
+        it("honors explicit overrides only", () => {
+            expect(resolveSessionPaths({
+                ...baseArgs,
+                mode: "ignore",
+                loadOverride: "/in/session.json",
+                saveOverride: "/out/session.json",
+            })).toEqual({
+                loadPath: "/in/session.json",
+                savePath: "/out/session.json",
+            });
+        });
+    });
+});

package/build/tools/trace/sessionState.js

@@ -0,0 +1,14 @@
+// Module-level state acting as a singleton: the start-trace tool stashes the
+// resolved save path here so the stop-trace tool can surface it without
+// re-resolving. ES modules are cached and singleton per Node process, so this
+// is the idiomatic TS pattern for cross-call state — equivalent to a class
+// with private static fields, without the extra wrapper.
+let savedPath;
+export function setSavedSessionPath(p) {
+    savedPath = p;
+}
+export function consumeSavedSessionPath() {
+    const v = savedPath;
+    savedPath = undefined;
+    return v;
+}

package/build/tools/trace/sessionState.test.js

@@ -0,0 +1,17 @@
+import { consumeSavedSessionPath, setSavedSessionPath, } from "./sessionState.js";
+describe("sessionState", () => {
+    afterEach(() => {
+        // Ensure module-level state is cleared between tests.
+        setSavedSessionPath(undefined);
+    });
+    it("returns the set value on first consume and undefined on the second", () => {
+        setSavedSessionPath("/abs/session.json");
+        expect(consumeSavedSessionPath()).toBe("/abs/session.json");
+        expect(consumeSavedSessionPath()).toBeUndefined();
+    });
+    it("setting undefined clears any prior value", () => {
+        setSavedSessionPath("/abs/session.json");
+        setSavedSessionPath(undefined);
+        expect(consumeSavedSessionPath()).toBeUndefined();
+    });
+});