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

package/dist/providers/openai/provider.js

@@ -174,7 +174,15 @@ export class OpenAIResponsesProvider {
             throw this.mapHttpError(response.status, response.statusText, response.headers, response.body, context);
         }
         const responseBody = parseJson(response.body);
+        // A lenient server (OpenRouter among them) can answer 2xx for a run that
+        // failed upstream; that is a failure to classify, not an empty answer.
+        if (responseBody.status === "failed" || responseBody.status === "cancelled") {
+            throw this.mapReportedError(responseBody.error, `OpenAI Responses run ended with status '${responseBody.status}'.`, context, responseBody.error_type);
+        }
         const outputText = extractOutputText(responseBody);
+        if (outputText === undefined && isRecord(responseBody.error)) {
+            throw this.mapReportedError(responseBody.error, "OpenAI Responses payload reported an error.", context, responseBody.error_type);
+        }
         if (outputText === undefined) {
             throw createInternal("OpenAI Responses payload did not contain text output.", {
                 providerId: this.id,
@@ -221,7 +229,9 @@ export class OpenAIResponsesProvider {
      * - `response.completed` and `response.incomplete` become the terminal done,
      *   with `finalText`, `usage`, and `finishReason` read off the embedded
      *   response object by the same helpers Mode 1 uses — it has the same shape;
-     * - `response.failed` and `error` become a terminal error;
+     * - `response.failed`, `response.error` and `error` become a terminal error,
+     *   as does an untyped event carrying an `error` object (OpenRouter's
+     *   documented mid-stream failure shape);
      * - every other event type is ignored, since the set is open and additive.
      *
      * @param request - Canonical IndeRun task request.
@@ -298,7 +308,10 @@ export class OpenAIResponsesProvider {
                 yield done;
                 return;
             }
-            if (type === "response.failed" || type === "error") {
+            if (type === "response.failed" ||
+                type === "response.error" ||
+                type === "error" ||
+                (type === undefined && isRecord(parsed.error))) {
                 yield { kind: "error", error: this.mapStreamError(parsed, context) };
                 return;
             }
@@ -308,28 +321,64 @@ export class OpenAIResponsesProvider {
         // whatever deltas happened to arrive would hide a truncated response.
     }
     /**
-     * Maps a `response.failed` / `error` stream event onto the error taxonomy.
-     * These arrive over an HTTP 200 body, so there is no status code to classify
-     * from; OpenAI reports rate limiting and auth failures here with the same
-     * `code` values it uses in unary error bodies.
+     * Maps a `response.failed` / `response.error` / `error` stream event onto the
+     * error taxonomy. These arrive over an HTTP 200 body, so there is no status
+     * code to classify from; the event's own `code` is classified instead.
      *
      * Two payload shapes exist and both are accepted: the standalone `error`
      * event carries `code`/`message` at its root, while `response.failed` nests
-     * them under `response.error`. The root `type` is the event name rather than
-     * an error type, so it is never read as one.
+     * them under `response.error` and some servers nest them under `error`. The
+     * root `type` is the event name rather than an error type, so it is never
+     * read as one. OpenRouter's typed classification comes from the embedded
+     * response (`response.failed`) or the error's metadata (untyped events).
      */
     mapStreamError(event, context) {
         const nested = event.error ?? event.response?.error;
-        const message = nested?.message ?? event.message ?? "OpenAI Responses stream reported a failure.";
-        const code = nested?.code ?? event.code;
-        const details = { errorType: nested?.type, errorCode: code };
+        return this.mapReportedError({
+            message: nested?.message ?? event.message,
+            type: nested?.type,
+            code: nested?.code ?? event.code
+        }, "OpenAI Responses stream reported a failure.", context, event.response?.error_type ?? nested?.metadata?.error_type);
+    }
+    /**
+     * Classifies a failure reported in a body rather than by the HTTP status: a
+     * failed stream event or a 2xx run body whose status is `failed`. The most
+     * specific signal wins:
+     * 1. OpenRouter's typed `error_type`, classified by the HTTP status it
+     *    documents for that type (see `openRouterErrorTypeStatus`);
+     * 2. an integer `code`, which is an HTTP status (OpenRouter's convention) and
+     *    is classified exactly as `mapHttpError` classifies that status;
+     * 3. a string code, by OpenAI's names.
+     * Anything unrecognized is a transient `Unavailable`, since the server did
+     * accept the request.
+     */
+    mapReportedError(reported, fallbackMessage, context, errorType) {
+        const message = typeof reported?.message === "string" && reported.message.length > 0
+            ? reported.message
+            : fallbackMessage;
+        const typedStatus = openRouterErrorTypeStatus(errorType);
+        const details = {
+            errorType: typedStatus !== undefined ? errorType : reported?.type,
+            errorCode: getErrorCode(reported?.code)
+        };
         const params = { providerId: this.id, runId: context.runId, details };
+        if (typedStatus !== undefined) {
+            return this.errorForStatus(typedStatus, message, params);
+        }
+        const code = reported?.code;
+        if (typeof code === "number" && Number.isInteger(code)) {
+            return this.errorForStatus(code, message, params);
+        }
         switch (code) {
             case "rate_limit_exceeded":
                 return createRateLimited(message, { ...params, retryable: true });
             case "invalid_api_key":
             case "authentication_error":
                 return createAuthError(message, params);
+            // The request itself was rejected; repeating it cannot succeed.
+            case "invalid_prompt":
+            case "image_content_policy_violation":
+                return createInternal(message, params);
             default:
                 return createUnavailable(message, { ...params, retryable: true });
         }
@@ -395,66 +444,64 @@ export class OpenAIResponsesProvider {
         return body;
     }
     /**
-     * Maps an OpenAI HTTP error response onto the IndeRun error taxonomy:
-     * - `401` / `403` → `AuthError`
-     * - `429` → `RateLimited` (honors `Retry-After` when present)
-     * - `408` / `504` → `Timeout`
-     * - `409` / `5xx` → `Unavailable`
-     * - any other non-2xx status → `Internal`
+     * Maps an OpenAI HTTP error response onto the IndeRun error taxonomy by its
+     * status (see `errorForStatus`), honoring `Retry-After` on whichever status
+     * carries it.
      */
     mapHttpError(status, statusText, headers, body, context) {
         const error = parseJson(body);
         const message = getOpenAIErrorMessage(error, status, statusText);
-        const details = {
-            status,
-            statusText,
-            errorType: getString(error.error?.type),
-            errorCode: getString(error.error?.code)
+        const params = {
+            providerId: this.id,
+            runId: context.runId,
+            details: {
+                status,
+                statusText,
+                errorType: getString(error.error?.type),
+                errorCode: getErrorCode(error.error?.code)
+            }
         };
+        return this.errorForStatus(status, message, params, parseRetryAfterMs(headers));
+    }
+    /**
+     * The status classification shared by HTTP errors and numeric in-body codes:
+     * - `401` / `403` → `AuthError`
+     * - `402` → `Unavailable`, not retryable: the account is out of credits, so
+     *   this target cannot serve until someone tops it up. A 402 that carries
+     *   `Retry-After` is the exception — OpenRouter documents it for its
+     *   in-flight budget limit, a wait-and-retry case — and is `RateLimited`. Fallback is unaffected
+     *   either way: the engine moves on to the next target whatever the class.
+     * - `429` → `RateLimited`
+     * - `408` / `504` → `Timeout`
+     * - `409` / `5xx` → `Unavailable`
+     * - any other status → `Internal`
+     *
+     * `retryAfterMs` travels on every retryable class; it is absent for numeric
+     * in-body codes, which have no header to read it from.
+     */
+    errorForStatus(status, message, params, retryAfterMs) {
+        const retry = { ...params, retryable: true };
+        if (retryAfterMs !== undefined) {
+            retry.retryAfterMs = retryAfterMs;
+        }
         if (status === 401 || status === 403) {
-            return createAuthError(message, {
-                providerId: this.id,
-                runId: context.runId,
-                details
-            });
+            return createAuthError(message, params);
+        }
+        if (status === 402) {
+            return retryAfterMs === undefined
+                ? createUnavailable(message, { ...params, retryable: false })
+                : createRateLimited(message, retry);
         }
         if (status === 429) {
-            const retryAfterMs = parseRetryAfterMs(headers);
-            const params = {
-                providerId: this.id,
-                runId: context.runId,
-                retryable: true,
-                details
-            };
-            if (retryAfterMs !== undefined) {
-                return createRateLimited(message, {
-                    ...params,
-                    retryAfterMs
-                });
-            }
-            return createRateLimited(message, params);
+            return createRateLimited(message, retry);
         }
         if (status === 408 || status === 504) {
-            return createTimeout(message, {
-                providerId: this.id,
-                runId: context.runId,
-                retryable: true,
-                details
-            });
+            return createTimeout(message, retry);
         }
         if (status === 409 || status >= 500) {
-            return createUnavailable(message, {
-                providerId: this.id,
-                runId: context.runId,
-                retryable: true,
-                details
-            });
+            return createUnavailable(message, retry);
         }
-        return createInternal(message, {
-            providerId: this.id,
-            runId: context.runId,
-            details
-        });
+        return createInternal(message, params);
     }
 }
 function createInput(request) {
@@ -563,3 +610,48 @@ function isRecord(value) {
 function getString(value) {
     return typeof value === "string" ? value : undefined;
 }
+/**
+ * The HTTP status OpenRouter documents for each typed `error_type`, so a typed
+ * failure is classified exactly like the equivalent HTTP error. Refusals and
+ * content-policy violations are documented as 403 but are not credential
+ * failures, so they classify as a rejected request (400). Unknown types return
+ * `undefined` and the native `code` decides instead.
+ */
+function openRouterErrorTypeStatus(errorType) {
+    return typeof errorType === "string" && Object.hasOwn(OPENROUTER_ERROR_TYPE_STATUS, errorType)
+        ? OPENROUTER_ERROR_TYPE_STATUS[errorType]
+        : undefined;
+}
+const OPENROUTER_ERROR_TYPE_STATUS = {
+    authentication: 401,
+    payment_required: 402,
+    permission_denied: 403,
+    rate_limit_exceeded: 429,
+    timeout: 504,
+    provider_unavailable: 502,
+    provider_overloaded: 503,
+    server: 500,
+    unmapped: 500,
+    not_found: 404,
+    image_not_found: 404,
+    precondition_failed: 412,
+    payload_too_large: 413,
+    unprocessable: 422,
+    content_policy_violation: 400,
+    refusal: 400,
+    context_length_exceeded: 400,
+    max_tokens_exceeded: 400,
+    token_limit_exceeded: 400,
+    string_too_long: 400,
+    invalid_request: 400,
+    invalid_prompt: 400,
+    invalid_image: 400,
+    image_too_large: 400,
+    image_too_small: 400,
+    unsupported_image_format: 400,
+    image_download_failed: 400
+};
+/** An error `code` as a detail string, whether the server sent a name or a numeric status. */
+function getErrorCode(value) {
+    return typeof value === "number" ? String(value) : getString(value);
+}

package/dist/web-sdk.d.ts

@@ -30,7 +30,8 @@ export interface CreateIndeRunWebOptions {
      */
     hostServices?: CreateBrowserHostServicesOptions;
     /**
-     * Explicit opt-in for calling the public OpenAI endpoint directly from this Web SDK factory.
+     * Explicit opt-in for calling a public Responses endpoint directly from this Web SDK factory —
+     * OpenAI's or OpenRouter's — with browser-held credentials.
      *
      * Browser apps should leave this unset and use a proxy endpoint with `openAI.auth = "none"` instead.
      * Direct calls can expose credentials to client-side code and are appropriate only for controlled

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,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"}
+{"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;;;;;;;OAOG;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

@@ -45,12 +45,12 @@ export function createIndeRunWeb(options) {
 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" && !allowDirectOpenAIEndpoint) {
+    const isDirectPublicEndpoint = isPublicResponsesEndpoint(endpointUrl);
+    if (isDirectPublicEndpoint && 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.');
     }
 }
-function isOpenAIResponsesEndpoint(endpointUrl) {
+function isPublicResponsesEndpoint(endpointUrl) {
     let parsed;
     try {
         parsed = new URL(endpointUrl);
@@ -59,5 +59,14 @@ function isOpenAIResponsesEndpoint(endpointUrl) {
         return false;
     }
     const pathname = parsed.pathname.replace(/\/+$/u, "");
-    return parsed.hostname.toLowerCase() === "api.openai.com" && pathname === "/v1/responses";
+    const endpoint = `${parsed.hostname.toLowerCase()}${pathname}`;
+    return PUBLIC_RESPONSES_ENDPOINTS.includes(endpoint);
 }
+/**
+ * Hosted Responses endpoints whose credentials are developer-owned API keys, which the
+ * factory keeps out of browser code unless `allowDirectOpenAIEndpoint` says otherwise.
+ */
+const PUBLIC_RESPONSES_ENDPOINTS = [
+    "api.openai.com/v1/responses",
+    "openrouter.ai/api/v1/responses"
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@independo/inderun-web",
-  "version": "0.4.0-rc.1",
+  "version": "0.4.0",
   "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": {
@@ -47,6 +47,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./provider": {
+      "types": "./dist/provider.d.ts",
+      "default": "./dist/provider.js"
+    },
     "./openai": {
       "types": "./dist/openai.d.ts",
       "default": "./dist/openai.js"
@@ -68,8 +72,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@independo/inderun-contracts": "^0.4.0-rc.1",
-    "@independo/inderun-route-core-wasm": "^0.4.0-rc.1"
+    "@independo/inderun-contracts": "^0.4.0",
+    "@independo/inderun-route-core-wasm": "^0.4.0"
   },
   "peerDependencies": {
     "@huggingface/transformers": "^4.0.0"

package/src/index.ts

@@ -1,100 +1,60 @@
 /**
- * Unified entry point for the IndeRun Web SDK (`@independo/inderun-web`).
+ * Application entry point for the IndeRun Web SDK (`@independo/inderun-web`).
  *
- * Everything a browser app needs to run and stream tasks is exported from here:
- * the engine, the routing and provider seams, host services, error and telemetry
- * types, and the contract types the SDK's own signatures use. Provider adapters
- * are the deliberate exception — each ships from its own subpath
- * (`/openai`, `/onnx`, `/system-model`) so this surface stays provider-agnostic.
+ * It leads with the primary text API (`generateText` / `streamText`) and the
+ * factory that builds a ready engine, then carries the advanced task API
+ * (`run()` / `stream()` / `checkCapabilities()`) and the contract, error and
+ * telemetry types those signatures use. See `docs/architecture/api-layering.md`.
+ *
+ * Two kinds of export live elsewhere on purpose:
+ * - provider-authoring and host-integration APIs ship from
+ *   `@independo/inderun-web/provider`;
+ * - provider adapters ship from their own subpaths (`/openai`, `/onnx`,
+ *   `/system-model`), so this surface stays provider-agnostic.
+ *
+ * The engine's internals (router, route planner bindings, Event Gate) are not
+ * exported at all.
  */
 
 /**
- * Host services: the platform capabilities the engine reads and calls through,
- * and the seams an embedder overrides to supply its own (custom transport,
- * credential storage, clock).
+ * The primary text API: one canonical request per call, over any `IndeRunApi`.
  */
 export {
-  type AbortSignalLike,
-  type ConnectivityService,
-  type DeviceConstraintsService,
-  type SecureStorageService,
-  type ClockService,
-  type HttpClientService,
-  type HttpRequest,
-  type HttpResponse,
-  type HttpStreamResponse,
-  type HttpStreamingClientService,
-  type HostServices,
-  type ThermalState
-} from "./core/host.js";
+  generateText,
+  streamText,
+  toTaskRequest,
+  TextStreamRetractedError,
+  type GeneratedText,
+  type StreamedText,
+  type TextExecutionOptions,
+  type TextGenerationOptions,
+  type TextStream
+} from "./facade/text.js";
 
 /**
- * The provider contract. Implement `ProviderAdapter` for a Mode 1 backend and add
- * a `stream` for Mode 2; the descriptor and dynamic capability check are what the
- * router plans against.
+ * The recommended way in: builds host services, registers the providers named in
+ * the options, and returns a ready engine.
  */
 export {
-  type ProviderDescriptor,
-  type ProviderDynamicCapabilities,
-  type ProviderCapabilitySnapshot,
-  type RunContext,
-  type ProviderAdapter,
-  type ProviderStreamContext,
-  type ProviderStreamEvent,
-  type StreamRun
-} from "./core/provider.js";
-
-/**
- * Per-run gatekeeper for a Mode 2 stream: assigns the sequence numbers callers
- * order by, and enforces that exactly one terminal outcome is produced with
- * nothing admitted after it. Exported for embedders driving a stream themselves.
- */
-export { EventGate } from "./core/event-gate.js";
-
-/** Holds the provider adapters a given engine instance can route to. */
-export { ProviderRegistry } from "./core/registry.js";
+  createIndeRunWeb,
+  type CreateIndeRunWebOptions,
+  type OpenAIFactoryOptions
+} from "./web-sdk.js";
 
 /**
- * Route selection. `Router` turns a request plus a host capability snapshot into
- * a provider chain; `WasmRoutePlanner` is the shared Rust planner behind it, and
- * the only planner the Web SDK has — there is no JavaScript fallback.
+ * Model profiles: application-defined names for ordered sets of targets that a
+ * request can route within. `"auto"` is built in.
  */
-export { type RouteSelection, Router } from "./core/router.js";
-export {
-  type RoutePlanner,
-  type PlannerOutcome,
-  type WasmUnavailableReason,
-  type SharedPlannerInput,
-  type SharedPlannerRoutePlan,
-  WasmRoutePlanner
-} from "./core/route-planner.js";
+export { AUTO_MODEL_PROFILE, type ModelProfiles } from "./core/model-profiles.js";
 
 /**
- * The normalized error taxonomy. Every failure the SDK surfaces is an
- * `IndeRunException` in one of these classes, whatever the provider raised.
+ * The advanced task API. `IndeRun` implements `IndeRunApi`; constructing one by
+ * hand takes a `ProviderRegistry` and `HostServices` from
+ * `@independo/inderun-web/provider`.
  */
-export {
-  type IndeRunExceptionParams,
-  IndeRunException,
-  createCapabilityMismatch,
-  createOffline,
-  createAuthError,
-  createRateLimited,
-  createTimeout,
-  createUnavailable,
-  createInternal,
-  toIndeRunException
-} from "./core/errors.js";
-
-/** The engine itself, and the app-facing API surface it implements. */
 export { IndeRun, type IndeRunOptions, type StreamHandleResult } from "./core/engine.js";
-
-/**
- * Model profiles: application-defined names for ordered sets of targets that a
- * request can route within. `"auto"` is built in.
- */
-export { AUTO_MODEL_PROFILE, type ModelProfiles } from "./core/model-profiles.js";
 export type { IndeRunApi } from "./core/generated/inderun-api.js";
+export type { ProviderCapabilitySnapshot, StreamRun } from "./core/provider.js";
 
 /**
  * The contract types this SDK's own signatures take and return.
@@ -105,13 +65,14 @@ export type { IndeRunApi } from "./core/generated/inderun-api.js";
  * This is the npm counterpart of Gradle `api(...)` on Android and `@_exported
  * import` on Swift — see
  * {@link https://github.com/independo-gmbh/inderun/issues/189 | #189}. The
- * host-service and telemetry blocks in this file re-export their halves of the
- * same contract surface for the same reason.
+ * telemetry block below and the host-service block of the `/provider` entry
+ * point re-export their halves of the same contract surface for the same reason.
  *
  * Depend on `@independo/inderun-contracts` directly only for what is not
  * re-exported here: the JSON Schemas and the `get*ValidationIssues` validators.
  */
 export type {
+  ExecutionProvenance,
   IndeRunError,
   IndeRunErrorClass,
   StreamEvent,
@@ -121,6 +82,13 @@ export type {
   TaskResult
 } from "@independo/inderun-contracts";
 
+/**
+ * The normalized error taxonomy. Every failure the SDK surfaces is an
+ * `IndeRunException` in one of these classes, whatever the provider raised.
+ * Provider authors create them with the `create*` helpers from `/provider`.
+ */
+export { IndeRunException, toIndeRunException } from "./core/errors.js";
+
 /**
  * Telemetry. Pass a `TelemetryService` to observe routing decisions and attempt
  * outcomes; the engine defaults to `NoOpTelemetryService`.
@@ -131,43 +99,3 @@ export {
   type TelemetryService,
   NoOpTelemetryService
 } from "./core/telemetry.js";
-
-/**
- * The browser implementations of the host services above, and the factory that
- * assembles them. Use these directly only when constructing `IndeRun` by hand.
- */
-export {
-  BrowserConnectivityService,
-  FetchHttpClient,
-  FetchStreamingHttpClient,
-  SystemClockService,
-  createBrowserHostServices,
-  type CreateBrowserHostServicesOptions,
-  type FetchHttpClientOptions
-} from "./core/browser-host.js";
-
-/**
- * The primary text API: one canonical request per call, over any `IndeRunApi`.
- * See `docs/architecture/api-layering.md`.
- */
-export {
-  generateText,
-  streamText,
-  toTaskRequest,
-  TextStreamRetractedError,
-  type GeneratedText,
-  type StreamedText,
-  type TextExecutionOptions,
-  type TextGenerationOptions,
-  type TextStream
-} from "./facade/text.js";
-
-/**
- * The recommended way in: builds host services, registers the providers named in
- * the options, and returns a ready engine.
- */
-export {
-  createIndeRunWeb,
-  type CreateIndeRunWebOptions,
-  type OpenAIFactoryOptions
-} from "./web-sdk.js";

package/src/provider.ts

@@ -0,0 +1,77 @@
+/**
+ * Provider-authoring and host-integration entry point
+ * (`@independo/inderun-web/provider`).
+ *
+ * For code that extends the engine rather than calls it: custom provider
+ * adapters, custom host services (transport, credential storage, clock), and
+ * assembling an `IndeRun` by hand from a `ProviderRegistry`. Applications that
+ * only call `generateText` / `streamText` or `run()` / `stream()` need nothing
+ * from here. Changes to this surface are called out in release notes.
+ */
+
+/**
+ * Host services: the platform capabilities the engine reads and calls through,
+ * and the seams an embedder overrides to supply its own.
+ */
+export {
+  type AbortSignalLike,
+  type ConnectivityService,
+  type DeviceConstraintsService,
+  type SecureStorageService,
+  type ClockService,
+  type HttpClientService,
+  type HttpRequest,
+  type HttpResponse,
+  type HttpStreamResponse,
+  type HttpStreamingClientService,
+  type HostServices,
+  type ThermalState
+} from "./core/host.js";
+
+/**
+ * The browser implementations of the host services above, and the factory that
+ * assembles them. Use these directly only when constructing `IndeRun` by hand.
+ */
+export {
+  BrowserConnectivityService,
+  FetchHttpClient,
+  FetchStreamingHttpClient,
+  SystemClockService,
+  createBrowserHostServices,
+  type CreateBrowserHostServicesOptions,
+  type FetchHttpClientOptions
+} from "./core/browser-host.js";
+
+/**
+ * The provider contract. Implement `ProviderAdapter` for a Mode 1 backend and add
+ * a `stream` for Mode 2; the descriptor and dynamic capability check are what the
+ * router plans against.
+ */
+export {
+  type ProviderDescriptor,
+  type ProviderDynamicCapabilities,
+  type ProviderCapabilitySnapshot,
+  type RunContext,
+  type ProviderAdapter,
+  type ProviderStreamContext,
+  type ProviderStreamEvent,
+  type StreamRun
+} from "./core/provider.js";
+
+/** Holds the provider adapters a given engine instance can route to. */
+export { ProviderRegistry } from "./core/registry.js";
+
+/**
+ * Constructors for the normalized error taxonomy. A provider maps every failure
+ * onto one of these classes; the engine does the rest.
+ */
+export {
+  type IndeRunExceptionParams,
+  createCapabilityMismatch,
+  createOffline,
+  createAuthError,
+  createRateLimited,
+  createTimeout,
+  createUnavailable,
+  createInternal
+} from "./core/errors.js";