@elizaos/agent 2.0.0-alpha.97 → 2.0.0-beta.1

package/dist/packages/agent/src/services/task-executor.d.ts

@@ -0,0 +1,47 @@
+import type { IAgentRuntime, Memory } from "@elizaos/core";
+/** Specification for a task to be executed */
+export interface TaskSpec {
+    id: string;
+    description: string;
+    type: string;
+    metadata?: Record<string, unknown>;
+    agentType?: string;
+    message?: Memory;
+}
+/** Result from a completed task */
+export interface TaskResult {
+    taskId: string;
+    success: boolean;
+    output?: string;
+    artifacts?: Array<{
+        name: string;
+        path: string;
+        type: string;
+    }>;
+    error?: string;
+    durationMs?: number;
+}
+/** Interface for task executors that handle specific task types */
+export interface TaskExecutor {
+    /** Unique type identifier (e.g., "coding", "research", "content") */
+    readonly type: string;
+    /** Human-readable description of what this executor handles */
+    readonly description: string;
+    /** Check if this executor can handle the given task */
+    canHandle(spec: TaskSpec, runtime: IAgentRuntime): boolean;
+    /** Execute the task and return results */
+    execute(spec: TaskSpec, runtime: IAgentRuntime): Promise<TaskResult>;
+    /** Abort a running task */
+    abort(taskId: string): Promise<void>;
+}
+/** Registry for task executors */
+export declare class TaskExecutorRegistry {
+    private executors;
+    register(executor: TaskExecutor): void;
+    unregister(type: string): void;
+    /** Find the best executor for a task spec */
+    findExecutor(spec: TaskSpec, runtime: IAgentRuntime): TaskExecutor | undefined;
+    getAll(): TaskExecutor[];
+    get(type: string): TaskExecutor | undefined;
+}
+//# sourceMappingURL=task-executor.d.ts.map

package/dist/packages/agent/src/services/task-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-executor.d.ts","sourceRoot":"","sources":["../../../../../src/services/task-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE3D,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,uDAAuD;IACvD,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IAE3D,0CAA0C;IAC1C,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAErE,2BAA2B;IAC3B,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,kCAAkC;AAClC,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,SAAS,CAAwC;IAEzD,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAItC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,6CAA6C;IAC7C,YAAY,CACV,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,aAAa,GACrB,YAAY,GAAG,SAAS;IAa3B,MAAM,IAAI,YAAY,EAAE;IAIxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;CAG5C"}

package/dist/packages/agent/src/services/task-executor.js

@@ -0,0 +1,31 @@
+/** Registry for task executors */
+export class TaskExecutorRegistry {
+    executors = new Map();
+    register(executor) {
+        this.executors.set(executor.type, executor);
+    }
+    unregister(type) {
+        this.executors.delete(type);
+    }
+    /** Find the best executor for a task spec */
+    findExecutor(spec, runtime) {
+        // If task has explicit type, try that first
+        if (spec.type) {
+            const explicit = this.executors.get(spec.type);
+            if (explicit?.canHandle(spec, runtime))
+                return explicit;
+        }
+        // Otherwise, find first executor that can handle it
+        for (const executor of this.executors.values()) {
+            if (executor.canHandle(spec, runtime))
+                return executor;
+        }
+        return undefined;
+    }
+    getAll() {
+        return Array.from(this.executors.values());
+    }
+    get(type) {
+        return this.executors.get(type);
+    }
+}

package/dist/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.ts";
+/** 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/dist/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/dist/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/dist/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 beta.0" 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-beta.0"           → [2, 0, 0, 0]
+ *   "2.0.0-beta.1"           → [2, 0, 0, 1]
+ *   "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
+ * (beta vs beta, nightly vs nightly). Cross-tag comparisons (beta.1 vs rc.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/dist/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,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAWhD,CAAC;AAiBF;;;;;;;;;;;;;;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,CAsDf"}

package/dist/packages/agent/src/services/version-compat.js

@@ -0,0 +1,211 @@
+/**
+ * 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
+ */
+/**
+ * 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 const AI_PROVIDER_PLUGINS = [
+    "@elizaos/plugin-anthropic",
+    "@elizaos/plugin-openai",
+    "@elizaos/plugin-openrouter",
+    "@elizaos/plugin-ollama",
+    "@elizaos/plugin-google-genai",
+    "@elizaos/plugin-groq",
+    "@elizaos/plugin-xai",
+    "@homunculuslabs/plugin-zai",
+    "@elizaos/plugin-elizacloud",
+    "@elizaos/plugin-codex-cli",
+];
+/**
+ * Self-declared plugin names (the `name` property on the plugin object) that
+ * correspond to AI provider plugins.  Some plugins use a short internal name
+ * (e.g. "elizaOSCloud") that differs from the npm package name.  The
+ * diagnostic must recognise both forms to avoid false-positive warnings.
+ */
+const AI_PROVIDER_PLUGIN_ALIASES = [
+    "elizaOSCloud",
+    "codex-cli",
+];
+// ---------------------------------------------------------------------------
+// Semver comparison for stable and prerelease tags.
+// ---------------------------------------------------------------------------
+/**
+ * Parse a semver string (including pre-release tags) into a comparable tuple.
+ * Returns null for unparseable versions.
+ *
+ * Examples:
+ *   "2.0.0-beta.0"           → [2, 0, 0, 0]
+ *   "2.0.0-beta.1"           → [2, 0, 0, 1]
+ *   "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
+ * (beta vs beta, nightly vs nightly). Cross-tag comparisons (beta.1 vs rc.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 function parseSemver(version) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-(?:beta|rc|nightly)\.(\d+))?$/);
+    if (!match)
+        return null;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    const patch = Number(match[3]);
+    // A release without a pre-release tag sorts after any pre-release.
+    const pre = match[4] !== undefined ? Number(match[4]) : Number.POSITIVE_INFINITY;
+    return [major, minor, patch, pre];
+}
+/**
+ * Compare two semver strings. Returns:
+ *   -1 if a < b
+ *    0 if a === b
+ *    1 if a > b
+ *   null if either version is unparseable.
+ */
+export function compareSemver(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (!pa || !pb)
+        return null;
+    for (let i = 0; i < 4; i++) {
+        if (pa[i] < pb[i])
+            return -1;
+        if (pa[i] > pb[i])
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Check if `installed` version satisfies `>= required`.
+ */
+export function versionSatisfies(installed, required) {
+    const cmp = compareSemver(installed, required);
+    return cmp !== null && cmp >= 0;
+}
+// ---------------------------------------------------------------------------
+// Core export probing
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function coreExportExists(exportName) {
+    try {
+        const core = (await import("@elizaos/core"));
+        return exportName in core && core[exportName] !== undefined;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") {
+            return false;
+        }
+        throw err;
+    }
+}
+/**
+ * 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 async function getInstalledVersion(packageName) {
+    try {
+        // Dynamic import of package.json is not universally supported, so we
+        // use createRequire as a robust fallback for reading metadata.
+        const { createRequire } = await import("node:module");
+        const require = createRequire(import.meta.url);
+        const pkgPath = require.resolve(`${packageName}/package.json`);
+        const { readFileSync } = await import("node:fs");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version ?? null;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "MODULE_NOT_FOUND" ||
+            code === "ERR_MODULE_NOT_FOUND" ||
+            code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate a single plugin's compatibility with the installed core.
+ */
+export async function validatePluginCompat(pluginName, coreVersion) {
+    const missingExports = [];
+    const pluginVersion = await getInstalledVersion(pluginName);
+    const compatible = missingExports.length === 0;
+    let message = "";
+    if (!compatible) {
+        message =
+            `${pluginName}${pluginVersion ? `@${pluginVersion}` : ""} requires ` +
+                `${missingExports.join(", ")} from @elizaos/core, but the installed ` +
+                `core@${coreVersion} does not export ${missingExports.length === 1 ? "it" : "them"}. ` +
+                `Pin this plugin to a version compatible with core@${coreVersion}, or upgrade core.`;
+    }
+    return {
+        plugin: pluginName,
+        compatible,
+        pluginVersion,
+        coreVersion,
+        missingExports,
+        message,
+    };
+}
+/**
+ * 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 function diagnoseNoAIProvider(loadedPluginNames, failedPlugins) {
+    const isAIProvider = (name) => AI_PROVIDER_PLUGINS.includes(name) ||
+        AI_PROVIDER_PLUGIN_ALIASES.includes(name);
+    const loadedProviders = loadedPluginNames.filter(isAIProvider);
+    // At least one AI provider loaded — no issue.
+    if (loadedProviders.length > 0)
+        return null;
+    if (process.env.ELIZA_LOCAL_LLAMA?.trim() === "1" ||
+        process.env.ELIZA_DEVICE_BRIDGE_ENABLED?.trim() === "1") {
+        return null;
+    }
+    // Check if any AI provider plugins were attempted but failed.
+    const failedProviders = failedPlugins.filter((f) => AI_PROVIDER_PLUGINS.includes(f.name));
+    if (failedProviders.length === 0) {
+        return ("No AI provider plugin was loaded. Set an API key environment variable " +
+            "(e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY) or log in " +
+            "to Eliza Cloud (ELIZAOS_CLOUD_API_KEY) to enable at least one model provider.");
+    }
+    // Check for the specific version-skew signature.
+    const versionSkewPlugins = failedProviders.filter((f) => f.error.includes("not found in module") ||
+        f.error.includes("Export named") ||
+        f.error.includes("does not provide an export named"));
+    if (versionSkewPlugins.length > 0) {
+        const names = versionSkewPlugins.map((f) => f.name).join(", ");
+        return (`Version skew detected: ${names} failed to import required symbols from ` +
+            `@elizaos/core. This usually means the plugin version is ahead of the ` +
+            `installed core version. Pin the affected plugins to a version compatible ` +
+            `with your installed @elizaos/core, or upgrade core. ` +
+            `See: https://github.com/elizaos/eliza/issues/10`);
+    }
+    // Generic failure.
+    const details = failedProviders
+        .map((f) => `  ${f.name}: ${f.error}`)
+        .join("\n");
+    return `All AI provider plugins failed to load:\n${details}`;
+}

package/dist/packages/agent/src/services/virtual-filesystem.d.ts

@@ -0,0 +1,88 @@
+export type VirtualFilesystemDiffStatus = "added" | "modified" | "deleted";
+export interface VirtualFilesystemOptions {
+    stateDir?: string;
+    projectId: string;
+    quotaBytes?: number;
+    maxFileBytes?: number;
+    now?: () => Date;
+}
+export interface VirtualFilesystemEntry {
+    path: string;
+    type: "file" | "directory";
+    size: number;
+    mtimeMs: number;
+}
+export interface VirtualFilesystemSnapshot {
+    id: string;
+    projectId: string;
+    createdAt: string;
+    root: string;
+    filesBytes: number;
+    fileCount: number;
+    note?: string;
+}
+export interface VirtualFilesystemRollback {
+    snapshotId: string;
+    projectId: string;
+    rolledBackAt: string;
+    previousSnapshotId?: string;
+}
+export interface VirtualFilesystemDiffEntry {
+    path: string;
+    status: VirtualFilesystemDiffStatus;
+    before?: VirtualFilesystemEntry;
+    after?: VirtualFilesystemEntry;
+}
+export declare class VirtualFilesystemError extends Error {
+    readonly code: "PATH_TRAVERSAL" | "INVALID_PATH" | "NOT_FOUND" | "NOT_FILE" | "NOT_DIRECTORY" | "SYMLINK_DENIED" | "QUOTA_EXCEEDED" | "SNAPSHOT_NOT_FOUND";
+    constructor(message: string, code: "PATH_TRAVERSAL" | "INVALID_PATH" | "NOT_FOUND" | "NOT_FILE" | "NOT_DIRECTORY" | "SYMLINK_DENIED" | "QUOTA_EXCEEDED" | "SNAPSHOT_NOT_FOUND");
+}
+export declare class VirtualFilesystemService {
+    readonly projectId: string;
+    readonly projectRoot: string;
+    readonly filesRoot: string;
+    readonly snapshotsRoot: string;
+    readonly quotaBytes: number;
+    readonly maxFileBytes: number;
+    private readonly now;
+    constructor(options: VirtualFilesystemOptions);
+    initialize(): Promise<void>;
+    writeFile(virtualPath: string, contents: string | Uint8Array): Promise<VirtualFilesystemEntry>;
+    readFile(virtualPath: string, encoding?: BufferEncoding): Promise<string>;
+    readFileBytes(virtualPath: string): Promise<Buffer>;
+    list(virtualPath?: string, options?: {
+        recursive?: boolean;
+    }): Promise<VirtualFilesystemEntry[]>;
+    delete(virtualPath: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    createSnapshot(note?: string): Promise<VirtualFilesystemSnapshot>;
+    getSnapshot(id: string): Promise<VirtualFilesystemSnapshot>;
+    diffSnapshots(beforeSnapshotId: string, afterSnapshotId: string): Promise<VirtualFilesystemDiffEntry[]>;
+    diffCurrent(snapshotId: string): Promise<VirtualFilesystemDiffEntry[]>;
+    rollback(snapshotId: string): Promise<VirtualFilesystemRollback>;
+    resolveVirtualPath(virtualPath: string): string;
+    /**
+     * Resolve a virtual path to its absolute on-disk location, applying the same
+     * traversal/symlink rules used by readFile/writeFile. The returned path is
+     * always inside the project's `filesRoot` and is the path Node/Bun will use
+     * if you `pathToFileURL()` it for a dynamic import. The path is not required
+     * to exist — callers that need existence should `readFile` it first.
+     */
+    resolveDiskPath(virtualPath: string): string;
+    private resolvePath;
+    private ensureSafeParentDirectory;
+    private rejectSymlinkIfExists;
+    private assertFile;
+    private assertDirectory;
+    private entryFor;
+    private listEntries;
+    private measureFiles;
+    private measureTree;
+    private fileSizeIfExists;
+    private readSnapshot;
+    private snapshotFilesRoot;
+    private indexTree;
+}
+export declare function createVirtualFilesystemService(options: VirtualFilesystemOptions): VirtualFilesystemService;
+//# sourceMappingURL=virtual-filesystem.d.ts.map

package/dist/packages/agent/src/services/virtual-filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-filesystem.d.ts","sourceRoot":"","sources":["../../../../../src/services/virtual-filesystem.ts"],"names":[],"mappings":"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"}