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

package/dist/core/route-planner.d.ts

@@ -2,6 +2,11 @@ import type { RoutePlan as SharedPlannerRoutePlan, RoutePlannerInput as SharedPl
 import type { HostServices } from "./host.js";
 import type { ProviderAdapter } 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
@@ -12,25 +17,23 @@ export interface SharedPlannerModule {
     planRouteJson: (inputJson: string) => string | Promise<string>;
 }
 /**
- * Coarse, privacy-safe reason the WASM planner produced no route plan. Used
- * only for observability (telemetry/logging) — callers still fall back to
- * local selection regardless of which reason fired.
+ * 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, in which case `source` is `"unavailable"`
- * and `unavailableReason` narrows down why, so callers can log/emit telemetry
- * instead of silently swapping planners.
+ * planner could not produce a plan, and `unavailableReason` then narrows down
+ * why.
  */
 export interface PlannerOutcome {
     routePlan: SharedPlannerRoutePlan | null;
-    source: "wasm" | "unavailable";
     unavailableReason?: WasmUnavailableReason;
 }
 /**
  * Strategy that turns planner input into a deterministic route plan, or an
- * "unavailable" outcome (callers then fall back to local selection).
+ * "unavailable" outcome (which the router reports as a routing failure).
  */
 export interface RoutePlanner {
     planRoute(input: SharedPlannerInput): Promise<PlannerOutcome>;
@@ -50,13 +53,14 @@ export interface ProviderRuntimeSnapshot {
  * 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 so the engine can
- * fall back to local selection, and logs once via `console.warn` so the
- * degradation is never fully silent.
+ * 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 declare class WasmRoutePlanner implements RoutePlanner {
     private modulePromise?;
-    private loadFailureReason?;
+    private loadFailure?;
     private hasWarned;
     planRoute(input: SharedPlannerInput): Promise<PlannerOutcome>;
     private loadModule;
@@ -65,7 +69,11 @@ export declare class WasmRoutePlanner implements RoutePlanner {
 }
 /**
  * Describes each provider and evaluates its dynamic capabilities against the
- * host, returning snapshots sorted by provider id for deterministic planning.
+ * 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 declare function collectProviderRuntimeSnapshots(registryProviders: ProviderAdapter[], hostServices: HostServices): Promise<ProviderRuntimeSnapshot[]>;
 /**
@@ -73,5 +81,5 @@ export declare function collectProviderRuntimeSnapshots(registryProviders: Provi
  * consumes, applying default constraints/preferences and the current network
  * state.
  */
-export declare function buildSharedPlannerInput(request: TaskRequest, snapshots: ProviderRuntimeSnapshot[], networkOnline: boolean): SharedPlannerInput;
+export declare function buildSharedPlannerInput(request: TaskRequest, snapshots: ProviderRuntimeSnapshot[], networkOnline: boolean, interactionMode?: InteractionMode): SharedPlannerInput;
 //# sourceMappingURL=route-planner.d.ts.map

package/dist/core/route-planner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-planner.d.ts","sourceRoot":"","sources":["../../src/core/route-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,IAAI,sBAAsB,EACnC,iBAAiB,IAAI,kBAAkB,EACvC,WAAW,EACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChE;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC/B,eAAe,GAAG,sBAAsB,GAAG,aAAa,GAAG,aAAa,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACzC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC;IAC/B,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/D;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAClE,YAAY,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;CACvE;AAED;;;;;;;;;GASG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,aAAa,CAAC,CAAsC;IAC5D,OAAO,CAAC,iBAAiB,CAAC,CAAwB;IAClD,OAAO,CAAC,SAAS,CAAS;IAEpB,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;YAkBrD,UAAU;YAOV,YAAY;IA6B1B,OAAO,CAAC,QAAQ;CAUjB;AAED;;;GAGG;AACH,wBAAsB,+BAA+B,CACnD,iBAAiB,EAAE,eAAe,EAAE,EACpC,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAepC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,uBAAuB,EAAE,EACpC,aAAa,EAAE,OAAO,GACrB,kBAAkB,CAsBpB"}
+{"version":3,"file":"route-planner.d.ts","sourceRoot":"","sources":["../../src/core/route-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,IAAI,sBAAsB,EACnC,iBAAiB,IAAI,kBAAkB,EACvC,WAAW,EACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAEjF;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChE;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC/B,eAAe,GAAG,sBAAsB,GAAG,aAAa,GAAG,aAAa,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACzC,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/D;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAClE,YAAY,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;CACvE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,aAAa,CAAC,CAAsC;IAC5D,OAAO,CAAC,WAAW,CAAC,CAAqD;IACzE,OAAO,CAAC,SAAS,CAAS;IAEpB,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;YAoBrD,UAAU;YAOV,YAAY;IA0B1B,OAAO,CAAC,QAAQ;CAOjB;AAED;;;;;;;GAOG;AACH,wBAAsB,+BAA+B,CACnD,iBAAiB,EAAE,eAAe,EAAE,EACpC,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAapC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,uBAAuB,EAAE,EACpC,aAAa,EAAE,OAAO,EACtB,eAAe,GAAE,eAAuB,GACvC,kBAAkB,CAuBpB"}

package/dist/core/route-planner.js

@@ -4,29 +4,32 @@
  * 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 so the engine can
- * fall back to local selection, and logs once via `console.warn` so the
- * degradation is never fully silent.
+ * 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 {
     modulePromise;
-    loadFailureReason;
+    loadFailure;
     hasWarned = false;
     async planRoute(input) {
         const module = await this.loadModule();
         if (!module) {
-            const unavailableReason = this.loadFailureReason ?? "import_failed";
-            this.warnOnce(unavailableReason);
-            return { routePlan: null, source: "unavailable", unavailableReason };
+            // 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), source: "wasm" };
+            return { routePlan: JSON.parse(result) };
         }
         catch (error) {
             this.warnOnce("plan_failed", error);
-            return { routePlan: null, source: "unavailable", unavailableReason: "plan_failed" };
+            return { routePlan: null, unavailableReason: "plan_failed" };
         }
     }
     async loadModule() {
@@ -41,13 +44,11 @@ export class WasmRoutePlanner {
             mod = (await import("@independo/inderun-route-core-wasm"));
         }
         catch (error) {
-            this.loadFailureReason = "import_failed";
-            this.warnOnce("import_failed", error);
+            this.loadFailure = { reason: "import_failed", error };
             return null;
         }
         if (typeof mod.planRouteJson !== "function") {
-            this.loadFailureReason = "invalid_module_shape";
-            this.warnOnce("invalid_module_shape");
+            this.loadFailure = { reason: "invalid_module_shape" };
             return null;
         }
         if (mod.initSharedCore) {
@@ -55,8 +56,7 @@ export class WasmRoutePlanner {
                 await mod.initSharedCore();
             }
             catch (error) {
-                this.loadFailureReason = "init_failed";
-                this.warnOnce("init_failed", error);
+                this.loadFailure = { reason: "init_failed", error };
                 return null;
             }
         }
@@ -67,37 +67,41 @@ export class WasmRoutePlanner {
             return;
         }
         this.hasWarned = true;
-        console.warn(`[IndeRun] WASM route planner unavailable (${reason}); falling back to local route selection.`, error);
+        console.warn(`[IndeRun] WASM route planner unavailable (${reason}); routing will fail.`, error);
     }
 }
 /**
  * Describes each provider and evaluates its dynamic capabilities against the
- * host, returning snapshots sorted by provider id for deterministic planning.
+ * 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, hostServices) {
-    const snapshots = await Promise.all(registryProviders.map(async (provider) => {
+    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)
+            capabilities: toSharedPlannerCapabilities(capabilities, descriptor, provider)
         };
     }));
-    return snapshots.sort((left, right) => left.descriptor.id.localeCompare(right.descriptor.id));
 }
 /**
  * Assembles the normalized {@link SharedPlannerInput} the shared route core
  * consumes, applying default constraints/preferences and the current network
  * state.
  */
-export function buildSharedPlannerInput(request, snapshots, networkOnline) {
+export function buildSharedPlannerInput(request, snapshots, networkOnline, interactionMode = "run") {
     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",
@@ -118,8 +122,10 @@ function toSharedPlannerDescriptor(descriptor) {
         id: descriptor.id,
         type: descriptor.type,
         supports: {
-            run: descriptor.supports.run
+            run: descriptor.supports.run,
+            streaming: descriptor.supports.streaming
         },
+        cancel: descriptor.cancel,
         tasks: descriptor.tasks,
         ...(descriptor.privacy
             ? {
@@ -131,9 +137,30 @@ function toSharedPlannerDescriptor(descriptor) {
             : {})
     };
 }
-function toSharedPlannerCapabilities(capabilities) {
+/**
+ * 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, descriptor, provider) {
+    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 } : {})
+        ...(capabilities.reason ? { reason: capabilities.reason } : {}),
+        streamingAvailable,
+        ...(!streamingAvailable && streamingUnavailableReason ? { streamingUnavailableReason } : {}),
+        ...(capabilities.cancellationAvailable !== undefined
+            ? { cancellationAvailable: capabilities.cancellationAvailable }
+            : {})
     };
 }

package/dist/core/router.d.ts

@@ -2,7 +2,7 @@ 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 { type RoutePlanner, type SharedPlannerRoutePlan, type WasmUnavailableReason } from "./route-planner.js";
+import { type InteractionMode, type RoutePlanner, type SharedPlannerRoutePlan } from "./route-planner.js";
 /**
  * Output structure from the Router containing the chosen provider and a route selection description.
  */
@@ -23,16 +23,6 @@ export interface RouteSelection {
      * Explanation detailing the selection decision. Useful for debugging and telemetry.
      */
     explanation: string;
-    /**
-     * Which planner produced `routePlan`: the shared Rust/WASM core, or the
-     * local TypeScript fallback used when the WASM planner is unavailable.
-     */
-    plannerSource: "wasm" | "fallback";
-    /**
-     * Set when `plannerSource` is `"fallback"` because the WASM planner failed;
-     * `undefined` when the fallback was not caused by a planner failure.
-     */
-    plannerUnavailableReason?: WasmUnavailableReason;
 }
 /**
  * Routing engine module. Filters registered providers against task types, request constraints,
@@ -52,13 +42,19 @@ export declare class Router {
      *  - `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.
      */
-    selectRoute(request: TaskRequest, hostServices: HostServices): Promise<RouteSelection>;
+    selectRoute(request: TaskRequest, hostServices: HostServices, interactionMode?: InteractionMode): Promise<RouteSelection>;
     private selectFromSharedPlan;
-    private selectFallbackRoute;
     private buildSelectionFromRoutePlan;
-    private createFallbackPlan;
-    private buildFallbackFailureSummary;
+    /**
+     * 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;
 }
 //# sourceMappingURL=router.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/core/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOtD,OAAO,EAIL,KAAK,YAAY,EAEjB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAE3B,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC;;OAEG;IACH,SAAS,EAAE,sBAAsB,CAAC;IAClC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,EAAE,MAAM,GAAG,UAAU,CAAC;IACnC;;;OAGG;IACH,wBAAwB,CAAC,EAAE,qBAAqB,CAAC;CAClD;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO;gBADP,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,GAAE,YAAqC;IAGxD;;;;;;;;;OASG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAc5F,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,2BAA2B;IA2BnC,OAAO,CAAC,kBAAkB;IA0F1B,OAAO,CAAC,2BAA2B;IAiCnC,OAAO,CAAC,gBAAgB;CAYzB"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/core/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOtD,OAAO,EAGL,KAAK,eAAe,EAEpB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAE5B,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC;;OAEG;IACH,SAAS,EAAE,sBAAsB,CAAC;IAClC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO;gBADP,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,GAAE,YAAqC;IAGxD;;;;;;;;;;;;;OAaG;IACG,WAAW,CACf,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,YAAY,EAC1B,eAAe,GAAE,eAAuB,GACvC,OAAO,CAAC,cAAc,CAAC;IAoB1B,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,2BAA2B;IAuBnC;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CAkBzB"}

package/dist/core/router.js

@@ -21,31 +21,34 @@ export class Router {
      *  - `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, hostServices) {
+    async selectRoute(request, hostServices, interactionMode = "run") {
         const online = await hostServices.connectivity.isOnline();
         const snapshots = await collectProviderRuntimeSnapshots(this.registry.list(), hostServices);
-        const planInput = buildSharedPlannerInput(request, snapshots, online);
+        const planInput = buildSharedPlannerInput(request, snapshots, online, interactionMode);
         const outcome = await this.planner.planRoute(planInput);
-        if (outcome.routePlan) {
-            return this.selectFromSharedPlan(snapshots, outcome.routePlan);
+        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.selectFallbackRoute(request, snapshots, online, outcome.unavailableReason);
+        return this.selectFromSharedPlan(snapshots, outcome.routePlan);
     }
     selectFromSharedPlan(snapshots, routePlan) {
         if (!routePlan.selectedProviderId) {
             throw this.routePlanFailure(routePlan);
         }
-        return this.buildSelectionFromRoutePlan(snapshots, routePlan, "wasm");
-    }
-    selectFallbackRoute(request, snapshots, online, plannerUnavailableReason) {
-        const plan = this.createFallbackPlan(request, snapshots, online);
-        if (!plan.selectedProviderId) {
-            throw this.routePlanFailure(plan);
-        }
-        return this.buildSelectionFromRoutePlan(snapshots, plan, "fallback", plannerUnavailableReason);
+        return this.buildSelectionFromRoutePlan(snapshots, routePlan);
     }
-    buildSelectionFromRoutePlan(snapshots, routePlan, plannerSource, plannerUnavailableReason) {
+    buildSelectionFromRoutePlan(snapshots, routePlan) {
         const orderedProviders = routePlan.candidates
             .map((candidate) => snapshots.find((snapshot) => snapshot.descriptor.id === candidate.providerId))
             .filter((snapshot) => snapshot !== undefined);
@@ -57,114 +60,30 @@ export class Router {
             provider: selected.provider,
             fallbackProviders: orderedProviders.slice(1).map((snapshot) => snapshot.provider),
             routePlan,
-            explanation: routePlan.explanation.summary,
-            plannerSource,
-            ...(plannerUnavailableReason ? { plannerUnavailableReason } : {})
-        };
-    }
-    createFallbackPlan(request, snapshots, online) {
-        const planInput = buildSharedPlannerInput(request, snapshots, online);
-        const eligible = snapshots
-            .filter((candidate) => candidate.descriptor.tasks.includes(planInput.task.kind))
-            .filter((candidate) => candidate.descriptor.supports.run);
-        const localCandidates = eligible.filter((candidate) => candidate.descriptor.type !== "cloud");
-        const cloudCandidates = eligible.filter((candidate) => candidate.descriptor.type === "cloud");
-        // Constraint filtering must apply to the whole candidate list, not just the selected provider:
-        // the remainder becomes the engine's fallback chain, and a fallback that violates the request
-        // constraints would let a `local_required` run be retried against a cloud provider.
-        const admissible = eligible.filter((candidate) => {
-            const descriptor = candidate.descriptor;
-            const constraints = planInput.constraints;
-            // Mirrors `is_data_private` in the shared Rust planner: a provider is private when it
-            // declares that data does not leave the device, defaulting to non-cloud providers.
-            const isDataPrivate = descriptor.privacy
-                ? !descriptor.privacy.dataLeavesDevice
-                : descriptor.type !== "cloud";
-            if (constraints.cloud === "forbidden" && descriptor.type === "cloud") {
-                return false;
-            }
-            if (constraints.cloud === "required" && descriptor.type !== "cloud") {
-                return false;
-            }
-            if (constraints.privacy === "local_required" && !isDataPrivate) {
-                return false;
-            }
-            if (constraints.privacy === "cloud_required" && descriptor.type !== "cloud") {
-                return false;
-            }
-            if (!online && descriptor.type === "cloud") {
-                return false;
-            }
-            return candidate.capabilities.available;
-        });
-        if (admissible.length === 0) {
-            const failureSummary = this.buildFallbackFailureSummary({
-                online,
-                constraints: planInput.constraints,
-                localCandidates,
-                cloudCandidates
-            });
-            const failureCode = !online
-                ? "offline"
-                : planInput.constraints.cloud === "required" ||
-                    planInput.constraints.privacy === "cloud_required"
-                    ? "unavailable"
-                    : "capability_mismatch";
-            return {
-                fallbackProviderIds: [],
-                candidates: [],
-                rejectedProviders: [],
-                failureCode,
-                explanation: {
-                    summary: failureSummary
-                }
-            };
-        }
-        const selectedProviderId = admissible[0]?.descriptor.id;
-        return {
-            selectedProviderId,
-            fallbackProviderIds: admissible.slice(1).map((candidate) => candidate.descriptor.id),
-            candidates: admissible.map((candidate, index) => ({
-                providerId: candidate.descriptor.id,
-                order: index
-            })),
-            rejectedProviders: [],
-            explanation: {
-                summary: `Selected provider '${selectedProviderId}' deterministically from ${admissible.length} eligible candidate(s).`,
-                selectedProviderId
-            }
+            explanation: routePlan.explanation.summary
         };
     }
-    buildFallbackFailureSummary(input) {
-        const wantsCloud = input.constraints.cloud === "required" || input.constraints.privacy === "cloud_required";
-        const wantsLocal = input.constraints.privacy === "local_required";
-        if (!input.online && (wantsCloud || input.cloudCandidates.length > 0)) {
-            return "No network connection is available.";
-        }
-        if (wantsCloud) {
-            if (input.cloudCandidates.length === 0) {
-                return "No cloud provider found.";
-            }
-            return "No cloud provider is currently available.";
-        }
-        if (wantsLocal) {
-            if (input.localCandidates.length === 0) {
-                return "No on-device provider found.";
-            }
-            return "No on-device provider is currently available.";
-        }
-        return "No eligible provider found for the current routing constraints.";
-    }
+    /**
+     * 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.
+     */
     routePlanFailure(routePlan) {
         const message = routePlan.explanation.summary;
+        const details = {
+            details: {
+                failureCode: routePlan.failureCode,
+                rejectedProviders: routePlan.rejectedProviders
+            }
+        };
         switch (routePlan.failureCode) {
             case "offline":
-                throw createOffline(message);
+                throw createOffline(message, details);
             case "unavailable":
-                throw createUnavailable(message);
+                throw createUnavailable(message, details);
             case "capability_mismatch":
             default:
-                throw createCapabilityMismatch(message);
+                throw createCapabilityMismatch(message, details);
         }
     }
 }

package/dist/core/sse.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare function parseSseStream(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<SseEvent>;
+//# sourceMappingURL=sse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/core/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAuB,cAAc,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAsFjG"}

package/dist/core/sse.js

@@ -0,0 +1,118 @@
+/**
+ * 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) {
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    let eventType;
+    let data;
+    let id;
+    const takeEvent = () => {
+        const dispatched = data === undefined ? undefined : buildEvent(eventType, data, id);
+        eventType = undefined;
+        data = undefined;
+        id = undefined;
+        return dispatched;
+    };
+    const handleLine = (line) => {
+        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) {
+        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, data, id) {
+    return {
+        ...(eventType !== undefined ? { event: eventType } : {}),
+        data,
+        ...(id !== undefined ? { id } : {})
+    };
+}