arcane-os 0.5.17 → 0.5.19

package/browser-runtime/ai/browser-wasm.mjs

@@ -1,3 +1,4 @@
+import Is from "../dependencies/strong-type/index.js";
 import {
   completeValueText,
   createModelController,
@@ -11,6 +12,8 @@ import {
 } from "./browser-wasm-llm-provider.mjs";
 import { BROWSER_WASM_RUNTIME_AUTHORITY } from "./browser-wllama-runtime.mjs";
 
+const is = new Is(false);
+
 /**
  * Creates the public Arcane browser-local AI API module. The SDK owns lifecycle,
  * cache, streaming, complete response projection, and structural tool visibility; applications
@@ -24,12 +27,12 @@ function createArcaneAI({
 } = {}) {
   const selected = llm ?? provider;
   if (!selected) throw new TypeError("createArcaneAI requires an llm provider.");
-  if (selected instanceof ModelController && security !== undefined) {
+  if (is.instanceCheck(selected, ModelController) && security !== undefined) {
     throw new TypeError(
       "createArcaneAI security must be configured when the existing ModelController is created.",
     );
   }
-  const controller = selected instanceof ModelController
+  const controller = is.instanceCheck(selected, ModelController)
     ? selected
     : createModelController({ provider: selected, loadPolicy, security });
   const api = {
@@ -46,7 +49,7 @@ function createArcaneAI({
   };
 
   async function createChatSession(options = {}) {
-    if (!options || typeof options !== "object" || Array.isArray(options)) {
+    if (!options || !is.object(options) || is.array(options)) {
       throw new TypeError("createChatSession options must be a plain object.");
     }
     if (Object.getPrototypeOf(options) !== Object.prototype) {

package/browser-runtime/ai/browser-wllama-runtime.mjs

@@ -1,6 +1,9 @@
+import Is from "../dependencies/strong-type/index.js";
 import { arcaneLogging } from '../logging.mjs';
 import { Wllama } from "./wllama/index.mjs";
 
+const is = new Is(false);
+
 const completeValue = (value) => value;
 
 const MODULE_URL = new URL("./wllama/index.mjs", import.meta.url).href;
@@ -63,15 +66,15 @@ function runtimeCapabilitySnapshot(evidence) {
   const navigatorObject = globalThis.navigator;
   const webgpuOperational = evidence?.state === "ready" && evidence?.webgpu?.observed === true;
   return completeValue({
-    webAssembly: typeof globalThis.WebAssembly === "object",
-    opfs: typeof navigatorObject?.storage?.getDirectory === "function",
+    webAssembly: is.object(globalThis.WebAssembly),
+    opfs: is.function(navigatorObject?.storage?.getDirectory),
     webgpu: webgpuOperational,
     webgpuApiPresent: Boolean(navigatorObject?.gpu),
     webgpuOperational,
     webgpuEvidenceProtocol: RUNTIME_EVIDENCE_PROTOCOL,
     crossOriginIsolated: globalThis.crossOriginIsolated === true,
     secureContext: globalThis.isSecureContext === true,
-    hardwareConcurrency: Number.isSafeInteger(navigatorObject?.hardwareConcurrency)
+    hardwareConcurrency: is.safeInteger(navigatorObject?.hardwareConcurrency)
       ? navigatorObject.hardwareConcurrency
       : null,
   });
@@ -80,7 +83,7 @@ function runtimeCapabilitySnapshot(evidence) {
 function normalizePositiveInteger(value, fallback) {
   if (value === undefined || value === null) return fallback;
   const number = Number(value);
-  if (!Number.isSafeInteger(number) || number < 1) {
+  if (!is.safeInteger(number) || number < 1) {
     throw new RangeError("Expected a positive safe integer.");
   }
   return number;
@@ -91,6 +94,59 @@ function createEvidenceLogger(logger) {
   let offload = null;
   let invalid = false;
   let completionCapture = null;
+  let loadProgress = null;
+  let tensorCount = null;
+
+  function observeLoadLine(line) {
+    if (!loadProgress) return;
+    let stage;
+    let message;
+    const metadata = line.match(/^llama_model_loader: loaded meta data with \d+ key-value pairs and (\d+) tensors from /u);
+    const layers = line.match(GPU_OFFLOAD_PATTERN);
+    if (line.startsWith('Loading "wllama.wasm" from ')) {
+      stage = "runtime";
+      message = "Loading the WebAssembly runtime";
+    } else if (line === "Calling wllamaStart...") {
+      stage = "backend";
+      message = "Starting the inference engine";
+    } else if (line === "Loading model...") {
+      stage = "metadata";
+      message = "Reading model metadata";
+    } else if (WEBGPU_ADAPTER_PATTERN.test(line)) {
+      stage = "gpu";
+      message = "Graphics device initialized; preparing the model";
+    } else if (metadata) {
+      tensorCount = Number(metadata[1]);
+      stage = "metadata";
+      message = `Model metadata read: ${tensorCount} tensors`;
+    } else if (line.startsWith("load_tensors: loading model tensors,")) {
+      stage = "weights";
+      message = tensorCount === null
+        ? "Loading model weights"
+        : `Loading model weights for ${tensorCount} tensors`;
+    } else if (layers) {
+      // Upstream reports layer assignment before the weight reads finish.
+      stage = "weights";
+      message = `Loading model weights; ${layers[1]} of ${layers[2]} layers assigned to the GPU`;
+    } else if (line === "llama_context: constructing llama_context") {
+      stage = "context";
+      message = "Preparing the inference context";
+    } else if (/^[^:]+:\s+graph (?:nodes|splits)\s+=\s+\d+/u.test(line)) {
+      stage = "graph";
+      message = "Preparing the inference graph";
+    } else if (/^cmn\s+common_init_:\s+warming up the model with an empty run\b/u.test(line)) {
+      stage = "warmup";
+      message = "Warming up the model with an empty run";
+    }
+    if (stage) {
+      loadProgress({
+        phase: "initialize",
+        stage,
+        message,
+        total: null,
+      });
+    }
+  }
 
   function same(left, right) {
     return JSON.stringify(left) === JSON.stringify(right);
@@ -116,6 +172,7 @@ function createEvidenceLogger(logger) {
     observeCompletionLine(level, value);
     const line = String(value).trim();
     if (!line) return;
+    observeLoadLine(line);
     const adapterMatch = line.match(WEBGPU_ADAPTER_PATTERN);
     if (adapterMatch) {
       const next = completeValue({
@@ -141,8 +198,10 @@ function createEvidenceLogger(logger) {
   }
 
   function observe(level, args) {
+    // Activity without a new stage updates its age without repainting the UI.
+    loadProgress?.(null);
     for (const value of args) {
-      if (typeof value !== "string") continue;
+      if (!is.string(value)) continue;
       for (const line of value.split(/\r?\n/u)) observeLine(level, line);
     }
   }
@@ -151,12 +210,19 @@ function createEvidenceLogger(logger) {
   for (const level of ["debug", "log", "warn", "error"]) {
     wrapped[level] = (...args) => {
       observe(level, args);
-      if (typeof logger?.[level] === "function") logger[level](...args);
+      if (is.function(logger?.[level])) logger[level](...args);
     };
   }
 
   return completeValue({
     logger: completeValue(wrapped),
+    beginLoadProgress(report) {
+      loadProgress = report;
+      tensorCount = null;
+      return function releaseLoadProgress() {
+        loadProgress = null;
+      };
+    },
     beginCompletionCapture() {
       if (completionCapture) {
         throw runtimeFailure(
@@ -214,7 +280,7 @@ function createStructuredStreamCapture() {
 
   function observe(value) {
     chunks += 1;
-    if (!value || typeof value !== "object" || !Array.isArray(value.choices)) {
+    if (!value || !is.object(value) || !is.array(value.choices)) {
       invalid = true;
       return;
     }
@@ -227,8 +293,8 @@ function createStructuredStreamCapture() {
     if (
       choice?.index !== 0
       || !delta
-      || typeof delta !== "object"
-      || Array.isArray(delta)
+      || !is.object(delta)
+      || is.array(delta)
       || (delta.role !== undefined && delta.role !== "assistant")
       || (choice.finish_reason !== undefined && choice.finish_reason !== null)
       || delta.tool_calls !== undefined
@@ -239,7 +305,7 @@ function createStructuredStreamCapture() {
       return;
     }
     if (delta.content === undefined || delta.content === null) return;
-    if (typeof delta.content !== "string") {
+    if (!is.string(delta.content)) {
       invalid = true;
       return;
     }
@@ -296,7 +362,7 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
   }
 
   function cancellationError(reason, fallback = "The Wllama operation was cancelled.") {
-    return reason instanceof Error ? reason : new Error(reason ? String(reason) : fallback);
+    return is.error(reason) ? reason : new Error(reason ? String(reason) : fallback);
   }
 
   function trackOperation(rawOperation) {
@@ -380,7 +446,7 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
     });
     next.setCompat(null);
     for (const method of ["arcaneLoadModel", "arcaneTelemetry", "arcaneTerminate"]) {
-      if (typeof next[method] !== "function") {
+      if (!is.function(next[method])) {
         throw new Error(`The packaged Wllama projection is missing public ${method}().`);
       }
     }
@@ -401,10 +467,10 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
   }
 
   async function load(files, options = {}) {
-    if (!Array.isArray(files) || files.length === 0) {
+    if (!is.array(files) || files.length === 0) {
       throw new TypeError("Wllama load() requires at least one File or Blob.");
     }
-    if (typeof globalThis.WebAssembly !== "object") {
+    if (!is.object(globalThis.WebAssembly)) {
       throw new Error("WebAssembly is unavailable in this browser.");
     }
     if (!globalThis.navigator?.gpu) {
@@ -435,25 +501,25 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
       loadOptions.n_ubatch = normalizePositiveInteger(options.microBatchTokens, 128);
     }
     if (options.reasoning !== undefined) {
-      if (typeof options.reasoning !== "boolean") {
+      if (!is.boolean(options.reasoning)) {
         throw new TypeError("reasoning must be a boolean when provided.");
       }
       loadOptions.reasoning = options.reasoning;
     }
     if (options.chatTemplate !== undefined) {
-      if (typeof options.chatTemplate !== "string") {
+      if (!is.string(options.chatTemplate)) {
         throw new TypeError("chatTemplate must be a string when provided.");
       }
       loadOptions.chat_template = options.chatTemplate;
     }
     if (options.jinja !== undefined) {
-      if (typeof options.jinja !== "boolean") {
+      if (!is.boolean(options.jinja)) {
         throw new TypeError("jinja must be a boolean when provided.");
       }
       loadOptions.jinja = options.jinja;
     }
     if (options.templateDefaults !== undefined) {
-      if (!options.templateDefaults || typeof options.templateDefaults !== "object" || Array.isArray(options.templateDefaults)) {
+      if (!options.templateDefaults || !is.object(options.templateDefaults) || is.array(options.templateDefaults)) {
         throw new TypeError("templateDefaults must be a plain object when provided.");
       }
       loadOptions.default_template_kwargs = { ...options.templateDefaults };
@@ -466,6 +532,18 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
       cleanup: null,
     });
     const loadController = new AbortController();
+    let progressFailure = null;
+    const releaseLoadProgress = sessionObservers.get(next).beginLoadProgress(
+      function reportRuntimeLoadProgress(progress) {
+        if (loadController.signal.aborted || !is.function(options.onProgress)) return;
+        try {
+          options.onProgress(progress);
+        } catch (error) {
+          progressFailure = error;
+          loadController.abort(error);
+        }
+      },
+    );
     const loadOperation = Promise.resolve().then(() => (
       next.arcaneLoadModel(files, loadOptions, loadController.signal)
     ));
@@ -481,8 +559,9 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
     else signal?.addEventListener?.("abort", onAbort, { once: true });
     try {
       await loadOperation;
+      if (progressFailure) throw progressFailure;
       if (pending?.engine !== next) throw new Error("Wllama load was cancelled.");
-      if (typeof next.isModelLoaded !== "function" || next.isModelLoaded() !== true) {
+      if (!is.function(next.isModelLoaded) || next.isModelLoaded() !== true) {
         throw runtimeFailure(
           "ARCANE_AI_LOAD_FAILED",
           "Wllama did not confirm a successfully loaded model.",
@@ -493,6 +572,7 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
       engine = next;
       publishEvidence({ state: "ready", webgpu, cancellation: null, cleanup: null });
     } catch (error) {
+      releaseLoadProgress();
       let cleanupFailure = null;
       try {
         await exitSession(next);
@@ -510,6 +590,7 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
       if (cleanupFailure) throw cleanupFailure;
       throw error;
     } finally {
+      releaseLoadProgress();
       signal?.removeEventListener?.("abort", onAbort);
     }
 
@@ -553,13 +634,13 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
         lastObservedOperational: evidenceState.webgpu?.lastObservedOperational === true,
       },
       failure: completeValue({
-        code: typeof error?.code === "string" ? error.code : "ARCANE_AI_RUNTIME_FAILED",
+        code: is.string(error?.code) ? error.code : "ARCANE_AI_RUNTIME_FAILED",
       }),
     });
   }
 
   async function inference(options, onData = null) {
-    if (!options || typeof options !== "object" || Array.isArray(options)) {
+    if (!options || !is.object(options) || is.array(options)) {
       throw new TypeError("Wllama inference options must be an object.");
     }
     if (Object.hasOwn(options, "signal")) {
@@ -629,7 +710,7 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
   }
 
   function stream(options, onData) {
-    if (typeof onData !== "function") {
+    if (!is.function(onData)) {
       throw new TypeError("Wllama stream() requires an onData callback.");
     }
     return inference({ ...options, stream: true }, onData);
@@ -653,7 +734,7 @@ export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
 
   async function probe({ args = ["-o", "ADD"] } = {}) {
     if (engine) throw new Error("The no-model Wllama probe cannot run while a model is loaded.");
-    if (!Array.isArray(args) || args.some((value) => typeof value !== "string")) {
+    if (!is.array(args) || args.some((value) => !is.string(value))) {
       throw new TypeError("Wllama probe args must be an array of strings.");
     }
     const temporary = newEngine();