@moldesk/runtime 0.0.5 → 0.0.6

package/dist/cloud/runpod.test.js

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+import { RunpodProvider, RUNPOD_USER_AGENT } from "./runpod.js";
+const SECRET = "rpa_TESTSECRET0123456789";
+function json(status, body, headers = {}) {
+    return new Response(body === undefined ? null : JSON.stringify(body), { status, headers });
+}
+function setup(responses) {
+    const calls = [];
+    const sleeps = [];
+    const queue = [...responses];
+    const fakeFetch = (async (url, init) => {
+        const call = {
+            method: init.method ?? "GET",
+            url: String(url),
+            headers: init.headers,
+            body: init.body ? JSON.parse(String(init.body)) : undefined,
+        };
+        calls.push(call);
+        const next = queue.shift();
+        if (!next)
+            throw new Error("unexpected extra request");
+        if (next instanceof Error)
+            throw next;
+        return typeof next === "function" ? next(call) : next;
+    });
+    const provider = new RunpodProvider({
+        getApiKey: async () => SECRET,
+        fetch: fakeFetch,
+        sleep: async (ms) => {
+            sleeps.push(ms);
+        },
+        now: () => new Date("2026-10-13T12:00:00Z"),
+    });
+    return { provider, calls, sleeps };
+}
+const podBody = { id: "pod1", name: "n", status: "RUNNING", dataCenterId: "EU-RO-1", cost: 0.57, createdAt: "2026-10-13T11:55:45Z" };
+describe("RunpodProvider", () => {
+    it("sends bearer auth and an explicit User-Agent, and validates credentials read-only", async () => {
+        const { provider, calls } = setup([json(200, { pods: [] })]);
+        expect(await provider.validateCredentials()).toEqual({ ok: true, checkedAt: "2026-10-13T12:00:00.000Z" });
+        expect(calls[0].method).toBe("GET");
+        expect(calls[0].url).toBe("https://api.runpod.io/v2/pods");
+        expect(calls[0].headers.Authorization).toBe(`Bearer ${SECRET}`);
+        expect(calls[0].headers["User-Agent"]).toBe(RUNPOD_USER_AGENT);
+    });
+    it("normalizes the catalog", async () => {
+        const { provider } = setup([
+            json(200, {
+                gpus: [
+                    {
+                        id: "NVIDIA A40",
+                        name: "A40",
+                        memory: 48,
+                        price: { secure: 0.59 },
+                        availability: "LOW",
+                        dataCenters: [{ id: "EU-SE-1", availability: "LOW" }],
+                        cudaVersions: [{ version: "12.8", available: true }, { version: "13.0", available: false }],
+                    },
+                ],
+            }),
+            json(200, { cpus: [{ id: "cpu3c", name: "Compute", price: { securePerVcpu: 0.03 }, ramGbPerVcpu: 2, vcpu: { min: 2, max: 32 } }] }),
+            json(200, { dataCenters: [{ id: "AP-JP-1", region: "ASIA", networkVolumeTypes: ["STANDARD"] }, { id: "X", region: "R" }] }),
+        ]);
+        const catalog = await provider.getCatalog();
+        expect(catalog.gpus[0]).toMatchObject({ id: "NVIDIA A40", memoryGb: 48, priceUsdPerHour: 0.59, availability: "LOW", cudaVersions: ["12.8"] });
+        expect(catalog.cpus[0]).toMatchObject({ id: "cpu3c", priceUsdPerVcpuHour: 0.03, minVcpu: 2, maxVcpu: 32 });
+        expect(catalog.dataCenters.map((dc) => [dc.id, dc.networkVolumeTypes])).toEqual([["AP-JP-1", ["STANDARD"]], ["X", []]]);
+    });
+    it("creates a GPU pod with a volume mount using the verified request shape", async () => {
+        const { provider, calls } = setup([json(201, podBody)]);
+        const pod = await provider.createPod({
+            name: "moldesk-run1-gpu",
+            image: "img",
+            containerDiskGb: 20,
+            dataCenterId: "EU-RO-1",
+            gpu: { id: "NVIDIA A40", count: 1 },
+            volume: { id: "vol1", mountPath: "/workspace" },
+            ports: ["8000/http"],
+            entrypoint: ["/bin/bash", "-c"],
+            cmd: ["run"],
+        });
+        expect(pod).toMatchObject({ id: "pod1", status: "RUNNING", costUsdPerHour: 0.57 });
+        expect(calls[0].body).toEqual({
+            name: "moldesk-run1-gpu",
+            image: "img",
+            disk: 20,
+            dataCenterIds: ["EU-RO-1"],
+            gpu: { id: "NVIDIA A40", count: 1 },
+            mounts: { network: [{ volumeId: "vol1", path: "/workspace" }] },
+            ports: ["8000/http"],
+            args: JSON.stringify({ entrypoint: ["/bin/bash", "-c"], cmd: ["run"] }),
+        });
+    });
+    it("rejects a pod request that is neither or both of gpu and cpu before any request", async () => {
+        const { provider, calls } = setup([]);
+        await expect(provider.createPod({ name: "n", image: "i", containerDiskGb: 1, dataCenterId: "d" })).rejects.toMatchObject({ code: "CLOUD_REQUEST_REJECTED" });
+        expect(calls).toHaveLength(0);
+    });
+    it("maps capacity failure to CLOUD_CAPACITY_UNAVAILABLE without retrying a create", async () => {
+        const { provider, calls } = setup([json(400, { detail: "There are no longer any instances available with the requested specifications.", status: 400 })]);
+        await expect(provider.createPod({ name: "n", image: "i", containerDiskGb: 1, dataCenterId: "d", gpu: { id: "g", count: 1 } })).rejects.toMatchObject({ code: "CLOUD_CAPACITY_UNAVAILABLE" });
+        expect(calls).toHaveLength(1);
+    });
+    it("treats a 5xx or network failure on create as ambiguous and never retries it", async () => {
+        const first = setup([json(503, { detail: "boom" })]);
+        await expect(first.provider.createVolume({ name: "v", sizeGb: 10, dataCenterId: "d" })).rejects.toMatchObject({ code: "CLOUD_AMBIGUOUS_CREATE" });
+        expect(first.calls).toHaveLength(1);
+        const second = setup([new Error("socket hang up")]);
+        await expect(second.provider.createPod({ name: "n", image: "i", containerDiskGb: 1, dataCenterId: "d", cpu: { id: "cpu3c", vcpuCount: 2 } })).rejects.toMatchObject({ code: "CLOUD_AMBIGUOUS_CREATE" });
+        expect(second.calls).toHaveLength(1);
+    });
+    it("treats terminate and delete of an absent resource as success", async () => {
+        const { provider, calls } = setup([json(204, undefined), json(404, { detail: "pod not found" }), json(404, { detail: "nope" })]);
+        expect(await provider.terminatePod("p")).toEqual({ id: "p", alreadyAbsent: false });
+        expect(calls[0].body).toEqual({ action: "terminate" });
+        expect(await provider.terminatePod("p")).toEqual({ id: "p", alreadyAbsent: true });
+        expect(await provider.deleteVolume("v")).toEqual({ id: "v", alreadyAbsent: true });
+    });
+    it("returns null for a missing pod or volume", async () => {
+        const { provider } = setup([json(404, {}), json(404, {})]);
+        expect(await provider.getPod("x")).toBeNull();
+        expect(await provider.getVolume("x")).toBeNull();
+    });
+    it("retries idempotent calls on 429 honoring Retry-After, then succeeds", async () => {
+        const { provider, sleeps } = setup([json(429, { detail: "slow down" }, { "retry-after": "2" }), json(200, { pods: [podBody] })]);
+        expect(await provider.listPods()).toHaveLength(1);
+        expect(sleeps).toEqual([2000]);
+    });
+    it("gives up with CLOUD_RATE_LIMITED after bounded retries", async () => {
+        const { provider, calls } = setup([json(429, {}), json(429, {}), json(429, {})]);
+        await expect(provider.listVolumes()).rejects.toMatchObject({ code: "CLOUD_RATE_LIMITED" });
+        expect(calls).toHaveLength(3);
+    });
+    it("maps auth, payment and permission failures and never leaks the key", async () => {
+        for (const [status, code] of [[401, "CLOUD_AUTH_FAILED"], [402, "CLOUD_PAYMENT_REQUIRED"], [403, "CLOUD_FORBIDDEN"]]) {
+            const { provider } = setup([json(status, { detail: "denied" })]);
+            const error = await provider.listPods().then(() => undefined, (e) => e);
+            expect(error?.code).toBe(code);
+            expect(JSON.stringify({ message: error?.message, details: error?.details })).not.toContain(SECRET);
+        }
+    });
+    it("flags malformed responses instead of returning partial data", async () => {
+        const { provider } = setup([json(200, { pods: [{ id: "p", status: "WEIRD" }] })]);
+        await expect(provider.listPods()).rejects.toMatchObject({ code: "CLOUD_BAD_RESPONSE" });
+    });
+});

package/dist/cloud/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Provider-neutral contracts for rented compute. Everything here is JSON-serializable so it can be
+ * journaled and reconstructed after a client restart. This is separate from the local
+ * `RuntimeProvider`, which spawns processes on this machine.
+ */
+export type CloudPodStatus = "PROVISIONING" | "STARTING" | "RUNNING" | "EXITED" | "ERROR" | "TERMINATED";
+export interface CloudGpuType {
+    id: string;
+    name: string;
+    memoryGb: number;
+    /** Secure-cloud on-demand price, USD per GPU-hour. */
+    priceUsdPerHour: number;
+    /** Availability by datacenter at retrieval time; capacity is never reserved. */
+    availability: "NONE" | "LOW" | "MEDIUM" | "HIGH" | "UNKNOWN";
+    dataCenters: Array<{
+        id: string;
+        availability: string;
+    }>;
+    cudaVersions: string[];
+}
+export interface CloudCpuType {
+    id: string;
+    name: string;
+    priceUsdPerVcpuHour: number;
+    ramGbPerVcpu: number;
+    minVcpu: number;
+    maxVcpu: number;
+}
+export interface CloudDataCenter {
+    id: string;
+    region: string;
+    /** Empty means network volumes are unsupported there. */
+    networkVolumeTypes: string[];
+}
+/**
+ * Storage rates, only when the provider publishes them. Runpod's catalog API does not expose disk or
+ * network-volume prices (only historical billing), so its provider leaves this undefined and quotes
+ * state those costs as unknown instead of guessing.
+ */
+export interface CloudStorageRates {
+    containerDiskUsdPerGbMonth?: number;
+    networkVolumeUsdPerGbMonth?: number;
+}
+export interface CloudCatalog {
+    retrievedAt: string;
+    storageRates?: CloudStorageRates;
+    gpus: CloudGpuType[];
+    cpus: CloudCpuType[];
+    dataCenters: CloudDataCenter[];
+}
+export interface CreatePodRequest {
+    name: string;
+    image: string;
+    containerDiskGb: number;
+    dataCenterId: string;
+    gpu?: {
+        id: string;
+        count: number;
+    };
+    cpu?: {
+        id: string;
+        vcpuCount: number;
+    };
+    volume?: {
+        id: string;
+        mountPath: string;
+    };
+    /** `port/protocol`, e.g. `8000/http`. */
+    ports?: string[];
+    env?: Record<string, string>;
+    entrypoint?: string[];
+    cmd?: string[];
+}
+export interface CloudPod {
+    id: string;
+    name: string;
+    status: CloudPodStatus;
+    dataCenterId: string | null;
+    /** Provider-reported hourly cost in USD while running. */
+    costUsdPerHour: number | null;
+    createdAt: string | null;
+}
+export interface CreateVolumeRequest {
+    name: string;
+    sizeGb: number;
+    dataCenterId: string;
+}
+export interface CloudVolume {
+    id: string;
+    name: string;
+    sizeGb: number;
+    dataCenterId: string;
+    type: string | null;
+}
+export interface CloudAccountCheck {
+    ok: true;
+    checkedAt: string;
+}
+/** Result of an idempotent delete: absence counts as success. */
+export interface CloudDeleteResult {
+    id: string;
+    alreadyAbsent: boolean;
+}
+export interface CloudProvider {
+    readonly name: string;
+    /** Minimum read-only call that proves the credential works. */
+    validateCredentials(): Promise<CloudAccountCheck>;
+    getCatalog(): Promise<CloudCatalog>;
+    createPod(request: CreatePodRequest): Promise<CloudPod>;
+    getPod(id: string): Promise<CloudPod | null>;
+    listPods(): Promise<CloudPod[]>;
+    terminatePod(id: string): Promise<CloudDeleteResult>;
+    createVolume(request: CreateVolumeRequest): Promise<CloudVolume>;
+    getVolume(id: string): Promise<CloudVolume | null>;
+    listVolumes(): Promise<CloudVolume[]>;
+    deleteVolume(id: string): Promise<CloudDeleteResult>;
+}
+export type CloudErrorCode = "CLOUD_AUTH_FAILED" | "CLOUD_FORBIDDEN" | "CLOUD_PAYMENT_REQUIRED" | "CLOUD_RATE_LIMITED" | "CLOUD_CAPACITY_UNAVAILABLE" | "CLOUD_REQUEST_REJECTED" | "CLOUD_BAD_RESPONSE" | "CLOUD_UNAVAILABLE"
+/** A create request may or may not have taken effect; discover candidates before retrying. */
+ | "CLOUD_AMBIGUOUS_CREATE";
+export type CloudResourceRoleName = "cpu" | "gpu" | "volume";

package/dist/cloud/types.js

@@ -0,0 +1,6 @@
+/**
+ * Provider-neutral contracts for rented compute. Everything here is JSON-serializable so it can be
+ * journaled and reconstructed after a client restart. This is separate from the local
+ * `RuntimeProvider`, which spawns processes on this machine.
+ */
+export {};

package/dist/cloud/worker-client.d.ts

@@ -0,0 +1,62 @@
+import type { ArtifactInventory, JobInputFile, JobSnapshot, WireJob } from "./execution.js";
+export declare const WORKER_USER_AGENT = "moldesk-worker-client/1";
+export interface WorkerClientOptions {
+    /** HTTPS base URL of the worker (the provider proxy), no trailing slash required. */
+    endpoint: string;
+    /** Per-job bearer token. Never logged, persisted in the journal or sent anywhere else. */
+    token: string;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    requestTimeoutMs?: number;
+    /** Test-only: permit plain http (loopback). Production endpoints must be https. */
+    allowInsecureLoopback?: boolean;
+    /** A stream that delivers no bytes for this long is aborted (and retried by range). Default 60 s. */
+    idleTimeoutMs?: number;
+    /** Cancels every in-flight request, including bodies still streaming. */
+    signal?: AbortSignal;
+}
+/** Rejects absolute paths, traversal, backslashes, empty/`.` segments and control characters. */
+export declare function isSafeRelativePath(value: string): boolean;
+export declare class WorkerClient {
+    private readonly options;
+    private readonly fetchFn;
+    private readonly sleep;
+    private readonly base;
+    private readonly timeoutMs;
+    private readonly idleMs;
+    constructor(options: WorkerClientOptions);
+    /** Timeout + cancellation scope covering headers AND body streaming; the timer is only released by the caller. */
+    private guard;
+    private failure;
+    private requestInit;
+    /** Whole-request deadline: the body is read inside the same timeout/cancellation scope as the headers. */
+    private requestText;
+    private parse;
+    health(): Promise<{
+        contract: number;
+        workerVersion: string;
+    }>;
+    /** Polls health until ready. 404/connection failures (proxy not routed yet, container booting) are expected. */
+    waitUntilReady(options: {
+        timeoutMs: number;
+        intervalMs?: number;
+        abortIf?: () => Promise<string | undefined>;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Streams one input file, verifying size and SHA-256 on both ends. */
+    uploadInput(runId: string, file: Pick<JobInputFile, "relativePath" | "sha256" | "sizeBytes" | "sourcePath">): Promise<void>;
+    start(job: WireJob): Promise<void>;
+    status(runId: string, after?: number): Promise<JobSnapshot>;
+    cancel(runId: string): Promise<void>;
+    inventory(runId: string, signal?: AbortSignal): Promise<ArtifactInventory>;
+    /**
+     * Downloads every inventory file into a staging directory, verifies size and SHA-256 per file,
+     * then promotes them into `localOutputDir`. Nothing is promoted unless everything verified, and a
+     * partial file is resumed by byte range then re-verified in full. Never reruns inference.
+     */
+    collect(runId: string, localOutputDir: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArtifactInventory>;
+    private downloadVerified;
+}
+export declare function validateInventory(inventory: ArtifactInventory): void;

package/dist/cloud/worker-client.js

@@ -0,0 +1,306 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { MoldeskError } from "../providers.js";
+import { EXECUTION_CONTRACT_VERSION } from "./execution.js";
+export const WORKER_USER_AGENT = "moldesk-worker-client/1";
+const MAX_JSON_BYTES = 8 * 1024 * 1024;
+function workerError(code, message, remediation, details, cause) {
+    return new MoldeskError({ code, message, remediation, details, cause });
+}
+/** Rejects absolute paths, traversal, backslashes, empty/`.` segments and control characters. */
+export function isSafeRelativePath(value) {
+    if (!value || value.length > 1024 || value.includes("\\") || value.startsWith("/") || /^[A-Za-z]:/.test(value) || /[\u0000-\u001f]/.test(value))
+        return false;
+    return value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+export class WorkerClient {
+    options;
+    fetchFn;
+    sleep;
+    base;
+    timeoutMs;
+    idleMs;
+    constructor(options) {
+        this.options = options;
+        const url = new URL(options.endpoint);
+        const loopback = url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "[::1]";
+        if (url.protocol !== "https:" && !(options.allowInsecureLoopback && loopback && url.protocol === "http:")) {
+            throw workerError("CLOUD_WORKER_INSECURE_ENDPOINT", "The worker endpoint must use HTTPS.", "There is no plaintext fallback; use the provider's HTTPS proxy.");
+        }
+        this.base = options.endpoint.replace(/\/+$/, "");
+        this.fetchFn = options.fetch ?? fetch;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.timeoutMs = options.requestTimeoutMs ?? 60_000;
+        this.idleMs = options.idleTimeoutMs ?? 60_000;
+    }
+    /** Timeout + cancellation scope covering headers AND body streaming; the timer is only released by the caller. */
+    guard(ms, external) {
+        const controller = new AbortController();
+        const source = external ?? this.options.signal;
+        let timer;
+        let timedOut = false;
+        const onAbort = () => controller.abort();
+        if (source?.aborted)
+            controller.abort();
+        else
+            source?.addEventListener("abort", onAbort, { once: true });
+        const arm = (next) => {
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, next);
+        };
+        arm(ms);
+        return {
+            signal: controller.signal,
+            arm,
+            release: () => {
+                clearTimeout(timer);
+                source?.removeEventListener("abort", onAbort);
+            },
+            cancelled: () => source?.aborted === true,
+            timedOut: () => timedOut,
+        };
+    }
+    failure(guard, route, cause) {
+        if (guard.cancelled())
+            return workerError("RUN_CANCELLED", "Cancelled.", "None.", { route }, cause);
+        if (guard.timedOut())
+            return workerError("CLOUD_WORKER_TIMEOUT", "The worker did not respond in time.", "Retry; the machine may be overloaded or the connection stalled.", { route }, cause);
+        return workerError("CLOUD_WORKER_UNREACHABLE", "Could not reach the worker.", "Check the connection; the machine may still be booting.", { route }, cause);
+    }
+    requestInit(method, init, signal) {
+        return {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.options.token}`,
+                "User-Agent": WORKER_USER_AGENT,
+                ...(init.json !== undefined ? { "Content-Type": "application/json" } : {}),
+                ...init.headers,
+            },
+            ...(init.json !== undefined ? { body: JSON.stringify(init.json) } : init.body !== undefined ? { body: init.body } : {}),
+            ...(init.duplex ? { duplex: "half" } : {}),
+            signal,
+        };
+    }
+    /** Whole-request deadline: the body is read inside the same timeout/cancellation scope as the headers. */
+    async requestText(method, route, init = {}) {
+        const guard = this.guard(init.timeoutMs ?? this.timeoutMs, init.signal);
+        try {
+            const response = await this.fetchFn(`${this.base}${route}`, this.requestInit(method, init, guard.signal));
+            const text = await response.text();
+            return { status: response.status, ok: response.ok, text };
+        }
+        catch (error) {
+            throw this.failure(guard, route, error);
+        }
+        finally {
+            guard.release();
+        }
+    }
+    parse(result, route) {
+        if (result.status === 401 || result.status === 403) {
+            throw workerError("CLOUD_WORKER_AUTH_FAILED", "The worker rejected the job token.", "The worker belongs to a different job; do not retry with another token.", { route, status: result.status });
+        }
+        if (result.text.length > MAX_JSON_BYTES)
+            throw workerError("CLOUD_BAD_RESPONSE", "Worker response too large.", "Retry.", { route });
+        if (!result.ok) {
+            let detail;
+            try {
+                detail = JSON.parse(result.text).message;
+            }
+            catch {
+                detail = result.text.slice(0, 200);
+            }
+            throw workerError("CLOUD_WORKER_ERROR", `Worker error ${result.status}${detail ? `: ${detail}` : ""}.`, "Retry or inspect the run logs.", { route, status: result.status });
+        }
+        try {
+            return JSON.parse(result.text);
+        }
+        catch (error) {
+            throw workerError("CLOUD_BAD_RESPONSE", "The worker returned malformed JSON.", "Retry.", { route }, error);
+        }
+    }
+    async health() {
+        const result = this.parse(await this.requestText("GET", "/v1/health", { timeoutMs: 15_000 }), "/v1/health");
+        if (result.contract !== EXECUTION_CONTRACT_VERSION) {
+            throw workerError("CLOUD_WORKER_VERSION_MISMATCH", `Worker speaks contract ${result.contract}; this client speaks ${EXECUTION_CONTRACT_VERSION}.`, "Use matching MoleculeDesk versions.");
+        }
+        return result;
+    }
+    /** Polls health until ready. 404/connection failures (proxy not routed yet, container booting) are expected. */
+    async waitUntilReady(options) {
+        const started = Date.now();
+        let last;
+        while (Date.now() - started < options.timeoutMs) {
+            if (options.signal?.aborted)
+                throw workerError("RUN_CANCELLED", "Cancelled while waiting for the worker.", "None.");
+            try {
+                await this.health();
+                return;
+            }
+            catch (error) {
+                last = error;
+                if (error instanceof MoldeskError && (error.code === "CLOUD_WORKER_AUTH_FAILED" || error.code === "CLOUD_WORKER_VERSION_MISMATCH"))
+                    throw error;
+            }
+            const fatal = await options.abortIf?.();
+            if (fatal)
+                throw workerError("CLOUD_WORKER_BOOT_FAILED", fatal, "Inspect the Pod; it will be terminated.");
+            await this.sleep(options.intervalMs ?? 5000);
+        }
+        throw workerError("CLOUD_WORKER_BOOT_TIMEOUT", `The worker did not become ready within ${Math.round(options.timeoutMs / 1000)}s.`, "Cold image pulls can be slow; retry, or check provider status.", undefined, last);
+    }
+    /** Streams one input file, verifying size and SHA-256 on both ends. */
+    async uploadInput(runId, file) {
+        if (!isSafeRelativePath(file.relativePath))
+            throw workerError("CLOUD_UNSAFE_PATH", `Unsafe input path ${JSON.stringify(file.relativePath)}.`, "Use a simple file name.");
+        const stat = fs.statSync(file.sourcePath);
+        if (stat.size !== file.sizeBytes)
+            throw workerError("CLOUD_INPUT_CHANGED", "The input changed size after it was quoted.", "Request a new quote.");
+        const route = `/v1/jobs/${encodeURIComponent(runId)}/input/${file.relativePath.split("/").map(encodeURIComponent).join("/")}`;
+        const body = Readable.toWeb(fs.createReadStream(file.sourcePath));
+        const response = await this.requestText("PUT", route, {
+            body,
+            duplex: true,
+            timeoutMs: 10 * 60_000,
+            headers: { "Content-Type": "application/octet-stream", "Content-Length": String(file.sizeBytes), "X-Moldesk-Sha256": file.sha256 },
+        });
+        this.parse(response, route);
+    }
+    async start(job) {
+        const route = `/v1/jobs/${encodeURIComponent(job.runId)}/start`;
+        this.parse(await this.requestText("POST", route, { json: job }), route);
+    }
+    async status(runId, after = 0) {
+        const route = `/v1/jobs/${encodeURIComponent(runId)}/status?after=${after}`;
+        return this.parse(await this.requestText("GET", route, { timeoutMs: 20_000 }), route);
+    }
+    async cancel(runId) {
+        const route = `/v1/jobs/${encodeURIComponent(runId)}/cancel`;
+        this.parse(await this.requestText("POST", route, { timeoutMs: 20_000 }), route);
+    }
+    async inventory(runId, signal) {
+        const route = `/v1/jobs/${encodeURIComponent(runId)}/inventory`;
+        const inventory = this.parse(await this.requestText("GET", route, { signal }), route);
+        validateInventory(inventory);
+        return inventory;
+    }
+    /**
+     * Downloads every inventory file into a staging directory, verifies size and SHA-256 per file,
+     * then promotes them into `localOutputDir`. Nothing is promoted unless everything verified, and a
+     * partial file is resumed by byte range then re-verified in full. Never reruns inference.
+     */
+    async collect(runId, localOutputDir, options = {}) {
+        const inventory = await this.inventory(runId, options.signal);
+        const staging = path.join(localOutputDir, `.moldesk-staging-${randomUUID()}`);
+        fs.mkdirSync(staging, { recursive: true });
+        try {
+            for (const file of inventory.files) {
+                const target = path.join(staging, ...file.path.split("/"));
+                fs.mkdirSync(path.dirname(target), { recursive: true });
+                await this.downloadVerified(runId, file, target, options.signal);
+            }
+            for (const file of inventory.files) {
+                const finalPath = path.join(localOutputDir, ...file.path.split("/"));
+                if (fs.existsSync(finalPath)) {
+                    throw workerError("CLOUD_OUTPUT_COLLISION", `Output ${file.path} already exists locally.`, "Use an empty run output directory.");
+                }
+                fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+                fs.renameSync(path.join(staging, ...file.path.split("/")), finalPath);
+            }
+            return inventory;
+        }
+        finally {
+            fs.rmSync(staging, { recursive: true, force: true });
+        }
+    }
+    async downloadVerified(runId, file, target, signal) {
+        const route = `/v1/jobs/${encodeURIComponent(runId)}/files/${file.path.split("/").map(encodeURIComponent).join("/")}`;
+        for (let attempt = 1; attempt <= 3; attempt += 1) {
+            const have = fs.existsSync(target) ? fs.statSync(target).size : 0;
+            const resume = have > 0 && have < file.sizeBytes;
+            if (!resume && have > 0)
+                fs.rmSync(target, { force: true });
+            // One scope per attempt: it covers connecting, headers and every body chunk, and is re-armed on
+            // each chunk so only a genuinely stalled stream times out. Cancellation aborts it immediately.
+            const guard = this.guard(this.idleMs, signal);
+            let response;
+            try {
+                response = await this.fetchFn(`${this.base}${route}`, this.requestInit("GET", { headers: resume ? { Range: `bytes=${have}-` } : {} }, guard.signal));
+            }
+            catch (error) {
+                guard.release();
+                const failure = this.failure(guard, route, error);
+                if (failure.code === "RUN_CANCELLED" || attempt === 3)
+                    throw failure.code === "RUN_CANCELLED" ? failure : workerError("CLOUD_TRANSFER_FAILED", `Could not download ${file.path}.`, "Retry recovery before the lifetime limit.", { path: file.path }, error);
+                continue;
+            }
+            if (response.status === 401 || response.status === 403) {
+                guard.release();
+                throw workerError("CLOUD_WORKER_AUTH_FAILED", "The worker rejected the job token.", "Do not retry.");
+            }
+            const okStatus = resume ? response.status === 206 : response.status === 200;
+            if (!okStatus || !response.body) {
+                guard.release();
+                if (resume && response.status === 200)
+                    fs.rmSync(target, { force: true }); // server ignored Range: restart this file only
+                if (attempt === 3)
+                    throw workerError("CLOUD_TRANSFER_FAILED", `Could not download ${file.path} (status ${response.status}).`, "Retry recovery before the lifetime limit.");
+                continue;
+            }
+            const sink = fs.createWriteStream(target, { flags: resume ? "a" : "w" });
+            const closeSink = () => new Promise((resolve, reject) => sink.end((error) => (error ? reject(error) : resolve())));
+            try {
+                for await (const chunk of Readable.fromWeb(response.body)) {
+                    guard.arm(this.idleMs);
+                    if (!sink.write(chunk))
+                        await new Promise((resolve) => sink.once("drain", resolve));
+                }
+                await closeSink();
+            }
+            catch (error) {
+                // Flush what arrived so the next attempt can resume from it by byte range.
+                await closeSink().catch(() => undefined);
+                const cancelled = guard.cancelled();
+                const stalled = guard.timedOut();
+                guard.release();
+                if (cancelled)
+                    throw workerError("RUN_CANCELLED", "Cancelled during download.", "None.", { path: file.path }, error);
+                if (attempt === 3) {
+                    throw workerError("CLOUD_TRANSFER_FAILED", `The download of ${file.path} was ${stalled ? "stalled" : "interrupted"}.`, "Retry recovery before the lifetime limit.", { path: file.path }, error);
+                }
+                continue;
+            }
+            guard.release();
+            // Verify the complete file regardless of how it was assembled.
+            const size = fs.statSync(target).size;
+            const hash = createHash("sha256");
+            for await (const chunk of fs.createReadStream(target))
+                hash.update(chunk);
+            if (size === file.sizeBytes && hash.digest("hex") === file.sha256.toLowerCase())
+                return;
+            fs.rmSync(target, { force: true });
+            if (attempt === 3)
+                throw workerError("CLOUD_TRANSFER_CORRUPT", `${file.path} failed size/SHA-256 verification.`, "The result was corrupted in transit; it is not accepted.", { path: file.path });
+        }
+    }
+}
+export function validateInventory(inventory) {
+    if (inventory?.version !== EXECUTION_CONTRACT_VERSION || !Array.isArray(inventory.files)) {
+        throw workerError("CLOUD_BAD_RESPONSE", "The worker returned an invalid inventory.", "Retry.");
+    }
+    const seen = new Set();
+    for (const file of inventory.files) {
+        const key = file?.path?.toLowerCase();
+        if (!file || !isSafeRelativePath(file.path) || !Number.isInteger(file.sizeBytes) || file.sizeBytes < 0 || !/^[0-9a-f]{64}$/i.test(file.sha256)) {
+            throw workerError("CLOUD_UNSAFE_PATH", `The inventory contains an unsafe or malformed entry: ${JSON.stringify(file?.path)}.`, "The result is rejected; nothing was written locally.");
+        }
+        if (seen.has(key))
+            throw workerError("CLOUD_UNSAFE_PATH", `The inventory lists ${file.path} more than once (case-insensitive).`, "The result is rejected.");
+        seen.add(key);
+    }
+}

package/dist/index.d.ts

@@ -19,6 +19,17 @@ export type { ExecuteRequest, ExecutionResult, MoldeskErrorData, PrepareRuntimeR
 export { MoldeskError } from "./providers.js";
 export { PythonRuntimeProvider } from "./providers/python.js";
 export { redactEnv } from "./redact.js";
+export { RunpodProvider, RUNPOD_API_BASE, RUNPOD_USER_AGENT } from "./cloud/runpod.js";
+export { CredentialStore, KEYRING_SERVICE, DEFAULT_ACCOUNT_REF, PROVIDER_ENV_VARS, createKeyringBackend, credentialFingerprint, redactSecrets, validateSecretShape, } from "./cloud/credentials.js";
+export type { CredentialSource, CredentialStoreOptions, ResolvedCredential, SecretBackend } from "./cloud/credentials.js";
+export type { RunpodProviderOptions } from "./cloud/runpod.js";
+export type * from "./cloud/types.js";
+export { EXECUTION_CONTRACT_VERSION, WORKER_PORT, toWireJob } from "./cloud/execution.js";
+export { RunpodExecutionBackend, WORKER_BOOTSTRAP_SCRIPT, MIN_WORKER_READY_TIMEOUT_MS, VOLUME_MOUNT, createKeyringTokenStore, } from "./cloud/runpod-backend.js";
+export type { RunpodBackendOptions, TokenStore, WorkerBundle } from "./cloud/runpod-backend.js";
+export { WorkerClient, WORKER_USER_AGENT, isSafeRelativePath, validateInventory } from "./cloud/worker-client.js";
+export type { WorkerClientOptions } from "./cloud/worker-client.js";
+export type * from "./cloud/execution.js";
 export { getHardwareInfo, getDiskInfo } from "./hardware/index.js";
 export { detectPython } from "./python/index.js";
 export { detectDocker, isImageCachedLocally, pullDockerImage, probeDockerGpuAccess, } from "./docker/index.js";