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

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,9 @@ 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 app.independo.inderun.core.ProviderCapabilitySnapshot
+import app.independo.inderun.core.ProviderDescriptor
+import app.independo.inderun.core.ProviderDynamicCapabilities
 import com.getcapacitor.JSArray
 import com.getcapacitor.JSObject
 import org.json.JSONArray
@@ -106,6 +116,198 @@ object IndeRunSerializer {
         }
     }
 
+    /**
+     * Wire encoding for `checkCapabilities()`.
+     *
+     * Note the enums are written with `.name`, which is the opposite of what
+     * [encodeOutcome] and [encodePhase] below have to do. Those contract enums are
+     * generated without raw values, so their Kotlin constant names are camelCase and the
+     * snake_case wire spelling has to be written by hand. `ProviderDescriptor`'s enums are
+     * declared with the wire spelling *as* the constant name (`in_process`,
+     * `system_service`), so `.name` already is the wire value — and writing them by hand
+     * here would be the thing that eventually drifts.
+     *
+     * The array is wrapped in a `providers` object because a Capacitor `PluginCall` cannot
+     * resolve a top-level array. `IndeRunCapacitor` unwraps it on the JS side.
+     */
+    fun encodeCapabilitySnapshots(snapshots: List<ProviderCapabilitySnapshot>): JSObject {
+        return JSObject().apply {
+            put(
+                "providers",
+                JSArray().apply {
+                    snapshots.forEach { snapshot ->
+                        put(
+                            JSObject().apply {
+                                put("providerId", snapshot.providerId)
+                                put("descriptor", encodeProviderDescriptor(snapshot.descriptor))
+                                put("capabilities", encodeProviderDynamicCapabilities(snapshot.capabilities))
+                            }
+                        )
+                    }
+                }
+            )
+        }
+    }
+
+    private fun encodeProviderDescriptor(descriptor: ProviderDescriptor): JSObject {
+        return JSObject().apply {
+            put("id", descriptor.id)
+            put("type", descriptor.type.name)
+            put("transport", descriptor.transport.name)
+            descriptor.streamingStyle?.let { put("streamingStyle", it.name) }
+            put(
+                "supports",
+                JSObject().apply {
+                    put("run", descriptor.supports.run)
+                    put("streaming", descriptor.supports.streaming)
+                    put("realtime", descriptor.supports.realtime)
+                    put("tools", descriptor.supports.tools)
+                    put("reasoningEvents", descriptor.supports.reasoningEvents)
+                    put("structuredOutput", descriptor.supports.structuredOutput)
+                    put("multimodal", descriptor.supports.multimodal)
+                }
+            )
+            put("cancel", descriptor.cancel.name)
+            put("tasks", JSArray().apply { descriptor.tasks.forEach { put(it) } })
+            descriptor.limits?.let { limits ->
+                put(
+                    "limits",
+                    JSObject().apply {
+                        limits.maxInputTokens?.let { put("maxInputTokens", it) }
+                        limits.maxOutputTokens?.let { put("maxOutputTokens", it) }
+                        limits.maxImageBytes?.let { put("maxImageBytes", it) }
+                        limits.maxAudioSeconds?.let { put("maxAudioSeconds", it) }
+                    }
+                )
+            }
+            descriptor.privacy?.let { privacy ->
+                put(
+                    "privacy",
+                    JSObject().apply {
+                        put("dataLeavesDevice", privacy.dataLeavesDevice)
+                        privacy.regions?.let { regions ->
+                            put("regions", JSArray().apply { regions.forEach { put(it) } })
+                        }
+                    }
+                )
+            }
+        }
+    }
+
+    /**
+     * The three nullable flags are **omitted** rather than written as null. Absence is the
+     * contract's "inherit the static declaration" state — `descriptor.supports.streaming`
+     * for streaming, `descriptor.cancel != none` for cancellation — and a null would be a
+     * third state no consumer has.
+     */
+    private fun encodeProviderDynamicCapabilities(capabilities: ProviderDynamicCapabilities): JSObject {
+        return JSObject().apply {
+            put("available", capabilities.available)
+            capabilities.reason?.let { put("reason", it) }
+            capabilities.streamingAvailable?.let { put("streamingAvailable", it) }
+            capabilities.streamingUnavailableReason?.let { put("streamingUnavailableReason", it) }
+            capabilities.cancellationAvailable?.let { put("cancellationAvailable", it) }
+        }
+    }
+
+    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()
+        }
+    }
+}

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

@@ -0,0 +1,253 @@
+package app.independo.inderun.capacitor
+
+import app.independo.inderun.core.ProviderCapabilitySnapshot
+import app.independo.inderun.core.ProviderDescriptor
+import app.independo.inderun.core.ProviderDynamicCapabilities
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class IndeRunSerializerCapabilitiesTest {
+
+    private fun snapshot(
+        providerId: String,
+        type: ProviderDescriptor.ProviderType,
+        transport: ProviderDescriptor.TransportType,
+        streamingStyle: ProviderDescriptor.StreamingStyle? = null,
+        streaming: Boolean,
+        cancel: ProviderDescriptor.CancelSemantics,
+        limits: ProviderDescriptor.ResourceLimits? = null,
+        privacy: ProviderDescriptor.PrivacyDescriptor? = null,
+        capabilities: ProviderDynamicCapabilities
+    ): ProviderCapabilitySnapshot = ProviderCapabilitySnapshot(
+        providerId = providerId,
+        descriptor = ProviderDescriptor(
+            id = providerId,
+            type = type,
+            transport = transport,
+            streamingStyle = streamingStyle,
+            supports = ProviderDescriptor.SupportsCapabilities(
+                run = true,
+                streaming = streaming,
+                realtime = false,
+                tools = false,
+                reasoningEvents = false,
+                structuredOutput = false,
+                multimodal = false
+            ),
+            cancel = cancel,
+            tasks = listOf("text_to_text"),
+            limits = limits,
+            privacy = privacy
+        ),
+        capabilities = capabilities
+    )
+
+    @Test
+    fun `encodeCapabilitySnapshots wraps the snapshots in a providers array`() {
+        val encoded = IndeRunSerializer.encodeCapabilitySnapshots(
+            listOf(
+                snapshot(
+                    providerId = "openai",
+                    type = ProviderDescriptor.ProviderType.cloud,
+                    transport = ProviderDescriptor.TransportType.http,
+                    streamingStyle = ProviderDescriptor.StreamingStyle.tokens,
+                    streaming = true,
+                    cancel = ProviderDescriptor.CancelSemantics.hard,
+                    limits = ProviderDescriptor.ResourceLimits(
+                        maxInputTokens = 128_000,
+                        maxOutputTokens = 4_096
+                    ),
+                    privacy = ProviderDescriptor.PrivacyDescriptor(
+                        dataLeavesDevice = true,
+                        regions = listOf("us")
+                    ),
+                    capabilities = ProviderDynamicCapabilities(available = true)
+                )
+            )
+        )
+
+        val providers = encoded.getJSONArray("providers")
+        assertEquals(1, providers.length())
+
+        val provider = providers.getJSONObject(0)
+        assertEquals("openai", provider.getString("providerId"))
+
+        val descriptor = provider.getJSONObject("descriptor")
+        assertEquals("openai", descriptor.getString("id"))
+        assertEquals("cloud", descriptor.getString("type"))
+        assertEquals("http", descriptor.getString("transport"))
+        assertEquals("tokens", descriptor.getString("streamingStyle"))
+        assertEquals("hard", descriptor.getString("cancel"))
+        assertEquals(1, descriptor.getJSONArray("tasks").length())
+        assertEquals("text_to_text", descriptor.getJSONArray("tasks").getString(0))
+
+        val supports = descriptor.getJSONObject("supports")
+        assertTrue(supports.getBoolean("run"))
+        assertTrue(supports.getBoolean("streaming"))
+        assertFalse(supports.getBoolean("realtime"))
+        assertFalse(supports.getBoolean("tools"))
+        assertFalse(supports.getBoolean("reasoningEvents"))
+        assertFalse(supports.getBoolean("structuredOutput"))
+        assertFalse(supports.getBoolean("multimodal"))
+
+        val limits = descriptor.getJSONObject("limits")
+        assertEquals(128_000, limits.getInt("maxInputTokens"))
+        assertEquals(4_096, limits.getInt("maxOutputTokens"))
+        assertFalse(limits.has("maxImageBytes"))
+        assertFalse(limits.has("maxAudioSeconds"))
+
+        val privacy = descriptor.getJSONObject("privacy")
+        assertTrue(privacy.getBoolean("dataLeavesDevice"))
+        assertEquals("us", privacy.getJSONArray("regions").getString(0))
+
+        assertTrue(provider.getJSONObject("capabilities").getBoolean("available"))
+    }
+
+    /**
+     * `in_process` and `system_service` are the two descriptor constants a future upstream
+     * rename to camelCase would silently corrupt on the wire, because the TypeScript union
+     * in src/definitions.ts spells them out. Asserting the literals is the guard.
+     */
+    @Test
+    fun `encodeCapabilitySnapshots writes snake case transport constants verbatim`() {
+        val encoded = IndeRunSerializer.encodeCapabilitySnapshots(
+            listOf(
+                snapshot(
+                    providerId = "local.onnx.genai.android",
+                    type = ProviderDescriptor.ProviderType.local,
+                    transport = ProviderDescriptor.TransportType.in_process,
+                    streaming = false,
+                    cancel = ProviderDescriptor.CancelSemantics.soft,
+                    capabilities = ProviderDynamicCapabilities(
+                        available = false,
+                        reason = "No model package configured."
+                    )
+                ),
+                snapshot(
+                    providerId = "android.mlkit.genai",
+                    type = ProviderDescriptor.ProviderType.local,
+                    transport = ProviderDescriptor.TransportType.system_service,
+                    streamingStyle = ProviderDescriptor.StreamingStyle.chunks,
+                    streaming = true,
+                    cancel = ProviderDescriptor.CancelSemantics.soft,
+                    capabilities = ProviderDynamicCapabilities(available = true)
+                )
+            )
+        )
+
+        val providers = encoded.getJSONArray("providers")
+        assertEquals(
+            "in_process",
+            providers.getJSONObject(0).getJSONObject("descriptor").getString("transport")
+        )
+        assertEquals(
+            "system_service",
+            providers.getJSONObject(1).getJSONObject("descriptor").getString("transport")
+        )
+        assertEquals(
+            "chunks",
+            providers.getJSONObject(1).getJSONObject("descriptor").getString("streamingStyle")
+        )
+    }
+
+    /**
+     * Absence is the contract's "inherit the static declaration" state, so the nullable
+     * flags must not reach the wire as nulls — a null would be a third state no consumer
+     * has. Same for the optional descriptor sub-objects.
+     */
+    @Test
+    fun `encodeCapabilitySnapshots omits unset optional fields instead of writing null`() {
+        val encoded = IndeRunSerializer.encodeCapabilitySnapshots(
+            listOf(
+                snapshot(
+                    providerId = "android.mlkit.genai",
+                    type = ProviderDescriptor.ProviderType.local,
+                    transport = ProviderDescriptor.TransportType.system_service,
+                    streaming = true,
+                    cancel = ProviderDescriptor.CancelSemantics.soft,
+                    capabilities = ProviderDynamicCapabilities(available = true)
+                )
+            )
+        )
+
+        val provider = encoded.getJSONArray("providers").getJSONObject(0)
+        val descriptor = provider.getJSONObject("descriptor")
+        assertFalse(descriptor.has("streamingStyle"))
+        assertFalse(descriptor.has("limits"))
+        assertFalse(descriptor.has("privacy"))
+
+        val capabilities = provider.getJSONObject("capabilities")
+        assertFalse(capabilities.has("reason"))
+        assertFalse(capabilities.has("streamingAvailable"))
+        assertFalse(capabilities.has("streamingUnavailableReason"))
+        assertFalse(capabilities.has("cancellationAvailable"))
+    }
+
+    @Test
+    fun `encodeCapabilitySnapshots encodes streaming taken away at runtime`() {
+        val encoded = IndeRunSerializer.encodeCapabilitySnapshots(
+            listOf(
+                snapshot(
+                    providerId = "openai",
+                    type = ProviderDescriptor.ProviderType.cloud,
+                    transport = ProviderDescriptor.TransportType.http,
+                    streamingStyle = ProviderDescriptor.StreamingStyle.tokens,
+                    streaming = true,
+                    cancel = ProviderDescriptor.CancelSemantics.hard,
+                    capabilities = ProviderDynamicCapabilities(
+                        available = true,
+                        streamingAvailable = false,
+                        streamingUnavailableReason = "Host has no streaming HTTP client.",
+                        cancellationAvailable = true
+                    )
+                )
+            )
+        )
+
+        val capabilities = encoded.getJSONArray("providers")
+            .getJSONObject(0)
+            .getJSONObject("capabilities")
+        assertTrue(capabilities.getBoolean("available"))
+        assertFalse(capabilities.getBoolean("streamingAvailable"))
+        assertEquals(
+            "Host has no streaming HTTP client.",
+            capabilities.getString("streamingUnavailableReason")
+        )
+        assertTrue(capabilities.getBoolean("cancellationAvailable"))
+    }
+
+    @Test
+    fun `encodeCapabilitySnapshots encodes an empty registry as an empty array`() {
+        val encoded = IndeRunSerializer.encodeCapabilitySnapshots(emptyList())
+
+        assertTrue(encoded.has("providers"))
+        assertEquals(0, encoded.getJSONArray("providers").length())
+    }
+
+    /**
+     * Every enum constant of every descriptor enum maps to the wire spelling the
+     * TypeScript unions declare. Exhaustive by construction: `values()` grows when
+     * upstream adds a constant, and a renamed one fails here rather than in a demo.
+     */
+    @Test
+    fun `every descriptor enum constant maps to its declared wire value`() {
+        assertEquals(
+            listOf("local", "edge", "cloud"),
+            ProviderDescriptor.ProviderType.values().map { it.name }
+        )
+        assertEquals(
+            listOf("in_process", "system_service", "http", "sse", "realtime"),
+            ProviderDescriptor.TransportType.values().map { it.name }
+        )
+        assertEquals(
+            listOf("tokens", "chunks", "snapshots"),
+            ProviderDescriptor.StreamingStyle.values().map { it.name }
+        )
+        assertEquals(
+            listOf("hard", "soft", "none"),
+            ProviderDescriptor.CancelSemantics.values().map { it.name }
+        )
+    }
+}