@skyramp/mcp 0.4.4-rc.1 → 0.4.4

package/build/types/RepositoryAnalysis.js

@@ -20,7 +20,7 @@ export var ScenarioSource;
     ScenarioSource["AgentEnriched"] = "agent-enriched";
 })(ScenarioSource || (ScenarioSource = {}));
 // ── Zod schemas ──
-export const analysisScopeSchema = z.nativeEnum(AnalysisScope);
+export const analysisScopeSchema = z.enum(AnalysisScope);
 export const paramInfoSchema = z.object({
     name: z.string(),
     type: z.string(),
@@ -40,15 +40,15 @@ export const endpointInteractionSchema = z.object({
     type: z.enum(["success", "error", "edge-case"]),
     request: z.object({
         contentType: z.string().optional(),
-        body: z.record(z.any()).optional(),
-        headers: z.record(z.string()).optional(),
-        queryParams: z.record(z.any()).optional(),
+        body: z.record(z.string(), z.any()).optional(),
+        headers: z.record(z.string(), z.string()).optional(),
+        queryParams: z.record(z.string(), z.any()).optional(),
     }),
     response: z.object({
         statusCode: z.number(),
         description: z.string(),
-        body: z.record(z.any()).optional(),
-        headers: z.record(z.string()).optional(),
+        body: z.record(z.string(), z.any()).optional(),
+        headers: z.record(z.string(), z.string()).optional(),
         cookies: z.array(cookieInfoSchema).optional(),
     }),
 });
@@ -83,9 +83,11 @@ export const scenarioStepSchema = z.object({
     path: z.string(),
     description: z.string(),
     interactionType: z.enum(["success", "error", "edge-case"]),
-    requestBody: z.record(z.any()).optional(),
-    queryParams: z.record(z.any()).optional(),
-    responseBody: z.union([z.record(z.any()), z.array(z.any())]).optional(),
+    requestBody: z.record(z.string(), z.any()).optional(),
+    queryParams: z.record(z.string(), z.any()).optional(),
+    responseBody: z
+        .union([z.record(z.string(), z.any()), z.array(z.any())])
+        .optional(),
     expectedStatusCode: z.number(),
     expectedResponseFields: z.array(z.string()).optional(),
     chainsFrom: z
@@ -192,7 +194,7 @@ export const repositoryAnalysisSchema = z.object({
             contract: z.number(),
             smoke: z.number(),
         }),
-        testLocations: z.record(z.string()),
+        testLocations: z.record(z.string(), z.string()),
         hasCoverageReports: z.boolean(),
         estimatedCoverage: z.number().optional(),
         relevantExternalTestPaths: z.array(z.string()).optional(),

package/build/types/StepMethod.d.ts

@@ -37,4 +37,27 @@ export declare const STEP_METHOD_DESCRIPTION: string;
  * The field itself: normalised first, then checked, so a rejection is about the
  * verb and never about its capitalisation.
  */
-export declare const stepMethodSchema: z.ZodEffects<z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE", "CONNECT", "assert", "click", "drag", "drag-hold", "hover", "inspect", "navigate", "press", "release", "tap", "type", "wait", "OPERATION"]>, "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "type" | "TRACE" | "CONNECT" | "assert" | "click" | "drag" | "drag-hold" | "hover" | "inspect" | "navigate" | "press" | "release" | "tap" | "wait" | "OPERATION", unknown>;
+export declare const stepMethodSchema: z.ZodPreprocess<z.ZodEnum<{
+    GET: "GET";
+    POST: "POST";
+    PUT: "PUT";
+    DELETE: "DELETE";
+    PATCH: "PATCH";
+    HEAD: "HEAD";
+    OPTIONS: "OPTIONS";
+    type: "type";
+    TRACE: "TRACE";
+    CONNECT: "CONNECT";
+    assert: "assert";
+    click: "click";
+    drag: "drag";
+    "drag-hold": "drag-hold";
+    hover: "hover";
+    inspect: "inspect";
+    navigate: "navigate";
+    press: "press";
+    release: "release";
+    tap: "tap";
+    wait: "wait";
+    OPERATION: "OPERATION";
+}>, unknown>;

package/build/types/StepMethod.js

@@ -87,5 +87,5 @@ export const STEP_METHOD_DESCRIPTION = "What this step does to the system: an HT
 export const stepMethodSchema = z.preprocess((value) => typeof value === "string"
     ? (normalizeStepMethod(value) ?? value.trim())
     : value, z.enum(STEP_METHODS, {
-    errorMap: () => ({ message: `method ${STEP_METHOD_HELP}` }),
+    error: () => `method ${STEP_METHOD_HELP}`,
 }));

package/build/types/TestTypes.d.ts

@@ -51,28 +51,22 @@ export declare enum RuntimeEnvironment {
     DOCKER = "docker",
     KUBERNETES = "k8s"
 }
-export declare const runtimeEnvironmentSchema: z.ZodNativeEnum<typeof RuntimeEnvironment>;
-export declare const runtimeEnvironmentInputSchema: z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>;
+export declare const runtimeEnvironmentSchema: z.ZodEnum<typeof RuntimeEnvironment>;
+export declare const runtimeEnvironmentInputSchema: z.ZodPreprocess<z.ZodEnum<typeof RuntimeEnvironment>, unknown>;
 export declare function normalizeRuntimeEnvironment(value: RuntimeEnvironment | "kubernetes"): RuntimeEnvironment;
 export interface TestConfig {
     testType: TestType;
     toolName: string;
     description: string;
-    additionalFields?: Record<string, z.ZodSchema>;
+    additionalFields?: Record<string, z.ZodType>;
 }
 export declare const languageSchema: z.ZodObject<{
-    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    language: z.ZodEnum<typeof ProgrammingLanguage>;
     framework: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    language: ProgrammingLanguage;
-    framework: string;
-}, {
-    language: ProgrammingLanguage;
-    framework: string;
-}>;
+}, z.core.$strip>;
 export declare const baseSchema: z.ZodObject<{
     deployDashboard: z.ZodDefault<z.ZodBoolean>;
-    runtime: z.ZodDefault<z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>>;
+    runtime: z.ZodDefault<z.ZodPreprocess<z.ZodEnum<typeof RuntimeEnvironment>, unknown>>;
     dockerNetwork: z.ZodDefault<z.ZodString>;
     dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
     k8sNamespace: z.ZodDefault<z.ZodString>;
@@ -81,78 +75,35 @@ export declare const baseSchema: z.ZodObject<{
     authHeader: z.ZodDefault<z.ZodString>;
     authScheme: z.ZodDefault<z.ZodString>;
     insecure: z.ZodDefault<z.ZodBoolean>;
-    output: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    output: z.ZodOptional<z.ZodString>;
     outputDir: z.ZodString;
     force: z.ZodDefault<z.ZodBoolean>;
     mockPort: z.ZodDefault<z.ZodNumber>;
     optionalFields: z.ZodDefault<z.ZodBoolean>;
     prompt: z.ZodString;
-    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    language: z.ZodEnum<typeof ProgrammingLanguage>;
     framework: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    language: ProgrammingLanguage;
-    framework: string;
-    deployDashboard: boolean;
-    runtime: RuntimeEnvironment;
-    dockerNetwork: string;
-    dockerWorkerPort: number;
-    k8sNamespace: string;
-    k8sConfig: string;
-    k8sContext: string;
-    authHeader: string;
-    authScheme: string;
-    insecure: boolean;
-    outputDir: string;
-    force: boolean;
-    mockPort: number;
-    optionalFields: boolean;
-    prompt: string;
-    output?: string | undefined;
-}, {
-    language: ProgrammingLanguage;
-    framework: string;
-    outputDir: string;
-    prompt: string;
-    deployDashboard?: boolean | undefined;
-    runtime?: unknown;
-    dockerNetwork?: string | undefined;
-    dockerWorkerPort?: number | undefined;
-    k8sNamespace?: string | undefined;
-    k8sConfig?: string | undefined;
-    k8sContext?: string | undefined;
-    authHeader?: string | undefined;
-    authScheme?: string | undefined;
-    insecure?: boolean | undefined;
-    output?: string | undefined;
-    force?: boolean | undefined;
-    mockPort?: number | undefined;
-    optionalFields?: boolean | undefined;
-}>;
+}, z.core.$strip>;
 export declare const basePlaywrightSchema: z.ZodObject<{
     playwrightInput: z.ZodString;
     playwrightStoragePath: z.ZodOptional<z.ZodString>;
     playwrightSaveStoragePath: z.ZodOptional<z.ZodString>;
-    playwrightViewportSize: z.ZodDefault<z.ZodUnion<[z.ZodEnum<["", "hd", "full-hd", "2k"]>, z.ZodString]>>;
-    browser: z.ZodDefault<z.ZodEnum<["chromium", "firefox", "webkit"]>>;
+    playwrightViewportSize: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+        "": "";
+        hd: "hd";
+        "full-hd": "full-hd";
+        "2k": "2k";
+    }>, z.ZodString]>>;
+    browser: z.ZodDefault<z.ZodEnum<{
+        chromium: "chromium";
+        firefox: "firefox";
+        webkit: "webkit";
+    }>>;
     device: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    playwrightInput: string;
-    playwrightViewportSize: string;
-    browser: "chromium" | "firefox" | "webkit";
-    device: string;
-    playwrightStoragePath?: string | undefined;
-    playwrightSaveStoragePath?: string | undefined;
-}, {
-    playwrightInput: string;
-    playwrightStoragePath?: string | undefined;
-    playwrightSaveStoragePath?: string | undefined;
-    playwrightViewportSize?: string | undefined;
-    browser?: "chromium" | "firefox" | "webkit" | undefined;
-    device?: string | undefined;
-}>;
+}, z.core.$strip>;
 export declare const baseTraceSchema: z.ZodObject<{
     deployDashboard: z.ZodDefault<z.ZodBoolean>;
-    runtime: z.ZodDefault<z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>>;
+    runtime: z.ZodDefault<z.ZodPreprocess<z.ZodEnum<typeof RuntimeEnvironment>, unknown>>;
     dockerNetwork: z.ZodDefault<z.ZodString>;
     dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
     k8sNamespace: z.ZodDefault<z.ZodString>;
@@ -161,65 +112,21 @@ export declare const baseTraceSchema: z.ZodObject<{
     authHeader: z.ZodDefault<z.ZodString>;
     authScheme: z.ZodDefault<z.ZodString>;
     insecure: z.ZodDefault<z.ZodBoolean>;
-    output: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    output: z.ZodOptional<z.ZodString>;
     outputDir: z.ZodString;
     force: z.ZodDefault<z.ZodBoolean>;
     mockPort: z.ZodDefault<z.ZodNumber>;
     optionalFields: z.ZodDefault<z.ZodBoolean>;
     prompt: z.ZodString;
-    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    language: z.ZodEnum<typeof ProgrammingLanguage>;
     framework: z.ZodString;
     trace: z.ZodString;
-    include: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    exclude: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-    language: ProgrammingLanguage;
-    framework: string;
-    deployDashboard: boolean;
-    runtime: RuntimeEnvironment;
-    dockerNetwork: string;
-    dockerWorkerPort: number;
-    k8sNamespace: string;
-    k8sConfig: string;
-    k8sContext: string;
-    authHeader: string;
-    authScheme: string;
-    insecure: boolean;
-    outputDir: string;
-    force: boolean;
-    mockPort: number;
-    optionalFields: boolean;
-    prompt: string;
-    trace: string;
-    include: string[];
-    exclude: string[];
-    output?: string | undefined;
-}, {
-    language: ProgrammingLanguage;
-    framework: string;
-    outputDir: string;
-    prompt: string;
-    trace: string;
-    deployDashboard?: boolean | undefined;
-    runtime?: unknown;
-    dockerNetwork?: string | undefined;
-    dockerWorkerPort?: number | undefined;
-    k8sNamespace?: string | undefined;
-    k8sConfig?: string | undefined;
-    k8sContext?: string | undefined;
-    authHeader?: string | undefined;
-    authScheme?: string | undefined;
-    insecure?: boolean | undefined;
-    output?: string | undefined;
-    force?: boolean | undefined;
-    mockPort?: number | undefined;
-    optionalFields?: boolean | undefined;
-    include?: string[] | undefined;
-    exclude?: string[] | undefined;
-}>;
+    include: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
 export declare const baseTestSchema: {
     deployDashboard: z.ZodDefault<z.ZodBoolean>;
-    runtime: z.ZodDefault<z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>>;
+    runtime: z.ZodDefault<z.ZodPreprocess<z.ZodEnum<typeof RuntimeEnvironment>, unknown>>;
     dockerNetwork: z.ZodDefault<z.ZodString>;
     dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
     k8sNamespace: z.ZodDefault<z.ZodString>;
@@ -228,33 +135,27 @@ export declare const baseTestSchema: {
     authHeader: z.ZodDefault<z.ZodString>;
     authScheme: z.ZodDefault<z.ZodString>;
     insecure: z.ZodDefault<z.ZodBoolean>;
-    output: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    output: z.ZodOptional<z.ZodString>;
     outputDir: z.ZodString;
     force: z.ZodDefault<z.ZodBoolean>;
     mockPort: z.ZodDefault<z.ZodNumber>;
     optionalFields: z.ZodDefault<z.ZodBoolean>;
     prompt: z.ZodString;
-    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    language: z.ZodEnum<typeof ProgrammingLanguage>;
     framework: z.ZodString;
     endpointURL: z.ZodString;
-    method: z.ZodDefault<z.ZodUnion<[z.ZodNativeEnum<typeof HttpMethod>, z.ZodLiteral<"">]>>;
+    method: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<typeof HttpMethod>, z.ZodLiteral<"">]>>;
     apiSchema: z.ZodDefault<z.ZodString>;
     pathParams: z.ZodDefault<z.ZodString>;
     queryParams: z.ZodDefault<z.ZodString>;
     formParams: z.ZodDefault<z.ZodString>;
-    requestData: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
-    responseStatusCode: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+    requestData: z.ZodDefault<z.ZodString>;
+    responseStatusCode: z.ZodDefault<z.ZodString>;
 };
 export declare const codeRefactoringSchema: z.ZodObject<{
     codeReuse: z.ZodDefault<z.ZodBoolean>;
     modularizeCode: z.ZodDefault<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    codeReuse: boolean;
-    modularizeCode: boolean;
-}, {
-    codeReuse?: boolean | undefined;
-    modularizeCode?: boolean | undefined;
-}>;
+}, z.core.$strip>;
 /** The `testName` field for a recording-driven generation tool.
  *
  *  Single-sourced because the description is prompt text: it is the only thing

package/build/types/TestTypes.js

@@ -64,14 +64,14 @@ export var RuntimeEnvironment;
     RuntimeEnvironment["DOCKER"] = "docker";
     RuntimeEnvironment["KUBERNETES"] = "k8s";
 })(RuntimeEnvironment || (RuntimeEnvironment = {}));
-export const runtimeEnvironmentSchema = z.nativeEnum(RuntimeEnvironment);
+export const runtimeEnvironmentSchema = z.enum(RuntimeEnvironment);
 export const runtimeEnvironmentInputSchema = z.preprocess((value) => (value === "kubernetes" ? RuntimeEnvironment.KUBERNETES : value), runtimeEnvironmentSchema);
 export function normalizeRuntimeEnvironment(value) {
     return value === "kubernetes" ? RuntimeEnvironment.KUBERNETES : value;
 }
 export const languageSchema = z.object({
     language: z
-        .nativeEnum(ProgrammingLanguage)
+        .enum(ProgrammingLanguage)
         .describe("Programming language for the generated test (default: python). Must be one of: python, typescript, javascript, java"),
     framework: z
         .string()
@@ -217,7 +217,7 @@ export const baseTestSchema = {
         "(e.g., https://demoshop.skyramp.dev/api/v1/products). " +
         "MUST include both the base URL and the endpoint path — never just the base URL alone."),
     method: z
-        .union([z.nativeEnum(HttpMethod), z.literal("")])
+        .union([z.enum(HttpMethod), z.literal("")])
         .default("")
         .describe('HTTP method to use. DEFAULT: Use empty string ("") to test ALL available methods from OpenAPI schema (recommended). Only specify a specific method (GET, POST, PUT, DELETE, etc.) if user explicitly requests testing a single method only.'),
     apiSchema: z

package/build/types/TestbotReport.d.ts

@@ -13,6 +13,26 @@ export declare enum IssueFoundCategory {
     Type = "type",
     Config = "config"
 }
+/** Why a Fail or Skipped testResults row did not pass. Application is the code
+ *  under test (or a test written to prove a defect, failing as intended);
+ *  Environment is the test environment stopping the test before it reached the
+ *  behaviour; TestDefect is the generated test itself being wrong. */
+export declare enum FailureCauseKind {
+    Application = "application",
+    Environment = "environment",
+    TestDefect = "test_defect"
+}
+/** Which test-environment gap stopped a test: the `family` of an Environment
+ *  failureCause, and the `environmentFamily` of a config issuesFound entry. */
+export declare enum EnvironmentFamily {
+    AuthToken = "auth_token",
+    Secret = "secret",
+    DataConnection = "data_connection",
+    AppNotStarted = "app_not_started",
+    Login = "login",
+    ExternalDependency = "external_dependency",
+    RecordingReplay = "recording_replay"
+}
 /**
  * Shape of the JSON report written by skyramp_submit_report and read by testbot
  * for rendering as Markdown. All fields mirror the corresponding Zod schemas in
@@ -104,6 +124,19 @@ export interface TestbotReport {
         endpoint: string;
         status: "Pass" | "Fail" | "Skipped";
         details: string;
+        /** Server-derived: the basename of the `testFilePath` the agent submitted,
+         *  which never reaches the report. The join key to `newTestsCreated` and
+         *  `testMaintenance`: match it against the basename of their `fileName`
+         *  (a `newTestsCreated` row may carry a repository-relative path), plus
+         *  `repository`. */
+        fileName: string;
+        /** Why a Fail or Skipped row did not pass. The submit schema requires it on
+         *  those rows and refuses it on a Pass row; `family` is set exactly when
+         *  `kind` is Environment. Absent in reports from MCP versions predating it. */
+        failureCause?: {
+            kind: FailureCauseKind;
+            family?: EnvironmentFamily;
+        };
         videoPath?: string;
         /** See newTestsCreated[].repository. */
         repository: string;
@@ -158,6 +191,10 @@ export interface TestbotReport {
         sourceFile?: string;
         sourceSymbol?: string;
         sourceLine?: number;
+        /** On a `config` entry that is a test-environment gap, which gap. The submit
+         *  schema refuses it on any other category. Optional: a config entry need
+         *  not be an environment gap, and older MCP versions never set it. */
+        environmentFamily?: EnvironmentFamily;
         /** See newTestsCreated[].repository. */
         repository: string;
     }[];

package/build/types/TestbotReport.js

@@ -8,3 +8,25 @@ export var IssueFoundCategory;
     IssueFoundCategory["Type"] = "type";
     IssueFoundCategory["Config"] = "config";
 })(IssueFoundCategory || (IssueFoundCategory = {}));
+/** Why a Fail or Skipped testResults row did not pass. Application is the code
+ *  under test (or a test written to prove a defect, failing as intended);
+ *  Environment is the test environment stopping the test before it reached the
+ *  behaviour; TestDefect is the generated test itself being wrong. */
+export var FailureCauseKind;
+(function (FailureCauseKind) {
+    FailureCauseKind["Application"] = "application";
+    FailureCauseKind["Environment"] = "environment";
+    FailureCauseKind["TestDefect"] = "test_defect";
+})(FailureCauseKind || (FailureCauseKind = {}));
+/** Which test-environment gap stopped a test: the `family` of an Environment
+ *  failureCause, and the `environmentFamily` of a config issuesFound entry. */
+export var EnvironmentFamily;
+(function (EnvironmentFamily) {
+    EnvironmentFamily["AuthToken"] = "auth_token";
+    EnvironmentFamily["Secret"] = "secret";
+    EnvironmentFamily["DataConnection"] = "data_connection";
+    EnvironmentFamily["AppNotStarted"] = "app_not_started";
+    EnvironmentFamily["Login"] = "login";
+    EnvironmentFamily["ExternalDependency"] = "external_dependency";
+    EnvironmentFamily["RecordingReplay"] = "recording_replay";
+})(EnvironmentFamily || (EnvironmentFamily = {}));

package/build/types/index.d.ts

@@ -2,7 +2,7 @@ export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
 export type { TestbotReport } from "./TestbotReport.js";
-export { IssueFoundCategory } from "./TestbotReport.js";
+export { IssueFoundCategory, FailureCauseKind, EnvironmentFamily, } from "./TestbotReport.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./ReuseOutcome.js";
 export type { ReuseOutcome, ReuseSkippedEntry, ReuseMissedEntry, HelperReuseOutcome, RetrofitOutcome, ChangedHelperEntry, ChangedHelperCaller, OrphanedHelper, } from "./ReuseOutcome.js";
 export type { RelatedRepository, TestbotPromptOptions, } from "./TestbotPromptOptions.js";

package/build/types/index.js

@@ -1,5 +1,5 @@
 export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
-export { IssueFoundCategory } from "./TestbotReport.js";
+export { IssueFoundCategory, FailureCauseKind, EnvironmentFamily, } from "./TestbotReport.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./ReuseOutcome.js";

package/build/utils/docker.d.ts

@@ -1,15 +1,37 @@
+/**
+ * Whether a pull failed because the image has nothing for the requested platform. The
+ * wording depends on the daemon and its image store: a Windows daemon answers a linux-only
+ * image, even a multi-platform one, with "image operating system ... cannot be used on this
+ * platform" (observed on Windows Server 2022, Docker 29.7.2); a manifest list without the
+ * platform gives "no matching manifest"; the containerd image store says "no match for
+ * platform in manifest". Anything else -- the network, a rate limit, a full disk -- is not
+ * this.
+ */
+export declare function isPlatformUnavailableError(err: unknown): boolean;
+/**
+ * Returns the Docker platform string for the current host architecture.
+ * Mirrors the backend's getDockerPlatform() in cmd/libs/init.go.
+ */
+export declare function getDockerPlatform(): string;
 /**
  * Pull a Docker image by name.
  *
- * When `dockerPlatform` is provided, pulls with that exact platform — no
- * fallback logic runs.  Use this for images whose platform is known ahead
- * of time (e.g. executor is amd64-only).
- *
- * When `dockerPlatform` is omitted, uses the host architecture and falls
- * back to linux/amd64 if the arm64 pull fails or the image doesn't land
- * locally (Docker Desktop quirk on Apple Silicon).
+ * `dockerPlatform` defaults to the host architecture. Whether given or
+ * defaulted, a `linux/arm64` pull falls back to `linux/amd64` when the arm64
+ * pull reports no matching manifest or completes without the image landing
+ * locally (Docker Desktop quirk on Apple Silicon). Any other platform is
+ * pulled exactly, with no fallback.
  */
 export declare function pullDockerImage(imageName: string, dockerPlatform?: string): Promise<void>;
+/**
+ * The default daemon's operating system ("windows" or "linux"), or undefined when it
+ * cannot be determined. The startup prefetch pulls each image for this OS; when it is
+ * undefined the executor is pulled as linux/amd64 and the worker for the host's own
+ * architecture (getDockerPlatform). Guessing is acceptable there because the prefetch is
+ * best-effort: a wrong guess costs a download, and the run itself refuses to guess
+ * (resolvePlatform in FleetExecutionService).
+ */
+export declare function dockerDaemonOsType(): Promise<string | undefined>;
 /**
  * Check if a Docker image exists locally for the given reference (repo:tag or digest).
  * Uses image inspect (daemon name resolution), not listImages tag scanning.

package/build/utils/docker.js

@@ -26,11 +26,26 @@ function isManifestMismatchError(err) {
     const msg = err?.message ?? "";
     return msg.includes("no matching manifest");
 }
+/**
+ * Whether a pull failed because the image has nothing for the requested platform. The
+ * wording depends on the daemon and its image store: a Windows daemon answers a linux-only
+ * image, even a multi-platform one, with "image operating system ... cannot be used on this
+ * platform" (observed on Windows Server 2022, Docker 29.7.2); a manifest list without the
+ * platform gives "no matching manifest"; the containerd image store says "no match for
+ * platform in manifest". Anything else -- the network, a rate limit, a full disk -- is not
+ * this.
+ */
+export function isPlatformUnavailableError(err) {
+    const msg = err?.message ?? "";
+    return (msg.includes("no matching manifest") ||
+        msg.includes("cannot be used on this platform") ||
+        msg.includes("no match for platform in manifest"));
+}
 /**
  * Returns the Docker platform string for the current host architecture.
  * Mirrors the backend's getDockerPlatform() in cmd/libs/init.go.
  */
-function getDockerPlatform() {
+export function getDockerPlatform() {
     return process.arch === "arm64" ? "linux/arm64" : "linux/amd64";
 }
 async function doPull(docker, imageName, platform) {
@@ -40,14 +55,27 @@ async function doPull(docker, imageName, platform) {
                 return reject(err);
             if (!stream)
                 return reject(new Error("No stream received from docker pull"));
+            // A pull can fail INSIDE the progress stream: followProgress still finishes
+            // without an error object, and the failure appears only as an `error` field on
+            // one of the messages. Without reading them, a pull that stored nothing is
+            // logged as a success. The Go side guards the same thing (`message.Error` in
+            // RunSkyrampWorker).
+            let streamError;
             docker.modem.followProgress(stream, (err) => {
                 if (err)
                     return reject(err);
+                if (streamError) {
+                    return reject(new Error(`docker pull ${imageName} (${platform}) failed: ${streamError}`));
+                }
                 logger.info("Docker image pulled successfully", {
                     image: imageName,
                     platform,
                 });
                 resolve();
+            }, (msg) => {
+                if (msg?.error && streamError === undefined) {
+                    streamError = msg.errorDetail?.message ?? msg.error;
+                }
             });
         });
     });
@@ -55,39 +83,67 @@ async function doPull(docker, imageName, platform) {
 /**
  * Pull a Docker image by name.
  *
- * When `dockerPlatform` is provided, pulls with that exact platform — no
- * fallback logic runs.  Use this for images whose platform is known ahead
- * of time (e.g. executor is amd64-only).
- *
- * When `dockerPlatform` is omitted, uses the host architecture and falls
- * back to linux/amd64 if the arm64 pull fails or the image doesn't land
- * locally (Docker Desktop quirk on Apple Silicon).
+ * `dockerPlatform` defaults to the host architecture. Whether given or
+ * defaulted, a `linux/arm64` pull falls back to `linux/amd64` when the arm64
+ * pull reports no matching manifest or completes without the image landing
+ * locally (Docker Desktop quirk on Apple Silicon). Any other platform is
+ * pulled exactly, with no fallback.
  */
 export async function pullDockerImage(imageName, dockerPlatform) {
     const client = new Dockerode();
-    if (dockerPlatform) {
-        await doPull(client, imageName, dockerPlatform);
-        return;
+    const platform = dockerPlatform ?? getDockerPlatform();
+    // Docker Desktop on Apple Silicon serves amd64-only images under emulation, but an arm64
+    // pull of one either reports no matching manifest or completes and stores nothing. Those
+    // are the same rule, not two special cases: try these platforms in order until one
+    // actually lands.
+    const candidates = platform === "linux/arm64" ? [platform, "linux/amd64"] : [platform];
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = candidates[i];
+        const next = candidates[i + 1];
+        try {
+            await doPull(client, imageName, candidate);
+        }
+        catch (err) {
+            // A manifest mismatch is the one failure another platform can answer.
+            if (next === undefined || !isManifestMismatchError(err))
+                throw err;
+            logger.info("pull failed, retrying on the next platform", {
+                image: imageName,
+                failed: candidate,
+                next,
+            });
+            continue;
+        }
+        // A pull can end its stream cleanly and store nothing, so success is the image being
+        // present -- not the pull returning.
+        if (await dockerImageExistsLocally(imageName))
+            return;
+        if (next === undefined)
+            break;
+        logger.info("pull completed but the image is absent, retrying on the next platform", {
+            image: imageName,
+            failed: candidate,
+            next,
+        });
     }
-    const platform = getDockerPlatform();
+    throw new Error(`docker pull ${imageName} (${candidates.join(", ")}) reported success but the image is not present locally`);
+}
+/**
+ * The default daemon's operating system ("windows" or "linux"), or undefined when it
+ * cannot be determined. The startup prefetch pulls each image for this OS; when it is
+ * undefined the executor is pulled as linux/amd64 and the worker for the host's own
+ * architecture (getDockerPlatform). Guessing is acceptable there because the prefetch is
+ * best-effort: a wrong guess costs a download, and the run itself refuses to guess
+ * (resolvePlatform in FleetExecutionService).
+ */
+export async function dockerDaemonOsType() {
     try {
-        await doPull(client, imageName, platform);
+        const info = (await new Dockerode().info());
+        return info?.OSType;
     }
     catch (err) {
-        if (platform === "linux/arm64" && isManifestMismatchError(err)) {
-            logger.info("arm64 pull failed, retrying with linux/amd64 (emulation on Apple Silicon)", { image: imageName });
-            await doPull(client, imageName, "linux/amd64");
-            return;
-        }
-        throw err;
-    }
-    // On Docker Desktop/Mac, pulling an amd64-only image with linux/arm64 can
-    // complete the stream without error yet not store the image locally.
-    // Verify it actually landed, and fall back to amd64 if not.
-    if (platform === "linux/arm64" &&
-        !(await dockerImageExistsLocally(imageName))) {
-        logger.info("arm64 pull completed but image not found locally, retrying with linux/amd64", { image: imageName });
-        await doPull(client, imageName, "linux/amd64");
+        logger.warning("Could not determine the Docker daemon OS", { error: err });
+        return undefined;
     }
 }
 /**