@moldesk/runtime 0.0.1 → 0.0.2

package/dist/nvidia/index.js

@@ -0,0 +1,119 @@
+const PROBE_TIMEOUT_MS = 10_000;
+const BYTES_PER_MIB = 1024 * 1024;
+function splitCsvLines(output) {
+    return output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => line.split(",").map((cell) => cell.trim()));
+}
+function parseNonNegativeInt(value) {
+    if (!/^\d+$/.test(value))
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+/**
+ * Extract the driver's max-supported CUDA version from `nvidia-smi -q -x` XML
+ * output. `<cuda_version>` is a singular top-level tag (appears once, before
+ * any per-GPU `<gpu>` repetition), so a first-match regex is unambiguous
+ * without needing a full XML parser. Never parse the decorative ASCII table.
+ */
+export function parseDriverCudaVersionXml(xml) {
+    const match = xml.match(/<cuda_version>\s*([\d.]+)\s*<\/cuda_version>/i);
+    if (!match)
+        return undefined;
+    const value = match[1];
+    return value && value.toLowerCase() !== "not found" ? value : undefined;
+}
+function parseToolkitCudaVersion(nvccOutput) {
+    const match = nvccOutput.match(/release\s+(\d+\.\d+(?:\.\d+)?)/i);
+    return match ? match[1] : undefined;
+}
+/**
+ * Probe NVIDIA GPUs via `nvidia-smi` CSV output only (never the
+ * decorative table). Any missing tool / error / unparsable output
+ * becomes `{available:false}` rather than throwing.
+ */
+export async function detectNvidia(capture, timeoutMs = PROBE_TIMEOUT_MS) {
+    let run;
+    if (capture) {
+        run = capture;
+    }
+    else {
+        const { defaultCapture } = await import("../process/index.js");
+        run = defaultCapture;
+    }
+    const gpuResult = await run("nvidia-smi", ["--query-gpu=index,name,memory.total", "--format=csv,noheader,nounits"], { timeoutMs });
+    if (gpuResult.timedOut) {
+        return {
+            available: false,
+            gpus: [],
+            error: `nvidia-smi timed out after ${timeoutMs}ms`,
+        };
+    }
+    if (gpuResult.code !== 0) {
+        const detail = `${gpuResult.stdout}\n${gpuResult.stderr}`.trim();
+        return {
+            available: false,
+            gpus: [],
+            error: detail.length > 0
+                ? `nvidia-smi unavailable: ${detail.split("\n")[0]}`
+                : "nvidia-smi not detected (no NVIDIA GPU or driver)",
+        };
+    }
+    const rows = splitCsvLines(gpuResult.stdout);
+    if (rows.length === 0) {
+        return {
+            available: false,
+            gpus: [],
+            error: "nvidia-smi returned no GPU rows",
+        };
+    }
+    const gpus = [];
+    for (const cells of rows) {
+        if (cells.length < 3) {
+            return {
+                available: false,
+                gpus: [],
+                error: `unrecognized nvidia-smi output: ${JSON.stringify(cells)}`,
+            };
+        }
+        const [indexRaw, nameRaw, memoryRaw] = cells;
+        const index = parseNonNegativeInt(indexRaw);
+        if (index === undefined || nameRaw.length === 0) {
+            return {
+                available: false,
+                gpus: [],
+                error: `unrecognized nvidia-smi output: ${JSON.stringify(cells)}`,
+            };
+        }
+        const memoryMib = parseNonNegativeInt(memoryRaw);
+        gpus.push({
+            index,
+            name: nameRaw,
+            totalVramBytes: memoryMib === undefined ? undefined : memoryMib * BYTES_PER_MIB,
+        });
+    }
+    // Driver/CUDA versions are best-effort; GPU presence decides availability.
+    let driverVersion;
+    let driverCudaVersion;
+    let cudaToolkitVersion;
+    const driverResult = await run("nvidia-smi", ["--query-gpu=driver_version", "--format=csv,noheader,nounits"], { timeoutMs });
+    if (!driverResult.timedOut && driverResult.code === 0) {
+        const first = driverResult.stdout.split("\n").map((l) => l.trim()).find(Boolean);
+        if (first && first.toLowerCase() !== "[not supported]")
+            driverVersion = first;
+    }
+    // Structured XML query for the driver's max-supported CUDA version — never
+    // scrape the decorative `nvidia-smi` banner table.
+    const cudaXmlResult = await run("nvidia-smi", ["-q", "-x"], { timeoutMs });
+    if (!cudaXmlResult.timedOut && cudaXmlResult.code === 0) {
+        driverCudaVersion = parseDriverCudaVersionXml(cudaXmlResult.stdout);
+    }
+    const toolkitResult = await run("nvcc", ["--version"], { timeoutMs });
+    if (!toolkitResult.timedOut && toolkitResult.code === 0) {
+        cudaToolkitVersion = parseToolkitCudaVersion(`${toolkitResult.stdout}\n${toolkitResult.stderr}`);
+    }
+    return { available: true, driverVersion, driverCudaVersion, cudaToolkitVersion, gpus };
+}

package/dist/nvidia/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/nvidia/index.test.js

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { detectNvidia, parseDriverCudaVersionXml } from "./index.js";
+function stubCapture(handler) {
+    return async (command, args) => {
+        const r = handler(command, args);
+        return { code: r.code, stdout: r.stdout ?? "", stderr: r.stderr ?? "", timedOut: r.timedOut };
+    };
+}
+const CSV_ROWS = "0, NVIDIA A100, 81920\n";
+describe("parseDriverCudaVersionXml", () => {
+    it("extracts the top-level cuda_version tag", () => {
+        const xml = "<nvidia_smi_log><cuda_version>12.4</cuda_version><gpu><cuda_version>ignored</cuda_version></gpu></nvidia_smi_log>";
+        expect(parseDriverCudaVersionXml(xml)).toBe("12.4");
+    });
+    it("returns undefined when the tag is absent", () => {
+        expect(parseDriverCudaVersionXml("<nvidia_smi_log></nvidia_smi_log>")).toBeUndefined();
+    });
+    it("returns undefined for a 'Not Found' placeholder value", () => {
+        expect(parseDriverCudaVersionXml("<cuda_version>Not Found</cuda_version>")).toBeUndefined();
+    });
+    it("never matches decorative table text", () => {
+        const decorative = "+-----------------------------------------------------------------------------------+\n| CUDA Version: 12.4                                                                   |\n";
+        expect(parseDriverCudaVersionXml(decorative)).toBeUndefined();
+    });
+});
+describe("detectNvidia — driver CUDA (XML) vs toolkit CUDA (nvcc)", () => {
+    it("reports driverCudaVersion from XML and cudaToolkitVersion from nvcc independently", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (cmd === "nvidia-smi" && args.join(" ").includes("memory.total"))
+                return { code: 0, stdout: CSV_ROWS };
+            if (cmd === "nvidia-smi" && args.includes("-x"))
+                return { code: 0, stdout: "<nvidia_smi_log><cuda_version>12.6</cuda_version></nvidia_smi_log>" };
+            if (cmd === "nvidia-smi")
+                return { code: 0, stdout: "560.35.03\n" };
+            if (cmd === "nvcc")
+                return { code: 0, stdout: "Cuda compilation tools, release 12.1\n" };
+            return { code: 1 };
+        });
+        const result = await detectNvidia(capture);
+        expect(result.available).toBe(true);
+        expect(result.driverCudaVersion).toBe("12.6");
+        expect(result.cudaToolkitVersion).toBe("12.1");
+    });
+    it("leaves driverCudaVersion undefined when only the toolkit is present (no driver-only host regression)", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (cmd === "nvidia-smi" && args.join(" ").includes("memory.total"))
+                return { code: 0, stdout: CSV_ROWS };
+            if (cmd === "nvidia-smi" && args.includes("-x"))
+                return { code: 1, stderr: "unsupported" };
+            if (cmd === "nvidia-smi")
+                return { code: 0, stdout: "560.35.03\n" };
+            if (cmd === "nvcc")
+                return { code: 0, stdout: "Cuda compilation tools, release 12.1\n" };
+            return { code: 1 };
+        });
+        const result = await detectNvidia(capture);
+        expect(result.driverCudaVersion).toBeUndefined();
+        expect(result.cudaToolkitVersion).toBe("12.1");
+    });
+    it("reports driverCudaVersion when nvcc (toolkit) is entirely absent — the driver-only Docker-host case", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (cmd === "nvidia-smi" && args.join(" ").includes("memory.total"))
+                return { code: 0, stdout: CSV_ROWS };
+            if (cmd === "nvidia-smi" && args.includes("-x"))
+                return { code: 0, stdout: "<nvidia_smi_log><cuda_version>12.6</cuda_version></nvidia_smi_log>" };
+            if (cmd === "nvidia-smi")
+                return { code: 0, stdout: "560.35.03\n" };
+            if (cmd === "nvcc")
+                return { code: 127, stderr: "command not found" };
+            return { code: 1 };
+        });
+        const result = await detectNvidia(capture);
+        expect(result.driverCudaVersion).toBe("12.6");
+        expect(result.cudaToolkitVersion).toBeUndefined();
+    });
+    it("leaves both undefined when neither probe succeeds, without failing GPU detection", async () => {
+        const capture = stubCapture((cmd, args) => {
+            if (cmd === "nvidia-smi" && args.join(" ").includes("memory.total"))
+                return { code: 0, stdout: CSV_ROWS };
+            if (cmd === "nvidia-smi")
+                return { code: 1, stderr: "unsupported" };
+            if (cmd === "nvcc")
+                return { code: 127, stderr: "command not found" };
+            return { code: 1 };
+        });
+        const result = await detectNvidia(capture);
+        expect(result.available).toBe(true);
+        expect(result.driverCudaVersion).toBeUndefined();
+        expect(result.cudaToolkitVersion).toBeUndefined();
+    });
+});

package/dist/process/index.d.ts

@@ -1,12 +1,46 @@
 export interface RunOptions {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
     onStdout?: (chunk: string) => void;
     onStderr?: (chunk: string) => void;
+    /** External cancellation trigger, e.g. wired to CLI SIGINT/SIGTERM handlers. */
+    signal?: AbortSignal;
+    /**
+     * If set, a timeout or `signal` abort sends SIGTERM first and waits up to
+     * this many ms before escalating to SIGKILL. If unset (the default),
+     * termination is an immediate SIGKILL — this is the pre-existing behavior,
+     * unchanged, so callers that don't pass it keep identical semantics.
+     */
+    gracefulTimeoutMs?: number;
+    /** Called synchronously once the child is spawned, so callers can persist the pid before the promise resolves. */
+    onSpawn?: (pid: number) => void;
 }
 export interface RunResult {
     code: number;
     stdout: string;
     stderr: string;
+    timedOut?: boolean;
+    pid?: number;
+    signal?: string;
+    /** True when termination was triggered by `options.signal` aborting (distinct from a `timeoutMs` timeout). */
+    cancelled?: boolean;
 }
+/**
+ * Spawn a command without a shell (never `sh -c`). Resolves on close;
+ * timeouts kill the child and resolve with `timedOut: true` instead of
+ * rejecting, so probes can degrade to capability results.
+ */
 export declare function runCommand(command: string, args: string[], options?: RunOptions): Promise<RunResult>;
+/** Minimal capture result for probes. */
+export interface CaptureResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+export type CaptureFn = (command: string, args: string[], options?: {
+    timeoutMs?: number;
+}) => Promise<CaptureResult>;
+/** Default capture backed by runCommand. */
+export declare const defaultCapture: CaptureFn;

package/dist/process/index.js

@@ -1,12 +1,75 @@
 import { spawn } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * Spawn a command without a shell (never `sh -c`). Resolves on close;
+ * timeouts kill the child and resolve with `timedOut: true` instead of
+ * rejecting, so probes can degrade to capability results.
+ */
 export function runCommand(command, args, options = {}) {
-    return new Promise((resolve, reject) => {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const gracefulTimeoutMs = options.gracefulTimeoutMs;
+    return new Promise((resolve) => {
+        let settled = false;
+        let timedOut = false;
+        let cancelled = false;
+        let forceKillTimer;
         const child = spawn(command, args, {
             cwd: options.cwd,
             env: options.env ?? process.env,
+            stdio: ["ignore", "pipe", "pipe"],
         });
+        if (typeof child.pid === "number") {
+            options.onSpawn?.(child.pid);
+        }
         let stdout = "";
         let stderr = "";
+        const terminate = () => {
+            try {
+                if (gracefulTimeoutMs && gracefulTimeoutMs > 0) {
+                    child.kill("SIGTERM");
+                    forceKillTimer = setTimeout(() => {
+                        try {
+                            child.kill("SIGKILL");
+                        }
+                        catch {
+                            // ignore kill failures; close handler settles below
+                        }
+                    }, gracefulTimeoutMs);
+                }
+                else {
+                    child.kill("SIGKILL");
+                }
+            }
+            catch {
+                // ignore kill failures; close handler settles below
+            }
+        };
+        const timer = timeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                terminate();
+            }, timeoutMs)
+            : undefined;
+        const onAbort = () => {
+            if (settled || timedOut)
+                return;
+            cancelled = true;
+            terminate();
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        if (options.signal?.aborted)
+            onAbort();
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (forceKillTimer)
+                clearTimeout(forceKillTimer);
+            options.signal?.removeEventListener("abort", onAbort);
+            resolve(result);
+        };
         child.stdout.on("data", (data) => {
             const text = data.toString();
             stdout += text;
@@ -17,9 +80,41 @@ export function runCommand(command, args, options = {}) {
             stderr += text;
             options.onStderr?.(text);
         });
-        child.on("error", reject);
-        child.on("close", (code) => {
-            resolve({ code: code ?? 0, stdout, stderr });
+        child.on("error", (error) => {
+            const suffix = timedOut || /timed out/i.test(error.message)
+                ? ` (timed out after ${timeoutMs}ms)`
+                : "";
+            settle({
+                code: 127,
+                stdout,
+                stderr: `${stderr}${error.message}${suffix}`,
+                timedOut,
+                cancelled,
+                pid: child.pid,
+            });
+        });
+        child.on("close", (code, signal) => {
+            if (timedOut) {
+                settle({
+                    code: 124,
+                    stdout,
+                    stderr: `${stderr}command timed out after ${timeoutMs}ms: ${command} ${args.join(" ")}`.trim(),
+                    timedOut: true,
+                    pid: child.pid,
+                    signal: signal ?? undefined,
+                });
+                return;
+            }
+            settle({
+                code: code ?? 0,
+                stdout,
+                stderr,
+                cancelled,
+                pid: child.pid,
+                signal: signal ?? undefined,
+            });
         });
     });
 }
+/** Default capture backed by runCommand. */
+export const defaultCapture = (command, args, options) => runCommand(command, args, { timeoutMs: options?.timeoutMs ?? 10_000 });

package/dist/process/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/process/index.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { runCommand } from "./index.js";
+describe("runCommand", () => {
+    it("exposes the child pid via onSpawn and on the result", async () => {
+        let spawnedPid;
+        const result = await runCommand(process.execPath, ["-e", "process.exit(0)"], {
+            onSpawn: (pid) => {
+                spawnedPid = pid;
+            },
+        });
+        expect(spawnedPid).toBeTypeOf("number");
+        expect(result.pid).toBe(spawnedPid);
+        expect(result.code).toBe(0);
+    });
+    it("escalates to SIGKILL after gracefulTimeoutMs when an aborted process ignores SIGTERM", async () => {
+        const controller = new AbortController();
+        const ignoreSigterm = "process.on('SIGTERM', () => {}); setInterval(() => {}, 1000);";
+        const runPromise = runCommand(process.execPath, ["-e", ignoreSigterm], {
+            signal: controller.signal,
+            gracefulTimeoutMs: 150,
+        });
+        controller.abort();
+        const result = await runPromise;
+        expect(result.cancelled).toBe(true);
+    }, 10_000);
+    it("kills immediately with no graceful escalation when gracefulTimeoutMs is unset (pre-existing behavior)", async () => {
+        const controller = new AbortController();
+        const sleep = "setTimeout(() => {}, 10000);";
+        const started = Date.now();
+        const runPromise = runCommand(process.execPath, ["-e", sleep], { signal: controller.signal });
+        controller.abort();
+        const result = await runPromise;
+        expect(result.cancelled).toBe(true);
+        expect(Date.now() - started).toBeLessThan(2000);
+    }, 10_000);
+});

package/dist/providers/python.d.ts

@@ -0,0 +1,14 @@
+import type { ExecuteRequest, ExecutionResult, PrepareRuntimeRequest, PreparedRuntime, RemoveRuntimeRequest, RuntimeCapability, RuntimeProvider } from "../providers.js";
+/**
+ * Executes already-installed Python models. Resolves the interpreter from
+ * the on-disk managed venv (`prepare`) and streams process output to
+ * `stdout.log`/`stderr.log` under the caller-supplied `cwd` while also
+ * forwarding chunks live (`execute`).
+ */
+export declare class PythonRuntimeProvider implements RuntimeProvider {
+    readonly kind: "python";
+    inspect(): Promise<RuntimeCapability>;
+    prepare(request: PrepareRuntimeRequest): Promise<PreparedRuntime>;
+    execute(request: ExecuteRequest): Promise<ExecutionResult>;
+    remove(_request: RemoveRuntimeRequest): Promise<void>;
+}

package/dist/providers/python.js

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MoldeskError } from "@moldesk/registry";
+import { runCommand } from "../process/index.js";
+import { detectPython } from "../python/index.js";
+/** Model runs have no fixed duration; termination is driven only by `signal`/graceful cancellation, not a timer. */
+const NO_TIMEOUT_MS = 0;
+const EXECUTE_GRACEFUL_TIMEOUT_MS = 5_000;
+/**
+ * Executes already-installed Python models. Resolves the interpreter from
+ * the on-disk managed venv (`prepare`) and streams process output to
+ * `stdout.log`/`stderr.log` under the caller-supplied `cwd` while also
+ * forwarding chunks live (`execute`).
+ */
+export class PythonRuntimeProvider {
+    kind = "python";
+    async inspect() {
+        const python = await detectPython();
+        return {
+            kind: "python",
+            available: python.available,
+            version: python.version,
+            error: python.error,
+        };
+    }
+    async prepare(request) {
+        const executable = path.join(request.targetDir, ".venv", "bin", "python");
+        if (!fs.existsSync(executable)) {
+            throw new MoldeskError({
+                code: "MODEL_NOT_INSTALLED",
+                message: `No managed Python environment found for "${request.modelName}" at ${executable}.`,
+                remediation: `Run "moldesk install ${request.modelName}" first.`,
+                details: { modelName: request.modelName, targetDir: request.targetDir },
+            });
+        }
+        return { kind: "python", executable, fingerprint: request.runtimeFingerprint };
+    }
+    async execute(request) {
+        const stdoutPath = path.join(request.cwd, "stdout.log");
+        const stderrPath = path.join(request.cwd, "stderr.log");
+        const stdoutFd = fs.openSync(stdoutPath, "a");
+        const stderrFd = fs.openSync(stderrPath, "a");
+        try {
+            const result = await runCommand(request.executable, request.args, {
+                cwd: request.cwd,
+                // Adapter-declared env vars (e.g. OPENDDE_ROOT_DIR, TORCH_HOME) overlay the
+                // inherited environment rather than replacing it — a bare `request.env`
+                // would drop PATH/HOME and break the model process.
+                env: request.env ? { ...process.env, ...request.env } : undefined,
+                timeoutMs: NO_TIMEOUT_MS,
+                gracefulTimeoutMs: EXECUTE_GRACEFUL_TIMEOUT_MS,
+                signal: request.signal,
+                onSpawn: request.onSpawn,
+                onStdout: (chunk) => {
+                    fs.writeSync(stdoutFd, chunk);
+                    request.onStdout?.(chunk);
+                },
+                onStderr: (chunk) => {
+                    fs.writeSync(stderrFd, chunk);
+                    request.onStderr?.(chunk);
+                },
+            });
+            return {
+                exitCode: result.code,
+                stdoutPath,
+                stderrPath,
+                pid: result.pid,
+                signal: result.signal,
+                cancelled: result.cancelled,
+            };
+        }
+        finally {
+            fs.closeSync(stdoutFd);
+            fs.closeSync(stderrFd);
+        }
+    }
+    async remove(_request) {
+        // No-op: uninstall already owns Python environment removal; kept for interface parity with a future Docker provider.
+    }
+}

package/dist/providers/python.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/providers/python.test.js

@@ -0,0 +1,68 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { PythonRuntimeProvider } from "./python.js";
+const dirs = [];
+function tempDir() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk-python-provider-"));
+    dirs.push(dir);
+    return dir;
+}
+afterEach(() => {
+    for (const dir of dirs.splice(0))
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+describe("PythonRuntimeProvider.prepare", () => {
+    it("resolves the venv executable when present", async () => {
+        const targetDir = tempDir();
+        fs.mkdirSync(path.join(targetDir, ".venv", "bin"), { recursive: true });
+        fs.writeFileSync(path.join(targetDir, ".venv", "bin", "python"), "");
+        const provider = new PythonRuntimeProvider();
+        const prepared = await provider.prepare({
+            modelName: "proteinmpnn",
+            modelVersion: "v_48_020",
+            runtimeFingerprint: "python-abc",
+            targetDir,
+        });
+        expect(prepared.executable).toBe(path.join(targetDir, ".venv", "bin", "python"));
+    });
+    it("throws MODEL_NOT_INSTALLED when the venv is missing", async () => {
+        const provider = new PythonRuntimeProvider();
+        await expect(provider.prepare({ modelName: "proteinmpnn", modelVersion: "v_48_020", runtimeFingerprint: "python-abc", targetDir: tempDir() })).rejects.toMatchObject({ code: "MODEL_NOT_INSTALLED" });
+    });
+});
+describe("PythonRuntimeProvider.execute", () => {
+    it("streams stdout/stderr to log files under cwd and forwards live chunks", async () => {
+        const cwd = tempDir();
+        const chunks = [];
+        const provider = new PythonRuntimeProvider();
+        const result = await provider.execute({
+            executable: process.execPath,
+            args: ["-e", "process.stdout.write('out\\n'); process.stderr.write('err\\n');"],
+            cwd,
+            onStdout: (chunk) => chunks.push({ stream: "stdout", text: chunk }),
+            onStderr: (chunk) => chunks.push({ stream: "stderr", text: chunk }),
+        });
+        expect(result.exitCode).toBe(0);
+        expect(result.stdoutPath).toBe(path.join(cwd, "stdout.log"));
+        expect(result.stderrPath).toBe(path.join(cwd, "stderr.log"));
+        expect(fs.readFileSync(result.stdoutPath, "utf8")).toContain("out");
+        expect(fs.readFileSync(result.stderrPath, "utf8")).toContain("err");
+        expect(chunks.some((c) => c.stream === "stdout" && c.text.includes("out"))).toBe(true);
+    });
+    it("overlays adapter env vars on the inherited environment instead of replacing it", async () => {
+        const cwd = tempDir();
+        const provider = new PythonRuntimeProvider();
+        const result = await provider.execute({
+            executable: process.execPath,
+            args: ["-e", "process.stdout.write(JSON.stringify({ path: process.env.PATH ?? null, extra: process.env.MOLDESK_TEST_EXTRA ?? null }))"],
+            cwd,
+            env: { MOLDESK_TEST_EXTRA: "set-by-adapter" },
+        });
+        expect(result.exitCode).toBe(0);
+        const seen = JSON.parse(fs.readFileSync(result.stdoutPath, "utf8"));
+        expect(seen.extra).toBe("set-by-adapter");
+        expect(seen.path).toBe(process.env["PATH"] ?? null);
+    });
+});

package/dist/providers.d.ts

@@ -0,0 +1,49 @@
+import type { RuntimeKind } from "@moldesk/registry";
+export { MoldeskError } from "@moldesk/registry";
+export type { MoldeskErrorData, RuntimeKind } from "@moldesk/registry";
+export interface RuntimeCapability {
+    kind: RuntimeKind;
+    available: boolean;
+    version?: string;
+    error?: string;
+}
+export interface PrepareRuntimeRequest {
+    modelName: string;
+    modelVersion: string;
+    runtimeFingerprint: string;
+    targetDir: string;
+}
+export interface PreparedRuntime {
+    kind: RuntimeKind;
+    executable: string;
+    fingerprint: string;
+}
+export interface ExecuteRequest {
+    executable: string;
+    args: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+    onSpawn?: (pid: number) => void;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+}
+export interface ExecutionResult {
+    exitCode: number;
+    stdoutPath: string;
+    stderrPath: string;
+    pid?: number;
+    signal?: string;
+    cancelled?: boolean;
+}
+export interface RemoveRuntimeRequest {
+    modelName: string;
+    runtimeFingerprint: string;
+}
+export interface RuntimeProvider {
+    readonly kind: RuntimeKind;
+    inspect(): Promise<RuntimeCapability>;
+    prepare(request: PrepareRuntimeRequest): Promise<PreparedRuntime>;
+    execute(request: ExecuteRequest): Promise<ExecutionResult>;
+    remove(request: RemoveRuntimeRequest): Promise<void>;
+}

package/dist/providers.js

@@ -0,0 +1 @@
+export { MoldeskError } from "@moldesk/registry";

package/dist/providers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/providers.test.js

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { MoldeskError as RegistryMoldeskError } from "@moldesk/registry";
+import { MoldeskError as RuntimeMoldeskError } from "./providers.js";
+describe("runtime public contracts", () => {
+    it("re-exports the canonical MoldeskError class", () => {
+        expect(RuntimeMoldeskError).toBe(RegistryMoldeskError);
+        const error = new RuntimeMoldeskError({ code: "TEST", message: "test" });
+        expect(error).toBeInstanceOf(RegistryMoldeskError);
+    });
+});