@skyramp/mcp 0.2.6 → 0.2.8-rc.1

package/build/utils/workspaceAuth.test.js

@@ -1,29 +1,29 @@
-import { getWorkspaceBaseUrl } from "./workspaceAuth.js";
+// @ts-nocheck - Jest ESM mock type inference issues
+import { jest } from "@jest/globals";
 const REPO = "/some/repo";
-jest.mock("../workspace/workspace.js", () => {
-    const twoServiceConfig = {
-        services: [
-            {
-                serviceName: "backend",
-                language: "python",
-                testDirectory: "backend/tests",
-                api: { baseUrl: "http://localhost:8000" },
-            },
-            {
-                serviceName: "frontend",
-                language: "typescript",
-                testDirectory: "frontend/tests",
-                api: { baseUrl: "http://localhost:5173" },
-            },
-        ],
-    };
-    return {
-        WorkspaceConfigManager: jest.fn().mockImplementation(() => ({
-            exists: jest.fn().mockResolvedValue(true),
-            read: jest.fn().mockResolvedValue(twoServiceConfig),
-        })),
-    };
-});
+const twoServiceConfig = {
+    services: [
+        {
+            serviceName: "backend",
+            language: "python",
+            testDirectory: "backend/tests",
+            api: { baseUrl: "http://localhost:8000" },
+        },
+        {
+            serviceName: "frontend",
+            language: "typescript",
+            testDirectory: "frontend/tests",
+            api: { baseUrl: "http://localhost:5173" },
+        },
+    ],
+};
+jest.unstable_mockModule("../workspace/workspace.js", () => ({
+    WorkspaceConfigManager: jest.fn().mockImplementation(() => ({
+        exists: jest.fn().mockResolvedValue(true),
+        read: jest.fn().mockResolvedValue(twoServiceConfig),
+    })),
+}));
+const { getWorkspaceBaseUrl } = await import("./workspaceAuth.js");
 describe("getWorkspaceBaseUrl", () => {
     it("should return no match when testFile is not provided", async () => {
         const result = await getWorkspaceBaseUrl(REPO);

package/build/workspace/index.d.ts

@@ -0,0 +1 @@
+export * from "./workspace.js";

package/build/workspace/workspace.d.ts

@@ -0,0 +1,390 @@
+import { z } from "zod";
+export declare const WORKSPACE_DIR = ".skyramp";
+export declare const WORKSPACE_FILENAME = "workspace.yml";
+export declare const serviceSchema: z.ZodObject<{
+    serviceName: z.ZodString;
+    repository: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodEnum<["python", "typescript", "javascript", "java"]>>;
+    framework: z.ZodOptional<z.ZodEnum<["playwright", "pytest", "robot", "junit"]>>;
+    testDirectory: z.ZodOptional<z.ZodString>;
+    api: z.ZodOptional<z.ZodObject<{
+        schemaPath: z.ZodOptional<z.ZodString>;
+        authType: z.ZodOptional<z.ZodEnum<["bearer", "basic", "oauth", "apiKey", "cookie", "session", "token", "none"]>>;
+        authHeader: z.ZodOptional<z.ZodString>;
+        authScheme: z.ZodOptional<z.ZodString>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        authHeader?: string | undefined;
+        authScheme?: string | undefined;
+        schemaPath?: string | undefined;
+        authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+        baseUrl?: string | undefined;
+    }, {
+        authHeader?: string | undefined;
+        authScheme?: string | undefined;
+        schemaPath?: string | undefined;
+        authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+        baseUrl?: string | undefined;
+    }>>;
+    runtimeDetails: z.ZodOptional<z.ZodObject<{
+        serverStartCommand: z.ZodOptional<z.ZodString>;
+        runtime: z.ZodEnum<["local", "docker", "k8s"]>;
+        dockerNetwork: z.ZodOptional<z.ZodString>;
+        k8sNamespace: z.ZodOptional<z.ZodString>;
+        k8sContext: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        runtime: "local" | "docker" | "k8s";
+        dockerNetwork?: string | undefined;
+        k8sNamespace?: string | undefined;
+        k8sContext?: string | undefined;
+        serverStartCommand?: string | undefined;
+    }, {
+        runtime: "local" | "docker" | "k8s";
+        dockerNetwork?: string | undefined;
+        k8sNamespace?: string | undefined;
+        k8sContext?: string | undefined;
+        serverStartCommand?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    serviceName: string;
+    language?: "python" | "typescript" | "javascript" | "java" | undefined;
+    framework?: "playwright" | "pytest" | "robot" | "junit" | undefined;
+    repository?: string | undefined;
+    testDirectory?: string | undefined;
+    api?: {
+        authHeader?: string | undefined;
+        authScheme?: string | undefined;
+        schemaPath?: string | undefined;
+        authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+        baseUrl?: string | undefined;
+    } | undefined;
+    runtimeDetails?: {
+        runtime: "local" | "docker" | "k8s";
+        dockerNetwork?: string | undefined;
+        k8sNamespace?: string | undefined;
+        k8sContext?: string | undefined;
+        serverStartCommand?: string | undefined;
+    } | undefined;
+}, {
+    serviceName: string;
+    language?: "python" | "typescript" | "javascript" | "java" | undefined;
+    framework?: "playwright" | "pytest" | "robot" | "junit" | undefined;
+    repository?: string | undefined;
+    testDirectory?: string | undefined;
+    api?: {
+        authHeader?: string | undefined;
+        authScheme?: string | undefined;
+        schemaPath?: string | undefined;
+        authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+        baseUrl?: string | undefined;
+    } | undefined;
+    runtimeDetails?: {
+        runtime: "local" | "docker" | "k8s";
+        dockerNetwork?: string | undefined;
+        k8sNamespace?: string | undefined;
+        k8sContext?: string | undefined;
+        serverStartCommand?: string | undefined;
+    } | undefined;
+}>;
+export declare const workspaceConfigSchema: z.ZodObject<{
+    workspace: z.ZodOptional<z.ZodObject<{
+        repoName: z.ZodOptional<z.ZodString>;
+        repoUrl: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        repoName?: string | undefined;
+        repoUrl?: string | undefined;
+    }, {
+        repoName?: string | undefined;
+        repoUrl?: string | undefined;
+    }>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        schemaVersion: z.ZodString;
+        mcpVersion: z.ZodString;
+        executorVersion: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        createdAt: string;
+        schemaVersion: string;
+        mcpVersion: string;
+        executorVersion: string;
+        updatedAt: string;
+    }, {
+        createdAt: string;
+        schemaVersion: string;
+        mcpVersion: string;
+        executorVersion: string;
+        updatedAt: string;
+    }>>;
+    services: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        serviceName: z.ZodString;
+        repository: z.ZodOptional<z.ZodString>;
+        language: z.ZodOptional<z.ZodEnum<["python", "typescript", "javascript", "java"]>>;
+        framework: z.ZodOptional<z.ZodEnum<["playwright", "pytest", "robot", "junit"]>>;
+        testDirectory: z.ZodOptional<z.ZodString>;
+        api: z.ZodOptional<z.ZodObject<{
+            schemaPath: z.ZodOptional<z.ZodString>;
+            authType: z.ZodOptional<z.ZodEnum<["bearer", "basic", "oauth", "apiKey", "cookie", "session", "token", "none"]>>;
+            authHeader: z.ZodOptional<z.ZodString>;
+            authScheme: z.ZodOptional<z.ZodString>;
+            baseUrl: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            authHeader?: string | undefined;
+            authScheme?: string | undefined;
+            schemaPath?: string | undefined;
+            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+            baseUrl?: string | undefined;
+        }, {
+            authHeader?: string | undefined;
+            authScheme?: string | undefined;
+            schemaPath?: string | undefined;
+            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+            baseUrl?: string | undefined;
+        }>>;
+        runtimeDetails: z.ZodOptional<z.ZodObject<{
+            serverStartCommand: z.ZodOptional<z.ZodString>;
+            runtime: z.ZodEnum<["local", "docker", "k8s"]>;
+            dockerNetwork: z.ZodOptional<z.ZodString>;
+            k8sNamespace: z.ZodOptional<z.ZodString>;
+            k8sContext: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            runtime: "local" | "docker" | "k8s";
+            dockerNetwork?: string | undefined;
+            k8sNamespace?: string | undefined;
+            k8sContext?: string | undefined;
+            serverStartCommand?: string | undefined;
+        }, {
+            runtime: "local" | "docker" | "k8s";
+            dockerNetwork?: string | undefined;
+            k8sNamespace?: string | undefined;
+            k8sContext?: string | undefined;
+            serverStartCommand?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        serviceName: string;
+        language?: "python" | "typescript" | "javascript" | "java" | undefined;
+        framework?: "playwright" | "pytest" | "robot" | "junit" | undefined;
+        repository?: string | undefined;
+        testDirectory?: string | undefined;
+        api?: {
+            authHeader?: string | undefined;
+            authScheme?: string | undefined;
+            schemaPath?: string | undefined;
+            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+            baseUrl?: string | undefined;
+        } | undefined;
+        runtimeDetails?: {
+            runtime: "local" | "docker" | "k8s";
+            dockerNetwork?: string | undefined;
+            k8sNamespace?: string | undefined;
+            k8sContext?: string | undefined;
+            serverStartCommand?: string | undefined;
+        } | undefined;
+    }, {
+        serviceName: string;
+        language?: "python" | "typescript" | "javascript" | "java" | undefined;
+        framework?: "playwright" | "pytest" | "robot" | "junit" | undefined;
+        repository?: string | undefined;
+        testDirectory?: string | undefined;
+        api?: {
+            authHeader?: string | undefined;
+            authScheme?: string | undefined;
+            schemaPath?: string | undefined;
+            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+            baseUrl?: string | undefined;
+        } | undefined;
+        runtimeDetails?: {
+            runtime: "local" | "docker" | "k8s";
+            dockerNetwork?: string | undefined;
+            k8sNamespace?: string | undefined;
+            k8sContext?: string | undefined;
+            serverStartCommand?: string | undefined;
+        } | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    metadata?: {
+        createdAt: string;
+        schemaVersion: string;
+        mcpVersion: string;
+        executorVersion: string;
+        updatedAt: string;
+    } | undefined;
+    workspace?: {
+        repoName?: string | undefined;
+        repoUrl?: string | undefined;
+    } | undefined;
+    services?: {
+        serviceName: string;
+        language?: "python" | "typescript" | "javascript" | "java" | undefined;
+        framework?: "playwright" | "pytest" | "robot" | "junit" | undefined;
+        repository?: string | undefined;
+        testDirectory?: string | undefined;
+        api?: {
+            authHeader?: string | undefined;
+            authScheme?: string | undefined;
+            schemaPath?: string | undefined;
+            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+            baseUrl?: string | undefined;
+        } | undefined;
+        runtimeDetails?: {
+            runtime: "local" | "docker" | "k8s";
+            dockerNetwork?: string | undefined;
+            k8sNamespace?: string | undefined;
+            k8sContext?: string | undefined;
+            serverStartCommand?: string | undefined;
+        } | undefined;
+    }[] | undefined;
+}, {
+    metadata?: {
+        createdAt: string;
+        schemaVersion: string;
+        mcpVersion: string;
+        executorVersion: string;
+        updatedAt: string;
+    } | undefined;
+    workspace?: {
+        repoName?: string | undefined;
+        repoUrl?: string | undefined;
+    } | undefined;
+    services?: {
+        serviceName: string;
+        language?: "python" | "typescript" | "javascript" | "java" | undefined;
+        framework?: "playwright" | "pytest" | "robot" | "junit" | undefined;
+        repository?: string | undefined;
+        testDirectory?: string | undefined;
+        api?: {
+            authHeader?: string | undefined;
+            authScheme?: string | undefined;
+            schemaPath?: string | undefined;
+            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+            baseUrl?: string | undefined;
+        } | undefined;
+        runtimeDetails?: {
+            runtime: "local" | "docker" | "k8s";
+            dockerNetwork?: string | undefined;
+            k8sNamespace?: string | undefined;
+            k8sContext?: string | undefined;
+            serverStartCommand?: string | undefined;
+        } | undefined;
+    }[] | undefined;
+}>;
+export type Service = z.infer<typeof serviceSchema>;
+export type ServiceApi = NonNullable<Service["api"]>;
+export type ServiceRuntimeDetails = NonNullable<Service["runtimeDetails"]>;
+export type WorkspaceConfig = z.infer<typeof workspaceConfigSchema>;
+export type WorkspaceSection = NonNullable<WorkspaceConfig["workspace"]>;
+export type MetadataSection = NonNullable<WorkspaceConfig["metadata"]>;
+/** Validates a workspace configuration object against the Zod schema. */
+export declare function validateWorkspaceConfig(config: unknown): z.SafeParseReturnType<{
+    metadata?: {
+        createdAt: string;
+        schemaVersion: string;
+        mcpVersion: string;
+        executorVersion: string;
+        updatedAt: string;
+    } | undefined;
+    workspace?: {
+        repoName?: string | undefined;
+        repoUrl?: string | undefined;
+    } | undefined;
+    services?: {
+        serviceName: string;
+        language?: "python" | "typescript" | "javascript" | "java" | undefined;
+        framework?: "playwright" | "pytest" | "robot" | "junit" | undefined;
+        repository?: string | undefined;
+        testDirectory?: string | undefined;
+        api?: {
+            authHeader?: string | undefined;
+            authScheme?: string | undefined;
+            schemaPath?: string | undefined;
+            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+            baseUrl?: string | undefined;
+        } | undefined;
+        runtimeDetails?: {
+            runtime: "local" | "docker" | "k8s";
+            dockerNetwork?: string | undefined;
+            k8sNamespace?: string | undefined;
+            k8sContext?: string | undefined;
+            serverStartCommand?: string | undefined;
+        } | undefined;
+    }[] | undefined;
+}, {
+    metadata?: {
+        createdAt: string;
+        schemaVersion: string;
+        mcpVersion: string;
+        executorVersion: string;
+        updatedAt: string;
+    } | undefined;
+    workspace?: {
+        repoName?: string | undefined;
+        repoUrl?: string | undefined;
+    } | undefined;
+    services?: {
+        serviceName: string;
+        language?: "python" | "typescript" | "javascript" | "java" | undefined;
+        framework?: "playwright" | "pytest" | "robot" | "junit" | undefined;
+        repository?: string | undefined;
+        testDirectory?: string | undefined;
+        api?: {
+            authHeader?: string | undefined;
+            authScheme?: string | undefined;
+            schemaPath?: string | undefined;
+            authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
+            baseUrl?: string | undefined;
+        } | undefined;
+        runtimeDetails?: {
+            runtime: "local" | "docker" | "k8s";
+            dockerNetwork?: string | undefined;
+            k8sNamespace?: string | undefined;
+            k8sContext?: string | undefined;
+            serverStartCommand?: string | undefined;
+        } | undefined;
+    }[] | undefined;
+}>;
+/** Creates a default workspace config with empty sections and timestamps. */
+export declare function createDefaultConfig(): WorkspaceConfig;
+/**
+ * High-level manager for .skyramp/workspace.yml.
+ *
+ * Provides three focused mutation methods:
+ *   1. initialize()     — create workspace file with repo info
+ *   2. updateMetadata() — update metadata section
+ *   3. addService()     — upsert a single service entry
+ */
+export declare class WorkspaceConfigManager {
+    private workspacePath;
+    private skyrampDir;
+    private configPath;
+    constructor(workspacePath: string);
+    /** Check if workspace config file exists */
+    exists(): Promise<boolean>;
+    /** Get the absolute path to the config file */
+    getConfigPath(): string;
+    /** Get the workspace root path */
+    getWorkspacePath(): string;
+    /** Read and parse workspace config from disk. */
+    read(): Promise<WorkspaceConfig>;
+    /**
+     * Initialize workspace — creates .skyramp/workspace.yml with repo info.
+     * Auto-detects repoName and repoUrl from git when not provided.
+     * Produces an empty services array and default metadata timestamps.
+     */
+    initialize(workspaceInfo?: WorkspaceSection): Promise<WorkspaceConfig>;
+    /**
+     * Update the metadata section of an existing workspace config.
+     * Only the provided fields are merged; metadata.updatedAt is refreshed
+     * automatically.
+     */
+    updateMetadata(metadata: Partial<MetadataSection>): Promise<WorkspaceConfig>;
+    /**
+     * Add a single service entry to the services array.
+     * If a service with the same identity already exists it is replaced
+     * (upsert semantics), otherwise the new entry is appended. Service identity
+     * is the composite (repo, serviceName) — a service's `repo` (absent → primary)
+     * is part of its key, so the same serviceName can coexist across repos in a
+     * unified multi-repo workspace.
+     * metadata.updatedAt is refreshed automatically.
+     */
+    addService(service: Service): Promise<WorkspaceConfig>;
+}

package/build/workspace/workspace.js

@@ -27,9 +27,9 @@ export const serviceSchema = z
     .object({
     serviceName: z.string(),
     // owner/repo this service belongs to (multi-repo workspaces). Absent → the
-    // primary repo. Service identity is the composite (repo, serviceName), so the
-    // same serviceName can appear once per repo without colliding.
-    repo: z.string().optional(),
+    // primary repo. Service identity is the composite (repository, serviceName),
+    // so the same serviceName can appear once per repo without colliding.
+    repository: z.string().optional(),
     language: z.enum(["python", "typescript", "javascript", "java"]).optional(),
     framework: z.enum(["playwright", "pytest", "robot", "junit"]).optional(),
     testDirectory: z.string().optional(),
@@ -318,11 +318,11 @@ export class WorkspaceConfigManager {
         const validatedService = svcResult.data;
         const config = await this.read();
         const services = config.services || [];
-        // Upsert keyed on the composite (repo, serviceName). Absent repo normalizes
-        // to "" (primary) so a primary service and a same-named additional-repo
+        // Upsert keyed on the composite (repository, serviceName). Absent repository
+        // normalizes to "" (primary) so a primary service and a same-named related-repo
         // service are distinct entries.
-        const repoKey = validatedService.repo || "";
-        const idx = services.findIndex((s) => (s.repo || "") === repoKey &&
+        const repoKey = validatedService.repository || "";
+        const idx = services.findIndex((s) => (s.repository || "") === repoKey &&
             s.serviceName === validatedService.serviceName);
         if (idx >= 0) {
             services[idx] = validatedService;

package/build/workspace/workspace.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/workspace/workspace.test.js

@@ -6,10 +6,10 @@ import yaml from "js-yaml";
 import { serviceSchema, WorkspaceConfigManager, validateWorkspaceConfig, createDefaultConfig, WORKSPACE_DIR, WORKSPACE_FILENAME, } from "./workspace.js";
 describe("workspace module (ported from @skyramp/skyramp, SKYR-3794)", () => {
     describe("serviceSchema", () => {
-        it("accepts an optional repo and rejects a non-string repo", () => {
-            expect(serviceSchema.safeParse({ serviceName: "api", repo: "org/api" }).success).toBe(true);
+        it("accepts an optional repository and rejects a non-string repository", () => {
+            expect(serviceSchema.safeParse({ serviceName: "api", repository: "org/api" }).success).toBe(true);
             expect(serviceSchema.safeParse({ serviceName: "api" }).success).toBe(true);
-            expect(serviceSchema.safeParse({ serviceName: "api", repo: 123 }).success).toBe(false);
+            expect(serviceSchema.safeParse({ serviceName: "api", repository: 123 }).success).toBe(false);
         });
         it("rejects unknown fields (strict)", () => {
             expect(serviceSchema.safeParse({ serviceName: "api", bogus: true }).success).toBe(false);
@@ -42,12 +42,12 @@ describe("workspace module (ported from @skyramp/skyramp, SKYR-3794)", () => {
             const mgr = new WorkspaceConfigManager(repoDir);
             await mgr.initialize();
             await mgr.addService({ serviceName: "svc", testDirectory: "tests/primary" });
-            await mgr.addService({ serviceName: "svc", repo: "letsramp/api-insight", testDirectory: "tests/py" });
+            await mgr.addService({ serviceName: "svc", repository: "letsramp/api-insight", testDirectory: "tests/py" });
             await mgr.addService({ serviceName: "svc", testDirectory: "tests/primary-v2" }); // upsert primary
             const cfg = read();
             expect(cfg.services).toHaveLength(2);
-            expect(cfg.services.find((s) => !s.repo).testDirectory).toBe("tests/primary-v2");
-            expect(cfg.services.find((s) => s.repo === "letsramp/api-insight").testDirectory).toBe("tests/py");
+            expect(cfg.services.find((s) => !s.repository).testDirectory).toBe("tests/primary-v2");
+            expect(cfg.services.find((s) => s.repository === "letsramp/api-insight").testDirectory).toBe("tests/py");
             // repoName auto-detected from the git remote.
             expect(cfg.workspace.repoName).toBe("letsramp/primary");
         });

package/node_modules/playwright/lib/mcp/skyramp/loadTraceTool.js

@@ -36,20 +36,23 @@ const loadTraceSchema = {
   name: "skyramp_load_trace",
   title: "Load and replay a Skyramp trace",
   description: [
-    "Load a previously recorded Skyramp trace (.zip or .jsonl/.txt) and replay its actions against the live browser to restore state, then continue recording from that point.",
-    "The replayed actions are merged into the current recording, so subsequent browser_* steps append to them and skyramp_export_zip writes a combined trace.",
-    "STOPPING EARLY: when the user wants to stop partway through the loaded trace before continuing, set ONE of stopAtStep / stopAtUrl / stopBefore based on their prompt. Omit all three to replay the whole trace.",
-    "- stopAtStep: replay steps 1..N then stop (N is 1-based, from the numbered step list).",
+    "Load a previously recorded Skyramp trace (.zip or .jsonl/.txt) and replay a range of its actions against the live browser to restore state, then continue recording from that point.",
+    "The replayed actions are merged into the current recording, so subsequent browser_* steps append to them and skyramp_export_zip writes a combined trace. You can record some steps FIRST, then load a trace to insert an already-recorded fragment at the current point.",
+    "STARTING LATER (skip a stale prefix): set startAtStep to begin replay partway in, skipping earlier steps. Use this when the live browser is already past the trace's opening steps - e.g. the login page changed, you recorded the NEW login manually, and now want to append only the still-valid post-login part of the old trace. Omit to start from step 1.",
+    "- startAtStep: begin replay at step N (1-based, from the numbered step list); steps 1..N-1 are skipped (neither replayed nor recorded).",
+    "STOPPING EARLY: when the user wants to stop partway through the loaded trace before continuing, set ONE of stopAtStep / stopAtUrl / stopBefore based on their prompt. Omit all three to replay to the end.",
+    "- stopAtStep: replay up to and including step N then stop (N is 1-based, from the numbered step list).",
     "- stopAtUrl: stop once the active page URL matches this glob/regex/substring (checked after each action).",
     '- stopBefore: stop right BEFORE the first action whose description contains this text (case-insensitive), e.g. "Checkout" to stop before clicking Checkout.',
-    "If unsure where to stop, first call with dryRun:true to read the numbered step list, then call again with the chosen stop parameter."
+    "If unsure where to start/stop, first call with dryRun:true to read the numbered step list, then call again with the chosen start/stop parameters."
   ].join(" "),
   inputSchema: import_mcpBundle.z.object({
     path: import_mcpBundle.z.string().describe("Absolute path to the trace file (.zip, .jsonl, or .txt)."),
-    stopAtStep: import_mcpBundle.z.number().int().positive().optional().describe("Replay steps 1..N (1-based), then stop before continuing."),
+    startAtStep: import_mcpBundle.z.number().int().positive().optional().describe("Begin replay at step N (1-based); skip steps 1..N-1. Use to skip a stale prefix (e.g. old login)."),
+    stopAtStep: import_mcpBundle.z.number().int().positive().optional().describe("Replay up to and including step N (1-based), then stop before continuing."),
     stopAtUrl: import_mcpBundle.z.string().optional().describe("Stop once the active page URL matches this glob/regex/substring."),
     stopBefore: import_mcpBundle.z.string().optional().describe("Stop before the first action whose description contains this text (case-insensitive)."),
-    dryRun: import_mcpBundle.z.boolean().optional().describe("Parse and list the steps WITHOUT replaying. Use to choose a stop point."),
+    dryRun: import_mcpBundle.z.boolean().optional().describe("Parse and list the steps WITHOUT replaying. Use to choose start/stop points."),
     speed: import_mcpBundle.z.enum(["fast", "slow"]).optional().describe('Replay speed. "slow" adds a 1s delay between actions (default "fast").')
   }),
   // Replaying drives the live browser and mutates the recording, so this is an
@@ -134,17 +137,30 @@ function describeStopReason(result) {
 async function replayActions(actionsList, callbacks, params) {
   const delay = params.speed === "slow" ? 1e3 : 0;
   const stopBefore = params.stopBefore?.toLowerCase();
-  let completedCount = 0;
-  for (let i = 0; i < actionsList.length; i++) {
+  const startIndex = params.startAtStep ? Math.max(0, Math.min(params.startAtStep - 1, actionsList.length)) : 0;
+  let completedCount = startIndex;
+  for (let i = startIndex; i < actionsList.length; i++) {
     const action = actionsList[i];
     if (stopBefore && describeStep(action, i).toLowerCase().includes(stopBefore))
-      return { completedCount, stopIndex: i, stopReason: "stopBefore" };
+      return { completedCount, startIndex, stopIndex: i, stopReason: "stopBefore" };
+    try {
+      callbacks.beforeAction?.(action);
+    } catch (e) {
+      return {
+        completedCount,
+        startIndex,
+        stopIndex: i,
+        stopReason: "error",
+        error: { message: e.message, actionName: action.action.name, stepIndex: i + 1 }
+      };
+    }
     const alias = action.frame.pageAlias || "page";
     const page = callbacks.pageForAlias(alias);
     if (!METADATA_ONLY_ACTIONS.has(action.action.name)) {
       if (!page) {
         return {
           completedCount,
+          startIndex,
           stopIndex: i,
           stopReason: "error",
           error: { message: `No live page for alias "${alias}"`, actionName: action.action.name, stepIndex: i + 1 }
@@ -152,9 +168,11 @@ async function replayActions(actionsList, callbacks, params) {
       }
       try {
         await performClientAction(page, action);
+        await callbacks.afterAction?.(action);
       } catch (e) {
         return {
           completedCount,
+          startIndex,
           stopIndex: i,
           stopReason: "error",
           error: { message: e.message, actionName: action.action.name, stepIndex: i + 1 }
@@ -163,16 +181,16 @@ async function replayActions(actionsList, callbacks, params) {
     }
     completedCount = i + 1;
     if (params.stopAtStep !== void 0 && completedCount >= params.stopAtStep)
-      return { completedCount, stopIndex: i + 1, stopReason: "stopAtStep" };
+      return { completedCount, startIndex, stopIndex: i + 1, stopReason: "stopAtStep" };
     if (params.stopAtUrl) {
       const currentUrl = page?.url() ?? "";
       if (urlMatchesPattern(currentUrl, params.stopAtUrl))
-        return { completedCount, stopIndex: i + 1, stopReason: "stopAtUrl" };
+        return { completedCount, startIndex, stopIndex: i + 1, stopReason: "stopAtUrl" };
     }
     if (delay)
       await new Promise((resolve) => setTimeout(resolve, delay));
   }
-  return { completedCount, stopIndex: actionsList.length, stopReason: "done" };
+  return { completedCount, startIndex, stopIndex: actionsList.length, stopReason: "done" };
 }
 function urlMatchesPattern(currentUrl, pattern) {
   const regexLiteral = /^\/(.*)\/([a-z]*)$/i.exec(pattern);