@elizaos/capacitor-mobile-agent-bridge 2.0.3-beta.2

package/ElizaosCapacitorMobileAgentBridge.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'ElizaosCapacitorMobileAgentBridge'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license'] || { :type => 'MIT' }
+  s.homepage = 'https://elizaos.ai'
+  s.authors = { 'elizaOS' => 'dev@elizaos.ai' }
+  s.source = { :git => 'https://github.com/elizaOS/eliza.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.9'
+end

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,44 @@
+# @elizaos/capacitor-mobile-agent-bridge
+
+Outbound tunnel from a phone-hosted Eliza agent so a remote Mac client
+can reach it. Phone-side companion to the Mac-side
+`TunnelToMobileClient` in `@elizaos/app-core`.
+
+This package owns the phone-to-relay tunnel for a phone-hosted Eliza
+agent. The JS surface (`startInboundTunnel`, `stopInboundTunnel`,
+`getTunnelStatus`, `stateChange` event) is stable. Native implementations
+hold an outbound WebSocket to the relay and proxy requests into the same
+local agent route surface used by the rest of the mobile app.
+
+## Status
+
+| Platform | Status |
+| --- | --- |
+| Web    | Fallback. Returns `state: "error"` with an explanatory message. |
+| iOS    | Outbound WebSocket tunnel. Proxies path-only requests through the WebView IPC bridge; no listening port is opened. |
+| Android | Outbound WebSocket tunnel. Proxies path-only requests into the registered `ElizaAgentService` via reflection; no listening port is opened. |
+
+## Relay frame protocol
+
+Tunnel frames use a path-only HTTP request envelope. The relay never
+sends absolute URLs, and the plugin rejects `//host` and scheme-bearing
+paths before dispatching to the agent. On iOS, dispatch goes through
+`window.__ELIZA_IOS_LOCAL_AGENT_REQUEST__`, which is the same Capacitor
+IPC bridge the UI uses for full-Bun local mode.
+
+## Usage
+
+```ts
+import { MobileAgentBridge } from "@elizaos/capacitor-mobile-agent-bridge";
+
+await MobileAgentBridge.startInboundTunnel({
+  relayUrl: "wss://relay.elizacloud.ai/v1/agent-tunnel",
+  deviceId: "phone-abc123",
+  pairingToken: "...",
+});
+
+const status = await MobileAgentBridge.getTunnelStatus();
+// { state: "registered" | "error" | ..., relayUrl, deviceId, lastError }
+
+await MobileAgentBridge.stopInboundTunnel();
+```

package/android/build.gradle

@@ -0,0 +1,59 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.6.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.1.5'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.5.1'
+    kotlinVersion = project.hasProperty('kotlinVersion') ? rootProject.ext.kotlinVersion : '1.9.25'
+}
+
+apply plugin: 'com.android.library'
+// Explicitly apply the Kotlin Android plugin. The kotlin-gradle-plugin is on
+// the root buildscript classpath, but without applying it here AGP 8.13 falls
+// back to its "built-in Kotlin" compile path (build/intermediates/
+// built_in_kotlinc), which compiles the .kt sources but does NOT bundle the
+// resulting .class files into the *release* library jar. The app's
+// :app:assembleRelease then links a library AAR with zero plugin classes, so
+// the Capacitor plugin (and any manifest-declared component) is absent from
+// the release dex. Applying the standard Kotlin plugin wires Kotlin
+// compilation into both the debug and release jar-bundling tasks.
+apply plugin: 'org.jetbrains.kotlin.android'
+android {
+    namespace = "ai.eliza.plugins.mobileagentbridge"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
+    defaultConfig {
+        minSdk project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdk project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+
+    kotlinOptions {
+        jvmTarget = "21"
+    }
+}
+
+repositories {
+    google()
+    maven {
+        url = uri(rootProject.ext.has('mavenCentralMirrorUrl') ? rootProject.ext.mavenCentralMirrorUrl : 'https://repo.maven.apache.org/maven2')
+    }
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlinVersion"
+    implementation "com.squareup.okhttp3:okhttp:4.12.0"
+    testImplementation "junit:junit:$junitVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+</manifest>

package/android/src/main/java/ai/eliza/plugins/mobileagentbridge/MobileAgentBridgePlugin.kt

@@ -0,0 +1,286 @@
+package ai.eliza.plugins.mobileagentbridge
+
+import android.net.Uri
+import android.content.pm.PackageManager
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import java.util.Locale
+import java.util.concurrent.TimeUnit
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import okhttp3.WebSocket
+import okhttp3.WebSocketListener
+import org.json.JSONObject
+
+@CapacitorPlugin(name = "MobileAgentBridge")
+class MobileAgentBridgePlugin : Plugin() {
+    private val client = OkHttpClient.Builder()
+        .pingInterval(20, TimeUnit.SECONDS)
+        .build()
+    private var socket: WebSocket? = null
+    private var relayUrl: String? = null
+    private var deviceId: String? = null
+    private var pairingToken: String? = null
+    private var localAgentApiBase: String = DEFAULT_LOCAL_AGENT_API_BASE
+    private var state: String = "idle"
+    private var lastError: String? = null
+
+    @PluginMethod
+    fun startInboundTunnel(call: PluginCall) {
+        val relay = call.getString("relayUrl")?.trim()
+        val id = call.getString("deviceId")?.trim()
+        if (relay.isNullOrEmpty()) {
+            call.reject("MobileAgentBridge.startInboundTunnel requires relayUrl")
+            return
+        }
+        if (id.isNullOrEmpty()) {
+            call.reject("MobileAgentBridge.startInboundTunnel requires deviceId")
+            return
+        }
+
+        stopTunnel(notify = false)
+        relayUrl = relay
+        deviceId = id
+        pairingToken = call.getString("pairingToken")?.trim()?.takeIf { it.isNotEmpty() }
+        val localBase = call.getString("localAgentApiBase")?.trim()?.takeIf { it.isNotEmpty() }
+        localAgentApiBase = if (localBase == null) {
+            DEFAULT_LOCAL_AGENT_API_BASE
+        } else {
+            normalizeLocalAgentApiBase(localBase) ?: run {
+                transition("error", "Invalid localAgentApiBase: $localBase")
+                call.resolve(status())
+                return
+            }
+        }
+
+        val url = buildRelayUrl(relay, id, pairingToken)
+        if (url == null) {
+            transition("error", "Invalid relay URL: $relay")
+            call.resolve(status())
+            return
+        }
+
+        transition("connecting", null)
+        val request = Request.Builder().url(url).build()
+        socket = client.newWebSocket(request, object : WebSocketListener() {
+            override fun onOpen(webSocket: WebSocket, response: Response) {
+                transition("registered", null)
+                sendFrame(JSONObject().apply {
+                    put("type", "tunnel.register")
+                    put("role", "phone-agent")
+                    put("deviceId", id)
+                    put("pairingToken", pairingToken ?: JSONObject.NULL)
+                })
+            }
+
+            override fun onMessage(webSocket: WebSocket, text: String) {
+                handleFrame(text)
+            }
+
+            override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
+                if (socket === webSocket) {
+                    socket = null
+                    transition("disconnected", reason.ifBlank { null })
+                }
+            }
+
+            override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
+                if (socket === webSocket) {
+                    transition("error", t.message ?: "WebSocket failure")
+                }
+            }
+        })
+        call.resolve(status())
+    }
+
+    @PluginMethod
+    fun stopInboundTunnel(call: PluginCall) {
+        stopTunnel(notify = true)
+        call.resolve()
+    }
+
+    @PluginMethod
+    fun getTunnelStatus(call: PluginCall) {
+        call.resolve(status())
+    }
+
+    private fun stopTunnel(notify: Boolean) {
+        socket?.close(1000, "Client stop")
+        socket = null
+        relayUrl = null
+        deviceId = null
+        pairingToken = null
+        localAgentApiBase = DEFAULT_LOCAL_AGENT_API_BASE
+        state = "idle"
+        lastError = null
+        if (notify) notifyListeners("stateChange", JSObject().apply { put("state", "idle") })
+    }
+
+    private fun transition(next: String, reason: String?) {
+        state = next
+        lastError = if (next == "error") reason else null
+        notifyListeners("stateChange", JSObject().apply {
+            put("state", next)
+            if (reason != null) put("reason", reason)
+        })
+    }
+
+    private fun status(): JSObject {
+        return JSObject().apply {
+            put("state", state)
+            put("relayUrl", relayUrl)
+            put("deviceId", deviceId)
+            put("localAgentApiBase", localAgentApiBase)
+            put("lastError", lastError)
+        }
+    }
+
+    private fun buildRelayUrl(raw: String, id: String, token: String?): String? {
+        return try {
+            val uri = Uri.parse(raw)
+            val scheme = when (uri.scheme) {
+                "https" -> "wss"
+                "http" -> "ws"
+                "wss", "ws" -> uri.scheme
+                else -> return null
+            }
+            val builder = uri.buildUpon().scheme(scheme)
+                .clearQuery()
+                .appendQueryParameter("deviceId", id)
+            for (name in uri.queryParameterNames) {
+                if (name != "deviceId" && name != "token") {
+                    for (value in uri.getQueryParameters(name)) {
+                        builder.appendQueryParameter(name, value)
+                    }
+                }
+            }
+            if (token != null) builder.appendQueryParameter("token", token)
+            builder.build().toString()
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    private fun handleFrame(text: String) {
+        val frame = try {
+            JSONObject(text)
+        } catch (_: Exception) {
+            return
+        }
+        val type = frame.optString("type")
+        if (type != "http_request" && type != "tunnel.http_request" && type != "agent.http_request") {
+            return
+        }
+        Thread {
+            val id = frame.opt("id")
+            val response = try {
+                proxyHttpRequest(frame)
+            } catch (error: Exception) {
+                JSONObject().apply {
+                    put("status", 0)
+                    put("headers", JSONObject())
+                    put("body", "")
+                    put("error", error.message ?: "Local agent proxy failed")
+                }
+            }
+            response.put("type", "http_response")
+            response.put("id", id ?: JSONObject.NULL)
+            sendFrame(response)
+        }.start()
+    }
+
+    private fun proxyHttpRequest(frame: JSONObject): JSONObject {
+        val path = frame.optString("path", "/api/health")
+        if (!path.startsWith("/") || path.startsWith("//") || path.contains("://")) {
+            return JSONObject().apply {
+                put("status", 400)
+                put("headers", JSONObject())
+                put("body", "Invalid local path")
+            }
+        }
+        val method = frame.optString("method", "GET").trim().uppercase(Locale.US)
+        if (!method.matches(Regex("^[A-Z]{1,16}$"))) {
+            throw IllegalArgumentException("Unsupported HTTP method")
+        }
+        val timeoutMs = frame.optInt(
+            "timeoutMs",
+            frame.optInt("timeout_ms", DEFAULT_LOCAL_REQUEST_TIMEOUT_MS),
+        ).coerceIn(1_000, MAX_LOCAL_REQUEST_TIMEOUT_MS)
+        val body = frame.opt("body")?.takeUnless { it == JSONObject.NULL }?.toString()
+        return requestLocalAgent(
+            method = method,
+            path = path,
+            headers = frame.optJSONObject("headers") ?: JSONObject(),
+            body = body,
+            timeoutMs = timeoutMs,
+        )
+    }
+
+    private fun requestLocalAgent(
+        method: String,
+        path: String,
+        headers: JSONObject,
+        body: String?,
+        timeoutMs: Int,
+    ): JSONObject {
+        val request = JSONObject().apply {
+            put("method", method)
+            put("path", path)
+            put("headers", headers)
+            put("body", body ?: JSONObject.NULL)
+            put("timeoutMs", timeoutMs)
+        }
+        val serviceClass = Class.forName(resolveAgentServiceClassName())
+        val bridge = serviceClass.getMethod("requestLocalAgent", String::class.java)
+        val raw = bridge.invoke(null, request.toString()) as? String
+            ?: throw IllegalStateException("ElizaAgentService.requestLocalAgent returned null")
+        return JSONObject(raw)
+    }
+
+    private fun resolveAgentServiceClassName(): String {
+        val ctx = context ?: throw IllegalStateException("Android context is unavailable")
+        val packageInfo = if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.TIRAMISU) {
+            ctx.packageManager.getPackageInfo(
+                ctx.packageName,
+                PackageManager.PackageInfoFlags.of(PackageManager.GET_SERVICES.toLong()),
+            )
+        } else {
+            @Suppress("DEPRECATION")
+            ctx.packageManager.getPackageInfo(ctx.packageName, PackageManager.GET_SERVICES)
+        }
+        return packageInfo.services
+            ?.firstOrNull {
+                it.packageName == ctx.packageName && it.name.endsWith(".ElizaAgentService")
+            }
+            ?.name
+            ?: throw IllegalStateException("ElizaAgentService is not registered")
+    }
+
+    private fun sendFrame(frame: JSONObject) {
+        socket?.send(frame.toString())
+    }
+
+    private fun normalizeLocalAgentApiBase(raw: String): String? {
+        return try {
+            if (raw == DEFAULT_LOCAL_AGENT_API_BASE) return DEFAULT_LOCAL_AGENT_API_BASE
+            val uri = Uri.parse(raw)
+            val scheme = uri.scheme?.lowercase(Locale.US)
+            val host = uri.host?.lowercase(Locale.US)
+            if (scheme != "http") return null
+            if (host !in setOf("127.0.0.1", "localhost", "10.0.2.2")) return null
+            DEFAULT_LOCAL_AGENT_API_BASE
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    private companion object {
+        private const val DEFAULT_LOCAL_AGENT_API_BASE = "eliza-local-agent://ipc"
+        private const val DEFAULT_LOCAL_REQUEST_TIMEOUT_MS = 30_000
+        private const val MAX_LOCAL_REQUEST_TIMEOUT_MS = 600_000
+    }
+}

package/dist/esm/definitions.d.ts

@@ -0,0 +1,94 @@
+import type { PluginListenerHandle } from "@capacitor/core";
+/**
+ * MobileAgentBridge — phone-side half of "Mac connects to an agent
+ * running on iOS/Android" via an outbound tunnel.
+ *
+ * iOS apps cannot bind a publicly reachable listening socket; Android
+ * apps mostly cannot either, depending on AOSP variant and network
+ * environment. This plugin lets the phone hold an **outbound** WebSocket
+ * to a configured relay (default: Eliza Cloud managed gateway relay)
+ * and proxy traffic between the relay and the on-device agent API.
+ *
+ * Wire shape (relay → phone → relay):
+ *   - Phone connects to `${relayUrl}?deviceId=<id>` and sends a
+ *     `register` frame with optional pairing token.
+ *   - Relay forwards JSON frames addressed to this device.
+ *   - Phone proxies frames into the on-device agent's native local-agent
+ *     bridge (`eliza-local-agent://ipc` on Android, in-process ITTP/Bun IPC
+ *     on iOS) and ships responses back over the same WebSocket.
+ *
+ * Native iOS and Android implementations open the outbound WebSocket and
+ * proxy `http_request` frames to the local agent without exposing an
+ * inbound listening port.
+ */
+export interface MobileAgentBridgeStartOptions {
+    /**
+     * URL of the relay endpoint to dial. Typically a WebSocket
+     * (`wss://...`) but may be `https://...` for long-poll fallbacks.
+     * The relay must understand the agent-tunnel frame protocol.
+     */
+    relayUrl: string;
+    /**
+     * Stable device identifier. Reused across relaunches so an existing
+     * pairing on the Mac side keeps resolving to this device.
+     */
+    deviceId: string;
+    /**
+     * Optional pre-shared token for the pairing. The relay uses this to
+     * authorize the inbound connection without requiring full cloud
+     * credentials per frame.
+     */
+    pairingToken?: string;
+    /**
+     * Optional override for the local agent base used to satisfy proxied
+     * frames. Defaults to `eliza-local-agent://ipc` on Android and the
+     * in-process ITTP/Bun IPC surface on iOS.
+     */
+    localAgentApiBase?: string;
+}
+export type MobileAgentTunnelState = "idle" | "connecting" | "registered" | "disconnected" | "error";
+export interface MobileAgentTunnelStatus {
+    state: MobileAgentTunnelState;
+    /** Relay URL the bridge is currently dialing (if any). */
+    relayUrl: string | null;
+    /** Stable device identifier from the last `startInboundTunnel` call. */
+    deviceId: string | null;
+    /** Last error message surfaced by the native transport. */
+    lastError: string | null;
+}
+export interface MobileAgentTunnelStateEvent {
+    state: MobileAgentTunnelState;
+    reason?: string;
+}
+/**
+ * MobileAgentBridge plugin surface.
+ *
+ * Implementations:
+ *   - Web fallback: reports tunnel startup as unavailable.
+ *   - iOS: URLSessionWebSocketTask + WebView IPC dispatch into the
+ *     in-process local-agent bridge.
+ *   - Android: OkHttp WebSocket + foreground-service local-agent request
+ *     dispatch.
+ */
+export interface MobileAgentBridgePlugin {
+    /**
+     * Start (or restart) the inbound tunnel. Idempotent; calling with
+     * the same options while already registered leaves the tunnel unchanged.
+     */
+    startInboundTunnel(options: MobileAgentBridgeStartOptions): Promise<MobileAgentTunnelStatus>;
+    /**
+     * Stop the tunnel and release resources. Safe to call when no
+     * tunnel is active.
+     */
+    stopInboundTunnel(): Promise<void>;
+    /**
+     * Snapshot the current tunnel status.
+     */
+    getTunnelStatus(): Promise<MobileAgentTunnelStatus>;
+    /**
+     * Subscribe to tunnel state changes. Returns a listener handle the
+     * caller must close to unsubscribe.
+     */
+    addListener(eventName: "stateChange", listenerFunc: (event: MobileAgentTunnelStateEvent) => void): Promise<PluginListenerHandle>;
+    removeAllListeners(): Promise<void>;
+}

package/dist/esm/definitions.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/index.d.ts

@@ -0,0 +1,9 @@
+import type { MobileAgentBridgePlugin } from "./definitions";
+export type * from "./definitions";
+/**
+ * Capacitor plugin entry point. The native bindings on iOS and Android
+ * register themselves under the name `MobileAgentBridge`; the web
+ * fallback loads on dev / Electrobun shells where no phone tunnel is
+ * possible.
+ */
+export declare const MobileAgentBridge: MobileAgentBridgePlugin;

package/dist/esm/index.js

@@ -0,0 +1,11 @@
+import { registerPlugin } from "@capacitor/core";
+const loadWeb = () => import("./web").then((m) => new m.MobileAgentBridgeWeb());
+/**
+ * Capacitor plugin entry point. The native bindings on iOS and Android
+ * register themselves under the name `MobileAgentBridge`; the web
+ * fallback loads on dev / Electrobun shells where no phone tunnel is
+ * possible.
+ */
+export const MobileAgentBridge = registerPlugin("MobileAgentBridge", {
+    web: loadWeb,
+});

package/dist/esm/web.d.ts

@@ -0,0 +1,16 @@
+import { WebPlugin } from "@capacitor/core";
+import type { MobileAgentBridgePlugin, MobileAgentBridgeStartOptions, MobileAgentTunnelStatus } from "./definitions";
+/**
+ * Web fallback for the MobileAgentBridge.
+ *
+ * Browsers and Electrobun shells cannot host the on-device agent that
+ * the inbound tunnel proxies traffic into. We surface a stable "idle"
+ * status and reject `startInboundTunnel` so callers see an honest
+ * failure mode rather than a silent success.
+ */
+export declare class MobileAgentBridgeWeb extends WebPlugin implements MobileAgentBridgePlugin {
+    private status;
+    startInboundTunnel(options: MobileAgentBridgeStartOptions): Promise<MobileAgentTunnelStatus>;
+    stopInboundTunnel(): Promise<void>;
+    getTunnelStatus(): Promise<MobileAgentTunnelStatus>;
+}

package/dist/esm/web.js

@@ -0,0 +1,81 @@
+import { WebPlugin } from "@capacitor/core";
+function assertRelayUrl(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error("relayUrl must be a non-empty URL");
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error("relayUrl must be a valid URL");
+    }
+    if (parsed.protocol !== "wss:" &&
+        parsed.protocol !== "ws:" &&
+        parsed.protocol !== "https:" &&
+        parsed.protocol !== "http:") {
+        throw new Error("relayUrl protocol is not allowed");
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error("relayUrl must not contain embedded credentials");
+    }
+    return parsed.toString();
+}
+function assertDeviceId(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error("deviceId must be a non-empty string");
+    }
+    const normalized = value.trim();
+    if (!/^[a-zA-Z0-9._:-]{1,128}$/.test(normalized)) {
+        throw new Error("deviceId contains invalid characters");
+    }
+    return normalized;
+}
+/**
+ * Web fallback for the MobileAgentBridge.
+ *
+ * Browsers and Electrobun shells cannot host the on-device agent that
+ * the inbound tunnel proxies traffic into. We surface a stable "idle"
+ * status and reject `startInboundTunnel` so callers see an honest
+ * failure mode rather than a silent success.
+ */
+export class MobileAgentBridgeWeb extends WebPlugin {
+    constructor() {
+        super(...arguments);
+        this.status = {
+            state: "idle",
+            relayUrl: null,
+            deviceId: null,
+            lastError: null,
+        };
+    }
+    async startInboundTunnel(options) {
+        const relayUrl = assertRelayUrl(options.relayUrl);
+        const deviceId = assertDeviceId(options.deviceId);
+        this.status = {
+            state: "error",
+            relayUrl,
+            deviceId,
+            lastError: "MobileAgentBridge.startInboundTunnel is only available on iOS and Android.",
+        };
+        this.notifyListeners("stateChange", {
+            state: "error",
+            reason: this.status.lastError ?? undefined,
+        });
+        return this.status;
+    }
+    async stopInboundTunnel() {
+        if (this.status.state === "idle")
+            return;
+        this.status = {
+            state: "idle",
+            relayUrl: null,
+            deviceId: null,
+            lastError: null,
+        };
+        this.notifyListeners("stateChange", { state: "idle" });
+    }
+    async getTunnelStatus() {
+        return this.status;
+    }
+}

package/dist/esm/web.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/web.test.js

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { MobileAgentBridgeWeb } from "./web";
+describe("MobileAgentBridgeWeb fallback", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("starts in an idle state", async () => {
+        await expect(new MobileAgentBridgeWeb().getTunnelStatus()).resolves.toEqual({
+            state: "idle",
+            relayUrl: null,
+            deviceId: null,
+            lastError: null,
+        });
+    });
+    it.each([
+        { relayUrl: "", deviceId: "device-1" },
+        { relayUrl: "javascript:alert(1)", deviceId: "device-1" },
+        { relayUrl: "file:///tmp/socket", deviceId: "device-1" },
+        { relayUrl: "wss://user:pass@example.test/relay", deviceId: "device-1" },
+        { relayUrl: "wss://example.test/relay", deviceId: "" },
+        { relayUrl: "wss://example.test/relay", deviceId: "../escape" },
+    ])("rejects malformed tunnel options %#", async (options) => {
+        const plugin = new MobileAgentBridgeWeb();
+        const listener = vi.fn();
+        await plugin.addListener("stateChange", listener);
+        await expect(plugin.startInboundTunnel(options)).rejects.toThrow(/relayUrl|deviceId/);
+        await expect(plugin.getTunnelStatus()).resolves.toEqual({
+            state: "idle",
+            relayUrl: null,
+            deviceId: null,
+            lastError: null,
+        });
+        expect(listener).not.toHaveBeenCalled();
+    });
+    it("normalizes valid options, emits an error state, and returns to idle on stop", async () => {
+        const plugin = new MobileAgentBridgeWeb();
+        const listener = vi.fn();
+        await plugin.addListener("stateChange", listener);
+        await expect(plugin.startInboundTunnel({
+            relayUrl: "wss://relay.example/tunnel",
+            deviceId: " device-1 ",
+            pairingToken: "<script>",
+        })).resolves.toEqual({
+            state: "error",
+            relayUrl: "wss://relay.example/tunnel",
+            deviceId: "device-1",
+            lastError: "MobileAgentBridge.startInboundTunnel is only available on iOS and Android.",
+        });
+        expect(listener).toHaveBeenCalledWith({
+            state: "error",
+            reason: "MobileAgentBridge.startInboundTunnel is only available on iOS and Android.",
+        });
+        await plugin.stopInboundTunnel();
+        await expect(plugin.getTunnelStatus()).resolves.toEqual({
+            state: "idle",
+            relayUrl: null,
+            deviceId: null,
+            lastError: null,
+        });
+        expect(listener).toHaveBeenLastCalledWith({ state: "idle" });
+    });
+});

package/dist/plugin.cjs.js

@@ -0,0 +1,103 @@
+'use strict';
+
+var core = require('@capacitor/core');
+
+const loadWeb = () => Promise.resolve().then(function () { return web; }).then((m) => new m.MobileAgentBridgeWeb());
+/**
+ * Capacitor plugin entry point. The native bindings on iOS and Android
+ * register themselves under the name `MobileAgentBridge`; the web
+ * fallback loads on dev / Electrobun shells where no phone tunnel is
+ * possible.
+ */
+const MobileAgentBridge = core.registerPlugin("MobileAgentBridge", {
+    web: loadWeb,
+});
+
+function assertRelayUrl(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error("relayUrl must be a non-empty URL");
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error("relayUrl must be a valid URL");
+    }
+    if (parsed.protocol !== "wss:" &&
+        parsed.protocol !== "ws:" &&
+        parsed.protocol !== "https:" &&
+        parsed.protocol !== "http:") {
+        throw new Error("relayUrl protocol is not allowed");
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error("relayUrl must not contain embedded credentials");
+    }
+    return parsed.toString();
+}
+function assertDeviceId(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error("deviceId must be a non-empty string");
+    }
+    const normalized = value.trim();
+    if (!/^[a-zA-Z0-9._:-]{1,128}$/.test(normalized)) {
+        throw new Error("deviceId contains invalid characters");
+    }
+    return normalized;
+}
+/**
+ * Web fallback for the MobileAgentBridge.
+ *
+ * Browsers and Electrobun shells cannot host the on-device agent that
+ * the inbound tunnel proxies traffic into. We surface a stable "idle"
+ * status and reject `startInboundTunnel` so callers see an honest
+ * failure mode rather than a silent success.
+ */
+class MobileAgentBridgeWeb extends core.WebPlugin {
+    constructor() {
+        super(...arguments);
+        this.status = {
+            state: "idle",
+            relayUrl: null,
+            deviceId: null,
+            lastError: null,
+        };
+    }
+    async startInboundTunnel(options) {
+        const relayUrl = assertRelayUrl(options.relayUrl);
+        const deviceId = assertDeviceId(options.deviceId);
+        this.status = {
+            state: "error",
+            relayUrl,
+            deviceId,
+            lastError: "MobileAgentBridge.startInboundTunnel is only available on iOS and Android.",
+        };
+        this.notifyListeners("stateChange", {
+            state: "error",
+            reason: this.status.lastError ?? undefined,
+        });
+        return this.status;
+    }
+    async stopInboundTunnel() {
+        if (this.status.state === "idle")
+            return;
+        this.status = {
+            state: "idle",
+            relayUrl: null,
+            deviceId: null,
+            lastError: null,
+        };
+        this.notifyListeners("stateChange", { state: "idle" });
+    }
+    async getTunnelStatus() {
+        return this.status;
+    }
+}
+
+var web = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    MobileAgentBridgeWeb: MobileAgentBridgeWeb
+});
+
+exports.MobileAgentBridge = MobileAgentBridge;
+//# sourceMappingURL=plugin.cjs.js.map

package/dist/plugin.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.cjs.js","sources":["esm/index.js","esm/web.js"],"sourcesContent":["import { registerPlugin } from \"@capacitor/core\";\nconst loadWeb = () => import(\"./web\").then((m) => new m.MobileAgentBridgeWeb());\n/**\n * Capacitor plugin entry point. The native bindings on iOS and Android\n * register themselves under the name `MobileAgentBridge`; the web\n * fallback loads on dev / Electrobun shells where no phone tunnel is\n * possible.\n */\nexport const MobileAgentBridge = registerPlugin(\"MobileAgentBridge\", {\n    web: loadWeb,\n});\n","import { WebPlugin } from \"@capacitor/core\";\nfunction assertRelayUrl(value) {\n    if (typeof value !== \"string\" || value.trim().length === 0) {\n        throw new Error(\"relayUrl must be a non-empty URL\");\n    }\n    let parsed;\n    try {\n        parsed = new URL(value);\n    }\n    catch {\n        throw new Error(\"relayUrl must be a valid URL\");\n    }\n    if (parsed.protocol !== \"wss:\" &&\n        parsed.protocol !== \"ws:\" &&\n        parsed.protocol !== \"https:\" &&\n        parsed.protocol !== \"http:\") {\n        throw new Error(\"relayUrl protocol is not allowed\");\n    }\n    if (parsed.username || parsed.password) {\n        throw new Error(\"relayUrl must not contain embedded credentials\");\n    }\n    return parsed.toString();\n}\nfunction assertDeviceId(value) {\n    if (typeof value !== \"string\" || value.trim().length === 0) {\n        throw new Error(\"deviceId must be a non-empty string\");\n    }\n    const normalized = value.trim();\n    if (!/^[a-zA-Z0-9._:-]{1,128}$/.test(normalized)) {\n        throw new Error(\"deviceId contains invalid characters\");\n    }\n    return normalized;\n}\n/**\n * Web fallback for the MobileAgentBridge.\n *\n * Browsers and Electrobun shells cannot host the on-device agent that\n * the inbound tunnel proxies traffic into. We surface a stable \"idle\"\n * status and reject `startInboundTunnel` so callers see an honest\n * failure mode rather than a silent success.\n */\nexport class MobileAgentBridgeWeb extends WebPlugin {\n    constructor() {\n        super(...arguments);\n        this.status = {\n            state: \"idle\",\n            relayUrl: null,\n            deviceId: null,\n            lastError: null,\n        };\n    }\n    async startInboundTunnel(options) {\n        const relayUrl = assertRelayUrl(options.relayUrl);\n        const deviceId = assertDeviceId(options.deviceId);\n        this.status = {\n            state: \"error\",\n            relayUrl,\n            deviceId,\n            lastError: \"MobileAgentBridge.startInboundTunnel is only available on iOS and Android.\",\n        };\n        this.notifyListeners(\"stateChange\", {\n            state: \"error\",\n            reason: this.status.lastError ?? undefined,\n        });\n        return this.status;\n    }\n    async stopInboundTunnel() {\n        if (this.status.state === \"idle\")\n            return;\n        this.status = {\n            state: \"idle\",\n            relayUrl: null,\n            deviceId: null,\n            lastError: null,\n        };\n        this.notifyListeners(\"stateChange\", { state: \"idle\" });\n    }\n    async getTunnelStatus() {\n        return this.status;\n    }\n}\n"],"names":["registerPlugin","WebPlugin"],"mappings":"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"}

package/dist/plugin.js

@@ -0,0 +1,106 @@
+var capacitorMobileAgentBridge = (function (exports, core) {
+    'use strict';
+
+    const loadWeb = () => Promise.resolve().then(function () { return web; }).then((m) => new m.MobileAgentBridgeWeb());
+    /**
+     * Capacitor plugin entry point. The native bindings on iOS and Android
+     * register themselves under the name `MobileAgentBridge`; the web
+     * fallback loads on dev / Electrobun shells where no phone tunnel is
+     * possible.
+     */
+    const MobileAgentBridge = core.registerPlugin("MobileAgentBridge", {
+        web: loadWeb,
+    });
+
+    function assertRelayUrl(value) {
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw new Error("relayUrl must be a non-empty URL");
+        }
+        let parsed;
+        try {
+            parsed = new URL(value);
+        }
+        catch {
+            throw new Error("relayUrl must be a valid URL");
+        }
+        if (parsed.protocol !== "wss:" &&
+            parsed.protocol !== "ws:" &&
+            parsed.protocol !== "https:" &&
+            parsed.protocol !== "http:") {
+            throw new Error("relayUrl protocol is not allowed");
+        }
+        if (parsed.username || parsed.password) {
+            throw new Error("relayUrl must not contain embedded credentials");
+        }
+        return parsed.toString();
+    }
+    function assertDeviceId(value) {
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw new Error("deviceId must be a non-empty string");
+        }
+        const normalized = value.trim();
+        if (!/^[a-zA-Z0-9._:-]{1,128}$/.test(normalized)) {
+            throw new Error("deviceId contains invalid characters");
+        }
+        return normalized;
+    }
+    /**
+     * Web fallback for the MobileAgentBridge.
+     *
+     * Browsers and Electrobun shells cannot host the on-device agent that
+     * the inbound tunnel proxies traffic into. We surface a stable "idle"
+     * status and reject `startInboundTunnel` so callers see an honest
+     * failure mode rather than a silent success.
+     */
+    class MobileAgentBridgeWeb extends core.WebPlugin {
+        constructor() {
+            super(...arguments);
+            this.status = {
+                state: "idle",
+                relayUrl: null,
+                deviceId: null,
+                lastError: null,
+            };
+        }
+        async startInboundTunnel(options) {
+            const relayUrl = assertRelayUrl(options.relayUrl);
+            const deviceId = assertDeviceId(options.deviceId);
+            this.status = {
+                state: "error",
+                relayUrl,
+                deviceId,
+                lastError: "MobileAgentBridge.startInboundTunnel is only available on iOS and Android.",
+            };
+            this.notifyListeners("stateChange", {
+                state: "error",
+                reason: this.status.lastError ?? undefined,
+            });
+            return this.status;
+        }
+        async stopInboundTunnel() {
+            if (this.status.state === "idle")
+                return;
+            this.status = {
+                state: "idle",
+                relayUrl: null,
+                deviceId: null,
+                lastError: null,
+            };
+            this.notifyListeners("stateChange", { state: "idle" });
+        }
+        async getTunnelStatus() {
+            return this.status;
+        }
+    }
+
+    var web = /*#__PURE__*/Object.freeze({
+        __proto__: null,
+        MobileAgentBridgeWeb: MobileAgentBridgeWeb
+    });
+
+    exports.MobileAgentBridge = MobileAgentBridge;
+
+    return exports;
+
+})({}, capacitorExports);
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sources":["esm/index.js","esm/web.js"],"sourcesContent":["import { registerPlugin } from \"@capacitor/core\";\nconst loadWeb = () => import(\"./web\").then((m) => new m.MobileAgentBridgeWeb());\n/**\n * Capacitor plugin entry point. The native bindings on iOS and Android\n * register themselves under the name `MobileAgentBridge`; the web\n * fallback loads on dev / Electrobun shells where no phone tunnel is\n * possible.\n */\nexport const MobileAgentBridge = registerPlugin(\"MobileAgentBridge\", {\n    web: loadWeb,\n});\n","import { WebPlugin } from \"@capacitor/core\";\nfunction assertRelayUrl(value) {\n    if (typeof value !== \"string\" || value.trim().length === 0) {\n        throw new Error(\"relayUrl must be a non-empty URL\");\n    }\n    let parsed;\n    try {\n        parsed = new URL(value);\n    }\n    catch {\n        throw new Error(\"relayUrl must be a valid URL\");\n    }\n    if (parsed.protocol !== \"wss:\" &&\n        parsed.protocol !== \"ws:\" &&\n        parsed.protocol !== \"https:\" &&\n        parsed.protocol !== \"http:\") {\n        throw new Error(\"relayUrl protocol is not allowed\");\n    }\n    if (parsed.username || parsed.password) {\n        throw new Error(\"relayUrl must not contain embedded credentials\");\n    }\n    return parsed.toString();\n}\nfunction assertDeviceId(value) {\n    if (typeof value !== \"string\" || value.trim().length === 0) {\n        throw new Error(\"deviceId must be a non-empty string\");\n    }\n    const normalized = value.trim();\n    if (!/^[a-zA-Z0-9._:-]{1,128}$/.test(normalized)) {\n        throw new Error(\"deviceId contains invalid characters\");\n    }\n    return normalized;\n}\n/**\n * Web fallback for the MobileAgentBridge.\n *\n * Browsers and Electrobun shells cannot host the on-device agent that\n * the inbound tunnel proxies traffic into. We surface a stable \"idle\"\n * status and reject `startInboundTunnel` so callers see an honest\n * failure mode rather than a silent success.\n */\nexport class MobileAgentBridgeWeb extends WebPlugin {\n    constructor() {\n        super(...arguments);\n        this.status = {\n            state: \"idle\",\n            relayUrl: null,\n            deviceId: null,\n            lastError: null,\n        };\n    }\n    async startInboundTunnel(options) {\n        const relayUrl = assertRelayUrl(options.relayUrl);\n        const deviceId = assertDeviceId(options.deviceId);\n        this.status = {\n            state: \"error\",\n            relayUrl,\n            deviceId,\n            lastError: \"MobileAgentBridge.startInboundTunnel is only available on iOS and Android.\",\n        };\n        this.notifyListeners(\"stateChange\", {\n            state: \"error\",\n            reason: this.status.lastError ?? undefined,\n        });\n        return this.status;\n    }\n    async stopInboundTunnel() {\n        if (this.status.state === \"idle\")\n            return;\n        this.status = {\n            state: \"idle\",\n            relayUrl: null,\n            deviceId: null,\n            lastError: null,\n        };\n        this.notifyListeners(\"stateChange\", { state: \"idle\" });\n    }\n    async getTunnelStatus() {\n        return this.status;\n    }\n}\n"],"names":["registerPlugin","WebPlugin"],"mappings":"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"}

package/ios/Sources/MobileAgentBridgePlugin/MobileAgentBridgePlugin.swift

@@ -0,0 +1,237 @@
+import Foundation
+import Capacitor
+import WebKit
+
+@objc(MobileAgentBridgePlugin)
+public class MobileAgentBridgePlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "MobileAgentBridgePlugin"
+    public let jsName = "MobileAgentBridge"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "startInboundTunnel", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "stopInboundTunnel", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getTunnelStatus", returnType: CAPPluginReturnPromise),
+    ]
+
+    private var relayUrl: String?
+    private var deviceId: String?
+    private var pairingToken: String?
+    private var state: String = "idle"
+    private var lastError: String?
+    private var session: URLSession?
+    private var task: URLSessionWebSocketTask?
+
+    @objc func startInboundTunnel(_ call: CAPPluginCall) {
+        guard let relay = call.getString("relayUrl")?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !relay.isEmpty else {
+            call.reject("MobileAgentBridge.startInboundTunnel requires relayUrl")
+            return
+        }
+        guard let id = call.getString("deviceId")?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !id.isEmpty else {
+            call.reject("MobileAgentBridge.startInboundTunnel requires deviceId")
+            return
+        }
+
+        stopTunnel(notify: false)
+        relayUrl = relay
+        deviceId = id
+        pairingToken = call.getString("pairingToken")?.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        guard let url = buildRelayUrl(relayUrl: relay, deviceId: id, token: pairingToken) else {
+            transition("error", reason: "Invalid relay URL: \(relay)")
+            call.resolve(status())
+            return
+        }
+
+        transition("connecting", reason: nil)
+        let session = URLSession(configuration: .default)
+        let task = session.webSocketTask(with: url)
+        self.session = session
+        self.task = task
+        task.resume()
+        receiveLoop()
+        sendFrame([
+            "type": "tunnel.register",
+            "role": "phone-agent",
+            "deviceId": id,
+            "pairingToken": pairingToken ?? NSNull(),
+        ]) { [weak self] error in
+            if let error {
+                self?.transition("error", reason: error.localizedDescription)
+            } else {
+                self?.transition("registered", reason: nil)
+            }
+        }
+        call.resolve(status())
+    }
+
+    @objc func stopInboundTunnel(_ call: CAPPluginCall) {
+        stopTunnel(notify: true)
+        call.resolve()
+    }
+
+    @objc func getTunnelStatus(_ call: CAPPluginCall) {
+        call.resolve(status())
+    }
+
+    private func stopTunnel(notify: Bool) {
+        task?.cancel(with: .normalClosure, reason: nil)
+        session?.invalidateAndCancel()
+        task = nil
+        session = nil
+        relayUrl = nil
+        deviceId = nil
+        pairingToken = nil
+        lastError = nil
+        state = "idle"
+        if notify {
+            notifyListeners("stateChange", data: ["state": "idle"])
+        }
+    }
+
+    private func transition(_ next: String, reason: String?) {
+        state = next
+        lastError = next == "error" ? reason : nil
+        var event: [String: Any] = ["state": next]
+        if let reason { event["reason"] = reason }
+        notifyListeners("stateChange", data: event)
+    }
+
+    private func status() -> [String: Any] {
+        [
+            "state": state,
+            "relayUrl": relayUrl ?? NSNull(),
+            "deviceId": deviceId ?? NSNull(),
+            "lastError": lastError ?? NSNull(),
+        ]
+    }
+
+    private func buildRelayUrl(relayUrl: String, deviceId: String, token: String?) -> URL? {
+        guard var components = URLComponents(string: relayUrl) else { return nil }
+        if components.scheme == "https" { components.scheme = "wss" }
+        if components.scheme == "http" { components.scheme = "ws" }
+        var items = components.queryItems ?? []
+        items.removeAll { $0.name == "deviceId" || $0.name == "token" }
+        items.append(URLQueryItem(name: "deviceId", value: deviceId))
+        if let token, !token.isEmpty {
+            items.append(URLQueryItem(name: "token", value: token))
+        }
+        components.queryItems = items
+        return components.url
+    }
+
+    private func receiveLoop() {
+        task?.receive { [weak self] result in
+            guard let self else { return }
+            switch result {
+            case .success(let message):
+                self.handle(message)
+                self.receiveLoop()
+            case .failure(let error):
+                if self.task != nil {
+                    self.transition("error", reason: error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    private func handle(_ message: URLSessionWebSocketTask.Message) {
+        let text: String
+        switch message {
+        case .string(let value):
+            text = value
+        case .data(let data):
+            text = String(data: data, encoding: .utf8) ?? ""
+        @unknown default:
+            return
+        }
+        guard let data = text.data(using: .utf8),
+              let frame = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return
+        }
+        let type = frame["type"] as? String
+        guard type == "http_request" || type == "tunnel.http_request" || type == "agent.http_request" else {
+            return
+        }
+        proxyHttpRequest(frame)
+    }
+
+    private func proxyHttpRequest(_ frame: [String: Any]) {
+        let id = frame["id"] ?? NSNull()
+        let path = (frame["path"] as? String) ?? "/api/health"
+        guard path.starts(with: "/"), !path.starts(with: "//"), !path.contains("://") else {
+            sendFrame(["type": "http_response", "id": id, "status": 400, "headers": [:], "body": "Invalid local path"])
+            return
+        }
+        let method = ((frame["method"] as? String) ?? "GET").uppercased()
+        let headers = frame["headers"] as? [String: String] ?? [:]
+        let body = frame["body"] is NSNull ? nil : frame["body"] as? String
+        let timeoutMs = frame["timeoutMs"] as? Int ?? frame["timeout_ms"] as? Int ?? 30000
+        let options: [String: Any] = [
+            "method": method,
+            "path": path,
+            "headers": headers,
+            "body": body ?? NSNull(),
+            "timeoutMs": timeoutMs,
+        ]
+        dispatchLocalRequest(options) { [weak self] response in
+            var out = response
+            out["type"] = "http_response"
+            out["id"] = id
+            self?.sendFrame(out)
+        }
+    }
+
+    private func dispatchLocalRequest(_ options: [String: Any], completion: @escaping ([String: Any]) -> Void) {
+        guard let webView = bridge?.webView else {
+            completion(["status": 0, "headers": [:], "body": "", "error": "WebView unavailable"])
+            return
+        }
+        let body = """
+        if (typeof window.__ELIZA_IOS_LOCAL_AGENT_REQUEST__ !== "function") {
+          throw new Error("iOS local agent IPC bridge is unavailable");
+        }
+        return await window.__ELIZA_IOS_LOCAL_AGENT_REQUEST__(options);
+        """
+        DispatchQueue.main.async {
+            webView.callAsyncJavaScript(body, arguments: ["options": options], in: nil, in: .page) { result in
+                switch result {
+                case .success(let value):
+                    if let dict = value as? [String: Any] {
+                        completion(dict)
+                    } else {
+                        completion(["status": 0, "headers": [:], "body": "", "error": "Invalid IPC response"])
+                    }
+                case .failure(let error):
+                    completion(["status": 0, "headers": [:], "body": "", "error": error.localizedDescription])
+                }
+            }
+        }
+    }
+
+    private func sendFrame(_ frame: [String: Any], completion: ((Error?) -> Void)? = nil) {
+        guard let task else {
+            completion?(NSError(
+                domain: "MobileAgentBridge",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "WebSocket is not connected"]
+            ))
+            return
+        }
+        guard let data = try? JSONSerialization.data(withJSONObject: frame),
+              let text = String(data: data, encoding: .utf8) else {
+            completion?(NSError(
+                domain: "MobileAgentBridge",
+                code: 2,
+                userInfo: [NSLocalizedDescriptionKey: "Failed to encode tunnel frame"]
+            ))
+            return
+        }
+        task.send(.string(text)) { [weak self] error in
+            if let error {
+                self?.transition("error", reason: error.localizedDescription)
+            }
+            completion?(error)
+        }
+    }
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@elizaos/capacitor-mobile-agent-bridge",
+  "version": "2.0.3-beta.2",
+  "description": "Outbound tunnel from a phone-hosted Eliza agent so a remote Mac client can reach it. See docs/reverse-direction-tunneling.md.",
+  "keywords": [
+    "agent",
+    "tunnel",
+    "relay",
+    "mobile",
+    "ios",
+    "android"
+  ],
+  "main": "./dist/plugin.cjs.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "bun": "./src/index.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/plugin.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "unpkg": "dist/plugin.js",
+  "files": [
+    "android/src/main/",
+    "android/build.gradle",
+    "ios/Sources/",
+    "ios/Plugin.xcodeproj/",
+    "*.podspec",
+    "dist"
+  ],
+  "author": "elizaOS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elizaOS/eliza"
+  },
+  "scripts": {
+    "lint": "bunx @biomejs/biome check .",
+    "lint:check": "bunx @biomejs/biome check .",
+    "fmt": "bunx @biomejs/biome check --write --unsafe .",
+    "format": "bunx @biomejs/biome format --write .",
+    "format:check": "bunx @biomejs/biome format .",
+    "build": "node ../../packages/scripts/with-package-build-lock.mjs plugins/plugin-native-mobile-agent-bridge -- bun run build:unlocked",
+    "clean": "node ../../packages/scripts/rm-path-recursive.mjs dist",
+    "test": "vitest run",
+    "watch": "tsc --watch",
+    "prepublishOnly": "bun run build",
+    "build:unlocked": "bun run clean && tsc && bunx rollup -c rollup.config.mjs"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@capacitor/core": "^8.3.1",
+    "rollup": "^4.60.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^8.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "capacitor": {
+    "ios": {
+      "src": "ios",
+      "podName": "ElizaosCapacitorMobileAgentBridge"
+    },
+    "android": {
+      "src": "android"
+    }
+  },
+  "elizaos": {
+    "platforms": [
+      "browser"
+    ],
+    "runtime": "both",
+    "platformDetails": {
+      "browser": "Fallback for non-native runtimes. Real transport lives on iOS/Android only.",
+      "ios": true,
+      "android": true
+    }
+  },
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
+}