@missionsquad/browserai 0.1.0

package/src/config.ts

@@ -0,0 +1,104 @@
+import type { BrowserCacheBackend } from "./model-source.js";
+import type { KokoroModule } from "./multimodal.js";
+
+/** Default WebLLM context-window baseline; a differing override becomes `context_window_size`. */
+export const DEFAULT_CONTEXT_LENGTH = 4096;
+
+/** Storage adapter for run-history persistence (matches the `localStorage` surface the SDK uses). */
+export type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+
+export type WebLLMOptions = {
+  /**
+   * Factory for a dedicated module worker running the SDK's WebLLM handler (the
+   * `@missionsquad/browserai/worker` entry). When provided, engines are created with
+   * `CreateWebWorkerMLCEngine` so loading + token generation stay off the main thread; when absent,
+   * the SDK uses the main-thread `CreateMLCEngine`.
+   */
+  worker?: () => Worker;
+  /** WebLLM engine log level. Default "INFO". */
+  logLevel?: "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "SILENT";
+};
+
+export type KokoroOptions = {
+  /** Override the kokoro-js ESM bundle URL (must export KokoroTTS + TextSplitterStream). */
+  url?: string;
+  /** Fully replace module loading (e.g. a bundled import). Wins over `url`. */
+  load?: () => Promise<KokoroModule>;
+};
+
+export type TtsDefaults = {
+  /** Voice id for the loaded TTS model's roster (Kokoro: "af_heart" etc.; Supertonic: "F1"–"M5"). */
+  voice: string;
+  /** Speech speed multiplier. Kokoro bakes it into synthesis; Supertonic applies it at playback. */
+  speed: number;
+  /** Pitch ratio baked into produced clips (1 = unchanged, 2 = up an octave). */
+  pitch: number;
+};
+
+export type HistoryOptions = {
+  /**
+   * Persistence for the run log. Defaults to `globalThis.localStorage` when available; pass `null`
+   * to keep history in memory only.
+   */
+  storage?: StorageLike | null;
+  /** localStorage key. */
+  key?: string;
+  /** Cap on persisted records (newest first). */
+  maxRecords?: number;
+};
+
+export type BrowserAIConfig = {
+  /**
+   * Where model artifacts are fetched from. "direct" (default) downloads straight from Hugging Face
+   * and raw GitHub — works on any site. "proxy" routes through a same-origin (or configured-origin)
+   * deployment of the bundled Cloudflare Worker template (`/hf/*`, `/hf-transformers/*`, `/gh-raw/*`).
+   */
+  modelSource?: "direct" | "proxy";
+  /**
+   * Origin of the proxy Worker when `modelSource: "proxy"`. Defaults to the page's own origin.
+   * Ignored in direct mode.
+   */
+  proxyOrigin?: string;
+  /** Probe the proxy (health + config HEAD checks) before each proxied load. Default true. */
+  verifyProxy?: boolean;
+  /**
+   * WebLLM artifact cache backend. Default "indexeddb" (clearer failures than the Cache API on
+   * proxied deployments). Transformers.js artifacts always use the browser Cache API bucket
+   * "transformers-cache" regardless of this setting.
+   */
+  cacheBackend?: BrowserCacheBackend;
+  webllm?: WebLLMOptions;
+  kokoro?: KokoroOptions;
+  /** Default TTS voice/speed/pitch used by synthesize helpers and the voice pipeline. */
+  tts?: Partial<TtsDefaults>;
+  history?: HistoryOptions;
+};
+
+export type ResolvedConfig = {
+  modelSource: "direct" | "proxy";
+  proxyOrigin: string | null;
+  verifyProxy: boolean;
+  cacheBackend: BrowserCacheBackend;
+  webllm: WebLLMOptions;
+  kokoro: KokoroOptions;
+  tts: TtsDefaults;
+  history: HistoryOptions;
+};
+
+/** Apply defaults. `proxyOrigin` falls back to the page origin only when running in a window/worker. */
+export function resolveConfig(config: BrowserAIConfig = {}): ResolvedConfig {
+  const pageOrigin =
+    typeof globalThis.location !== "undefined" && typeof globalThis.location.origin === "string"
+      ? globalThis.location.origin
+      : null;
+  return {
+    modelSource: config.modelSource ?? "direct",
+    proxyOrigin: config.proxyOrigin ?? pageOrigin,
+    verifyProxy: config.verifyProxy ?? true,
+    cacheBackend: config.cacheBackend ?? "indexeddb",
+    webllm: config.webllm ?? {},
+    kokoro: config.kokoro ?? {},
+    tts: { voice: "af_heart", speed: 1, pitch: 1, ...config.tts },
+    history: config.history ?? {},
+  };
+}

package/src/errors.ts

@@ -0,0 +1,81 @@
+/**
+ * Custom error classes for the SDK. Every error thrown by BrowserAI code is (or wraps into) a
+ * `BrowserAIError` subclass so hosts can branch with `instanceof` instead of parsing messages.
+ */
+
+/** Format an unknown thrown value as a human-readable message. */
+export function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Base class for all SDK errors. */
+export class BrowserAIError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+}
+
+/** A model id that is not present in the catalog. */
+export class UnknownModelError extends BrowserAIError {
+  readonly modelId: string;
+  constructor(modelId: string) {
+    super(`Unknown model id: ${modelId}`);
+    this.modelId = modelId;
+  }
+}
+
+/** WebGPU is required for the requested load but is not available. */
+export class WebGPUUnavailableError extends BrowserAIError {
+  /** The probe's explanation (e.g. "navigator.gpu is not available."). */
+  readonly reason: string;
+  constructor(reason: string) {
+    super(`WebGPU unavailable: ${reason}`);
+    this.reason = reason;
+  }
+}
+
+/** A model load failed. Wraps the underlying engine/network error as `cause`. */
+export class ModelLoadError extends BrowserAIError {
+  readonly modelId: string;
+  constructor(modelId: string, cause: unknown) {
+    super(`Model load failed for ${modelId}: ${formatError(cause)}`, { cause });
+    this.modelId = modelId;
+  }
+}
+
+/** The same-origin proxy did not pass its pre-load health/probe checks. */
+export class ProxyVerificationError extends BrowserAIError {}
+
+/** An operation needs a capability slot (text/vision/stt/tts) that no loaded model fills. */
+export class MissingModelError extends BrowserAIError {
+  readonly slot: string;
+  constructor(slot: string, message?: string) {
+    super(message ?? `No loaded model fills the "${slot}" capability slot.`);
+    this.slot = slot;
+  }
+}
+
+/** Microphone acquisition failed. `permissionDenied` distinguishes user/browser denial. */
+export class MicrophoneError extends BrowserAIError {
+  readonly permissionDenied: boolean;
+  constructor(cause: unknown) {
+    super(`Microphone error: ${formatError(cause)}`, { cause });
+    this.permissionDenied =
+      cause instanceof DOMException && (cause.name === "NotAllowedError" || cause.name === "SecurityError");
+  }
+}
+
+/**
+ * A voice-pipeline turn failure tagged with the component that failed. The streaming path runs
+ * generation and synthesis CONCURRENTLY, so the pipeline stage no longer identifies the failing
+ * component (the stage can be "speaking" when generation throws, or "thinking" when synthesis
+ * rejects) — the throw site knows and tags the label.
+ */
+export class VoiceTurnError extends BrowserAIError {
+  readonly label: string;
+  constructor(label: string, cause: unknown) {
+    super(formatError(cause), { cause });
+    this.label = label;
+  }
+}

package/src/events.ts

@@ -0,0 +1,53 @@
+/**
+ * Minimal typed event emitter. Framework-agnostic and dependency-free; the event map type gives
+ * hosts full payload typing (`on("stagechange", ({ stage }) => …)`).
+ */
+export type EventMap = Record<string, unknown>;
+
+export type Listener<T> = (payload: T) => void;
+
+export class TypedEmitter<Events extends EventMap> {
+  #listeners = new Map<keyof Events, Set<Listener<never>>>();
+
+  /** Subscribe. Returns an unsubscribe function. */
+  on<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void {
+    let set = this.#listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.#listeners.set(event, set);
+    }
+    set.add(listener as Listener<never>);
+    return () => this.off(event, listener);
+  }
+
+  /** Subscribe for a single emission. Returns an unsubscribe function. */
+  once<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void {
+    const unsubscribe = this.on(event, (payload) => {
+      unsubscribe();
+      listener(payload);
+    });
+    return unsubscribe;
+  }
+
+  off<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void {
+    this.#listeners.get(event)?.delete(listener as Listener<never>);
+  }
+
+  protected emit<K extends keyof Events>(event: K, payload: Events[K]): void {
+    const set = this.#listeners.get(event);
+    if (!set) return;
+    // Copy so a listener unsubscribing (or subscribing) mid-emit cannot skip/duplicate deliveries.
+    for (const listener of [...set]) {
+      try {
+        (listener as Listener<Events[K]>)(payload);
+      } catch {
+        // A throwing listener must not break the engine or starve other listeners.
+      }
+    }
+  }
+
+  /** Remove every listener (all events). */
+  removeAllListeners(): void {
+    this.#listeners.clear();
+  }
+}

package/src/generation.ts

@@ -0,0 +1,39 @@
+import type { ResponseFormat } from "@mlc-ai/web-llm";
+import type { RuntimePreset } from "./models.js";
+import { stripSchemaMetadata } from "./schema.js";
+
+export type JsonMode = "schema" | "json_object" | "none";
+
+export type RuntimeParameters = RuntimePreset & {
+  jsonMode: JsonMode;
+  latencyBreakdown: boolean;
+};
+
+export function runtimeParamsFromPreset(preset: RuntimePreset): RuntimeParameters {
+  return {
+    ...preset,
+    jsonMode: "schema",
+    latencyBreakdown: true,
+  };
+}
+
+export function buildResponseFormat(mode: JsonMode, schema: unknown): ResponseFormat | undefined {
+  if (mode === "none") return undefined;
+  if (mode === "json_object") return { type: "json_object" };
+
+  return {
+    type: "json_object",
+    schema: JSON.stringify(stripSchemaMetadata(schema)),
+  };
+}
+
+export function clampNumber(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, value));
+}
+
+export function parseOptionalInteger(value: string): number | null {
+  if (!value.trim()) return null;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}

package/src/hardware.ts

@@ -0,0 +1,193 @@
+import type { ModelPreset } from "./models.js";
+import { formatMB } from "./models.js";
+
+type WebGpuLimitMap = Record<string, number | string>;
+
+export type HardwareSnapshot = {
+  webgpuSupported: boolean;
+  webgpuReason: string;
+  adapterInfo?: Record<string, unknown>;
+  features: string[];
+  limits: WebGpuLimitMap;
+  deviceMemoryGB?: number;
+  logicalProcessors?: number;
+  storageQuotaBytes?: number;
+  storageUsageBytes?: number;
+  secureContext: boolean;
+  crossOriginIsolated: boolean;
+  userAgent: string;
+  platform?: string;
+};
+
+const LIMIT_NAMES = [
+  "maxBufferSize",
+  "maxStorageBufferBindingSize",
+  "maxComputeInvocationsPerWorkgroup",
+  "maxComputeWorkgroupSizeX",
+  "maxComputeWorkgroupSizeY",
+  "maxComputeWorkgroupsPerDimension",
+  "maxBindGroups",
+  "maxBindingsPerBindGroup",
+  "maxStorageBuffersPerShaderStage",
+  "maxUniformBuffersPerShaderStage",
+  "maxTextureDimension2D",
+];
+
+export async function collectHardwareSnapshot(): Promise<HardwareSnapshot> {
+  const nav = navigator as Navigator & {
+    deviceMemory?: number;
+    userAgentData?: { platform?: string };
+  };
+
+  // Read off globalThis (not window) so the probe also works in a worker global scope.
+  const scope = globalThis as typeof globalThis & { isSecureContext?: boolean; crossOriginIsolated?: boolean };
+
+  const base: HardwareSnapshot = {
+    webgpuSupported: false,
+    webgpuReason: "navigator.gpu is not available.",
+    features: [],
+    limits: {},
+    deviceMemoryGB: nav.deviceMemory,
+    logicalProcessors: nav.hardwareConcurrency,
+    secureContext: scope.isSecureContext === true,
+    crossOriginIsolated: scope.crossOriginIsolated === true,
+    userAgent: navigator.userAgent,
+    platform: nav.userAgentData?.platform ?? navigator.platform,
+  };
+
+  try {
+    const estimate = await navigator.storage?.estimate?.();
+    base.storageQuotaBytes = estimate?.quota;
+    base.storageUsageBytes = estimate?.usage;
+  } catch {
+    // Storage quota is a best-effort browser hint; ignore unsupported/blocked cases.
+  }
+
+  if (!("gpu" in navigator)) {
+    return base;
+  }
+
+  try {
+    const adapter = await navigator.gpu.requestAdapter();
+    if (!adapter) {
+      return { ...base, webgpuReason: "WebGPU exists, but no adapter was returned." };
+    }
+
+    const limits = adapter.limits as unknown as Record<string, number>;
+    const pickedLimits: WebGpuLimitMap = {};
+    for (const name of LIMIT_NAMES) {
+      if (typeof limits[name] === "number") {
+        pickedLimits[name] = limits[name];
+      }
+    }
+
+    let canCreateDevice = false;
+    try {
+      const device = await adapter.requestDevice();
+      canCreateDevice = true;
+      device.destroy();
+    } catch {
+      canCreateDevice = false;
+    }
+
+    const info = adapter.info as unknown as Record<string, unknown> | undefined;
+    return {
+      ...base,
+      webgpuSupported: canCreateDevice,
+      webgpuReason: canCreateDevice ? "WebGPU adapter and device are available." : "Adapter exists, but requestDevice() failed.",
+      adapterInfo: info,
+      features: Array.from(adapter.features).sort(),
+      limits: pickedLimits,
+    };
+  } catch (error) {
+    return {
+      ...base,
+      webgpuReason: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function modelSafetyHint(snapshot: HardwareSnapshot, model: ModelPreset): string {
+  const vram = formatMB(model.vramRequiredMB);
+  const maxStorage = numberLimit(snapshot, "maxStorageBufferBindingSize");
+  const deviceMemory = snapshot.deviceMemoryGB;
+
+  const sourceText =
+    model.vramSource === "estimated"
+      ? `This custom model is configured with an estimated GPU memory requirement of about ${vram}.`
+      : `WebLLM metadata says this model requires about ${vram} of GPU memory.`;
+
+  const parts = [
+    sourceText,
+    "Browsers do not expose total or free VRAM, so this is a heuristic; the actual load attempt is the definitive test.",
+  ];
+
+  if (typeof maxStorage === "number") {
+    parts.push(`Adapter maxStorageBufferBindingSize is ${formatBytes(maxStorage)}.`);
+  }
+
+  if (typeof deviceMemory === "number") {
+    parts.push(`navigator.deviceMemory reports about ${deviceMemory} GB of system memory, but this is not VRAM.`);
+  }
+
+  return parts.join(" ");
+}
+
+export function formatHardwareSnapshot(snapshot: HardwareSnapshot, model?: ModelPreset): string {
+  const lines = [
+    `WebGPU: ${snapshot.webgpuSupported ? "available" : "unavailable"}`,
+    `Reason: ${snapshot.webgpuReason}`,
+    `Secure context: ${snapshot.secureContext ? "yes" : "no"}`,
+    `crossOriginIsolated: ${snapshot.crossOriginIsolated ? "yes" : "no"}`,
+    `Logical processors: ${snapshot.logicalProcessors ?? "unknown"}`,
+    `Approx system memory: ${snapshot.deviceMemoryGB ? `${snapshot.deviceMemoryGB} GB` : "unavailable"}`,
+    `Browser storage: ${formatStorage(snapshot)}`,
+    `Platform: ${snapshot.platform ?? "unknown"}`,
+  ];
+
+  if (snapshot.adapterInfo && Object.keys(snapshot.adapterInfo).length > 0) {
+    lines.push("", "GPU adapter info:", JSON.stringify(snapshot.adapterInfo, null, 2));
+  }
+
+  if (snapshot.features.length > 0) {
+    lines.push("", `GPU features (${snapshot.features.length}):`, snapshot.features.join(", "));
+  }
+
+  if (Object.keys(snapshot.limits).length > 0) {
+    lines.push("", "Selected GPU limits:");
+    for (const [key, value] of Object.entries(snapshot.limits)) {
+      lines.push(`  ${key}: ${typeof value === "number" && key.toLowerCase().includes("size") ? formatBytes(value) : value}`);
+    }
+  }
+
+  if (model) {
+    lines.push("", "Selected model safety hint:", modelSafetyHint(snapshot, model));
+  }
+
+  return lines.join("\n");
+}
+
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes)) return "unknown";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(value >= 10 || unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+
+function formatStorage(snapshot: HardwareSnapshot): string {
+  if (typeof snapshot.storageQuotaBytes !== "number") {
+    return "unavailable";
+  }
+  const usage = typeof snapshot.storageUsageBytes === "number" ? formatBytes(snapshot.storageUsageBytes) : "unknown";
+  return `${usage} used / ${formatBytes(snapshot.storageQuotaBytes)} quota`;
+}
+
+function numberLimit(snapshot: HardwareSnapshot, key: string): number | undefined {
+  const value = snapshot.limits[key];
+  return typeof value === "number" ? value : undefined;
+}