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

package/Package.swift

@@ -9,22 +9,35 @@ import PackageDescription
 let package = Package(
     name: "IndeRunCapacitor",
     platforms: [
-        .iOS(.v15),
+        .iOS(.v16),
         .macOS(.v14)
     ],
     products: [
         .library(
             name: "IndeRunCapacitor",
             targets: ["IndeRunCapacitorPlugin"]
+        ),
+        // The Capacitor CLI derives a product name from the npm package name
+        // (`@independo/capacitor-inderun` -> `IndependoCapacitorInderun`) and writes exactly
+        // that into the app's generated CapApp-SPM manifest. Without a product under this
+        // name, `cap add ios` produces a project that cannot resolve its dependencies at all.
+        // Kept alongside the original name rather than replacing it, so anything already
+        // depending on `IndeRunCapacitor` by URL keeps resolving.
+        .library(
+            name: "IndependoCapacitorInderun",
+            targets: ["IndeRunCapacitorPlugin"]
         )
     ],
     dependencies: [
         .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
-        // `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")
+        // Ranged rather than `exact:` so a consumer that also depends on `inderun`
+        // directly can unify the graph. `.upToNextMinor` rather than `from:` because
+        // `from:` on a 0.x means `<1.0.0` — it would let SwiftPM float across a minor
+        // (where an 0.x SDK's breaking changes live) while package.json and
+        // android/build.gradle.kts stay pinned, which is exactly the three-platform
+        // drift the versioning policy forbids. Both operators exclude prereleases:
+        // tracking a `-dev.N` again requires going back to `exact:`.
+        .package(url: "https://github.com/independo-gmbh/inderun.git", .upToNextMinor(from: "0.3.0"))
     ],
     targets: [
         .target(

package/README.md

@@ -14,10 +14,15 @@
 
 <p align="center">Built and maintained by <a href="https://www.independo.app/">Independo</a>.</p>
 
-Thin Capacitor bridge for IndeRun Mode 1 `run()` and Mode 2 `stream()` execution.
+**On-device AI with cloud fallback, for Capacitor apps.**
 
-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:
+Runs a prompt on the device when the device can — Apple Foundation Models on iOS, ML Kit GenAI
+(Gemini Nano) on Android — and falls back to an OpenAI-compatible cloud endpoint when it cannot.
+One API across iOS, Android and the web, with streaming and cancellation. MIT.
+
+It is a thin bridge, not a second engine. 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:
 
 - web: [`@independo/inderun-web`](https://www.npmjs.com/package/@independo/inderun-web) (npm)
 - iOS: `IndeRun` Swift package (`github.com/independo-gmbh/inderun`, SwiftPM)
@@ -38,10 +43,72 @@ Then sync native projects with your normal Capacitor workflow.
 
 | Platform | Minimum version        |
 |----------|------------------------|
-| iOS      | 15.0                   |
+| iOS      | 16.0                   |
 | Android  | API 26 (Android 8.0)   |
 | Web      | Any modern browser     |
 
+The iOS floor comes from the IndeRun Swift package this bridge depends on, not from the bridge
+itself. On-device execution needs more than the floor: Apple Foundation Models requires an Apple
+Intelligence–capable device on iOS 26+, and ML Kit GenAI requires AICore / Gemini Nano support.
+Availability is checked at runtime and the cloud provider serves the request when it is missing.
+
+## Host Project Requirements
+
+The IndeRun SDKs this bridge wraps are newer than a freshly generated Capacitor app's
+defaults, so `cap add` alone is not enough. Each of these is a hard requirement — the
+corresponding build failure is named so it is searchable:
+
+**Android** (`android/variables.gradle` and `android/build.gradle` in your app):
+
+| Setting | Value | Failure if unset |
+|---|---|---|
+| `compileSdkVersion` | `37` | *"requires libraries and applications that depend on it to compile against version 37 or later"* |
+| `minSdkVersion` | `26` | manifest merger conflict |
+| Android Gradle Plugin | `9.1.0`+ (Gradle 9.x) | *"requires Android Gradle plugin 9.1.0 or higher"* |
+| `org.jetbrains.kotlin:kotlin-gradle-plugin:2.4.10` on the app's `buildscript` classpath | — | *"Module was compiled with an incompatible version of Kotlin … metadata is 2.4.0, expected version is 2.2.0"* |
+
+The Kotlin one is the surprising entry: the `inderun-*` artifacts carry Kotlin 2.4.x
+metadata, which the Kotlin plugin AGP brings by default cannot read. The plugin's own build
+hoists a newer KGP for its standalone build, but a consuming app resolves KGP from its own
+buildscript classpath, so the app has to add it too:
+
+```groovy
+// android/build.gradle
+buildscript {
+    dependencies {
+        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.4.10'
+    }
+}
+```
+
+AGP 9 also rejects `getDefaultProguardFile('proguard-android.txt')`; switch to
+`proguard-android-optimize.txt`.
+
+**iOS**: set `IPHONEOS_DEPLOYMENT_TARGET` to `16.0` in your Xcode project **before**
+`npx cap sync ios`. The Capacitor CLI reads that value to generate `CapApp-SPM/Package.swift`,
+so syncing with the default leaves a manifest pinned below this package's floor and the build
+fails with *"requires minimum platform version 16.0 for the iOS platform, but this target
+supports 15.0"*.
+
+## Supported IndeRun Version
+
+This release tracks **IndeRun 0.3.0** on all three platforms:
+
+| Platform | Artifact | Constraint |
+|----------|----------|------------|
+| Web      | `@independo/inderun-web`, `@independo/inderun-contracts` | `0.3.0` (exact) |
+| iOS      | `inderun` SwiftPM package | `>=0.3.0 <0.4.0` |
+| Android  | `app.independo.inderun:inderun-*` | `0.3.0` (exact) |
+
+The npm and Gradle pins are exact and all three are bumped together — a partial bump is how the
+platforms drift apart. The SwiftPM constraint is ranged rather than exact so an app that also depends
+on `inderun` directly can still unify its package graph; it stops at the next minor because that is
+where an 0.x SDK's breaking changes live.
+
+This package versions **independently** of the IndeRun monorepo under plain semver — the numbers are
+unrelated, and this bridge's own version says nothing about which IndeRun release it wraps. Read that
+off the table above.
+
 ## Usage
 
 ```ts
@@ -96,42 +163,78 @@ for await (const event of run.events) {
 run.cancel("user navigated away"); // idempotent; a no-op after the terminal
 ```
 
-Three things worth knowing before you build on it:
+Event semantics, ordering, the terminal guarantees, cancellation and fallback are the engines'
+contract, identical on every platform, and documented once in
+[Streaming (Mode 2)](https://github.com/independo-gmbh/inderun/blob/dev/docs/streaming.md). Two
+things are specific to reaching them through a bridge:
 
-- **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.
+- **The bridge hop is not order-preserving.** That is why `sequence` rather than arrival is the
+  contract's ordering authority. `events` already yields strictly by it; if you attach your own
+  listener to `STREAM_EVENT_NAME` instead, ordering is yours to enforce.
+- **A failed run is not a rejected promise**, and a bridge transport fault is a third thing again.
+  See [Error Handling](#error-handling).
 
 ## API
 
 - `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.
+- `checkCapabilities()` — every registered provider's static declaration and live availability, without executing a task. Resolves with `ProviderCapabilitySnapshot[]`. Use it for a provider or settings screen; availability changes between calls, so do not cache it across a `run()` or `stream()`.
 - 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`.
-
-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.
+The `IndeRunCapacitorPlugin` and `ConfigureOptions` contracts — including the `openAI`,
+`systemModel` and `onnx` bootstrap configs and the `allowDirectOpenAIEndpoint` flag — are
+defined and documented in `src/definitions.ts`.
+
+`systemModel`, `onnx` and `allowDirectOpenAIEndpoint` are **web-only** and ignored on iOS
+and Android, which register their own on-device provider from `configure()` regardless.
+`systemModel` registers the browser-managed on-device provider (Chrome's Prompt API) and is
+what makes `constraints.privacy = "local_required"` routable in a browser. Both on-device
+web providers are Mode 1 only.
+
+`onnx` carries two caveats. It needs the consumer to install the optional
+`@huggingface/transformers` peer dependency — this bridge does not declare it — and to
+supply real model weights, because the web SDK's `runtime` injection seam is a function and
+so cannot cross a JSON bridge hop: only the default Transformers.js runtime is reachable
+through `configure()`, never the fixture runtime the upstream demos use offline. Register it
+only when the weights are there; a provider that cannot load turns a clean routing refusal
+into a provider error.
+
+Two asymmetries in the low-level surface, both hidden by the ergonomic API:
+
+- `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.
+- The plugin method `checkCapabilities()` resolves `{ providers: [...] }` rather than the
+  array itself, because a Capacitor plugin method cannot resolve a top-level array on
+  either native platform. `IndeRunCapacitor.checkCapabilities()` unwraps it, so app code
+  sees the same array the three platform SDKs return.
+
+`ProviderCapabilitySnapshot` and the `ProviderDescriptor` /
+`ProviderDynamicCapabilities` it contains are declared in `src/definitions.ts` rather than
+imported, because — unlike `TaskRequest` or `StreamEvent` — they are not generated
+contracts: each platform SDK declares its own copy and there is no schema or validator for
+them upstream. `src/web.ts` returns the web SDK's snapshots into the bridge's type uncast,
+so the shapes staying identical is a compile error rather than a convention. Note
+`capabilities.streamingAvailable` and `cancellationAvailable` are **absent**, not `null`,
+when the runtime has nothing to add: absence means *inherit the static declaration*.
 
 ## Platform Notes
 
-- Web requires `openAI` registration because the current web SDK only has the OpenAI-compatible provider.
+- Web requires at least one provider to be registered from `configure()`. The web SDK ships an
+  OpenAI-compatible provider, a Web ONNX Runtime provider and a browser system-model provider, but
+  only the OpenAI-compatible one declares streaming support — so a `local_required` **stream** in a
+  browser is refused at routing time, while a `local_required` **run** can be served on-device.
 - iOS always registers the Apple on-device provider and optionally registers OpenAI when configured.
 - Android always registers the ML Kit on-device provider and optionally registers OpenAI when configured.
-- Keep credentials behind `authContextRef`. For browser apps, prefer a proxy endpoint with `auth: "none"`.
+- Keep credentials behind `authContextRef`. That keeps a secret out of the request payload and out
+  of source; it does not make a key safe to ship, since anything an installed app or a browser can
+  read, someone with that app or browser can read. For a key you own, put it behind a backend you
+  control and point `endpointUrl` at that — for browser apps, a same-origin proxy with
+  `auth: "none"`.
 
 ## Current Limitations
 

package/android/build.gradle.kts

@@ -10,7 +10,13 @@ buildscript {
 }
 
 plugins {
-    id("com.android.library") version "9.3.1"
+    // No version here on purpose. When a Capacitor app includes this module, AGP is already
+    // on the app's classpath and a versioned request fails with "the plugin is already on the
+    // classpath with an unknown version, so compatibility cannot be checked" — i.e. the plugin
+    // could not be consumed at all. The version for a standalone build of this directory is
+    // declared in settings.gradle's pluginManagement instead, which a consuming app's own
+    // settings file replaces.
+    id("com.android.library")
 }
 
 android {
@@ -37,11 +43,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.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("app.independo.inderun:inderun-contracts:0.3.0")
+    implementation("app.independo.inderun:inderun-core:0.3.0")
+    implementation("app.independo.inderun:inderun-kotlin:0.3.0")
+    implementation("app.independo.inderun:inderun-mlkit-providers:0.3.0")
+    implementation("app.independo.inderun:inderun-openai-providers:0.3.0")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2")
 
     testImplementation("junit:junit:4.13.2")

package/android/settings.gradle

@@ -4,6 +4,13 @@ pluginManagement {
         mavenCentral()
         gradlePluginPortal()
     }
+
+    // Supplies the version build.gradle.kts deliberately omits, for a standalone build of
+    // this directory (pnpm test:android / verify:android). A Capacitor app that includes the
+    // module uses its own settings file, so AGP comes from the app's classpath there.
+    plugins {
+        id("com.android.library") version "9.3.1"
+    }
 }
 
 dependencyResolutionManagement {

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

@@ -87,6 +87,41 @@ class IndeRunCapacitorPlugin : Plugin() {
         }
     }
 
+    /**
+     * Reports every registered provider's static declaration and live availability without
+     * executing a task. Availability changes between calls — a local model can unload,
+     * cloud credentials can expire — so callers must not cache it across a run.
+     */
+    @PluginMethod
+    fun checkCapabilities(call: PluginCall) {
+        scope.launch {
+            try {
+                val registry = configuredRegistry
+                    ?: throw toIndeRunException(IllegalStateException("Capacitor IndeRun has not been configured. Configure providers before calling checkCapabilities()."))
+                // IndeRun is stateless; new per call is intentional — registry is cached after configure().
+                val snapshots = IndeRun.initialize(context.applicationContext, registry).checkCapabilities()
+                call.resolve(IndeRunSerializer.encodeCapabilitySnapshots(snapshots))
+            } catch (error: IndeRunException) {
+                val contractError = error.toContractError()
+                call.reject(
+                    contractError.message,
+                    contractError.errorClass.rawValue,
+                    null,
+                    runCatching { IndeRunSerializer.encodeError(contractError) }.getOrNull()
+                )
+            } catch (error: Throwable) {
+                val normalized = toIndeRunException(error)
+                val contractError = normalized.toContractError()
+                call.reject(
+                    contractError.message,
+                    contractError.errorClass.rawValue,
+                    null,
+                    runCatching { IndeRunSerializer.encodeError(contractError) }.getOrNull()
+                )
+            }
+        }
+    }
+
     /**
      * 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

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

@@ -28,6 +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.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
@@ -113,6 +116,100 @@ 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)