@independo/inderun-web 0.2.0-dev.1 → 0.2.0-dev.3

package/README.md

@@ -8,7 +8,7 @@
 
 TypeScript/Web SDK for IndeRun.
 
-This package provides the Web SDK entrypoint, the engine core, routing, telemetry, error normalization, and the OpenAI-compatible cloud provider.
+This package provides the Web SDK entrypoint, the engine core, routing, telemetry, error normalization, the OpenAI-compatible cloud provider, and the Web ONNX Runtime provider for developer-supplied local models.
 
 ## Basic Usage
 
@@ -48,6 +48,122 @@ taxonomy (`AuthError`, `RateLimited`, `Timeout`, `Unavailable`, `Internal`). The
 exact status-to-class mapping is documented on the provider in code — see
 `OpenAIResponsesProvider` — so it stays in sync with behavior.
 
+## On-Device Models: ONNX Runtime (Web)
+
+`local.onnx.genai.web` runs developer-supplied ONNX models in the browser. Registering it is what
+makes `constraints.privacy = "local_required"` routable. Pass `onnx` to the factory (`openAI` and
+`onnx` are both optional, but at least one is required):
+
+```ts
+import { createIndeRunWeb } from "@independo/inderun-web";
+
+const inderun = createIndeRunWeb({
+  onnx: {
+    modelPackage: {
+      id: "phi-3-mini-web",
+      format: "onnx",
+      tasks: ["text_to_text"],
+      runtime: { platforms: ["web"] },
+      source: { sourceType: "registry", ref: "onnx-community/Phi-3-mini-4k-instruct" }
+    }
+  }
+});
+```
+
+`modelPackage` is the provider-neutral `ModelPackage` contract from
+`@independo/inderun-contracts`; only `id` and `format` are required, and the package is validated
+(including the inline-secret and URL-userinfo rules) before every attempt. Model files must never
+carry credentials — use `authContextRef` and secure storage instead.
+
+Options: `id` (defaults to `local.onnx.genai.web`), `modelPackage` (required), `runtime`, and
+`timeoutMs` (a request's `constraints.timeoutMs` wins).
+
+The default runtime loads **quantized** weights (`q4f16` on WebGPU, `q4` otherwise). Transformers.js
+would otherwise pick `fp32`, which makes ONNX Runtime fail session creation with an allocation error
+(`std::bad_alloc`) for anything but tiny models. Override with `dtype` when your model does not
+publish that variant:
+
+```ts
+import { OnnxRuntimeWebProvider, createTransformersJsRuntime } from "@independo/inderun-web/onnx";
+
+const provider = new OnnxRuntimeWebProvider({
+  modelPackage,
+  runtime: createTransformersJsRuntime({ dtype: "q8", device: "wasm" })
+});
+```
+
+The default runtime targets models that load through the Transformers.js `text-generation` pipeline
+— for example `onnx-community/gemma-3-1b-it-ONNX`. Multimodal exports split across separate
+encoder/decoder graphs need `AutoProcessor` plus a model-specific class and should implement the
+runtime seam instead — see [Custom runtimes](#custom-runtimes).
+
+### Runtime dependency
+
+The default runtime uses [Transformers.js](https://www.npmjs.com/package/@huggingface/transformers),
+which runs ONNX models on `onnxruntime-web` and owns the generation loop (ONNX Runtime GenAI has no
+browser build). It is an optional dependency that IndeRun does not bundle — install it yourself:
+
+```sh
+pnpm add @huggingface/transformers
+```
+
+If the package is present but fails to initialize, the provider reports itself unavailable and
+routing produces an explainable `capability_unavailable` rejection instead of throwing. Bundlers do
+need to resolve the specifier, so an app that imports `@independo/inderun-web/onnx` without
+installing Transformers.js should pass its own runtime (or a `load` override) — see
+[Custom runtimes](#custom-runtimes). WASM threads additionally require
+cross-origin isolation (`Cross-Origin-Opener-Policy: same-origin`,
+`Cross-Origin-Embedder-Policy: require-corp`) on whatever serves your app.
+
+### Supported model sources
+
+| `source.sourceType` | Web         |
+| ------------------- | ----------- |
+| `registry`          | Supported (hub model id in `source.ref`) |
+| `bundled`           | Supported (assets served by your app) |
+| `app_managed`       | Supported (assets served by your app) |
+| `programmatic`      | Supported (requires `createGenerator`) |
+| `remote`            | Deferred — download yourself, then declare the files |
+| `filesystem`        | Unsupported — browsers cannot read arbitrary local paths |
+
+### Errors
+
+| Condition                                                   | `errorClass`         |
+| ----------------------------------------------------------- | -------------------- |
+| Capability gate fails pre-attempt, model missing/incompatible | `CapabilityMismatch` |
+| Runtime initialization failure, resource exhaustion          | `Unavailable`        |
+| Generation exceeded its timeout budget                       | `Timeout`            |
+| Malformed/empty model output, unexpected runtime failure     | `Internal`           |
+
+A purely local runtime never produces `AuthError`, `RateLimited`, or `Offline`.
+
+### Custom runtimes
+
+Swap the execution backend without touching provider semantics by implementing
+`OnnxTextGenerationRuntime`:
+
+```ts
+import {
+  OnnxRuntimeWebProvider,
+  OnnxRuntimeError,
+  createFixtureOnnxRuntime,
+  type OnnxTextGenerationRuntime
+} from "@independo/inderun-web/onnx";
+
+const runtime: OnnxTextGenerationRuntime = {
+  async prepare(modelPackage) {
+    return { available: true };
+  },
+  async generate({ messages, generation }, signal) {
+    // Throw OnnxRuntimeError("capability" | "unavailable" | "timeout" | "internal", …)
+    // to steer IndeRun error normalization.
+    return { text: "…" };
+  }
+};
+```
+
+`createFixtureOnnxRuntime()` provides a deterministic in-memory runtime for tests and offline demos.
+
 ## Commands
 
 ```sh

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/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,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAuB,KAAK,gBAAgB,EAAwB,MAAM,gBAAgB,CAAC;AAElG;;;;GAIG;AACH,qBAAa,OAAO;IAWhB,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;CAoIrD"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/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,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAuB,KAAK,gBAAgB,EAAwB,MAAM,gBAAgB,CAAC;AAElG;;;;GAIG;AACH,qBAAa,OAAO;IAWhB,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;CAsIrD"}

package/dist/engine.js

@@ -101,7 +101,9 @@ export class IndeRun {
                     taskKind: request.task.kind,
                     explanation: routeSelection.explanation,
                     constraints: request.constraints ?? null,
-                    preferences: request.preferences ?? null
+                    preferences: request.preferences ?? null,
+                    plannerSource: routeSelection.plannerSource,
+                    plannerUnavailableReason: routeSelection.plannerUnavailableReason ?? null
                 }
             });
             // 3. Execute the run task using the planned provider chain

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { type ConnectivityService, type DeviceConstraintsService, type SecureSto
 export { type ProviderDescriptor, type ProviderDynamicCapabilities, type RunContext, type ProviderAdapter } from "./provider.js";
 export { ProviderRegistry } from "./registry.js";
 export { type RouteSelection, Router } from "./router.js";
-export { type RoutePlanner, type SharedPlannerInput, type SharedPlannerRoutePlan, WasmRoutePlanner } from "./route-planner.js";
+export { type RoutePlanner, type PlannerOutcome, type WasmUnavailableReason, type SharedPlannerInput, type SharedPlannerRoutePlan, WasmRoutePlanner } from "./route-planner.js";
 export { type IndeRunExceptionParams, IndeRunException, createCapabilityMismatch, createOffline, createAuthError, createRateLimited, createTimeout, createUnavailable, createInternal, toIndeRunException } from "./errors.js";
 export { IndeRun } from "./engine.js";
 export { type TelemetryEventType, type TelemetryEvent, type TelemetryService, NoOpTelemetryService } from "./telemetry.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,oBAAoB,EACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,gCAAgC,EACrC,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,oBAAoB,EACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,gCAAgC,EACrC,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC"}

package/dist/onnx-provider.d.ts

@@ -0,0 +1,78 @@
+import { type ModelPackage, type ModelSourceType, type TaskRequest, type TaskResult } from "@independo/inderun-contracts";
+import type { HostServices } from "./host.js";
+import { type OnnxTextGenerationRuntime } from "./onnx-runtime.js";
+import type { ProviderAdapter, ProviderDescriptor, ProviderDynamicCapabilities, RunContext } from "./provider.js";
+/** Default provider id of the Web member of the ONNX Runtime provider family. */
+export declare const DEFAULT_ONNX_WEB_PROVIDER_ID = "local.onnx.genai.web";
+/**
+ * Model source types the Web member of the ONNX Runtime provider family can honor.
+ *
+ * `filesystem` is unsupported because browsers do not expose arbitrary local paths, and `remote`
+ * is deferred: hosts download model files themselves and then supply them as `bundled`,
+ * `app_managed`, or `programmatic`.
+ */
+export declare const SUPPORTED_WEB_MODEL_SOURCE_TYPES: readonly ModelSourceType[];
+/**
+ * Configuration for the Web ONNX Runtime provider.
+ */
+export interface OnnxProviderOptions {
+    /**
+     * Provider id exposed in telemetry and routing explanations.
+     */
+    id?: string;
+    /**
+     * Provider-neutral bootstrap metadata describing the developer-supplied model.
+     */
+    modelPackage: ModelPackage;
+    /**
+     * Runtime implementation used to execute generation. Defaults to the Transformers.js-backed
+     * runtime; applications can inject their own implementation of the seam.
+     */
+    runtime?: OnnxTextGenerationRuntime;
+    /**
+     * Optional generation timeout in milliseconds. A request-level `constraints.timeoutMs` wins.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Local provider adapter that executes Mode-1 text-to-text requests with a developer-supplied ONNX
+ * model in the browser.
+ *
+ * The adapter owns the IndeRun-facing contract (descriptor, capability checks, error taxonomy) and
+ * delegates execution to an injectable {@link OnnxTextGenerationRuntime}. ONNX Runtime execution
+ * backends (WASM, WebGPU, WebNN) stay behind that seam and are never public routing concepts.
+ */
+export declare class OnnxRuntimeWebProvider implements ProviderAdapter {
+    private readonly options;
+    private readonly id;
+    private readonly modelPackage;
+    private readonly runtime;
+    /**
+     * Creates a Web ONNX Runtime provider.
+     * @param options - Model package plus optional id, runtime, and timeout overrides.
+     */
+    constructor(options: OnnxProviderOptions);
+    /**
+     * Returns static metadata used by the router for deterministic provider selection.
+     */
+    describe(): ProviderDescriptor;
+    /**
+     * Reports dynamic provider availability for the current host.
+     *
+     * Every failure below is provider-internal detail: the shared route planner flattens it into a
+     * single `capability_unavailable` rejection carrying the returned reason.
+     *
+     * @param _host - Host services available to the engine (unused; ONNX runs in-process).
+     */
+    capabilities(_host: HostServices): Promise<ProviderDynamicCapabilities>;
+    /**
+     * Executes a normalized text-to-text task on the developer-supplied local ONNX model.
+     * @param request - Canonical IndeRun task request.
+     * @param context - Engine execution context containing run id and host services.
+     * @returns Normalized IndeRun task result.
+     * @throws IndeRunException mapped to the standard error taxonomy.
+     */
+    run(request: TaskRequest, context: RunContext): Promise<TaskResult>;
+    private mapRuntimeError;
+}
+//# sourceMappingURL=onnx-provider.d.ts.map

package/dist/onnx-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onnx-provider.d.ts","sourceRoot":"","sources":["../src/onnx-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,8BAA8B,CAAC;AAStC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAIL,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,2BAA2B,EAC3B,UAAU,EACX,MAAM,eAAe,CAAC;AAEvB,iFAAiF;AACjF,eAAO,MAAM,4BAA4B,yBAAyB,CAAC;AAKnE;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,EAAE,SAAS,eAAe,EAKtE,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,YAAY,EAAE,YAAY,CAAC;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAShD,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD;;;OAGG;gBAC0B,OAAO,EAAE,mBAAmB;IAMzD;;OAEG;IACH,QAAQ,IAAI,kBAAkB;IAsB9B;;;;;;;OAOG;IACG,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAoC7E;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAoEzE,OAAO,CAAC,eAAe;CA2BxB"}

package/dist/onnx-provider.js

@@ -0,0 +1,217 @@
+import { getModelPackageValidationIssues } from "@independo/inderun-contracts";
+import { createCapabilityMismatch, createInternal, createTimeout, createUnavailable, toIndeRunException } from "./errors.js";
+import { OnnxRuntimeError } from "./onnx-runtime.js";
+import { createTransformersJsRuntime } from "./onnx-transformers-runtime.js";
+/** Default provider id of the Web member of the ONNX Runtime provider family. */
+export const DEFAULT_ONNX_WEB_PROVIDER_ID = "local.onnx.genai.web";
+/** Task kind this provider implements in Milestone 2 (Mode 1 only). */
+const TEXT_TO_TEXT = "text_to_text";
+/**
+ * Model source types the Web member of the ONNX Runtime provider family can honor.
+ *
+ * `filesystem` is unsupported because browsers do not expose arbitrary local paths, and `remote`
+ * is deferred: hosts download model files themselves and then supply them as `bundled`,
+ * `app_managed`, or `programmatic`.
+ */
+export const SUPPORTED_WEB_MODEL_SOURCE_TYPES = [
+    "registry",
+    "bundled",
+    "programmatic",
+    "app_managed"
+];
+/**
+ * Local provider adapter that executes Mode-1 text-to-text requests with a developer-supplied ONNX
+ * model in the browser.
+ *
+ * The adapter owns the IndeRun-facing contract (descriptor, capability checks, error taxonomy) and
+ * delegates execution to an injectable {@link OnnxTextGenerationRuntime}. ONNX Runtime execution
+ * backends (WASM, WebGPU, WebNN) stay behind that seam and are never public routing concepts.
+ */
+export class OnnxRuntimeWebProvider {
+    options;
+    id;
+    modelPackage;
+    runtime;
+    /**
+     * Creates a Web ONNX Runtime provider.
+     * @param options - Model package plus optional id, runtime, and timeout overrides.
+     */
+    constructor(options) {
+        this.options = options;
+        this.id = options.id ?? DEFAULT_ONNX_WEB_PROVIDER_ID;
+        this.modelPackage = options.modelPackage;
+        this.runtime = options.runtime ?? createTransformersJsRuntime();
+    }
+    /**
+     * Returns static metadata used by the router for deterministic provider selection.
+     */
+    describe() {
+        return {
+            id: this.id,
+            type: "local",
+            transport: "in_process",
+            supports: {
+                run: true,
+                streaming: false,
+                realtime: false,
+                tools: false,
+                reasoningEvents: false,
+                structuredOutput: false,
+                multimodal: false
+            },
+            cancel: "soft",
+            tasks: getDeclaredTasks(this.modelPackage),
+            privacy: {
+                dataLeavesDevice: false
+            }
+        };
+    }
+    /**
+     * Reports dynamic provider availability for the current host.
+     *
+     * Every failure below is provider-internal detail: the shared route planner flattens it into a
+     * single `capability_unavailable` rejection carrying the returned reason.
+     *
+     * @param _host - Host services available to the engine (unused; ONNX runs in-process).
+     */
+    async capabilities(_host) {
+        const issues = getModelPackageValidationIssues(this.modelPackage);
+        if (issues.length > 0) {
+            const summary = issues.map((issue) => `${issue.path} ${issue.message}`).join("; ");
+            return { available: false, reason: `model package malformed: ${summary}` };
+        }
+        const sourceType = this.modelPackage.source?.sourceType;
+        if (sourceType !== undefined && !SUPPORTED_WEB_MODEL_SOURCE_TYPES.includes(sourceType)) {
+            return {
+                available: false,
+                reason: sourceType === "filesystem"
+                    ? "model source unavailable: 'filesystem' model sources are unsupported on Web because browsers cannot read arbitrary local paths."
+                    : `model source unavailable: '${sourceType}' model sources are deferred on Web; supply model files as ${SUPPORTED_WEB_MODEL_SOURCE_TYPES.join(", ")}.`
+            };
+        }
+        const platforms = this.modelPackage.runtime?.platforms;
+        if (Array.isArray(platforms) && platforms.length > 0 && !platforms.includes("web")) {
+            return {
+                available: false,
+                reason: `platform unsupported: the model package targets ${platforms.join(", ")} and does not list 'web'.`
+            };
+        }
+        if (!getDeclaredTasks(this.modelPackage).includes(TEXT_TO_TEXT)) {
+            return {
+                available: false,
+                reason: `unsupported task: the model package declares ${getDeclaredTasks(this.modelPackage).join(", ")} and does not support '${TEXT_TO_TEXT}'.`
+            };
+        }
+        return this.runtime.prepare(this.modelPackage);
+    }
+    /**
+     * Executes a normalized text-to-text task on the developer-supplied local ONNX model.
+     * @param request - Canonical IndeRun task request.
+     * @param context - Engine execution context containing run id and host services.
+     * @returns Normalized IndeRun task result.
+     * @throws IndeRunException mapped to the standard error taxonomy.
+     */
+    async run(request, context) {
+        const availability = await this.capabilities(context.hostServices);
+        if (!availability.available) {
+            throw createCapabilityMismatch(availability.reason ?? "ONNX Runtime Web provider is unavailable on this host.", { providerId: this.id, runId: context.runId });
+        }
+        const messages = createMessages(request);
+        if (messages.length === 0) {
+            throw createInternal("ONNX Runtime Web provider requires a prompt or messages.", {
+                providerId: this.id,
+                runId: context.runId
+            });
+        }
+        const timeoutMs = request.constraints?.timeoutMs ?? this.options.timeoutMs;
+        const controller = new AbortController();
+        const timer = timeoutMs !== undefined && timeoutMs > 0
+            ? setTimeout(() => controller.abort(), timeoutMs)
+            : undefined;
+        let output;
+        try {
+            output = await this.runtime.generate({
+                modelPackage: this.modelPackage,
+                messages,
+                ...(request.generation !== undefined ? { generation: request.generation } : {})
+            }, controller.signal);
+        }
+        catch (err) {
+            throw this.mapRuntimeError(err, context);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        if (typeof output.text !== "string" || output.text.length === 0) {
+            throw createInternal("ONNX Runtime Web provider returned no text output.", {
+                providerId: this.id,
+                runId: context.runId
+            });
+        }
+        const result = {
+            schemaVersion: "1.0",
+            runId: context.runId,
+            output: {
+                type: "text",
+                text: output.text
+            },
+            finishReason: output.finishReason ?? "stop",
+            telemetry: {
+                providerUsed: this.id,
+                totalMs: 0
+            }
+        };
+        if (output.usage) {
+            result.usage = output.usage;
+        }
+        return result;
+    }
+    mapRuntimeError(error, context) {
+        const extra = { providerId: this.id, runId: context.runId };
+        if (error instanceof OnnxRuntimeError) {
+            const details = error.originalError !== undefined
+                ? { details: { originalError: getErrorSummary(error.originalError) } }
+                : {};
+            switch (error.kind) {
+                case "capability":
+                    return createCapabilityMismatch(error.message, { ...extra, ...details });
+                case "unavailable":
+                    return createUnavailable(error.message, { ...extra, ...details });
+                case "timeout":
+                    return createTimeout(error.message, { ...extra, ...details });
+                default:
+                    return createInternal(error.message, { ...extra, ...details });
+            }
+        }
+        if (isAbortError(error)) {
+            return createTimeout("ONNX Runtime Web generation timed out.", extra);
+        }
+        return toIndeRunException(error, extra);
+    }
+}
+function getDeclaredTasks(modelPackage) {
+    const tasks = modelPackage.tasks;
+    return Array.isArray(tasks) && tasks.length > 0 ? tasks : [TEXT_TO_TEXT];
+}
+function createMessages(request) {
+    if (request.messages && request.messages.length > 0) {
+        return request.messages.map((message) => ({
+            role: message.role,
+            content: message.content
+        }));
+    }
+    const prompt = request.prompt;
+    return prompt !== undefined && prompt.length > 0 ? [{ role: "user", content: prompt }] : [];
+}
+function isAbortError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.name === "AbortError");
+}
+function getErrorSummary(error) {
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message, stack: error.stack };
+    }
+    return { message: String(error) };
+}

package/dist/onnx-runtime.d.ts

@@ -0,0 +1,110 @@
+import type { ModelPackage, TaskRequest, TaskResult } from "@independo/inderun-contracts";
+/**
+ * Availability snapshot reported by an ONNX text generation runtime.
+ *
+ * The `reason` string uses the provider-internal capability vocabulary documented in
+ * `docs/architecture/onnx-runtime-provider-family.md`. It is not a public enum: the provider
+ * flattens every failure into a single `capability_unavailable` route rejection and carries the
+ * reason as human-readable text.
+ */
+export interface OnnxRuntimeAvailability {
+    /** Whether the runtime can execute the given model package on this host right now. */
+    available: boolean;
+    /** Human-readable detail describing why the runtime is unavailable. */
+    reason?: string;
+}
+/**
+ * Normalized conversation turn handed to an ONNX text generation runtime.
+ */
+export interface OnnxGenerationMessage {
+    /** The role of the author of this turn. */
+    role: "system" | "user" | "assistant";
+    /** Plain-text content of this turn. */
+    content: string;
+}
+/**
+ * Normalized generation request handed to an ONNX text generation runtime.
+ */
+export interface OnnxGenerationInput {
+    /** The model package the provider was configured with. */
+    modelPackage: ModelPackage;
+    /** Conversation turns, normalized from `prompt` or `messages` by the provider. */
+    messages: OnnxGenerationMessage[];
+    /** Optional generation controls copied from the task request. */
+    generation?: NonNullable<TaskRequest["generation"]>;
+}
+/**
+ * Normalized generation result returned by an ONNX text generation runtime.
+ */
+export interface OnnxGenerationOutput {
+    /** The generated text. */
+    text: string;
+    /** Optional normalized finish reason; the provider defaults to `stop`. */
+    finishReason?: TaskResult["finishReason"];
+    /** Optional token accounting, when the runtime reports it. */
+    usage?: TaskResult["usage"];
+}
+/**
+ * Failure category a runtime can signal so the provider maps it onto the IndeRun error taxonomy.
+ *
+ * - `capability`: model or runtime cannot serve this request (`CapabilityMismatch`).
+ * - `unavailable`: runtime initialization failure or resource exhaustion (`Unavailable`).
+ * - `timeout`: generation exceeded its budget or was aborted (`Timeout`).
+ * - `internal`: unexpected runtime failure (`Internal`).
+ */
+export type OnnxRuntimeErrorKind = "capability" | "unavailable" | "timeout" | "internal";
+/**
+ * Error type ONNX runtime implementations throw to steer IndeRun error normalization.
+ *
+ * Anything else thrown by a runtime is normalized to `Internal`.
+ */
+export declare class OnnxRuntimeError extends Error {
+    /** Failure category used by the provider to select an IndeRun error class. */
+    readonly kind: OnnxRuntimeErrorKind;
+    /** Optional underlying error captured for telemetry details. */
+    readonly originalError?: unknown;
+    constructor(kind: OnnxRuntimeErrorKind, message: string, originalError?: unknown);
+}
+/**
+ * Injectable seam between the IndeRun ONNX Web provider and the actual on-device runtime.
+ *
+ * IndeRun ships a Transformers.js-backed implementation as the default and a deterministic
+ * fixture for tests, but applications can supply their own implementation (for example a
+ * hand-rolled `onnxruntime-web` pipeline) without touching the provider.
+ */
+export interface OnnxTextGenerationRuntime {
+    /**
+     * Checks runtime package availability, execution backend availability, and model readiness.
+     * Implementations must resolve with an availability snapshot rather than throwing.
+     */
+    prepare(modelPackage: ModelPackage): Promise<OnnxRuntimeAvailability>;
+    /**
+     * Runs one Mode-1 generation. Implementations should honor `signal` where the underlying
+     * runtime allows it; ONNX inference is not hard-interruptible, so cancellation is best effort.
+     */
+    generate(input: OnnxGenerationInput, signal?: AbortSignal): Promise<OnnxGenerationOutput>;
+}
+/**
+ * Configuration for the deterministic fixture runtime.
+ */
+export interface FixtureOnnxRuntimeOptions {
+    /** Availability snapshot returned by `prepare`. Defaults to `{ available: true }`. */
+    availability?: OnnxRuntimeAvailability;
+    /** Text or full output produced by `generate`. Defaults to a deterministic echo. */
+    respond?: (input: OnnxGenerationInput) => string | OnnxGenerationOutput;
+    /** Error thrown by `generate` instead of producing output. */
+    failWith?: unknown;
+    /** Artificial generation delay in milliseconds, used to exercise timeouts. */
+    delayMs?: number;
+}
+/**
+ * Creates a deterministic in-memory ONNX runtime.
+ *
+ * This is the test seam mandated by the ONNX Runtime provider family specification: it proves the
+ * model package contract, capability checks, routing, and error normalization without depending on
+ * a real ONNX runtime, and it lets demos exercise the on-device route offline.
+ *
+ * @param options - Scripted availability, response, failure, and delay behavior.
+ */
+export declare function createFixtureOnnxRuntime(options?: FixtureOnnxRuntimeOptions): OnnxTextGenerationRuntime;
+//# sourceMappingURL=onnx-runtime.d.ts.map

package/dist/onnx-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onnx-runtime.d.ts","sourceRoot":"","sources":["../src/onnx-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE1F;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,sFAAsF;IACtF,SAAS,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,YAAY,EAAE,YAAY,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,iEAAiE;IACjE,UAAU,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,YAAY,CAAC,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC;IAC1C,8DAA8D;IAC9D,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAEzF;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;gBAErB,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO;CAQjF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,OAAO,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACtE;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC3F;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,sFAAsF;IACtF,YAAY,CAAC,EAAE,uBAAuB,CAAC;IACvC,oFAAoF;IACpF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,MAAM,GAAG,oBAAoB,CAAC;IACxE,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,yBAAyB,CA4B3B"}

package/dist/onnx-runtime.js

@@ -0,0 +1,76 @@
+/**
+ * Error type ONNX runtime implementations throw to steer IndeRun error normalization.
+ *
+ * Anything else thrown by a runtime is normalized to `Internal`.
+ */
+export class OnnxRuntimeError extends Error {
+    /** Failure category used by the provider to select an IndeRun error class. */
+    kind;
+    /** Optional underlying error captured for telemetry details. */
+    originalError;
+    constructor(kind, message, originalError) {
+        super(message);
+        this.name = "OnnxRuntimeError";
+        this.kind = kind;
+        if (originalError !== undefined)
+            this.originalError = originalError;
+        Object.setPrototypeOf(this, OnnxRuntimeError.prototype);
+    }
+}
+/**
+ * Creates a deterministic in-memory ONNX runtime.
+ *
+ * This is the test seam mandated by the ONNX Runtime provider family specification: it proves the
+ * model package contract, capability checks, routing, and error normalization without depending on
+ * a real ONNX runtime, and it lets demos exercise the on-device route offline.
+ *
+ * @param options - Scripted availability, response, failure, and delay behavior.
+ */
+export function createFixtureOnnxRuntime(options = {}) {
+    const availability = options.availability ?? { available: true };
+    return {
+        async prepare() {
+            return availability;
+        },
+        async generate(input, signal) {
+            if (options.delayMs !== undefined && options.delayMs > 0) {
+                await delay(options.delayMs, signal);
+            }
+            throwIfAborted(signal);
+            if (options.failWith !== undefined) {
+                throw options.failWith;
+            }
+            const response = options.respond
+                ? options.respond(input)
+                : createFixtureText(input.modelPackage, input.messages);
+            return typeof response === "string" ? { text: response } : response;
+        }
+    };
+}
+function createFixtureText(modelPackage, messages) {
+    const lastUserMessage = [...messages].reverse().find((message) => message.role === "user");
+    const prompt = lastUserMessage?.content ?? "";
+    return `[fixture:${modelPackage.id}] ${prompt}`;
+}
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(new OnnxRuntimeError("timeout", "Fixture ONNX generation was aborted."));
+        }
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new OnnxRuntimeError("timeout", "Fixture ONNX generation was aborted.");
+    }
+}