@skyramp/mcp 0.4.4-rc.1 → 0.4.4

package/build/tools/generate-tests/generateMockRestTool.d.ts

@@ -1,8 +1,7 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, CallToolResult } from "@modelcontextprotocol/server";
 import { MockProtocol } from "../../types/TestTypes.js";
 export { MockProtocol } from "../../types/TestTypes.js";
 import { TestGenerationService } from "../../services/TestGenerationService.js";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 export declare const MOCK_PROTOCOL_EXAMPLES = "\n<example protocol=\"rest\">\nGenerate a REST mock for one HTTP endpoint. Required fields: protocol=\"rest\", endpointURL, method. Use apiSchema with an empty method only when intentionally generating all schema methods.\n{\n  \"protocol\": \"rest\",\n  \"endpointURL\": \"http://payment-service:5001/orders/:order_id/payment_authorizations\",\n  \"method\": \"PUT\",\n  \"requestAware\": true,\n  \"requestData\": \"{\"payment_method_id\":\"pm_123\"}\",\n  \"responseData\": \"{\"accepted\":true}\",\n  \"responseStatusCode\": \"200\"\n}\n</example>\n\n<example protocol=\"rest-traffic-simulation\">\nGenerate a REST mock with traffic simulation (latency + drop rate). minLatency/maxLatency inject a random delay per response; dropRate drops a percentage of requests.\n{\n  \"protocol\": \"rest\",\n  \"endpointURL\": \"http://payment-service:5001/payments\",\n  \"method\": \"POST\",\n  \"responseData\": \"{\"status\":\"ok\"}\",\n  \"minLatency\": 500,\n  \"maxLatency\": 1000,\n  \"dropRate\": 10\n}\n</example>\n\n<example protocol=\"rest-conditional\">\nGenerate a conditional REST mock that selects a response based on request data. Use \"when\" to match request fields and \"requestSchema\" to validate the request body. Multiple mocks for the same endpoint+method are evaluated in order; the first matching \"when\" wins.\n{\n  \"protocol\": \"rest\",\n  \"endpointURL\": \"http://payment-service:5001/api/v1/orders\",\n  \"method\": \"POST\",\n  \"when\": {\"request.body.payment.method\": \"card\"},\n  \"requestSchema\": \"{\"type\":\"object\",\"required\":[\"orderId\",\"payment\"]}\",\n  \"responseData\": \"{\"status\":\"confirmed\"}\",\n  \"responseStatusCode\": \"201\",\n  \"noMatchStatusCode\": 404,\n  \"validationFailureStatusCode\": 422\n}\n</example>\n\n<example protocol=\"grpc\">\nGenerate a gRPC mock. Required fields: protocol=\"grpc\", endpointURL as host:port, protoPath, grpcServiceName. method is the RPC method name; omit or leave empty to generate all service methods. use responseData for successful protobuf-shaped responses, or grpcStatusCode/grpcStatusMessage for gRPC status errors.\n{\n  \"protocol\": \"grpc\",\n  \"endpointURL\": \"profile-service:50051\",\n  \"protoPath\": \"/repo/proto/profiles.proto\",\n  \"grpcServiceName\": \"ProfileService\",\n  \"method\": \"GetProfile\",\n  \"responseData\": \"{\"eligible\":true}\"\n}\n</example>\n\n<example protocol=\"grpc-traffic-simulation\">\nGenerate a gRPC mock with traffic simulation. Same latency/drop fields as REST.\n{\n  \"protocol\": \"grpc\",\n  \"endpointURL\": \"profile-service:50051\",\n  \"protoPath\": \"/repo/proto/profiles.proto\",\n  \"grpcServiceName\": \"ProfileService\",\n  \"method\": \"GetProfile\",\n  \"responseData\": \"{\"eligible\":true}\",\n  \"minLatency\": 200,\n  \"maxLatency\": 800,\n  \"dropRate\": 5\n}\n</example>\n\n<example protocol=\"grpc-status-error\">\nGenerate a gRPC status error mock. Do not provide responseData with grpcStatusCode.\n{\n  \"protocol\": \"grpc\",\n  \"endpointURL\": \"profile-service:50051\",\n  \"protoPath\": \"/repo/proto/profiles.proto\",\n  \"grpcServiceName\": \"ProfileService\",\n  \"method\": \"GetProfile\",\n  \"grpcStatusCode\": 5,\n  \"grpcStatusMessage\": \"profile not found\"\n}\n</example>\n\n<example protocol=\"kafka-producer\">\nGenerate a Kafka producer validation mock. Required fields: protocol=\"kafka\", endpointURL as broker host:port, kafkaTopic, and requestData. Do not pass method or responseData. Traffic simulation (minLatency/maxLatency/dropRate) is NOT supported for Kafka.\n{\n  \"protocol\": \"kafka\",\n  \"endpointURL\": \"broker:9092\",\n  \"kafkaTopic\": \"events\",\n  \"requestData\": \"{\"name\":\"order.created\"}\"\n}\n</example>\n\n<example protocol=\"kafka-consumer\">\nGenerate a Kafka consumer message mock. Required fields: protocol=\"kafka\", endpointURL as broker host:port, kafkaTopic, and responseData. Do not pass method or requestData. Traffic simulation (minLatency/maxLatency/dropRate) is NOT supported for Kafka.\n{\n  \"protocol\": \"kafka\",\n  \"endpointURL\": \"broker:9092\",\n  \"kafkaTopic\": \"events\",\n  \"responseData\": \"{\"accepted\":true}\"\n}\n</example>";
 type MockParams = {
     protocol?: MockProtocol;

package/build/tools/generate-tests/generateMockRestTool.js

@@ -110,7 +110,7 @@ Generate a Kafka consumer message mock. Required fields: protocol="kafka", endpo
 </example>`;
 const mockSchema = {
     protocol: z
-        .nativeEnum(MockProtocol)
+        .enum(MockProtocol)
         .default(MockProtocol.Rest)
         .describe("Protocol for the mock to generate. Use 'rest' for HTTP/OpenAPI mocks, 'grpc' for protobuf/gRPC mocks, and 'kafka' for Kafka topic mocks. See <example> blocks in the tool description for protocol-specific required fields."),
     endpointURL: z
@@ -209,7 +209,7 @@ const mockSchema = {
         .optional()
         .describe("MUST be absolute path to a trace file (e.g., /path/to/trace.json) to generate the mock from captured traffic."),
     when: z
-        .record(z.unknown())
+        .record(z.string(), z.unknown())
         .optional()
         .describe("Conditional-selection predicate (operator map) for REST and gRPC mocks. " +
         "When multiple mocks share an (endpoint, method), the server evaluates each mock's `when` in declared order " +
@@ -566,7 +566,7 @@ Mocks simulate REST, gRPC, or Kafka dependencies so that consumers can develop a
 3. Inline response data (\`responseData\`): generates a static mock with a fixed response.
 
 ${MOCK_PROTOCOL_EXAMPLES}`,
-        inputSchema: mockSchema,
+        inputSchema: z.object(mockSchema),
     }, async (params) => {
         const service = new MockGenerationService();
         const result = await service.generateTest(params);

package/build/tools/generate-tests/generateSmokeRestTool.d.ts

@@ -1,4 +1,4 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 import { TestType } from "../../types/TestTypes.js";
 import { TestGenerationService, BaseTestParams } from "../../services/TestGenerationService.js";
 export declare class SmokeTestService extends TestGenerationService {

package/build/tools/generate-tests/generateSmokeRestTool.js

@@ -28,7 +28,7 @@ export function registerSmokeTestTool(server) {
 Smoke testing is a preliminary check used to verify that an endpoint is accessible and returns a valid response. Smoke tests are useful for quickly identifying critical defects after significant changes. They provide rapid validation for basic functionality verification and endpoint accessibility testing.
 
 **IMPORTANT: If an apiSchema parameter (OpenAPI/Swagger file path or URL) is provided, DO NOT attempt to read or analyze the file contents. These files can be very large. Simply pass the path/URL to the tool - the backend will handle reading and processing the schema file.**`,
-        inputSchema: smokeTestSchema,
+        inputSchema: z.object(smokeTestSchema),
         _meta: {
             keywords: ["smoke test", "quick test"],
         },

package/build/tools/generate-tests/generateUILoadRestTool.d.ts

@@ -0,0 +1,64 @@
+import { McpServer, CallToolResult } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { ProgrammingLanguage } from "../../types/TestTypes.js";
+/**
+ * One recorded journey becomes three files: the browser half, the protocol half, and the
+ * fleet manager that runs them together.
+ *
+ * The split is the point. A ui-load run measures one user flow at two levels at once --
+ * a few real browsers for what a person experiences, and cheap protocol traffic for what
+ * the backend carries -- so the numbers come from the same journey rather than from two
+ * tests that drifted apart.
+ */
+export declare const uiLoadTestSchema: {
+    playwrightTrace: z.ZodOptional<z.ZodString>;
+    playwrightInput: z.ZodOptional<z.ZodString>;
+    playwrightStoragePath: z.ZodDefault<z.ZodString>;
+    language: z.ZodPreprocess<z.ZodDefault<z.ZodEnum<typeof ProgrammingLanguage>>, unknown>;
+    framework: z.ZodPreprocess<z.ZodDefault<z.ZodString>, unknown>;
+    hosts: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        region: z.ZodDefault<z.ZodString>;
+        dockerHost: z.ZodDefault<z.ZodString>;
+        tls: z.ZodDefault<z.ZodString>;
+        hostPort: z.ZodDefault<z.ZodNumber>;
+        address: z.ZodDefault<z.ZodString>;
+        workerImage: z.ZodDefault<z.ZodString>;
+        workerTag: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    browserCoverage: z.ZodDefault<z.ZodNumber>;
+    loadDuration: z.ZodDefault<z.ZodNumber>;
+    loadNumThreads: z.ZodDefault<z.ZodNumber>;
+    loadCount: z.ZodDefault<z.ZodNumber>;
+    loadTargetRPS: z.ZodDefault<z.ZodNumber>;
+    loadRampupDuration: z.ZodDefault<z.ZodNumber>;
+    loadRampupInterval: z.ZodDefault<z.ZodNumber>;
+    thresholds: z.ZodDefault<z.ZodString>;
+    deployWorker: z.ZodDefault<z.ZodBoolean>;
+    include: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    output: z.ZodDefault<z.ZodString>;
+    outputDir: z.ZodString;
+    allowTraceReuse: z.ZodDefault<z.ZodBoolean>;
+    force: z.ZodDefault<z.ZodBoolean>;
+};
+type UILoadParams = z.infer<z.ZodObject<typeof uiLoadTestSchema>>;
+/**
+ * Generate the three ui-load files from one Playwright trace.
+ *
+ * Separate from the REST generators because it does not go through
+ * generateRestTestWrapper: ui-load has its own FFI export, which is what lets it take
+ * hosts and a browser/protocol split that the shared wrapper has no room for.
+ */
+export declare function generateUILoadTest(params: UILoadParams): Promise<CallToolResult>;
+/**
+ * The tool's entry point: the trace-reuse guard and the usage event around the generation,
+ * as skyramp_ui_test_generation has them.
+ *
+ * The guard is scoped "ui-load", not "ui". It namespaces by generator on purpose -- a UI
+ * test and a hybrid trio from one recording are different artifacts -- so what it stops
+ * here is a second, differently named TRIO from the same zip.
+ */
+export declare function handleUILoadTest(params: UILoadParams): Promise<CallToolResult>;
+export declare function registerUILoadTestTool(server: McpServer): void;
+export {};

package/build/tools/generate-tests/generateUILoadRestTool.js

@@ -0,0 +1,512 @@
+import { SkyrampClient } from "@skyramp/skyramp";
+import { z } from "zod";
+import { existsSync, readFileSync } from "fs";
+import { ProgrammingLanguage } from "../../types/TestTypes.js";
+import { toolError, validatePath } from "../../utils/utils.js";
+import { logger } from "../../utils/logger.js";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { generatedFilesFrom } from "../../services/TestGenerationService.js";
+import { getTestsRepoDir } from "../../utils/AnalysisStateManager.js";
+import { executorWorkDirRefusal, generationTargets, isInsideExecutorWorkDir, } from "../../utils/executorWorkDir.js";
+import { resolveOutputDir, stageGeneratedPaths, } from "../../utils/gitStaging.js";
+import { normalizeLanguageParams } from "../../utils/normalizeParams.js";
+import { getEntryPoint } from "../../utils/telemetry.js";
+import { checkTraceReuse, recordTraceOutput } from "./trace-reuse-guard.js";
+const TOOL_NAME = "skyramp_ui_load_test_generation";
+/**
+ * Language and framework in the spelling the generator takes. Done in the SCHEMA rather than
+ * in the handler: input is validated before the handler runs, so "Java" against an enum is
+ * refused before any handler code could lower-case it.
+ */
+const normalized = (field) => (value) => {
+    if (typeof value !== "string")
+        return value;
+    const params = { [field]: value };
+    normalizeLanguageParams(params);
+    return params[field];
+};
+/** A Docker Engine reached over the network, which is mTLS (pkg/fleet/types.go). */
+const REMOTE_DOCKER_HOST = /^(tcp|https?):\/\//i;
+/**
+ * One recorded journey becomes three files: the browser half, the protocol half, and the
+ * fleet manager that runs them together.
+ *
+ * The split is the point. A ui-load run measures one user flow at two levels at once --
+ * a few real browsers for what a person experiences, and cheap protocol traffic for what
+ * the backend carries -- so the numbers come from the same journey rather than from two
+ * tests that drifted apart.
+ */
+export const uiLoadTestSchema = {
+    playwrightTrace: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("REQUIRED. MUST be an absolute path to the Playwright trace zip, e.g. " +
+        "/path/to/trace.zip. This ONE recorded journey drives all three generated files: " +
+        "the UI test replays it in a real browser, and its captured backend calls become " +
+        "the protocol load scenario. Capture it with the browser_* tools + skyramp_export_zip."),
+    // Declared, not resolved in the handler: an undeclared key fails validation before the
+    // handler runs, which is why skyramp_ui_test_generation's own in-handler aliases never fire.
+    playwrightInput: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("The same trace zip under the name skyramp_ui_test_generation uses. Read only when " +
+        "playwrightTrace is absent; pass one or the other."),
+    playwrightStoragePath: z
+        .string()
+        .default("")
+        .describe("Absolute path to the Playwright storage state the journey was recorded with. Lets the generated fleet seed each virtual user's token where the app keeps its session."),
+    language: z
+        .preprocess(normalized("language"), z.enum(ProgrammingLanguage).default(ProgrammingLanguage.PYTHON))
+        .describe("Language for all three generated files (default: python). For python/typescript/" +
+        "javascript the fleet manager is a standalone script; for java it is a JUnit class, " +
+        "and the UI test is JUnit + Playwright-for-Java."),
+    framework: z
+        .preprocess(normalized("framework"), z.string().default(""))
+        .describe("Testing framework for the UI test. Empty uses the per-language default: pytest for " +
+        "python, playwright for typescript/javascript, junit for java."),
+    hosts: z
+        .array(z.object({
+        name: z
+            .string()
+            .min(1)
+            .describe('Unique label for this load-generating host, e.g. "uk-1". Appears in the ' +
+            "generated fleet file and in the aggregated report, so each host's slice is " +
+            "identifiable. Required."),
+        region: z
+            .string()
+            .default("")
+            .describe('Region this host generates load from, e.g. "uk", "us-east". Metadata only: it ' +
+            "labels the host's slice in the report. Recommended when fanning out."),
+        dockerHost: z
+            .string()
+            .default("")
+            .describe("Remote Docker Engine where the worker for this host is deployed, e.g. " +
+            '"tcp://10.0.1.11:2376". Empty means the local/default Docker context, which ' +
+            "skyramp_execute_fleet cannot run: run such a fleet on the host instead."),
+        tls: z
+            .string()
+            .default("")
+            .describe("Directory holding the Docker client certificates (ca.pem, cert.pem, key.pem) " +
+            'for dockerHost, e.g. "/certs/uk". A remote Docker Engine is mTLS, so this is ' +
+            "REQUIRED whenever dockerHost is set: without it the generated fleet refuses to " +
+            "run. The generated file reads SKYRAMP_DOCKER_CERTS at run time and falls back to " +
+            "this directory, so the same fleet moves between machines by setting that one " +
+            "variable. Ask the user where their Docker client certificates live."),
+        hostPort: z
+            .number()
+            .int()
+            .min(0)
+            .max(65535)
+            .default(0)
+            .describe("Port to deploy and drive the worker on, e.g. 35142. REQUIRED when the host has " +
+            "no address: the fleet does not choose a port, and refuses a host that carries " +
+            "neither. Give each host on the same machine its own port."),
+        address: z
+            .string()
+            .default("")
+            .describe('Address of an already-running worker, e.g. "10.10.10.10:35142". The fleet ' +
+            "REFUSES a host with neither an address nor a hostPort, so a generated " +
+            "fleet manager that carries neither cannot be run without being edited. A " +
+            "dockerHost says where to deploy, not how to reach the worker, so it does not " +
+            "replace either. Supply this whenever the worker is reachable directly."),
+        workerImage: z
+            .string()
+            .default("")
+            .describe("Worker image to deploy, when it is not the default for the installed Skyramp " +
+            "version, e.g. a private registry path. Empty uses the library's default. " +
+            "skyramp_execute_fleet refuses a fleet that sets it: run such a fleet on the host."),
+        workerTag: z
+            .string()
+            .default("")
+            .describe("Tag for workerImage. Empty uses the library's default. skyramp_execute_fleet " +
+            "refuses a fleet that sets it: run such a fleet on the host."),
+    }))
+        .min(1)
+        // The fleet runner's own rules (pkg/fleet/runner.go validate), applied here so a host
+        // list it would refuse is refused at generation and not after the files are written.
+        .superRefine((hosts, ctx) => {
+        const seen = new Set();
+        hosts.forEach((host, index) => {
+            if (seen.has(host.name)) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: [index, "name"],
+                    message: `duplicate host name "${host.name}"`,
+                });
+            }
+            seen.add(host.name);
+            if (host.address === "" && host.hostPort === 0) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: [index],
+                    message: `host "${host.name}" needs an address or a hostPort`,
+                });
+            }
+            // Remote engines only: a unix://, npipe:// or fd:// daemon needs no certificates.
+            // A refusal rather than the generator's warning, because with no tls the generated
+            // file carries no certificate lookup at all -- not even the SKYRAMP_DOCKER_CERTS
+            // fallback -- so it cannot run until someone edits it.
+            if (REMOTE_DOCKER_HOST.test(host.dockerHost) && host.tls === "") {
+                ctx.addIssue({
+                    code: "custom",
+                    path: [index, "tls"],
+                    message: `host "${host.name}" deploys on the remote Docker Engine ${host.dockerHost}, ` +
+                        "which is mTLS: set tls to the directory holding ca.pem, cert.pem and key.pem",
+                });
+            }
+        });
+    })
+        .describe("The load-generating hosts to fan the journey across, one entry per VM or region. " +
+        "Each becomes an inline Host(...) in the generated fleet manager. Ask the user which " +
+        "regions they want to drive load from; at least one is required."),
+    browserCoverage: z
+        .number()
+        // Strictly inside 0..1, not inclusive: ui-load always emits BOTH halves, and the fleet
+        // refuses a run carrying both unless the virtual users actually divide between them. 0
+        // gives each half the full count; 1 leaves the protocol half none.
+        .gt(0)
+        .lt(1)
+        .default(0.1)
+        .describe("Fraction of the run executed in REAL browsers, strictly between 0 and 1; the rest " +
+        "runs as the cheaper protocol load. Default 0.1. Raise toward 1 for browser " +
+        "fidelity, lower for mostly protocol load. Do NOT assume a non-default value."),
+    loadDuration: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(5)
+        .describe("Seconds the generated run lasts (default 5). A short run is a smoke test rather " +
+        "than a measurement; raise loadNumThreads for more samples, not the duration."),
+    loadNumThreads: z
+        .number()
+        .int()
+        .positive()
+        // 2, not 1: both halves always ship, so the smallest honest run is one user in each.
+        .default(2)
+        .describe("Total virtual users (default 2), split between the browser and protocol halves by " +
+        "browserCoverage and then across the hosts. Must be large enough to give every " +
+        "host at least one user in each half; a smaller count is refused with the minimum."),
+    loadCount: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0)
+        .describe("Total iterations across the run. 0 means unbounded within loadDuration."),
+    loadTargetRPS: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0)
+        .describe("Target requests per second. 0 means as fast as the virtual users go."),
+    loadRampupDuration: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0)
+        .describe("Seconds over which to reach the full virtual-user count. 0 disables ramp-up."),
+    loadRampupInterval: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0)
+        .describe("Seconds between ramp-up steps."),
+    thresholds: z
+        .string()
+        .default("")
+        .describe("CI pass/fail thresholds the generated fleet manager asserts against, e.g. " +
+        '"lcp_ms=2500,inp_ms=200,cls=0.1,journey_success_rate=0.99".'),
+    deployWorker: z
+        .boolean()
+        .default(true)
+        .describe("Whether the generated fleet manager deploys a worker to each host before running. " +
+        "False expects a worker already there."),
+    include: z
+        .array(z.string())
+        .default([])
+        .describe("Endpoints or patterns to keep in the generated load scenario."),
+    exclude: z
+        .array(z.string())
+        .default([])
+        .describe("Hosts or patterns to drop from the generated load scenario. Matched by EXACT host, " +
+        'not substring: excluding "example.com" does not drop "cdn.example.com". A trace ' +
+        "from a real site carries CDN and analytics traffic, and without excluding those the " +
+        "protocol half load-tests third parties rather than the application."),
+    output: z
+        .string()
+        .default("")
+        .describe("Base name for the three generated files. Empty derives one from the trace filename."),
+    outputDir: z
+        .string()
+        .min(1)
+        .describe("Absolute path to the directory the three files are written to."),
+    allowTraceReuse: z
+        .boolean()
+        .default(false)
+        .describe("A recording captures ONE flow, so a second, differently named trio from the same " +
+        "trace zip is refused. Set true only when this recording genuinely covers the " +
+        "scenario the new name claims. Regenerating the SAME trio never needs it."),
+    force: z
+        .boolean()
+        // true, like every other generation tool: regenerating after adjusting hosts or
+        // exclude is the normal loop, and a refusal there reads as a failed generation.
+        .default(true)
+        .describe("Overwrite existing files with the same names (default true). Set false to keep " +
+        "files that are already there."),
+};
+/** The line the generator prints for each file it writes. */
+const GENERATED_FILES_LINE = /Successfully generated\/updated tests? files?:/i;
+/**
+ * The smallest virtual-user count, at or above `threads`, that gives every host at least
+ * one user in each half -- or null when `threads` already does.
+ *
+ * Mirrors the fleet (pkg/fleet/runner.go): browserShare splits the total between the halves,
+ * rounding the browser slice to nearest and flooring it at 1, and splitShare then divides
+ * each half across the hosts, which this tool always weights equally. The worker runs a
+ * share of zero as ONE session, so a count too small to divide does not fail: it quietly
+ * runs more users than the generated file names.
+ */
+function minimumThreads(threads, hosts, coverage) {
+    const divides = (total) => {
+        const browser = Math.min(Math.max(Math.round(total * coverage), 1), total);
+        return browser >= hosts && total - browser >= hosts;
+    };
+    if (divides(threads))
+        return null;
+    let total = threads + 1;
+    while (!divides(total))
+        total++;
+    return total;
+}
+/**
+ * Every file the generator reports writing. ui-load prints one "Successfully generated"
+ * block PER FILE, and generatedFilesFrom reads a single block, so on its own it returns the
+ * UI test and nothing else. Each block is handed to it in turn, so the parsing stays there.
+ */
+function allGeneratedFiles(result) {
+    const blocks = result.match(/Successfully generated\/updated tests? files?:\s*\n(?:[ \t]+\S[^\n]*\n?)+/gi) ?? [];
+    return blocks.flatMap((block) => generatedFilesFrom(block));
+}
+/**
+ * Host settings the caller asked for that are missing from what was written.
+ *
+ * hostPort and tls travel to the generator inside the hosts JSON, and a native library that
+ * predates them ignores the keys without a word. Nothing on the JavaScript side can see
+ * that, so the written files are the only evidence. Empty when no file could be read, so an
+ * unreadable output never turns a good generation into a failure.
+ */
+function droppedHostSettings(files, hosts) {
+    let written = "";
+    for (const file of files) {
+        try {
+            written += readFileSync(file, "utf8");
+        }
+        catch {
+            // Unreadable: leave it out rather than guess.
+        }
+    }
+    if (written === "")
+        return [];
+    const dropped = [];
+    for (const host of hosts) {
+        // Bounded by non-digits, so 80 is not found inside 8080.
+        const port = new RegExp(`(?<!\\d)${host.hostPort}(?!\\d)`);
+        if (host.hostPort > 0 && !port.test(written)) {
+            dropped.push(`hostPort ${host.hostPort} of host "${host.name}"`);
+        }
+        // Written as a string literal, so a Windows path appears with its backslashes doubled.
+        const escapedTls = host.tls.replace(/\\/g, "\\\\");
+        if (host.tls !== "" &&
+            !written.includes(host.tls) &&
+            !written.includes(escapedTls)) {
+            dropped.push(`tls ${host.tls} of host "${host.name}"`);
+        }
+    }
+    return dropped;
+}
+/**
+ * Generate the three ui-load files from one Playwright trace.
+ *
+ * Separate from the REST generators because it does not go through
+ * generateRestTestWrapper: ui-load has its own FFI export, which is what lets it take
+ * hosts and a browser/protocol split that the shared wrapper has no room for.
+ */
+export async function generateUILoadTest(params) {
+    const playwrightTrace = params.playwrightTrace ?? params.playwrightInput;
+    if (!playwrightTrace) {
+        return toolError("Error: playwrightTrace is required: the absolute path to the trace zip exported " +
+            "by skyramp_export_zip.");
+    }
+    const traceError = validatePath(playwrightTrace, "playwrightTrace");
+    if (traceError)
+        return traceError;
+    if (!existsSync(playwrightTrace)) {
+        return toolError(`Error: playwrightTrace does not exist: ${playwrightTrace}`);
+    }
+    // Checked here like the trace: the generator resolves a relative path against the
+    // server's own directory, and a missing file yields a fleet with no seeded session.
+    if (params.playwrightStoragePath !== "") {
+        const storageError = validatePath(params.playwrightStoragePath, "playwrightStoragePath");
+        if (storageError)
+            return storageError;
+        if (!existsSync(params.playwrightStoragePath)) {
+            return toolError(`Error: playwrightStoragePath does not exist: ${params.playwrightStoragePath}`);
+        }
+    }
+    const outError = validatePath(params.outputDir, "outputDir");
+    if (outError)
+        return outError;
+    // The filesystem guards every other generator gets from TestGenerationService, which
+    // this tool does not pass through because ui-load has its own FFI export.
+    // In cross-repo mode the files belong in the tests repo clone, not the source repo.
+    const outputDir = resolveOutputDir(params.outputDir, getTestsRepoDir());
+    // Nothing written under .skyramp is delivered as a test, and it is the one absolute path
+    // an agent already holds, because the trace zip it just exported lives there.
+    const badTarget = generationTargets(outputDir, params.output || undefined).find(isInsideExecutorWorkDir);
+    if (badTarget)
+        return toolError(executorWorkDirRefusal(badTarget));
+    const minimum = minimumThreads(params.loadNumThreads, params.hosts.length, params.browserCoverage);
+    if (minimum !== null) {
+        return toolError(`Error: loadNumThreads ${params.loadNumThreads} cannot give each of the ` +
+            `${params.hosts.length} host(s) a virtual user in both halves at browserCoverage ` +
+            `${params.browserCoverage}. Use at least ${minimum}, or change browserCoverage.`);
+    }
+    const client = new SkyrampClient();
+    if (typeof client.generateUILoad !== "function") {
+        return toolError("Error: the installed @skyramp/skyramp SDK does not expose generateUILoad. " +
+            "Upgrade to an SDK that includes the ui-load generator.");
+    }
+    // The released SDK has generateUILoad but never reads playwrightStorage, so the session
+    // would be dropped and every virtual user would run unauthenticated, with a success
+    // message on top. The function's own source is the only signal the SDK offers: it has no
+    // capability or version call that distinguishes the two.
+    if (params.playwrightStoragePath !== "" &&
+        !String(client.generateUILoad).includes("playwrightStorage")) {
+        return toolError("Error: the installed @skyramp/skyramp SDK does not take playwrightStoragePath for " +
+            "ui-load, so the recorded session would be silently ignored. Upgrade to an SDK " +
+            "that supports it, or generate without playwrightStoragePath.");
+    }
+    logger.info("Generating ui-load test", {
+        language: params.language,
+        hosts: params.hosts.length,
+        outputDir,
+    });
+    let result;
+    try {
+        result = await client.generateUILoad({
+            playwrightTrace,
+            playwrightStorage: params.playwrightStoragePath,
+            language: params.language,
+            framework: params.framework,
+            output: params.output,
+            outputDir,
+            force: params.force,
+            include: params.include,
+            exclude: params.exclude,
+            loadCount: params.loadCount,
+            loadDuration: params.loadDuration,
+            loadNumThreads: params.loadNumThreads,
+            loadRampupDuration: params.loadRampupDuration,
+            loadRampupInterval: params.loadRampupInterval,
+            loadTargetRPS: params.loadTargetRPS,
+            browserCoverage: params.browserCoverage,
+            thresholds: params.thresholds,
+            hosts: params.hosts,
+            deployWorker: params.deployWorker,
+            entrypoint: getEntryPoint(),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return toolError(`Error: ui-load generation failed: ${message}`);
+    }
+    // The generator prints one line per file it writes. Anything without that line failed in
+    // a way the FFI returned as text rather than as a thrown error. The line itself, not the
+    // word "success": an error quotes what it was given, and both a path and the documented
+    // threshold key journey_success_rate contain that word.
+    if (typeof result !== "string" || !GENERATED_FILES_LINE.test(result)) {
+        return toolError(`Error: ui-load generation failed: ${String(result)}`);
+    }
+    // The tool promises a runnable trio, and a partial generation cannot be run.
+    const files = [...new Set(allGeneratedFiles(result))];
+    if (files.length < 3) {
+        return toolError(`Error: ui-load generation wrote ${files.length} of the three files: ${String(result)}`);
+    }
+    const dropped = droppedHostSettings(files, params.hosts);
+    if (dropped.length > 0) {
+        return toolError(`Error: the generated files do not carry ${dropped.join(", ")}. The installed ` +
+            "@skyramp/skyramp SDK ignored it, so the fleet cannot run as generated. Upgrade to " +
+            "an SDK that supports per-host hostPort and tls.");
+    }
+    // Stage so testbot includes the generated files in its output commit.
+    await stageGeneratedPaths(outputDir);
+    return {
+        content: [
+            { type: "text", text: result },
+            {
+                type: "text",
+                text: `Generated three coordinated files in ${outputDir}:\n` +
+                    `- the UI test, which replays the recorded journey in a real browser\n` +
+                    `- the load file, whose function RETURNS the protocol scenario (static assets filtered out)\n` +
+                    `- the fleet manager, which wires the hosts, the UI test and the scenario into one run\n\n` +
+                    `The fleet manager is the entry point. For python/typescript/javascript run it as a ` +
+                    `script; for java run it as a JUnit test. It builds the scenario, fans the journey ` +
+                    `across the hosts at browserCoverage ${params.browserCoverage}, and asserts the ` +
+                    `thresholds.`,
+            },
+        ],
+    };
+}
+/**
+ * The tool's entry point: the trace-reuse guard and the usage event around the generation,
+ * as skyramp_ui_test_generation has them.
+ *
+ * The guard is scoped "ui-load", not "ui". It namespaces by generator on purpose -- a UI
+ * test and a hybrid trio from one recording are different artifacts -- so what it stops
+ * here is a second, differently named TRIO from the same zip.
+ */
+export async function handleUILoadTest(params) {
+    const traceReuse = await checkTraceReuse(params.playwrightTrace ?? params.playwrightInput, params.output || undefined, params.outputDir, params.allowTraceReuse, "ui-load");
+    if (traceReuse.rejection)
+        return toolError(traceReuse.rejection);
+    const result = await generateUILoadTest(params);
+    // Registered only once generation produced something: recording at check time would
+    // refuse the corrected retry of a failed call for reusing its own trace.
+    if (!result.isError && traceReuse.key && traceReuse.identity) {
+        recordTraceOutput(traceReuse.key, traceReuse.identity);
+    }
+    AnalyticsService.pushTestGenerationToolEvent(TOOL_NAME, result, params).catch(() => {
+        // A usage event never decides whether a generation succeeded.
+    });
+    return result;
+}
+export function registerUILoadTestTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: `Generate a ui-load (hybrid) test from a Playwright trace: one journey measured in real browsers AND as protocol load, in one run.
+
+Emits THREE coordinated files:
+- the UI test — replays the recorded journey in a real browser (the frontend metrics)
+- the load file — a function returning the protocol scenario built from the journey's captured API calls (the backend metrics)
+- the fleet manager — the entry point, wiring hosts + UI test + scenario into one \`Fleet.run(...)\`
+
+**Use this when the user wants frontend and backend numbers for the same flow.** A plain UI test measures only what a browser sees; a plain load test measures only the API. ui-load measures both, from one recording, so the two cannot drift apart.
+
+**Inputs you must gather from the user, not guess:**
+- \`hosts\` — which VMs or regions should generate load. At least one is required; each becomes an inline Host(...) in the fleet manager. A host on a remote Docker Engine (\`dockerHost\`) also needs \`tls\` — the directory holding its client certificates — because that connection is mTLS.
+- \`browserCoverage\` — how much of the run is real browsers. Strictly between 0 and 1. Do NOT assume a non-default value.
+
+**Exclude third-party hosts.** A trace from a real site carries CDN, analytics and ad traffic. \`exclude\` matches the EXACT host, so enumerate every one — excluding "example.com" does not drop "cdn.example.com". Without this the protocol half load-tests other people's infrastructure.
+
+**Typical pipeline:** \`browser_*\` tools to record → \`skyramp_export_zip\` → this tool with the absolute zip path.`,
+        inputSchema: z.object(uiLoadTestSchema),
+        _meta: {
+            keywords: [
+                "ui-load test",
+                "hybrid test",
+                "fleet test",
+                "browser and load",
+            ],
+        },
+    }, async (params) => handleUILoadTest(params));
+}