@elizaos/app-core 2.0.0-alpha.85 → 2.0.0-beta.1

package/runtime/ensure-local-inference-handler.js

@@ -0,0 +1,380 @@
+/**
+ * Registers the standalone llama.cpp engine as the runtime handler for
+ * `ModelType.TEXT_SMALL` and `ModelType.TEXT_LARGE`.
+ *
+ * Priority is 0 — same band as cloud and direct provider plugins. Tie-breaks
+ * between local and cloud are owned by the routing-policy layer
+ * (`router-handler.ts` + `routing-policy.ts`), not by this priority value:
+ * the router sits at MAX_SAFE_INTEGER and consults the user's policy
+ * (manual / cheapest / fastest / prefer-local / round-robin) on every call.
+ *
+ * Until the cuttlefish smoke landed this was -1 to "let cloud win by default,"
+ * but that conflated routing-policy (a user preference) with handler
+ * priority (a registration ordinal). The runtime's getModel() returns
+ * undefined when no priority-0 handler is registered, which manifested as
+ * "No handler found for delegate type: TEXT_SMALL" on AOSP builds where
+ * the AOSP local inference loader is the only provider. Both cloud-only and
+ * local-only deployments now have a registered priority-0 handler; the
+ * router decides which one fires per request.
+ *
+ * Parallels `ensure-text-to-speech-handler.ts` — same shape, same guards.
+ */
+import { logger, ModelType, } from "@elizaos/core";
+import { resolveLocalInferenceLoadArgs, } from "../services/local-inference/active-model";
+import { autoAssignAtBoot, readEffectiveAssignments, } from "../services/local-inference/assignments";
+import { extractConversationId, extractPromptCacheKey, resolveLocalCacheKey, } from "../services/local-inference/cache-bridge";
+import { deviceBridge } from "../services/local-inference/device-bridge";
+import { localInferenceEngine } from "../services/local-inference/engine";
+import { handlerRegistry } from "../services/local-inference/handler-registry";
+import { listInstalledModels } from "../services/local-inference/registry";
+import { installRouterHandler } from "../services/local-inference/router-handler";
+const LOCAL_INFERENCE_PROVIDER = "eliza-local-inference";
+const DEVICE_BRIDGE_PROVIDER = "eliza-device-bridge";
+const CAPACITOR_LLAMA_PROVIDER = "capacitor-llama";
+const AOSP_LLAMA_PROVIDER = "eliza-aosp-llama";
+/**
+ * Same band as cloud / direct provider plugins. Tie-breaks between
+ * candidates live in `routing-policy.ts`, not in this number — the
+ * router (registered at MAX_SAFE_INTEGER) consults the user's
+ * per-slot policy on every dispatch.
+ *
+ * Was -1 historically, which made `runtime.getModel(TEXT_SMALL)` return
+ * undefined when the AOSP local-inference loader was the only registered
+ * provider. The smoke run failed with "No handler found for delegate
+ * type: TEXT_SMALL"; bumping to 0 unblocks AOSP without changing
+ * cloud-only deployments (cloud providers still register at 0 and the
+ * routing-policy layer picks between them).
+ */
+const LOCAL_INFERENCE_PRIORITY = 0;
+function getLoader(runtime) {
+    const candidate = runtime.getService?.("localInferenceLoader");
+    if (!candidate || typeof candidate !== "object")
+        return null;
+    const loader = candidate;
+    if (typeof loader.loadModel === "function" &&
+        typeof loader.unloadModel === "function") {
+        return candidate;
+    }
+    return null;
+}
+/**
+ * Look up the model assigned to a given agent slot and ensure it's the
+ * one loaded before generation runs. Loads lazily on first call; swaps
+ * when a different slot's assignment fires with a different model.
+ *
+ * If no assignment is set for the slot, falls back to whatever is
+ * currently loaded (keeps the old "one active model" behaviour).
+ */
+async function ensureAssignedModelLoaded(loader, slot) {
+    const assignments = await readEffectiveAssignments();
+    const assignedId = assignments[slot];
+    if (!assignedId)
+        return;
+    // Desktop fast path: check the engine state directly.
+    if (!loader && localInferenceEngine.currentModelPath()) {
+        const installed = await listInstalledModels();
+        const current = installed.find((m) => m.path === localInferenceEngine.currentModelPath());
+        if (current?.id === assignedId)
+            return;
+    }
+    // Via loader: compare reported path against assignment.
+    if (loader) {
+        const currentPath = loader.currentModelPath();
+        if (currentPath) {
+            const installed = await listInstalledModels();
+            const current = installed.find((m) => m.path === currentPath);
+            if (current?.id === assignedId)
+                return;
+        }
+    }
+    const installed = await listInstalledModels();
+    const target = installed.find((m) => m.id === assignedId);
+    if (!target) {
+        throw new Error(`[local-inference] Slot ${slot} assigned to ${assignedId}, but that model is not installed.`);
+    }
+    if (loader) {
+        await loader.unloadModel();
+        await loader.loadModel(await resolveLocalInferenceLoadArgs(target));
+    }
+    else {
+        await localInferenceEngine.load(target.path);
+    }
+}
+function makeHandler(slot) {
+    return async (runtime, params) => {
+        const loader = getLoader(runtime);
+        // Lazy-load the assigned model for this slot, if any. Swaps are
+        // expensive; the user is expected to assign a small number of models.
+        await ensureAssignedModelLoaded(loader, slot);
+        // Resolve the strongest cache key the runtime can give us. Order of
+        // precedence (see `resolveLocalCacheKey`):
+        //   1. Conversation id   — survives any prompt drift
+        //   2. Stable-prefix hash — survives unstable-tail timestamps
+        //   3. Provider plan hashes — back-compat
+        const providerOptions = params
+            .providerOptions;
+        const conversationId = extractConversationId(providerOptions);
+        const cacheKey = resolveLocalCacheKey(providerOptions) ??
+            extractPromptCacheKey(providerOptions) ??
+            undefined;
+        // Prefer a runtime-registered loader that implements `generate` — that's
+        // the mobile / device-bridge path. On desktop we fall back to the
+        // standalone engine.
+        if (loader?.generate) {
+            return loader.generate({
+                prompt: params.prompt ?? "",
+                stopSequences: params.stopSequences,
+                cacheKey,
+            });
+        }
+        if (!(await localInferenceEngine.available())) {
+            throw new Error(`[local-inference] No llama.cpp binding available for ${slot} request`);
+        }
+        if (!localInferenceEngine.hasLoadedModel()) {
+            throw new Error(`[local-inference] No local model is active. Assign a model to ${slot} or activate one in Settings → Local models.`);
+        }
+        // Long-lived conversation? Open / reuse a registry handle so this
+        // turn lands on the same slot every time, regardless of prompt
+        // hash drift. The handle API additionally returns Anthropic-shape
+        // usage telemetry, which we surface at INFO once per generation.
+        if (conversationId) {
+            const modelId = localInferenceEngine.currentModelPath() ?? "default-local-model";
+            const handle = localInferenceEngine.conversation(conversationId, modelId) ??
+                localInferenceEngine.openConversation({
+                    conversationId,
+                    modelId,
+                });
+            const result = await localInferenceEngine.generateInConversation(handle, {
+                prompt: params.prompt ?? "",
+                stopSequences: params.stopSequences,
+            });
+            // Per-generation usage log. Match the Anthropic plugin's
+            // observability surface so cloud and local share the same
+            // mental model. Cache hit rate is reported when input_tokens > 0.
+            const u = result.usage;
+            const hitRate = u.cache_hit_rate !== undefined
+                ? `${Math.round(u.cache_hit_rate * 100)}%`
+                : "n/a";
+            const dflashRate = u.dflash_acceptance_rate !== undefined
+                ? ` dflash=${Math.round(u.dflash_acceptance_rate * 100)}%`
+                : "";
+            logger.info(`[local-inference] usage conv=${conversationId} slot=${result.slotId} in=${u.input_tokens} out=${u.output_tokens} cache_read=${u.cache_read_input_tokens} cache_create=${u.cache_creation_input_tokens} hit=${hitRate}${dflashRate}`);
+            // Auto-tune signal — emits a one-line warn if the high-water mark
+            // outgrew the configured slot count this turn. Cheap to call,
+            // and the warning is what the operator needs to see.
+            localInferenceEngine.warnIfParallelTooLow({ warn: logger.warn });
+            return result.text;
+        }
+        // No conversation context: fall through to the existing hash-based
+        // slot allocation. Doesn't break any caller that wasn't aware of
+        // conversation handles.
+        return localInferenceEngine.generate({
+            prompt: params.prompt ?? "",
+            stopSequences: params.stopSequences,
+            cacheKey,
+        });
+    };
+}
+/**
+ * Normalize the runtime's TEXT_EMBEDDING input shape — `params` may be the
+ * structured `TextEmbeddingParams` (when called from a typed plugin), a
+ * raw string (when called from action runners), or `null` (an internal
+ * warmup probe used to size the shipped embedding vector).
+ */
+function extractEmbeddingText(params) {
+    if (params === null)
+        return "";
+    if (typeof params === "string")
+        return params;
+    return params.text;
+}
+/**
+ * Build the TEXT_EMBEDDING handler. Mirrors `makeHandler` for generate:
+ * routes through the loader's `embed` if available, otherwise throws so
+ * the runtime falls back to a non-local provider rather than serving a
+ * silent zero-vector (Commandment 8: don't hide broken pipelines).
+ */
+function makeEmbeddingHandler() {
+    return async (runtime, params) => {
+        const loader = getLoader(runtime);
+        if (!loader?.embed) {
+            throw new Error("[local-inference] Active loader does not implement embed; falling through to next provider");
+        }
+        // Embeddings in this runtime are not slot-aware — there's a single
+        // active model. Make sure the user's TEXT_EMBEDDING assignment, if
+        // any, is loaded before we hit the loader.
+        await ensureAssignedModelLoaded(loader, "TEXT_EMBEDDING");
+        const text = extractEmbeddingText(params);
+        const result = await loader.embed({ input: text });
+        return result.embedding;
+    };
+}
+/**
+ * Register the device-bridge loader on the runtime. Accepts load/generate
+ * calls whether or not a mobile device is currently connected — parked
+ * calls resolve on reconnect (up to a timeout). Cheaper than waiting for
+ * the first device register to register the service: ordering is already
+ * handled inside `DeviceBridge.generate`.
+ */
+function registerDeviceBridgeLoader(runtime) {
+    const withRegistration = runtime;
+    if (typeof withRegistration.registerService !== "function")
+        return;
+    const loader = {
+        loadModel: (args) => deviceBridge.loadModel(args),
+        unloadModel: () => deviceBridge.unloadModel(),
+        currentModelPath: () => deviceBridge.currentModelPath(),
+        generate: (args) => deviceBridge.generate(args),
+        embed: (args) => deviceBridge.embed(args),
+    };
+    withRegistration.registerService("localInferenceLoader", loader);
+}
+/**
+ * AOSP-only path: load `libllama.so` directly into the bun process via
+ * `bun:ffi`. The adapter no-ops at runtime when `ELIZA_LOCAL_LLAMA !== "1"`,
+ * so the dynamic import below is safe on every platform; we only attempt
+ * registration when the user explicitly opted in.
+ *
+ * The `try`/`catch` is justified because the AOSP build can ship the .so on
+ * one ABI but be invoked on another (e.g. cuttlefish_x86_64 reporting both
+ * x86_64 and arm64-v8a). When `ELIZA_LOCAL_LLAMA=1` is set but registration
+ * fails, the adapter logs at `error` level — we must NOT silently fall
+ * through to the device-bridge or stock engine: the operator opted in and
+ * deserves the failure surfaced clearly.
+ */
+async function tryRegisterAospLlamaLoader(runtime) {
+    if (process.env.ELIZA_LOCAL_LLAMA?.trim() !== "1")
+        return false;
+    try {
+        const mod = (await import("@elizaos/plugin-aosp-local-inference"));
+        if (typeof mod.registerAospLlamaLoader !== "function") {
+            logger.error("[local-inference] AOSP llama adapter import resolved but missing registerAospLlamaLoader export");
+            return false;
+        }
+        const result = await mod.registerAospLlamaLoader(runtime);
+        return Boolean(result);
+    }
+    catch (err) {
+        logger.error("[local-inference] AOSP llama adapter unavailable while ELIZA_LOCAL_LLAMA=1:", err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
+async function tryRegisterCapacitorLoader(runtime) {
+    // Only meaningful under Capacitor (iOS/Android). Dynamic import so web /
+    // desktop bundlers don't choke on the native plugin metadata.
+    const cap = globalThis.Capacitor;
+    if (!cap?.isNativePlatform?.())
+        return false;
+    try {
+        const { registerCapacitorLlamaLoader } = await import("@elizaos/capacitor-llama");
+        const capacitorRuntime = Object.create(runtime);
+        registerCapacitorLlamaLoader(capacitorRuntime);
+        logger.info("[local-inference] Registered capacitor-llama loader for mobile on-device inference");
+        return true;
+    }
+    catch (err) {
+        logger.debug("[local-inference] capacitor-llama not available:", err instanceof Error ? err.message : String(err));
+    }
+    return false;
+}
+export async function ensureLocalInferenceHandler(runtime) {
+    const runtimeWithRegistration = runtime;
+    if (typeof runtimeWithRegistration.getModel !== "function" ||
+        typeof runtimeWithRegistration.registerModel !== "function") {
+        return;
+    }
+    // Install the side-registry interception as early as possible so it
+    // captures every subsequent `registerModel` call — including our own
+    // handlers below, plus anything else that registers during the rest of
+    // boot. Idempotent per-runtime.
+    handlerRegistry.installOn(runtime);
+    // Loader precedence:
+    //   1. AOSP native FFI loader when running inside the AOSP agent process
+    //      itself (ELIZA_LOCAL_LLAMA=1). This is the canonical AOSP path —
+    //      libllama.so is dlopen'd directly, no IPC.
+    //   2. Capacitor native adapter when running on a mobile device with the
+    //      Capacitor APK shell.
+    //   3. Device-bridge (WebSocket to a paired phone) when explicitly
+    //      opted in via ELIZA_DEVICE_BRIDGE_ENABLED=1.
+    //   4. Standalone node-llama-cpp engine for desktop / server.
+    //
+    // All four satisfy the same `localInferenceLoader` service contract.
+    // A later registration overrides an earlier one, so we register in
+    // LOWEST-priority order first; the AOSP loader runs last so it wins on
+    // AOSP builds. Each `try*Loader` is idempotent and gated on its own env
+    // signal, so they're safe to chain.
+    const aospRegistered = await tryRegisterAospLlamaLoader(runtime);
+    const capacitorRegistered = !aospRegistered && (await tryRegisterCapacitorLoader(runtime));
+    const deviceBridgeEnabled = process.env.ELIZA_DEVICE_BRIDGE_ENABLED?.trim() === "1";
+    if (!aospRegistered && !capacitorRegistered && deviceBridgeEnabled) {
+        registerDeviceBridgeLoader(runtime);
+        logger.info("[local-inference] Registered device-bridge loader; inference routes to paired mobile device when connected");
+    }
+    // Pre-flight: if no backend is available, skip handler registration
+    // entirely so we don't advertise a handler that will throw. The device
+    // bridge is always "available" in the sense that it parks calls until a
+    // device connects, so if it is enabled we always register handlers.
+    if (!aospRegistered &&
+        !capacitorRegistered &&
+        !deviceBridgeEnabled &&
+        !(await localInferenceEngine.available())) {
+        logger.debug("[local-inference] No local inference backend available; skipping model registration");
+        return;
+    }
+    // First-light convenience: when exactly one model is installed and no
+    // slot assignments exist, auto-fill TEXT_SMALL/TEXT_LARGE so the user
+    // lands in chat without opening Settings. The downloader handles the
+    // post-install case; this catches the user who pre-staged a model
+    // (external scan, prior install) and is now booting fresh.
+    try {
+        const installed = await listInstalledModels();
+        const filled = await autoAssignAtBoot(installed);
+        if (filled) {
+            logger.info(`[local-inference] Auto-assigned single installed model to empty slots: ${JSON.stringify(filled)}`);
+        }
+    }
+    catch (err) {
+        logger.warn("[local-inference] autoAssignAtBoot failed:", err instanceof Error ? err.message : String(err));
+    }
+    const provider = aospRegistered
+        ? AOSP_LLAMA_PROVIDER
+        : capacitorRegistered
+            ? CAPACITOR_LLAMA_PROVIDER
+            : deviceBridgeEnabled
+                ? DEVICE_BRIDGE_PROVIDER
+                : LOCAL_INFERENCE_PROVIDER;
+    const slots = [
+        [ModelType.TEXT_SMALL, "TEXT_SMALL"],
+        [ModelType.TEXT_LARGE, "TEXT_LARGE"],
+    ];
+    for (const [modelType, slot] of slots) {
+        try {
+            runtimeWithRegistration.registerModel(modelType, makeHandler(slot), provider, LOCAL_INFERENCE_PRIORITY);
+        }
+        catch (err) {
+            logger.warn("[local-inference] Could not register ModelType", modelType, err instanceof Error ? err.message : String(err));
+        }
+    }
+    // Register TEXT_EMBEDDING separately — the runtime contract returns
+    // `number[]` instead of `string`, so it can't share `makeHandler`. We
+    // only register when the active loader actually exposes `embed`;
+    // otherwise the runtime should fall through to the operator-configured
+    // embedding provider.
+    const loaderForEmbed = runtime.getService?.("localInferenceLoader");
+    if (loaderForEmbed && typeof loaderForEmbed.embed === "function") {
+        try {
+            runtimeWithRegistration.registerModel(ModelType.TEXT_EMBEDDING, makeEmbeddingHandler(), provider, LOCAL_INFERENCE_PRIORITY);
+            logger.info(`[local-inference] Registered ${provider} embedding handler for TEXT_EMBEDDING at priority ${LOCAL_INFERENCE_PRIORITY}`);
+        }
+        catch (err) {
+            logger.warn("[local-inference] Could not register TEXT_EMBEDDING handler", err instanceof Error ? err.message : String(err));
+        }
+    }
+    logger.info(`[local-inference] Registered ${provider} llama.cpp handler for TEXT_SMALL / TEXT_LARGE at priority ${LOCAL_INFERENCE_PRIORITY}`);
+    // Install the top-priority router AFTER everything else has registered.
+    // The router sits at Number.MAX_SAFE_INTEGER so the runtime dispatches
+    // to it first; at dispatch time it picks a real provider via
+    // `routing-policy` and calls that handler directly.
+    installRouterHandler(runtime);
+    logger.info("[local-inference] Installed top-priority router for cross-provider routing");
+}

package/runtime/ensure-text-to-speech-handler.d.ts

@@ -0,0 +1,18 @@
+import { type AgentRuntime } from "@elizaos/core";
+export interface EdgeTtsConfig {
+    plugins?: {
+        entries?: {
+            "edge-tts"?: {
+                enabled?: boolean;
+            };
+        };
+    };
+}
+export declare function isEdgeTtsDisabled(config: EdgeTtsConfig): boolean;
+/**
+ * `@elizaos/agent` boot calls its own `collectPluginNames`, so the app wrapper
+ * that adds Edge TTS is bypassed. Register the Edge TTS model handler on the
+ * live runtime so streaming / swarm voice can still resolve TEXT_TO_SPEECH.
+ */
+export declare function ensureTextToSpeechHandler(runtime: AgentRuntime): Promise<void>;
+//# sourceMappingURL=ensure-text-to-speech-handler.d.ts.map

package/runtime/ensure-text-to-speech-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-text-to-speech-handler.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/ensure-text-to-speech-handler.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,YAAY,EAAqB,MAAM,eAAe,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE;YACR,UAAU,CAAC,EAAE;gBACX,OAAO,CAAC,EAAE,OAAO,CAAC;aACnB,CAAC;SACH,CAAC;KACH,CAAC;CACH;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAYhE;AA6BD;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CA6Cf"}

package/runtime/ensure-text-to-speech-handler.js

@@ -0,0 +1,50 @@
+import process from "node:process";
+import { loadElizaConfig } from "@elizaos/agent";
+import { logger, ModelType } from "@elizaos/core";
+export function isEdgeTtsDisabled(config) {
+    if (config.plugins?.entries?.["edge-tts"]?.enabled === false) {
+        return true;
+    }
+    const raw = process?.env ? process.env.ELIZA_DISABLE_EDGE_TTS : undefined;
+    if (!raw || typeof raw !== "string") {
+        return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+function readHandler(plugin) {
+    const handler = plugin?.models?.[ModelType.TEXT_TO_SPEECH];
+    return typeof handler === "function" ? handler : undefined;
+}
+/**
+ * `@elizaos/agent` boot calls its own `collectPluginNames`, so the app wrapper
+ * that adds Edge TTS is bypassed. Register the Edge TTS model handler on the
+ * live runtime so streaming / swarm voice can still resolve TEXT_TO_SPEECH.
+ */
+export async function ensureTextToSpeechHandler(runtime) {
+    const config = loadElizaConfig();
+    if (isEdgeTtsDisabled(config)) {
+        return;
+    }
+    const runtimeWithRegistration = runtime;
+    if (typeof runtimeWithRegistration.getModel !== "function" ||
+        typeof runtimeWithRegistration.registerModel !== "function") {
+        return;
+    }
+    const existing = runtimeWithRegistration.getModel(ModelType.TEXT_TO_SPEECH);
+    if (existing) {
+        return;
+    }
+    try {
+        const nodeModule = (await import("@elizaos/plugin-edge-tts"));
+        const handler = readHandler(nodeModule.default);
+        if (!handler) {
+            throw new Error("@elizaos/plugin-edge-tts did not expose a TEXT_TO_SPEECH handler");
+        }
+        runtimeWithRegistration.registerModel(ModelType.TEXT_TO_SPEECH, handler, "edge-tts", 0);
+        logger.info("[eliza] Registered Edge TTS for runtime TEXT_TO_SPEECH (streaming / swarm voice)");
+    }
+    catch (error) {
+        throw new Error(`[eliza] Could not register Edge TTS for TEXT_TO_SPEECH: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/runtime/error-handlers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared error-formatting utilities for global process handlers.
+ * Used by both the CLI (run-main.ts) and the dev-server (dev-server.ts).
+ * Intentionally dependency-free — only string operations.
+ */
+export declare function formatUncaughtError(error: unknown): string;
+/**
+ * Returns `true` when the rejection looks like an AI provider credit-exhaustion
+ * error — these are noisy but not fatal, so callers should warn instead of crash.
+ */
+export declare function shouldIgnoreUnhandledRejection(reason: unknown): boolean;
+//# sourceMappingURL=error-handlers.d.ts.map

package/runtime/error-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handlers.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/error-handlers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAK1D;AAQD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAyCvE"}

package/runtime/error-handlers.js

@@ -0,0 +1,49 @@
+/**
+ * Shared error-formatting utilities for global process handlers.
+ * Used by both the CLI (run-main.ts) and the dev-server (dev-server.ts).
+ * Intentionally dependency-free — only string operations.
+ */
+export function formatUncaughtError(error) {
+    if (error instanceof Error) {
+        return error.stack ?? error.message;
+    }
+    return String(error);
+}
+function hasInsufficientCreditsSignal(input) {
+    return /\b(insufficient(?:[_\s]+(?:credits?|quota))|insufficient_quota|out of credits|payment required|statuscode:\s*402)\b/i.test(input);
+}
+/**
+ * Returns `true` when the rejection looks like an AI provider credit-exhaustion
+ * error — these are noisy but not fatal, so callers should warn instead of crash.
+ */
+export function shouldIgnoreUnhandledRejection(reason) {
+    const formatted = formatUncaughtError(reason);
+    if (!/AI_NoOutputGeneratedError|No output generated|AI_APICallError|AI_RetryError/i.test(formatted)) {
+        return false;
+    }
+    if (hasInsufficientCreditsSignal(formatted)) {
+        return true;
+    }
+    const seen = new Set();
+    let current = reason;
+    while (current && typeof current === "object" && !seen.has(current)) {
+        seen.add(current);
+        const statusCode = current.statusCode;
+        if (statusCode === 402)
+            return true;
+        const responseBody = current.responseBody;
+        if (typeof responseBody === "string" &&
+            hasInsufficientCreditsSignal(responseBody)) {
+            return true;
+        }
+        const errors = current.errors;
+        if (Array.isArray(errors)) {
+            for (const inner of errors) {
+                if (shouldIgnoreUnhandledRejection(inner))
+                    return true;
+            }
+        }
+        current = current.cause;
+    }
+    return false;
+}

package/runtime/mobile-local-inference-gate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * On a mobile platform (`ELIZA_PLATFORM=android` / `ios`) the runtime skips
+ * nearly every boot helper because they shell out to subprocesses,
+ * platform-specific binaries, or optional packages that aren't in the mobile
+ * bundle. Two mobile-safe inference paths still need wiring:
+ *
+ *   - `ELIZA_DEVICE_BRIDGE_ENABLED=1`: the agent (this process) hosts the
+ *     device-bridge WSS and dials whichever paired device connects. On the
+ *     Capacitor APK the WebView's `@elizaos/capacitor-llama` is the intended
+ *     dialer over loopback. The Capacitor build always exports this env so
+ *     the bridge is ready as soon as onboarding picks the local mode.
+ *
+ *   - `ELIZA_LOCAL_LLAMA=1`: AOSP-only path that loads node-llama-cpp
+ *     directly inside the Android process. Wired here so the gate is in
+ *     place ahead of sub-task 2 — the AOSP build flag flips this on.
+ *
+ * Kept dependency-free so it can be unit-tested without instantiating the
+ * full runtime.
+ */
+export declare function shouldEnableMobileLocalInference(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=mobile-local-inference-gate.d.ts.map

package/runtime/mobile-local-inference-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobile-local-inference-gate.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/mobile-local-inference-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gCAAgC,CAC9C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAIT"}

package/runtime/mobile-local-inference-gate.js

@@ -0,0 +1,24 @@
+/**
+ * On a mobile platform (`ELIZA_PLATFORM=android` / `ios`) the runtime skips
+ * nearly every boot helper because they shell out to subprocesses,
+ * platform-specific binaries, or optional packages that aren't in the mobile
+ * bundle. Two mobile-safe inference paths still need wiring:
+ *
+ *   - `ELIZA_DEVICE_BRIDGE_ENABLED=1`: the agent (this process) hosts the
+ *     device-bridge WSS and dials whichever paired device connects. On the
+ *     Capacitor APK the WebView's `@elizaos/capacitor-llama` is the intended
+ *     dialer over loopback. The Capacitor build always exports this env so
+ *     the bridge is ready as soon as onboarding picks the local mode.
+ *
+ *   - `ELIZA_LOCAL_LLAMA=1`: AOSP-only path that loads node-llama-cpp
+ *     directly inside the Android process. Wired here so the gate is in
+ *     place ahead of sub-task 2 — the AOSP build flag flips this on.
+ *
+ * Kept dependency-free so it can be unit-tested without instantiating the
+ * full runtime.
+ */
+export function shouldEnableMobileLocalInference(env = process.env) {
+    const deviceBridge = env.ELIZA_DEVICE_BRIDGE_ENABLED?.trim() === "1";
+    const localLlama = env.ELIZA_LOCAL_LLAMA?.trim() === "1";
+    return deviceBridge || localLlama;
+}