@elizaos/capacitor-agent 1.0.0 → 2.0.11-beta.7

package/ElizaosCapacitorAgent.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'ElizaosCapacitorAgent'
+  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}'
+  s.ios.deployment_target = '13.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+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,145 @@
+# @elizaos/capacitor-agent
+
+Capacitor plugin for managing an embedded Eliza agent runtime from a WebView-based app. Provides a uniform `Agent.*` JavaScript API across iOS, Android, and web/desktop, with platform-specific native bridges and an HTTP-based web fallback.
+
+## What it does
+
+- **Start / stop** the agent runtime and poll its state.
+- **Send chat messages** (DM channel) and receive agent replies.
+- **Forward arbitrary HTTP requests** to the local agent API server via a path-only bridge.
+- **Read the per-boot bearer token** on Android local deployments.
+
+The plugin handles three deployment shapes automatically:
+
+| Platform | Mechanism |
+|---|---|
+| iOS remote/cloud | HTTP to a configured API endpoint (reads `ELIZA_IOS_API_BASE` or equivalent) |
+| iOS local / sideload | WebView ITTP bridge (`window.__ELIZA_IOS_LOCAL_AGENT_REQUEST__`) |
+| Android local | Reflection call into `ElizaAgentService` in the host app |
+| Web / Electrobun | HTTP fetch to `window.__ELIZA_API_BASE__` or relative URLs |
+
+## Capacitor methods
+
+```typescript
+import { Agent } from "@elizaos/capacitor-agent";
+
+// Start the agent
+const status = await Agent.start({ mode: "cloud" });
+
+// Get status
+const status = await Agent.getStatus();
+// status.state: "not_started" | "starting" | "running" | "stopped" | "error"
+
+// Chat
+const reply = await Agent.chat({ text: "Hello" });
+// reply.text, reply.agentName
+
+// Forward a request
+const result = await Agent.request({
+  path: "/api/status",
+  method: "GET",
+  timeoutMs: 5000,
+});
+
+// Stop the agent
+await Agent.stop();
+
+// Read local agent token (Android only)
+const { available, token } = await Agent.getLocalAgentToken();
+```
+
+## Installation
+
+This is a Capacitor plugin distributed as part of the elizaOS monorepo. Add it as a dependency in your Capacitor app, then run `npx cap sync` to install the native modules.
+
+```bash
+npm install @elizaos/capacitor-agent
+npx cap sync
+```
+
+### iOS (CocoaPods)
+
+The pod is named `ElizaosCapacitorAgent`. It is registered automatically via `capacitor.config` after `pod install`. Minimum deployment target: **iOS 13.0** (note: local ITTP mode requires iOS 14+).
+
+### Android
+
+The plugin is registered automatically. The host app must implement `ElizaAgentService` and register it in `AndroidManifest.xml`. The plugin locates it via reflection (no direct Gradle dependency).
+
+## Configuration
+
+### iOS endpoint (remote/cloud mode)
+
+Set one of the following in your `capacitor.config.json` (under the `Agent` plugin key), `Info.plist`, or environment:
+
+- `ELIZA_AGENT_API_BASE` / `ELIZA_IOS_API_BASE` / `ELIZA_MOBILE_API_BASE` — HTTP/HTTPS base URL of the agent API server
+- `ELIZA_AGENT_API_TOKEN` / `ELIZA_IOS_API_TOKEN` / `ELIZA_MOBILE_API_TOKEN` — optional bearer token
+- `ELIZA_IOS_RUNTIME_MODE` / `VITE_ELIZA_IOS_RUNTIME_MODE` — set to `local` / `ios-local` / `sideload-local` to activate local ITTP mode instead of HTTP
+
+Example `capacitor.config.json` fragment:
+```json
+{
+  "plugins": {
+    "Agent": {
+      "apiBase": "https://your-eliza-host.example.com",
+      "apiToken": "your-bearer-token"
+    }
+  }
+}
+```
+
+### Web / Electrobun
+
+- `window.__ELIZA_API_BASE__` — API server base URL; falls back to relative URLs on `http:`/`https:` origins.
+- `window.__ELIZA_API_TOKEN__` — bearer token; falls back to `sessionStorage.eliza_api_token`.
+
+## Exported types
+
+```typescript
+interface AgentStatus {
+  state: "not_started" | "starting" | "running" | "stopped" | "error";
+  agentName: string | null;
+  port: number | null;
+  startedAt: number | null; // epoch ms
+  error: string | null;
+}
+
+interface ChatResult {
+  text: string;
+  agentName: string;
+}
+
+interface AgentStartOptions {
+  apiBase?: string;
+  mode?: "remote-mac" | "cloud" | "cloud-hybrid" | "local" | string;
+}
+
+interface AgentRequestOptions {
+  path: string;       // must start with /, not an absolute URL
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string | null;
+  timeoutMs?: number;
+}
+
+interface AgentRequestResult {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  body: string;
+}
+```
+
+## Building
+
+```bash
+bun run --cwd plugins/plugin-native-agent build   # tsc + rollup → dist/
+bun run --cwd plugins/plugin-native-agent watch   # tsc --watch
+```
+
+## Limitations
+
+- `Agent.request` only accepts path-only URLs (must start with `/`). Absolute URLs are rejected by all implementations.
+- Request and response bodies are capped at 10 MB.
+- iOS local mode (`Agent.chat` / `Agent.request` via ITTP) requires `window.__ELIZA_IOS_LOCAL_AGENT_REQUEST__` to be installed by the host WebView. If it is absent, a 503 is returned.
+- The Android bridge uses reflection; renaming or unregistering `ElizaAgentService` breaks all Android calls silently at runtime.
+- The `chat` method maintains one conversation per session (lazily created via `POST /api/conversations`). The conversation ID is not persisted across app restarts.

package/android/build.gradle

@@ -0,0 +1,44 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.6.1'
+}
+
+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.agent"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
+    defaultConfig {
+        minSdk project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 22
+        targetSdk project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
+    }
+    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 project(':capacitor-android')
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/ai/eliza/plugins/agent/AgentPlugin.kt

@@ -0,0 +1,308 @@
+package ai.eliza.plugins.agent
+
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import android.content.pm.PackageManager
+import java.util.Locale
+import org.json.JSONObject
+
+private const val MAX_REQUEST_BODY_BYTES = 10 * 1024 * 1024
+private const val DEFAULT_REQUEST_TIMEOUT_MS = 10_000
+private const val MAX_REQUEST_TIMEOUT_MS = 600_000
+
+/**
+ * Eliza Agent Plugin — Android bridge.
+ *
+ * The app module owns ElizaAgentService, so this library uses reflection to
+ * avoid a Gradle dependency cycle while still exposing the per-boot bearer
+ * token and request dispatch surface to the WebView.
+ */
+@CapacitorPlugin(name = "Agent")
+class AgentPlugin : Plugin() {
+    @PluginMethod
+    fun start(call: PluginCall) {
+        try {
+            invokeAgentService("start")
+            call.resolve(agentStatus("starting", null))
+        } catch (error: Exception) {
+            call.reject(error.message ?: "Failed to start local agent")
+        }
+    }
+
+    @PluginMethod
+    fun stop(call: PluginCall) {
+        try {
+            invokeAgentService("stop")
+            call.resolve(JSObject().apply {
+                put("ok", true)
+            })
+        } catch (error: Exception) {
+            call.reject(error.message ?: "Failed to stop local agent")
+        }
+    }
+
+    @PluginMethod
+    fun getStatus(call: PluginCall) {
+        val token = readLocalAgentToken()
+        if (token == null) {
+            call.resolve(agentStatus("not_started", null))
+            return
+        }
+
+        Thread {
+            try {
+                val result = forwardLocalRequest("/api/status", "GET", JSObject(), null, 1_500, token)
+                val json = JSONObject(result.getString("body") ?: "{}")
+                call.resolve(agentStatus(
+                    json.optString("state", "running"),
+                    json.optString("error").takeIf { it.isNotBlank() },
+                ))
+            } catch (error: Exception) {
+                call.resolve(agentStatus("error", error.message ?: "Local agent status unavailable"))
+            }
+        }.start()
+    }
+
+    @PluginMethod
+    fun getLocalAgentToken(call: PluginCall) {
+        val token = readLocalAgentToken()
+        call.resolve(JSObject().apply {
+            put("available", token != null)
+            put("token", token ?: JSONObject.NULL)
+        })
+    }
+
+    @PluginMethod
+    fun request(call: PluginCall) {
+        val path = call.getString("path")?.trim()
+        if (path == null || !isSafeLocalPath(path)) {
+            call.reject("Agent.request requires a local path that starts with /")
+            return
+        }
+
+        val method = (call.getString("method") ?: "GET").trim().uppercase(Locale.US)
+        if (!method.matches(Regex("^[A-Z]{1,16}$"))) {
+            call.reject("Unsupported HTTP method")
+            return
+        }
+
+        val timeoutMs = (call.getInt("timeoutMs") ?: DEFAULT_REQUEST_TIMEOUT_MS)
+            .coerceIn(1_000, MAX_REQUEST_TIMEOUT_MS)
+        val body = call.getString("body")
+        val headers = call.getObject("headers") ?: JSObject()
+        val token = readLocalAgentToken()
+
+        Thread {
+            try {
+                val result = forwardLocalRequest(path, method, headers, body, timeoutMs, token)
+                call.resolve(result)
+            } catch (error: Exception) {
+                call.resolve(localAgentUnavailableResponse(error.message ?: "Local agent request failed"))
+            }
+        }.start()
+    }
+
+    /**
+     * Streaming variant of [request]. Where [request] buffers the whole loopback
+     * response, this pushes it incrementally: the service reads the response
+     * stream and hands us per-fragment JSON envelopes, which we forward to the
+     * WebView as `agentStream*` Capacitor events tagged with a per-request
+     * `streamId`. Resolves immediately with the `streamId`; events follow.
+     */
+    @PluginMethod
+    fun requestStream(call: PluginCall) {
+        val path = call.getString("path")?.trim()
+        if (path == null || !isSafeLocalPath(path)) {
+            call.reject("Agent.requestStream requires a local path that starts with /")
+            return
+        }
+        val method = (call.getString("method") ?: "GET").trim().uppercase(Locale.US)
+        if (!method.matches(Regex("^[A-Z]{1,16}$"))) {
+            call.reject("Unsupported HTTP method")
+            return
+        }
+        val timeoutMs = (call.getInt("timeoutMs") ?: DEFAULT_REQUEST_TIMEOUT_MS)
+            .coerceIn(1_000, MAX_REQUEST_TIMEOUT_MS)
+        val body = call.getString("body")
+        val headers = call.getObject("headers") ?: JSObject()
+        val streamId = java.util.UUID.randomUUID().toString()
+
+        val requestJson = JSONObject().apply {
+            put("method", method)
+            put("path", path)
+            put("headers", JSONObject(headers.toString()))
+            put("body", body ?: JSONObject.NULL)
+            put("timeoutMs", timeoutMs)
+        }.toString()
+
+        val onEvent = java.util.function.Consumer<String> { eventJson ->
+            try {
+                val event = JSONObject(eventJson)
+                when (event.optString("type")) {
+                    "response" -> notifyListeners("agentStreamResponse", JSObject().apply {
+                        put("streamId", streamId)
+                        put("status", event.optInt("status"))
+                        put("statusText", event.optString("statusText"))
+                        put("headers", event.optJSONObject("headers") ?: JSONObject())
+                    })
+                    "chunk" -> notifyListeners("agentStreamChunk", JSObject().apply {
+                        put("streamId", streamId)
+                        put("dataBase64", event.optString("dataBase64"))
+                    })
+                    "complete" -> notifyListeners("agentStreamComplete", JSObject().apply {
+                        put("streamId", streamId)
+                        if (event.has("error")) put("error", event.optString("error"))
+                    })
+                }
+            } catch (_: Exception) {
+                // A malformed envelope shouldn't kill the stream; drop it.
+            }
+        }
+
+        // Resolve before the work starts so the WebView can attach listeners for
+        // this streamId; the service emits on the background thread below.
+        call.resolve(JSObject().apply { put("streamId", streamId) })
+
+        Thread {
+            try {
+                invokeAgentServiceRequestStream(requestJson, onEvent)
+            } catch (error: Exception) {
+                notifyListeners("agentStreamComplete", JSObject().apply {
+                    put("streamId", streamId)
+                    put("error", error.message ?: "Local agent stream failed")
+                })
+            }
+        }.start()
+    }
+
+    private fun agentStatus(state: String, error: String?): JSObject {
+        return JSObject().apply {
+            put("state", state)
+            put("agentName", JSONObject.NULL)
+            put("port", if (state == "not_started") JSONObject.NULL else 31337)
+            put("startedAt", JSONObject.NULL)
+            put("error", error ?: JSONObject.NULL)
+        }
+    }
+
+    private fun invokeAgentService(methodName: String) {
+        val serviceClass = Class.forName(resolveAgentServiceClassName())
+        val method = serviceClass.getMethod(methodName, android.content.Context::class.java)
+        method.invoke(null, context)
+    }
+
+    private fun localAgentUnavailableResponse(message: String): JSObject {
+        return JSObject().apply {
+            put("status", 503)
+            put("statusText", "Service Unavailable")
+            put("headers", JSObject().apply {
+                put("content-type", "application/json")
+            })
+            put("body", JSONObject().apply {
+                put("error", "local_agent_unavailable")
+                put("message", message)
+            }.toString())
+        }
+    }
+
+    private fun readLocalAgentToken(): String? {
+        return try {
+            val serviceClass = Class.forName(resolveAgentServiceClassName())
+            val method = serviceClass.getMethod("localAgentToken")
+            (method.invoke(null) as? String)?.trim()?.takeIf { it.isNotEmpty() }
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    private fun forwardLocalRequest(
+        path: String,
+        method: String,
+        headers: JSObject,
+        body: String?,
+        timeoutMs: Int,
+        token: String?,
+    ): JSObject {
+        val requestBody = body?.toByteArray(Charsets.UTF_8)
+        if (requestBody != null && requestBody.size > MAX_REQUEST_BODY_BYTES) {
+            throw IllegalArgumentException("Request body is too large")
+        }
+
+        val request = JSONObject().apply {
+            put("method", method)
+            put("path", path)
+            put("headers", headers)
+            put("body", body ?: JSONObject.NULL)
+            put("timeoutMs", timeoutMs)
+            if (!token.isNullOrBlank() && !hasHeader(headers, "authorization")) {
+                put("headers", JSONObject(headers.toString()).apply {
+                    put("Authorization", "Bearer $token")
+                })
+            }
+        }
+        val raw = invokeAgentServiceRequest(request.toString())
+        return jsObjectFromJson(JSONObject(raw))
+    }
+
+    private fun invokeAgentServiceRequest(requestJson: String): String {
+        val serviceClass = Class.forName(resolveAgentServiceClassName())
+        val method = serviceClass.getMethod("requestLocalAgent", String::class.java)
+        return method.invoke(null, requestJson) as? String
+            ?: throw IllegalStateException("ElizaAgentService.requestLocalAgent returned null")
+    }
+
+    private fun invokeAgentServiceRequestStream(
+        requestJson: String,
+        onEvent: java.util.function.Consumer<String>,
+    ) {
+        val serviceClass = Class.forName(resolveAgentServiceClassName())
+        val method = serviceClass.getMethod(
+            "requestLocalAgentStream",
+            String::class.java,
+            java.util.function.Consumer::class.java,
+        )
+        method.invoke(null, requestJson, onEvent)
+    }
+
+    private fun isSafeLocalPath(path: String): Boolean {
+        return path.startsWith("/") && !path.startsWith("//") && !path.contains("://")
+    }
+
+    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 hasHeader(headers: JSObject, expected: String): Boolean {
+        val keys = headers.keys()
+        while (keys.hasNext()) {
+            if (expected.equals(keys.next(), ignoreCase = true)) return true
+        }
+        return false
+    }
+
+    private fun jsObjectFromJson(json: JSONObject): JSObject {
+        return JSObject().apply {
+            for (key in json.keys()) {
+                put(key, json.opt(key))
+            }
+        }
+    }
+}

package/dist/esm/definitions.d.ts

@@ -5,7 +5,10 @@
  * communicating with the embedded Eliza agent.
  *
  * - Electrobun desktop: RPC to the main-process AgentManager
- * - iOS/Android/Web: HTTP calls to the API server
+ * - Android/Web: HTTP calls to the API server or bundled loopback agent
+ * - iOS: HTTP for remote/cloud endpoints; local dev/sideload foreground
+ *   requests bridge into the WebView ITTP kernel until the native route-kernel
+ *   backend lands
  */
 export interface AgentStatus {
     state: "not_started" | "starting" | "running" | "stopped" | "error";
@@ -18,9 +21,63 @@ export interface ChatResult {
     text: string;
     agentName: string;
 }
+export interface LocalAgentTokenResult {
+    available: boolean;
+    token: string | null;
+}
+export interface AgentStartOptions {
+    /**
+     * Optional API base for native shells that need an explicit endpoint.
+     * Android local uses loopback; iOS local dev/sideload builds use the same
+     * URL shape as a stable identity but route app requests through ITTP.
+     */
+    apiBase?: string;
+    /** Runtime mode hint for native shells that cannot read WebView storage. */
+    mode?: "remote-mac" | "cloud" | "cloud-hybrid" | "local" | string;
+}
+export interface AgentRequestOptions {
+    method?: string;
+    path: string;
+    headers?: Record<string, string>;
+    body?: string | null;
+    timeoutMs?: number;
+}
+export interface AgentRequestResult {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+}
+/** Handle returned by `addListener`; call `.remove()` to detach. */
+export interface AgentPluginListenerHandle {
+    remove: () => Promise<void>;
+}
+/** Acknowledgement of a started streaming request. */
+export interface AgentStreamHandle {
+    /** Correlates the `agentStream*` events for THIS request. */
+    streamId: string;
+}
+/** First `agentStreamResponse` event — the response head, before any body. */
+export interface AgentStreamResponseEvent {
+    streamId: string;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+}
+/** A body chunk as it arrives. `dataBase64` is the lossless raw bytes (base64)
+ *  so SSE frames / binary survive the bridge; decode + enqueue verbatim. */
+export interface AgentStreamChunkEvent {
+    streamId: string;
+    dataBase64: string;
+}
+/** Terminal event for a stream — `error` set only on failure. */
+export interface AgentStreamCompleteEvent {
+    streamId: string;
+    error?: string | null;
+}
 export interface AgentPlugin {
     /** Start the agent runtime. Resolves when it's ready. */
-    start(): Promise<AgentStatus>;
+    start(options?: AgentStartOptions): Promise<AgentStatus>;
     /** Stop the agent runtime. */
     stop(): Promise<{
         ok: boolean;
@@ -31,5 +88,33 @@ export interface AgentPlugin {
     chat(options: {
         text: string;
     }): Promise<ChatResult>;
+    /** Read the per-boot bearer token for the bundled Android local agent. */
+    getLocalAgentToken?(): Promise<LocalAgentTokenResult>;
+    /**
+     * Path-only request bridge for the bundled local agent.
+     *
+     * Native implementations must reject absolute URLs and route only to the
+     * app-owned local backend. This is a transitional transport before the
+     * backend route kernel can run over Binder/LocalSocket/WKURLSchemeHandler.
+     * On iOS local dev/sideload builds this requires the WebView ITTP bridge to
+     * be installed, so it is a foreground-only path.
+     */
+    request?(options: AgentRequestOptions): Promise<AgentRequestResult>;
+    /**
+     * STREAMING variant of {@link request}. Where `request` buffers the whole
+     * response into one string (so SSE token frames arrive all at once — the chat
+     * reply never streams on mobile), `requestStream` opens the same loopback
+     * request and pushes the response incrementally via `agentStream*` events,
+     * letting the WebView reconstruct a real streaming `Response`.
+     *
+     * Resolves with the `streamId` once the request is started; the head arrives
+     * as `agentStreamResponse`, body bytes as `agentStreamChunk`, and the stream
+     * ends with `agentStreamComplete`. Absent on platforms without a streaming
+     * bridge — callers MUST fall back to {@link request}.
+     */
+    requestStream?(options: AgentRequestOptions): Promise<AgentStreamHandle>;
+    addListener?(eventName: "agentStreamResponse", listener: (event: AgentStreamResponseEvent) => void): Promise<AgentPluginListenerHandle> | AgentPluginListenerHandle;
+    addListener?(eventName: "agentStreamChunk", listener: (event: AgentStreamChunkEvent) => void): Promise<AgentPluginListenerHandle> | AgentPluginListenerHandle;
+    addListener?(eventName: "agentStreamComplete", listener: (event: AgentStreamCompleteEvent) => void): Promise<AgentPluginListenerHandle> | AgentPluginListenerHandle;
 }
 //# sourceMappingURL=definitions.d.ts.map

package/dist/esm/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACpE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAE9B,8BAA8B;IAC9B,IAAI,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAEjC,gCAAgC;IAChC,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAElC,gDAAgD;IAChD,IAAI,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACtD"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"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"}

package/dist/esm/definitions.js

@@ -5,7 +5,10 @@
  * communicating with the embedded Eliza agent.
  *
  * - Electrobun desktop: RPC to the main-process AgentManager
- * - iOS/Android/Web: HTTP calls to the API server
+ * - Android/Web: HTTP calls to the API server or bundled loopback agent
+ * - iOS: HTTP for remote/cloud endpoints; local dev/sideload foreground
+ *   requests bridge into the WebView ITTP kernel until the native route-kernel
+ *   backend lands
  */
 export {};
 //# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}