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

package/Package.swift

@@ -20,7 +20,11 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
-        .package(url: "https://github.com/independo-gmbh/inderun.git", from: "0.2.2")
+        // `exact:` rather than `from:` while tracking a prerelease: SwiftPM's range
+        // operators exclude prerelease versions, so `from: "0.3.0-dev.14"` would
+        // silently keep resolving 0.2.2 and fail on the missing stream(). Move back
+        // to `from: "0.3.0"` once the stable release is out.
+        .package(url: "https://github.com/independo-gmbh/inderun.git", exact: "0.3.0-dev.14")
     ],
     targets: [
         .target(

package/README.md

@@ -14,7 +14,7 @@
 
 <p align="center">Built and maintained by <a href="https://www.independo.app/">Independo</a>.</p>
 
-Thin Capacitor bridge for IndeRun Mode 1 `run()` execution.
+Thin Capacitor bridge for IndeRun Mode 1 `run()` and Mode 2 `stream()` execution.
 
 The package delegates to the released [IndeRun](https://github.com/independo-gmbh/inderun)
 platform SDKs instead of re-implementing routing, provider logic, or normalized error handling:
@@ -63,15 +63,68 @@ const result = await inderun.run({
 });
 ```
 
+## Streaming (Mode 2)
+
+`stream()` returns the same `StreamRun` shape the platform SDKs return directly: the
+run's handle, its canonical event sequence, and a cancel hook.
+
+```ts
+const run = await inderun.stream({
+  schemaVersion: "1.0",
+  task: { kind: "text_to_text" },
+  prompt: "Explain routing in two sentences."
+});
+
+console.log(run.handle.runId); // available before the first event
+
+let text = "";
+for await (const event of run.events) {
+  switch (event.type) {
+    case "content_delta":
+      text += event.payload.text;       // append
+      break;
+    case "content_snapshot":
+      text = event.payload.text ?? "";  // replace — an empty one retracts
+      break;
+    case "terminal":
+      // exactly one of "completed" | "error" | "cancelled"
+      console.log(event.payload.outcome);
+      break;
+  }
+}
+
+run.cancel("user navigated away"); // idempotent; a no-op after the terminal
+```
+
+Three things worth knowing before you build on it:
+
+- **Order by `sequence`, not arrival.** The bridge hop is not order-preserving, which is
+  why `sequence` is the contract's ordering authority. `events` already yields strictly by
+  it; if you attach your own listener instead, you must order them yourself.
+- **A failed run is not a rejected promise.** See [Error Handling](#error-handling).
+- **Handle `content_snapshot` even from a token-streaming provider.** A snapshot replaces
+  the cumulative text rather than appending to it, and an empty one is how a provider
+  retracts content it already delivered — for example when an on-device safety check
+  rejects a half-generated response.
+
 ## API
 
-- `createIndeRunCapacitor(options)` — returns a handle that lazily `configure()`s on the first `run()` and memoizes it. Safe to call once at app startup.
-- The low-level plugin methods `configure(options)` and `run(request)` are also exported.
+- `createIndeRunCapacitor(options)` — returns a handle that lazily `configure()`s on the first `run()` or `stream()` and memoizes it. Safe to call once at app startup.
+- `run(request)` — Mode 1. Resolves with the canonical IndeRun `TaskResult`.
+- `stream(request)` — Mode 2. Resolves with a `StreamRun` (`handle`, `events`, `cancel`). `events` is single-use.
+- The low-level plugin methods `configure(options)`, `startStream(options)` and `cancelStream(options)` are also exported, along with the listener event names `STREAM_EVENT_NAME` (`"indeRunStreamEvent"`) and `STREAM_ERROR_NAME` (`"indeRunStreamError"`).
+
+> The two listener event names are **public contract**. Native emits exactly these, and an
+> app may attach its own listener to them; renaming one is a breaking change.
 
 The `IndeRunCapacitorPlugin`, `ConfigureOptions`, and `OpenAIProviderBootstrapOptions`
 contracts — including the `openAI` bootstrap config and the web-only
 `allowDirectOpenAIEndpoint` flag — are defined and documented in
-`src/definitions.ts`. `run()` returns the canonical IndeRun `TaskResult`.
+`src/definitions.ts`.
+
+Note one asymmetry in the low-level surface: `run(request)` passes the request at the
+options root, while `startStream({ streamId, request })` nests it, because that envelope
+also carries the bridge-local correlation id. `stream()` hides this.
 
 ## Platform Notes
 
@@ -82,12 +135,33 @@ contracts — including the `openAI` bootstrap config and the web-only
 
 ## Current Limitations
 
-- Mode 1 `run()` only.
+- Mode 1 `run()` and Mode 2 `stream()` are supported. Mode 3 sessions are not.
+- **No backpressure across the bridge.** Native pushes events; a slow consumer buys memory,
+  not throttling, because events buffer in JS until they are read. Runs are finite and
+  terminal-bounded, and any drop or throttle policy would be behaviour — which belongs in
+  the engines, not in a bridge.
+- Which providers can actually stream is decided upstream, not here; see the
+  [provider matrix](https://github.com/independo-gmbh/inderun/blob/main/docs/architecture/providers.md#provider-matrix).
+- An unrecognized `StreamEvent.type` is passed through untouched rather than rejected, so a
+  consumer built against an older contract revision keeps working when a newer one adds an
+  event type. Ignore what you do not recognize.
 - No plugin-level credential management API is exposed in this first cut.
 - The bridge is intentionally thin; cloud provider bootstrap still has to come from the app.
 
 ## Error Handling
 
+A streaming run has **three** distinct failure surfaces, and conflating them is the easiest
+mistake to make:
+
+| Surface | When | How it reaches you |
+| --- | --- | --- |
+| Rejection | Request validation, or no streaming-capable provider | `stream()` rejects with an `IndeRunError` |
+| Terminal `error` event | A provider failed, or the whole planned chain did | **Not** a rejection — `for await` completes normally and the last event is `terminal` with `payload.outcome === "error"` |
+| Bridge fault | The transport lost or could not encode events | `events` throws an `Internal` `IndeRunError` |
+
+So a run that fails *after starting* ends your loop normally. Branch on
+`event.payload.outcome` to tell completion from failure from cancellation.
+
 Errors thrown by `configure()` and `run()` conform to `IndeRunError` from
 `@independo/inderun-contracts`; branch on `error.errorClass` (the shared error
 taxonomy). The bridge unwraps the native error envelope before re-throwing, so

package/android/build.gradle.kts

@@ -37,11 +37,11 @@ dependencies {
     testImplementation("com.capacitorjs:core:8.0.0")
     implementation("androidx.appcompat:appcompat:1.7.1")
     implementation("androidx.core:core-ktx:1.17.0")
-    implementation("app.independo.inderun:inderun-contracts:0.2.2")
-    implementation("app.independo.inderun:inderun-core:0.2.2")
-    implementation("app.independo.inderun:inderun-kotlin:0.2.2")
-    implementation("app.independo.inderun:inderun-mlkit-providers:0.2.2")
-    implementation("app.independo.inderun:inderun-openai-providers:0.2.2")
+    implementation("app.independo.inderun:inderun-contracts:0.3.0-dev.14")
+    implementation("app.independo.inderun:inderun-core:0.3.0-dev.14")
+    implementation("app.independo.inderun:inderun-kotlin:0.3.0-dev.14")
+    implementation("app.independo.inderun:inderun-mlkit-providers:0.3.0-dev.14")
+    implementation("app.independo.inderun:inderun-openai-providers:0.3.0-dev.14")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2")
 
     testImplementation("junit:junit:4.13.2")

package/android/src/main/kotlin/app/independo/inderun/capacitor/IndeRunCapacitorPlugin.kt

@@ -1,5 +1,6 @@
 package app.independo.inderun.capacitor
 
+import app.independo.inderun.contracts.IndeRunError
 import app.independo.inderun.core.IndeRunException
 import app.independo.inderun.core.ProviderRegistry
 import app.independo.inderun.core.toIndeRunException
@@ -9,10 +10,12 @@ import app.independo.inderun.providers.openai.OpenAIAuthMode
 import app.independo.inderun.providers.openai.OpenAIProvider
 import app.independo.inderun.providers.openai.OpenAIProviderOptions
 import app.independo.inderun.sdk.IndeRun
+import com.getcapacitor.JSObject
 import com.getcapacitor.Plugin
 import com.getcapacitor.PluginCall
 import com.getcapacitor.PluginMethod
 import com.getcapacitor.annotation.CapacitorPlugin
+import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
@@ -23,6 +26,7 @@ import kotlinx.coroutines.launch
 class IndeRunCapacitorPlugin : Plugin() {
     private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
     private var configuredRegistry: ProviderRegistry? = null
+    private val streams = IndeRunStreamRegistry()
 
     @PluginMethod
     fun configure(call: PluginCall) {
@@ -83,11 +87,126 @@ class IndeRunCapacitorPlugin : Plugin() {
         }
     }
 
+    /**
+     * Resolves with the run handle. Only validation and route-selection failures reject;
+     * a provider failure, a cancellation, or completion all arrive as the single terminal
+     * event on `indeRunStreamEvent` — which is why [resolved] is tracked: a PluginCall
+     * must settle exactly once, and a failure after the handle has gone back is an event,
+     * not a rejection.
+     *
+     * `retainUntilConsumed` closes the listener-registration race from the native side: an
+     * event emitted before the JS listener attaches is retained and replayed, not lost.
+     */
+    @PluginMethod
+    fun startStream(call: PluginCall) {
+        val streamId = call.getString("streamId")
+        if (streamId == null) {
+            rejectContractError(call, IllegalArgumentException("startStream requires a streamId."))
+            return
+        }
+        // Unlike run(request), which takes the request at the options root, startStream
+        // nests it under `request` so the envelope can also carry the bridge-local streamId.
+        val requestJson = call.getObject("request")
+        if (requestJson == null) {
+            rejectContractError(call, IllegalArgumentException("startStream requires a request."))
+            return
+        }
+
+        // Reserved before the engine is reached, so a cancel arriving during route
+        // selection is recorded rather than dropped as an unknown id.
+        streams.open(streamId)
+
+        val job = scope.launch {
+            var resolved = false
+            try {
+                val registry = configuredRegistry
+                    ?: throw toIndeRunException(IllegalStateException("Capacitor IndeRun has not been configured. Configure providers before calling stream(request)."))
+                val request = IndeRunSerializer.parseTaskRequest(requestJson)
+                // IndeRun is stateless; new per call is intentional — registry is cached after configure().
+                val streamRun = IndeRun.initialize(context.applicationContext, registry).stream(request)
+
+                val outcome = streams.attach(streamId, streamRun)
+                if (outcome is AttachOutcome.CancelRequested) {
+                    streamRun.cancel(outcome.reason)
+                }
+
+                call.resolve(IndeRunSerializer.encodeStreamRunHandle(streamRun.handle))
+                resolved = true
+
+                // The Flow is cold and single-use; collecting it exactly once here is what
+                // drives the run.
+                streamRun.events.collect { event ->
+                    val payload = JSObject()
+                    payload.put("streamId", streamId)
+                    payload.put("event", IndeRunSerializer.encodeStreamEvent(event))
+                    notifyListeners("indeRunStreamEvent", payload, true)
+                }
+            } catch (error: CancellationException) {
+                throw error
+            } catch (error: Throwable) {
+                val contractError = contractErrorFor(error)
+                if (resolved) {
+                    val payload = JSObject()
+                    payload.put("streamId", streamId)
+                    payload.put(
+                        "error",
+                        runCatching { IndeRunSerializer.encodeError(contractError) }.getOrNull()
+                    )
+                    notifyListeners("indeRunStreamError", payload, true)
+                } else {
+                    call.reject(
+                        contractError.message,
+                        contractError.errorClass.rawValue,
+                        null,
+                        runCatching { IndeRunSerializer.encodeError(contractError) }.getOrNull()
+                    )
+                }
+            } finally {
+                streams.close(streamId)
+            }
+        }
+
+        streams.attachJob(streamId, job)
+    }
+
+    /**
+     * Resolves for an unknown or already-finished run: cancelling after the terminal is a
+     * no-op by contract, not an error.
+     */
+    @PluginMethod
+    fun cancelStream(call: PluginCall) {
+        val streamId = call.getString("streamId")
+        if (streamId == null) {
+            rejectContractError(call, IllegalArgumentException("cancelStream requires a streamId."))
+            return
+        }
+
+        streams.requestCancel(streamId, call.getString("reason"))
+        call.resolve()
+    }
+
     override fun handleOnDestroy() {
+        // Runs first, so providers unwind before the scope that collects them goes away.
+        streams.cancelAll("Capacitor plugin destroyed.")
         scope.cancel()
         super.handleOnDestroy()
     }
 
+    private fun contractErrorFor(error: Throwable): IndeRunError = when (error) {
+        is IndeRunException -> error.toContractError()
+        else -> toIndeRunException(error).toContractError()
+    }
+
+    private fun rejectContractError(call: PluginCall, error: Throwable) {
+        val contractError = contractErrorFor(error)
+        call.reject(
+            contractError.message,
+            contractError.errorClass.rawValue,
+            null,
+            runCatching { IndeRunSerializer.encodeError(contractError) }.getOrNull()
+        )
+    }
+
     private fun createRegistry(openAI: OpenAIProviderBootstrapOptions?): ProviderRegistry {
         val registry = AndroidProviderRegistryFactory.makeDefaultRegistry(context.applicationContext)
 

package/android/src/main/kotlin/app/independo/inderun/capacitor/IndeRunSerializer.kt

@@ -8,9 +8,17 @@ import app.independo.inderun.contracts.IndeRunErrorClass
 import app.independo.inderun.contracts.Message
 import app.independo.inderun.contracts.MessageRole
 import app.independo.inderun.contracts.OptimizeFor
+import app.independo.inderun.contracts.Outcome
 import app.independo.inderun.contracts.OutputType
+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.PrivacyEnum
 import app.independo.inderun.contracts.SchemaVersion
+import app.independo.inderun.contracts.StreamEvent
+import app.independo.inderun.contracts.StreamRunHandle
 import app.independo.inderun.contracts.TaskKind
 import app.independo.inderun.contracts.TaskRequest
 import app.independo.inderun.contracts.TaskRequestConstraints
@@ -20,7 +28,6 @@ import app.independo.inderun.contracts.TaskRequestTelemetry
 import app.independo.inderun.contracts.TaskResult
 import app.independo.inderun.contracts.TaskResultTelemetry
 import app.independo.inderun.contracts.TelemetryLevel
-import app.independo.inderun.contracts.Usage
 import com.getcapacitor.JSArray
 import com.getcapacitor.JSObject
 import org.json.JSONArray
@@ -106,6 +113,104 @@ object IndeRunSerializer {
         }
     }
 
+    fun encodeStreamRunHandle(handle: StreamRunHandle): JSObject {
+        return JSObject().apply {
+            put("schemaVersion", handle.schemaVersion.rawValue)
+            put("runId", handle.runId)
+            put("startedAt", handle.startedAt)
+            handle.providerId?.let { put("providerId", it) }
+        }
+    }
+
+    /**
+     * Note what is deliberately *not* here: a `when` over [StreamEvent.type].
+     *
+     * The inbound parsers in this file throw on an unrecognized enum value, and that is
+     * right for them — those are closed contract enums on a request, where an unknown
+     * value really is an invalid request. `type` is the opposite: stream-event.schema.json
+     * closes its union with an explicit catch-all branch, and contracts/README.md requires
+     * SDKs to treat an unrecognized type as ignore-or-pass-through rather than an error, so
+     * that an additive minor revision does not break older consumers. Copying the
+     * throw-on-unknown pattern here would turn the one mechanism protecting forward
+     * compatibility into a guaranteed hard failure at the bridge hop. The type crosses as
+     * the string it is.
+     */
+    fun encodeStreamEvent(event: StreamEvent): JSObject {
+        return JSObject().apply {
+            put("schemaVersion", event.schemaVersion.rawValue)
+            put("runId", event.runId)
+            put("sequence", event.sequence)
+            put("timestamp", event.timestamp)
+            put("type", event.type)
+            event.payload?.let { put("payload", encodeStreamPayload(it)) }
+        }
+    }
+
+    /**
+     * quicktype flattens the event union, so [Payload] carries every branch's fields as
+     * optionals. Emitting only the non-null ones is what reconstitutes the correct branch
+     * on the JS side: each branch's `outcome` discriminator plus its required peer field
+     * (finalText / error / partialText) is exactly the set that is populated.
+     */
+    private fun encodeStreamPayload(payload: Payload): JSObject {
+        return JSObject().apply {
+            payload.text?.let { put("text", it) }
+            payload.phase?.let { put("phase", phaseValue(it)) }
+            payload.finalText?.let { put("finalText", it) }
+            payload.finishReason?.let { put("finishReason", it.rawValue) }
+            payload.outcome?.let { put("outcome", outcomeValue(it)) }
+            payload.runId?.let { put("runId", it) }
+            payload.schemaVersion?.let { put("schemaVersion", it.rawValue) }
+            payload.telemetry?.let { put("telemetry", encodeStreamPayloadTelemetry(it)) }
+            payload.usage?.let { put("usage", encodeStreamPayloadUsage(it)) }
+            payload.error?.let { put("error", encodeStreamPayloadError(it)) }
+            payload.partialText?.let { put("partialText", it) }
+            payload.reason?.let { put("reason", it) }
+        }
+    }
+
+    private fun encodeStreamPayloadError(error: PayloadError): JSObject {
+        return JSObject().apply {
+            put("schemaVersion", error.schemaVersion.rawValue)
+            put("errorClass", error.errorClass.rawValue)
+            put("message", error.message)
+            error.providerId?.let { put("providerId", it) }
+            error.retryable?.let { put("retryable", it) }
+            error.retryAfterMs?.let { put("retryAfterMs", it) }
+            error.details?.let { put("details", JSONObject(it)) }
+        }
+    }
+
+    private fun encodeStreamPayloadTelemetry(telemetry: PayloadTelemetry): JSObject {
+        return JSObject().apply {
+            put("providerUsed", telemetry.providerUsed)
+            put("totalMs", telemetry.totalMs)
+        }
+    }
+
+    private fun encodeStreamPayloadUsage(usage: PayloadUsage): JSObject {
+        return JSObject().apply {
+            usage.inputTokens?.let { put("inputTokens", it) }
+            usage.outputTokens?.let { put("outputTokens", it) }
+            usage.totalTokens?.let { put("totalTokens", it) }
+        }
+    }
+
+    // Outcome and Phase are generated without a rawValue, unlike every other contract enum
+    // here, so the wire strings have to be written out. Both `when`s are exhaustive with no
+    // `else`: if a regeneration ever adds a constant, this must fail to compile rather than
+    // silently serialize the wrong discriminator.
+    private fun outcomeValue(outcome: Outcome): String = when (outcome) {
+        Outcome.Completed -> "completed"
+        Outcome.Error -> "error"
+        Outcome.Cancelled -> "cancelled"
+    }
+
+    private fun phaseValue(phase: Phase): String = when (phase) {
+        Phase.ProviderSelected -> "provider_selected"
+        Phase.Started -> "started"
+    }
+
     private fun parseOpenAIOptions(json: JSONObject): OpenAIProviderBootstrapOptions {
         return OpenAIProviderBootstrapOptions(
             model = json.getString("model"),

package/android/src/main/kotlin/app/independo/inderun/capacitor/IndeRunStreamRegistry.kt

@@ -0,0 +1,118 @@
+package app.independo.inderun.capacitor
+
+import app.independo.inderun.core.StreamRun
+import kotlinx.coroutines.Job
+
+/**
+ * The outcome of attaching a freshly started run to its reserved id.
+ */
+internal sealed interface AttachOutcome {
+    data object Attached : AttachOutcome
+
+    /** A cancel arrived before the run did; the caller must apply it. */
+    data class CancelRequested(val reason: String?) : AttachOutcome
+}
+
+/**
+ * Tracks the streaming runs the plugin is currently collecting, keyed by the
+ * bridge-local `streamId`.
+ *
+ * Two things make this more than a map. A cancel can arrive before the run it refers
+ * to exists — `startStream` has to reach route selection first — so a cancel in that
+ * window is recorded and applied on attach. And cancelling a run is *not* cancelling
+ * the collecting job: the engine answers a cancel with its one `cancelled` terminal
+ * event, which the collector still has to deliver. Job cancellation is reserved for
+ * teardown, where the webview is going away and nobody is left to receive a terminal.
+ *
+ * Deliberately free of any Capacitor dependency, so it is exercised by plain JVM unit
+ * tests.
+ */
+internal class IndeRunStreamRegistry {
+    private class Entry {
+        var run: StreamRun? = null
+        var job: Job? = null
+        var cancelRequested: Boolean = false
+        var cancelReason: String? = null
+    }
+
+    private val lock = Any()
+    private val entries = mutableMapOf<String, Entry>()
+
+    val activeCount: Int
+        get() = synchronized(lock) { entries.size }
+
+    /** Reserves the id so a cancel arriving before the run is recorded, not dropped. */
+    fun open(streamId: String) {
+        synchronized(lock) {
+            entries.getOrPut(streamId) { Entry() }
+        }
+    }
+
+    fun attach(streamId: String, run: StreamRun): AttachOutcome {
+        synchronized(lock) {
+            // Torn down while the engine was still selecting a route.
+            val entry = entries[streamId] ?: return AttachOutcome.CancelRequested(null)
+            if (entry.cancelRequested) {
+                return AttachOutcome.CancelRequested(entry.cancelReason)
+            }
+            entry.run = run
+            return AttachOutcome.Attached
+        }
+    }
+
+    fun attachJob(streamId: String, job: Job) {
+        val orphaned = synchronized(lock) {
+            val entry = entries[streamId]
+            if (entry == null) {
+                true
+            } else {
+                entry.job = job
+                false
+            }
+        }
+        if (orphaned) {
+            job.cancel()
+        }
+    }
+
+    /**
+     * Cancels the run if it has attached, otherwise records the request for attach. An
+     * unknown id — already finished, or never started — is a silent no-op, which is what
+     * makes cancelling after the terminal harmless.
+     */
+    fun requestCancel(streamId: String, reason: String?) {
+        val run = synchronized(lock) {
+            val entry = entries[streamId] ?: return
+            if (entry.cancelRequested) return
+            entry.cancelRequested = true
+            entry.cancelReason = reason
+            entry.run
+        }
+
+        // Never under the lock: cancel reaches into engine code.
+        run?.cancel(reason)
+    }
+
+    fun close(streamId: String) {
+        synchronized(lock) {
+            entries.remove(streamId)
+        }
+    }
+
+    /**
+     * Teardown. Cancels each run first so providers unwind, then the collecting jobs,
+     * which at this point have nobody left to deliver to.
+     */
+    fun cancelAll(reason: String?) {
+        val draining = synchronized(lock) {
+            val copy = entries.values.toList()
+            entries.clear()
+            copy
+        }
+
+        for (entry in draining) {
+            entry.run?.cancel(reason)
+            entry.job?.cancel()
+        }
+    }
+}