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

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/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.");
+    }
+}

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

@@ -0,0 +1,72 @@
+import type { ModelPackage } from "@independo/inderun-contracts";
+import { type OnnxTextGenerationRuntime } from "./onnx-runtime.js";
+/**
+ * Structural view of the `@huggingface/transformers` entry points this runtime uses.
+ *
+ * The dependency is optional, so the module is typed structurally instead of imported for types.
+ */
+export interface TransformersModule {
+    /** Builds a task pipeline, downloading or loading model assets as needed. */
+    pipeline: (task: string, model?: string, options?: Record<string, unknown>) => Promise<TransformersTextGenerator>;
+    /** Global Transformers.js environment used to point the loader at local model assets. */
+    env?: Record<string, unknown>;
+}
+/**
+ * Structural view of a Transformers.js `text-generation` pipeline.
+ */
+export type TransformersTextGenerator = (input: unknown, options?: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Configuration for the Transformers.js-backed ONNX runtime.
+ */
+export interface TransformersJsRuntimeOptions {
+    /**
+     * Overrides how the `@huggingface/transformers` module is loaded. Tests inject a fake module;
+     * production uses a lazy dynamic import so the dependency stays optional.
+     */
+    load?: () => Promise<TransformersModule>;
+    /**
+     * Execution backend passed to Transformers.js. Defaults to `webgpu` when `navigator.gpu`
+     * exists and `wasm` otherwise. This is an ONNX Runtime execution backend, not an IndeRun
+     * routing concept.
+     */
+    device?: string;
+    /**
+     * Weight quantization passed to Transformers.js (for example `q4`, `q4f16`, `q8`, `fp16`,
+     * `fp32`).
+     *
+     * Defaults to a quantized variant (`q4f16` on WebGPU, `q4` otherwise) because Transformers.js
+     * would otherwise load full `fp32` weights, which exhausts browser memory for all but the
+     * smallest models. Set explicitly when the model does not publish the default variant.
+     */
+    dtype?: string;
+    /** Base path or URL for locally served model assets (`bundled` / `app_managed` sources). */
+    localModelPath?: string;
+    /** Extra options merged into the Transformers.js `pipeline()` call. */
+    pipelineOptions?: Record<string, unknown>;
+    /**
+     * Supplies a pre-built generator instead of letting this runtime construct one. Required for
+     * `programmatic` model sources, where the application owns model resolution.
+     */
+    createGenerator?: (context: {
+        modelPackage: ModelPackage;
+        module: TransformersModule;
+        device: string;
+    }) => Promise<TransformersTextGenerator>;
+}
+/**
+ * Creates the default Web ONNX runtime, backed by Transformers.js (which runs ONNX models through
+ * `onnxruntime-web`).
+ *
+ * ONNX Runtime GenAI has no browser build, so Transformers.js fills the generative-loop role
+ * (tokenization, sampling, KV cache) behind the `OnnxTextGenerationRuntime` seam. Applications that
+ * need a different runtime implement the seam themselves and pass it to the provider.
+ *
+ * `@huggingface/transformers` is an optional dependency the application installs: when it is absent
+ * the runtime
+ * reports itself unavailable instead of throwing, so routing degrades to an explainable
+ * `capability_unavailable` rejection.
+ *
+ * @param options - Loader, backend, and model-resolution overrides.
+ */
+export declare function createTransformersJsRuntime(options?: TransformersJsRuntimeOptions): OnnxTextGenerationRuntime;
+//# sourceMappingURL=onnx-transformers-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"onnx-transformers-runtime.d.ts","sourceRoot":"","sources":["../src/onnx-transformers-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,QAAQ,EAAE,CACR,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACxC,yFAAyF;IACzF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACtC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACzC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE;QAC1B,YAAY,EAAE,YAAY,CAAC;QAC3B,MAAM,EAAE,kBAAkB,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAC1C;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,GAAE,4BAAiC,GACzC,yBAAyB,CAyI3B"}

package/dist/onnx-transformers-runtime.js

@@ -0,0 +1,210 @@
+import { OnnxRuntimeError } from "./onnx-runtime.js";
+const TEXT_GENERATION_TASK = "text-generation";
+/**
+ * Creates the default Web ONNX runtime, backed by Transformers.js (which runs ONNX models through
+ * `onnxruntime-web`).
+ *
+ * ONNX Runtime GenAI has no browser build, so Transformers.js fills the generative-loop role
+ * (tokenization, sampling, KV cache) behind the `OnnxTextGenerationRuntime` seam. Applications that
+ * need a different runtime implement the seam themselves and pass it to the provider.
+ *
+ * `@huggingface/transformers` is an optional dependency the application installs: when it is absent
+ * the runtime
+ * reports itself unavailable instead of throwing, so routing degrades to an explainable
+ * `capability_unavailable` rejection.
+ *
+ * @param options - Loader, backend, and model-resolution overrides.
+ */
+export function createTransformersJsRuntime(options = {}) {
+    let modulePromise;
+    let generatorPromise;
+    async function loadModule() {
+        modulePromise ??= (options.load ?? loadTransformersModule)();
+        return modulePromise;
+    }
+    async function loadGenerator(modelPackage) {
+        generatorPromise ??= (async () => {
+            const module = await loadModule();
+            const device = resolveDevice(options.device);
+            if (options.createGenerator) {
+                return options.createGenerator({ modelPackage, module, device });
+            }
+            const modelRef = getModelRef(modelPackage);
+            if (!modelRef) {
+                throw new OnnxRuntimeError("capability", "model source unavailable: the model package does not declare source.ref.");
+            }
+            applyEnvironment(module, modelPackage, options.localModelPath);
+            const pipelineOptions = {
+                device,
+                dtype: options.dtype ?? defaultDtype(device),
+                ...(options.pipelineOptions ?? {})
+            };
+            return module.pipeline(TEXT_GENERATION_TASK, modelRef, pipelineOptions);
+        })();
+        return generatorPromise;
+    }
+    return {
+        async prepare(modelPackage) {
+            let module;
+            try {
+                module = await loadModule();
+            }
+            catch (err) {
+                modulePromise = undefined;
+                return {
+                    available: false,
+                    reason: `runtime package unavailable: install the optional dependency @huggingface/transformers (${getErrorMessage(err)}).`
+                };
+            }
+            if (typeof module.pipeline !== "function") {
+                return {
+                    available: false,
+                    reason: "runtime initialization failed: @huggingface/transformers did not expose pipeline()."
+                };
+            }
+            if (modelPackage.format !== "onnx") {
+                return {
+                    available: false,
+                    reason: `unsupported model format: the Transformers.js runtime consumes ONNX weights, received '${modelPackage.format}'.`
+                };
+            }
+            const sourceType = modelPackage.source?.sourceType;
+            if (sourceType === "programmatic" && !options.createGenerator) {
+                return {
+                    available: false,
+                    reason: "model source unavailable: programmatic model packages require a createGenerator option."
+                };
+            }
+            if (!options.createGenerator && !getModelRef(modelPackage)) {
+                return {
+                    available: false,
+                    reason: "model source unavailable: the model package does not declare source.ref."
+                };
+            }
+            return { available: true };
+        },
+        async generate(input, signal) {
+            let generator;
+            try {
+                generator = await loadGenerator(input.modelPackage);
+            }
+            catch (err) {
+                generatorPromise = undefined;
+                if (err instanceof OnnxRuntimeError)
+                    throw err;
+                if (isResourceExhaustion(err)) {
+                    throw new OnnxRuntimeError("unavailable", `insufficient memory to load the model: ${getErrorMessage(err)}. Try a smaller model or a more aggressive dtype (for example 'q4').`, err);
+                }
+                throw new OnnxRuntimeError("capability", `model files missing or unreadable: ${getErrorMessage(err)}`, err);
+            }
+            if (signal?.aborted) {
+                throw new OnnxRuntimeError("timeout", "ONNX generation was aborted before it started.");
+            }
+            let raw;
+            try {
+                raw = await generator(input.messages, createGenerationOptions(input, signal));
+            }
+            catch (err) {
+                throw new OnnxRuntimeError("internal", `ONNX generation failed: ${getErrorMessage(err)}`, err);
+            }
+            const text = extractGeneratedText(raw);
+            if (text === undefined) {
+                throw new OnnxRuntimeError("internal", "model output malformed: the Transformers.js pipeline returned no text.");
+            }
+            return { text };
+        }
+    };
+}
+async function loadTransformersModule() {
+    // The specifier stays a literal so bundlers and dev servers resolve the bare package name; the
+    // `as string` cast keeps TypeScript from requiring the optional dependency's types here. Apps that
+    // do not install Transformers.js should pass their own `load` (or a different runtime) rather than
+    // relying on this default, which their bundler will fail to resolve.
+    return (await import("@huggingface/transformers"));
+}
+/**
+ * Browser-viable weight variant. Transformers.js defaults to `fp32`, which makes ONNX Runtime
+ * allocate the full-precision model and fail session creation with an allocation error for
+ * anything but tiny models.
+ */
+function defaultDtype(device) {
+    return device === "webgpu" ? "q4f16" : "q4";
+}
+function resolveDevice(configured) {
+    if (configured !== undefined)
+        return configured;
+    const gpu = globalThis.navigator?.gpu;
+    return gpu ? "webgpu" : "wasm";
+}
+function getModelRef(modelPackage) {
+    const ref = modelPackage.source?.ref;
+    return typeof ref === "string" && ref.length > 0 ? ref : undefined;
+}
+function applyEnvironment(module, modelPackage, localModelPath) {
+    const env = module.env;
+    if (!env)
+        return;
+    const sourceType = modelPackage.source?.sourceType;
+    if (sourceType === "bundled" || sourceType === "app_managed") {
+        env.allowLocalModels = true;
+        env.allowRemoteModels = false;
+        if (localModelPath !== undefined) {
+            env.localModelPath = localModelPath;
+        }
+    }
+}
+function createGenerationOptions(input, signal) {
+    const generation = input.generation;
+    const generationOptions = {};
+    if (generation?.maxOutputTokens !== undefined) {
+        generationOptions.max_new_tokens = generation.maxOutputTokens;
+    }
+    if (generation?.temperature !== undefined) {
+        generationOptions.temperature = generation.temperature;
+        generationOptions.do_sample = generation.temperature > 0;
+    }
+    if (generation?.topP !== undefined) {
+        generationOptions.top_p = generation.topP;
+    }
+    if (generation?.stop !== undefined && generation.stop.length > 0) {
+        generationOptions.stop_strings = generation.stop;
+    }
+    if (signal !== undefined) {
+        generationOptions.signal = signal;
+    }
+    return generationOptions;
+}
+function extractGeneratedText(raw) {
+    const first = Array.isArray(raw) ? raw[0] : raw;
+    if (!isRecord(first)) {
+        return typeof first === "string" ? first : undefined;
+    }
+    const generated = first.generated_text;
+    if (typeof generated === "string") {
+        return generated;
+    }
+    if (Array.isArray(generated)) {
+        const last = generated[generated.length - 1];
+        if (isRecord(last) && typeof last.content === "string") {
+            return last.content;
+        }
+    }
+    return undefined;
+}
+/**
+ * Detects out-of-memory failures surfaced by ONNX Runtime session creation, which arrive as
+ * allocation errors from the WASM/native layer rather than as typed errors.
+ */
+function isResourceExhaustion(error) {
+    const message = getErrorMessage(error).toLowerCase();
+    return (message.includes("bad_alloc") ||
+        message.includes("out of memory") ||
+        message.includes("failed to allocate") ||
+        message.includes("allocation failed"));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/onnx.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Provider-specific entry point for the Web member of the ONNX Runtime provider family.
+ *
+ * Kept out of the unified SDK index (`@independo/inderun-web`) so the top-level
+ * surface stays provider-agnostic. Import from `@independo/inderun-web/onnx`
+ * when registering the adapter manually or when implementing a custom
+ * `OnnxTextGenerationRuntime`; most browser apps should pass `onnx` to
+ * `createIndeRunWeb` from the main entry point instead.
+ */
+export { OnnxRuntimeWebProvider, DEFAULT_ONNX_WEB_PROVIDER_ID, SUPPORTED_WEB_MODEL_SOURCE_TYPES, type OnnxProviderOptions } from "./onnx-provider.js";
+export { OnnxRuntimeError, createFixtureOnnxRuntime, type FixtureOnnxRuntimeOptions, type OnnxGenerationInput, type OnnxGenerationMessage, type OnnxGenerationOutput, type OnnxRuntimeAvailability, type OnnxRuntimeErrorKind, type OnnxTextGenerationRuntime } from "./onnx-runtime.js";
+export { createTransformersJsRuntime, type TransformersJsRuntimeOptions, type TransformersModule, type TransformersTextGenerator } from "./onnx-transformers-runtime.js";
+//# sourceMappingURL=onnx.d.ts.map

package/dist/onnx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onnx.d.ts","sourceRoot":"","sources":["../src/onnx.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,gCAAgC,EAChC,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,2BAA2B,EAC3B,KAAK,4BAA4B,EACjC,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC/B,MAAM,gCAAgC,CAAC"}

package/dist/onnx.js

@@ -0,0 +1,12 @@
+/**
+ * Provider-specific entry point for the Web member of the ONNX Runtime provider family.
+ *
+ * Kept out of the unified SDK index (`@independo/inderun-web`) so the top-level
+ * surface stays provider-agnostic. Import from `@independo/inderun-web/onnx`
+ * when registering the adapter manually or when implementing a custom
+ * `OnnxTextGenerationRuntime`; most browser apps should pass `onnx` to
+ * `createIndeRunWeb` from the main entry point instead.
+ */
+export { OnnxRuntimeWebProvider, DEFAULT_ONNX_WEB_PROVIDER_ID, SUPPORTED_WEB_MODEL_SOURCE_TYPES } from "./onnx-provider.js";
+export { OnnxRuntimeError, createFixtureOnnxRuntime } from "./onnx-runtime.js";
+export { createTransformersJsRuntime } from "./onnx-transformers-runtime.js";

package/dist/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/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,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;;;;;;;;;OASG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAc5F,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,2BAA2B;IAuBnC,OAAO,CAAC,kBAAkB;IAuF1B,OAAO,CAAC,2BAA2B;IAiCnC,OAAO,CAAC,gBAAgB;CAYzB"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/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,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;;;;;;;;;OASG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAc5F,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,2BAA2B;IAuBnC,OAAO,CAAC,kBAAkB;IA0F1B,OAAO,CAAC,2BAA2B;IAiCnC,OAAO,CAAC,gBAAgB;CAYzB"}

package/dist/router.js

@@ -67,17 +67,24 @@ export class Router {
             .filter((candidate) => candidate.descriptor.supports.run);
         const localCandidates = eligible.filter((candidate) => candidate.descriptor.type !== "cloud");
         const cloudCandidates = eligible.filter((candidate) => candidate.descriptor.type === "cloud");
-        const selected = eligible.find((candidate) => {
+        // 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;
-            const privacy = descriptor.privacy?.dataLeavesDevice ?? descriptor.type !== "cloud";
+            // 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" && !privacy) {
+            if (constraints.privacy === "local_required" && !isDataPrivate) {
                 return false;
             }
             if (constraints.privacy === "cloud_required" && descriptor.type !== "cloud") {
@@ -88,10 +95,7 @@ export class Router {
             }
             return candidate.capabilities.available;
         });
-        const ordered = selected
-            ? [selected, ...eligible.filter((candidate) => candidate !== selected)]
-            : [];
-        if (ordered.length === 0) {
+        if (admissible.length === 0) {
             const failureSummary = this.buildFallbackFailureSummary({
                 online,
                 constraints: planInput.constraints,
@@ -114,17 +118,17 @@ export class Router {
                 }
             };
         }
-        const selectedProviderId = ordered[0]?.descriptor.id;
+        const selectedProviderId = admissible[0]?.descriptor.id;
         return {
             selectedProviderId,
-            fallbackProviderIds: ordered.slice(1).map((candidate) => candidate.descriptor.id),
-            candidates: ordered.map((candidate, index) => ({
+            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 ${ordered.length} eligible candidate(s).`,
+                summary: `Selected provider '${selectedProviderId}' deterministically from ${admissible.length} eligible candidate(s).`,
                 selectedProviderId
             }
         };

package/dist/web-sdk.d.ts

@@ -1,5 +1,6 @@
 import { type CreateBrowserHostServicesOptions } from "./browser-host.js";
 import { IndeRun } from "./engine.js";
+import { type OnnxProviderOptions } from "./onnx-provider.js";
 import { type OpenAIProviderOptions } from "./openai-provider.js";
 /**
  * Configuration for the default Web SDK factory.
@@ -8,7 +9,12 @@ export interface CreateIndeRunWebOptions {
     /**
      * OpenAI Responses provider configuration registered by the factory.
      */
-    openAI: OpenAIProviderOptions;
+    openAI?: OpenAIProviderOptions;
+    /**
+     * Web ONNX Runtime provider configuration registered by the factory, for developer-supplied
+     * local models. Registering it is what makes `constraints.privacy = "local_required"` routable.
+     */
+    onnx?: OnnxProviderOptions;
     /**
      * Optional browser host service overrides.
      */
@@ -23,13 +29,16 @@ export interface CreateIndeRunWebOptions {
     allowDirectOpenAIEndpoint?: boolean;
 }
 /**
- * Creates a Web SDK instance with the OpenAI Responses provider registered.
+ * Creates a Web SDK instance with the configured providers registered.
+ *
+ * Pass `openAI` for cloud execution, `onnx` for developer-supplied local models, or both to let
+ * routing choose between them; at least one is required.
  *
  * Use `openAI.auth = "none"` with a proxy endpoint for production browser apps so the OpenAI API key never ships
  * to the client. Direct OpenAI calls require `allowDirectOpenAIEndpoint` and should resolve credentials through
  * `authContextRef` and `SecureStorageService`.
  *
- * @param options - OpenAI provider configuration and optional host service overrides.
+ * @param options - Provider configuration and optional host service overrides.
  */
 export declare function createIndeRunWeb(options: CreateIndeRunWebOptions): IndeRun;
 //# sourceMappingURL=web-sdk.d.ts.map

package/dist/web-sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web-sdk.d.ts","sourceRoot":"","sources":["../src/web-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gCAAgC,EACtC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAG9B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,EAAE,qBAAqB,CAAC;IAC9B;;OAEG;IACH,YAAY,CAAC,EAAE,gCAAgC,CAAC;IAChD;;;;;;OAMG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAO1E"}
+{"version":3,"file":"web-sdk.d.ts","sourceRoot":"","sources":["../src/web-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gCAAgC,EACtC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAG9B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B;;OAEG;IACH,YAAY,CAAC,EAAE,gCAAgC,CAAC;IAChD;;;;;;OAMG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAmB1E"}

package/dist/web-sdk.js

@@ -1,27 +1,39 @@
 import { createBrowserHostServices } from "./browser-host.js";
 import { IndeRun } from "./engine.js";
+import { OnnxRuntimeWebProvider } from "./onnx-provider.js";
 import { DEFAULT_OPENAI_RESPONSES_ENDPOINT, OpenAIResponsesProvider } from "./openai-provider.js";
 import { ProviderRegistry } from "./registry.js";
 /**
- * Creates a Web SDK instance with the OpenAI Responses provider registered.
+ * Creates a Web SDK instance with the configured providers registered.
+ *
+ * Pass `openAI` for cloud execution, `onnx` for developer-supplied local models, or both to let
+ * routing choose between them; at least one is required.
  *
  * Use `openAI.auth = "none"` with a proxy endpoint for production browser apps so the OpenAI API key never ships
  * to the client. Direct OpenAI calls require `allowDirectOpenAIEndpoint` and should resolve credentials through
  * `authContextRef` and `SecureStorageService`.
  *
- * @param options - OpenAI provider configuration and optional host service overrides.
+ * @param options - Provider configuration and optional host service overrides.
  */
 export function createIndeRunWeb(options) {
-    assertSafeOpenAIEndpoint(options);
+    if (!options.openAI && !options.onnx) {
+        throw new Error("createIndeRunWeb requires at least one provider configuration (openAI and/or onnx).");
+    }
     const registry = new ProviderRegistry();
-    registry.register(new OpenAIResponsesProvider(options.openAI));
+    if (options.openAI) {
+        assertSafeOpenAIEndpoint(options.openAI, options.allowDirectOpenAIEndpoint);
+        registry.register(new OpenAIResponsesProvider(options.openAI));
+    }
+    if (options.onnx) {
+        registry.register(new OnnxRuntimeWebProvider(options.onnx));
+    }
     return new IndeRun(registry, createBrowserHostServices(options.hostServices));
 }
-function assertSafeOpenAIEndpoint(options) {
-    const endpointUrl = options.openAI.endpointUrl ?? DEFAULT_OPENAI_RESPONSES_ENDPOINT;
-    const auth = options.openAI.auth ?? "authContextRef";
+function assertSafeOpenAIEndpoint(openAI, allowDirectOpenAIEndpoint) {
+    const endpointUrl = openAI.endpointUrl ?? DEFAULT_OPENAI_RESPONSES_ENDPOINT;
+    const auth = openAI.auth ?? "authContextRef";
     const isDirectOpenAIEndpoint = isOpenAIResponsesEndpoint(endpointUrl);
-    if (isDirectOpenAIEndpoint && auth !== "none" && !options.allowDirectOpenAIEndpoint) {
+    if (isDirectOpenAIEndpoint && auth !== "none" && !allowDirectOpenAIEndpoint) {
         throw new Error('createIndeRunWeb is proxy-first for browser safety. Configure openAI.endpointUrl to a server-side proxy with auth: "none", or set allowDirectOpenAIEndpoint: true for controlled direct OpenAI calls.');
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@independo/inderun-web",
-  "version": "0.2.0-dev.1",
+  "version": "0.2.0-dev.2",
   "description": "TypeScript/Web SDK for IndeRun.",
   "license": "MIT",
   "author": {
@@ -40,6 +40,10 @@
     "./openai": {
       "types": "./dist/openai.d.ts",
       "default": "./dist/openai.js"
+    },
+    "./onnx": {
+      "types": "./dist/onnx.d.ts",
+      "default": "./dist/onnx.js"
     }
   },
   "files": [
@@ -47,8 +51,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@independo/inderun-contracts": "^0.2.0-dev.1",
-    "@independo/inderun-route-core-wasm": "^0.2.0-dev.1"
+    "@independo/inderun-contracts": "^0.2.0-dev.2",
+    "@independo/inderun-route-core-wasm": "^0.2.0-dev.2"
+  },
+  "peerDependencies": {
+    "@huggingface/transformers": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^26.1.1",