@elizaos/plugin-capacitor-bridge 2.0.0-beta.1 → 2.0.3-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @elizaos/plugin-capacitor-bridge
+
+Agent-side bridge that enables stock iOS and Android Eliza builds to run local GGUF inference through the device's native Capacitor llama.cpp plugin.
+
+## What it does
+
+AOSP builds run llama.cpp directly inside the agent process via `bun:ffi`. Stock Capacitor builds (App Store iOS, standard Android APK) cannot do that — llama.cpp is exposed to the WebView through a native Capacitor plugin instead. This package is the agent-side half of that path:
+
+- **Android**: accepts a loopback WebSocket from the Capacitor WebView, delegates `TEXT_SMALL`, `TEXT_LARGE`, and `TEXT_EMBEDDING` model requests to the connected device, and lets the normal elizaOS model-handler system work unchanged.
+- **iOS**: runs the elizaOS runtime inside the Bun binary bundled into the iOS app and dispatches API calls in-process over native Bun host IPC (no HTTP loopback).
+
+Both paths install a sandboxed virtual filesystem (`installMobileFsShim`) that confines all `node:fs` operations to the app's writable workspace directory, enforcing App Store and Play Store code-execution policies.
+
+## Capabilities added
+
+- `TEXT_SMALL` model handler — routes to the connected Capacitor device.
+- `TEXT_LARGE` model handler — routes to the connected Capacitor device.
+- `TEXT_EMBEDDING` model handler — routes to the connected Capacitor device.
+- Automatic GGUF model download from `elizaos/eliza-1` on HuggingFace when no local model is found (unless `ELIZA_DISABLE_MODEL_AUTO_DOWNLOAD=1`).
+- WebSocket endpoint `/api/local-inference/device-bridge` for Capacitor WebView registration and inference RPC.
+
+## Installation
+
+This package is used by the elizaOS agent bundle. It is not a standard elizaOS plugin and cannot be added to `character.plugins`. The agent bundle entry point imports and calls its bootstrap functions directly.
+
+```
+@elizaos/plugin-capacitor-bridge
+```
+
+## Configuration
+
+### Android (WebSocket device bridge)
+
+| Env var | Required | Description |
+|---|---|---|
+| `ELIZA_DEVICE_BRIDGE_ENABLED=1` | Yes | Enables the WebSocket bridge. |
+| `ELIZA_DEVICE_PAIRING_TOKEN` | Yes | Shared secret — must match the token sent by the Capacitor WebView. |
+| `ELIZA_DEVICE_BRIDGE_TOKEN` | Alias | Fallback for `ELIZA_DEVICE_PAIRING_TOKEN`. |
+
+### Model path (both platforms)
+
+| Env var | Description |
+|---|---|
+| `ELIZA_LOCAL_CHAT_MODEL_PATH` | Absolute path to a GGUF for chat (TEXT_SMALL / TEXT_LARGE). |
+| `ELIZA_LOCAL_EMBEDDING_MODEL_PATH` | Absolute path to an embedding GGUF. |
+| `ELIZA_LOCAL_MODEL_PATH` | Fallback when neither slot-specific var is set. |
+| `ELIZA_DISABLE_MODEL_AUTO_DOWNLOAD=1` | Disables auto-download from HuggingFace. |
+
+If no model path is set and auto-download is enabled, the bridge downloads recommended eliza-1 GGUFs from `elizaos/eliza-1` on HuggingFace into `$ELIZA_STATE_DIR/local-inference/models/`.
+
+### Timeouts (all optional, default 600000 ms)
+
+- `ELIZA_DEVICE_LOAD_TIMEOUT_MS`
+- `ELIZA_DEVICE_GENERATE_TIMEOUT_MS`
+- `ELIZA_DEVICE_EMBED_TIMEOUT_MS`
+
+## Filesystem sandbox
+
+Both platforms install a deny-by-default `node:fs` interceptor (`installMobileFsShim`) before booting the runtime:
+
+- All paths are resolved relative to the app's writable workspace root (`MOBILE_WORKSPACE_ROOT` on iOS, `HOME` on Android).
+- Path traversal outside the root throws `EACCES`.
+- System directories (`/etc`, `/usr`, `/System`, `/proc`, etc.) are blocked unconditionally.
+- Writes to native binary extensions (`.so`, `.dylib`, `.node`) are blocked.
+- `require()` of file paths is blocked — all code must be bundled.
+
+## WebSocket protocol (Android)
+
+The Capacitor WebView connects to `ws://127.0.0.1:<port>/api/local-inference/device-bridge?token=<ELIZA_DEVICE_PAIRING_TOKEN>`.
+
+Connection flow:
+1. WebView sends `{ type: "register", payload: { deviceId, pairingToken, capabilities, loadedPath } }`.
+2. Agent sends `{ type: "load", correlationId, modelPath, ... }` → device replies `{ type: "loadResult", correlationId, ok, loadedPath }`.
+3. Agent sends `{ type: "generate", correlationId, prompt, ... }` → device replies `{ type: "generateResult", correlationId, ok, text }`.
+4. Agent sends `{ type: "embed", correlationId, input }` → device replies `{ type: "embedResult", correlationId, ok, embedding }`.
+5. Agent sends `{ type: "formatChat", correlationId, messages }` → device replies `{ type: "formatChatResult", correlationId, ok, prompt }` (invokes native Jinja chat template).
+6. Agent pings every 15 s; device replies `{ type: "pong" }`.
+
+Note: iOS connections are rejected with close code `4003`. iOS uses native IPC, not this WebSocket path.
+
+## Recommended default models
+
+| Slot | Model ID | HuggingFace path |
+|---|---|---|
+| TEXT_SMALL | `eliza-1-4b` | `elizaos/eliza-1` — `bundles/4b/text/eliza-1-4b-128k.gguf` |
+| TEXT_LARGE | `eliza-1-4b` | `elizaos/eliza-1` — `bundles/4b/text/eliza-1-4b-128k.gguf` |
+| TEXT_EMBEDDING | `eliza-1-embedding` | `elizaos/eliza-1` — `bundles/4b/embedding/eliza-1-embedding.gguf` |
+
+The 4B tier is the shipped mobile default for both chat slots; `eliza-1-2b` is
+the smallest/entry tier (the small-phone floor) but is not a recommended default.

package/dist/android/bridge.d.ts

@@ -0,0 +1,39 @@
+/**
+ * android-mobile-bridge.ts — Android counterpart to ios-bridge.ts.
+ *
+ * On Android, the elizaOS agent runs as a Bun child process managed by
+ * `ElizaAgentService`. Unlike the iOS path (which uses a stdio JSON-RPC
+ * bridge to a JSContext host), the Android Bun process boots the full
+ * elizaOS backend as an HTTP server listening on 127.0.0.1:31337.
+ *
+ * The agent bundle entry-point (`serve` / `start` command) already binds
+ * the server when `ELIZA_DISABLE_DIRECT_RUN` is unset.  This module:
+ *   1. Sets Android-specific environment variables before any module import.
+ *   2. Installs the mobile fs sandbox shim.
+ *   3. Boots the elizaOS runtime via the canonical `startEliza` path.
+ *   4. Wires the `ELIZA_DEVICE_BRIDGE_ENABLED` inference delegation layer
+ *      so the Capacitor WebView's llama-cpp plugin routes through the
+ *      on-device agent over loopback.
+ *
+ * This module is imported by the agent bundle's `android-bridge` CLI command:
+ *   `bun agent-bundle.js android-bridge`
+ *
+ * Environment variables set here mirror those set by `ElizaAgentService`:
+ *   - ELIZA_PLATFORM=android
+ *   - ELIZA_MOBILE_PLATFORM=android
+ *   - ELIZA_ANDROID_LOCAL_BACKEND=1   (Android-specific backend flag)
+ *   - ELIZA_HEADLESS=1                (no terminal UI)
+ *   - ELIZA_API_BIND=127.0.0.1        (loopback only)
+ *   - ELIZA_VAULT_BACKEND=file
+ *   - ELIZA_DISABLE_VAULT_PROFILE_RESOLVER=1
+ *   - ELIZA_DISABLE_AGENT_WALLET_BOOTSTRAP=1
+ *   - LOG_LEVEL=error                 (quiet on-device)
+ *
+ * All values use the `||=` pattern so that values pre-set by the
+ * `ElizaAgentService` environment take precedence over these defaults.
+ * The service sets richer values (e.g. `ELIZA_API_TOKEN`, port, state dir)
+ * before spawning the bundle; this module only fills gaps for direct runs.
+ */
+declare function runAndroidBridgeCli(): Promise<void>;
+
+export { runAndroidBridgeCli };

package/dist/android/bridge.js

@@ -0,0 +1,151 @@
+import {
+  installMobileFsShim
+} from "../chunk-E7Y447TQ.js";
+import "../chunk-MLKGABMK.js";
+
+// src/android/bridge.ts
+import process from "process";
+import * as nodeFs from "fs";
+import nodePath from "path";
+process.env.ELIZA_PLATFORM ||= "android";
+process.env.ELIZA_MOBILE_PLATFORM ||= "android";
+process.env.ELIZA_ANDROID_LOCAL_BACKEND ||= "1";
+process.env.ELIZA_DISABLE_DIRECT_RUN ||= "1";
+process.env.ELIZA_HEADLESS ||= "1";
+process.env.ELIZA_API_BIND ||= "127.0.0.1";
+process.env.ELIZA_VAULT_BACKEND ||= "file";
+process.env.ELIZA_DISABLE_VAULT_PROFILE_RESOLVER ||= "1";
+process.env.ELIZA_DISABLE_AGENT_WALLET_BOOTSTRAP ||= "1";
+process.env.LOG_LEVEL ||= "error";
+process.env.ELIZA_DISABLE_AUTO_BOOTSTRAP ||= "1";
+process.env.ELIZA_DISABLE_TRAJECTORY_LOGGING ||= "1";
+async function loadStartEliza() {
+  const mod = await import(
+    /* @vite-ignore */
+    "@elizaos/agent"
+  );
+  return mod.startEliza;
+}
+var _logPath = "";
+function setupAndroidBridgeEnvironment() {
+  const rawHome = process.env.HOME || nodePath.dirname(
+    process.env.ELIZA_STATE_DIR || process.env.ELIZA_STATE_DIR || "/data/local/tmp/.eliza"
+  );
+  let canonicalHome;
+  try {
+    canonicalHome = nodeFs.realpathSync(rawHome);
+  } catch {
+    canonicalHome = rawHome;
+  }
+  if (canonicalHome !== rawHome) {
+    if (process.env.HOME) process.env.HOME = canonicalHome;
+    for (const key of [
+      "ELIZA_STATE_DIR",
+      "ELIZA_STATE_DIR",
+      "ELIZA_WORKSPACE_DIR",
+      "ELIZA_WORKSPACE_DIR",
+      "TMPDIR"
+    ]) {
+      const val = process.env[key];
+      if (val?.startsWith(rawHome)) {
+        process.env[key] = canonicalHome + val.slice(rawHome.length);
+      }
+    }
+  }
+  const stateDir = process.env.ELIZA_STATE_DIR || process.env.ELIZA_STATE_DIR || `${canonicalHome}/.eliza`;
+  installMobileFsShim(canonicalHome);
+  _logPath = `${stateDir}/android-bridge.log`;
+  try {
+    nodeFs.mkdirSync(stateDir, { recursive: true });
+  } catch {
+  }
+  _logToFile(`[android-bridge] process started, stateDir=${stateDir}`);
+  return stateDir;
+}
+function _logToFile(line) {
+  if (!_logPath) return;
+  try {
+    nodeFs.appendFileSync(_logPath, `${(/* @__PURE__ */ new Date()).toISOString()} ${line}
+`);
+  } catch {
+  }
+}
+async function runAndroidBridgeCli() {
+  setupAndroidBridgeEnvironment();
+  process.on("exit", (code) => {
+    _logToFile(`[android-bridge] process.exit code=${code}`);
+  });
+  const _origConsoleError = console.error.bind(console);
+  console.error = (...args) => {
+    _logToFile(`[console.error] ${args.map(String).join(" ")}`);
+    _origConsoleError(...args);
+  };
+  const _origConsoleWarn = console.warn.bind(console);
+  console.warn = (...args) => {
+    const msg = args.map(String).join(" ");
+    if (msg.includes("Error") || msg.includes("error") || msg.includes("fail")) {
+      _logToFile(`[console.warn] ${msg}`);
+    }
+    _origConsoleWarn(...args);
+  };
+  process.on("unhandledRejection", (reason) => {
+    const msg = reason instanceof Error ? reason.stack || reason.message : String(reason);
+    _logToFile(`[android-bridge] unhandledRejection: ${msg}`);
+    console.error("[android-bridge] unhandled rejection:", msg);
+  });
+  process.on("uncaughtException", (error) => {
+    _logToFile(
+      `[android-bridge] uncaughtException: ${error.stack || error.message}`
+    );
+    console.error(
+      "[android-bridge] uncaught exception:",
+      error.stack || error.message
+    );
+  });
+  _logToFile("[android-bridge] importing startEliza...");
+  const startEliza = await loadStartEliza();
+  _logToFile("[android-bridge] calling startEliza({ serverOnly: true })...");
+  const _hb = setInterval(() => {
+    _logToFile("[android-bridge] startEliza still running...");
+  }, 1e4);
+  let runtime;
+  try {
+    runtime = await startEliza({ serverOnly: true });
+  } catch (err) {
+    const msg = err instanceof Error ? err.stack || err.message : String(err);
+    _logToFile(`[android-bridge] startEliza THREW: ${msg}`);
+    throw err;
+  } finally {
+    clearInterval(_hb);
+  }
+  _logToFile(
+    `[android-bridge] startEliza returned: ${runtime ? "present" : "null"}`
+  );
+  _logToFile(
+    `[android-bridge] startEliza returned: runtime=${runtime ? "present" : "null"}, ELIZA_ANDROID_LOCAL_BACKEND=${process.env.ELIZA_ANDROID_LOCAL_BACKEND ?? "(unset)"}`
+  );
+  if (runtime && process.env.ELIZA_DEVICE_BRIDGE_ENABLED?.trim() === "1") {
+    _logToFile("[android-bridge] importing mobile-device-bridge-bootstrap\u2026");
+    const { ensureMobileDeviceBridgeInferenceHandlers } = await import("../mobile-device-bridge-bootstrap.js");
+    await ensureMobileDeviceBridgeInferenceHandlers(runtime);
+    try {
+      const { installRouterHandler } = await import("@elizaos/plugin-local-inference/runtime");
+      installRouterHandler(runtime, {});
+      _logToFile(
+        "[android-bridge] installed prefer-local cross-provider router"
+      );
+    } catch (err) {
+      _logToFile(
+        `[android-bridge] router install failed (local routing may defer to priority): ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  await new Promise((resolve) => {
+    process.once("SIGINT", resolve);
+    process.once("SIGTERM", resolve);
+  });
+  _logToFile("[android-bridge] shutdown signal received, exiting.");
+}
+export {
+  runAndroidBridgeCli
+};