@independo/inderun-web 0.3.3-rc.2 → 0.4.0-rc.1

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

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/providers/openai/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAQ5E,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,UAAU,EACX,MAAM,wBAAwB,CAAC;AA4BhC,eAAO,MAAM,iCAAiC,wCAAwC,CAAC;AAKvF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC;IACjC;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AA6BD;;;;;;GAMG;AACH,qBAAa,uBAAwB,YAAW,eAAe;IAUjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IATpC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,YAAY,CAAC,CAA6D;IAElF;;;OAGG;gBAC0B,OAAO,EAAE,qBAAqB;IAM3D;;OAEG;IACH,QAAQ,IAAI,kBAAkB;IAuB9B;;;;;;;;OAQG;IACG,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,2BAA2B,CAAC;YA+B9D,sBAAsB;IAuCpC;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAiFzE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,MAAM,CACX,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAAC,mBAAmB,CAAC;IAiGtC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;;;OAKG;YACW,cAAc;IA2C5B,OAAO,CAAC,iBAAiB;IA2BzB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;CAmErB"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/providers/openai/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAQ5E,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,UAAU,EACX,MAAM,wBAAwB,CAAC;AA4BhC,eAAO,MAAM,iCAAiC,wCAAwC,CAAC;AAKvF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC;IACjC;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AA8BD;;;;;;GAMG;AACH,qBAAa,uBAAwB,YAAW,eAAe;IAUjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IATpC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,YAAY,CAAC,CAA6D;IAElF;;;OAGG;gBAC0B,OAAO,EAAE,qBAAqB;IAM3D;;OAEG;IACH,QAAQ,IAAI,kBAAkB;IAwB9B;;;;;;;;OAQG;IACG,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,2BAA2B,CAAC;YA+B9D,sBAAsB;IAuCpC;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAsFzE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,MAAM,CACX,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAAC,mBAAmB,CAAC;IAqGtC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;;;OAKG;YACW,cAAc;IA2C5B,OAAO,CAAC,iBAAiB;IA2BzB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;CAmErB"}

package/dist/providers/openai/provider.js

@@ -42,6 +42,7 @@ export class OpenAIResponsesProvider {
         return {
             id: this.id,
             type: "cloud",
+            model: this.options.model,
             transport: "http",
             streamingStyle: "tokens",
             supports: {
@@ -193,6 +194,10 @@ export class OpenAIResponsesProvider {
                 totalMs: 0
             }
         };
+        const reportedModel = getReportedModel(responseBody);
+        if (reportedModel !== undefined) {
+            result.telemetry.reportedModel = reportedModel;
+        }
         const usage = getUsage(responseBody);
         if (usage) {
             result.usage = usage;
@@ -286,6 +291,10 @@ export class OpenAIResponsesProvider {
                 if (usage) {
                     done.usage = usage;
                 }
+                const reportedModel = getReportedModel(body);
+                if (reportedModel !== undefined) {
+                    done.reportedModel = reportedModel;
+                }
                 yield done;
                 return;
             }
@@ -485,6 +494,15 @@ function getFinishReason(response) {
     }
     return "stop";
 }
+/**
+ * The model id the Responses API echoes on the response object. It names the model that
+ * served the request, which can be a dated snapshot of the configured alias.
+ */
+function getReportedModel(responseBody) {
+    return typeof responseBody.model === "string" && responseBody.model.length > 0
+        ? responseBody.model
+        : undefined;
+}
 function getUsage(response) {
     const usage = {};
     if (typeof response.usage?.input_tokens === "number") {

package/dist/web-sdk.d.ts

@@ -1,5 +1,6 @@
 import { type CreateBrowserHostServicesOptions } from "./core/browser-host.js";
 import { IndeRun } from "./core/engine.js";
+import type { ModelProfiles } from "./core/model-profiles.js";
 import { type OnnxProviderOptions } from "./providers/onnx/provider.js";
 import { type OpenAIProviderOptions } from "./providers/openai/provider.js";
 import { type SystemModelProviderOptions } from "./providers/system-model/provider.js";
@@ -8,9 +9,11 @@ import { type SystemModelProviderOptions } from "./providers/system-model/provid
  */
 export interface CreateIndeRunWebOptions {
     /**
-     * OpenAI Responses provider configuration registered by the factory.
+     * OpenAI Responses provider configuration registered by the factory. One target is
+     * registered per entry in `models`, with id `<id>:<model>` (`id` defaults to
+     * `"openai"`), so model profiles can list each model separately.
      */
-    openAI?: OpenAIProviderOptions;
+    openAI?: OpenAIFactoryOptions;
     /**
      * Web ONNX Runtime provider configuration registered by the factory, for developer-supplied
      * local models. Registering it is what makes `constraints.privacy = "local_required"` routable.
@@ -34,7 +37,21 @@ export interface CreateIndeRunWebOptions {
      * non-production environments.
      */
     allowDirectOpenAIEndpoint?: boolean;
+    /**
+     * Named model profiles requests can route within. Each maps a profile name to an
+     * ordered list of target ids, for example `{ smart: ["openai:gpt-5.2"] }`.
+     */
+    modelProfiles?: ModelProfiles;
 }
+/**
+ * OpenAI options for {@link createIndeRunWeb}: the provider options with `models` in
+ * place of the single `model`. The first model is not special; every model becomes
+ * its own target.
+ */
+export type OpenAIFactoryOptions = Omit<OpenAIProviderOptions, "model"> & {
+    /** OpenAI model ids to register, one target each. */
+    models: readonly string[];
+};
 /**
  * Creates a Web SDK instance with the configured providers registered.
  *

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,wBAAwB,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAChG,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,0BAA0B,CAAC;IACzC;;OAEG;IACH,YAAY,CAAC,EAAE,gCAAgC,CAAC;IAChD;;;;;;OAMG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAuB1E"}
+{"version":3,"file":"web-sdk.d.ts","sourceRoot":"","sources":["../src/web-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gCAAgC,EACtC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAChG,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;OAGG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,0BAA0B,CAAC;IACzC;;OAEG;IACH,YAAY,CAAC,EAAE,gCAAgC,CAAC;IAChD;;;;;;OAMG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,qBAAqB,EAAE,OAAO,CAAC,GAAG;IACxE,qDAAqD;IACrD,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CA+B1E"}

package/dist/web-sdk.js

@@ -24,7 +24,13 @@ export function createIndeRunWeb(options) {
     const registry = new ProviderRegistry();
     if (options.openAI) {
         assertSafeOpenAIEndpoint(options.openAI, options.allowDirectOpenAIEndpoint);
-        registry.register(new OpenAIResponsesProvider(options.openAI));
+        const { models, id = "openai", ...shared } = options.openAI;
+        if (models.length === 0) {
+            throw new Error("createIndeRunWeb requires openAI.models to list at least one model.");
+        }
+        for (const model of models) {
+            registry.register(new OpenAIResponsesProvider({ ...shared, id: `${id}:${model}`, model }));
+        }
     }
     if (options.onnx) {
         registry.register(new OnnxRuntimeWebProvider(options.onnx));
@@ -32,7 +38,9 @@ export function createIndeRunWeb(options) {
     if (options.systemModel) {
         registry.register(new SystemModelWebProvider(options.systemModel));
     }
-    return new IndeRun(registry, createBrowserHostServices(options.hostServices));
+    return new IndeRun(registry, createBrowserHostServices(options.hostServices), {
+        ...(options.modelProfiles ? { modelProfiles: options.modelProfiles } : {})
+    });
 }
 function assertSafeOpenAIEndpoint(openAI, allowDirectOpenAIEndpoint) {
     const endpointUrl = openAI.endpointUrl ?? DEFAULT_OPENAI_RESPONSES_ENDPOINT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@independo/inderun-web",
-  "version": "0.3.3-rc.2",
+  "version": "0.4.0-rc.1",
   "description": "On-device AI with automatic cloud fallback for web apps. Runs ONNX Runtime or the Chrome Prompt API in the browser and falls back to an OpenAI-compatible endpoint, with streaming and cancellation behind one API.",
   "license": "MIT",
   "author": {
@@ -68,8 +68,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@independo/inderun-contracts": "^0.3.3-rc.2",
-    "@independo/inderun-route-core-wasm": "^0.3.3-rc.2"
+    "@independo/inderun-contracts": "^0.4.0-rc.1",
+    "@independo/inderun-route-core-wasm": "^0.4.0-rc.1"
   },
   "peerDependencies": {
     "@huggingface/transformers": "^4.0.0"

package/src/core/engine.ts

@@ -19,6 +19,14 @@ import {
 } from "./errors.js";
 import { type TelemetryEvent, type TelemetryService, NoOpTelemetryService } from "./telemetry.js";
 import { EventGate } from "./event-gate.js";
+import {
+  AUTO_MODEL_PROFILE,
+  type ModelProfiles,
+  type ResolvedModelProfile,
+  resolveModelProfile,
+  validateModelProfiles
+} from "./model-profiles.js";
+import { ProvenanceRecorder } from "./provenance.js";
 
 /**
  * @deprecated Renamed to `StreamRun`, which is the name the generated
@@ -27,6 +35,22 @@ import { EventGate } from "./event-gate.js";
  */
 export type StreamHandleResult = StreamRun;
 
+/**
+ * Optional engine configuration.
+ */
+export interface IndeRunOptions {
+  /**
+   * Telemetry listener. Defaults to the host's telemetry service, then to a no-op.
+   */
+  telemetryService?: TelemetryService;
+  /**
+   * Named model profiles requests can route within (`TaskRequest.modelProfile`).
+   * Each maps a profile name to an ordered list of target (provider instance) ids.
+   * `"auto"` is built in and cannot be redefined. See `docs/architecture/api-layering.md`.
+   */
+  modelProfiles?: ModelProfiles;
+}
+
 /**
  * Main orchestrator SDK entrypoint class.
  * Validates tasks, executes routing rules based on request constraints and connectivity,
@@ -35,21 +59,48 @@ export type StreamHandleResult = StreamRun;
 export class IndeRun implements IndeRunApi {
   private router: Router;
   private telemetryService: TelemetryService;
+  private modelProfiles: ModelProfiles;
 
   /**
    * Initializes the IndeRun instance.
    * @param registry - Registry filled with active providers.
    * @param hostServices - Services wrapping OS interfaces and indicators.
-   * @param telemetryService - Optional custom telemetry service listener.
+   * @param options - Optional telemetry listener and model profiles.
+   * @throws {Error} If a model profile is malformed (see {@link validateModelProfiles}).
    */
   constructor(
     private registry: ProviderRegistry,
     private hostServices: HostServices,
-    telemetryService?: TelemetryService
+    options: IndeRunOptions = {}
   ) {
     this.router = new Router(this.registry);
     this.telemetryService =
-      telemetryService || this.hostServices.telemetry || new NoOpTelemetryService();
+      options.telemetryService || this.hostServices.telemetry || new NoOpTelemetryService();
+    this.modelProfiles = options.modelProfiles ?? {};
+    validateModelProfiles(this.modelProfiles);
+  }
+
+  /**
+   * Validates the request against the schema and resolves its model profile.
+   * Both failures are request validation errors: they are reported before any
+   * provider is probed, with the offending fields in `details.validationIssues`.
+   */
+  private validateRequest(request: TaskRequest, runId: string): ResolvedModelProfile {
+    const validationIssues = getTaskRequestValidationIssues(request);
+    if (validationIssues.length === 0) {
+      const resolved = resolveModelProfile(this.modelProfiles, request.modelProfile);
+      if (resolved.known) {
+        return resolved.profile;
+      }
+      validationIssues.push({
+        path: "/modelProfile",
+        message: `unknown model profile "${request.modelProfile}"; configure it in the engine's modelProfiles`
+      });
+    }
+    const message = `Validation failed for TaskRequest: ${validationIssues
+      .map((i) => `${i.path} - ${i.message}`)
+      .join("; ")}`;
+    throw createInternal(message, { runId, details: { validationIssues } });
   }
 
   /**
@@ -81,6 +132,7 @@ export class IndeRun implements IndeRunApi {
         rejectedProviders: routeSelection.routePlan.rejectedProviders,
         fallbackAvailable: providerCount > 1,
         taskKind: request.task.kind,
+        modelProfile: request.modelProfile ?? "auto",
         constraints: request.constraints ?? null,
         preferences: request.preferences ?? null,
         explanation: routeSelection.explanation
@@ -137,23 +189,21 @@ export class IndeRun implements IndeRunApi {
     const startTime = this.now();
 
     const runId = request.requestId || `run_${Math.random().toString(36).substring(2, 11)}`;
+    const provenance = new ProvenanceRecorder(request.modelProfile ?? AUTO_MODEL_PROFILE);
 
     try {
-      // 1. Validate request payload using schema contracts
-      const validationIssues = getTaskRequestValidationIssues(request);
-      if (validationIssues.length > 0) {
-        const message = `Validation failed for TaskRequest: ${validationIssues
-          .map((i) => `${i.path} - ${i.message}`)
-          .join("; ")}`;
-        throw createInternal(message, {
-          runId,
-          details: { validationIssues }
-        });
-      }
-
-      // 2. Select the route based on constraints and host capabilities
-      const routeSelection = await this.router.selectRoute(request, this.hostServices, "run");
+      // 1. Validate request payload using schema contracts and resolve its model profile
+      const modelProfile = this.validateRequest(request, runId);
+
+      // 2. Select the route based on constraints, model profile, and host capabilities
+      const routeSelection = await this.router.selectRoute(
+        request,
+        this.hostServices,
+        "run",
+        modelProfile
+      );
       const providers = [routeSelection.provider, ...routeSelection.fallbackProviders];
+      provenance.routed(routeSelection.routePlan);
 
       this.emitRouteDecided(runId, request, routeSelection, providers.length);
 
@@ -179,6 +229,8 @@ export class IndeRun implements IndeRunApi {
             providerUsed: providerId,
             totalMs
           };
+          provenance.attempted(providerId, "succeeded");
+          result.provenance = provenance.build(provider.describe(), result.telemetry.reportedModel);
 
           this.safeEmit({
             type: "attempt_succeeded",
@@ -194,7 +246,7 @@ export class IndeRun implements IndeRunApi {
 
           return result;
         } catch (err) {
-          lastError = toIndeRunException(err, {
+          const attemptError = toIndeRunException(err, {
             providerId,
             runId,
             details: {
@@ -203,6 +255,8 @@ export class IndeRun implements IndeRunApi {
               routePlan: routeSelection.routePlan
             }
           });
+          provenance.attempted(providerId, "failed", attemptError.errorClass);
+          lastError = attemptError;
         }
       }
 
@@ -213,14 +267,14 @@ export class IndeRun implements IndeRunApi {
         details: {
           totalMs,
           attemptedProviderIds,
-          fallbackOccurred: providers.length > 1,
+          fallbackOccurred: attemptedProviderIds.length > 1,
           routePlan: routeSelection.routePlan
         }
       });
 
       throw exception;
     } catch (error) {
-      const exception = toIndeRunException(error, {
+      const normalized = toIndeRunException(error, {
         runId,
         details: {
           totalMs:
@@ -229,6 +283,10 @@ export class IndeRun implements IndeRunApi {
               : this.now() - startTime
         }
       });
+      // A routing refusal throws before any attempt; its rejections travel on the details.
+      provenance.routingFailed(normalized.details);
+      // No attempt produced the result, so the outcome is attributed to no provider.
+      const exception = normalized.withProvenance(provenance.build());
       const endTime = this.now();
       const totalMs =
         typeof (exception as { details?: { totalMs?: number } }).details?.totalMs === "number"
@@ -273,13 +331,13 @@ export class IndeRun implements IndeRunApi {
     const startTime = this.now();
     const now = () => this.now();
     const runId = request.requestId || `run_${Math.random().toString(36).substring(2, 11)}`;
+    const provenance = new ProvenanceRecorder(request.modelProfile ?? AUTO_MODEL_PROFILE);
 
-    const validationIssues = getTaskRequestValidationIssues(request);
-    if (validationIssues.length > 0) {
-      const message = `Validation failed for TaskRequest: ${validationIssues
-        .map((i) => `${i.path} - ${i.message}`)
-        .join("; ")}`;
-      throw createInternal(message, { runId, details: { validationIssues } });
+    let modelProfile: ResolvedModelProfile;
+    try {
+      modelProfile = this.validateRequest(request, runId);
+    } catch (error) {
+      throw toIndeRunException(error, { runId }).withProvenance(provenance.build());
     }
 
     // Route selection failures are the one class of stream error that surfaces as a
@@ -287,11 +345,19 @@ export class IndeRun implements IndeRunApi {
     // runId — there is no handle for the caller to correlate them with otherwise.
     let routeSelection: RouteSelection;
     try {
-      routeSelection = await this.router.selectRoute(request, this.hostServices, "stream");
+      routeSelection = await this.router.selectRoute(
+        request,
+        this.hostServices,
+        "stream",
+        modelProfile
+      );
     } catch (error) {
-      throw toIndeRunException(error, { runId });
+      const exception = toIndeRunException(error, { runId });
+      provenance.routingFailed(exception.details);
+      throw exception.withProvenance(provenance.build());
     }
     const providers = [routeSelection.provider, ...routeSelection.fallbackProviders];
+    provenance.routed(routeSelection.routePlan);
 
     this.emitRouteDecided(runId, request, routeSelection, providers.length);
 
@@ -322,15 +388,22 @@ export class IndeRun implements IndeRunApi {
       const attemptedProviderIds: string[] = [];
       let committed = false;
 
-      const cancelledOutcome = (partialText: string): StreamTerminalOutcome => {
+      const cancelledOutcome = (
+        partialText: string,
+        cancelledProvider?: ProviderAdapter
+      ): StreamTerminalOutcome => {
         const reason =
           typeof controller.signal.reason === "string" ? controller.signal.reason : undefined;
+        if (cancelledProvider !== undefined) {
+          provenance.attempted(cancelledProvider.describe().id, "cancelled");
+        }
         return {
           outcome: "cancelled",
           runId,
           schemaVersion: "1.0",
           partialText,
-          ...(reason !== undefined ? { reason } : {})
+          ...(reason !== undefined ? { reason } : {}),
+          provenance: provenance.build(cancelledProvider?.describe())
         };
       };
 
@@ -387,6 +460,7 @@ export class IndeRun implements IndeRunApi {
             }
 
             // ev.kind === "done"
+            provenance.attempted(providerId, "succeeded");
             const outcome: StreamTerminalOutcome = {
               outcome: "completed",
               runId,
@@ -394,7 +468,8 @@ export class IndeRun implements IndeRunApi {
               finalText: ev.finalText,
               telemetry: { providerUsed: providerId, totalMs: now() - startTime },
               ...(ev.finishReason !== undefined ? { finishReason: ev.finishReason } : {}),
-              ...(ev.usage !== undefined ? { usage: ev.usage } : {})
+              ...(ev.usage !== undefined ? { usage: ev.usage } : {}),
+              provenance: provenance.build(provider.describe(), ev.reportedModel)
             };
             const terminal = gate.terminate(outcome, now());
             safeEmit({
@@ -413,7 +488,7 @@ export class IndeRun implements IndeRunApi {
           }
 
           if (controller.signal.aborted) {
-            const terminal = gate.terminate(cancelledOutcome(partialText), now());
+            const terminal = gate.terminate(cancelledOutcome(partialText, provider), now());
             safeEmit({
               type: "stream_cancelled",
               runId,
@@ -428,7 +503,7 @@ export class IndeRun implements IndeRunApi {
           throw new Error(`Provider '${providerId}' stream ended without a terminal event.`);
         } catch (err) {
           if (controller.signal.aborted) {
-            const terminal = gate.terminate(cancelledOutcome(partialText), now());
+            const terminal = gate.terminate(cancelledOutcome(partialText, provider), now());
             safeEmit({
               type: "stream_cancelled",
               runId,
@@ -444,6 +519,7 @@ export class IndeRun implements IndeRunApi {
             runId,
             details: { attemptedProviderIds }
           });
+          provenance.attempted(providerId, "failed", exception.errorClass);
 
           if (!committed) {
             safeEmit({
@@ -459,12 +535,14 @@ export class IndeRun implements IndeRunApi {
             continue;
           }
 
+          // Committed: the failure belongs to this provider, not to the chain.
           const outcome: StreamTerminalOutcome = {
             outcome: "error",
             runId,
             schemaVersion: "1.0",
             error: exception.toContractError(),
-            partialText
+            partialText,
+            provenance: provenance.build(provider.describe())
           };
           const terminal = gate.terminate(outcome, now());
           safeEmit({
@@ -505,7 +583,8 @@ export class IndeRun implements IndeRunApi {
         runId,
         schemaVersion: "1.0",
         error: exception.toContractError(),
-        partialText: ""
+        partialText: "",
+        provenance: provenance.build()
       };
       const terminal = gate.terminate(outcome, now());
       safeEmit({

package/src/core/errors.ts

@@ -1,4 +1,8 @@
-import type { IndeRunError, IndeRunErrorClass } from "@independo/inderun-contracts";
+import type {
+  ExecutionProvenance,
+  IndeRunError,
+  IndeRunErrorClass
+} from "@independo/inderun-contracts";
 
 /**
  * Parameter structure required to initialize an IndeRunException.
@@ -32,6 +36,10 @@ export interface IndeRunExceptionParams {
    * Rich contextual metadata regarding the error.
    */
   details?: Record<string, unknown>;
+  /**
+   * How the failed execution played out, attached by the engine.
+   */
+  provenance?: ExecutionProvenance;
 }
 
 /**
@@ -53,6 +61,8 @@ export class IndeRunException extends Error {
   readonly retryAfterMs?: number;
   /** Custom details and metadata context. */
   readonly details?: Record<string, unknown>;
+  /** How the failed execution played out: attempts, rejections, the provider committed to. */
+  readonly provenance?: ExecutionProvenance;
 
   constructor(params: IndeRunExceptionParams) {
     super(params.message);
@@ -63,6 +73,7 @@ export class IndeRunException extends Error {
     if (params.retryable !== undefined) this.retryable = params.retryable;
     if (params.retryAfterMs !== undefined) this.retryAfterMs = params.retryAfterMs;
     if (params.details !== undefined) this.details = params.details;
+    if (params.provenance !== undefined) this.provenance = params.provenance;
 
     Object.setPrototypeOf(this, IndeRunException.prototype);
   }
@@ -81,8 +92,28 @@ export class IndeRunException extends Error {
     if (this.retryable !== undefined) err.retryable = this.retryable;
     if (this.retryAfterMs !== undefined) err.retryAfterMs = this.retryAfterMs;
     if (this.details !== undefined) err.details = this.details;
+    if (this.provenance !== undefined) err.provenance = this.provenance;
     return err;
   }
+
+  /**
+   * A copy of this exception carrying `provenance`. The engine attaches provenance once it
+   * knows how the whole execution ended, replacing anything set earlier.
+   */
+  withProvenance(provenance: ExecutionProvenance): IndeRunException {
+    return new IndeRunException({ ...this.params(), provenance });
+  }
+
+  private params(): IndeRunExceptionParams {
+    const params: IndeRunExceptionParams = { errorClass: this.errorClass, message: this.message };
+    if (this.runId !== undefined) params.runId = this.runId;
+    if (this.providerId !== undefined) params.providerId = this.providerId;
+    if (this.retryable !== undefined) params.retryable = this.retryable;
+    if (this.retryAfterMs !== undefined) params.retryAfterMs = this.retryAfterMs;
+    if (this.details !== undefined) params.details = this.details;
+    if (this.provenance !== undefined) params.provenance = this.provenance;
+    return params;
+  }
 }
 
 /**
@@ -189,6 +220,9 @@ export function toIndeRunException(
         };
       }
 
+      const provenance = error.provenance ?? fallbackParams.provenance;
+      if (provenance !== undefined) mergedParams.provenance = provenance;
+
       return new IndeRunException(mergedParams);
     }
     return error;

package/src/core/model-profiles.ts

@@ -0,0 +1,70 @@
+import type { SharedPlannerInput } from "./route-planner.js";
+
+/**
+ * The built-in profile: every registered target, ranked by constraints and
+ * preferences alone. Requests that name no profile route within it.
+ */
+export const AUTO_MODEL_PROFILE = "auto";
+
+/**
+ * Application-defined model profiles: a profile name mapped to an ordered list of
+ * target ids (provider instance ids, each bound to one model). Requests name a
+ * profile through `TaskRequest.modelProfile`; the route planner treats the list as
+ * an allow-list and ranks its entries after placement and before preferences.
+ * Ids that name no registered provider are ignored by the planner.
+ */
+export type ModelProfiles = Readonly<Record<string, readonly string[]>>;
+
+/** A resolved profile as the shared planner consumes it; absent means `auto`. */
+export type ResolvedModelProfile = SharedPlannerInput["modelProfile"];
+
+/**
+ * Checks profile configuration once, when the engine is constructed, so a
+ * malformed profile is a setup error rather than a per-request surprise.
+ * @throws {Error} When a profile is named `auto`, is empty, or lists a target twice.
+ */
+export function validateModelProfiles(profiles: ModelProfiles): void {
+  for (const [name, targetIds] of Object.entries(profiles)) {
+    if (name.length === 0) {
+      throw new Error("Model profile names must be non-empty.");
+    }
+    if (name === AUTO_MODEL_PROFILE) {
+      throw new Error(
+        `"${AUTO_MODEL_PROFILE}" is the built-in model profile and cannot be redefined.`
+      );
+    }
+    if (targetIds.length === 0) {
+      throw new Error(`Model profile "${name}" must list at least one target id.`);
+    }
+    const seen = new Set<string>();
+    for (const id of targetIds) {
+      if (id.length === 0) {
+        throw new Error(`Model profile "${name}" lists an empty target id.`);
+      }
+      if (seen.has(id)) {
+        throw new Error(`Model profile "${name}" lists target "${id}" more than once.`);
+      }
+      seen.add(id);
+    }
+  }
+}
+
+/**
+ * Resolves a request's profile name against the configured profiles.
+ * @returns `{ known: true }` with the planner input (undefined for `auto`), or
+ *   `{ known: false }` when the name matches no configured profile.
+ */
+export function resolveModelProfile(
+  profiles: ModelProfiles,
+  name: string | undefined
+): { known: true; profile: ResolvedModelProfile } | { known: false } {
+  if (name === undefined || name === AUTO_MODEL_PROFILE) {
+    return { known: true, profile: undefined };
+  }
+  if (!Object.hasOwn(profiles, name)) {
+    return { known: false };
+  }
+  // validateModelProfiles guarantees every configured profile is non-empty.
+  const [first, ...rest] = profiles[name]!;
+  return { known: true, profile: { name, targetIds: [first!, ...rest] } };
+}