@skyramp/mcp 0.4.4 → 0.5.0-rc.10

package/build/tools/executeFleetTool.js

@@ -1,24 +1,38 @@
 import { z } from "zod";
-import { executeFleet, JAVA_CLASS_NAME, } from "../services/FleetExecutionService.js";
+import { FLEET_ENTRY_NAME } from "../services/FleetExecutionService.js";
+import { fleetRuns } from "../services/FleetRunRegistry.js";
+import { assertFleetLimitsConfirmed } from "../services/fleetLimitConfirmation.js";
 import { logger } from "../utils/logger.js";
 import { toolError } from "../utils/utils.js";
 const TOOL_NAME = "skyramp_execute_fleet";
 export const fleetExecutionInputSchema = {
     directory: z
         .string()
-        .describe("Directory holding a generated Java ui-load trio (the fleet, load and journey " +
-        "classes) and, usually, its credentials.csv. Java only: a python, typescript or " +
-        "javascript fleet manager is a script, run it directly."),
+        .describe("Directory holding a generated ui-load trio (the fleet manager, load and journey " +
+        "files) in java, python, typescript or javascript and, usually, its credentials.csv."),
     entryClass: z
         .string()
-        .regex(JAVA_CLASS_NAME)
+        .regex(FLEET_ENTRY_NAME)
         .optional()
-        .describe("The fleet class to run. Discovered from *FleetTest.java when omitted."),
+        .describe("The fleet manager to run: a Java class name, or a python/typescript/javascript file " +
+        "name (X_fleet.py, X_fleet.ts, X_fleet.js). Discovered from *FleetTest.java, " +
+        "*_fleet.py, *_fleet.ts or *_fleet.js when omitted."),
     certsDir: z
         .string()
-        .describe("Docker client certificates for the remote engine (ca.pem, cert.pem, key.pem). " +
-        "Required: the run needs a remote engine, and a remote engine is mTLS. Mounted " +
-        "read-only and exported as SKYRAMP_DOCKER_CERTS."),
+        .optional()
+        .describe("Docker client certificates for a remote engine (ca.pem, cert.pem, key.pem). " +
+        "Required when a host of the fleet names a remote Docker engine, which is mTLS. " +
+        "Mounted read-only and exported as SKYRAMP_DOCKER_CERTS. A fleet whose hosts name " +
+        "no dockerHost deploys on the local Docker daemon and needs none. dockerHost is " +
+        "read from the file's text, so write each host's options inline with dockerHost " +
+        '(if any) as a string literal ("tcp://…:2376"), not a variable or a spread -- the ' +
+        "latter reads as no dockerHost found, which this tool refuses rather than guess."),
+    localDocker: z
+        .boolean()
+        .optional()
+        .describe("Allow a fleet that deploys on the local Docker daemon. The daemon's socket is " +
+        "mounted into the executor, which gives the fleet code root-level access to this " +
+        "host. Off by default: set it only after the user agreed to that."),
     credentials: z
         .string()
         .optional()
@@ -26,12 +40,19 @@ export const fleetExecutionInputSchema = {
     libraryJar: z
         .string()
         .optional()
-        .describe("A branch-built skyramp-library jar to compile and run against, for a fix that is not " +
-        "released yet. The executor image's own SDK is used when this is omitted."),
+        .describe("Java only: a branch-built skyramp-library jar to compile and run against, for a fix " +
+        "that is not released yet. The executor image's own SDK is used when this is omitted."),
+    libraryPackage: z
+        .string()
+        .optional()
+        .describe("Python, typescript or javascript: a branch-built SDK package to run against, for a " +
+        "fix that is not released yet -- a pip .whl or .tar.gz for python, an npm .tgz for " +
+        "typescript and javascript. Installed over the executor image's SDK before the " +
+        "fleet starts; the image's own SDK is used when this is omitted."),
     executorImage: z
         .string()
         .optional()
-        .describe("Container image to compile and run in. Defaults to the released executor, or " +
+        .describe("Container image to run in. Defaults to the released executor, or " +
         "SKYRAMP_EXECUTOR_IMAGE. Name a branch-built one when its baked SDK is what you " +
         "are testing."),
     platform: z
@@ -49,6 +70,12 @@ export const fleetExecutionInputSchema = {
         .record(z.string(), z.string())
         .optional()
         .describe("Extra environment for the run, e.g. SKYRAMP_TEST_BASE_URL."),
+    confirmationToken: z
+        .string()
+        .optional()
+        .describe("Required when the fleet file sets limits: the token returned beside the echoed " +
+        "normalized limits. Pass it only after the user confirmed those limits. A fleet " +
+        "without limits needs none."),
 };
 /**
  * Runs a generated fleet test and reports what happened.
@@ -57,40 +84,57 @@ export const fleetExecutionInputSchema = {
  * executor container every other generated test runs in compiles the trio and starts the
  * fleet manager, and the caller gets the run's own report plus its result as data.
  *
- * The worker is deployed by the test, not by this tool, so the run needs a remote Docker
- * engine: inside a container, a locally deployed worker is not reachable at the localhost
- * address the fleet resolves for it.
+ * The worker is deployed by the test, not by this tool: on a remote Docker engine over mTLS,
+ * or, for a host that names no engine, on the local daemon through its socket.
  */
 export function registerExecuteFleetTool(server) {
     server.registerTool(TOOL_NAME, {
         title: "Execute a generated fleet test",
-        description: "Compile and run a generated Java ui-load fleet trio in the Skyramp executor container, " +
-            "against a remote Docker engine, and return the run's report, its verdict and its " +
-            "structured result. Point it at the directory the generation wrote.",
+        description: "Run a generated ui-load fleet trio (java, python, typescript or javascript) in the Skyramp executor container " +
+            "and return the run's report, its verdict and its structured result. It blocks until " +
+            "the run ends and relays no limit events while it runs: prefer skyramp_start_fleet " +
+            "when the client can poll. The fleet deploys " +
+            "its workers on the Docker engines its hosts name: a remote engine needs certsDir, a " +
+            "host with no dockerHost deploys on the local Docker daemon and needs no " +
+            "certificates but needs localDocker: true, because the daemon's socket gives the run " +
+            "root-level access to this host. Point it at the directory the generation wrote. A fleet with limits " +
+            "needs the confirmationToken returned beside its echoed limits; pass it only after the " +
+            "user confirmed those limits. The token ties the run to the echoed limits, it does not " +
+            "record the user's confirmation.",
         inputSchema: z.object(fleetExecutionInputSchema),
-    }, async (args) => {
+    }, async (args, extra) => {
         try {
-            const run = await executeFleet({
+            assertFleetLimitsConfirmed(args);
+            // Through the registry, so a blocking run shares the one-run-per-directory guard.
+            const run = await fleetRuns.run({
                 directory: args.directory,
                 executorImage: args.executorImage,
                 platform: args.platform,
                 entryClass: args.entryClass,
                 certsDir: args.certsDir,
+                localDocker: args.localDocker,
                 credentials: args.credentials,
                 libraryJar: args.libraryJar,
+                libraryPackage: args.libraryPackage,
                 timeoutSec: args.timeoutSec,
                 env: args.env,
-            });
+            }, extra.mcpReq.signal);
             const headline = run.timedOut
                 ? `Fleet run timed out after ${args.timeoutSec ?? 600}s`
-                : `Fleet run ${run.passed ? "PASSED" : "FAILED"} (${run.entryClass} in ${run.executorImage}, exit ${run.exitCode})`;
+                : run.cancelled
+                    ? "Fleet run cancelled"
+                    : `Fleet run ${run.passed ? "PASSED" : "FAILED"} (${run.entryClass} in ${run.executorImage}, exit ${run.exitCode})`;
             const text = [
                 headline,
                 run.report || "(the run printed no report lines)",
                 run.result
                     ? "Structured result:\n" + JSON.stringify(run.result, null, 2)
                     : "",
-                run.passed ? "" : "Output:\n" + run.output.slice(-4000),
+                run.passed
+                    ? ""
+                    : "Output:\n" +
+                        run.output.slice(-4000) +
+                        (run.outputLog ? `\n(full log: ${run.outputLog})` : ""),
             ]
                 .filter(Boolean)
                 .join("\n\n");

package/build/tools/fixErrorTool.js

@@ -58,8 +58,9 @@ export function registerFixErrorTool(server) {
             return errorResult;
         }
         finally {
+            // No prompt: it carries the user's test code, and PushToolEvent
+            // forwards every field verbatim.
             AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
-                prompt: params.prompt,
                 testFile: params.testFile,
             }).catch((err) => {
                 logger.warning("Analytics event failed", { error: String(err) });

package/build/tools/fleetLifecycleTools.d.ts

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import type { FleetExecutionResult } from "../services/FleetExecutionService.js";
+/** The most run output a result carries; a multi-hour run's log stays on disk. */
+export declare const MAX_RESULT_OUTPUT: number;
+/** The result with its output cut to the last MAX_RESULT_OUTPUT characters, saying so. */
+export declare function boundedResult(result: FleetExecutionResult): FleetExecutionResult | {
+    output: string;
+    outputTruncated: string;
+    passed: boolean;
+    executorImage: string;
+    platform: import("../services/FleetExecutionService.js").ContainerPlatform;
+    entryClass: string;
+    exitCode: number | null;
+    report: string;
+    result?: unknown;
+    timedOut?: boolean;
+    cancelled?: boolean;
+    outputLog?: string;
+};
+export declare function registerFleetLifecycleTools(server: McpServer): void;

package/build/tools/fleetLifecycleTools.js

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import { SkyrampClient } from "@skyramp/skyramp";
+import { fleetRuns } from "../services/FleetRunRegistry.js";
+import { assertFleetLimitsConfirmed } from "../services/fleetLimitConfirmation.js";
+import { fleetExecutionInputSchema } from "./executeFleetTool.js";
+import { toolError } from "../utils/utils.js";
+import { makeProgressReporter } from "../utils/progress.js";
+const response = (value) => ({
+    content: [{ type: "text", text: JSON.stringify(value) }],
+});
+const errorResponse = (error) => toolError(error instanceof Error ? error.message : String(error));
+/** The most run output a result carries; a multi-hour run's log stays on disk. */
+export const MAX_RESULT_OUTPUT = 64 * 1024;
+/** The result with its output cut to the last MAX_RESULT_OUTPUT characters, saying so. */
+export function boundedResult(result) {
+    if (result.output.length <= MAX_RESULT_OUTPUT)
+        return result;
+    return {
+        ...result,
+        output: result.output.slice(-MAX_RESULT_OUTPUT),
+        outputTruncated: `output cut to its last ${MAX_RESULT_OUTPUT} of ${result.output.length} characters; ` +
+            (result.outputLog
+                ? `the full log is ${result.outputLog}`
+                : "the full log could not be written to disk"),
+    };
+}
+export function registerFleetLifecycleTools(server) {
+    server.registerTool("skyramp_kpi_catalog", {
+        title: "Read the fleet KPI catalogue",
+        description: "Read native limit KPI names, base units, valid aggregations, scopes, deferred features and site defaults. A unitless rate is a ratio (0..1). Translate latency in seconds to ms. Ask instead of inventing unknown metrics, scopes, ambiguous units or sustained-breach durations. No run is started.",
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        try {
+            const client = new SkyrampClient();
+            if (!client.getFleetLimitCatalogue)
+                throw new Error("installed SDK lacks the native limit catalogue; upgrade the SDK");
+            return response(client.getFleetLimitCatalogue());
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    server.registerTool("skyramp_start_fleet", {
+        title: "Start a fleet and return its run id",
+        description: "Start a generated fleet asynchronously. A fleet with limits needs confirmationToken: the token returned beside the echoed normalized limits, passed only after the user confirmed them. The token ties the run to the echoed limits, it does not record the user's confirmation. A fleet on the local Docker daemon needs localDocker: true, because the daemon's socket gives the run root-level access to this host. Keep this MCP session open. Poll skyramp_fleet_status every few seconds, relay each tripped/cleared limit event immediately, then collect skyramp_fleet_result. The fleet core, not the agent, decides warnings, failure and stopping.",
+        inputSchema: z.object(fleetExecutionInputSchema),
+    }, async ({ confirmationToken, ...args }) => {
+        try {
+            assertFleetLimitsConfirmed({ ...args, confirmationToken });
+            return response({ runId: fleetRuns.start(args) });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    server.registerTool("skyramp_fleet_status", {
+        title: "Read new live fleet events",
+        description: "Poll the same MCP session with runId and the previous next cursor. Relay limit events while the run is in progress; do not wait for the final report. An event is emitted once per transition. A call returns at most 200 events; when more is true, call again at once with next. truncated means the caller fell behind retention.",
+        inputSchema: z.object({
+            runId: z
+                .string()
+                .describe("The run id returned by skyramp_start_fleet."),
+            since: z
+                .number()
+                .int()
+                .nonnegative()
+                .default(0)
+                .describe("The next cursor from the previous skyramp_fleet_status response; 0 on the first call. Not an elapsed time or event count."),
+        }),
+        annotations: { readOnlyHint: true },
+    }, async ({ runId, since }, ctx) => {
+        try {
+            const status = fleetRuns.status(runId, since);
+            const notify = makeProgressReporter(ctx);
+            for (const item of status.events)
+                await notify(item.sequence + 1, status.next, JSON.stringify(item.event));
+            return response(status);
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    server.registerTool("skyramp_fleet_result", {
+        title: "Collect a completed fleet report",
+        description: "Read the completed fleet's deterministic report, verdict and structured result. release=true also removes the retained job; only use it after saving the result. A running job is never removed.",
+        inputSchema: z.object({
+            runId: z
+                .string()
+                .describe("The run id returned by skyramp_start_fleet."),
+            release: z
+                .boolean()
+                .default(false)
+                .describe("When true, also remove the retained job after reading it. Only use after saving the result; a running job is never removed."),
+        }),
+    }, async ({ runId, release }) => {
+        try {
+            const result = fleetRuns.result(runId, release);
+            return {
+                ...response(boundedResult(result)),
+                ...(result.passed ? {} : { isError: true }),
+            };
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    server.registerTool("skyramp_fleet_cancel", {
+        title: "Cancel a running fleet",
+        description: "Cancel a fleet started with skyramp_start_fleet, by runId, when the user asks to stop it. The run is interrupted so the fleet can cancel its workers, and killed if it has not ended after a grace period. Poll skyramp_fleet_status until done, then collect skyramp_fleet_result. Cancelling a finished run changes nothing.",
+        inputSchema: z.object({
+            runId: z
+                .string()
+                .describe("The run id returned by skyramp_start_fleet."),
+        }),
+    }, async ({ runId }) => {
+        try {
+            return response(fleetRuns.cancel(runId));
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+}

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

@@ -1,6 +1,43 @@
 import { McpServer, CallToolResult } from "@modelcontextprotocol/server";
+import { z } from "zod";
 import { TestType } from "../../types/TestTypes.js";
 import { TestGenerationService, BaseTestParams } from "../../services/TestGenerationService.js";
+export declare const integrationTestSchema: {
+    language: z.ZodEnum<typeof import("../../types/TestTypes.js").ProgrammingLanguage>;
+    framework: z.ZodString;
+    output: z.ZodOptional<z.ZodString>;
+    deployDashboard: z.ZodDefault<z.ZodBoolean>;
+    runtime: z.ZodDefault<z.ZodPreprocess<z.ZodEnum<typeof import("../../types/TestTypes.js").RuntimeEnvironment>, unknown>>;
+    dockerNetwork: z.ZodDefault<z.ZodString>;
+    dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
+    k8sNamespace: z.ZodDefault<z.ZodString>;
+    k8sConfig: z.ZodDefault<z.ZodString>;
+    k8sContext: z.ZodDefault<z.ZodString>;
+    authHeader: z.ZodDefault<z.ZodString>;
+    authScheme: z.ZodDefault<z.ZodString>;
+    insecure: z.ZodDefault<z.ZodBoolean>;
+    outputDir: z.ZodString;
+    force: z.ZodDefault<z.ZodBoolean>;
+    mockPort: z.ZodDefault<z.ZodNumber>;
+    optionalFields: z.ZodDefault<z.ZodBoolean>;
+    prompt: z.ZodString;
+    trace: z.ZodOptional<z.ZodString>;
+    include: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    exclude: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    codeReuse: z.ZodDefault<z.ZodBoolean>;
+    modularizeCode: z.ZodDefault<z.ZodBoolean>;
+    pathParams: z.ZodDefault<z.ZodString>;
+    queryParams: z.ZodDefault<z.ZodString>;
+    formParams: z.ZodDefault<z.ZodString>;
+    enhanceAssertions: z.ZodDefault<z.ZodBoolean>;
+    endpointURL: z.ZodDefault<z.ZodString>;
+    apiSchema: z.ZodDefault<z.ZodString>;
+    requestData: z.ZodDefault<z.ZodString>;
+    responseStatusCode: z.ZodDefault<z.ZodString>;
+    chainingKey: z.ZodOptional<z.ZodString>;
+    scenarioFile: z.ZodOptional<z.ZodString>;
+    emitIntegrationTeardown: z.ZodDefault<z.ZodBoolean>;
+};
 export declare class IntegrationTestService extends TestGenerationService {
     protected getTestType(): TestType;
     generateTest(params: BaseTestParams & Record<string, any>): Promise<CallToolResult>;
@@ -9,6 +46,7 @@ export declare class IntegrationTestService extends TestGenerationService {
         responseData?: string;
         playwrightInput?: string;
         scenarioFile?: string;
+        emitIntegrationTeardown?: boolean;
     }): any;
     protected handleApiAnalysis(_params: BaseTestParams): Promise<CallToolResult | null>;
 }

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

@@ -11,8 +11,13 @@ import { readScenarioNameFromFile } from "./scenarioFileIdentity.js";
 import { toolError } from "../../utils/utils.js";
 import { enhanceAssertionsStep } from "../../skills/enhanceAssertionsSkill.js";
 const ADD_ASSERTIONS_DEFAULT = isTestbotEnabled();
-const integrationTestSchema = z
+export const integrationTestSchema = z
     .object({
+    emitIntegrationTeardown: z
+        .boolean()
+        .default(false)
+        .describe("Register every record the test creates with the client's created-resources scope so the library deletes them in reverse order when the test exits, on success and on failure. " +
+        "Use for tests that create data against a shared or long-lived target."),
     enhanceAssertions: z
         .boolean()
         .default(ADD_ASSERTIONS_DEFAULT)
@@ -80,6 +85,7 @@ ${enhanceAssertionsStep("integration", "generated test file")}
             responseData: params.responseData,
             playwrightInput: params.playwrightInput,
             scenarioFile: params.scenarioFile,
+            emitIntegrationTeardown: params.emitIntegrationTeardown ?? false,
         };
     }
     async handleApiAnalysis(_params) {

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

@@ -25,24 +25,33 @@ export declare const uiLoadTestSchema: {
         address: z.ZodDefault<z.ZodString>;
         workerImage: z.ZodDefault<z.ZodString>;
         workerTag: z.ZodDefault<z.ZodString>;
+        browserSessions: z.ZodDefault<z.ZodNumber>;
     }, 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>;
+    coresPerBrowser: z.ZodOptional<z.ZodNumber>;
     loadRampupDuration: z.ZodDefault<z.ZodNumber>;
     loadRampupInterval: z.ZodDefault<z.ZodNumber>;
+    limits: z.ZodOptional<z.ZodArray<z.ZodString>>;
     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;
+    credentialsFile: z.ZodOptional<z.ZodString>;
     allowTraceReuse: z.ZodDefault<z.ZodBoolean>;
     force: z.ZodDefault<z.ZodBoolean>;
 };
 type UILoadParams = z.infer<z.ZodObject<typeof uiLoadTestSchema>>;
+/**
+ * Legacy threshold keys in the limit form the fleet core maps them to (D7): inclusive
+ * bounds, evaluated per region and overall, CPU per host. For the echo only; the
+ * thresholds themselves still reach the generator unchanged.
+ */
+export declare function legacyThresholdLimits(thresholds: string): string[];
 /**
  * Generate the three ui-load files from one Playwright trace.
  *
@@ -51,6 +60,15 @@ type UILoadParams = z.infer<z.ZodObject<typeof uiLoadTestSchema>>;
  * hosts and a browser/protocol split that the shared wrapper has no room for.
  */
 export declare function generateUILoadTest(params: UILoadParams): Promise<CallToolResult>;
+/**
+ * Copy the credential pool (credentialsFile, else credentials.csv beside the recorded
+ * session) to credentials.csv beside the generated files, where the fleet reads it; an
+ * existing one is left alone. Returns a line for the tool's result, or "" when not needed.
+ */
+export declare function placeCredentialPool(files: string[], outputDir: string, params: {
+    credentialsFile?: string;
+    playwrightStoragePath?: string;
+}): string;
 /**
  * The tool's entry point: the trace-reuse guard and the usage event around the generation,
  * as skyramp_ui_test_generation has them.