@independo/inderun-web 0.3.0-dev.9 → 0.3.1-dev.1

package/src/core/errors.ts

@@ -0,0 +1,220 @@
+import type { IndeRunError, IndeRunErrorClass } from "@independo/inderun-contracts";
+
+/**
+ * Parameter structure required to initialize an IndeRunException.
+ */
+export interface IndeRunExceptionParams {
+  /**
+   * The standardized error class (e.g. 'CapabilityMismatch', 'Offline').
+   */
+  errorClass: IndeRunErrorClass;
+  /**
+   * Explanatory human-readable message.
+   */
+  message: string;
+  /**
+   * The unique run ID where this exception occurred.
+   */
+  runId?: string;
+  /**
+   * The provider ID that triggered the exception, if execution reached a provider.
+   */
+  providerId?: string;
+  /**
+   * Whether the client should retry this request.
+   */
+  retryable?: boolean;
+  /**
+   * Backoff time suggestion in milliseconds before retrying.
+   */
+  retryAfterMs?: number;
+  /**
+   * Rich contextual metadata regarding the error.
+   */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Standardized framework exception thrown when route selection or provider execution fails.
+ * Extends the native JavaScript Error class and exposes normalized error schema fields.
+ */
+export class IndeRunException extends Error {
+  /** The schema version matching the API contracts. */
+  readonly schemaVersion = "1.0";
+  /** The categorized class of error. */
+  readonly errorClass: IndeRunErrorClass;
+  /** The unique execution run ID. */
+  readonly runId?: string;
+  /** The provider ID responsible for the error. */
+  readonly providerId?: string;
+  /** Whether the error is transient and retryable. */
+  readonly retryable?: boolean;
+  /** Suggested cooling-down time in milliseconds before retry. */
+  readonly retryAfterMs?: number;
+  /** Custom details and metadata context. */
+  readonly details?: Record<string, unknown>;
+
+  constructor(params: IndeRunExceptionParams) {
+    super(params.message);
+    this.name = "IndeRunException";
+    this.errorClass = params.errorClass;
+    if (params.runId !== undefined) this.runId = params.runId;
+    if (params.providerId !== undefined) this.providerId = params.providerId;
+    if (params.retryable !== undefined) this.retryable = params.retryable;
+    if (params.retryAfterMs !== undefined) this.retryAfterMs = params.retryAfterMs;
+    if (params.details !== undefined) this.details = params.details;
+
+    Object.setPrototypeOf(this, IndeRunException.prototype);
+  }
+
+  /**
+   * Converts the exception into a JSON-compatible contract-compliant IndeRunError.
+   */
+  toContractError(): IndeRunError {
+    const err: IndeRunError = {
+      schemaVersion: this.schemaVersion,
+      errorClass: this.errorClass,
+      message: this.message
+    };
+    if (this.runId !== undefined) err.runId = this.runId;
+    if (this.providerId !== undefined) err.providerId = this.providerId;
+    if (this.retryable !== undefined) err.retryable = this.retryable;
+    if (this.retryAfterMs !== undefined) err.retryAfterMs = this.retryAfterMs;
+    if (this.details !== undefined) err.details = this.details;
+    return err;
+  }
+}
+
+/**
+ * Factory helper for CapabilityMismatch error class.
+ */
+export function createCapabilityMismatch(
+  message: string,
+  extra?: Omit<IndeRunExceptionParams, "errorClass" | "message">
+): IndeRunException {
+  return new IndeRunException({ errorClass: "CapabilityMismatch", message, ...extra });
+}
+
+/**
+ * Factory helper for Offline error class.
+ */
+export function createOffline(
+  message: string,
+  extra?: Omit<IndeRunExceptionParams, "errorClass" | "message">
+): IndeRunException {
+  return new IndeRunException({ errorClass: "Offline", message, ...extra });
+}
+
+/**
+ * Factory helper for AuthError error class.
+ */
+export function createAuthError(
+  message: string,
+  extra?: Omit<IndeRunExceptionParams, "errorClass" | "message">
+): IndeRunException {
+  return new IndeRunException({ errorClass: "AuthError", message, ...extra });
+}
+
+/**
+ * Factory helper for RateLimited error class.
+ */
+export function createRateLimited(
+  message: string,
+  extra?: Omit<IndeRunExceptionParams, "errorClass" | "message">
+): IndeRunException {
+  return new IndeRunException({ errorClass: "RateLimited", message, ...extra });
+}
+
+/**
+ * Factory helper for Timeout error class.
+ */
+export function createTimeout(
+  message: string,
+  extra?: Omit<IndeRunExceptionParams, "errorClass" | "message">
+): IndeRunException {
+  return new IndeRunException({ errorClass: "Timeout", message, ...extra });
+}
+
+/**
+ * Factory helper for Unavailable error class.
+ */
+export function createUnavailable(
+  message: string,
+  extra?: Omit<IndeRunExceptionParams, "errorClass" | "message">
+): IndeRunException {
+  return new IndeRunException({ errorClass: "Unavailable", message, ...extra });
+}
+
+/**
+ * Factory helper for Internal error class.
+ */
+export function createInternal(
+  message: string,
+  extra?: Omit<IndeRunExceptionParams, "errorClass" | "message">
+): IndeRunException {
+  return new IndeRunException({ errorClass: "Internal", message, ...extra });
+}
+
+/**
+ * Standardizes any caught error into an IndeRunException.
+ * If the input error is already an IndeRunException, merges additional fallback parameters (like totalMs).
+ */
+export function toIndeRunException(
+  error: unknown,
+  fallbackParams?: Partial<Omit<IndeRunExceptionParams, "message">>
+): IndeRunException {
+  if (error instanceof IndeRunException) {
+    if (fallbackParams) {
+      const mergedParams: IndeRunExceptionParams = {
+        errorClass: error.errorClass,
+        message: error.message
+      };
+
+      const runId = error.runId ?? fallbackParams.runId;
+      if (runId !== undefined) mergedParams.runId = runId;
+
+      const providerId = error.providerId ?? fallbackParams.providerId;
+      if (providerId !== undefined) mergedParams.providerId = providerId;
+
+      const retryable = error.retryable ?? fallbackParams.retryable;
+      if (retryable !== undefined) mergedParams.retryable = retryable;
+
+      const retryAfterMs = error.retryAfterMs ?? fallbackParams.retryAfterMs;
+      if (retryAfterMs !== undefined) mergedParams.retryAfterMs = retryAfterMs;
+
+      if (error.details !== undefined || fallbackParams.details !== undefined) {
+        mergedParams.details = {
+          ...(error.details || {}),
+          ...(fallbackParams.details || {})
+        };
+      }
+
+      return new IndeRunException(mergedParams);
+    }
+    return error;
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  const details: Record<string, unknown> = {
+    ...(fallbackParams?.details || {})
+  };
+
+  if (error instanceof Error) {
+    details.originalError = {
+      name: error.name,
+      message: error.message,
+      stack: error.stack
+    };
+  } else {
+    details.originalError = {
+      message: String(error)
+    };
+  }
+
+  return new IndeRunException({
+    errorClass: "Internal",
+    message,
+    ...fallbackParams,
+    details
+  });
+}

package/src/core/event-gate.ts

@@ -0,0 +1,71 @@
+import type { StreamEvent, StreamTerminalOutcome } from "@independo/inderun-contracts";
+
+/**
+ * Per-run gatekeeper for Mode 2 streaming. Enforces the two structural guarantees
+ * required by the streaming orchestrator: exactly one terminal outcome is ever
+ * produced for a run, and no event is admitted after that terminal outcome fires.
+ *
+ * Correctness relies on `admit`/`terminate` performing their check-and-set
+ * synchronously with no `await` in between — safe under JS's single-threaded,
+ * run-to-completion semantics even with interleaved `await` resumption elsewhere
+ * (e.g. a provider's async iterator and a caller's `cancel()` racing).
+ */
+export class EventGate {
+  private sequence = 0;
+  private terminated = false;
+  private terminalOutcome: StreamTerminalOutcome | undefined;
+
+  constructor(private readonly runId: string) {}
+
+  /**
+   * Admits a non-terminal StreamEvent, assigning it the next monotonic sequence
+   * number. Returns null (suppressing the event) if the run has already terminated.
+   */
+  admit(event: {
+    timestamp: number;
+    type: string;
+    payload?: StreamEvent["payload"];
+  }): StreamEvent | null {
+    if (this.terminated) {
+      return null;
+    }
+    return {
+      runId: this.runId,
+      schemaVersion: "1.0",
+      sequence: this.sequence++,
+      timestamp: event.timestamp,
+      type: event.type,
+      ...(event.payload !== undefined ? { payload: event.payload } : {})
+    };
+  }
+
+  /**
+   * Terminates the run with the given outcome. First writer wins: only the first
+   * call produces a terminal StreamEvent and stores the outcome; every subsequent
+   * call (duplicate provider "done", late error after cancel, concurrent cancel()
+   * calls) is a silent no-op that returns null, making repeated cancellation safe.
+   */
+  terminate(outcome: StreamTerminalOutcome, timestamp: number): StreamEvent | null {
+    if (this.terminated) {
+      return null;
+    }
+    this.terminated = true;
+    this.terminalOutcome = outcome;
+    return {
+      runId: this.runId,
+      schemaVersion: "1.0",
+      sequence: this.sequence++,
+      timestamp,
+      type: "terminal",
+      payload: outcome
+    };
+  }
+
+  isTerminated(): boolean {
+    return this.terminated;
+  }
+
+  getOutcome(): StreamTerminalOutcome | undefined {
+    return this.terminalOutcome;
+  }
+}

package/src/core/generated/inderun-api.ts

@@ -0,0 +1,19 @@
+/* This file was generated from contracts/api/inderun-api.json. Do not edit by hand. */
+
+import type { TaskRequest, TaskResult } from "@independo/inderun-contracts";
+import type { StreamRun, ProviderCapabilitySnapshot } from "../provider.js";
+
+export interface IndeRunApi {
+  /**
+   * Executes a Mode 1 (request/response) text-to-text task against a routed provider and returns the completed TaskResult. Routing (local vs. cloud, which provider) is decided internally from TaskRequest.constraints/preferences — the caller does not select a provider directly. Rejects the request up front on validation failure; otherwise throws an IndeRunException (carrying an IndeRunError) if no eligible provider is found or every attempted provider fails. There is no partial or streaming result in this mode: run() either resolves with a complete TaskResult or throws.
+   */
+  run(request: TaskRequest): Promise<TaskResult>;
+  /**
+   * Executes a Mode 2 (streaming) text-to-text task and returns a handle to the run, its canonical StreamEvent sequence, and a cancel hook. The requested interaction mode is a routing input rather than a filter applied after routing: providers that cannot stream are rejected during planning with a normalized reason, so a stream and a run over the same registry may legitimately resolve to different provider chains. Two failure surfaces exist deliberately — validation and route-selection failures reject this call, since there is no handle to correlate them with yet, while provider failure, cancellation, and completion all arrive as the single terminal StreamEvent in the returned sequence. Fallback is narrower than run()'s: a provider failure is only fallback-eligible before the first content event has been delivered; once one has, the run is committed to that provider and a later failure becomes a terminal error rather than a silent provider swap. Cancellation forecloses both at any commit state and always produces exactly one cancelled outcome.
+   */
+  stream(request: TaskRequest): Promise<StreamRun>;
+  /**
+   * Returns a live snapshot of every registered provider's static descriptor and current dynamic availability, without executing a task or producing any side effects. Call this before run() when you need to show which providers/models are currently available — for example a settings screen or provider picker. Availability can change between calls (a local model can unload, cloud credentials can expire), so don't cache the result across a run() call.
+   */
+  checkCapabilities(): Promise<ProviderCapabilitySnapshot[]>;
+}

package/src/core/host.ts

@@ -0,0 +1,15 @@
+export type {
+  AbortSignalLike,
+  ClockService,
+  ConnectivityService,
+  DeviceConstraintsService,
+  HostServices,
+  HttpClientService,
+  HttpRequest,
+  HttpResponse,
+  HttpStreamResponse,
+  HttpStreamingClientService,
+  SecureStorageService,
+  TelemetryService,
+  ThermalState
+} from "@independo/inderun-contracts";

package/src/core/provider.ts

@@ -0,0 +1,231 @@
+import type {
+  StreamEvent,
+  StreamRunHandle,
+  TaskRequest,
+  TaskResult
+} from "@independo/inderun-contracts";
+import type { HostServices } from "./host.js";
+
+/**
+ * Static metadata descriptor defining the capabilities, requirements, and constraints
+ * of a provider. This is used by the routing engine and Router to select candidate providers.
+ */
+export interface ProviderDescriptor {
+  /**
+   * Unique identifier of the provider (e.g., 'openai', 'apple-foundation-models').
+   */
+  id: string;
+  /**
+   * Execution target type: 'local' (on-device), 'edge', or 'cloud'.
+   */
+  type: "local" | "edge" | "cloud";
+  /**
+   * Connection transport layer protocol.
+   */
+  transport: "in_process" | "system_service" | "http" | "sse" | "realtime";
+  /**
+   * Optional streaming style, if token or chunk streaming is supported.
+   */
+  streamingStyle?: "tokens" | "chunks" | "snapshots";
+
+  /**
+   * Flags representing the features and modes supported by this provider.
+   */
+  supports: {
+    /** Whether the provider supports Mode 1 run (request/response). */
+    run: boolean;
+    /** Whether the provider supports Mode 2 stream. */
+    streaming: boolean;
+    /** Whether the provider supports Mode 3 realtime session. */
+    realtime: boolean;
+    /** Whether the provider supports tool calling definition. */
+    tools: boolean;
+    /** Whether the provider outputs reasoning events alongside contents. */
+    reasoningEvents: boolean;
+    /** Whether the provider supports structured outputs (JSON schema constraints). */
+    structuredOutput: boolean;
+    /** Whether the provider supports multimodal inputs (images, audio, etc.). */
+    multimodal: boolean;
+  };
+
+  /**
+   * Cancellation capabilities support:
+   * - 'hard': fully stops processing and interrupts remote operations.
+   * - 'soft': stops reading the stream locally, but the remote execution continues.
+   * - 'none': cancellation is unsupported.
+   */
+  cancel: "hard" | "soft" | "none";
+
+  /**
+   * List of supported task kinds (e.g., 'text_to_text', 'embeddings').
+   */
+  tasks: string[];
+
+  /**
+   * Optional input/output resource boundaries.
+   */
+  limits?: {
+    maxInputTokens?: number;
+    maxOutputTokens?: number;
+    maxImageBytes?: number;
+    maxAudioSeconds?: number;
+  };
+
+  /**
+   * Privacy settings regarding data egress.
+   */
+  privacy?: {
+    /** Set to true if the model input leaves the host device. */
+    dataLeavesDevice: boolean;
+    /** Geographic regions where the cloud service executes. */
+    regions?: string[];
+  };
+}
+
+/**
+ * Dynamic capability snapshot evaluated at runtime.
+ */
+export interface ProviderDynamicCapabilities {
+  /**
+   * Whether the provider is available and functional on the host device now.
+   */
+  available: boolean;
+  /**
+   * Detail message if availability check fails.
+   */
+  reason?: string;
+  /**
+   * Whether the provider can stream (Mode 2) right now on this host. Leave
+   * undefined to inherit the static `descriptor.supports.streaming` value —
+   * only set it when the runtime environment can take streaming away from a
+   * provider that otherwise declares it (e.g. the host has no chunked HTTP
+   * capability).
+   */
+  streamingAvailable?: boolean;
+  /**
+   * Detail message used when `streamingAvailable` is false. Omit to let the
+   * route planner synthesize a generic message.
+   */
+  streamingUnavailableReason?: string;
+  /**
+   * Whether cancellation is honored right now on this host. Leave undefined to
+   * inherit the static `descriptor.cancel` value (anything other than `"none"`
+   * means available).
+   */
+  cancellationAvailable?: boolean;
+}
+
+/**
+ * One registered provider's identity, fixed capabilities, and live availability,
+ * as of the moment checkCapabilities() was called.
+ */
+export interface ProviderCapabilitySnapshot {
+  /**
+   * Stable identifier for this provider, matching the value used in routing
+   * preferences/constraints.
+   */
+  providerId: string;
+  /**
+   * The provider's static, unchanging capability declaration (supported modes,
+   * privacy posture, model info).
+   */
+  descriptor: ProviderDescriptor;
+  /**
+   * The provider's current dynamic availability (e.g. whether it's reachable/loaded
+   * right now) — this is the part that can change between calls.
+   */
+  capabilities: ProviderDynamicCapabilities;
+}
+
+/**
+ * Execution context passed to provider run commands.
+ */
+export interface RunContext {
+  /**
+   * Unique execution run ID.
+   */
+  runId: string;
+  /**
+   * Host service boundary for provider adapters. Cloud adapters use this to
+   * resolve authContextRef through secure storage and dispatch HTTP requests.
+   */
+  hostServices: HostServices;
+}
+
+/**
+ * Execution context passed to provider stream commands. Extends RunContext with the
+ * caller-driven cancellation signal; the Engine core owns the AbortController and
+ * threads its signal here, so providers never need to construct their own.
+ */
+export interface ProviderStreamContext extends RunContext {
+  /**
+   * Signals caller-driven cancellation of this stream. Providers with `cancel: "hard"`
+   * should tear down their connection immediately on abort; `cancel: "soft"` providers
+   * may stop relaying events without interrupting underlying local work; `cancel:
+   * "none"` providers may ignore it entirely; the engine enforces the caller-visible
+   * cancellation guarantee at the consumer loop regardless of what the provider does.
+   */
+  signal: AbortSignal;
+}
+
+/**
+ * A raw, provider-shaped streaming event yielded by ProviderAdapter.stream(). This is
+ * intentionally distinct from the canonical StreamEvent contract: providers emit
+ * provider-shaped deltas here, and the Engine core's Event Gate normalizes these into
+ * StreamEvent/StreamTerminalOutcome, keeping provider-specific mechanics from leaking
+ * through the public API.
+ */
+export type ProviderStreamEvent =
+  | { kind: "delta"; text: string }
+  | { kind: "snapshot"; text: string }
+  | {
+      kind: "done";
+      finalText: string;
+      /**
+       * How generation ended, when the provider reports it. Mirrors
+       * `TaskResult.finishReason` for Mode 1 and surfaces on the `completed`
+       * terminal outcome; omit when the provider gives no signal.
+       */
+      finishReason?: TaskResult["finishReason"];
+      usage?: TaskResult["usage"];
+    }
+  | { kind: "error"; error: unknown };
+
+/**
+ * Pluggable execution adapter contract that wraps a specific model runtime
+ * (system frameworks, local runtimes, or cloud APIs) and exposes normalized APIs.
+ */
+export interface ProviderAdapter {
+  /**
+   * Returns static provider descriptor metadata.
+   */
+  describe(): ProviderDescriptor;
+  /**
+   * Performs dynamic capability check to determine if the provider can execute now.
+   */
+  capabilities(host: HostServices): Promise<ProviderDynamicCapabilities>;
+  /**
+   * Executes a task request in Mode 1 (request/response).
+   */
+  run(req: TaskRequest, ctx: RunContext): Promise<TaskResult>;
+  /**
+   * Executes a task request in Mode 2 (streaming). Optional: only providers declaring
+   * `describe().supports.streaming === true` are expected to implement this.
+   */
+  stream?(req: TaskRequest, ctx: ProviderStreamContext): AsyncIterable<ProviderStreamEvent>;
+}
+
+/**
+ * What `IndeRun.stream()` returns: the run's identity, its canonical event
+ * sequence, and a cancel hook.
+ *
+ * `events` terminates in exactly one terminal `StreamEvent`, per the Event
+ * Gate's guarantee, and is single-use — the run is driven once, not restarted
+ * per consumer. `cancel()` is idempotent: repeated or concurrent calls produce
+ * exactly one `cancelled` terminal outcome.
+ */
+export interface StreamRun {
+  handle: StreamRunHandle;
+  events: AsyncIterable<StreamEvent>;
+  cancel(reason?: string): void;
+}

package/src/core/registry.ts

@@ -0,0 +1,48 @@
+import type { ProviderAdapter } from "./provider.js";
+
+/**
+ * Registry class that holds and manages all active ProviderAdapter instances.
+ * Loaded adapters are queried by the Router to choose appropriate routes.
+ */
+export class ProviderRegistry {
+  private providers = new Map<string, ProviderAdapter>();
+
+  /**
+   * Registers a provider adapter in the registry.
+   * @param provider - The provider adapter instance to register.
+   * @throws {Error} If the provider does not have a valid ID.
+   * @throws {Error} If another provider is already registered with the same ID.
+   */
+  register(provider: ProviderAdapter): void {
+    const descriptor = provider.describe();
+    if (!descriptor.id) {
+      throw new Error("Provider must have a non-empty ID.");
+    }
+    if (this.providers.has(descriptor.id)) {
+      throw new Error(`Provider with ID "${descriptor.id}" is already registered.`);
+    }
+    this.providers.set(descriptor.id, provider);
+  }
+
+  /**
+   * Retrieves a registered provider by its ID.
+   * @param id - Unique provider identifier.
+   */
+  get(id: string): ProviderAdapter | undefined {
+    return this.providers.get(id);
+  }
+
+  /**
+   * Returns a list of all registered provider adapters.
+   */
+  list(): ProviderAdapter[] {
+    return Array.from(this.providers.values());
+  }
+
+  /**
+   * Clears all registered providers.
+   */
+  clear(): void {
+    this.providers.clear();
+  }
+}