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

package/src/facade/text.ts

@@ -0,0 +1,349 @@
+import type {
+  ExecutionProvenance,
+  StreamEvent,
+  StreamTerminalOutcome,
+  TaskRequest,
+  TaskResult
+} from "@independo/inderun-contracts";
+import { IndeRunException } from "../core/errors.js";
+import type { IndeRunApi } from "../core/generated/inderun-api.js";
+import { AUTO_MODEL_PROFILE } from "../core/model-profiles.js";
+
+/**
+ * The primary text API: `generateText()` and `streamText()`.
+ *
+ * Both are translation only. Each call compiles to exactly one canonical `TaskRequest`
+ * ({@link toTaskRequest}) and calls `run()` or `stream()` on the `IndeRunApi` it is given, so
+ * routing, fallback, cancellation, credentials, telemetry, and error normalization are the
+ * engine's and identical to a direct call. Written against the generated interface rather than
+ * the engine class, so anything that implements `IndeRunApi` -- a bridge included -- gets the
+ * same facade. See `docs/architecture/api-layering.md`.
+ */
+
+type Message = NonNullable<TaskRequest["messages"]>[number];
+
+/**
+ * Compact execution policy. Reuses the canonical enum values, so moving a call between the
+ * facade and `run()` never changes what a constraint means.
+ */
+export interface TextExecutionOptions {
+  /** `constraints.privacy`: how strict placement is, e.g. `"local_required"`. */
+  privacy?: NonNullable<TaskRequest["constraints"]>["privacy"];
+  /** `constraints.cloud`: `"forbidden"`, `"allowed"`, or `"required"`. */
+  cloud?: NonNullable<TaskRequest["constraints"]>["cloud"];
+  /** `constraints.timeoutMs`. */
+  timeoutMs?: number;
+  /** `preferences.optimizeFor`. */
+  optimizeFor?: NonNullable<TaskRequest["preferences"]>["optimizeFor"];
+}
+
+interface TextGenerationCommonOptions {
+  /**
+   * Model profile to route within, as configured on the engine. Omitted or `"auto"` routes
+   * across every registered target. Never a vendor model id.
+   */
+  model?: string;
+  /** Instructions sent as a leading `system` message. */
+  system?: string;
+  maxOutputTokens?: number;
+  temperature?: number;
+  topP?: number;
+  stop?: string[];
+  seed?: number;
+  execution?: TextExecutionOptions;
+  /** Secure-storage slot for provider credentials. Never a raw secret. */
+  authContextRef?: string;
+  telemetry?: TaskRequest["telemetry"];
+  /** Fixes the run id, for correlation. */
+  requestId?: string;
+}
+
+/** Options for {@link generateText} and {@link streamText}: a prompt or a message list. */
+export type TextGenerationOptions = TextGenerationCommonOptions &
+  ({ prompt: string; messages?: never } | { messages: Message[]; prompt?: never });
+
+/** What {@link generateText} returns. */
+export interface GeneratedText {
+  text: string;
+  finishReason: TaskResult["finishReason"];
+  usage?: TaskResult["usage"];
+  runId: string;
+  /** How the run played out; see `ExecutionProvenance`. */
+  provenance?: ExecutionProvenance;
+  /** The canonical result, for anything the summary above leaves out. */
+  taskResult: TaskResult;
+}
+
+/** How a {@link streamText} run ended, when it did not fail. */
+export interface StreamedText {
+  /** The full text, or the partial text a cancelled run had delivered. */
+  text: string;
+  /** `"cancelled"` when the run was cancelled; otherwise as the provider reported it. */
+  finishReason?: TaskResult["finishReason"];
+  usage?: TaskResult["usage"];
+  runId: string;
+  provenance?: ExecutionProvenance;
+  /** The canonical terminal outcome. */
+  outcome: StreamTerminalOutcome;
+}
+
+/** What {@link streamText} returns. */
+export interface TextStream {
+  runId: string;
+  /**
+   * Text increments, in order. Ends when the run completes or is cancelled; throws the run's
+   * `IndeRunException` when it fails, and {@link TextStreamRetractedError} when the provider
+   * replaces delivered text (use `fullStream` to render retractions).
+   */
+  textStream: AsyncIterable<string>;
+  /** The canonical `StreamEvent` sequence, terminal included. */
+  fullStream: AsyncIterable<StreamEvent>;
+  /**
+   * Settles with the run's ending: resolves on completion or cancellation, rejects with the
+   * run's `IndeRunException` on failure.
+   */
+  result: Promise<StreamedText>;
+  /** Cancels the run; idempotent. */
+  cancel(reason?: string): void;
+}
+
+/**
+ * Thrown by `textStream` when the provider replaces text it already delivered with text that
+ * does not extend it, which an append-only text view cannot represent.
+ */
+export class TextStreamRetractedError extends Error {
+  constructor(readonly runId: string) {
+    super(
+      `Run ${runId} replaced text it had already delivered; read fullStream to render retractions.`
+    );
+    this.name = "TextStreamRetractedError";
+  }
+}
+
+/** The canonical `TaskRequest` a facade call compiles to. */
+export function toTaskRequest(options: TextGenerationOptions): TaskRequest {
+  const request: TaskRequest = { schemaVersion: "1.0", task: { kind: "text_to_text" } };
+
+  if (options.system !== undefined) {
+    const conversation =
+      options.messages ??
+      (options.prompt !== undefined ? [{ role: "user" as const, content: options.prompt }] : []);
+    request.messages = [{ role: "system", content: options.system }, ...conversation];
+  } else if (options.messages !== undefined) {
+    // An empty list is the engine's to reject, with the same validation error as run().
+    request.messages = options.messages as NonNullable<TaskRequest["messages"]>;
+  } else if (options.prompt !== undefined) {
+    request.prompt = options.prompt;
+  }
+
+  if (options.model !== undefined && options.model !== AUTO_MODEL_PROFILE) {
+    request.modelProfile = options.model;
+  }
+
+  const generation: NonNullable<TaskRequest["generation"]> = {};
+  if (options.maxOutputTokens !== undefined) generation.maxOutputTokens = options.maxOutputTokens;
+  if (options.temperature !== undefined) generation.temperature = options.temperature;
+  if (options.topP !== undefined) generation.topP = options.topP;
+  if (options.stop !== undefined) generation.stop = options.stop;
+  if (options.seed !== undefined) generation.seed = options.seed;
+  if (Object.keys(generation).length > 0) request.generation = generation;
+
+  const execution = options.execution ?? {};
+  const constraints: NonNullable<TaskRequest["constraints"]> = {};
+  if (execution.privacy !== undefined) constraints.privacy = execution.privacy;
+  if (execution.cloud !== undefined) constraints.cloud = execution.cloud;
+  if (execution.timeoutMs !== undefined) constraints.timeoutMs = execution.timeoutMs;
+  if (Object.keys(constraints).length > 0) request.constraints = constraints;
+  if (execution.optimizeFor !== undefined) {
+    request.preferences = { optimizeFor: execution.optimizeFor };
+  }
+
+  if (options.authContextRef !== undefined) request.authContextRef = options.authContextRef;
+  if (options.telemetry !== undefined) request.telemetry = options.telemetry;
+  if (options.requestId !== undefined) request.requestId = options.requestId;
+
+  return request;
+}
+
+/**
+ * Generates text in one call: `run()` over the canonical request. Not cancellable, for the same
+ * reason `run()` is not; use {@link streamText} when cancellation matters.
+ * @throws {IndeRunException} Exactly as `run()` does.
+ */
+export async function generateText(
+  inderun: IndeRunApi,
+  options: TextGenerationOptions
+): Promise<GeneratedText> {
+  const taskResult = await inderun.run(toTaskRequest(options));
+  return {
+    text: taskResult.output.text,
+    finishReason: taskResult.finishReason,
+    ...(taskResult.usage !== undefined ? { usage: taskResult.usage } : {}),
+    runId: taskResult.runId,
+    ...(taskResult.provenance !== undefined ? { provenance: taskResult.provenance } : {}),
+    taskResult
+  };
+}
+
+/**
+ * Streams text: `stream()` over the canonical request. The run starts immediately and is read
+ * once, into a replay buffer, so `textStream`, `fullStream`, and `result` can each be consumed
+ * in any order (or not at all) without stalling the others.
+ * @throws {IndeRunException} Exactly as `stream()` does: validation and routing refusals reject
+ *   here, before there is a run.
+ */
+export async function streamText(
+  inderun: IndeRunApi,
+  options: TextGenerationOptions
+): Promise<TextStream> {
+  const run = await inderun.stream(toTaskRequest(options));
+  const runId = run.handle.runId;
+  const replay = new ReplayBuffer<StreamEvent>();
+
+  const result = (async (): Promise<StreamedText> => {
+    // The terminal event is the last one a run delivers, so it settles everything; a source
+    // that stays open after it (a bridge subscription, say) must not hold the result back.
+    // Releasing the source is not awaited for the same reason.
+    const events = run.events[Symbol.asyncIterator]();
+    try {
+      for (let next = await events.next(); next.done !== true; next = await events.next()) {
+        replay.push(next.value);
+        if (next.value.type === "terminal") {
+          void events.return?.()?.catch(() => undefined);
+          break;
+        }
+      }
+      replay.close();
+    } catch (error) {
+      replay.fail(error);
+      throw error;
+    }
+    const terminal = replay.items.find((event) => event.type === "terminal");
+    if (terminal === undefined) {
+      throw new IndeRunException({
+        errorClass: "Internal",
+        message: `Run ${runId} ended without a terminal event.`,
+        runId
+      });
+    }
+    return settle(terminal.payload as unknown as StreamTerminalOutcome);
+  })();
+  // Consumers may read only one view; an unread rejection must not surface as unhandled.
+  result.catch(() => undefined);
+
+  return {
+    runId,
+    fullStream: { [Symbol.asyncIterator]: () => replay.iterate() },
+    textStream: { [Symbol.asyncIterator]: () => textIncrements(replay.iterate(), runId) },
+    result,
+    cancel: (reason?: string) => run.cancel(reason)
+  };
+}
+
+function settle(outcome: StreamTerminalOutcome): StreamedText {
+  const provenance = outcome.provenance !== undefined ? { provenance: outcome.provenance } : {};
+  switch (outcome.outcome) {
+    case "completed":
+      return {
+        text: outcome.finalText ?? "",
+        ...(outcome.finishReason !== undefined ? { finishReason: outcome.finishReason } : {}),
+        ...(outcome.usage !== undefined ? { usage: outcome.usage } : {}),
+        runId: outcome.runId,
+        ...provenance,
+        outcome
+      };
+    case "cancelled":
+      return {
+        text: outcome.partialText ?? "",
+        finishReason: "cancelled",
+        runId: outcome.runId,
+        ...provenance,
+        outcome
+      };
+    case "error": {
+      const error = outcome.error!;
+      throw new IndeRunException({
+        errorClass: error.errorClass,
+        message: error.message,
+        runId: outcome.runId,
+        ...(error.providerId !== undefined ? { providerId: error.providerId } : {}),
+        ...(error.retryable !== undefined ? { retryable: error.retryable } : {}),
+        ...(error.retryAfterMs !== undefined ? { retryAfterMs: error.retryAfterMs } : {}),
+        ...(error.details !== undefined ? { details: error.details } : {}),
+        ...(outcome.provenance !== undefined ? { provenance: outcome.provenance } : {})
+      });
+    }
+  }
+}
+
+async function* textIncrements(
+  events: AsyncIterable<StreamEvent>,
+  runId: string
+): AsyncGenerator<string> {
+  let text = "";
+  for await (const event of events) {
+    if (event.type === "content_delta") {
+      const delta = (event.payload as { text: string }).text;
+      text += delta;
+      yield delta;
+    } else if (event.type === "content_snapshot") {
+      const snapshot = (event.payload as { text: string }).text;
+      if (!snapshot.startsWith(text)) {
+        throw new TextStreamRetractedError(runId);
+      }
+      const suffix = snapshot.slice(text.length);
+      text = snapshot;
+      if (suffix.length > 0) yield suffix;
+    } else if (event.type === "terminal") {
+      settle(event.payload as unknown as StreamTerminalOutcome);
+      return;
+    }
+  }
+}
+
+/**
+ * Holds every item read from a single-use source so any number of readers can iterate it from
+ * the start, each at its own pace. Readers that catch up wait for the next item.
+ */
+class ReplayBuffer<T> {
+  readonly items: T[] = [];
+  private done = false;
+  private failure: { error: unknown } | undefined;
+  private waiters: (() => void)[] = [];
+
+  push(item: T): void {
+    this.items.push(item);
+    this.wake();
+  }
+
+  close(): void {
+    this.done = true;
+    this.wake();
+  }
+
+  fail(error: unknown): void {
+    this.failure = { error };
+    this.close();
+  }
+
+  async *iterate(): AsyncGenerator<T> {
+    let index = 0;
+    while (true) {
+      if (index < this.items.length) {
+        yield this.items[index++]!;
+        continue;
+      }
+      if (this.done) {
+        if (this.failure !== undefined) throw this.failure.error;
+        return;
+      }
+      await new Promise<void>((resolve) => this.waiters.push(resolve));
+    }
+  }
+
+  private wake(): void {
+    const waiters = this.waiters;
+    this.waiters = [];
+    for (const wake of waiters) wake();
+  }
+}

package/src/index.ts

@@ -1,94 +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 StreamHandleResult } from "./core/engine.js";
+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.
@@ -99,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,
@@ -115,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`.
@@ -125,23 +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 recommended way in: builds host services, registers the providers named in
- * the options, and returns a ready engine.
- */
-export { createIndeRunWeb, type CreateIndeRunWebOptions } 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";

package/src/providers/onnx/provider.ts

@@ -101,6 +101,7 @@ export class OnnxRuntimeWebProvider implements ProviderAdapter {
     return {
       id: this.id,
       type: "local",
+      model: this.modelPackage.id,
       transport: "in_process",
       supports: {
         run: true,