@elizaos/agent 2.0.0-alpha.441 → 2.0.0-alpha.501

package/packages/agent/src/runtime/operations/repository.js

@@ -0,0 +1,233 @@
+/**
+ * Filesystem-backed RuntimeOperationRepository.
+ *
+ * Storage layout:
+ *   <stateDir>/runtime-operations/<id>.json   one JSON file per operation
+ *
+ * Atomic writes: write to <id>.json.tmp.<pid> then rename — same pattern
+ * the Eliza config uses (config.ts:saveElizaConfig).
+ *
+ * In-memory caches are populated lazily at first access from disk and kept
+ * in sync on every mutation. They make `findActive` and
+ * `findByIdempotencyKey` O(1) on the hot path.
+ *
+ * Hydration also reaps abandoned operations: anything still `pending` or
+ * `running` whose `startedAt` is older than 24h is force-marked `failed`
+ * with code `"abandoned"` (the process must have died mid-flight).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "@elizaos/core";
+import { resolveStateDir } from "../../config/paths.js";
+const ABANDONED_AFTER_MS = 24 * 60 * 60 * 1000;
+const IDEMPOTENCY_RETENTION_MS = 24 * 60 * 60 * 1000;
+function operationsDirFor(stateDir) {
+    return path.join(stateDir, "runtime-operations");
+}
+function ensureDir(dir) {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+}
+function readJsonFile(filePath) {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    if (!raw.trim()) {
+        return null;
+    }
+    const parsed = JSON.parse(raw);
+    if (!parsed.id || !parsed.kind || !Array.isArray(parsed.phases)) {
+        return null;
+    }
+    return parsed;
+}
+function writeJsonAtomic(filePath, op) {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+    const tmpPath = `${filePath}.tmp.${process.pid}`;
+    const content = `${JSON.stringify(op, null, 2)}\n`;
+    fs.writeFileSync(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
+    fs.renameSync(tmpPath, filePath);
+}
+export class FilesystemRuntimeOperationRepository {
+    dir;
+    byId = new Map();
+    byIdempotencyKey = new Map();
+    activeId = null;
+    hydrated = false;
+    constructor(stateDir = resolveStateDir()) {
+        this.dir = operationsDirFor(stateDir);
+    }
+    hydrate() {
+        if (this.hydrated)
+            return;
+        this.hydrated = true;
+        ensureDir(this.dir);
+        const entries = fs.readdirSync(this.dir);
+        const now = Date.now();
+        for (const entry of entries) {
+            if (!entry.endsWith(".json"))
+                continue;
+            const fullPath = path.join(this.dir, entry);
+            const op = readJsonFile(fullPath);
+            if (!op)
+                continue;
+            // Reap abandoned operations: a process died with this op still "live".
+            const isLive = op.status === "pending" || op.status === "running";
+            const isStale = now - op.startedAt > ABANDONED_AFTER_MS;
+            if (isLive && isStale) {
+                const reaped = {
+                    ...op,
+                    status: "failed",
+                    finishedAt: now,
+                    error: {
+                        message: "Operation abandoned (process exited before completion)",
+                        code: "abandoned",
+                    },
+                };
+                writeJsonAtomic(fullPath, reaped);
+                this.byId.set(reaped.id, reaped);
+                if (reaped.idempotencyKey) {
+                    this.byIdempotencyKey.set(reaped.idempotencyKey, reaped.id);
+                }
+                logger.info(`[runtime-ops] Reaped abandoned operation on hydrate: ${reaped.id}`);
+                continue;
+            }
+            this.byId.set(op.id, op);
+            if (op.idempotencyKey) {
+                this.byIdempotencyKey.set(op.idempotencyKey, op.id);
+            }
+            if (isLive && !this.activeId) {
+                this.activeId = op.id;
+            }
+        }
+    }
+    pathFor(id) {
+        return path.join(this.dir, `${id}.json`);
+    }
+    persist(op) {
+        writeJsonAtomic(this.pathFor(op.id), op);
+    }
+    syncActiveSlot(op) {
+        const isLive = op.status === "pending" || op.status === "running";
+        if (isLive) {
+            this.activeId = op.id;
+            return;
+        }
+        if (this.activeId === op.id) {
+            this.activeId = null;
+        }
+    }
+    async create(op) {
+        this.hydrate();
+        if (this.byId.has(op.id)) {
+            throw new Error(`[runtime-ops] Operation already exists: ${op.id}`);
+        }
+        this.persist(op);
+        this.byId.set(op.id, op);
+        if (op.idempotencyKey) {
+            this.byIdempotencyKey.set(op.idempotencyKey, op.id);
+        }
+        this.syncActiveSlot(op);
+    }
+    async update(id, patch) {
+        this.hydrate();
+        const current = this.byId.get(id);
+        if (!current) {
+            throw new Error(`[runtime-ops] Operation not found: ${id}`);
+        }
+        const next = { ...current, ...patch };
+        this.persist(next);
+        this.byId.set(id, next);
+        this.syncActiveSlot(next);
+    }
+    async appendPhase(id, phase) {
+        this.hydrate();
+        const current = this.byId.get(id);
+        if (!current) {
+            throw new Error(`[runtime-ops] Operation not found: ${id}`);
+        }
+        const next = {
+            ...current,
+            phases: [...current.phases, phase],
+        };
+        this.persist(next);
+        this.byId.set(id, next);
+    }
+    async updateLastPhase(id, patch) {
+        this.hydrate();
+        const current = this.byId.get(id);
+        if (!current) {
+            throw new Error(`[runtime-ops] Operation not found: ${id}`);
+        }
+        if (current.phases.length === 0) {
+            throw new Error(`[runtime-ops] Cannot update last phase — no phases on op ${id}`);
+        }
+        const last = current.phases[current.phases.length - 1];
+        if (!last) {
+            throw new Error(`[runtime-ops] Cannot update last phase — phase array empty on ${id}`);
+        }
+        const merged = { ...last, ...patch };
+        const phases = [...current.phases.slice(0, -1), merged];
+        const next = { ...current, phases };
+        this.persist(next);
+        this.byId.set(id, next);
+    }
+    async get(id) {
+        this.hydrate();
+        return this.byId.get(id) ?? null;
+    }
+    async list(opts) {
+        this.hydrate();
+        let ops = Array.from(this.byId.values());
+        if (opts?.status) {
+            ops = ops.filter((o) => o.status === opts.status);
+        }
+        else if (opts?.includeTerminal === false) {
+            ops = ops.filter((o) => o.status === "pending" || o.status === "running");
+        }
+        ops.sort((a, b) => b.startedAt - a.startedAt);
+        if (typeof opts?.limit === "number" && opts.limit >= 0) {
+            ops = ops.slice(0, opts.limit);
+        }
+        return ops;
+    }
+    async findByIdempotencyKey(key) {
+        this.hydrate();
+        const id = this.byIdempotencyKey.get(key);
+        if (!id)
+            return null;
+        const op = this.byId.get(id);
+        if (!op)
+            return null;
+        if (Date.now() - op.startedAt > IDEMPOTENCY_RETENTION_MS) {
+            return null;
+        }
+        return op;
+    }
+    async findActive() {
+        this.hydrate();
+        if (!this.activeId)
+            return null;
+        const op = this.byId.get(this.activeId);
+        if (!op) {
+            this.activeId = null;
+            return null;
+        }
+        if (op.status !== "pending" && op.status !== "running") {
+            this.activeId = null;
+            return null;
+        }
+        return op;
+    }
+}
+let cachedDefault = null;
+/**
+ * Lazy per-process singleton. Constructed on first call so tests can swap
+ * the env or provide their own repository before the manager is built.
+ */
+export function getDefaultRepository() {
+    if (!cachedDefault) {
+        cachedDefault = new FilesystemRuntimeOperationRepository();
+    }
+    return cachedDefault;
+}

package/packages/agent/src/runtime/operations/types.d.ts

@@ -0,0 +1,201 @@
+/**
+ * RuntimeOperation contracts — the single model for any state-changing
+ * lifecycle action against the live runtime (provider switch, plugin
+ * enable/disable, config reload, full restart).
+ *
+ * Design invariants (see docs/architecture/runtime-operations.md once written):
+ *
+ *   1. Single queue. One operation runs at a time, full-stop. New requests
+ *      while an op is running return 409 with the active op's id.
+ *   2. Tiered execution. The use case classifies an intent into a reload
+ *      tier (hot / warm / cold). Most provider switches collapse to hot
+ *      or warm; only plugin allowlist changes go cold.
+ *   3. Health-gated promotion. A new runtime (cold) or a re-initialised
+ *      plugin (warm) only "wins" after health checks pass; failure rolls
+ *      back to the previous configuration.
+ *   4. Append-only phase log. Each phase mutation is a new entry — never
+ *      patched in place. This is the substrate for an event-log WS later.
+ *   5. Idempotency keys de-dupe retries. Same key in within the retention
+ *      window returns the existing operation record.
+ *
+ * This module exports types only. Implementations live in sibling files:
+ *   - manager.ts     — RuntimeOperationManager (the use case)
+ *   - repository.ts  — RuntimeOperationRepository (filesystem-backed)
+ *   - classifier.ts  — classifyOperation(intent) → ReloadTier
+ *   - health.ts      — HealthCheck registry + runner
+ *   - reload-hot.ts  — env-var swap + plugin notify
+ *   - reload-warm.ts — per-plugin reinit (Phase 2)
+ *   - reload-cold.ts — full runtime swap (delegates to existing handleRestart)
+ */
+import type { AgentRuntime } from "@elizaos/core";
+export interface ProviderSwitchIntent {
+    kind: "provider-switch";
+    provider: string;
+    apiKey?: string;
+    primaryModel?: string;
+}
+export interface ConfigReloadIntent {
+    kind: "config-reload";
+    /**
+     * Optional list of dotted config paths that changed. When present, the
+     * classifier can choose hot/warm based on which keys moved.
+     */
+    changedPaths?: readonly string[];
+}
+export interface PluginEnableIntent {
+    kind: "plugin-enable";
+    pluginId: string;
+}
+export interface PluginDisableIntent {
+    kind: "plugin-disable";
+    pluginId: string;
+}
+export interface RestartIntent {
+    kind: "restart";
+    reason: string;
+}
+export type OperationIntent = ProviderSwitchIntent | ConfigReloadIntent | PluginEnableIntent | PluginDisableIntent | RestartIntent;
+export type OperationKind = OperationIntent["kind"];
+/**
+ * Reload tiers, ordered by cost ascending.
+ *
+ *   hot  — env-var or in-memory swap; plugins notified via callback.
+ *          Bounded ~100ms. No service lifecycle touched.
+ *   warm — re-init of one or more plugins' services. Bounded 1–3s.
+ *          Other plugins keep their state.
+ *   cold — full runtime swap (current handleRestart). 15–60s.
+ *
+ * The classifier MUST upgrade conservatively when uncertain: hot → warm,
+ * warm → cold. Downgrading a cold change to warm risks corrupt state.
+ */
+export type ReloadTier = "hot" | "warm" | "cold";
+export type OperationStatus = "pending" | "running" | "succeeded" | "failed" | "rolled-back";
+export type PhaseStatus = "pending" | "running" | "succeeded" | "failed" | "skipped";
+export interface OperationError {
+    message: string;
+    code?: string;
+    cause?: string;
+}
+export interface OperationPhase {
+    /** Stable phase name — e.g. "validate", "persist-config", "health-check". */
+    name: string;
+    status: PhaseStatus;
+    startedAt?: number;
+    finishedAt?: number;
+    error?: OperationError;
+    /** Optional structured detail surfaced to the UI / logs. */
+    detail?: Record<string, unknown>;
+}
+export interface RuntimeOperation {
+    id: string;
+    kind: OperationKind;
+    intent: OperationIntent;
+    tier: ReloadTier;
+    idempotencyKey?: string;
+    status: OperationStatus;
+    phases: OperationPhase[];
+    fromConfigVersion?: number;
+    toConfigVersion?: number;
+    startedAt: number;
+    finishedAt?: number;
+    error?: OperationError;
+}
+export interface RuntimeOperationListOptions {
+    limit?: number;
+    status?: OperationStatus;
+    /** When true, include rolled-back / failed ops in the result. */
+    includeTerminal?: boolean;
+}
+export interface RuntimeOperationRepository {
+    create(op: RuntimeOperation): Promise<void>;
+    /**
+     * Patch top-level fields. Phases are append-only — use appendPhase /
+     * updatePhase for those.
+     */
+    update(id: string, patch: Partial<Omit<RuntimeOperation, "id" | "phases" | "intent" | "kind">>): Promise<void>;
+    appendPhase(id: string, phase: OperationPhase): Promise<void>;
+    /**
+     * Update the LAST phase only (for transitioning pending → running →
+     * succeeded). Earlier phases are immutable once finished.
+     */
+    updateLastPhase(id: string, patch: Partial<OperationPhase>): Promise<void>;
+    get(id: string): Promise<RuntimeOperation | null>;
+    list(opts?: RuntimeOperationListOptions): Promise<RuntimeOperation[]>;
+    findByIdempotencyKey(key: string): Promise<RuntimeOperation | null>;
+    /** Returns the active (running) operation, if any. */
+    findActive(): Promise<RuntimeOperation | null>;
+}
+export type HealthCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    cause?: unknown;
+};
+export interface HealthCheck {
+    name: string;
+    /**
+     * Required checks block promotion. Optional checks are reported in the
+     * operation phase detail but do not fail the operation.
+     */
+    required: boolean;
+    /** Soft timeout in ms. The runner enforces it. */
+    timeoutMs: number;
+    run(runtime: AgentRuntime): Promise<HealthCheckResult>;
+}
+export interface HealthCheckReport {
+    passed: readonly {
+        name: string;
+        durationMs: number;
+    }[];
+    failed: readonly {
+        name: string;
+        required: boolean;
+        reason: string;
+        durationMs: number;
+    }[];
+    /** True only when every REQUIRED check passed. */
+    ok: boolean;
+}
+export interface ReloadContext {
+    runtime: AgentRuntime;
+    intent: OperationIntent;
+    /** Phase reporter — call for every meaningful step inside a strategy. */
+    reportPhase: (phase: OperationPhase) => Promise<void>;
+}
+export interface ReloadStrategy {
+    tier: ReloadTier;
+    /**
+     * Apply the change. Return the (possibly new) runtime to install as
+     * primary. For hot/warm, this is typically the same runtime; for cold,
+     * it's a freshly bootstrapped one.
+     */
+    apply(ctx: ReloadContext): Promise<AgentRuntime>;
+}
+export interface StartOperationRequest {
+    intent: OperationIntent;
+    idempotencyKey?: string;
+}
+export type StartOperationOutcome = 
+/** Newly accepted; will run async. Caller polls /events for status. */
+{
+    kind: "accepted";
+    operation: RuntimeOperation;
+}
+/** Idempotent hit — same key, same intent already in flight or done. */
+ | {
+    kind: "deduped";
+    operation: RuntimeOperation;
+}
+/** Another operation is currently active. Caller should retry later. */
+ | {
+    kind: "rejected-busy";
+    activeOperationId: string;
+};
+export interface RuntimeOperationManager {
+    start(req: StartOperationRequest): Promise<StartOperationOutcome>;
+    get(id: string): Promise<RuntimeOperation | null>;
+    list(opts?: RuntimeOperationListOptions): Promise<RuntimeOperation[]>;
+    findActive(): Promise<RuntimeOperation | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/agent/src/runtime/operations/types.d.ts.map

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

package/packages/agent/src/runtime/operations/types.js

@@ -0,0 +1,30 @@
+/**
+ * RuntimeOperation contracts — the single model for any state-changing
+ * lifecycle action against the live runtime (provider switch, plugin
+ * enable/disable, config reload, full restart).
+ *
+ * Design invariants (see docs/architecture/runtime-operations.md once written):
+ *
+ *   1. Single queue. One operation runs at a time, full-stop. New requests
+ *      while an op is running return 409 with the active op's id.
+ *   2. Tiered execution. The use case classifies an intent into a reload
+ *      tier (hot / warm / cold). Most provider switches collapse to hot
+ *      or warm; only plugin allowlist changes go cold.
+ *   3. Health-gated promotion. A new runtime (cold) or a re-initialised
+ *      plugin (warm) only "wins" after health checks pass; failure rolls
+ *      back to the previous configuration.
+ *   4. Append-only phase log. Each phase mutation is a new entry — never
+ *      patched in place. This is the substrate for an event-log WS later.
+ *   5. Idempotency keys de-dupe retries. Same key in within the retention
+ *      window returns the existing operation record.
+ *
+ * This module exports types only. Implementations live in sibling files:
+ *   - manager.ts     — RuntimeOperationManager (the use case)
+ *   - repository.ts  — RuntimeOperationRepository (filesystem-backed)
+ *   - classifier.ts  — classifyOperation(intent) → ReloadTier
+ *   - health.ts      — HealthCheck registry + runner
+ *   - reload-hot.ts  — env-var swap + plugin notify
+ *   - reload-warm.ts — per-plugin reinit (Phase 2)
+ *   - reload-cold.ts — full runtime swap (delegates to existing handleRestart)
+ */
+export {};

package/packages/agent/src/runtime/plugin-collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-collector.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/plugin-collector.ts"],"names":[],"mappings":"AAoDA;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErE;AAQD,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsB/D,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBhE,CAAC;AAeF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4ChE,CAAC;AAMF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC"}
+{"version":3,"file":"plugin-collector.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/plugin-collector.ts"],"names":[],"mappings":"AAyDA;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErE;AAQD,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsB/D,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBhE,CAAC;AAeF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4ChE,CAAC;AAMF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC"}

package/packages/agent/src/runtime/plugin-collector.js

@@ -12,8 +12,8 @@
  *
  * @module plugin-collector
  */
-import { hasExplicitCanonicalRuntimeConfig, migrateLegacyRuntimeConfig, resolveDeploymentTargetInConfig, resolveElizaCloudTopology, resolveServiceRoutingInConfig, } from "@elizaos/shared";
-import { CORE_PLUGINS, OPTIONAL_CORE_PLUGINS } from "./core-plugins.js";
+import { hasExplicitCanonicalRuntimeConfig, isMobilePlatform, migrateLegacyRuntimeConfig, resolveDeploymentTargetInConfig, resolveElizaCloudTopology, resolveServiceRoutingInConfig, } from "@elizaos/shared";
+import { CORE_PLUGINS, MOBILE_CORE_PLUGINS, OPTIONAL_CORE_PLUGINS, } from "./core-plugins.js";
 const OPTIONAL_CORE_PLUGIN_NAMES = new Set(OPTIONAL_CORE_PLUGINS);
 /**
  * Agent orchestrator ships as the standalone @elizaos/plugin-agent-orchestrator package;
@@ -142,7 +142,7 @@ export const OPTIONAL_PLUGIN_MAP = {
     bluebubbles: "@elizaos/plugin-bluebubbles",
     discordLocal: "@elizaos/plugin-discord-local",
     x402: "@elizaos/plugin-x402",
-    // plugin-manager, secrets-manager, trust: now built-in core capabilities
+    // plugin-manager, secrets (SECRETS), trust: now built-in core capabilities
     // Enable via ENABLE_PLUGIN_MANAGER, ENABLE_SECRETS_MANAGER, ENABLE_TRUST
     "streaming-base": "@elizaos/plugin-streaming-base",
     "twitch-streaming": "@elizaos/plugin-twitch-streaming",
@@ -181,6 +181,16 @@ export function collectPluginNames(config, reasons) {
     const hasCanonicalRuntimeConfig = hasExplicitCanonicalRuntimeConfig(config);
     const isCloudContainer = process.env.ELIZA_CLOUD_PROVISIONED === "1";
     const cloudExplicitlyDisabled = config.cloud?.enabled === false;
+    // `MILADY_LOCAL_LLAMA=1` is the AOSP / on-device signal that the in-process
+    // llama.cpp loader is wired up and should be available as a routable
+    // provider. It does NOT mean "strip every other provider": subscription
+    // accounts (anthropic-subscription, openai-codex) and API-key cloud
+    // plugins must keep loading so the user can route slots to them.
+    // The local handler already registers at priority -1 (see
+    // ensure-local-inference-handler.ts), so cloud/direct providers win when
+    // the user has them configured, and local fills in otherwise.
+    // TODO(local-only-mode): introduce a separate explicit opt-in flag (e.g.
+    // `MILADY_LOCAL_ONLY=1`) for users who want all-cloud-providers stripped.
     const localOnlyInference = legacyLocalOnlyInference ||
         (cloudExplicitlyDisabled &&
             deploymentTarget.runtime === "local" &&
@@ -220,14 +230,24 @@ export function collectPluginNames(config, reasons) {
     const hasExplicitEnabledProvider = explicitProviderEntries.some(([, entry]) => entry?.enabled === true);
     // Allow-list entries are additive (extra plugins), not exclusive.
     const allowList = config.plugins?.allow;
-    const pluginsToLoad = new Set(CORE_PLUGINS);
+    // On mobile (MILADY_PLATFORM=android|ios) the desktop core list pulls in
+    // ~10 plugins that depend on subprocesses (n8n, signal-cli), platform
+    // launchers (/usr/bin/open, osascript, xdg-open), or PTY tooling — all
+    // unavailable in the app sandbox. Substitute the curated mobile-safe set.
+    const onMobile = isMobilePlatform();
+    const seedCorePlugins = onMobile ? MOBILE_CORE_PLUGINS : CORE_PLUGINS;
+    const pluginsToLoad = new Set(seedCorePlugins);
     const track = (name, reason) => {
         if (reasons && !reasons.has(name))
             reasons.set(name, reason);
     };
-    for (const core of CORE_PLUGINS)
-        track(core, "CORE_PLUGINS");
-    if (orchestratorCompatPluginRequested(config)) {
+    for (const core of seedCorePlugins) {
+        track(core, onMobile ? "MOBILE_CORE_PLUGINS" : "CORE_PLUGINS");
+    }
+    // Agent orchestrator depends on PTY / coding-swarm subprocesses (none of
+    // which exist on Android / iOS), so always skip it on mobile regardless of
+    // the stored ELIZA_AGENT_ORCHESTRATOR / config preference.
+    if (!onMobile && orchestratorCompatPluginRequested(config)) {
         pluginsToLoad.add("agent-orchestrator");
         track("agent-orchestrator", "agent-orchestrator (@elizaos/plugin-agent-orchestrator)");
     }
@@ -396,6 +416,26 @@ export function collectPluginNames(config, reasons) {
             pluginsToLoad.delete(pluginName);
         }
     }
+    // Mobile: restrict the final set to plugins that the bundled mobile runtime
+    // can actually load — the mobile-core list plus model-provider plugins that
+    // are statically imported in `runtime/eliza.ts`. Anything else (connector
+    // plugins, feature plugins from `plugins.entries`, drop-in plugins from
+    // `plugins.installs`) would force a dynamic `import("@elizaos/plugin-...")`
+    // against a `node_modules` tree that does not ship in the APK.
+    if (onMobile) {
+        const mobileAllowed = new Set([
+            ...MOBILE_CORE_PLUGINS,
+            "@elizaos/plugin-anthropic",
+            "@elizaos/plugin-openai",
+            "@elizaos/plugin-ollama",
+            "@elizaos/plugin-elizacloud",
+        ]);
+        for (const pluginName of Array.from(pluginsToLoad)) {
+            if (!mobileAllowed.has(pluginName)) {
+                pluginsToLoad.delete(pluginName);
+            }
+        }
+    }
     return pluginsToLoad;
 }
 function resolveCloudPluginRequirement(topology, requestedByEnv) {

package/packages/agent/src/runtime/plugin-role-gating.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-role-gating.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/plugin-role-gating.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAIV,MAAM,EAIP,MAAM,eAAe,CAAC;AAGvB,KAAK,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAY3C,QAAA,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAwC1D,CAAC;AAOF,QAAA,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CA0D7D,CAAC;AAOF,QAAA,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAyB/D,CAAC;AA4FF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CA+C7D;AAED,4BAA4B;AAC5B,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"plugin-role-gating.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/plugin-role-gating.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAIV,MAAM,EAIP,MAAM,eAAe,CAAC;AAGvB,KAAK,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAY3C,QAAA,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CA8C1D,CAAC;AAOF,QAAA,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CA0D7D,CAAC;AAOF,QAAA,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CA0C/D,CAAC;AA+GF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CA+C7D;AAED,4BAA4B;AAC5B,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,CAAC"}