@independo/inderun-web 0.3.0-dev.1 → 0.3.0-dev.10

package/README.md

@@ -30,10 +30,49 @@ const result = await inderun.run({
 });
 ```
 
+## Streaming
+
+`stream()` returns the run handle, its canonical `StreamEvent` sequence, and a `cancel()` hook:
+
+```ts
+const { handle, events, cancel } = await inderun.stream({
+  schemaVersion: "1.0",
+  task: { kind: "text_to_text" },
+  prompt: "Write a one-sentence summary of IndeRun."
+});
+
+for await (const event of events) {
+  if (event.type === "content_delta") process.stdout.write(event.payload.text);
+  if (event.type === "terminal") console.log(event.payload.outcome);
+}
+```
+
+Order by `event.sequence`, not by arrival: it is the ordering authority for a run. Treat an
+unrecognized `event.type` as ignore-or-pass-through — the set is open and additive. Exactly one
+`terminal` event is produced per run, and `cancel()` is idempotent.
+
+Streaming needs a host that can deliver a response body incrementally.
+`createBrowserHostServices` provides one; a custom host without a
+`streamingHttpClient` still runs Mode 1, and a stream request is refused at routing
+time with a `streaming_unavailable` reason rather than failing later.
+
+### Custom OpenAI-compatible endpoints
+
+The adapter speaks the OpenAI **Responses** API, not chat completions. A custom endpoint must
+accept `"stream": true` and emit `text/event-stream` with the Responses event types —
+`response.output_text.delta`, and `response.completed` / `response.incomplete` carrying the
+response object. Unknown event types are ignored, so an endpoint that emits extra events is
+fine; one that emits a different vocabulary entirely is not.
+
 ## Security Model
 
 Browser apps should use a proxy endpoint and keep provider credentials server-side. `createIndeRunWeb` rejects direct calls to the public OpenAI Responses endpoint unless `allowDirectOpenAIEndpoint: true` is set for a controlled environment.
 
+This applies to streaming too, and is the reason `@independo/inderun-demo-proxy` relays event
+streams rather than buffering them: a browser cannot open its own authenticated connection to
+OpenAI without shipping the key in client code. Never embed a developer-owned API key in
+distributed client code — put it behind a trusted backend proxy and point `endpointUrl` at that.
+
 ## Advanced: registering the OpenAI provider directly
 
 `createIndeRunWeb` wires the OpenAI Responses provider for you. To register it

package/dist/core/browser-host.d.ts

@@ -1,4 +1,4 @@
-import type { ClockService, ConnectivityService, HostServices, HttpClientService, HttpRequest, HttpResponse } from "./host.js";
+import type { ClockService, ConnectivityService, HostServices, HttpClientService, HttpRequest, HttpResponse, HttpStreamResponse, HttpStreamingClientService } from "./host.js";
 /**
  * Configuration for the fetch-backed HTTP host service.
  */
@@ -49,12 +49,39 @@ export declare class FetchHttpClient implements HttpClientService {
      */
     send(request: HttpRequest): Promise<HttpResponse>;
 }
+/**
+ * Streaming HTTP client service that adapts `fetch` to IndeRun's incremental
+ * HTTP contract by handing back `Response.body` rather than buffering it.
+ *
+ * Two abort sources are merged onto one controller: `timeoutMs`, which bounds
+ * only the wait for the response head, and the caller's `signal`, which stays
+ * live for the whole body. The timeout timer is therefore cleared as soon as
+ * the head resolves — a stream that legitimately stays open for minutes must
+ * not be killed by a time-to-first-byte budget.
+ */
+export declare class FetchStreamingHttpClient implements HttpStreamingClientService {
+    private readonly fetchFn;
+    /**
+     * Creates a fetch-backed streaming HTTP client.
+     * @param options - Optional fetch implementation override.
+     * @throws Error when no fetch implementation is available.
+     */
+    constructor(options?: FetchHttpClientOptions);
+    /**
+     * Sends a normalized HTTP request and resolves once the response head is available.
+     * @param request - Normalized HTTP request payload.
+     * @param signal - Optional caller-driven cancellation covering the whole response.
+     * @returns Response head plus a lazily-consumed body chunk sequence.
+     */
+    stream(request: HttpRequest, signal?: AbortSignal): Promise<HttpStreamResponse>;
+}
 /**
  * Options for constructing default browser host services.
  */
 export interface CreateBrowserHostServicesOptions extends Partial<HostServices> {
     /**
-     * Optional fetch implementation used when `httpClient` is not supplied.
+     * Optional fetch implementation used when `httpClient`/`streamingHttpClient`
+     * are not supplied.
      */
     fetchFn?: typeof fetch;
 }

package/dist/core/browser-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-host.d.ts","sourceRoot":"","sources":["../../src/core/browser-host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,YAAY,EACb,MAAM,WAAW,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,0BAA2B,YAAW,mBAAmB;IACpE;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;CAOnC;AAED;;GAEG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD;;OAEG;IACH,GAAG,IAAI,MAAM;IAIb;;OAEG;IACH,YAAY,IAAI,MAAM;CAOvB;AAED;;GAEG;AACH,qBAAa,eAAgB,YAAW,iBAAiB;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC;;;;OAIG;gBACS,OAAO,GAAE,sBAA2B;IAShD;;;;OAIG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CA0CxD;AAED;;GAEG;AACH,MAAM,WAAW,gCAAiC,SAAQ,OAAO,CAAC,YAAY,CAAC;IAC7E;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,gCAAqC,GAC7C,YAAY,CA2Bd"}
+{"version":3,"file":"browser-host.d.ts","sourceRoot":"","sources":["../../src/core/browser-host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,0BAA0B,EAC3B,MAAM,WAAW,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,0BAA2B,YAAW,mBAAmB;IACpE;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;CAOnC;AAED;;GAEG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD;;OAEG;IACH,GAAG,IAAI,MAAM;IAIb;;OAEG;IACH,YAAY,IAAI,MAAM;CAOvB;AAED;;GAEG;AACH,qBAAa,eAAgB,YAAW,iBAAiB;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC;;;;OAIG;gBACS,OAAO,GAAE,sBAA2B;IAShD;;;;OAIG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CA0CxD;AAED;;;;;;;;;GASG;AACH,qBAAa,wBAAyB,YAAW,0BAA0B;IACzE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC;;;;OAIG;gBACS,OAAO,GAAE,sBAA2B;IAShD;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAwHtF;AAED;;GAEG;AACH,MAAM,WAAW,gCAAiC,SAAQ,OAAO,CAAC,YAAY,CAAC;IAC7E;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,gCAAqC,GAC7C,YAAY,CAmCd"}

package/dist/core/browser-host.js

@@ -93,6 +93,154 @@ export class FetchHttpClient {
         }
     }
 }
+/**
+ * Streaming HTTP client service that adapts `fetch` to IndeRun's incremental
+ * HTTP contract by handing back `Response.body` rather than buffering it.
+ *
+ * Two abort sources are merged onto one controller: `timeoutMs`, which bounds
+ * only the wait for the response head, and the caller's `signal`, which stays
+ * live for the whole body. The timeout timer is therefore cleared as soon as
+ * the head resolves — a stream that legitimately stays open for minutes must
+ * not be killed by a time-to-first-byte budget.
+ */
+export class FetchStreamingHttpClient {
+    fetchFn;
+    /**
+     * Creates a fetch-backed streaming HTTP client.
+     * @param options - Optional fetch implementation override.
+     * @throws Error when no fetch implementation is available.
+     */
+    constructor(options = {}) {
+        const fetchFn = options.fetchFn ?? globalThis.fetch?.bind(globalThis);
+        if (!fetchFn) {
+            throw new Error("FetchStreamingHttpClient requires a fetch implementation.");
+        }
+        this.fetchFn = fetchFn;
+    }
+    /**
+     * Sends a normalized HTTP request and resolves once the response head is available.
+     * @param request - Normalized HTTP request payload.
+     * @param signal - Optional caller-driven cancellation covering the whole response.
+     * @returns Response head plus a lazily-consumed body chunk sequence.
+     */
+    async stream(request, signal) {
+        const controller = typeof AbortController === "undefined" ? undefined : new AbortController();
+        let timeoutId;
+        let onAbort;
+        if (controller) {
+            if (request.timeoutMs !== undefined) {
+                timeoutId = setTimeout(() => controller.abort(), request.timeoutMs);
+            }
+            if (signal) {
+                if (signal.aborted) {
+                    controller.abort();
+                }
+                else {
+                    onAbort = () => controller.abort();
+                    signal.addEventListener("abort", onAbort, { once: true });
+                }
+            }
+        }
+        const clearTimeoutTimer = () => {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+                timeoutId = undefined;
+            }
+        };
+        const releaseAbortListener = () => {
+            if (signal && onAbort) {
+                signal.removeEventListener("abort", onAbort);
+                onAbort = undefined;
+            }
+        };
+        let response;
+        try {
+            const init = { method: request.method };
+            if (request.headers) {
+                init.headers = request.headers;
+            }
+            if (request.body !== undefined) {
+                init.body = request.body;
+            }
+            if (controller) {
+                init.signal = controller.signal;
+            }
+            response = await this.fetchFn(request.url, init);
+        }
+        catch (error) {
+            clearTimeoutTimer();
+            releaseAbortListener();
+            throw error;
+        }
+        clearTimeoutTimer();
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            headers[key.toLowerCase()] = value;
+        });
+        const stream = response.body;
+        async function* iterate() {
+            try {
+                if (!stream) {
+                    // A bodyless response (204, HEAD) or a fetch polyfill without stream
+                    // support: fall back to the buffered text so callers still terminate.
+                    const text = await response.text();
+                    if (text.length > 0) {
+                        yield new TextEncoder().encode(text);
+                    }
+                    return;
+                }
+                const reader = stream.getReader();
+                // The body is also raced against `signal` directly, not just against the
+                // fetch-level abort: a fetch implementation is free not to error an
+                // in-flight body when its request signal fires, and the caller's
+                // cancellation guarantee must not depend on that.
+                let onBodyAbort;
+                const aborted = new Promise((_resolve, reject) => {
+                    if (!signal)
+                        return;
+                    onBodyAbort = () => reject(Object.assign(new Error("The stream was aborted."), { name: "AbortError" }));
+                    if (signal.aborted) {
+                        onBodyAbort();
+                    }
+                    else {
+                        signal.addEventListener("abort", onBodyAbort, { once: true });
+                    }
+                });
+                // Keeps an abort that arrives after the body finished from surfacing as
+                // an unhandled rejection; the race below still observes it.
+                void aborted.catch(() => undefined);
+                try {
+                    for (;;) {
+                        const { done, value } = await Promise.race([reader.read(), aborted]);
+                        if (done)
+                            return;
+                        if (value)
+                            yield value;
+                    }
+                }
+                catch (error) {
+                    await reader.cancel().catch(() => undefined);
+                    throw error;
+                }
+                finally {
+                    if (signal && onBodyAbort) {
+                        signal.removeEventListener("abort", onBodyAbort);
+                    }
+                    reader.releaseLock();
+                }
+            }
+            finally {
+                releaseAbortListener();
+            }
+        }
+        return {
+            status: response.status,
+            statusText: response.statusText,
+            headers,
+            body: iterate()
+        };
+    }
+}
 /**
  * Creates a browser-oriented HostServices bundle for the Web SDK.
  * Supplied host services override the defaults; missing connectivity, clock, and HTTP services are created.
@@ -112,6 +260,15 @@ export function createBrowserHostServices(options = {}) {
     else {
         hostServices.httpClient = new FetchHttpClient();
     }
+    if (options.streamingHttpClient) {
+        hostServices.streamingHttpClient = options.streamingHttpClient;
+    }
+    else if (options.fetchFn) {
+        hostServices.streamingHttpClient = new FetchStreamingHttpClient({ fetchFn: options.fetchFn });
+    }
+    else {
+        hostServices.streamingHttpClient = new FetchStreamingHttpClient();
+    }
     if (options.deviceConstraints) {
         hostServices.deviceConstraints = options.deviceConstraints;
     }

package/dist/core/engine.d.ts

@@ -1,9 +1,15 @@
 import { type TaskRequest, type TaskResult } from "@independo/inderun-contracts";
 import type { HostServices } from "./host.js";
-import type { ProviderCapabilitySnapshot } from "./provider.js";
+import type { ProviderCapabilitySnapshot, StreamRun } from "./provider.js";
 import type { IndeRunApi } from "./generated/inderun-api.js";
 import { ProviderRegistry } from "./registry.js";
 import { type TelemetryService } from "./telemetry.js";
+/**
+ * @deprecated Renamed to `StreamRun`, which is the name the generated
+ * `IndeRunApi` surface and the Swift/Kotlin SDKs use. Kept as an alias so the
+ * rename is not a breaking change.
+ */
+export type StreamHandleResult = StreamRun;
 /**
  * Main orchestrator SDK entrypoint class.
  * Validates tasks, executes routing rules based on request constraints and connectivity,
@@ -21,6 +27,17 @@ export declare class IndeRun implements IndeRunApi {
      * @param telemetryService - Optional custom telemetry service listener.
      */
     constructor(registry: ProviderRegistry, hostServices: HostServices, telemetryService?: TelemetryService);
+    /**
+     * Current time from the host clock, falling back to wall-clock time when the
+     * host does not supply one.
+     */
+    private now;
+    /**
+     * Emits `route_decided` for a completed route selection. Shared by `run()` and
+     * `stream()`: the payload is identical for both modes, and the interaction
+     * mode is already reflected in the plan the router returned.
+     */
+    private emitRouteDecided;
     /**
      * Safely emits a telemetry event by swallowing any internal logging/telemetry system errors.
      * @param event - The telemetry event to emit.
@@ -40,6 +57,25 @@ export declare class IndeRun implements IndeRunApi {
      * @throws {IndeRunException} Standardized error indicating validation, connection, or provider failures.
      */
     run(request: TaskRequest): Promise<TaskResult>;
+    /**
+     * Orchestrates a Mode 2 streaming execution of a TaskRequest.
+     *
+     * Routes through the same planner as run(), asking it for a `stream` route: the
+     * planner rejects providers that do not declare `supports.streaming` or whose
+     * dynamic capability snapshot says they cannot stream here, and reports why. The
+     * whole returned chain is therefore mode-compatible and subject to the same
+     * privacy, locality, availability, and policy constraints as a Mode 1 route.
+     *
+     * Fallback to the next provider is allowed only before the first content event
+     * has been admitted for the run; once one has been delivered, the run is
+     * committed to that provider and any later provider failure becomes a terminal
+     * error outcome rather than a silent provider swap — partial output spliced from
+     * two providers is undetectable to the caller. Cancellation always forecloses
+     * fallback, regardless of commit state, and is idempotent.
+     * @param request - The canonical task request containing prompts, tasks, and constraints.
+     * @throws {IndeRunException} If validation fails or no eligible streaming provider exists.
+     */
+    stream(request: TaskRequest): Promise<StreamRun>;
     /**
      * Reports each registered provider's static descriptor and current dynamic capability check,
      * without executing a task. Useful for UI that shows live provider availability before a run.

package/dist/core/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAuB,KAAK,gBAAgB,EAAwB,MAAM,gBAAgB,CAAC;AAElG;;;;GAIG;AACH,qBAAa,OAAQ,YAAW,UAAU;IAWtC,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,YAAY;IAXtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAmB;IAE3C;;;;;OAKG;gBAEO,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,YAAY,EAClC,gBAAgB,CAAC,EAAE,gBAAgB;IAOrC;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAShB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;;;;OAOG;IACG,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAuIpD;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,0BAA0B,EAAE,CAAC;CASjE"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAmB,0BAA0B,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAQjD,OAAO,EAAuB,KAAK,gBAAgB,EAAwB,MAAM,gBAAgB,CAAC;AAGlG;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,OAAQ,YAAW,UAAU;IAWtC,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,YAAY;IAXtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAmB;IAE3C;;;;;OAKG;gBAEO,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,YAAY,EAClC,gBAAgB,CAAC,EAAE,gBAAgB;IAOrC;;;OAGG;IACH,OAAO,CAAC,GAAG;IAIX;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAShB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;;;;OAOG;IACG,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAsHpD;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;IA+PtD;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,0BAA0B,EAAE,CAAC;CASjE"}