@xopcai/xopc 0.0.190 → 0.0.192

package/dist/src/gateway/service/marketplace-service.js

@@ -112,9 +112,9 @@ var GatewayMarketplaceService = class {
 		const { listMarketplacePackages } = await import("../../agent/skills/skills-marketplace.js");
 		return listMarketplacePackages(this.opts.getConfig(), params, provider);
 	}
-	async fetchSkillsCategories(provider) {
+	async fetchSkillsCategories(provider, locale) {
 		const { listMarketplaceCategories } = await import("../../agent/skills/skills-marketplace.js");
-		return listMarketplaceCategories(this.opts.getConfig(), provider);
+		return listMarketplaceCategories(this.opts.getConfig(), provider, locale);
 	}
 	async fetchSkillsPackageDetail(packageName, provider) {
 		const { getMarketplacePackageDetail } = await import("../../agent/skills/skills-marketplace.js");

package/dist/src/heartbeat/index.js

@@ -1,6 +1,6 @@
 import { DEFAULT_ACK_MAX_CHARS, HEARTBEAT_OK, NO_REPLY, shouldSilence, stripHeartbeatToken } from "./tokens.js";
+import { appendCronEventLines } from "./event-prompt.js";
 import { isWithinActiveHours } from "./active-hours.js";
 import { isHeartbeatContentEmpty } from "./content-check.js";
-import { appendCronEventLines } from "./event-prompt.js";
 import { createHeartbeatWake } from "./wake.js";
 export { DEFAULT_ACK_MAX_CHARS, HEARTBEAT_OK, NO_REPLY, appendCronEventLines, createHeartbeatWake, isHeartbeatContentEmpty, isWithinActiveHours, shouldSilence, stripHeartbeatToken };

package/dist/src/infra/update-global.js

@@ -1,6 +1,6 @@
+import { applyPathPrepend } from "./path-prepend.js";
 import { resolveExecPathBinPrepend } from "./path-env.js";
 import { readPackageVersion } from "./package-json.js";
-import { applyPathPrepend } from "./path-prepend.js";
 import { createDefaultCommandRunner } from "./run-command.js";
 import path from "node:path";
 import fs from "node:fs";

package/dist/src/providers/extension-stream-bridge.js

@@ -3,6 +3,7 @@ import { init_logger } from "../utils/logger.js";
 import "./constants.js";
 import { getProviderRegistry, init_plugin_registry } from "./plugin-registry.js";
 import { init_providers } from "./index.js";
+import { stripPromptCacheBoundary } from "../agent/prompt/cache-boundary.js";
 import { createAssistantMessageEventStream, streamSimple } from "@earendil-works/pi-ai/compat";
 //#region src/providers/extension-stream-bridge.ts
 init_plugin_registry();
@@ -80,7 +81,7 @@ function createExtensionAwareStreamFn() {
 		const stream = createAssistantMessageEventStream();
 		const params = {
 			model: model.id,
-			systemPrompt: context.systemPrompt,
+			systemPrompt: context.systemPrompt ? stripPromptCacheBoundary(context.systemPrompt) : void 0,
 			messages: context.messages,
 			tools: context.tools,
 			temperature: options?.temperature,
@@ -200,15 +201,15 @@ function createExtensionAwareStreamFn() {
 								partial.usage = {
 									input: chunk.usage.input,
 									output: chunk.usage.output,
-									cacheRead: 0,
-									cacheWrite: 0,
-									totalTokens: chunk.usage.total ?? chunk.usage.input + chunk.usage.output,
+									cacheRead: chunk.usage.cacheRead ?? 0,
+									cacheWrite: chunk.usage.cacheWrite ?? 0,
+									totalTokens: chunk.usage.total ?? chunk.usage.input + chunk.usage.output + (chunk.usage.cacheRead ?? 0) + (chunk.usage.cacheWrite ?? 0),
 									cost: {
 										input: inputCost,
 										output: outputCost,
-										cacheRead: 0,
-										cacheWrite: 0,
-										total: inputCost + outputCost
+										cacheRead: (chunk.usage.cacheRead ?? 0) / 1e6 * (model.cost?.cacheRead ?? 0),
+										cacheWrite: (chunk.usage.cacheWrite ?? 0) / 1e6 * (model.cost?.cacheWrite ?? 0),
+										total: inputCost + outputCost + (chunk.usage.cacheRead ?? 0) / 1e6 * (model.cost?.cacheRead ?? 0) + (chunk.usage.cacheWrite ?? 0) / 1e6 * (model.cost?.cacheWrite ?? 0)
 									}
 								};
 							}

package/dist/src/providers/model-catalog-store.d.ts

@@ -2,7 +2,42 @@ export interface CatalogModel {
     id: string;
     name: string;
     availability: 'available' | 'unavailable';
+    kind: 'language' | 'image' | 'stt' | 'tts';
+    input: Array<'text' | 'image' | 'audio'>;
+    output: Array<'text' | 'image' | 'audio'>;
+    operations: Array<'chat.completions' | 'responses' | 'images.generate' | 'images.edit' | 'audio.transcription' | 'audio.speech'>;
+    reasoning: boolean;
+    contextWindow: number;
     maxOutputTokens: number | null;
+    imageGeneration?: {
+        maxCount: number;
+        sizes: string[];
+        aspectRatios?: string[];
+        qualities: Array<'low' | 'medium' | 'high' | 'auto'>;
+        formats: Array<'png' | 'jpeg' | 'webp'>;
+        backgrounds: Array<'transparent' | 'opaque' | 'auto'>;
+        maxInputImages: number;
+    };
+    stt?: {
+        inputFormats: string[];
+        maxBytes: number;
+        maxDurationSeconds: number;
+        languages: string[];
+        languageHint: boolean;
+        prompt: boolean;
+        timestamps: Array<'segment' | 'word'>;
+        diarization: boolean;
+    };
+    tts?: {
+        maxCharacters: number;
+        languages: string[];
+        outputFormats: Array<'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'>;
+        streaming: boolean;
+        speed: boolean;
+        pitch: boolean;
+        instructions: boolean;
+        defaultVoice?: string;
+    };
 }
 export interface CatalogSource {
     providerId: string;

package/dist/src/providers/model-catalog-store.js

@@ -53,7 +53,31 @@ var init_model_catalog_store = __esmMin((() => {
 		cloneSource(source) {
 			return {
 				...source,
-				models: source.models.map((model) => ({ ...model }))
+				models: source.models.map((model) => ({
+					...model,
+					input: [...model.input],
+					output: [...model.output],
+					operations: [...model.operations],
+					...model.imageGeneration ? { imageGeneration: {
+						...model.imageGeneration,
+						sizes: [...model.imageGeneration.sizes],
+						aspectRatios: [...model.imageGeneration.aspectRatios ?? []],
+						qualities: [...model.imageGeneration.qualities],
+						formats: [...model.imageGeneration.formats],
+						backgrounds: [...model.imageGeneration.backgrounds]
+					} } : {},
+					...model.stt ? { stt: {
+						...model.stt,
+						inputFormats: [...model.stt.inputFormats],
+						languages: [...model.stt.languages],
+						timestamps: [...model.stt.timestamps]
+					} } : {},
+					...model.tts ? { tts: {
+						...model.tts,
+						languages: [...model.tts.languages],
+						outputFormats: [...model.tts.outputFormats]
+					} } : {}
+				}))
 			};
 		}
 	};

package/dist/src/providers/model-catalog-sync-service.js

@@ -110,6 +110,12 @@ var ModelCatalogSyncService = class {
 				}, models.map((model) => ({
 					id: model.id,
 					name: model.name ?? model.id,
+					kind: "language",
+					input: ["text"],
+					output: ["text"],
+					operations: provider.api === "openai-responses" ? ["responses"] : ["chat.completions"],
+					reasoning: false,
+					contextWindow: 128e3,
 					maxOutputTokens: null
 				})));
 				return providerId;

package/dist/src/providers/model-registry.js

@@ -236,21 +236,21 @@ var init_model_registry = __esmMin((() => {
 				log.warn({ err }, "Failed to load remote model catalog");
 				return [];
 			}
-			return Object.values(sources).flatMap((source) => source.models.filter((model) => model.availability === "available").map((model) => ({
+			return Object.values(sources).flatMap((source) => source.models.filter((model) => model.availability === "available" && model.kind === "language").map((model) => ({
 				id: model.id,
 				name: model.name,
 				api: source.api,
 				provider: source.providerId,
 				baseUrl: source.baseUrl,
-				reasoning: false,
-				input: ["text"],
+				reasoning: model.reasoning,
+				input: model.input.filter((value) => value === "text" || value === "image"),
 				cost: {
 					input: 0,
 					output: 0,
 					cacheRead: 0,
 					cacheWrite: 0
 				},
-				contextWindow: 128e3,
+				contextWindow: model.contextWindow,
 				maxTokens: model.maxOutputTokens ?? 16384
 			})));
 		}

package/dist/src/providers/prompt-cache-payload.d.ts

@@ -0,0 +1,13 @@
+import type { Api, Model, SimpleStreamOptions } from '@earendil-works/pi-ai';
+export declare function transformPromptCachePayload(model: Model<Api>, payload: unknown): unknown;
+export declare function buildPromptCacheKey(model: Model<Api>, context: {
+    systemPrompt?: string;
+    tools?: unknown[];
+}): string;
+export declare function preparePromptCacheContext<T extends {
+    systemPrompt?: string;
+}>(model: Model<Api>, context: T): T;
+export declare function withPromptCachePayloadTransform(model: Model<Api>, context: {
+    systemPrompt?: string;
+    tools?: unknown[];
+}, options: SimpleStreamOptions | undefined): SimpleStreamOptions | undefined;

package/dist/src/providers/prompt-cache-payload.js

@@ -0,0 +1,110 @@
+import { splitPromptCacheBoundary, stripPromptCacheBoundary } from "../agent/prompt/cache-boundary.js";
+import { createHash } from "node:crypto";
+//#region src/providers/prompt-cache-payload.ts
+function asRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function supportsPromptCacheKey(model) {
+	if (model.api === "openai-codex-responses" || model.api === "azure-openai-responses") return true;
+	if (model.api !== "openai-completions" && model.api !== "openai-responses") return false;
+	return model.provider === "openai" || model.baseUrl?.includes("api.openai.com") === true;
+}
+function splitAnthropicSystem(payload) {
+	const record = asRecord(payload);
+	if (!record || !Array.isArray(record.system)) return payload;
+	let changed = false;
+	const system = record.system.flatMap((value) => {
+		const block = asRecord(value);
+		if (!block || typeof block.text !== "string") return [value];
+		const split = splitPromptCacheBoundary(block.text);
+		if (!split) return [value];
+		changed = true;
+		const { text: _text, ...rest } = block;
+		return [{
+			...rest,
+			type: block.type ?? "text",
+			text: split.stablePrefix
+		}, ...split.dynamicSuffix ? [{
+			type: block.type ?? "text",
+			text: split.dynamicSuffix
+		}] : []];
+	});
+	return changed ? {
+		...record,
+		system
+	} : payload;
+}
+function splitBedrockSystem(payload) {
+	const record = asRecord(payload);
+	if (!record || !Array.isArray(record.system)) return payload;
+	let changed = false;
+	const system = [];
+	for (let index = 0; index < record.system.length; index += 1) {
+		const value = record.system[index];
+		const block = asRecord(value);
+		const split = block && typeof block.text === "string" ? splitPromptCacheBoundary(block.text) : void 0;
+		if (!split) {
+			system.push(value);
+			continue;
+		}
+		changed = true;
+		system.push({
+			...block,
+			text: split.stablePrefix
+		});
+		const next = asRecord(record.system[index + 1]);
+		if (next?.cachePoint) {
+			system.push(next);
+			index += 1;
+		}
+		if (split.dynamicSuffix) system.push({ text: split.dynamicSuffix });
+	}
+	return changed ? {
+		...record,
+		system
+	} : payload;
+}
+function transformPromptCachePayload(model, payload) {
+	if (model.api === "anthropic-messages") return splitAnthropicSystem(payload);
+	if (model.api === "bedrock-converse-stream") return splitBedrockSystem(payload);
+	return payload;
+}
+function canonicalJson(value) {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	const record = asRecord(value);
+	if (record) return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+	return JSON.stringify(value) ?? "null";
+}
+function buildPromptCacheKey(model, context) {
+	const stablePrompt = context.systemPrompt ? splitPromptCacheBoundary(context.systemPrompt)?.stablePrefix ?? stripPromptCacheBoundary(context.systemPrompt) : "";
+	return `xopc-${createHash("sha256").update(`${model.provider}\0${model.id}\0${stablePrompt}\0${canonicalJson(context.tools ?? [])}`).digest("base64url")}`;
+}
+function preparePromptCacheContext(model, context) {
+	if (model.api === "anthropic-messages" || model.api === "bedrock-converse-stream") return context;
+	if (!context.systemPrompt) return context;
+	return {
+		...context,
+		systemPrompt: stripPromptCacheBoundary(context.systemPrompt)
+	};
+}
+function withPromptCachePayloadTransform(model, context, options) {
+	const explicitBoundary = model.api === "anthropic-messages" || model.api === "bedrock-converse-stream";
+	const openAiCacheKey = supportsPromptCacheKey(model) && options?.cacheRetention !== "none";
+	if (!explicitBoundary && !openAiCacheKey) return options;
+	const upstream = options?.onPayload;
+	const promptCacheKey = openAiCacheKey ? buildPromptCacheKey(model, context) : void 0;
+	return {
+		...options,
+		onPayload: async (payload, payloadModel) => {
+			const upstreamPayload = await upstream?.(payload, payloadModel);
+			const transformed = transformPromptCachePayload(model, upstreamPayload === void 0 ? payload : upstreamPayload);
+			const record = asRecord(transformed);
+			return record && promptCacheKey ? {
+				...record,
+				prompt_cache_key: promptCacheKey
+			} : transformed;
+		}
+	};
+}
+//#endregion
+export { buildPromptCacheKey, preparePromptCacheContext, transformPromptCachePayload, withPromptCachePayloadTransform };

package/dist/src/providers/register-runtime-providers.js

@@ -16,18 +16,18 @@ function registerRuntimeProvider(modelRuntime, source) {
 		baseUrl: source.baseUrl,
 		api: source.api,
 		oauth,
-		models: source.models.filter((model) => model.availability === "available").map((model) => ({
+		models: source.models.filter((model) => model.availability === "available" && model.kind === "language").map((model) => ({
 			id: model.id,
 			name: model.name,
-			reasoning: false,
-			input: ["text"],
+			reasoning: model.reasoning,
+			input: model.input.filter((value) => value === "text" || value === "image"),
 			cost: {
 				input: 0,
 				output: 0,
 				cacheRead: 0,
 				cacheWrite: 0
 			},
-			contextWindow: 128e3,
+			contextWindow: model.contextWindow,
 			maxTokens: model.maxOutputTokens ?? 16384
 		}))
 	});

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

@@ -2,6 +2,7 @@ import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-
 import { getModelRegistry, init_model_registry } from "./model-registry.js";
 import { init_xopc_cloud_config, resolveXopcModelRouterUrl } from "./xopc-cloud-config.js";
 import { getProviderAuthService, init_provider_auth_service } from "./provider-auth-service.js";
+import { reloadImageGenerationProviders } from "../agent/image/generation/provider-registry.js";
 //#region src/providers/xopc-cloud-model-source.ts
 init_model_catalog_store();
 init_model_registry();
@@ -44,26 +45,118 @@ var XopcCloudModelSource = class {
 		const body = await response.json().catch(() => null);
 		if (!response.ok) throw new XopcCloudModelError(typeof body?.error?.message === "string" ? body.error.message : `XOPC model discovery failed (${response.status})`, response.status, typeof body?.error?.code === "string" ? body.error.code : void 0);
 		if (!Array.isArray(body?.data)) throw new XopcCloudModelError("XOPC model discovery returned an invalid response", response.status, "invalid_response");
-		const models = [...new Set(body.data.map((model) => model.id).filter((id) => typeof id === "string" && id.length > 0))];
+		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" || 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 = 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 = 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,
+				input,
+				output,
+				operations,
+				reasoning: model.xopc?.capabilities?.reasoning === true,
+				contextWindow: 128e3,
+				maxOutputTokens: typeof maxOutputTokens === "number" && Number.isSafeInteger(maxOutputTokens) ? maxOutputTokens : null,
+				...generation ? { imageGeneration: generation } : {},
+				...stt ? { stt } : {},
+				...tts ? { tts } : {}
+			}];
+		})).values()];
 		this.catalogStore.replaceSourceModels("xopc-cloud", {
 			providerId: "xopc-cloud",
 			baseUrl: this.routerUrl,
 			api: "openai-completions",
 			etag: response.headers.get("x-xopc-model-catalog-version"),
-			recommendedModel: models[0] ?? null,
+			recommendedModel: models[0]?.id ?? null,
 			lastSuccessAt: Date.now()
-		}, models.map((id) => ({
-			id,
-			name: id,
-			maxOutputTokens: null
-		})));
+		}, models);
 		this.refreshModels();
+		reloadImageGenerationProviders();
 		return {
 			status: "updated",
 			modelCount: models.length,
-			models
+			models: models.map((model) => model.id)
 		};
 	}
 };
+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;
+	const strings = (candidate, allowed) => Array.isArray(candidate) ? candidate.filter((item) => typeof item === "string" && (!allowed || allowed.includes(item))) : [];
+	return {
+		maxCount: Number.isSafeInteger(raw.maxCount) && Number(raw.maxCount) > 0 ? Number(raw.maxCount) : 1,
+		sizes: strings(raw.sizes),
+		aspectRatios: strings(raw.aspectRatios),
+		qualities: strings(raw.qualities, [
+			"low",
+			"medium",
+			"high",
+			"auto"
+		]),
+		formats: strings(raw.formats, [
+			"png",
+			"jpeg",
+			"webp"
+		]),
+		backgrounds: strings(raw.backgrounds, [
+			"transparent",
+			"opaque",
+			"auto"
+		]),
+		maxInputImages: Number.isSafeInteger(raw.maxInputImages) && Number(raw.maxInputImages) > 0 ? Number(raw.maxInputImages) : 0
+	};
+}
 //#endregion
 export { XopcCloudModelError, XopcCloudModelSource };

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;