@independo/capacitor-inderun 1.0.1-dev.1 → 1.1.0-dev.2

package/android/src/test/kotlin/app/independo/inderun/capacitor/IndeRunSerializerStreamTest.kt

@@ -0,0 +1,226 @@
+package app.independo.inderun.capacitor
+
+import app.independo.inderun.contracts.FinishReason
+import app.independo.inderun.contracts.IndeRunErrorClass
+import app.independo.inderun.contracts.Outcome
+import app.independo.inderun.contracts.Payload
+import app.independo.inderun.contracts.PayloadError
+import app.independo.inderun.contracts.PayloadTelemetry
+import app.independo.inderun.contracts.PayloadUsage
+import app.independo.inderun.contracts.Phase
+import app.independo.inderun.contracts.SchemaVersion
+import app.independo.inderun.contracts.StreamEvent
+import app.independo.inderun.contracts.StreamRunHandle
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Encoding is what the JS side actually consumes, so these assert exact key sets: a
+ * field that encodes as null instead of being absent changes which union branch the
+ * consumer reconstitutes.
+ */
+class IndeRunSerializerStreamTest {
+
+    private fun event(
+        type: String,
+        payload: Payload?,
+        sequence: Long = 0,
+        runId: String = "run_1"
+    ): StreamEvent = StreamEvent(
+        payload = payload,
+        runId = runId,
+        schemaVersion = SchemaVersion.V1_0,
+        sequence = sequence,
+        timestamp = 1_700_000_000_000.0,
+        type = type
+    )
+
+    private fun keysOf(json: org.json.JSONObject): Set<String> =
+        json.keys().asSequence().toSet()
+
+    @Test
+    fun `encodes a content delta with only the text field`() {
+        val encoded = IndeRunSerializer.encodeStreamEvent(
+            event(type = "content_delta", payload = Payload(text = "hello"))
+        )
+
+        assertEquals("1.0", encoded.getString("schemaVersion"))
+        assertEquals("run_1", encoded.getString("runId"))
+        assertEquals(0L, encoded.getLong("sequence"))
+        assertEquals("content_delta", encoded.getString("type"))
+        assertEquals(setOf("text"), keysOf(encoded.getJSONObject("payload")))
+        assertEquals("hello", encoded.getJSONObject("payload").getString("text"))
+    }
+
+    @Test
+    fun `encodes a completed terminal outcome`() {
+        val payload = Payload(
+            finalText = "all done",
+            finishReason = FinishReason.STOP,
+            outcome = Outcome.Completed,
+            runId = "run_1",
+            schemaVersion = SchemaVersion.V1_0,
+            telemetry = PayloadTelemetry(providerUsed = "openai", totalMs = 42.0),
+            usage = PayloadUsage(inputTokens = 3, outputTokens = 5, totalTokens = 8)
+        )
+
+        val encoded = IndeRunSerializer.encodeStreamEvent(
+            event(type = "terminal", payload = payload, sequence = 4)
+        ).getJSONObject("payload")
+
+        assertEquals("completed", encoded.getString("outcome"))
+        assertEquals("all done", encoded.getString("finalText"))
+        assertEquals("stop", encoded.getString("finishReason"))
+        assertEquals(8L, encoded.getJSONObject("usage").getLong("totalTokens"))
+        assertEquals("openai", encoded.getJSONObject("telemetry").getString("providerUsed"))
+        // The other branches' fields must not leak into a completion.
+        assertFalse(encoded.has("error"))
+        assertFalse(encoded.has("partialText"))
+        assertFalse(encoded.has("reason"))
+    }
+
+    @Test
+    fun `encodes an error terminal outcome with its nested error`() {
+        val payload = Payload(
+            outcome = Outcome.Error,
+            runId = "run_1",
+            schemaVersion = SchemaVersion.V1_0,
+            error = PayloadError(
+                details = mapOf("endpoint" to "https://example.test"),
+                errorClass = IndeRunErrorClass.RateLimited,
+                message = "Too many requests.",
+                providerId = "openai",
+                retryable = true,
+                retryAfterMs = 2_000
+            ),
+            partialText = "half "
+        )
+
+        val encoded = IndeRunSerializer.encodeStreamEvent(
+            event(type = "terminal", payload = payload, sequence = 7)
+        ).getJSONObject("payload")
+
+        assertEquals("error", encoded.getString("outcome"))
+        assertEquals("half ", encoded.getString("partialText"))
+
+        val error = encoded.getJSONObject("error")
+        assertEquals("RateLimited", error.getString("errorClass"))
+        assertEquals(2_000L, error.getLong("retryAfterMs"))
+        assertTrue(error.getBoolean("retryable"))
+        assertEquals(
+            "https://example.test",
+            error.getJSONObject("details").getString("endpoint")
+        )
+    }
+
+    @Test
+    fun `omits the cancellation reason entirely when there is none`() {
+        val withReason = IndeRunSerializer.encodeStreamEvent(
+            event(
+                type = "terminal",
+                payload = Payload(
+                    outcome = Outcome.Cancelled,
+                    partialText = "part",
+                    reason = "user left"
+                )
+            )
+        ).getJSONObject("payload")
+        assertEquals("user left", withReason.getString("reason"))
+
+        val withoutReason = IndeRunSerializer.encodeStreamEvent(
+            event(
+                type = "terminal",
+                payload = Payload(outcome = Outcome.Cancelled, partialText = "part")
+            )
+        ).getJSONObject("payload")
+
+        assertEquals("cancelled", withoutReason.getString("outcome"))
+        assertEquals("part", withoutReason.getString("partialText"))
+        // Absent, not null: a null would decode as a present-but-empty reason.
+        assertFalse(withoutReason.has("reason"))
+    }
+
+    @Test
+    fun `encodes a lifecycle phase using its snake case wire value`() {
+        val encoded = IndeRunSerializer.encodeStreamEvent(
+            event(type = "lifecycle", payload = Payload(phase = Phase.ProviderSelected))
+        ).getJSONObject("payload")
+
+        assertEquals("provider_selected", encoded.getString("phase"))
+    }
+
+    /**
+     * The schema closes its union with an open catch-all branch, so an unrecognized
+     * type must cross the bridge untouched rather than be rejected — unlike the
+     * inbound request enums, which throw.
+     */
+    @Test
+    fun `passes an unknown event type through verbatim without a payload`() {
+        val encoded = IndeRunSerializer.encodeStreamEvent(
+            event(type = "some_future_type", payload = null, sequence = 2)
+        )
+
+        assertEquals("some_future_type", encoded.getString("type"))
+        assertFalse(encoded.has("payload"))
+    }
+
+    @Test
+    fun `encodes a diagnostic event with an empty payload object`() {
+        val encoded = IndeRunSerializer.encodeStreamEvent(
+            event(type = "diagnostic", payload = Payload())
+        )
+
+        assertTrue(encoded.has("payload"))
+        assertEquals(emptySet<String>(), keysOf(encoded.getJSONObject("payload")))
+    }
+
+    @Test
+    fun `encodes a stream run handle with and without a provider id`() {
+        val withProvider = IndeRunSerializer.encodeStreamRunHandle(
+            StreamRunHandle(
+                providerId = "openai",
+                runId = "run_1",
+                schemaVersion = SchemaVersion.V1_0,
+                startedAt = 1_700_000_000_000.0
+            )
+        )
+        assertEquals("openai", withProvider.getString("providerId"))
+        assertEquals("run_1", withProvider.getString("runId"))
+        assertEquals(1_700_000_000_000.0, withProvider.getDouble("startedAt"), 0.0)
+
+        val withoutProvider = IndeRunSerializer.encodeStreamRunHandle(
+            StreamRunHandle(
+                runId = "run_1",
+                schemaVersion = SchemaVersion.V1_0,
+                startedAt = 1_700_000_000_000.0
+            )
+        )
+        assertFalse(withoutProvider.has("providerId"))
+    }
+
+    /**
+     * Outcome and Phase are generated without a rawValue, so their wire strings are
+     * hand-written. If a regeneration adds a constant, the `when` stops compiling —
+     * and if one is ever mapped to the wrong casing, this catches it.
+     */
+    @Test
+    fun `every outcome and phase constant maps to a snake case wire value`() {
+        val outcomes = Outcome.entries.map { outcome ->
+            IndeRunSerializer.encodeStreamEvent(
+                event(type = "terminal", payload = Payload(outcome = outcome))
+            ).getJSONObject("payload").getString("outcome")
+        }
+        assertEquals(listOf("cancelled", "completed", "error"), outcomes)
+
+        val phases = Phase.entries.map { phase ->
+            IndeRunSerializer.encodeStreamEvent(
+                event(type = "lifecycle", payload = Payload(phase = phase))
+            ).getJSONObject("payload").getString("phase")
+        }
+        assertEquals(listOf("provider_selected", "started"), phases)
+
+        assertTrue((outcomes + phases).all { it.isNotEmpty() && it == it.lowercase() })
+    }
+}

package/android/src/test/kotlin/app/independo/inderun/capacitor/IndeRunStreamRegistryTest.kt

@@ -0,0 +1,163 @@
+package app.independo.inderun.capacitor
+
+import app.independo.inderun.contracts.SchemaVersion
+import app.independo.inderun.contracts.StreamRunHandle
+import app.independo.inderun.core.StreamRun
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.emptyFlow
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class IndeRunStreamRegistryTest {
+
+    private fun run(record: (String?) -> Unit): StreamRun = StreamRun(
+        handle = StreamRunHandle(
+            runId = "run_1",
+            schemaVersion = SchemaVersion.V1_0,
+            startedAt = 1_700_000_000_000.0
+        ),
+        events = emptyFlow(),
+        onCancel = record
+    )
+
+    @Test
+    fun `attaches and closes by stream id`() {
+        val registry = IndeRunStreamRegistry()
+
+        registry.open("s1")
+        assertEquals(AttachOutcome.Attached, registry.attach("s1", run {}))
+        assertEquals(1, registry.activeCount)
+
+        registry.close("s1")
+        assertEquals(0, registry.activeCount)
+    }
+
+    /**
+     * A cancel can beat the engine's route selection. It must be held and applied when
+     * the run finally attaches, not dropped.
+     */
+    @Test
+    fun `cancel before attach is applied on attach with its reason`() {
+        val registry = IndeRunStreamRegistry()
+        val reasons = mutableListOf<String?>()
+
+        registry.open("s1")
+        registry.requestCancel("s1", "user left")
+        // Nothing to cancel yet, so nothing was called.
+        assertTrue(reasons.isEmpty())
+
+        val outcome = registry.attach("s1", run { reasons.add(it) })
+        assertEquals(AttachOutcome.CancelRequested("user left"), outcome)
+    }
+
+    @Test
+    fun `cancel after close is a no-op`() {
+        val registry = IndeRunStreamRegistry()
+        val reasons = mutableListOf<String?>()
+
+        registry.open("s1")
+        registry.attach("s1", run { reasons.add(it) })
+        registry.close("s1")
+
+        registry.requestCancel("s1", "too late")
+        assertTrue(reasons.isEmpty())
+    }
+
+    @Test
+    fun `cancel for an unknown stream id is a no-op`() {
+        val registry = IndeRunStreamRegistry()
+
+        registry.requestCancel("never_opened", null)
+        assertEquals(0, registry.activeCount)
+    }
+
+    @Test
+    fun `repeated cancel cancels the run exactly once`() {
+        val registry = IndeRunStreamRegistry()
+        val reasons = mutableListOf<String?>()
+
+        registry.open("s1")
+        registry.attach("s1", run { reasons.add(it) })
+
+        registry.requestCancel("s1", "first")
+        registry.requestCancel("s1", "second")
+
+        assertEquals(listOf("first"), reasons)
+    }
+
+    @Test
+    fun `concurrent streams are isolated`() {
+        val registry = IndeRunStreamRegistry()
+        val first = mutableListOf<String?>()
+        val second = mutableListOf<String?>()
+
+        registry.open("s1")
+        registry.open("s2")
+        registry.attach("s1", run { first.add(it) })
+        registry.attach("s2", run { second.add(it) })
+
+        registry.requestCancel("s1", "only the first")
+
+        assertEquals(listOf("only the first"), first)
+        assertTrue(second.isEmpty())
+        assertEquals(2, registry.activeCount)
+    }
+
+    @Test
+    fun `cancelAll cancels every run once and empties the registry`() {
+        val registry = IndeRunStreamRegistry()
+        val first = mutableListOf<String?>()
+        val second = mutableListOf<String?>()
+
+        registry.open("s1")
+        registry.open("s2")
+        registry.attach("s1", run { first.add(it) })
+        registry.attach("s2", run { second.add(it) })
+
+        registry.cancelAll("torn down")
+
+        assertEquals(listOf("torn down"), first)
+        assertEquals(listOf("torn down"), second)
+        assertEquals(0, registry.activeCount)
+    }
+
+    /**
+     * Teardown also cancels the collecting jobs — at that point nobody is left to
+     * receive a terminal event.
+     */
+    @Test
+    fun `cancelAll cancels the collecting job`() {
+        val registry = IndeRunStreamRegistry()
+        val job = Job()
+
+        registry.open("s1")
+        registry.attach("s1", run {})
+        registry.attachJob("s1", job)
+
+        assertFalse(job.isCancelled)
+        registry.cancelAll(null)
+        assertTrue(job.isCancelled)
+    }
+
+    @Test
+    fun `attach after teardown reports cancel requested`() {
+        val registry = IndeRunStreamRegistry()
+
+        registry.open("s1")
+        registry.cancelAll("torn down")
+
+        // The entry is gone, so the run that arrives late must be cancelled by its caller.
+        assertEquals(AttachOutcome.CancelRequested(null), registry.attach("s1", run {}))
+    }
+
+    @Test
+    fun `a job attached to a closed stream is cancelled immediately`() {
+        val registry = IndeRunStreamRegistry()
+        val job = Job()
+
+        registry.attachJob("never_opened", job)
+        assertTrue(job.isCancelled)
+    }
+}

package/dist/definitions.d.ts

@@ -1,4 +1,5 @@
-import type { TaskRequest, TaskResult } from "@independo/inderun-contracts";
+import type { PluginListenerHandle } from "@capacitor/core";
+import type { IndeRunError, StreamEvent, StreamRunHandle, TaskRequest, TaskResult } from "@independo/inderun-contracts";
 export interface OpenAIProviderBootstrapOptions {
     model: string;
     endpointUrl?: string;
@@ -10,8 +11,60 @@ export interface ConfigureOptions {
     openAI?: OpenAIProviderBootstrapOptions;
     allowDirectOpenAIEndpoint?: boolean;
 }
+/**
+ * Bridge-local correlation id for one streaming run.
+ *
+ * Not a contract field, and never placed inside the `TaskRequest`: `runId` stays the
+ * engine's to mint. `startStream` resolves only *after* the engine has minted one, so
+ * keying the JS-side event sink on `runId` would leave a window in which native can
+ * emit events for a run JS has not yet heard of. The `streamId` is generated before
+ * the call instead, which lets the sink be bound first and makes `cancel()`
+ * well-defined even before a handle exists.
+ */
+export interface StartStreamOptions {
+    streamId: string;
+    request: TaskRequest;
+}
+export interface CancelStreamOptions {
+    streamId: string;
+    reason?: string;
+}
+/** Payload of `"indeRunStreamEvent"`. `event` is the canonical, unmodified `StreamEvent`. */
+export interface StreamEventNotification {
+    streamId: string;
+    event: StreamEvent;
+}
+/**
+ * Payload of `"indeRunStreamError"`: a failure of the *bridge*, not an outcome of the
+ * run. A run that fails ends in a terminal event with `payload.outcome === "error"`,
+ * delivered through `"indeRunStreamEvent"` like any other event.
+ */
+export interface StreamErrorNotification {
+    streamId: string;
+    error: IndeRunError;
+}
+/**
+ * Structurally identical to `StreamRun` in `@independo/inderun-web`, so bridge and
+ * direct-SDK consumers read the same. `events` terminates in exactly one terminal
+ * event and is single-use; `cancel()` is idempotent.
+ */
+export interface StreamRun {
+    handle: StreamRunHandle;
+    events: AsyncIterable<StreamEvent>;
+    cancel(reason?: string): void;
+}
 export interface IndeRunCapacitorPlugin {
     configure(options?: ConfigureOptions): Promise<void>;
     run(request: TaskRequest): Promise<TaskResult>;
+    /**
+     * Unlike `run(request)`, which passes the request at the options root, this nests it
+     * under `request` so the envelope can also carry `streamId`. Both native decode sites
+     * carry a matching comment.
+     */
+    startStream(options: StartStreamOptions): Promise<StreamRunHandle>;
+    cancelStream(options: CancelStreamOptions): Promise<void>;
+    addListener(eventName: "indeRunStreamEvent", listenerFunc: (notification: StreamEventNotification) => void): Promise<PluginListenerHandle>;
+    addListener(eventName: "indeRunStreamError", listenerFunc: (notification: StreamErrorNotification) => void): Promise<PluginListenerHandle>;
+    removeAllListeners(): Promise<void>;
 }
 //# sourceMappingURL=definitions.d.ts.map

package/dist/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE5E,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,8BAA8B,CAAC;IACxC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAChD"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,WAAW,EACX,UAAU,EACX,MAAM,8BAA8B,CAAC;AAEtC,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,8BAA8B,CAAC;IACxC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6FAA6F;AAC7F,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/C;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACnE,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,WAAW,CACT,SAAS,EAAE,oBAAoB,EAC/B,YAAY,EAAE,CAAC,YAAY,EAAE,uBAAuB,KAAK,IAAI,GAC5D,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjC,WAAW,CACT,SAAS,EAAE,oBAAoB,EAC/B,YAAY,EAAE,CAAC,YAAY,EAAE,uBAAuB,KAAK,IAAI,GAC5D,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjC,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC"}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+import { type IndeRunError } from "@independo/inderun-contracts";
+/**
+ * Unwraps whatever the Capacitor boundary hands back into the canonical
+ * `IndeRunError` the native side rejected with.
+ *
+ * Capacitor wraps a native rejection's structured data under `error.data`, so a
+ * thrown value is either already an `IndeRunError` (the web implementation throws
+ * one directly) or carries one there. Anything else is passed through untouched
+ * rather than guessed at.
+ */
+export declare function normalizePluginError(error: unknown): unknown;
+/**
+ * Mints an `IndeRunError` for a failure of the bridge itself — event loss across
+ * the JS boundary, a malformed handle — as opposed to one reported by a provider
+ * or the engine. `Internal` is the correct class: nothing about the request or the
+ * provider is at fault, the transport is.
+ */
+export declare function createBridgeError(message: string, runId?: string): IndeRunError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEvF;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAe5D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,CAO/E"}

package/dist/errors.js

@@ -0,0 +1,36 @@
+import { validateIndeRunError } from "@independo/inderun-contracts";
+/**
+ * Unwraps whatever the Capacitor boundary hands back into the canonical
+ * `IndeRunError` the native side rejected with.
+ *
+ * Capacitor wraps a native rejection's structured data under `error.data`, so a
+ * thrown value is either already an `IndeRunError` (the web implementation throws
+ * one directly) or carries one there. Anything else is passed through untouched
+ * rather than guessed at.
+ */
+export function normalizePluginError(error) {
+    if (validateIndeRunError(error)) {
+        return error;
+    }
+    if (typeof error === "object" &&
+        error !== null &&
+        "data" in error &&
+        validateIndeRunError(error.data)) {
+        return error.data;
+    }
+    return error;
+}
+/**
+ * Mints an `IndeRunError` for a failure of the bridge itself — event loss across
+ * the JS boundary, a malformed handle — as opposed to one reported by a provider
+ * or the engine. `Internal` is the correct class: nothing about the request or the
+ * provider is at fault, the transport is.
+ */
+export function createBridgeError(message, runId) {
+    return {
+        schemaVersion: "1.0",
+        errorClass: "Internal",
+        message,
+        ...(runId !== undefined ? { runId } : {})
+    };
+}

package/dist/index.d.ts

@@ -1,10 +1,20 @@
-import { type TaskRequest, type TaskResult } from "@independo/inderun-contracts";
-import type { ConfigureOptions, IndeRunCapacitorPlugin as IndeRunCapacitorPluginContract, OpenAIProviderBootstrapOptions } from "./definitions.js";
-export declare const IndeRunCapacitor: IndeRunCapacitorPluginContract;
+import type { TaskRequest, TaskResult } from "@independo/inderun-contracts";
+import type { CancelStreamOptions, ConfigureOptions, IndeRunCapacitorPlugin as IndeRunCapacitorPluginContract, OpenAIProviderBootstrapOptions, StartStreamOptions, StreamErrorNotification, StreamEventNotification, StreamRun } from "./definitions.js";
+/**
+ * The plugin contract plus the ergonomic Mode 2 entry point. `stream()` is not a
+ * plugin method — it is `startStream`, the event listeners, and `cancelStream`
+ * reassembled into the same shape the platform SDKs return from `stream()`.
+ */
+export interface IndeRunCapacitorApi extends IndeRunCapacitorPluginContract {
+    stream(request: TaskRequest): Promise<StreamRun>;
+}
+export declare const IndeRunCapacitor: IndeRunCapacitorApi;
 export interface IndeRunCapacitorInstance {
     run(request: TaskRequest): Promise<TaskResult>;
+    stream(request: TaskRequest): Promise<StreamRun>;
 }
 export declare function createIndeRunCapacitor(options?: ConfigureOptions): IndeRunCapacitorInstance;
-export type { ConfigureOptions, IndeRunCapacitorPluginContract as IndeRunCapacitorPlugin, OpenAIProviderBootstrapOptions, TaskRequest, TaskResult };
+export { STREAM_ERROR_NAME, STREAM_EVENT_NAME } from "./streaming.js";
+export type { CancelStreamOptions, ConfigureOptions, IndeRunCapacitorPluginContract as IndeRunCapacitorPlugin, OpenAIProviderBootstrapOptions, StartStreamOptions, StreamErrorNotification, StreamEventNotification, StreamRun, TaskRequest, TaskResult };
 export type * from "@independo/inderun-contracts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,IAAI,8BAA8B,EACxD,8BAA8B,EAC/B,MAAM,kBAAkB,CAAC;AAuB1B,eAAO,MAAM,gBAAgB,EAAE,8BAgB9B,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAChD;AAED,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,wBAAwB,CAiB3F;AAED,YAAY,EACV,gBAAgB,EAChB,8BAA8B,IAAI,sBAAsB,EACxD,8BAA8B,EAC9B,WAAW,EACX,UAAU,EACX,CAAC;AAEF,mBAAmB,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,WAAW,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE7F,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,IAAI,8BAA8B,EACxD,8BAA8B,EAC9B,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,SAAS,EACV,MAAM,kBAAkB,CAAC;AAQ1B;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,8BAA8B;IACzE,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAClD;AAED,eAAO,MAAM,gBAAgB,EAAE,mBA4C9B,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAClD;AAED,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,wBAAwB,CAsB3F;AAED,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEtE,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,8BAA8B,IAAI,sBAAsB,EACxD,8BAA8B,EAC9B,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,SAAS,EACT,WAAW,EACX,UAAU,EACX,CAAC;AAEF,mBAAmB,8BAA8B,CAAC"}

package/dist/index.js

@@ -1,20 +1,9 @@
-import { validateIndeRunError } from "@independo/inderun-contracts";
 import { registerPlugin } from "@capacitor/core";
+import { normalizePluginError } from "./errors.js";
+import { startCapacitorStream } from "./streaming.js";
 const IndeRunCapacitorNative = registerPlugin("IndeRunCapacitor", {
     web: () => import("./web.js").then((module) => new module.IndeRunWeb())
 });
-function normalizePluginError(error) {
-    if (validateIndeRunError(error)) {
-        return error;
-    }
-    if (typeof error === "object" &&
-        error !== null &&
-        "data" in error &&
-        validateIndeRunError(error.data)) {
-        return error.data;
-    }
-    return error;
-}
 export const IndeRunCapacitor = {
     async configure(options) {
         try {
@@ -31,6 +20,29 @@ export const IndeRunCapacitor = {
         catch (error) {
             throw normalizePluginError(error);
         }
+    },
+    async startStream(options) {
+        try {
+            return await IndeRunCapacitorNative.startStream(options);
+        }
+        catch (error) {
+            throw normalizePluginError(error);
+        }
+    },
+    async cancelStream(options) {
+        try {
+            await IndeRunCapacitorNative.cancelStream(options);
+        }
+        catch (error) {
+            throw normalizePluginError(error);
+        }
+    },
+    addListener: IndeRunCapacitorNative.addListener.bind(IndeRunCapacitorNative),
+    async removeAllListeners() {
+        await IndeRunCapacitorNative.removeAllListeners();
+    },
+    stream(request) {
+        return startCapacitorStream(IndeRunCapacitorNative, request);
     }
 };
 export function createIndeRunCapacitor(options) {
@@ -46,6 +58,11 @@ export function createIndeRunCapacitor(options) {
         async run(request) {
             await ensureConfigured();
             return IndeRunCapacitor.run(request);
+        },
+        async stream(request) {
+            await ensureConfigured();
+            return IndeRunCapacitor.stream(request);
         }
     };
 }
+export { STREAM_ERROR_NAME, STREAM_EVENT_NAME } from "./streaming.js";

package/dist/streaming.d.ts

@@ -0,0 +1,17 @@
+import { type TaskRequest } from "@independo/inderun-contracts";
+import type { IndeRunCapacitorPlugin, StreamRun } from "./definitions.js";
+/**
+ * Listener event names. These are **public contract**: an app may attach its own
+ * listener, and native code emits exactly these. Renaming one is a breaking change.
+ */
+export declare const STREAM_EVENT_NAME = "indeRunStreamEvent";
+export declare const STREAM_ERROR_NAME = "indeRunStreamError";
+/**
+ * Starts a Mode 2 run over the bridge and reassembles it into the same `StreamRun`
+ * shape `@independo/inderun-web` returns directly.
+ *
+ * The listeners are registered *before* `startStream` is called, so no event can be
+ * emitted for a run whose sink does not exist yet.
+ */
+export declare function startCapacitorStream(plugin: IndeRunCapacitorPlugin, request: TaskRequest): Promise<StreamRun>;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EACV,sBAAsB,EAGtB,SAAS,EACV,MAAM,kBAAkB,CAAC;AAG1B;;;GAGG;AACH,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AACtD,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AA6QtD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,SAAS,CAAC,CAwDpB"}