@xopcai/xopc 0.0.191 → 0.0.193

package/dist/src/providers/xopc-cloud-model-source.js

@@ -47,25 +47,30 @@ var XopcCloudModelSource = class {
 		if (!Array.isArray(body?.data)) throw new XopcCloudModelError("XOPC model discovery returned an invalid response", response.status, "invalid_response");
 		const models = [...new Map(body.data.filter((model) => typeof model.id === "string" && model.id.length > 0).map((model) => {
 			const declaredInput = model.xopc?.capabilities?.input;
-			const parsedInput = Array.isArray(declaredInput) ? declaredInput.filter((value) => value === "text" || value === "image") : [];
-			const input = parsedInput.includes("text") ? [...new Set(parsedInput)] : ["text", ...new Set(parsedInput)];
+			const parsedInput = Array.isArray(declaredInput) ? declaredInput.filter((value) => value === "text" || value === "image" || value === "audio") : [];
+			const kind = model.xopc?.kind === "image" || model.xopc?.kind === "stt" || model.xopc?.kind === "tts" ? model.xopc.kind : "language";
+			const input = kind === "stt" ? ["audio"] : kind === "tts" ? ["text"] : kind === "language" && !parsedInput.includes("text") ? ["text", ...new Set(parsedInput)] : [...new Set(parsedInput)];
 			const maxOutputTokens = model.xopc?.maxOutputTokens;
 			const declaredOutput = model.xopc?.capabilities?.output;
-			const output = Array.isArray(declaredOutput) ? declaredOutput.filter((value) => value === "text" || value === "image") : ["text"];
+			const output = kind === "stt" ? ["text"] : kind === "tts" ? ["audio"] : Array.isArray(declaredOutput) ? declaredOutput.filter((value) => value === "text" || value === "image" || value === "audio") : ["text"];
 			const declaredOperations = model.xopc?.operations ?? model.xopc?.capabilities?.operations;
-			const operations = Array.isArray(declaredOperations) ? declaredOperations.filter((value) => value === "chat.completions" || value === "responses" || value === "images.generate" || value === "images.edit") : ["chat.completions", "responses"];
+			const operations = kind === "stt" ? ["audio.transcription"] : kind === "tts" ? ["audio.speech"] : Array.isArray(declaredOperations) ? declaredOperations.filter((value) => value === "chat.completions" || value === "responses" || value === "images.generate" || value === "images.edit" || value === "audio.transcription" || value === "audio.speech") : ["chat.completions", "responses"];
 			const generation = parseImageGenerationCapabilities(model.xopc?.capabilities?.imageGeneration);
+			const stt = kind === "stt" ? parseSttCapabilities(model.xopc?.capabilities) : void 0;
+			const tts = kind === "tts" ? parseTtsCapabilities(model.xopc?.capabilities, model.xopc?.defaultVoice) : void 0;
 			return [model.id, {
 				id: model.id,
 				name: model.id,
-				kind: model.xopc?.kind === "image" ? "image" : "language",
+				kind,
 				input,
 				output,
 				operations,
 				reasoning: model.xopc?.capabilities?.reasoning === true,
 				contextWindow: 128e3,
 				maxOutputTokens: typeof maxOutputTokens === "number" && Number.isSafeInteger(maxOutputTokens) ? maxOutputTokens : null,
-				...generation ? { imageGeneration: generation } : {}
+				...generation ? { imageGeneration: generation } : {},
+				...stt ? { stt } : {},
+				...tts ? { tts } : {}
 			}];
 		})).values()];
 		this.catalogStore.replaceSourceModels("xopc-cloud", {
@@ -85,6 +90,47 @@ var XopcCloudModelSource = class {
 		};
 	}
 };
+function parseSttCapabilities(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const raw = value;
+	return {
+		inputFormats: strings(raw.inputFormats),
+		maxBytes: positiveInteger(raw.maxBytes),
+		maxDurationSeconds: positiveInteger(raw.maxDurationSeconds),
+		languages: strings(raw.languages),
+		languageHint: raw.languageHint === true,
+		prompt: raw.prompt === true,
+		timestamps: strings(raw.timestamps).filter((item) => item === "segment" || item === "word"),
+		diarization: raw.diarization === true
+	};
+}
+function parseTtsCapabilities(value, defaultVoice) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const raw = value;
+	return {
+		maxCharacters: positiveInteger(raw.maxCharacters),
+		languages: strings(raw.languages),
+		outputFormats: strings(raw.outputFormats).filter((item) => [
+			"mp3",
+			"opus",
+			"aac",
+			"flac",
+			"wav",
+			"pcm"
+		].includes(item)),
+		streaming: raw.streaming === true,
+		speed: raw.speed === true,
+		pitch: raw.pitch === true,
+		instructions: raw.instructions === true,
+		...typeof defaultVoice === "string" && defaultVoice ? { defaultVoice } : {}
+	};
+}
+function strings(value) {
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function positiveInteger(value) {
+	return Number.isSafeInteger(value) && Number(value) > 0 ? Number(value) : 0;
+}
 function parseImageGenerationCapabilities(value) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
 	const raw = value;

package/dist/src/runtime-tools/archive.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeKind } from './types.js';
+export declare function extractRuntimeArchive(params: {
+    runtime: RuntimeKind;
+    archivePath: string;
+    archiveType: 'zip' | 'tar.gz';
+    stagingDir: string;
+}): Promise<string>;
+export declare function atomicInstallRuntime(extractedRoot: string, installDir: string): Promise<void>;

package/dist/src/runtime-tools/archive.js

@@ -0,0 +1,99 @@
+import { RuntimeError } from "./errors.js";
+import { isAbsolute, join, posix, relative, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { lstat, mkdir, readdir, readlink, rename, rm, stat } from "node:fs/promises";
+import AdmZip from "adm-zip";
+//#region src/runtime-tools/archive.ts
+const MAX_ARCHIVE_ENTRIES = 5e4;
+function validateMemberPath(memberPath) {
+	const portablePath = memberPath.replaceAll("\\", "/");
+	const normalized = posix.normalize(portablePath);
+	if (!memberPath || isAbsolute(memberPath) || portablePath.startsWith("/") || normalized === ".." || normalized.startsWith("../")) throw new Error(`Unsafe archive member: ${memberPath}`);
+}
+async function validateExtractedTree(root, current = root) {
+	for (const entry of await readdir(current)) {
+		const entryPath = join(current, entry);
+		const details = await lstat(entryPath);
+		if (details.isSymbolicLink()) {
+			const relativeTarget = relative(root, resolve(current, await readlink(entryPath)));
+			if (relativeTarget.split(/[\\/]/)[0] === ".." || isAbsolute(relativeTarget)) throw new Error(`Archive symlink escapes extraction root: ${entryPath}`);
+			continue;
+		}
+		if (details.isDirectory()) await validateExtractedTree(root, entryPath);
+	}
+}
+async function runTar(args) {
+	return await new Promise((resolvePromise, reject) => {
+		let stdout = "";
+		let stderr = "";
+		const child = spawn("tar", args, {
+			shell: false,
+			windowsHide: true
+		});
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.once("error", reject);
+		child.once("close", (code) => {
+			if (code === 0) resolvePromise(stdout);
+			else reject(new Error(stderr.trim() || `tar exited with code ${code}`));
+		});
+	});
+}
+async function extractZip(archivePath, destination) {
+	const zip = new AdmZip(archivePath);
+	const entries = zip.getEntries();
+	if (entries.length > MAX_ARCHIVE_ENTRIES) throw new Error("Archive contains too many entries");
+	for (const entry of entries) validateMemberPath(entry.entryName);
+	zip.extractAllTo(destination, true, false);
+}
+async function extractTarGz(archivePath, destination) {
+	const entries = (await runTar(["-tzf", archivePath])).split(/\r?\n/).filter(Boolean);
+	if (entries.length > MAX_ARCHIVE_ENTRIES) throw new Error("Archive contains too many entries");
+	for (const entry of entries) validateMemberPath(entry);
+	await runTar([
+		"-xzf",
+		archivePath,
+		"-C",
+		destination
+	]);
+}
+async function singleArchiveRoot(destination) {
+	const entries = (await readdir(destination)).filter((entry) => entry !== "__MACOSX");
+	if (entries.length !== 1) throw new Error("Archive must contain one top-level directory");
+	const root = join(destination, entries[0]);
+	if (!(await stat(root)).isDirectory()) throw new Error("Archive root is not a directory");
+	return root;
+}
+async function extractRuntimeArchive(params) {
+	await rm(params.stagingDir, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(params.stagingDir, { recursive: true });
+	try {
+		if (params.archiveType === "zip") await extractZip(params.archivePath, params.stagingDir);
+		else await extractTarGz(params.archivePath, params.stagingDir);
+		await validateExtractedTree(params.stagingDir);
+		return await singleArchiveRoot(params.stagingDir);
+	} catch (error) {
+		await rm(params.stagingDir, {
+			recursive: true,
+			force: true
+		});
+		throw new RuntimeError(`Invalid ${params.runtime} archive: ${error instanceof Error ? error.message : String(error)}`, "RUNTIME_ARCHIVE_INVALID", params.runtime, "extract", true, [], { cause: error });
+	}
+}
+async function atomicInstallRuntime(extractedRoot, installDir) {
+	await mkdir(resolve(installDir, ".."), { recursive: true });
+	await rm(installDir, {
+		recursive: true,
+		force: true
+	});
+	await rename(extractedRoot, installDir);
+}
+//#endregion
+export { atomicInstallRuntime, extractRuntimeArchive };

package/dist/src/runtime-tools/bootstrap.d.ts

@@ -0,0 +1,16 @@
+import type { RuntimeToolsConfig } from '../config/schema.js';
+import { ManagedRuntimeManager } from './manager.js';
+import type { ResolvedRuntime, RuntimeKind } from './types.js';
+export type RuntimeBootstrapResult = {
+    runtime: RuntimeKind;
+    ok: boolean;
+    resolved?: ResolvedRuntime;
+    error?: string;
+};
+type RuntimeResolver = Pick<ManagedRuntimeManager, 'resolve'>;
+export declare function provisionEagerRuntimes(params: {
+    stateDir: string;
+    config: RuntimeToolsConfig;
+    manager?: RuntimeResolver;
+}): Promise<RuntimeBootstrapResult[]>;
+export {};

package/dist/src/runtime-tools/bootstrap.js

@@ -0,0 +1,33 @@
+import { ManagedRuntimeManager } from "./manager.js";
+//#region src/runtime-tools/bootstrap.ts
+async function provisionEagerRuntimes(params) {
+	if (!params.config.enabled) return [];
+	const manager = params.manager ?? new ManagedRuntimeManager({
+		stateDir: params.stateDir,
+		config: params.config
+	});
+	const requested = [];
+	if (params.config.node.enabled && params.config.node.provision === "eager") requested.push("node");
+	if (params.config.python.enabled && params.config.python.provision === "eager") requested.push("python");
+	const results = [];
+	for (const runtime of requested) try {
+		const resolved = await manager.resolve({
+			runtime,
+			allowProvision: true
+		});
+		results.push({
+			runtime,
+			ok: true,
+			resolved
+		});
+	} catch (error) {
+		results.push({
+			runtime,
+			ok: false,
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return results;
+}
+//#endregion
+export { provisionEagerRuntimes };

package/dist/src/runtime-tools/catalog.d.ts

@@ -0,0 +1,19 @@
+import type { RuntimeKind } from './types.js';
+export declare const RUNTIME_CATALOG_VERSION = "2026-08-23";
+export declare const DEFAULT_RUNTIME_VERSIONS: Record<RuntimeKind, string>;
+export type RuntimePlatform = 'darwin-arm64' | 'darwin-x64' | 'win32-x64' | 'linux-x64-gnu' | 'linux-arm64-gnu';
+export interface RuntimeAsset {
+    runtime: 'node' | 'uv';
+    version: string;
+    platform: RuntimePlatform;
+    archiveFile: string;
+    url: string;
+    checksumUrl: string;
+    archiveType: 'zip' | 'tar.gz';
+}
+export declare function detectRuntimePlatform(platform?: NodeJS.Platform, arch?: string): RuntimePlatform | null;
+export declare function resolveRuntimeAsset(params: {
+    runtime: 'node' | 'uv';
+    version: string;
+    platform: RuntimePlatform;
+}): RuntimeAsset;

package/dist/src/runtime-tools/catalog.js

@@ -0,0 +1,59 @@
+//#region src/runtime-tools/catalog.ts
+const RUNTIME_CATALOG_VERSION = "2026-08-23";
+const DEFAULT_RUNTIME_VERSIONS = {
+	node: "22.23.2",
+	uv: "0.8.12",
+	python: "3.12.11"
+};
+function detectRuntimePlatform(platform = process.platform, arch = process.arch) {
+	if (platform === "darwin" && arch === "arm64") return "darwin-arm64";
+	if (platform === "darwin" && arch === "x64") return "darwin-x64";
+	if (platform === "win32" && arch === "x64") return "win32-x64";
+	if (platform === "linux" && arch === "x64") return "linux-x64-gnu";
+	if (platform === "linux" && arch === "arm64") return "linux-arm64-gnu";
+	return null;
+}
+function nodePlatformSuffix(platform) {
+	return {
+		"darwin-arm64": "darwin-arm64",
+		"darwin-x64": "darwin-x64",
+		"win32-x64": "win-x64",
+		"linux-x64-gnu": "linux-x64",
+		"linux-arm64-gnu": "linux-arm64"
+	}[platform];
+}
+function uvPlatformSuffix(platform) {
+	return {
+		"darwin-arm64": "aarch64-apple-darwin",
+		"darwin-x64": "x86_64-apple-darwin",
+		"win32-x64": "x86_64-pc-windows-msvc",
+		"linux-x64-gnu": "x86_64-unknown-linux-gnu",
+		"linux-arm64-gnu": "aarch64-unknown-linux-gnu"
+	}[platform];
+}
+function resolveRuntimeAsset(params) {
+	if (params.runtime === "node") {
+		const ext = params.platform === "win32-x64" ? "zip" : "tar.gz";
+		const archiveFile = `node-v${params.version}-${nodePlatformSuffix(params.platform)}.${ext}`;
+		const releaseBase = `https://nodejs.org/download/release/v${params.version}`;
+		return {
+			...params,
+			archiveFile,
+			url: `${releaseBase}/${archiveFile}`,
+			checksumUrl: `${releaseBase}/SHASUMS256.txt`,
+			archiveType: ext
+		};
+	}
+	const ext = params.platform === "win32-x64" ? "zip" : "tar.gz";
+	const archiveFile = `uv-${uvPlatformSuffix(params.platform)}.${ext}`;
+	const base = `https://github.com/astral-sh/uv/releases/download/${params.version}`;
+	return {
+		...params,
+		archiveFile,
+		url: `${base}/${archiveFile}`,
+		checksumUrl: `${base}/${archiveFile}.sha256`,
+		archiveType: ext
+	};
+}
+//#endregion
+export { DEFAULT_RUNTIME_VERSIONS, RUNTIME_CATALOG_VERSION, detectRuntimePlatform, resolveRuntimeAsset };

package/dist/src/runtime-tools/command.d.ts

@@ -0,0 +1,15 @@
+export interface RuntimeCommandResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+}
+export declare function runRuntimeCommand(params: {
+    command: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<RuntimeCommandResult>;

package/dist/src/runtime-tools/command.js

@@ -0,0 +1,59 @@
+import { spawn } from "node:child_process";
+//#region src/runtime-tools/command.ts
+const DEFAULT_COMMAND_TIMEOUT_MS = 5e3;
+async function runRuntimeCommand(params) {
+	return await new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		let timedOut = false;
+		let aborted = false;
+		const child = spawn(params.command, params.args, {
+			env: params.env,
+			shell: false,
+			windowsHide: process.platform === "win32",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		const finish = (exitCode) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			params.signal?.removeEventListener("abort", abort);
+			resolve({
+				ok: exitCode === 0 && !timedOut && !aborted,
+				stdout: stdout.trim(),
+				stderr: stderr.trim(),
+				exitCode,
+				timedOut,
+				aborted
+			});
+		};
+		const abort = () => {
+			aborted = true;
+			child.kill("SIGKILL");
+			finish(null);
+		};
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.once("error", () => finish(null));
+		child.once("close", finish);
+		const timeout = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGKILL");
+			finish(null);
+		}, params.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS);
+		timeout.unref();
+		if (params.signal?.aborted) abort();
+		else params.signal?.addEventListener("abort", abort, { once: true });
+	});
+}
+//#endregion
+export { runRuntimeCommand };

package/dist/src/runtime-tools/download-source.d.ts

@@ -0,0 +1,24 @@
+import type { RuntimeToolsConfig } from '../config/schema.js';
+import type { RuntimeAsset, RuntimePlatform } from './catalog.js';
+type DownloadConfig = RuntimeToolsConfig['download'];
+export interface ResolvedRuntimeDownload {
+    url: string;
+    sha256: string;
+    source: 'website' | 'direct';
+}
+export declare function runtimeGatewayPythonMirror(gatewayBaseUrl: string): string;
+export declare function canFallbackPythonInstall(output: string, timedOut: boolean): boolean;
+export declare function validateGatewayDescriptor(params: {
+    value: unknown;
+    gatewayBaseUrl: string;
+    asset: RuntimeAsset;
+    platform: RuntimePlatform;
+}): ResolvedRuntimeDownload;
+export declare function resolveRuntimeDownloadSource(params: {
+    asset: RuntimeAsset;
+    platform: RuntimePlatform;
+    config: DownloadConfig;
+    signal?: AbortSignal;
+    onFallback?: (message: string) => void;
+}): Promise<ResolvedRuntimeDownload>;
+export {};

package/dist/src/runtime-tools/download-source.js

@@ -0,0 +1,125 @@
+import { RuntimeError } from "./errors.js";
+import { fetchRuntimeResource, readRuntimeResponseText } from "./network.js";
+import { resolveExpectedChecksum } from "./downloader.js";
+//#region src/runtime-tools/download-source.ts
+const MAX_GATEWAY_RESPONSE_BYTES = 64 * 1024;
+function runtimeGatewayPythonMirror(gatewayBaseUrl) {
+	return `${gatewayBaseUrl.replace(/\/+$/, "")}/python-build-standalone`;
+}
+function canFallbackPythonInstall(output, timedOut) {
+	if (/checksum|digest|hash mismatch|integrity|verification failed|invalid archive/i.test(output)) return false;
+	return timedOut || /failed to download|request failed|error sending request|timed? out|connection|dns|429|50[234]/i.test(output);
+}
+var GatewayResolveError = class extends Error {
+	constructor(message, allowsDirectFallback, retrySameSource = allowsDirectFallback) {
+		super(message);
+		this.allowsDirectFallback = allowsDirectFallback;
+		this.retrySameSource = retrySameSource;
+	}
+};
+function descriptorUrl(baseUrl, asset, platform) {
+	const url = new URL(`${baseUrl.replace(/\/+$/, "")}/resolve`);
+	url.searchParams.set("runtime", asset.runtime);
+	url.searchParams.set("version", asset.version);
+	url.searchParams.set("platform", platform);
+	return url;
+}
+function validateGatewayDescriptor(params) {
+	const value = params.value;
+	const archive = value?.archive;
+	if (value?.schemaVersion !== 1 || value.runtime !== params.asset.runtime || value.version !== params.asset.version || value.platform !== params.platform || archive?.name !== params.asset.archiveFile || archive.archiveType !== params.asset.archiveType || typeof archive.url !== "string" || typeof archive.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(archive.sha256)) throw new GatewayResolveError("Runtime gateway returned an invalid descriptor", false);
+	const base = new URL(`${params.gatewayBaseUrl.replace(/\/+$/, "")}/`);
+	const artifact = new URL(archive.url);
+	const expectedPath = `${base.pathname}artifacts/${params.asset.runtime}/${params.asset.version}/${params.platform}/${params.asset.archiveFile}`;
+	if (artifact.origin !== base.origin || artifact.username || artifact.password || artifact.pathname !== expectedPath || artifact.search || artifact.hash) throw new GatewayResolveError("Runtime gateway returned an untrusted artifact URL", false);
+	return {
+		url: artifact.href,
+		sha256: archive.sha256,
+		source: "website"
+	};
+}
+async function resolveFromGateway(params) {
+	let lastError;
+	for (let attempt = 0; attempt < 2; attempt += 1) {
+		if (params.signal?.aborted) throw params.signal.reason;
+		try {
+			const response = await fetchRuntimeResource({
+				url: descriptorUrl(params.config.gatewayBaseUrl, params.asset, params.platform).href,
+				timeoutMs: params.config.timeoutMs,
+				proxy: params.config.proxy,
+				signal: params.signal,
+				init: {
+					headers: { "User-Agent": "xopc-runtime-manager/1" },
+					redirect: "error"
+				}
+			});
+			const declaredSize = Number(response.headers.get("content-length"));
+			if (Number.isFinite(declaredSize) && declaredSize > MAX_GATEWAY_RESPONSE_BYTES) {
+				await response.body?.cancel().catch(() => {});
+				throw new GatewayResolveError("Runtime gateway response exceeds the size limit", false);
+			}
+			let responseText;
+			try {
+				responseText = await readRuntimeResponseText(response, MAX_GATEWAY_RESPONSE_BYTES);
+			} catch {
+				throw new GatewayResolveError("Runtime gateway response exceeds the size limit", false);
+			}
+			if (!response.ok) {
+				let body = null;
+				try {
+					body = JSON.parse(responseText);
+				} catch {}
+				const unsupported = response.status === 404 && body?.error === "unsupported_catalog_entry";
+				const retryable = unsupported || response.status === 429 || response.status >= 500;
+				throw new GatewayResolveError(`Runtime gateway returned HTTP ${response.status}`, retryable, !unsupported && retryable);
+			}
+			let descriptor;
+			try {
+				descriptor = JSON.parse(responseText);
+			} catch {
+				throw new GatewayResolveError("Runtime gateway returned invalid JSON", false);
+			}
+			return validateGatewayDescriptor({
+				value: descriptor,
+				gatewayBaseUrl: params.config.gatewayBaseUrl,
+				asset: params.asset,
+				platform: params.platform
+			});
+		} catch (error) {
+			if (params.signal?.aborted) throw error;
+			const normalized = error instanceof GatewayResolveError ? error : new GatewayResolveError(error instanceof Error ? error.message : String(error), true);
+			if (!normalized.allowsDirectFallback) throw normalized;
+			lastError = normalized;
+			if (!normalized.retrySameSource) break;
+			if (attempt === 0) await new Promise((resolve) => setTimeout(resolve, 500));
+		}
+	}
+	throw lastError ?? new GatewayResolveError("Runtime gateway is unavailable", true);
+}
+async function resolveDirect(asset, config, signal) {
+	const sha256 = await resolveExpectedChecksum({
+		runtime: asset.runtime,
+		checksumUrl: asset.checksumUrl,
+		archiveFile: asset.archiveFile,
+		timeoutMs: config.timeoutMs,
+		proxy: config.proxy,
+		signal
+	});
+	return {
+		url: asset.url,
+		sha256,
+		source: "direct"
+	};
+}
+async function resolveRuntimeDownloadSource(params) {
+	if (params.config.source === "direct-only") return await resolveDirect(params.asset, params.config, params.signal);
+	try {
+		return await resolveFromGateway(params);
+	} catch (error) {
+		if (params.config.source === "website-only" || !(error instanceof GatewayResolveError) || !error.allowsDirectFallback) throw new RuntimeError(`Failed to resolve ${params.asset.runtime} from the runtime gateway: ${error instanceof Error ? error.message : String(error)}`, "RUNTIME_DOWNLOAD_FAILED", params.asset.runtime, "resolve_gateway", true, [], { cause: error });
+		params.onFallback?.(`Runtime gateway unavailable; downloading ${params.asset.runtime} directly`);
+		return await resolveDirect(params.asset, params.config, params.signal);
+	}
+}
+//#endregion
+export { canFallbackPythonInstall, resolveRuntimeDownloadSource, runtimeGatewayPythonMirror, validateGatewayDescriptor };

package/dist/src/runtime-tools/downloader.d.ts

@@ -0,0 +1,21 @@
+import type { RuntimeKind } from './types.js';
+export declare function canFallbackRuntimeDownload(error: unknown): boolean;
+export declare function resolveExpectedChecksum(params: {
+    runtime: 'node' | 'uv';
+    checksumUrl: string;
+    archiveFile: string;
+    timeoutMs: number;
+    proxy?: string;
+    signal?: AbortSignal;
+}): Promise<string>;
+export declare function sha256File(path: string): Promise<string>;
+export declare function downloadVerifiedArchive(params: {
+    runtime: RuntimeKind;
+    url: string;
+    targetPath: string;
+    expectedSha256: string;
+    timeoutMs: number;
+    proxy?: string;
+    signal?: AbortSignal;
+    onProgress?: (downloadedBytes: number, totalBytes?: number) => void;
+}): Promise<string>;