@skyramp/mcp 0.5.0-rc.2 → 0.5.0-rc.4

package/build/index.js

@@ -7,6 +7,8 @@ import { registerTraceTool } from "./tools/trace/startTraceCollectionTool.js";
 import { registerTraceStopTool } from "./tools/trace/stopTraceCollectionTool.js";
 import { registerExecuteSkyrampTestTool } from "./tools/executeSkyrampTestTool.js";
 import { registerExecuteFleetTool } from "./tools/executeFleetTool.js";
+import { registerFleetLifecycleTools } from "./tools/fleetLifecycleTools.js";
+import { fleetRuns } from "./services/FleetRunRegistry.js";
 import { AUTH_PLACEHOLDER_TOKEN } from "./types/TestTypes.js";
 import { AUTH_CONFLICT_ERROR_MSG } from "./prompts/test-recommendation/recommendationSections.js";
 import { logger } from "./utils/logger.js";
@@ -242,6 +244,7 @@ async function createServer({ era }) {
         registerLogoutTool,
         registerExecuteSkyrampTestTool,
         registerExecuteFleetTool,
+        registerFleetLifecycleTools,
         registerTraceTool,
         registerTraceStopTool,
     ];
@@ -328,11 +331,18 @@ async function createServer({ era }) {
         runInitTrigger();
     return server;
 }
+// A crashing process must not stay alive anywhere near the full graceful
+// shutdown's 30s grace — it still gives workers a moment to cancel, but caps
+// it low enough that a crash can't hang the process.
+const CRASH_CLEANUP_WAIT_MS = 3_000;
+/** Interrupt running fleets (bounded wait) so an exit does not leave workers loading. */
+const cancelFleets = () => fleetRuns.cancelAll(CRASH_CLEANUP_WAIT_MS).catch(() => { });
 // Global error handlers for crash telemetry
 process.on("uncaughtException", async (error) => {
     // Don't send analytics for EPIPE errors
     const isEpipeError = "code" in error && error.code === "EPIPE";
     if (isEpipeError) {
+        await cancelFleets();
         process.exit(0);
     }
     logger.critical("Uncaught exception - MCP server crashing", {
@@ -345,6 +355,7 @@ process.on("uncaughtException", async (error) => {
     catch (telemetryError) {
         logger.error("Failed to send crash telemetry", { telemetryError });
     }
+    await cancelFleets();
     process.exit(1);
 });
 // Handle unhandled promise rejections — without this handler Node.js 15+
@@ -354,6 +365,7 @@ process.on("unhandledRejection", async (reason) => {
     const error = reason instanceof Error ? reason : new Error(String(reason));
     // EPIPE means the client already disconnected — exit cleanly
     if ("code" in error && error.code === "EPIPE") {
+        await cancelFleets();
         process.exit(0);
     }
     // gRPC/Docker connectivity errors — log and survive.
@@ -400,7 +412,9 @@ async function main() {
         const cleanupPlaywright = playwrightService
             ? playwrightService.shutdown().catch(() => { })
             : Promise.resolve();
-        cleanupPlaywright.finally(() => {
+        // A running fleet is interrupted so it can cancel its workers, not left loading them.
+        const cleanupFleets = fleetRuns.cancelAll().catch(() => { });
+        Promise.all([cleanupPlaywright, cleanupFleets]).finally(() => {
             handle.close().finally(() => {
                 process.exit(0);
             });

package/build/services/FleetExecutionService.d.ts

@@ -1,4 +1,5 @@
 import Docker from "dockerode";
+import { Writable } from "stream";
 /**
  * Where the mounted pieces live inside the executor, per container platform.
  *
@@ -11,8 +12,12 @@ export type ContainerPlatform = "linux" | "windows";
 interface Layout {
     work: string;
     certs: string;
-    /** The directory a branch-built library jar is mounted from. */
+    /** The directory a branch-built library jar or package is mounted from. */
     overrideDir: string;
+    /** The native library the image's SDKs load. */
+    nativeLib: string;
+    /** Where a branch-built npm SDK is installed, ahead of the image's on NODE_PATH. */
+    npmOverride: string;
     /** The directory a credential pool outside the work directory is mounted from. */
     poolDir: string;
     imageClasses: string;
@@ -49,11 +54,20 @@ export interface FleetExecutionOptions {
     executorImage?: string;
     platform?: ContainerPlatform;
     entryClass?: string;
-    certsDir: string;
+    /** Required only when the fleet deploys on a remote engine, which is mTLS. */
+    certsDir?: string;
+    /** Opt-in: the mounted daemon socket gives the fleet root-level access to this host. */
+    localDocker?: boolean;
     credentials?: string;
     libraryJar?: string;
+    /** A branch-built pip (.whl, .tar.gz) or npm (.tgz) SDK for a Python, TS or JS fleet. */
+    libraryPackage?: string;
     timeoutSec?: number;
     env?: Record<string, string>;
+    /** Internal live-output sink, fed whole lines; never supplied through a tool's JSON schema. */
+    onOutput?: (chunk: string) => void;
+    /** Internal: aborting it interrupts the run, then kills it after CANCEL_GRACE_MS. */
+    signal?: AbortSignal;
 }
 export interface FleetExecutionResult {
     passed: boolean;
@@ -62,17 +76,47 @@ export interface FleetExecutionResult {
     entryClass: string;
     exitCode: number | null;
     report: string;
+    /** Only the last MAX_BUFFERED_OUTPUT characters; the complete run is at outputLog. */
     output: string;
     result?: unknown;
     timedOut?: boolean;
+    cancelled?: boolean;
+    /** The run's complete output on the host, when it could be written. */
+    outputLog?: string;
 }
-/** A simple (unqualified) Java class name. */
-export declare const JAVA_CLASS_NAME: RegExp;
+/** How long an interrupted fleet gets to cancel its workers before it is killed. */
+export declare const CANCEL_GRACE_MS = 20000;
 /**
- * The generated fleet manager: the one class in the directory that JUnit runs. The journey
- * and the load class travel with it because they sit beside it, and they are compiled but
- * never selected -- the journey is an input the fleet ships to the worker, and the load
- * class only supplies the scenario.
+ * A sink for one of the container's streams that passes on whole lines only. Docker
+ * interleaves stdout and stderr frames, so a line is only whole within its own stream:
+ * one shared sink could split a SKYRAMP_LIMIT line around a stderr frame.
+ */
+export declare function lineSink(emit: (line: string) => void): {
+    sink: Writable;
+    flush: () => void;
+};
+/**
+ * A simple Java class name, or a Python, TypeScript or JavaScript fleet script's file name.
+ *
+ * No `$`: the name is interpolated unquoted into the `sh`/PowerShell command built below, and
+ * `$` there is a variable sigil, not a literal character.
+ */
+export declare const FLEET_ENTRY_NAME: RegExp;
+export type FleetLanguage = "java" | "python" | "typescript" | "javascript";
+/** The language a fleet entry is written in: a script by its extension, else a Java class. */
+export declare function fleetLanguage(entry: string): FleetLanguage;
+/**
+ * The SDK a branch-built package replaces: a pip sdist or wheel for Python, an npm tarball
+ * for TypeScript and JavaScript. Java takes a jar through libraryJar instead.
+ */
+export declare function packageLanguages(pkg: string): FleetLanguage[];
+/** The file an entry lives in, relative to the fleet directory. */
+export declare function fleetFileName(entry: string): string;
+/**
+ * The generated fleet manager: the JUnit class (Java) or the script (Python, TypeScript)
+ * the run starts. The journey and the load file travel with it because they sit beside it
+ * -- the journey is an input the fleet ships to the worker, and the load file only supplies
+ * the scenario.
  */
 export declare function findEntryClass(directory: string, explicit?: string): string;
 /**
@@ -84,12 +128,25 @@ export declare function findEntryClass(directory: string, explicit?: string): st
  */
 export declare function assertNoPinnedImage(fleetFile: string): void;
 /**
- * The fleet reaches the worker it deployed at an address derived from the Docker daemon:
- * the daemon's host for a remote engine, `localhost` for a local socket. Inside this
- * container `localhost` is the container, so a local-socket fleet cannot reach the worker it
- * just deployed and would hang until the timeout instead of failing.
+ * Which Docker daemons the fleet deploys its workers through, read off its hosts.
+ *
+ * `remote`: a host names a tcp or http(s) engine. That connection is mTLS, so the run needs
+ * the client certificates.
+ *
+ * `local`: a host deploys with no remote engine, which is the daemon this tool runs the
+ * executor on. The fleet reaches it through the daemon's socket and needs no certificates:
+ * the way to try a fleet on one's own machine.
+ *
+ * A host that carries an address drives a worker that already runs and deploys nothing, so
+ * it counts as neither. Throws when no host, a non-literal dockerHost, or a host built from a
+ * spread or a bare variable leaves the engine unknown -- the last of those would otherwise
+ * read as local with no dockerHost found, mounting the daemon's socket for a host that may
+ * actually be remote.
  */
-export declare function assertRemoteDaemon(fleetFile: string): void;
+export declare function fleetDaemons(fleetFile: string): {
+    remote: boolean;
+    local: boolean;
+};
 /**
  * The image the run happens in.
  *
@@ -105,10 +162,24 @@ export interface ContainerCommand {
     /** The shell script argv ends with -- named, because its index differs per platform. */
     script: string;
 }
-/** javac, then the JUnit console runner, both against the image's classpath. */
-export declare function buildCommand(entryClass: string, overrideJar: string | undefined, platform?: ContainerPlatform): ContainerCommand;
-/** The lines the fleet printed, which is what a reader wants out of the JUnit noise. */
+/**
+ * Java: javac, then the JUnit console runner, both against the image's classpath. Python,
+ * TypeScript and JavaScript: the fleet script, run from the work directory so its imports
+ * of the load file resolve beside it -- after installing a branch-built SDK package over
+ * the image's own, when one is mounted.
+ */
+export declare function buildCommand(entryClass: string, overrideJar: string | undefined, platform?: ContainerPlatform, overridePackage?: string): ContainerCommand;
+/**
+ * The lines the fleet printed, which is what a reader wants out of the JUnit noise: the
+ * one-line digest, or the report blocks (name in column one, continuation lines indented).
+ */
 export declare function extractReport(output: string): string;
+/**
+ * The report the library rendered itself, carried in the structured result as `report`.
+ * Preferred over the stdout filter: it is the complete text, not whatever survived the
+ * JUnit runner's console, and it is the same text every SDK prints.
+ */
+export declare function embeddedReport(result: unknown): string | undefined;
 /**
  * Where a path inside the container lands on the host.
  *