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

package/dist/streaming.js

@@ -0,0 +1,303 @@
+import { validateStreamRunHandle } from "@independo/inderun-contracts";
+import { createBridgeError, normalizePluginError } from "./errors.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 const STREAM_EVENT_NAME = "indeRunStreamEvent";
+export const STREAM_ERROR_NAME = "indeRunStreamError";
+/**
+ * How long to wait, after the terminal event has arrived, for a still-missing
+ * earlier event before declaring the run's event sequence irrecoverable.
+ *
+ * Deliberately a module constant rather than a public option: any value here is a
+ * behavioural policy, and behaviour belongs in the engines, not in the bridge.
+ */
+const REORDER_GRACE_MS = 250;
+function createStreamId() {
+    const globalCrypto = globalThis.crypto;
+    if (typeof globalCrypto?.randomUUID === "function") {
+        return globalCrypto.randomUUID();
+    }
+    return `stream_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 11)}`;
+}
+/**
+ * Reassembles one run's canonical event sequence on the JS side of the bridge.
+ *
+ * The bridge hop is not order-preserving, which is why `StreamEvent.sequence` is
+ * the contract's ordering authority rather than arrival order. This sink buffers
+ * out-of-order arrivals and yields strictly by `sequence`, so a consumer sees
+ * exactly what the engine's Event Gate admitted, in the order it admitted it.
+ *
+ * It owns no run semantics: it never synthesizes a terminal event, never retries,
+ * never decides an outcome. A gap that never closes becomes a transport error, not
+ * an invented ending. Everything about *what* a run does stays in the engines.
+ */
+class StreamSink {
+    nextSequence = 0;
+    pending = new Map();
+    ready = [];
+    terminalSequence = null;
+    runId = null;
+    failure = null;
+    done = false;
+    wake = null;
+    graceTimer = null;
+    bindRunId(runId) {
+        this.runId = runId;
+    }
+    /**
+     * True once the run has ended — the terminal event has been admitted, or the
+     * transport has failed — regardless of whether the consumer has drained it yet.
+     */
+    isFinished() {
+        return this.done || this.failure !== null;
+    }
+    accept(event) {
+        if (this.isFinished()) {
+            return;
+        }
+        // Defence in depth on top of streamId routing: an event for another run is
+        // never this run's business.
+        if (this.runId !== null && event.runId !== this.runId) {
+            return;
+        }
+        // Already delivered (a duplicate), or arriving after the terminal that closed
+        // the run. The Event Gate guarantees the terminal is the highest sequence.
+        if (event.sequence < this.nextSequence) {
+            return;
+        }
+        if (this.terminalSequence !== null && event.sequence > this.terminalSequence) {
+            return;
+        }
+        this.pending.set(event.sequence, event);
+        if (event.type === "terminal") {
+            this.terminalSequence = event.sequence;
+        }
+        this.drain();
+    }
+    fail(error) {
+        if (this.isFinished()) {
+            return;
+        }
+        this.clearGrace();
+        this.failure = error;
+        this.signal();
+    }
+    async *iterate() {
+        for (;;) {
+            while (this.ready.length > 0) {
+                yield this.ready.shift();
+            }
+            if (this.failure !== null) {
+                throw this.failure;
+            }
+            if (this.done) {
+                return;
+            }
+            await new Promise((resolve) => {
+                this.wake = resolve;
+            });
+        }
+    }
+    dispose() {
+        this.clearGrace();
+    }
+    drain() {
+        let moved = false;
+        for (;;) {
+            const next = this.pending.get(this.nextSequence);
+            if (next === undefined) {
+                break;
+            }
+            this.pending.delete(this.nextSequence);
+            this.ready.push(next);
+            this.nextSequence += 1;
+            moved = true;
+        }
+        if (this.terminalSequence !== null) {
+            if (this.nextSequence > this.terminalSequence) {
+                // The whole 0..terminal range has been handed over, in order.
+                this.clearGrace();
+                this.done = true;
+            }
+            else {
+                this.startGrace();
+            }
+        }
+        if (moved || this.done) {
+            this.signal();
+        }
+    }
+    startGrace() {
+        if (this.graceTimer !== null) {
+            return;
+        }
+        this.graceTimer = setTimeout(() => {
+            this.graceTimer = null;
+            this.onGraceExpired();
+        }, REORDER_GRACE_MS);
+    }
+    clearGrace() {
+        if (this.graceTimer !== null) {
+            clearTimeout(this.graceTimer);
+            this.graceTimer = null;
+        }
+    }
+    /**
+     * The terminal arrived but an earlier event never did.
+     *
+     * Hand over the content that did arrive, in order, then fail. The terminal itself
+     * is deliberately withheld: delivering it would assert an ending — a `finalText`,
+     * a clean `completed` — that the consumer's own event sequence does not support.
+     * A transport that lost events reports that, rather than papering over it.
+     */
+    onGraceExpired() {
+        if (this.isFinished()) {
+            return;
+        }
+        const terminalSequence = this.terminalSequence;
+        let lost = 0;
+        for (let sequence = this.nextSequence; sequence <= terminalSequence; sequence += 1) {
+            if (!this.pending.has(sequence)) {
+                lost += 1;
+            }
+        }
+        for (const [sequence, event] of [...this.pending.entries()].sort(([a], [b]) => a - b)) {
+            if (sequence !== terminalSequence) {
+                this.ready.push(event);
+            }
+        }
+        this.pending.clear();
+        this.failure = createBridgeError(`Capacitor bridge lost ${lost} stream event(s) for run ${this.runId ?? "<unknown>"}.`, this.runId ?? undefined);
+        this.signal();
+    }
+    signal() {
+        const wake = this.wake;
+        this.wake = null;
+        wake?.();
+    }
+}
+/**
+ * Owns the two plugin listeners and fans notifications out to the sink for each
+ * live run.
+ *
+ * One registration serves every concurrent run: listeners are attached on the
+ * first bind and removed once the last run releases, so a consumer that streams
+ * repeatedly does not accumulate listeners.
+ */
+class StreamDispatcher {
+    sinks = new Map();
+    handles = null;
+    registering = null;
+    async bind(plugin, streamId, sink) {
+        this.sinks.set(streamId, sink);
+        try {
+            await this.ensureListeners(plugin);
+        }
+        catch (error) {
+            this.sinks.delete(streamId);
+            throw error;
+        }
+    }
+    release(streamId) {
+        const sink = this.sinks.get(streamId);
+        if (sink === undefined) {
+            return;
+        }
+        sink.dispose();
+        this.sinks.delete(streamId);
+        if (this.sinks.size === 0) {
+            void this.removeListeners();
+        }
+    }
+    ensureListeners(plugin) {
+        this.registering ??= (async () => {
+            const [events, errors] = await Promise.all([
+                plugin.addListener(STREAM_EVENT_NAME, this.handleEvent),
+                plugin.addListener(STREAM_ERROR_NAME, this.handleError)
+            ]);
+            this.handles = [events, errors];
+        })().catch((error) => {
+            this.registering = null;
+            throw error;
+        });
+        return this.registering;
+    }
+    async removeListeners() {
+        const handles = this.handles;
+        this.handles = null;
+        this.registering = null;
+        if (handles === null) {
+            return;
+        }
+        await Promise.all(handles.map((handle) => handle.remove()));
+    }
+    // Arrow properties: they are handed to addListener and must keep their binding.
+    handleEvent = (notification) => {
+        // An unknown streamId is a retained notification replayed for a run that has
+        // already finished. Dropping it is correct, not an error.
+        this.sinks.get(notification.streamId)?.accept(notification.event);
+    };
+    handleError = (notification) => {
+        this.sinks.get(notification.streamId)?.fail(notification.error);
+    };
+}
+const dispatcher = new StreamDispatcher();
+/**
+ * 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 async function startCapacitorStream(plugin, request) {
+    const streamId = createStreamId();
+    const sink = new StreamSink();
+    await dispatcher.bind(plugin, streamId, sink);
+    let handle;
+    try {
+        handle = await plugin.startStream({ streamId, request });
+    }
+    catch (error) {
+        dispatcher.release(streamId);
+        throw normalizePluginError(error);
+    }
+    if (!validateStreamRunHandle(handle)) {
+        dispatcher.release(streamId);
+        throw createBridgeError("Capacitor bridge received a malformed StreamRunHandle from the native plugin.");
+    }
+    sink.bindRunId(handle.runId);
+    let cancelled = false;
+    const requestCancel = (reason) => {
+        // Cancelling a run that has already ended is a no-op by contract, and is
+        // answered locally so the bridge is not crossed for nothing.
+        if (cancelled || sink.isFinished()) {
+            return;
+        }
+        cancelled = true;
+        void plugin
+            .cancelStream({ streamId, ...(reason !== undefined ? { reason } : {}) })
+            .catch((error) => sink.fail(normalizePluginError(error)));
+    };
+    const generator = (async function* consume() {
+        try {
+            yield* sink.iterate();
+        }
+        finally {
+            // Covers the consumer abandoning the loop with `break`: tell native to stop
+            // producing, and let go of the listeners.
+            requestCancel();
+            dispatcher.release(streamId);
+        }
+    })();
+    return {
+        handle,
+        events: {
+            // Single-use, matching the engines: the run is driven once, not restarted per
+            // consumer, so a second iteration observes completion rather than a replay.
+            [Symbol.asyncIterator]: () => generator
+        },
+        cancel: requestCancel
+    };
+}

package/dist/web.d.ts

@@ -1,10 +1,25 @@
-import type { TaskResult } from "@independo/inderun-contracts";
+import type { StreamRunHandle, TaskResult } from "@independo/inderun-contracts";
 import { WebPlugin } from "@capacitor/core";
-import type { ConfigureOptions, IndeRunCapacitorPlugin } from "./definitions.js";
+import type { CancelStreamOptions, ConfigureOptions, IndeRunCapacitorPlugin, StartStreamOptions } from "./definitions.js";
 import type { TaskRequest } from "@independo/inderun-contracts";
 export declare class IndeRunWeb extends WebPlugin implements IndeRunCapacitorPlugin {
     private engine;
+    private readonly activeStreams;
+    private readonly startingStreams;
+    private readonly pendingCancels;
     configure(options?: ConfigureOptions): Promise<void>;
     run(request: TaskRequest): Promise<TaskResult>;
+    /**
+     * The web path deliberately round-trips through `notifyListeners` rather than
+     * handing the engine's `StreamRun` straight back.
+     *
+     * Short-circuiting would require the facade to branch on the platform and would
+     * leave two reassembly paths whose equivalence is only a convention — while this
+     * way there is exactly one, exercised on every platform. It also equalizes the
+     * loss of generator backpressure that the native paths have regardless.
+     */
+    startStream(options: StartStreamOptions): Promise<StreamRunHandle>;
+    cancelStream(options: CancelStreamOptions): Promise<void>;
+    private pump;
 }
 //# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAGhE,qBAAa,UAAW,SAAQ,SAAU,YAAW,sBAAsB;IACzE,OAAO,CAAC,MAAM,CAAwB;IAEhC,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BzD;IAEK,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAYnD;CACF"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAEnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAIhE,qBAAa,UAAW,SAAQ,SAAU,YAAW,sBAAsB;IACzE,OAAO,CAAC,MAAM,CAAwB;IAItC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgC;IAC9D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyC;IAElE,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BzD;IAEK,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAYnD;IAED;;;;;;;;OAQG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CA8BvE;IAEK,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB9D;YAEa,IAAI;CAenB"}

package/dist/web.js

@@ -1,7 +1,14 @@
 import { WebPlugin } from "@capacitor/core";
 import { createIndeRunWeb, createUnavailable, toIndeRunException } from "@independo/inderun-web";
+import { STREAM_ERROR_NAME, STREAM_EVENT_NAME } from "./streaming.js";
 export class IndeRunWeb extends WebPlugin {
     engine = null;
+    // Deliberately the bridge's StreamRun, not the web SDK's: the engine's run is
+    // assigned straight into this map, so the two shapes staying identical is checked
+    // by the compiler rather than by convention.
+    activeStreams = new Map();
+    startingStreams = new Set();
+    pendingCancels = new Map();
     async configure(options) {
         if (!options?.openAI) {
             throw createUnavailable("Capacitor web execution requires OpenAI provider registration. Configure with openAI bootstrap options before calling run(request).").toContractError();
@@ -30,6 +37,69 @@ export class IndeRunWeb extends WebPlugin {
             throw toIndeRunException(error).toContractError();
         }
     }
+    /**
+     * The web path deliberately round-trips through `notifyListeners` rather than
+     * handing the engine's `StreamRun` straight back.
+     *
+     * Short-circuiting would require the facade to branch on the platform and would
+     * leave two reassembly paths whose equivalence is only a convention — while this
+     * way there is exactly one, exercised on every platform. It also equalizes the
+     * loss of generator backpressure that the native paths have regardless.
+     */
+    async startStream(options) {
+        if (!this.engine) {
+            throw createUnavailable("Capacitor IndeRun has not been configured. Configure providers before calling stream(request).").toContractError();
+        }
+        this.startingStreams.add(options.streamId);
+        let run;
+        try {
+            run = await this.engine.stream(options.request);
+        }
+        catch (error) {
+            this.startingStreams.delete(options.streamId);
+            this.pendingCancels.delete(options.streamId);
+            throw toIndeRunException(error).toContractError();
+        }
+        this.startingStreams.delete(options.streamId);
+        this.activeStreams.set(options.streamId, run);
+        if (this.pendingCancels.has(options.streamId)) {
+            const reason = this.pendingCancels.get(options.streamId);
+            this.pendingCancels.delete(options.streamId);
+            run.cancel(reason);
+        }
+        // Pump on a later microtask so this call's handle settles first.
+        queueMicrotask(() => void this.pump(options.streamId, run));
+        return run.handle;
+    }
+    async cancelStream(options) {
+        const run = this.activeStreams.get(options.streamId);
+        if (run !== undefined) {
+            // Never abandon the generator: the engine must stay free to emit its one
+            // `cancelled` terminal event.
+            run.cancel(options.reason);
+            return;
+        }
+        if (this.startingStreams.has(options.streamId)) {
+            // Cancel raced startStream's route selection; applied once the run attaches.
+            this.pendingCancels.set(options.streamId, options.reason);
+            return;
+        }
+        // Unknown or already-finished run: cancelling after the terminal is a no-op,
+        // not an error.
+    }
+    async pump(streamId, run) {
+        try {
+            for await (const event of run.events) {
+                this.notifyListeners(STREAM_EVENT_NAME, { streamId, event }, true);
+            }
+        }
+        catch (error) {
+            this.notifyListeners(STREAM_ERROR_NAME, { streamId, error: toIndeRunException(error).toContractError() }, true);
+        }
+        finally {
+            this.activeStreams.delete(streamId);
+        }
+    }
 }
 function compactOpenAIOptions(options) {
     const openAI = options.openAI;

package/ios/Sources/IndeRunCapacitorPlugin/IndeRunCapacitorBridge.swift

@@ -16,6 +16,19 @@ struct OpenAIProviderBootstrapOptions: Codable {
     let auth: String?
     let authContextRef: String?
     let timeoutMs: Int?
+
+    // The property keeps Swift's `URL` capitalisation to match OpenAIProviderOptions,
+    // but the wire key is whatever `ConfigureOptions` in src/definitions.ts sends --
+    // `endpointUrl`, which is also what IndeRunSerializer.kt reads on Android. Without
+    // this mapping the field silently decodes as nil and the provider falls back to the
+    // default endpoint.
+    enum CodingKeys: String, CodingKey {
+        case model
+        case endpointURL = "endpointUrl"
+        case auth
+        case authContextRef
+        case timeoutMs
+    }
 }
 
 struct CapacitorRunOptions: Codable {
@@ -23,9 +36,33 @@ struct CapacitorRunOptions: Codable {
     let allowDirectOpenAIEndpoint: Bool? // web-only, no-op on native
 }
 
+/// 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`. See `StartStreamOptions` in src/definitions.ts.
+struct CapacitorStartStreamOptions: Codable {
+    let streamId: String
+    let request: TaskRequest
+}
+
+struct CapacitorCancelStreamOptions: Codable {
+    let streamId: String
+    let reason: String?
+}
+
+/// Called with an already-encoded event/error for one run. The plugin turns these
+/// into `notifyListeners` calls; taking them as closures keeps the pump testable
+/// without Capacitor.
+typealias StreamEventSink = @Sendable (String, JSObject) -> Void
+typealias StreamErrorSink = @Sendable (String, JSObject) -> Void
+
 final class IndeRunCapacitorBridge {
     private var configuredRegistry: ProviderRegistry?
     private var configuredHostServices: HostServices?
+    let streams = StreamRegistry()
+
+    deinit {
+        streams.cancelAll(reason: "Capacitor bridge deallocated.")
+    }
 
     func configure(options: JSObject) throws {
         let runOptions = try decodeConfigureOptions(from: options)
@@ -45,10 +82,97 @@ final class IndeRunCapacitorBridge {
         return try encode(result)
     }
 
+    func startStream(
+        options: JSObject,
+        onEvent: @escaping StreamEventSink,
+        onError: @escaping StreamErrorSink
+    ) async throws -> JSObject {
+        guard let registry = configuredRegistry, let hostServices = configuredHostServices else {
+            throw createUnavailable(message: "Capacitor IndeRun has not been configured. Configure providers before calling stream(request).")
+        }
+
+        let start = try decodeStartStreamOptions(from: options)
+        // 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: start.streamId)
+
+        let run: StreamRun
+        do {
+            // IndeRun is a stateless coordinator; new per call is intentional — registry is cached above.
+            let engine = IndeRun(registry: registry, hostServices: hostServices)
+            run = try await engine.stream(request: start.request)
+        } catch {
+            streams.finish(streamId: start.streamId)
+            throw error
+        }
+
+        if case .cancelRequested(let reason) = streams.attach(streamId: start.streamId, run: run) {
+            run.cancel(reason: reason)
+        }
+
+        let streamId = start.streamId
+        // Weak, so a live run cannot keep the bridge alive past the plugin's deinit;
+        // the plugin's teardown cancels these tasks, which then release the bridge.
+        let task = Task { [weak self] in
+            guard let self else { return }
+            await self.pump(streamId: streamId, run: run, onEvent: onEvent, onError: onError)
+        }
+        streams.store(task: task, for: streamId)
+
+        return try encode(handle: run.handle)
+    }
+
+    func cancelStream(options: JSObject) throws {
+        let cancel = try decodeCancelStreamOptions(from: options)
+        streams.requestCancel(streamId: cancel.streamId, reason: cancel.reason)
+    }
+
+    func teardownStreams() {
+        streams.cancelAll(reason: "Capacitor plugin torn down.")
+    }
+
+    /// Forwards one run's canonical events to the sink until the stream ends.
+    ///
+    /// A provider failure has already become a terminal `error` event by the time it
+    /// reaches here — the engine's Event Gate owns that. Anything thrown out of the
+    /// sequence is a failure of this bridge, and is reported as one.
+    func pump(
+        streamId: String,
+        run: StreamRun,
+        onEvent: @escaping StreamEventSink,
+        onError: @escaping StreamErrorSink
+    ) async {
+        do {
+            for try await event in run.events {
+                onEvent(streamId, try encode(streamEvent: event))
+            }
+        } catch is CancellationError {
+            // Our own task cancellation, from teardown. The webview is going away and
+            // no one is left to receive a terminal event; not a bridge fault.
+        } catch {
+            let contractError = toIndeRunException(error).toContractError()
+            if let encoded = try? encode(error: contractError) {
+                onError(streamId, encoded)
+            }
+        }
+        streams.finish(streamId: streamId)
+    }
+
     func encode(error: IndeRunError) throws -> JSObject {
         try encodeObject(error)
     }
 
+    // JSONEncoder omits nil optionals, so "emit only the fields this event actually
+    // has" — which is what reconstitutes the right union branch on the JS side —
+    // comes for free from the generated Codable conformances.
+    func encode(streamEvent: StreamEvent) throws -> JSObject {
+        try encodeObject(streamEvent)
+    }
+
+    func encode(handle: StreamRunHandle) throws -> JSObject {
+        try encodeObject(handle)
+    }
+
     private func makeRegistry(openAI: OpenAIProviderBootstrapOptions?) throws -> ProviderRegistry {
         let registry = ProviderRegistry()
         try registry.register(AppleFoundationModelsProvider())
@@ -76,6 +200,16 @@ final class IndeRunCapacitorBridge {
         return try JSONDecoder().decode(CapacitorRunOptions.self, from: data)
     }
 
+    private func decodeStartStreamOptions(from object: JSObject) throws -> CapacitorStartStreamOptions {
+        let data = try JSONSerialization.data(withJSONObject: object, options: [])
+        return try JSONDecoder().decode(CapacitorStartStreamOptions.self, from: data)
+    }
+
+    private func decodeCancelStreamOptions(from object: JSObject) throws -> CapacitorCancelStreamOptions {
+        let data = try JSONSerialization.data(withJSONObject: object, options: [])
+        return try JSONDecoder().decode(CapacitorCancelStreamOptions.self, from: data)
+    }
+
     private func decodeRequest(from object: JSObject) throws -> TaskRequest {
         let data = try JSONSerialization.data(withJSONObject: object, options: [])
         return try JSONDecoder().decode(TaskRequest.self, from: data)

package/ios/Sources/IndeRunCapacitorPlugin/IndeRunCapacitorPlugin.swift

@@ -9,11 +9,20 @@ public final class IndeRunCapacitorPlugin: CAPPlugin, CAPBridgedPlugin {
     public let jsName = "IndeRunCapacitor"
     public let pluginMethods: [CAPPluginMethod] = [
         CAPPluginMethod(name: "configure", returnType: CAPPluginReturnPromise),
-        CAPPluginMethod(name: "run", returnType: CAPPluginReturnPromise)
+        CAPPluginMethod(name: "run", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "startStream", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "cancelStream", returnType: CAPPluginReturnPromise)
     ]
 
     private let implementation = IndeRunCapacitorBridge()
 
+    /// CAPPlugin has no teardown hook — `load()` has no counterpart — so deinit is
+    /// the only place left to stop runs the webview can no longer receive. The pump
+    /// tasks hold `self` weakly precisely so this can run.
+    deinit {
+        implementation.teardownStreams()
+    }
+
     @objc func configure(_ call: CAPPluginCall) {
         do {
             try implementation.configure(options: call.options)
@@ -47,5 +56,65 @@ public final class IndeRunCapacitorPlugin: CAPPlugin, CAPBridgedPlugin {
             }
         }
     }
+
+    /// Resolves with the run handle. Only validation and route-selection failures
+    /// reject here; a provider failure, a cancellation, or completion all arrive as
+    /// the single terminal event on `indeRunStreamEvent`.
+    ///
+    /// `retainUntilConsumed` closes the listener-registration race from the native
+    /// side: an event emitted before the JS listener is attached is retained and
+    /// replayed rather than lost.
+    @objc func startStream(_ call: CAPPluginCall) {
+        Task { [weak self] in
+            guard let self else { return }
+            do {
+                let handle = try await self.implementation.startStream(
+                    options: call.options,
+                    onEvent: { [weak self] streamId, event in
+                        self?.notifyListeners(
+                            "indeRunStreamEvent",
+                            data: ["streamId": streamId, "event": event],
+                            retainUntilConsumed: true
+                        )
+                    },
+                    onError: { [weak self] streamId, error in
+                        self?.notifyListeners(
+                            "indeRunStreamError",
+                            data: ["streamId": streamId, "error": error],
+                            retainUntilConsumed: true
+                        )
+                    }
+                )
+                call.resolve(handle)
+            } catch let error as IndeRunException {
+                let contractError = error.toContractError()
+                let details = try? self.implementation.encode(error: contractError)
+                call.reject(contractError.message, contractError.errorClass.rawValue, error, details)
+            } catch {
+                let normalized = toIndeRunException(error)
+                let contractError = normalized.toContractError()
+                let details = try? self.implementation.encode(error: contractError)
+                call.reject(contractError.message, contractError.errorClass.rawValue, normalized, details)
+            }
+        }
+    }
+
+    /// Resolves for an unknown or already-finished run: cancelling after the terminal
+    /// is a no-op by contract, not an error.
+    @objc func cancelStream(_ call: CAPPluginCall) {
+        do {
+            try implementation.cancelStream(options: call.options)
+            call.resolve()
+        } catch let error as IndeRunException {
+            let contractError = error.toContractError()
+            let details = try? implementation.encode(error: contractError)
+            call.reject(contractError.message, contractError.errorClass.rawValue, error, details)
+        } catch {
+            let normalized = toIndeRunException(error)
+            let contractError = normalized.toContractError()
+            let details = try? implementation.encode(error: contractError)
+            call.reject(contractError.message, contractError.errorClass.rawValue, normalized, details)
+        }
+    }
 }
 #endif