@elizaos/agent 0.25.9 → 2.0.0-alpha.151

package/packages/agent/src/services/tts-stream-bridge.js

@@ -0,0 +1,360 @@
+/**
+ * TTS Stream Bridge — generates TTS audio server-side and pipes PCM data
+ * into FFmpeg's audio track for RTMP streaming.
+ *
+ * Uses pipe:3 (a 4th stdio fd) as the audio input to FFmpeg. Writes PCM
+ * silence when idle and decoded TTS audio when speaking. This avoids FIFO
+ * complexity and works cross-platform.
+ *
+ * @module services/tts-stream-bridge
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { spawn } from "node:child_process";
+import { logger } from "@elizaos/core";
+import { sanitizeSpeechText } from "../utils/spoken-text.js";
+const TAG = "[TtsStreamBridge]";
+// PCM format: signed 16-bit little-endian, 24 kHz, mono
+const SAMPLE_RATE = 24000;
+const CHANNELS = 1;
+const BYTES_PER_SAMPLE = 2;
+const CHUNK_MS = 50;
+/** Bytes per tick: 24000 * 2 * 1 * 50/1000 = 2400 */
+const CHUNK_BYTES = (SAMPLE_RATE * BYTES_PER_SAMPLE * CHANNELS * CHUNK_MS) / 1000;
+const ELEVENLABS_TIMEOUT_MS = 20_000;
+const OPENAI_TIMEOUT_MS = 20_000;
+class TtsStreamBridge {
+    writeStream = null;
+    tickTimer = null;
+    pcmQueue = [];
+    _speaking = false;
+    silenceChunk;
+    constructor() {
+        // Pre-allocate a silence chunk (all zeros = silence in s16le)
+        this.silenceChunk = Buffer.alloc(CHUNK_BYTES, 0);
+    }
+    /** Attach the bridge to an FFmpeg stdio pipe (pipe:3). */
+    attach(stream) {
+        this.detach();
+        this.writeStream = stream;
+        stream.on("error", (err) => {
+            logger.warn(`${TAG} Write stream error: ${err.message}`);
+        });
+        // Start the tick loop — writes PCM chunks every CHUNK_MS
+        this.tickTimer = setInterval(() => this.tick(), CHUNK_MS);
+        logger.info(`${TAG} Attached to FFmpeg audio pipe`);
+    }
+    /** Detach from FFmpeg — stops tick loop and clears queue. */
+    detach() {
+        if (this.tickTimer) {
+            clearInterval(this.tickTimer);
+            this.tickTimer = null;
+        }
+        this.writeStream = null;
+        this.pcmQueue = [];
+        this._speaking = false;
+    }
+    /** Whether the bridge is currently attached to an FFmpeg process. */
+    isAttached() {
+        return this.writeStream !== null;
+    }
+    /** Whether TTS audio is currently being played. */
+    isSpeaking() {
+        return this._speaking;
+    }
+    /**
+     * Generate TTS for the given text and queue PCM audio for playback.
+     * Non-blocking — queues audio and returns immediately after generation.
+     */
+    async speak(text, config) {
+        if (!this.writeStream) {
+            logger.warn(`${TAG} Cannot speak — not attached to FFmpeg`);
+            return false;
+        }
+        const speakableText = sanitizeSpeechText(text);
+        if (!speakableText)
+            return false;
+        try {
+            logger.info(`${TAG} Generating TTS (${config.provider}, ${speakableText.length} chars)`);
+            const mp3 = await this.generateTts(speakableText, config);
+            if (!mp3 || mp3.length === 0) {
+                logger.warn(`${TAG} TTS returned empty audio`);
+                return false;
+            }
+            const pcm = await this.decodeMp3ToPcm(mp3);
+            if (!pcm || pcm.length === 0) {
+                logger.warn(`${TAG} PCM decode returned empty buffer`);
+                return false;
+            }
+            // Split PCM into CHUNK_BYTES-sized buffers for smooth playback
+            const chunks = [];
+            for (let i = 0; i < pcm.length; i += CHUNK_BYTES) {
+                const end = Math.min(i + CHUNK_BYTES, pcm.length);
+                const chunk = Buffer.alloc(CHUNK_BYTES, 0);
+                pcm.copy(chunk, 0, i, end);
+                chunks.push(chunk);
+            }
+            this.pcmQueue.push(...chunks);
+            this._speaking = true;
+            logger.info(`${TAG} Queued ${chunks.length} PCM chunks (${(pcm.length / SAMPLE_RATE / BYTES_PER_SAMPLE).toFixed(1)}s)`);
+            return true;
+        }
+        catch (err) {
+            logger.error(`${TAG} TTS generation failed: ${String(err)}`);
+            return false;
+        }
+    }
+    /** Called every CHUNK_MS — writes next PCM chunk (TTS or silence) to FFmpeg. */
+    tick() {
+        if (!this.writeStream)
+            return;
+        let chunk;
+        if (this.pcmQueue.length > 0) {
+            chunk = this.pcmQueue.shift();
+            if (this.pcmQueue.length === 0) {
+                this._speaking = false;
+                logger.info(`${TAG} Finished speaking`);
+            }
+        }
+        else {
+            chunk = this.silenceChunk;
+        }
+        try {
+            this.writeStream.write(chunk);
+        }
+        catch {
+            // Stream may have been closed — detach will handle cleanup
+        }
+    }
+    // ── TTS generation ─────────────────────────────────────────────────────
+    async generateTts(text, config) {
+        switch (config.provider) {
+            case "elevenlabs":
+                return this.generateElevenlabs(text, config);
+            case "openai":
+                return this.generateOpenai(text, config);
+            case "edge":
+                return this.generateEdge(text, config);
+            default:
+                throw new Error(`Unknown TTS provider: ${config.provider}`);
+        }
+    }
+    async generateElevenlabs(text, config) {
+        const el = config.elevenlabs;
+        if (!el?.apiKey)
+            throw new Error("ElevenLabs API key not available");
+        const voiceId = el.voiceId || "EXAVITQu4vr4xnSDxMaL";
+        const modelId = el.modelId || "eleven_flash_v2_5";
+        const url = `https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream?output_format=mp3_22050_32`;
+        const payload = {
+            text,
+            model_id: modelId,
+        };
+        if (el.voiceSettings && Object.keys(el.voiceSettings).length > 0) {
+            payload.voice_settings = el.voiceSettings;
+        }
+        const resp = await fetchWithTimeout(url, {
+            method: "POST",
+            headers: {
+                "xi-api-key": el.apiKey,
+                "Content-Type": "application/json",
+                Accept: "audio/mpeg",
+            },
+            body: JSON.stringify(payload),
+        }, ELEVENLABS_TIMEOUT_MS);
+        if (!resp.ok) {
+            const body = await resp.text().catch(() => "");
+            throw new Error(`ElevenLabs ${resp.status}: ${body.slice(0, 200)}`);
+        }
+        return Buffer.from(await resp.arrayBuffer());
+    }
+    async generateOpenai(text, config) {
+        const oai = config.openai;
+        if (!oai?.apiKey)
+            throw new Error("OpenAI API key not available");
+        const model = oai.model || "tts-1";
+        const voice = oai.voice || "alloy";
+        const resp = await fetchWithTimeout("https://api.openai.com/v1/audio/speech", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${oai.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model,
+                input: text,
+                voice,
+                response_format: "mp3",
+            }),
+        }, OPENAI_TIMEOUT_MS);
+        if (!resp.ok) {
+            const body = await resp.text().catch(() => "");
+            throw new Error(`OpenAI TTS ${resp.status}: ${body.slice(0, 200)}`);
+        }
+        return Buffer.from(await resp.arrayBuffer());
+    }
+    async generateEdge(text, config) {
+        // Edge TTS requires node-edge-tts package — optional dependency
+        try {
+            // Use a variable so Vite's static analysis doesn't try to resolve this optional dep
+            const edgeTtsModule = "node-edge-tts";
+            const { MsEdgeTTS } = await import(__rewriteRelativeImportExtension(edgeTtsModule));
+            const tts = new MsEdgeTTS();
+            const voice = config.edge?.voice || "en-US-AriaNeural";
+            await tts.setMetadata(voice, "audio-24khz-48kbitrate-mono-mp3");
+            const readable = tts.toStream(text);
+            return new Promise((resolve, reject) => {
+                const chunks = [];
+                readable.on("data", (chunk) => chunks.push(chunk));
+                readable.on("end", () => resolve(Buffer.concat(chunks)));
+                readable.on("error", reject);
+            });
+        }
+        catch (err) {
+            throw new Error(`Edge TTS failed (node-edge-tts may not be installed): ${String(err)}`);
+        }
+    }
+    // ── MP3 → PCM decode ──────────────────────────────────────────────────
+    /** Decode MP3 audio to raw s16le PCM using an FFmpeg subprocess. */
+    decodeMp3ToPcm(mp3) {
+        return new Promise((resolve, reject) => {
+            const proc = spawn("ffmpeg", [
+                "-i",
+                "pipe:0",
+                "-f",
+                "s16le",
+                "-ar",
+                String(SAMPLE_RATE),
+                "-ac",
+                String(CHANNELS),
+                "pipe:1",
+            ], { stdio: ["pipe", "pipe", "ignore"] });
+            const chunks = [];
+            proc.stdout?.on("data", (chunk) => chunks.push(chunk));
+            proc.on("close", (code) => {
+                if (code === 0) {
+                    resolve(Buffer.concat(chunks));
+                }
+                else {
+                    reject(new Error(`FFmpeg decode exited with code ${code}`));
+                }
+            });
+            proc.on("error", reject);
+            proc.stdin?.write(mp3);
+            proc.stdin?.end();
+        });
+    }
+}
+// ── Helper ────────────────────────────────────────────────────────────────
+function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    return fetch(url, { ...init, signal: controller.signal }).finally(() => clearTimeout(timer));
+}
+// ── Config resolution ─────────────────────────────────────────────────────
+/** Helper to check if a string looks like a redacted secret placeholder. */
+function isRedactedSecret(val) {
+    return /^\*+$/.test(val) || val === "REDACTED" || val === "[REDACTED]";
+}
+/**
+ * Resolve TTS configuration from eliza config, finding the best available
+ * provider with valid API keys.
+ */
+export function resolveTtsConfig(ttsConfig) {
+    if (!ttsConfig)
+        return null;
+    const preferredProvider = ttsConfig.provider || "elevenlabs";
+    // Try providers in preference order: configured → elevenlabs → openai → edge
+    const providers = [preferredProvider];
+    if (!providers.includes("elevenlabs"))
+        providers.push("elevenlabs");
+    if (!providers.includes("openai"))
+        providers.push("openai");
+    if (!providers.includes("edge"))
+        providers.push("edge");
+    for (const provider of providers) {
+        switch (provider) {
+            case "elevenlabs": {
+                const el = ttsConfig.elevenlabs;
+                const apiKey = resolveKey(el?.apiKey, "ELEVENLABS_API_KEY");
+                if (apiKey) {
+                    return {
+                        provider: "elevenlabs",
+                        elevenlabs: {
+                            apiKey,
+                            voiceId: el?.voiceId || "EXAVITQu4vr4xnSDxMaL",
+                            modelId: el?.modelId || "eleven_flash_v2_5",
+                            voiceSettings: el?.voiceSettings
+                                ? { ...el.voiceSettings }
+                                : undefined,
+                        },
+                    };
+                }
+                break;
+            }
+            case "openai": {
+                const oai = ttsConfig.openai;
+                const apiKey = resolveKey(oai?.apiKey, "OPENAI_API_KEY");
+                if (apiKey) {
+                    return {
+                        provider: "openai",
+                        openai: {
+                            apiKey,
+                            model: oai?.model || "tts-1",
+                            voice: oai?.voice || "alloy",
+                        },
+                    };
+                }
+                break;
+            }
+            case "edge": {
+                // Edge TTS always works (no API key needed)
+                return {
+                    provider: "edge",
+                    edge: {
+                        voice: ttsConfig.edge?.voice || "en-US-AriaNeural",
+                    },
+                };
+            }
+        }
+    }
+    return null;
+}
+function resolveKey(configKey, envVar) {
+    const ck = configKey?.trim();
+    if (ck && !isRedactedSecret(ck))
+        return ck;
+    const ev = process.env[envVar]?.trim();
+    if (ev && !isRedactedSecret(ev))
+        return ev;
+    const explicitCloudTts = process.env.ELIZAOS_CLOUD_USE_TTS === "true";
+    const legacyCloudTts = process.env.ELIZAOS_CLOUD_USE_TTS === undefined &&
+        process.env.ELIZAOS_CLOUD_ENABLED === "true" &&
+        process.env.ELIZA_CLOUD_TTS_DISABLED !== "true";
+    if (explicitCloudTts || legacyCloudTts) {
+        const cloudKey = process.env.ELIZAOS_CLOUD_API_KEY?.trim();
+        if (cloudKey && !isRedactedSecret(cloudKey)) {
+            return cloudKey;
+        }
+    }
+    return null;
+}
+/**
+ * Get a summary of available TTS providers and their status.
+ */
+export function getTtsProviderStatus(ttsConfig) {
+    const resolved = resolveTtsConfig(ttsConfig);
+    return {
+        configuredProvider: ttsConfig?.provider || null,
+        hasApiKey: resolved ? resolved.provider !== "edge" : false,
+        resolvedProvider: resolved?.provider || null,
+    };
+}
+// Module singleton
+export const ttsStreamBridge = new TtsStreamBridge();

package/packages/agent/src/services/update-checker.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Queries the npm registry for new elizaos versions on the user's
+ * configured release channel (stable/beta/nightly).
+ */
+import type { ReleaseChannel, UpdateConfig } from "../config/types.eliza.js";
+/** npm dist-tag corresponding to each release channel. */
+export declare const CHANNEL_DIST_TAGS: Readonly<Record<ReleaseChannel, string>>;
+export interface UpdateCheckResult {
+    updateAvailable: boolean;
+    currentVersion: string;
+    latestVersion: string | null;
+    channel: ReleaseChannel;
+    distTag: string;
+    /** True when the result came from the interval cache, not a live fetch. */
+    cached: boolean;
+    error: string | null;
+}
+/** Resolve the effective release channel from config, env, or default. */
+export declare function resolveChannel(cfg: UpdateConfig | undefined): ReleaseChannel;
+/**
+ * Check whether a newer version is available.
+ * Respects the check interval; pass `force: true` to bypass.
+ */
+export declare function checkForUpdate(options?: {
+    force?: boolean;
+}): Promise<UpdateCheckResult>;
+/** Returns the latest published version for each channel. */
+export declare function fetchAllChannelVersions(): Promise<Record<ReleaseChannel, string | null>>;
+//# sourceMappingURL=update-checker.d.ts.map

package/packages/agent/src/services/update-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-checker.d.ts","sourceRoot":"","sources":["../../../../../src/services/update-checker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAQ7E,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAItE,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AA6BD,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,cAAc,CAI5E;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8E7B;AAED,6DAA6D;AAC7D,wBAAsB,uBAAuB,IAAI,OAAO,CACtD,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC,CACtC,CAOA"}

package/packages/agent/src/services/update-checker.js

@@ -0,0 +1,134 @@
+/**
+ * Queries the npm registry for new elizaos versions on the user's
+ * configured release channel (stable/beta/nightly).
+ */
+import { loadElizaConfig, saveElizaConfig } from "../config/config.js";
+import { VERSION } from "../runtime/version.js";
+import { compareSemver } from "./version-compat.js";
+const CHECK_INTERVAL_SECONDS = 14_400; // 4 hours
+const REGISTRY_TIMEOUT_MS = 8_000;
+const NPM_REGISTRY_PACKUMENT_URL = "https://registry.npmjs.org/elizaos";
+/** npm dist-tag corresponding to each release channel. */
+export const CHANNEL_DIST_TAGS = {
+    stable: "latest",
+    beta: "beta",
+    nightly: "nightly",
+};
+/** Fetch dist-tags from the npm registry. Returns null on any failure. */
+async function fetchDistTags() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REGISTRY_TIMEOUT_MS);
+    try {
+        const res = await fetch(NPM_REGISTRY_PACKUMENT_URL, {
+            headers: { Accept: "application/vnd.npm.install-v1+json" },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data["dist-tags"] ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function shouldSkipCheck(cfg) {
+    if (!cfg?.lastCheckAt)
+        return false;
+    const interval = cfg.checkIntervalSeconds ?? CHECK_INTERVAL_SECONDS;
+    const elapsed = (Date.now() - new Date(cfg.lastCheckAt).getTime()) / 1_000;
+    return elapsed < interval;
+}
+/** Resolve the effective release channel from config, env, or default. */
+export function resolveChannel(cfg) {
+    const env = process.env.ELIZA_UPDATE_CHANNEL?.trim().toLowerCase();
+    if (env === "stable" || env === "beta" || env === "nightly")
+        return env;
+    return cfg?.channel ?? "stable";
+}
+/**
+ * Check whether a newer version is available.
+ * Respects the check interval; pass `force: true` to bypass.
+ */
+export async function checkForUpdate(options) {
+    const config = loadElizaConfig();
+    const updateCfg = config.update;
+    const channel = resolveChannel(updateCfg);
+    const distTag = CHANNEL_DIST_TAGS[channel];
+    if (!options?.force && shouldSkipCheck(updateCfg)) {
+        return {
+            updateAvailable: updateCfg?.lastCheckVersion
+                ? (compareSemver(VERSION, updateCfg.lastCheckVersion) ?? 0) < 0
+                : false,
+            currentVersion: VERSION,
+            latestVersion: updateCfg?.lastCheckVersion ?? null,
+            channel,
+            distTag,
+            cached: true,
+            error: null,
+        };
+    }
+    const distTags = await fetchDistTags();
+    if (!distTags) {
+        return {
+            updateAvailable: false,
+            currentVersion: VERSION,
+            latestVersion: null,
+            channel,
+            distTag,
+            cached: false,
+            error: "Unable to reach the npm registry. Check your network connection.",
+        };
+    }
+    const latestVersion = distTags[distTag] ?? null;
+    if (!latestVersion) {
+        return {
+            updateAvailable: false,
+            currentVersion: VERSION,
+            latestVersion: null,
+            channel,
+            distTag,
+            cached: false,
+            error: `No version found for dist-tag "${distTag}". The "${channel}" channel may not have any published releases yet.`,
+        };
+    }
+    const cmp = compareSemver(VERSION, latestVersion);
+    const updateAvailable = cmp !== null && cmp < 0;
+    try {
+        saveElizaConfig({
+            ...config,
+            update: {
+                ...config.update,
+                lastCheckAt: new Date().toISOString(),
+                lastCheckVersion: latestVersion,
+            },
+        });
+    }
+    catch (err) {
+        // If config is unwritable the cache interval won't persist and the
+        // registry gets queried on every startup — worth surfacing.
+        const msg = String(err);
+        process.stderr.write(`[eliza] Warning: could not save update-check metadata: ${msg}\n`);
+    }
+    return {
+        updateAvailable,
+        currentVersion: VERSION,
+        latestVersion,
+        channel,
+        distTag,
+        cached: false,
+        error: null,
+    };
+}
+/** Returns the latest published version for each channel. */
+export async function fetchAllChannelVersions() {
+    const distTags = await fetchDistTags();
+    return {
+        stable: distTags?.latest ?? null,
+        beta: distTags?.beta ?? null,
+        nightly: distTags?.nightly ?? null,
+    };
+}

package/packages/agent/src/services/version-compat.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Plugin ↔ Core version compatibility validation.
+ *
+ * Detects version skew between @elizaos/core and plugins that depend on
+ * specific core exports. This catches the class of bug where plugins on npm
+ * advance past the core version, importing symbols that don't exist yet in
+ * the installed core — causing silent import failures that take down every
+ * model provider.
+ *
+ * @see https://github.com/elizaos/eliza/issues/10
+ */
+/** Result of a single plugin compatibility check. */
+export interface PluginCompatResult {
+    /** Plugin package name. */
+    plugin: string;
+    /** Whether the plugin is compatible with the installed core. */
+    compatible: boolean;
+    /** The installed plugin version, or null if unresolvable. */
+    pluginVersion: string | null;
+    /** The installed core version. */
+    coreVersion: string;
+    /** List of symbols the plugin needs that are missing from core. */
+    missingExports: string[];
+    /** Human-readable explanation when incompatible. */
+    message: string;
+}
+/** Aggregate result of validating all critical plugins. */
+export interface VersionCompatReport {
+    /** Whether all checked plugins are compatible. */
+    compatible: boolean;
+    /** Per-plugin results. */
+    results: PluginCompatResult[];
+    /** Plugins that failed the check. */
+    failures: PluginCompatResult[];
+    /** Advisory message (e.g. "pin to alpha.3" or "upgrade core"). */
+    advisory: string;
+}
+/**
+ * Plugins that provide AI model capabilities. If ALL of these fail to load
+ * the agent is completely non-functional — no responses can be generated.
+ */
+export declare const AI_PROVIDER_PLUGINS: readonly string[];
+/**
+ * Parse a semver string (including pre-release tags) into a comparable tuple.
+ * Returns null for unparseable versions.
+ *
+ * Examples:
+ *   "2.0.0-alpha.3"          → [2, 0, 0, 3]
+ *   "2.0.0-alpha.4"          → [2, 0, 0, 4]
+ *   "2.0.0-nightly.20260208" → [2, 0, 0, 20260208]
+ *   "2.0.0"                  → [2, 0, 0, Infinity]  (release beats any pre-release)
+ *
+ * Note: comparisons are only meaningful within the same pre-release tag type
+ * (alpha vs alpha, nightly vs nightly). Cross-tag comparisons (alpha.7 vs beta.1)
+ * compare only the numeric suffix, which may not reflect the intended ordering.
+ * The update checker always compares within the same channel, so this is safe.
+ */
+export declare function parseSemver(version: string): [number, number, number, number] | null;
+/**
+ * Compare two semver strings. Returns:
+ *   -1 if a < b
+ *    0 if a === b
+ *    1 if a > b
+ *   null if either version is unparseable.
+ */
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1 | null;
+/**
+ * Check if `installed` version satisfies `>= required`.
+ */
+export declare function versionSatisfies(installed: string, required: string): boolean;
+/**
+ * Check whether a specific named export exists in `@elizaos/core`.
+ *
+ * This does a live import check — it tests the *actual* installed module,
+ * not a version number lookup.
+ */
+export declare function coreExportExists(exportName: string): Promise<boolean>;
+/**
+ * Read the installed version of a package from its package.json.
+ * Returns null if the package is not installed or the version is unreadable.
+ */
+export declare function getInstalledVersion(packageName: string): Promise<string | null>;
+/**
+ * Validate a single plugin's compatibility with the installed core.
+ */
+export declare function validatePluginCompat(pluginName: string, coreVersion: string): Promise<PluginCompatResult>;
+/**
+ * After plugin resolution, check whether at least one AI provider plugin
+ * loaded successfully. If none loaded, return a diagnostic message explaining
+ * whether this is a version-skew issue or a configuration issue.
+ *
+ * @param loadedPluginNames - Names of plugins that loaded successfully.
+ * @param failedPlugins - Names + error strings of plugins that failed to load.
+ */
+export declare function diagnoseNoAIProvider(loadedPluginNames: string[], failedPlugins: Array<{
+    name: string;
+    error: string;
+}>): string | null;
+//# sourceMappingURL=version-compat.d.ts.map

package/packages/agent/src/services/version-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compat.d.ts","sourceRoot":"","sources":["../../../../../src/services/version-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,UAAU,EAAE,OAAO,CAAC;IACpB,6DAA6D;IAC7D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,UAAU,EAAE,OAAO,CAAC;IACpB,0BAA0B;IAC1B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAUhD,CAAC;AAcF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,GACd,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAczC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAUrE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG7E;AAMD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW3E;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuBxB;AAMD;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC,CAuB7B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,iBAAiB,EAAE,MAAM,EAAE,EAC3B,aAAa,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GACpD,MAAM,GAAG,IAAI,CA+Cf"}