@independo/inderun-web 0.3.0-dev.9 → 0.3.0

package/src/core/route-planner.ts

@@ -0,0 +1,261 @@
+import type {
+  RoutePlan as SharedPlannerRoutePlan,
+  RoutePlannerInput as SharedPlannerInput,
+  TaskRequest
+} from "@independo/inderun-contracts";
+import type { HostServices } from "./host.js";
+import type {
+  ProviderAdapter,
+  ProviderDescriptor,
+  ProviderDynamicCapabilities
+} from "./provider.js";
+
+export type { SharedPlannerInput, SharedPlannerRoutePlan };
+
+/**
+ * Interaction mode the caller is requesting a route for. Passed to the shared
+ * planner, which rejects providers that cannot satisfy it.
+ */
+export type InteractionMode = NonNullable<SharedPlannerInput["interactionMode"]>;
+
+/**
+ * Minimal shape of the shared route-core module (the WASM wrapper), used to
+ * plan routes via JSON in/JSON out. `initSharedCore` initializes the WASM
+ * bindings when present.
+ */
+export interface SharedPlannerModule {
+  initSharedCore?: () => Promise<void>;
+  planRouteJson: (inputJson: string) => string | Promise<string>;
+}
+
+/**
+ * Coarse, privacy-safe reason the WASM planner produced no route plan. Surfaced
+ * on the resulting `Internal` routing error and in the `console.warn`, so an
+ * operator can tell a missing bundle chunk from a blocked instantiation.
+ */
+export type WasmUnavailableReason =
+  "import_failed" | "invalid_module_shape" | "init_failed" | "plan_failed";
+
+/**
+ * Result of a {@link RoutePlanner} attempt. `routePlan` is `null` when the
+ * planner could not produce a plan, and `unavailableReason` then narrows down
+ * why.
+ */
+export interface PlannerOutcome {
+  routePlan: SharedPlannerRoutePlan | null;
+  unavailableReason?: WasmUnavailableReason;
+}
+
+/**
+ * Strategy that turns planner input into a deterministic route plan, or an
+ * "unavailable" outcome (which the router reports as a routing failure).
+ */
+export interface RoutePlanner {
+  planRoute(input: SharedPlannerInput): Promise<PlannerOutcome>;
+}
+
+/**
+ * A provider paired with the descriptor/capability projection the shared route
+ * planner consumes.
+ */
+export interface ProviderRuntimeSnapshot {
+  provider: ProviderAdapter;
+  descriptor: SharedPlannerInput["providers"][number]["descriptor"];
+  capabilities: SharedPlannerInput["providers"][number]["capabilities"];
+}
+
+/**
+ * {@link RoutePlanner} backed by the Rust route core compiled to WASM. The
+ * module specifier is a static literal (not configurable) so bundlers such as
+ * Vite/webpack/Rollup can statically resolve and chunk it — a variable
+ * specifier defeats bundler analysis and silently never loads in the browser
+ * (see issue #109). The module is imported lazily and memoized; if it cannot
+ * be loaded, `planRoute` resolves an "unavailable" outcome, which the engine
+ * turns into an `Internal` routing failure carrying the reason below. There is
+ * no second planner to degrade to — a failure here is a failure to route, not a
+ * quieter route — so this also logs once via `console.warn` to name the cause.
+ */
+export class WasmRoutePlanner implements RoutePlanner {
+  private modulePromise?: Promise<SharedPlannerModule | null>;
+  private loadFailure?: { reason: WasmUnavailableReason; error?: unknown };
+  private hasWarned = false;
+
+  async planRoute(input: SharedPlannerInput): Promise<PlannerOutcome> {
+    const module = await this.loadModule();
+    if (!module) {
+      // The load path only records why it failed; warning here covers both the
+      // first attempt and every later call served from the memoized promise.
+      const unavailableReason = this.loadFailure?.reason ?? "import_failed";
+      this.warnOnce(unavailableReason, this.loadFailure?.error);
+      return { routePlan: null, unavailableReason };
+    }
+
+    try {
+      const json = JSON.stringify(input);
+      const result = await module.planRouteJson(json);
+      return { routePlan: JSON.parse(result) as SharedPlannerRoutePlan };
+    } catch (error) {
+      this.warnOnce("plan_failed", error);
+      return { routePlan: null, unavailableReason: "plan_failed" };
+    }
+  }
+
+  private async loadModule(): Promise<SharedPlannerModule | null> {
+    if (!this.modulePromise) {
+      this.modulePromise = this.importModule();
+    }
+    return this.modulePromise;
+  }
+
+  private async importModule(): Promise<SharedPlannerModule | null> {
+    let mod: SharedPlannerModule;
+    try {
+      mod = (await import("@independo/inderun-route-core-wasm")) as SharedPlannerModule;
+    } catch (error) {
+      this.loadFailure = { reason: "import_failed", error };
+      return null;
+    }
+
+    if (typeof mod.planRouteJson !== "function") {
+      this.loadFailure = { reason: "invalid_module_shape" };
+      return null;
+    }
+
+    if (mod.initSharedCore) {
+      try {
+        await mod.initSharedCore();
+      } catch (error) {
+        this.loadFailure = { reason: "init_failed", error };
+        return null;
+      }
+    }
+
+    return mod;
+  }
+
+  private warnOnce(reason: WasmUnavailableReason, error?: unknown): void {
+    if (this.hasWarned) {
+      return;
+    }
+    this.hasWarned = true;
+    console.warn(`[IndeRun] WASM route planner unavailable (${reason}); routing will fail.`, error);
+  }
+}
+
+/**
+ * Describes each provider and evaluates its dynamic capabilities against the
+ * host.
+ *
+ * Registration order is passed through untouched: the shared planner ranks
+ * candidates itself and tie-breaks by provider id, so sorting here would only
+ * assert an ordering the planner is free to ignore.
+ */
+export async function collectProviderRuntimeSnapshots(
+  registryProviders: ProviderAdapter[],
+  hostServices: HostServices
+): Promise<ProviderRuntimeSnapshot[]> {
+  return Promise.all(
+    registryProviders.map(async (provider) => {
+      const descriptor = provider.describe();
+      const capabilities = await provider.capabilities(hostServices);
+
+      return {
+        provider,
+        descriptor: toSharedPlannerDescriptor(descriptor),
+        capabilities: toSharedPlannerCapabilities(capabilities, descriptor, provider)
+      };
+    })
+  );
+}
+
+/**
+ * Assembles the normalized {@link SharedPlannerInput} the shared route core
+ * consumes, applying default constraints/preferences and the current network
+ * state.
+ */
+export function buildSharedPlannerInput(
+  request: TaskRequest,
+  snapshots: ProviderRuntimeSnapshot[],
+  networkOnline: boolean,
+  interactionMode: InteractionMode = "run"
+): SharedPlannerInput {
+  const constraints = request.constraints ?? {};
+  const preferences = request.preferences ?? {};
+
+  return {
+    task: {
+      kind: request.task.kind
+    },
+    interactionMode,
+    constraints: {
+      privacy: constraints.privacy ?? "cloud_allowed",
+      cloud: constraints.cloud ?? "allowed",
+      networkOnline,
+      ...(constraints.timeoutMs !== undefined ? { timeoutMs: constraints.timeoutMs } : {})
+    },
+    preferences: {
+      optimizeFor: preferences.optimizeFor ?? "balanced"
+    },
+    providers: snapshots.map((snapshot) => ({
+      descriptor: snapshot.descriptor,
+      capabilities: snapshot.capabilities
+    }))
+  };
+}
+
+function toSharedPlannerDescriptor(
+  descriptor: ProviderDescriptor
+): SharedPlannerInput["providers"][number]["descriptor"] {
+  return {
+    id: descriptor.id,
+    type: descriptor.type,
+    supports: {
+      run: descriptor.supports.run,
+      streaming: descriptor.supports.streaming
+    },
+    cancel: descriptor.cancel,
+    tasks: descriptor.tasks,
+    ...(descriptor.privacy
+      ? {
+          privacy: {
+            dataLeavesDevice: descriptor.privacy.dataLeavesDevice,
+            ...(descriptor.privacy.regions ? { regions: descriptor.privacy.regions } : {})
+          }
+        }
+      : {})
+  };
+}
+
+/**
+ * Projects the dynamic capability snapshot for the planner.
+ *
+ * `stream()` being absent from the adapter is folded in here rather than
+ * filtered out downstream: an adapter that declares `supports.streaming` but
+ * never implemented the method is not streaming-capable, and saying so as a
+ * planner-visible reason is what lets the route explanation name the provider
+ * instead of silently dropping it.
+ */
+function toSharedPlannerCapabilities(
+  capabilities: ProviderDynamicCapabilities,
+  descriptor: ProviderDescriptor,
+  provider: ProviderAdapter
+): SharedPlannerInput["providers"][number]["capabilities"] {
+  const declaresStreaming = capabilities.streamingAvailable ?? descriptor.supports.streaming;
+  const implementsStream = typeof provider.stream === "function";
+  const streamingAvailable = declaresStreaming && implementsStream;
+  const streamingUnavailableReason =
+    capabilities.streamingUnavailableReason ??
+    (declaresStreaming && !implementsStream
+      ? `Provider '${descriptor.id}' declares streaming but does not implement stream().`
+      : undefined);
+
+  return {
+    available: capabilities.available,
+    ...(capabilities.reason ? { reason: capabilities.reason } : {}),
+    streamingAvailable,
+    ...(!streamingAvailable && streamingUnavailableReason ? { streamingUnavailableReason } : {}),
+    ...(capabilities.cancellationAvailable !== undefined
+      ? { cancellationAvailable: capabilities.cancellationAvailable }
+      : {})
+  };
+}

package/src/core/router.ts

@@ -0,0 +1,149 @@
+import type { TaskRequest } from "@independo/inderun-contracts";
+import type { HostServices } from "./host.js";
+import type { ProviderAdapter } from "./provider.js";
+import type { ProviderRegistry } from "./registry.js";
+import {
+  createCapabilityMismatch,
+  createInternal,
+  createOffline,
+  createUnavailable
+} from "./errors.js";
+import {
+  buildSharedPlannerInput,
+  collectProviderRuntimeSnapshots,
+  type InteractionMode,
+  type ProviderRuntimeSnapshot,
+  type RoutePlanner,
+  type SharedPlannerRoutePlan,
+  WasmRoutePlanner
+} from "./route-planner.js";
+
+/**
+ * Output structure from the Router containing the chosen provider and a route selection description.
+ */
+export interface RouteSelection {
+  /**
+   * The selected provider adapter to run.
+   */
+  provider: ProviderAdapter;
+  /**
+   * Ordered fallback providers to try if the primary provider fails before producing a final result.
+   */
+  fallbackProviders: ProviderAdapter[];
+  /**
+   * The shared route plan used to select this provider chain.
+   */
+  routePlan: SharedPlannerRoutePlan;
+  /**
+   * Explanation detailing the selection decision. Useful for debugging and telemetry.
+   */
+  explanation: string;
+}
+
+/**
+ * Routing engine module. Filters registered providers against task types, request constraints,
+ * and dynamic host capabilities (such as connectivity and battery/thermal constraints)
+ * to output deterministic execution pathways.
+ */
+export class Router {
+  constructor(
+    private registry: ProviderRegistry,
+    private planner: RoutePlanner = new WasmRoutePlanner()
+  ) {}
+
+  /**
+   * Selects an optimal and compatible execution provider based on the task request and host conditions.
+   * @param request - The canonical task request payload.
+   * @param hostServices - Host services containing network status and hardware indicators.
+   * @returns Resolves to the selected RouteSelection object.
+   * @throws {IndeRunException} Under the following routing failure rules:
+   *  - `CapabilityMismatch` when `execution === 'on_device'` but no local provider is registered or available.
+   *  - `Offline` when `execution === 'cloud'` but the device lacks internet connectivity.
+   *  - `Unavailable` when `execution === 'cloud'` but no cloud provider is registered or functional.
+   *
+   * The requested `interactionMode` is a planning input, not a post-filter: the
+   * shared planner rejects providers that cannot satisfy it and says why, so the
+   * whole returned chain is mode-compatible.
+   */
+  async selectRoute(
+    request: TaskRequest,
+    hostServices: HostServices,
+    interactionMode: InteractionMode = "run"
+  ): Promise<RouteSelection> {
+    const online = await hostServices.connectivity.isOnline();
+    const snapshots = await collectProviderRuntimeSnapshots(this.registry.list(), hostServices);
+
+    const planInput = buildSharedPlannerInput(request, snapshots, online, interactionMode);
+    const outcome = await this.planner.planRoute(planInput);
+
+    if (!outcome.routePlan) {
+      // There is no second planner to degrade to: routing is the shared Rust
+      // core's semantics or nothing. Failing here keeps provider selection
+      // identical everywhere rather than forking it on a module load failure.
+      const reason = outcome.unavailableReason ?? "import_failed";
+      throw createInternal(`Route planner unavailable (${reason}).`, {
+        details: { plannerUnavailableReason: reason }
+      });
+    }
+
+    return this.selectFromSharedPlan(snapshots, outcome.routePlan);
+  }
+
+  private selectFromSharedPlan(
+    snapshots: ProviderRuntimeSnapshot[],
+    routePlan: SharedPlannerRoutePlan
+  ): RouteSelection {
+    if (!routePlan.selectedProviderId) {
+      throw this.routePlanFailure(routePlan);
+    }
+
+    return this.buildSelectionFromRoutePlan(snapshots, routePlan);
+  }
+
+  private buildSelectionFromRoutePlan(
+    snapshots: ProviderRuntimeSnapshot[],
+    routePlan: SharedPlannerRoutePlan
+  ): RouteSelection {
+    const orderedProviders = routePlan.candidates
+      .map((candidate) =>
+        snapshots.find((snapshot) => snapshot.descriptor.id === candidate.providerId)
+      )
+      .filter((snapshot): snapshot is ProviderRuntimeSnapshot => snapshot !== undefined);
+
+    const selected = orderedProviders[0];
+    if (!selected) {
+      throw createInternal("Route plan selected a provider that is no longer registered.");
+    }
+
+    return {
+      provider: selected.provider,
+      fallbackProviders: orderedProviders.slice(1).map((snapshot) => snapshot.provider),
+      routePlan,
+      explanation: routePlan.explanation.summary
+    };
+  }
+
+  /**
+   * Routing failure throws before any `route_decided` telemetry is emitted, so the
+   * plan's diagnostics are attached to the exception — that is the only channel
+   * through which a caller learns *why* each provider was rejected.
+   */
+  private routePlanFailure(routePlan: SharedPlannerRoutePlan): never {
+    const message = routePlan.explanation.summary;
+    const details = {
+      details: {
+        failureCode: routePlan.failureCode,
+        rejectedProviders: routePlan.rejectedProviders
+      }
+    };
+    switch (routePlan.failureCode) {
+      case "offline":
+        throw createOffline(message, details);
+      case "unavailable":
+        throw createUnavailable(message, details);
+      case "capability_mismatch":
+      default:
+        throw createCapabilityMismatch(message, details);
+    }
+  }
+}

package/src/core/sse.ts

@@ -0,0 +1,134 @@
+/**
+ * A single dispatched server-sent event.
+ *
+ * `event` and `id` are `undefined` when the stream did not carry those fields.
+ * `data` is the accumulated data payload with its trailing newline removed, and
+ * is passed through verbatim — sentinels such as OpenAI's `[DONE]` are the
+ * caller's concern, not the framing layer's.
+ */
+export interface SseEvent {
+  event?: string;
+  data: string;
+  id?: string;
+}
+
+/**
+ * Frames a raw byte stream into server-sent events.
+ *
+ * Follows the WHATWG server-sent events stream parsing rules, minus
+ * reconnection: `retry` is parsed as a field and ignored, and there is no
+ * Last-Event-ID reconnect logic. Concretely that means:
+ *
+ * - lines end with LF, CRLF, or bare CR;
+ * - a line beginning with `:` is a comment (servers send these as keep-alives);
+ * - `field: value` strips exactly one leading space from the value, and a line
+ *   with no colon is that field with an empty value;
+ * - `data` fields accumulate, joined by newlines;
+ * - a blank line dispatches the accumulated event, or resets without
+ *   dispatching if no data was accumulated;
+ * - a stream that ends mid-event does **not** dispatch the partial event, since
+ *   a truncated event must never be reported as a complete one.
+ *
+ * Chunk boundaries are meaningless: this decodes incrementally (`stream: true`)
+ * so a boundary may fall inside a multi-byte UTF-8 sequence or mid-line.
+ *
+ * Held to `contracts/fixtures/streaming/sse-framing.json` together with the
+ * Swift and Kotlin implementations of the same protocol.
+ *
+ * @param chunks - Raw response body chunks, in arrival order.
+ */
+export async function* parseSseStream(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<SseEvent> {
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+
+  let eventType: string | undefined;
+  let data: string | undefined;
+  let id: string | undefined;
+
+  const takeEvent = (): SseEvent | undefined => {
+    const dispatched = data === undefined ? undefined : buildEvent(eventType, data, id);
+    eventType = undefined;
+    data = undefined;
+    id = undefined;
+    return dispatched;
+  };
+
+  const handleLine = (line: string): SseEvent | undefined => {
+    if (line.length === 0) return takeEvent();
+    if (line.startsWith(":")) return undefined;
+
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+
+    switch (field) {
+      case "event":
+        eventType = value;
+        break;
+      case "data":
+        data = data === undefined ? value : `${data}\n${value}`;
+        break;
+      case "id":
+        // Per the SSE spec an id containing a NUL is ignored outright.
+        if (!value.includes("\0")) id = value;
+        break;
+      default:
+        // `retry` and anything unrecognized are dropped rather than erroring.
+        break;
+    }
+
+    return undefined;
+  };
+
+  for await (const chunk of chunks) {
+    buffer += decoder.decode(chunk, { stream: true });
+
+    for (;;) {
+      const line = takeLine();
+      if (line === undefined) break;
+      const dispatched = handleLine(line);
+      if (dispatched) yield dispatched;
+    }
+  }
+
+  // A trailing bare CR is ambiguous until the stream ends: it could still have
+  // been the first half of a CRLF.
+  buffer += decoder.decode();
+  for (;;) {
+    const line = takeLine(true);
+    if (line === undefined) break;
+    const dispatched = handleLine(line);
+    if (dispatched) yield dispatched;
+  }
+
+  function takeLine(atEnd = false): string | undefined {
+    for (let index = 0; index < buffer.length; index += 1) {
+      const char = buffer[index];
+      if (char === "\n") {
+        const line = buffer.slice(0, index);
+        buffer = buffer.slice(index + 1);
+        return line;
+      }
+      if (char === "\r") {
+        const isLast = index === buffer.length - 1;
+        // Withhold a trailing CR until we know whether an LF follows, unless
+        // the stream is over and no LF can arrive.
+        if (isLast && !atEnd) return undefined;
+        const skip = buffer[index + 1] === "\n" ? 2 : 1;
+        const line = buffer.slice(0, index);
+        buffer = buffer.slice(index + skip);
+        return line;
+      }
+    }
+    return undefined;
+  }
+}
+
+function buildEvent(eventType: string | undefined, data: string, id: string | undefined): SseEvent {
+  return {
+    ...(eventType !== undefined ? { event: eventType } : {}),
+    data,
+    ...(id !== undefined ? { id } : {})
+  };
+}

package/src/core/telemetry.ts

@@ -0,0 +1,20 @@
+import type { TelemetryEvent, TelemetryService } from "@independo/inderun-contracts";
+
+export type {
+  TelemetryEvent,
+  TelemetryEventType,
+  TelemetryService
+} from "@independo/inderun-contracts";
+
+/**
+ * Default no-op telemetry handler that discards all events.
+ */
+export class NoOpTelemetryService implements TelemetryService {
+  /**
+   * Discards the telemetry event.
+   * @param _event - The telemetry event to discard.
+   */
+  emit(_event: TelemetryEvent): void {
+    // No-op
+  }
+}