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

package/dist/index.js

@@ -1,12 +1,12 @@
-export {} from "./host.js";
-export {} from "./provider.js";
-export { ProviderRegistry } from "./registry.js";
-export { Router } from "./router.js";
-export { WasmRoutePlanner } from "./route-planner.js";
-export { IndeRunException, createCapabilityMismatch, createOffline, createAuthError, createRateLimited, createTimeout, createUnavailable, createInternal, toIndeRunException } from "./errors.js";
-export { IndeRun } from "./engine.js";
-export { NoOpTelemetryService } from "./telemetry.js";
-export { BrowserConnectivityService, FetchHttpClient, SystemClockService, createBrowserHostServices } from "./browser-host.js";
+export {} from "./core/host.js";
+export {} from "./core/provider.js";
+export { ProviderRegistry } from "./core/registry.js";
+export { Router } from "./core/router.js";
+export { WasmRoutePlanner } from "./core/route-planner.js";
+export { IndeRunException, createCapabilityMismatch, createOffline, createAuthError, createRateLimited, createTimeout, createUnavailable, createInternal, toIndeRunException } from "./core/errors.js";
+export { IndeRun } from "./core/engine.js";
+export { NoOpTelemetryService } from "./core/telemetry.js";
+export { BrowserConnectivityService, FetchHttpClient, SystemClockService, createBrowserHostServices } from "./core/browser-host.js";
 export { createIndeRunWeb } from "./web-sdk.js";
 // The OpenAI Responses adapter is provider-specific and intentionally excluded
 // from this unified index. Import it from "@independo/inderun-web/openai".

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 "./providers/onnx/provider.js";
+export { OnnxRuntimeError, createFixtureOnnxRuntime, type FixtureOnnxRuntimeOptions, type OnnxGenerationInput, type OnnxGenerationMessage, type OnnxGenerationOutput, type OnnxRuntimeAvailability, type OnnxRuntimeErrorKind, type OnnxTextGenerationRuntime } from "./providers/onnx/runtime.js";
+export { createTransformersJsRuntime, type TransformersJsRuntimeOptions, type TransformersModule, type TransformersTextGenerator } from "./providers/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,8BAA8B,CAAC;AAEtC,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,6BAA6B,CAAC;AAErC,OAAO,EACL,2BAA2B,EAC3B,KAAK,4BAA4B,EACjC,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC/B,MAAM,0CAA0C,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 "./providers/onnx/provider.js";
+export { OnnxRuntimeError, createFixtureOnnxRuntime } from "./providers/onnx/runtime.js";
+export { createTransformersJsRuntime } from "./providers/onnx/transformers-runtime.js";

package/dist/openai.d.ts

@@ -6,5 +6,5 @@
  * when registering the adapter manually; most browser apps should use
  * `createIndeRunWeb` from the main entry point instead.
  */
-export { OpenAIResponsesProvider, type OpenAIProviderOptions, DEFAULT_OPENAI_RESPONSES_ENDPOINT } from "./openai-provider.js";
+export { OpenAIResponsesProvider, type OpenAIProviderOptions, DEFAULT_OPENAI_RESPONSES_ENDPOINT } from "./providers/openai/provider.js";
 //# sourceMappingURL=openai.d.ts.map

package/dist/openai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../src/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,iCAAiC,EAClC,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../src/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,iCAAiC,EAClC,MAAM,gCAAgC,CAAC"}

package/dist/openai.js

@@ -6,4 +6,4 @@
  * when registering the adapter manually; most browser apps should use
  * `createIndeRunWeb` from the main entry point instead.
  */
-export { OpenAIResponsesProvider, DEFAULT_OPENAI_RESPONSES_ENDPOINT } from "./openai-provider.js";
+export { OpenAIResponsesProvider, DEFAULT_OPENAI_RESPONSES_ENDPOINT } from "./providers/openai/provider.js";

package/dist/providers/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 "../../core/host.js";
+import { type OnnxTextGenerationRuntime } from "./runtime.js";
+import type { ProviderAdapter, ProviderDescriptor, ProviderDynamicCapabilities, RunContext } from "../../core/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=provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/providers/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,oBAAoB,CAAC;AACvD,OAAO,EAIL,KAAK,yBAAyB,EAC/B,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,2BAA2B,EAC3B,UAAU,EACX,MAAM,wBAAwB,CAAC;AAEhC,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/providers/onnx/provider.js

@@ -0,0 +1,217 @@
+import { getModelPackageValidationIssues } from "@independo/inderun-contracts";
+import { createCapabilityMismatch, createInternal, createTimeout, createUnavailable, toIndeRunException } from "../../core/errors.js";
+import { OnnxRuntimeError } from "./runtime.js";
+import { createTransformersJsRuntime } from "./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/providers/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=runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/providers/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/providers/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/providers/onnx/transformers-runtime.d.ts

@@ -0,0 +1,72 @@
+import type { ModelPackage } from "@independo/inderun-contracts";
+import { type OnnxTextGenerationRuntime } from "./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=transformers-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transformers-runtime.d.ts","sourceRoot":"","sources":["../../../src/providers/onnx/transformers-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,cAAc,CAAC;AAEtB;;;;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"}