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

package/README.md

@@ -10,7 +10,18 @@ TypeScript/Web SDK for IndeRun.
 
 This package provides the Web SDK entrypoint, the engine core, routing, telemetry, error normalization, the OpenAI-compatible cloud provider, the Web ONNX Runtime provider for developer-supplied local models, and the Web system-model provider for browser-managed on-device models.
 
-The contract types this SDK's own signatures take and return — `TaskRequest`, `TaskResult`, `StreamEvent`, `StreamRunHandle`, `StreamTerminalOutcome`, `IndeRunError`, the host-service and telemetry interfaces, and (from the `/onnx` subpath) `ModelPackage` — are re-exported here, so a fully typed app does not need to depend on `@independo/inderun-contracts` separately. Import that package directly only if you want the JSON Schemas or the `get*ValidationIssues` validators.
+The contract types this SDK's own signatures take and return — `TaskRequest`, `TaskResult`, `StreamEvent`, `StreamRunHandle`, `StreamTerminalOutcome`, `IndeRunError`, `ExecutionProvenance`, the telemetry interfaces, the host-service interfaces (from `/provider`), and (from the `/onnx` subpath) `ModelPackage` — are re-exported here, so a fully typed app does not need to depend on `@independo/inderun-contracts` separately. Import that package directly only if you want the JSON Schemas or the `get*ValidationIssues` validators.
+
+## Entry points
+
+| Import | For | Contains |
+| --- | --- | --- |
+| `@independo/inderun-web` | Applications | `generateText` / `streamText`, `createIndeRunWeb`, the advanced task API (`IndeRun`, `run()` / `stream()` / `checkCapabilities()`), model profiles, contract types, `IndeRunException`, telemetry |
+| `@independo/inderun-web/provider` | Provider authors and host integrators | `ProviderAdapter` and the descriptor/capability types, `ProviderRegistry`, `HostServices` and the browser host services, the `create*` error constructors |
+| `@independo/inderun-web/openai`, `/onnx`, `/system-model` | Registering a provider by hand | One provider adapter each |
+
+The router, the route planner bindings and the Event Gate are engine internals and are not exported. Moving from 0.3?
+See the [migration guide](https://github.com/independo-gmbh/inderun/blob/main/docs/migration.md).
 
 ## Basic Usage
 
@@ -41,6 +52,13 @@ default `"auto"`), the usual sampling options, and an `execution` policy that re
 constraint values. Each call compiles to one `TaskRequest` — `toTaskRequest(options)` shows which —
 and runs through the engine below, so errors, fallback, and cancellation match the advanced API.
 
+## Advanced: the task API
+
+Use `TaskRequest` with `run()` / `stream()` when you need the raw event sequence, build requests in code (for example
+with your own `requestId`), or check capabilities before offering an option —
+`await inderun.checkCapabilities()` reports every registered target's live availability. Both layers run through the
+same engine.
+
 ## Streaming
 
 For the full event sequence, use the advanced API. `stream()` returns the run handle, its canonical `StreamEvent` sequence, and a `cancel()` hook:
@@ -75,6 +93,9 @@ accept `"stream": true` and emit `text/event-stream` with the Responses event ty
 response object. Unknown event types are ignored, so an endpoint that emits extra events is
 fine; one that emits a different vocabulary entirely is not.
 
+[OpenRouter](https://github.com/independo-gmbh/inderun/blob/main/docs/openrouter.md) is reached this way: point
+`endpointUrl` at its Responses endpoint (through a proxy in browser apps) and list `vendor/model` ids as `models`.
+
 ## Security Model
 
 Browser apps should use a proxy endpoint and keep provider credentials server-side. `createIndeRunWeb` rejects direct calls to the public OpenAI Responses endpoint unless `allowDirectOpenAIEndpoint: true` is set for a controlled environment.
@@ -87,10 +108,17 @@ distributed client code — put it behind a trusted backend proxy and point `end
 ## Advanced: registering the OpenAI provider directly
 
 `createIndeRunWeb` wires the OpenAI Responses provider for you. To register it
-manually (e.g. alongside other providers), import it from the provider subpath:
+manually (e.g. alongside other providers), import it from the provider subpath and build the engine from
+the `/provider` entry point:
 
 ```ts
+import { IndeRun } from "@independo/inderun-web";
 import { OpenAIResponsesProvider } from "@independo/inderun-web/openai";
+import { ProviderRegistry, createBrowserHostServices } from "@independo/inderun-web/provider";
+
+const registry = new ProviderRegistry();
+registry.register(new OpenAIResponsesProvider({ model: "gpt-5.2", endpointUrl: "/api/inderun/openai-responses", auth: "none" }));
+const inderun = new IndeRun(registry, createBrowserHostServices());
 ```
 
 The provider normalizes OpenAI transport and API failures into the IndeRun error

package/dist/index.d.ts

@@ -1,52 +1,42 @@
 /**
- * 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.
- */
-/**
- * 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).
- */
-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 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";
-/**
- * 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.
+ * 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.
  */
-export { EventGate } from "./core/event-gate.js";
-/** Holds the provider adapters a given engine instance can route to. */
-export { ProviderRegistry } from "./core/registry.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.
+ * The primary text API: one canonical request per call, over any `IndeRunApi`.
  */
-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 { generateText, streamText, toTaskRequest, TextStreamRetractedError, type GeneratedText, type StreamedText, type TextExecutionOptions, type TextGenerationOptions, type TextStream } from "./facade/text.js";
 /**
- * The normalized error taxonomy. Every failure the SDK surfaces is an
- * `IndeRunException` in one of these classes, whatever the provider raised.
+ * The recommended way in: builds host services, registers the providers named in
+ * the options, and returns a ready engine.
  */
-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";
+export { createIndeRunWeb, type CreateIndeRunWebOptions, type OpenAIFactoryOptions } from "./web-sdk.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";
+/**
+ * The advanced task API. `IndeRun` implements `IndeRunApi`; constructing one by
+ * hand takes a `ProviderRegistry` and `HostServices` from
+ * `@independo/inderun-web/provider`.
+ */
+export { IndeRun, type IndeRunOptions, type StreamHandleResult } from "./core/engine.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.
  *
@@ -56,31 +46,22 @@ 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 { IndeRunError, IndeRunErrorClass, StreamEvent, StreamRunHandle, StreamTerminalOutcome, TaskRequest, TaskResult } from "@independo/inderun-contracts";
+export type { ExecutionProvenance, IndeRunError, IndeRunErrorClass, StreamEvent, StreamRunHandle, StreamTerminalOutcome, TaskRequest, 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`.
  */
 export { type TelemetryEventType, type TelemetryEvent, 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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;GAIG;AACH,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,OAAO,EACL,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAE1B,uEAAuE;AACvE,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEzF;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAClF,YAAY,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE;;;;;;;;;;;;;;GAcG;AACH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,UAAU,EACX,MAAM,8BAA8B,CAAC;AAEtC;;;GAGG;AACH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAE7B;;;GAGG;AACH,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,wBAAwB,EACxB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,gCAAgC,EACrC,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAEhC;;;GAGG;AACH,OAAO,EACL,YAAY,EACZ,UAAU,EACV,aAAa,EACb,wBAAwB,EACxB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAE1B;;;GAGG;AACH,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;GAEG;AACH,OAAO,EACL,YAAY,EACZ,UAAU,EACV,aAAa,EACb,wBAAwB,EACxB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAE1B;;;GAGG;AACH,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAEtB;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAElF;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACzF,YAAY,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAClE,YAAY,EAAE,0BAA0B,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEhF;;;;;;;;;;;;;;GAcG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,UAAU,EACX,MAAM,8BAA8B,CAAC;AAEtC;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;GAGG;AACH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,oBAAoB,EACrB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,68 +1,48 @@
 /**
- * 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 {} from "./core/host.js";
+export { generateText, streamText, toTaskRequest, TextStreamRetractedError } 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 {} from "./core/provider.js";
+export { createIndeRunWeb } from "./web-sdk.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.
+ * Model profiles: application-defined names for ordered sets of targets that a
+ * request can route within. `"auto"` is built in.
  */
-export { EventGate } from "./core/event-gate.js";
-/** Holds the provider adapters a given engine instance can route to. */
-export { ProviderRegistry } from "./core/registry.js";
+export { AUTO_MODEL_PROFILE } from "./core/model-profiles.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.
+ * The advanced task API. `IndeRun` implements `IndeRunApi`; constructing one by
+ * hand takes a `ProviderRegistry` and `HostServices` from
+ * `@independo/inderun-web/provider`.
  */
-export { Router } from "./core/router.js";
-export { WasmRoutePlanner } from "./core/route-planner.js";
+export { IndeRun } from "./core/engine.js";
 /**
  * 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, 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 } 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 } from "./core/model-profiles.js";
+export { IndeRunException, toIndeRunException } from "./core/errors.js";
 /**
  * Telemetry. Pass a `TelemetryService` to observe routing decisions and attempt
  * outcomes; the engine defaults to `NoOpTelemetryService`.
  */
 export { 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 } 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 } 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 } from "./web-sdk.js";

package/dist/provider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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";
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,wBAAwB,EACxB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,gCAAgC,EACrC,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAEhC;;;;GAIG;AACH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAE5B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,OAAO,EACL,KAAK,sBAAsB,EAC3B,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACf,MAAM,kBAAkB,CAAC"}

package/dist/provider.js

@@ -0,0 +1,33 @@
+/**
+ * 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 {} 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 } 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 {} 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 { createCapabilityMismatch, createOffline, createAuthError, createRateLimited, createTimeout, createUnavailable, createInternal } from "./core/errors.js";

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

@@ -101,7 +101,9 @@ export declare class OpenAIResponsesProvider implements ProviderAdapter {
      * - `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.
@@ -109,17 +111,31 @@ export declare class OpenAIResponsesProvider implements ProviderAdapter {
      */
     stream(request: TaskRequest, context: ProviderStreamContext): AsyncGenerator<ProviderStreamEvent>;
     /**
-     * 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).
      */
     private mapStreamError;
+    /**
+     * 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.
+     */
+    private mapReportedError;
     /**
      * Resolves the request headers, including the bearer token behind
      * `authContextRef`. Shared by `run` and `stream`: the credential never travels
@@ -129,13 +145,27 @@ export declare class OpenAIResponsesProvider implements ProviderAdapter {
     private resolveHeaders;
     private createRequestBody;
     /**
-     * Maps an OpenAI HTTP error response onto the IndeRun error taxonomy:
+     * Maps an OpenAI HTTP error response onto the IndeRun error taxonomy by its
+     * status (see `errorForStatus`), honoring `Retry-After` on whichever status
+     * carries it.
+     */
+    private mapHttpError;
+    /**
+     * The status classification shared by HTTP errors and numeric in-body codes:
      * - `401` / `403` → `AuthError`
-     * - `429` → `RateLimited` (honors `Retry-After` when present)
+     * - `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 non-2xx status → `Internal`
+     * - 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.
      */
-    private mapHttpError;
+    private errorForStatus;
 }
 //# sourceMappingURL=provider.d.ts.map

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;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"}
+{"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;AAS5E,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;AA0ChC,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;AA+BD;;;;;;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;IAyGzE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,MAAM,CACX,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAAC,mBAAmB,CAAC;IA0GtC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;IActB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,gBAAgB;IAyCxB;;;;;OAKG;YACW,cAAc;IA2C5B,OAAO,CAAC,iBAAiB;IA2BzB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAuBpB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,cAAc;CAmCvB"}