@independo/inderun-web 0.3.0-dev.8 → 0.3.0

package/src/providers/system-model/chrome-runtime.ts

@@ -0,0 +1,221 @@
+import {
+  SystemModelRuntimeError,
+  type SystemModelAvailability,
+  type SystemModelGenerationInput,
+  type SystemModelGenerationOutput,
+  type SystemModelRuntime
+} from "./runtime.js";
+
+/**
+ * Structural view of the Chrome/Edge Prompt API's `LanguageModel` global this runtime uses.
+ *
+ * Typed structurally (not imported from `@types/dom`) since the Prompt API is not yet part of
+ * stable browser type definitions. See https://developer.chrome.com/docs/ai/prompt-api.
+ */
+export interface PromptApiLanguageModel {
+  availability: (options?: Record<string, unknown>) => Promise<string>;
+  create: (options?: Record<string, unknown>) => Promise<PromptApiSession>;
+}
+
+/** Structural view of a Prompt API session. */
+export interface PromptApiSession {
+  prompt: (input: string, options?: { signal?: AbortSignal }) => Promise<string>;
+  destroy: () => void;
+}
+
+/**
+ * Generation controls forwarded to `LanguageModel.availability()` and `LanguageModel.create()`.
+ *
+ * Chrome's docs require passing the same options to both calls, since availability can depend on
+ * the requested configuration.
+ */
+export interface ChromePromptApiGenerationOptions {
+  temperature?: number;
+  topK?: number;
+}
+
+/**
+ * Configuration for the Chrome Prompt API-backed system-model runtime.
+ */
+export interface ChromePromptApiRuntimeOptions {
+  /** Generation controls passed to both `availability()` and `create()`. */
+  generation?: ChromePromptApiGenerationOptions;
+}
+
+/**
+ * Creates the default Web system-model runtime, backed by Chrome's built-in Prompt API
+ * (`LanguageModel`).
+ *
+ * The browser owns model availability, download, and execution; this runtime never bundles or
+ * fetches a model itself. When `LanguageModel` is not defined (unsupported browser, disabled
+ * flag, or origin trial not enrolled) the runtime reports itself unavailable instead of throwing,
+ * so routing degrades to an explainable `capability_unavailable` rejection.
+ *
+ * @param options - Generation control overrides forwarded to the Prompt API.
+ */
+export function createChromePromptApiRuntime(
+  options: ChromePromptApiRuntimeOptions = {}
+): SystemModelRuntime {
+  const promptOptions = toPromptApiOptions(options.generation);
+
+  return {
+    async availability(): Promise<SystemModelAvailability> {
+      const languageModel = getLanguageModel();
+      if (!languageModel) {
+        return {
+          kind: "api_missing",
+          reason:
+            "system model API missing: 'LanguageModel' is not defined on this browser. See https://developer.chrome.com/docs/ai/prompt-api."
+        };
+      }
+
+      let result: string;
+      try {
+        result = await languageModel.availability(promptOptions);
+      } catch (err) {
+        return mapAvailabilityError(err);
+      }
+
+      switch (result) {
+        case "available":
+          return { kind: "available" };
+        case "downloadable":
+          return {
+            kind: "downloadable",
+            reason: "model downloadable: the model can be downloaded but is not installed yet."
+          };
+        case "downloading":
+          return {
+            kind: "downloading",
+            reason: "model downloading: the model is currently downloading."
+          };
+        case "unavailable":
+          return {
+            kind: "model_unavailable",
+            reason: "model unavailable: the model is unavailable on this device."
+          };
+        default:
+          return {
+            kind: "unavailable",
+            reason: `provider temporarily unavailable: unrecognized availability result '${result}'.`
+          };
+      }
+    },
+
+    async generate(
+      input: SystemModelGenerationInput,
+      signal?: AbortSignal
+    ): Promise<SystemModelGenerationOutput> {
+      const languageModel = getLanguageModel();
+      if (!languageModel) {
+        throw new SystemModelRuntimeError(
+          "capability",
+          "system model API missing: 'LanguageModel' is not defined on this browser."
+        );
+      }
+
+      let session: PromptApiSession;
+      try {
+        session = await languageModel.create({ ...promptOptions, signal });
+      } catch (err) {
+        throw mapGenerateError(err);
+      }
+
+      try {
+        const text = await session.prompt(
+          toPromptText(input),
+          signal !== undefined ? { signal } : {}
+        );
+        return { text };
+      } catch (err) {
+        throw mapGenerateError(err);
+      } finally {
+        session.destroy();
+      }
+    }
+  };
+}
+
+function getLanguageModel(): PromptApiLanguageModel | undefined {
+  return (globalThis as { LanguageModel?: PromptApiLanguageModel }).LanguageModel;
+}
+
+function toPromptApiOptions(
+  generation?: ChromePromptApiGenerationOptions
+): Record<string, unknown> {
+  const promptOptions: Record<string, unknown> = {};
+  if (generation?.temperature !== undefined) promptOptions.temperature = generation.temperature;
+  if (generation?.topK !== undefined) promptOptions.topK = generation.topK;
+  return promptOptions;
+}
+
+function toPromptText(input: SystemModelGenerationInput): string {
+  return input.messages.map((message) => `${message.role}: ${message.content}`).join("\n");
+}
+
+function mapAvailabilityError(error: unknown): SystemModelAvailability {
+  const name = getDomExceptionName(error);
+  if (name === "NotSupportedError") {
+    return {
+      kind: "browser_unsupported",
+      reason: `browser unsupported: ${getErrorMessage(error)}`
+    };
+  }
+  if (name === "NotAllowedError" || name === "SecurityError") {
+    return {
+      kind: "feature_disabled",
+      reason: `browser feature disabled: ${getErrorMessage(error)}`
+    };
+  }
+  return {
+    kind: "unavailable",
+    reason: `provider temporarily unavailable: ${getErrorMessage(error)}`
+  };
+}
+
+function mapGenerateError(error: unknown): SystemModelRuntimeError {
+  if (error instanceof SystemModelRuntimeError) return error;
+
+  const name = getDomExceptionName(error);
+  switch (name) {
+    case "NotSupportedError":
+      return new SystemModelRuntimeError(
+        "capability",
+        `hardware unsupported: ${getErrorMessage(error)}`,
+        error
+      );
+    case "NotAllowedError":
+    case "SecurityError":
+      return new SystemModelRuntimeError(
+        "capability",
+        `browser feature disabled: ${getErrorMessage(error)}`,
+        error
+      );
+    case "QuotaExceededError":
+      return new SystemModelRuntimeError(
+        "unavailable",
+        `storage or network constraints: ${getErrorMessage(error)}`,
+        error
+      );
+    case "AbortError":
+      return new SystemModelRuntimeError(
+        "timeout",
+        `system model generation was aborted: ${getErrorMessage(error)}`,
+        error
+      );
+    default:
+      return new SystemModelRuntimeError(
+        "internal",
+        `system model generation failed: ${getErrorMessage(error)}`,
+        error
+      );
+  }
+}
+
+function getDomExceptionName(error: unknown): string | undefined {
+  return error instanceof DOMException ? error.name : undefined;
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/providers/system-model/provider.ts

@@ -0,0 +1,260 @@
+import type { TaskRequest, TaskResult } from "@independo/inderun-contracts";
+import {
+  createCapabilityMismatch,
+  createInternal,
+  createTimeout,
+  createUnavailable,
+  toIndeRunException,
+  type IndeRunException
+} from "../../core/errors.js";
+import type { HostServices } from "../../core/host.js";
+import { createChromePromptApiRuntime } from "./chrome-runtime.js";
+import {
+  SystemModelRuntimeError,
+  type SystemModelAvailability,
+  type SystemModelPromptMessage,
+  type SystemModelRuntime
+} from "./runtime.js";
+import type {
+  ProviderAdapter,
+  ProviderDescriptor,
+  ProviderDynamicCapabilities,
+  RunContext
+} from "../../core/provider.js";
+
+/** Default provider id of the Web member of the system-model provider family. */
+export const DEFAULT_SYSTEM_MODEL_WEB_PROVIDER_ID = "local.system-model.web";
+
+/** Task kind this provider implements in Milestone 2 (Mode 1 only). */
+const TEXT_TO_TEXT = "text_to_text";
+
+/**
+ * Configuration for the Web system-model provider.
+ */
+export interface SystemModelProviderOptions {
+  /**
+   * Provider id exposed in telemetry and routing explanations.
+   */
+  id?: string;
+  /**
+   * Runtime implementation used to check availability and execute generation. Defaults to
+   * `createChromePromptApiRuntime()`; pass `createFixtureSystemModelRuntime()` from
+   * `system-model.js` for tests and offline demos.
+   */
+  runtime?: SystemModelRuntime;
+  /**
+   * Optional generation timeout in milliseconds. A request-level `constraints.timeoutMs` wins.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * Local provider adapter that executes Mode-1 text-to-text requests against a browser-managed
+ * on-device model (for example Chrome's Prompt API / Gemini Nano).
+ *
+ * Unlike the ONNX Runtime provider family, this provider takes no developer-supplied model: the
+ * browser owns model availability, download, and execution. The adapter owns the IndeRun-facing
+ * contract (descriptor, capability checks, error taxonomy) and delegates everything else to an
+ * injectable {@link SystemModelRuntime}.
+ */
+export class SystemModelWebProvider implements ProviderAdapter {
+  private readonly id: string;
+  private readonly runtime: SystemModelRuntime;
+
+  /**
+   * Creates a Web system-model provider.
+   * @param options - Optional id, runtime, and timeout overrides.
+   */
+  constructor(private readonly options: SystemModelProviderOptions = {}) {
+    this.id = options.id ?? DEFAULT_SYSTEM_MODEL_WEB_PROVIDER_ID;
+    this.runtime = options.runtime ?? createChromePromptApiRuntime();
+  }
+
+  /**
+   * Returns static metadata used by the router for deterministic provider selection.
+   */
+  describe(): ProviderDescriptor {
+    return {
+      id: this.id,
+      type: "local",
+      transport: "system_service",
+      supports: {
+        run: true,
+        streaming: false,
+        realtime: false,
+        tools: false,
+        reasoningEvents: false,
+        structuredOutput: false,
+        multimodal: false
+      },
+      cancel: "soft",
+      tasks: [TEXT_TO_TEXT],
+      privacy: {
+        dataLeavesDevice: false
+      }
+    };
+  }
+
+  /**
+   * Reports dynamic provider availability for the current host.
+   *
+   * Every failure below is provider-internal detail: the shared route planner flattens it into a
+   * single `capability_unavailable` rejection carrying the returned reason.
+   *
+   * @param _host - Host services available to the engine (unused; the browser owns execution).
+   */
+  async capabilities(_host: HostServices): Promise<ProviderDynamicCapabilities> {
+    const availability = await this.runtime.availability();
+    return toDynamicCapabilities(availability);
+  }
+
+  /**
+   * Executes a normalized text-to-text task against the browser-managed on-device model.
+   * @param request - Canonical IndeRun task request.
+   * @param context - Engine execution context containing run id and host services.
+   * @returns Normalized IndeRun task result.
+   * @throws IndeRunException mapped to the standard error taxonomy.
+   */
+  async run(request: TaskRequest, context: RunContext): Promise<TaskResult> {
+    const availability = await this.runtime.availability();
+    const capabilities = toDynamicCapabilities(availability);
+    if (!capabilities.available) {
+      throw createCapabilityMismatch(
+        capabilities.reason ?? "Web system-model provider is unavailable on this host.",
+        { providerId: this.id, runId: context.runId }
+      );
+    }
+
+    const messages = createMessages(request);
+    if (messages.length === 0) {
+      throw createInternal("Web system-model provider requires a prompt or messages.", {
+        providerId: this.id,
+        runId: context.runId
+      });
+    }
+
+    const timeoutMs = request.constraints?.timeoutMs ?? this.options.timeoutMs;
+    const controller = new AbortController();
+    const timer =
+      timeoutMs !== undefined && timeoutMs > 0
+        ? setTimeout(() => controller.abort(), timeoutMs)
+        : undefined;
+
+    let output: Awaited<ReturnType<SystemModelRuntime["generate"]>>;
+    try {
+      output = await this.runtime.generate(
+        {
+          messages,
+          ...(request.generation !== undefined ? { generation: request.generation } : {})
+        },
+        controller.signal
+      );
+    } catch (err) {
+      throw this.mapRuntimeError(err, context);
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+
+    if (typeof output.text !== "string" || output.text.length === 0) {
+      throw createInternal("Web system-model provider returned no text output.", {
+        providerId: this.id,
+        runId: context.runId
+      });
+    }
+
+    return {
+      schemaVersion: "1.0",
+      runId: context.runId,
+      output: {
+        type: "text",
+        text: output.text
+      },
+      finishReason: output.finishReason ?? "stop",
+      telemetry: {
+        providerUsed: this.id,
+        totalMs: 0
+      }
+    };
+  }
+
+  private mapRuntimeError(error: unknown, context: RunContext): IndeRunException {
+    const extra = { providerId: this.id, runId: context.runId };
+
+    if (error instanceof SystemModelRuntimeError) {
+      const details =
+        error.originalError !== undefined
+          ? { details: { originalError: getErrorSummary(error.originalError) } }
+          : {};
+
+      switch (error.kind) {
+        case "capability":
+          return createCapabilityMismatch(error.message, { ...extra, ...details });
+        case "unavailable":
+          return createUnavailable(error.message, { ...extra, ...details });
+        case "timeout":
+          return createTimeout(error.message, { ...extra, ...details });
+        default:
+          return createInternal(error.message, { ...extra, ...details });
+      }
+    }
+
+    if (isAbortError(error)) {
+      return createTimeout("Web system-model generation timed out.", extra);
+    }
+
+    return toIndeRunException(error, extra);
+  }
+}
+
+const REASON_PREFIX: Record<SystemModelAvailability["kind"], string | undefined> = {
+  available: undefined,
+  downloadable: "model downloadable",
+  downloading: "model downloading",
+  model_unavailable: "model unavailable",
+  api_missing: "system model API missing",
+  browser_unsupported: "browser unsupported",
+  feature_disabled: "browser feature disabled",
+  hardware_unsupported: "hardware unsupported",
+  resource_constrained: "storage or network constraints",
+  unavailable: "provider temporarily unavailable"
+};
+
+function toDynamicCapabilities(availability: SystemModelAvailability): ProviderDynamicCapabilities {
+  if (availability.kind === "available") {
+    return { available: true };
+  }
+
+  const prefix = REASON_PREFIX[availability.kind];
+  const reason = availability.reason
+    ? `${prefix}: ${availability.reason}`
+    : `${prefix}: the Web system-model provider is unavailable.`;
+
+  return { available: false, reason };
+}
+
+function createMessages(request: TaskRequest): SystemModelPromptMessage[] {
+  if (request.messages && request.messages.length > 0) {
+    return request.messages.map((message) => ({
+      role: message.role,
+      content: message.content
+    }));
+  }
+
+  const prompt = request.prompt;
+  return prompt !== undefined && prompt.length > 0 ? [{ role: "user", content: prompt }] : [];
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { name?: unknown }).name === "AbortError"
+  );
+}
+
+function getErrorSummary(error: unknown): Record<string, unknown> {
+  if (error instanceof Error) {
+    return { name: error.name, message: error.message, stack: error.stack };
+  }
+  return { message: String(error) };
+}

package/src/providers/system-model/runtime.ts

@@ -0,0 +1,202 @@
+import type { TaskRequest, TaskResult } from "@independo/inderun-contracts";
+
+/**
+ * Capability state reported by a system-model runtime.
+ *
+ * The `reason` string uses the provider-internal capability vocabulary documented in
+ * `docs/architecture/web-system-model-provider-family.md`. It is not a public enum: the provider
+ * flattens every non-`available` kind into a single `capability_unavailable` route rejection and
+ * carries the reason as human-readable text.
+ */
+export type SystemModelAvailabilityKind =
+  | "available"
+  | "downloadable"
+  | "downloading"
+  | "model_unavailable"
+  | "api_missing"
+  | "browser_unsupported"
+  | "feature_disabled"
+  | "hardware_unsupported"
+  | "resource_constrained"
+  | "unavailable";
+
+/**
+ * Availability snapshot reported by a system-model runtime.
+ */
+export interface SystemModelAvailability {
+  /** The specific availability state the runtime observed. */
+  kind: SystemModelAvailabilityKind;
+  /** Human-readable detail describing the state; expected for every non-`available` kind. */
+  reason?: string;
+}
+
+/**
+ * Normalized conversation turn handed to a system-model runtime.
+ */
+export interface SystemModelPromptMessage {
+  /** The role of the author of this turn. */
+  role: "system" | "user" | "assistant";
+  /** Plain-text content of this turn. */
+  content: string;
+}
+
+/**
+ * Normalized generation request handed to a system-model runtime.
+ */
+export interface SystemModelGenerationInput {
+  /** Conversation turns, normalized from `prompt` or `messages` by the provider. */
+  messages: SystemModelPromptMessage[];
+  /** Optional generation controls copied from the task request. */
+  generation?: NonNullable<TaskRequest["generation"]>;
+}
+
+/**
+ * Normalized generation result returned by a system-model runtime.
+ */
+export interface SystemModelGenerationOutput {
+  /** The generated text. */
+  text: string;
+  /** Optional normalized finish reason; the provider defaults to `stop`. */
+  finishReason?: TaskResult["finishReason"];
+}
+
+/**
+ * Failure category a runtime can signal so the provider maps it onto the IndeRun error taxonomy.
+ *
+ * - `capability`: the browser or hardware cannot serve this request (`CapabilityMismatch`).
+ * - `unavailable`: resource exhaustion or transient failure (`Unavailable`).
+ * - `timeout`: generation exceeded its budget or was aborted (`Timeout`).
+ * - `internal`: unexpected runtime failure (`Internal`).
+ */
+export type SystemModelRuntimeErrorKind = "capability" | "unavailable" | "timeout" | "internal";
+
+/**
+ * Error type system-model runtime implementations throw to steer IndeRun error normalization.
+ *
+ * Anything else thrown by a runtime is normalized to `Internal`.
+ */
+export class SystemModelRuntimeError extends Error {
+  /** Failure category used by the provider to select an IndeRun error class. */
+  readonly kind: SystemModelRuntimeErrorKind;
+  /** Optional underlying error captured for telemetry details. */
+  readonly originalError?: unknown;
+
+  constructor(kind: SystemModelRuntimeErrorKind, message: string, originalError?: unknown) {
+    super(message);
+    this.name = "SystemModelRuntimeError";
+    this.kind = kind;
+    if (originalError !== undefined) this.originalError = originalError;
+
+    Object.setPrototypeOf(this, SystemModelRuntimeError.prototype);
+  }
+}
+
+/**
+ * Injectable seam between the IndeRun Web system-model provider and the browser's on-device model
+ * API.
+ *
+ * IndeRun ships a Chrome Prompt API-backed implementation as the default and a deterministic
+ * fixture for tests. The seam exposes only Mode-1 generation (no session object, no streaming
+ * method) so streaming/session support cannot leak in even as unused scaffolding.
+ */
+export interface SystemModelRuntime {
+  /**
+   * Checks browser API presence and model readiness. Implementations must resolve with an
+   * availability snapshot rather than throwing.
+   */
+  availability(): Promise<SystemModelAvailability>;
+  /**
+   * Runs one Mode-1 generation. Implementations should honor `signal` where the underlying API
+   * allows it.
+   */
+  generate(
+    input: SystemModelGenerationInput,
+    signal?: AbortSignal
+  ): Promise<SystemModelGenerationOutput>;
+}
+
+/**
+ * Configuration for the deterministic fixture runtime.
+ */
+export interface FixtureSystemModelRuntimeOptions {
+  /** Availability snapshot returned by `availability`. Defaults to `{ kind: "available" }`. */
+  availability?: SystemModelAvailability;
+  /** Text or full output produced by `generate`. Defaults to a deterministic echo. */
+  respond?: (input: SystemModelGenerationInput) => string | SystemModelGenerationOutput;
+  /** Error thrown by `generate` instead of producing output. */
+  failWith?: unknown;
+  /** Artificial generation delay in milliseconds, used to exercise timeouts. */
+  delayMs?: number;
+}
+
+/**
+ * Creates a deterministic in-memory system-model runtime.
+ *
+ * This is the test seam for the Web system-model provider family: it proves capability checks,
+ * routing, and error normalization without depending on a real browser Prompt API implementation.
+ *
+ * @param options - Scripted availability, response, failure, and delay behavior.
+ */
+export function createFixtureSystemModelRuntime(
+  options: FixtureSystemModelRuntimeOptions = {}
+): SystemModelRuntime {
+  const availability = options.availability ?? { kind: "available" };
+
+  return {
+    async availability(): Promise<SystemModelAvailability> {
+      return availability;
+    },
+    async generate(
+      input: SystemModelGenerationInput,
+      signal?: AbortSignal
+    ): Promise<SystemModelGenerationOutput> {
+      if (options.delayMs !== undefined && options.delayMs > 0) {
+        await delay(options.delayMs, signal);
+      }
+
+      throwIfAborted(signal);
+
+      if (options.failWith !== undefined) {
+        throw options.failWith;
+      }
+
+      const response = options.respond ? options.respond(input) : createFixtureText(input.messages);
+
+      return typeof response === "string" ? { text: response } : response;
+    }
+  };
+}
+
+function createFixtureText(messages: SystemModelPromptMessage[]): string {
+  const lastUserMessage = [...messages].reverse().find((message) => message.role === "user");
+  const prompt = lastUserMessage?.content ?? "";
+  return `[fixture:system-model] ${prompt}`;
+}
+
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+
+    function onAbort(): void {
+      clearTimeout(timer);
+      reject(
+        new SystemModelRuntimeError("timeout", "Fixture system-model generation was aborted.")
+      );
+    }
+
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw new SystemModelRuntimeError("timeout", "Fixture system-model generation was aborted.");
+  }
+}