arcane-os 0.1.0-dev.5 → 0.1.1

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

@@ -0,0 +1,44 @@
+import { createModelController, ModelController } from "./model-controller.mjs";
+import {
+  createBrowserModelSource,
+  createBrowserWasmLlmProvider,
+  createDbopfsModelStore,
+} from "./browser-wasm-llm-provider.mjs";
+import { BROWSER_WASM_RUNTIME_AUTHORITY } from "./browser-wllama-runtime.mjs";
+
+/**
+ * Creates the generic Arcane browser-local AI facade. The SDK owns lifecycle,
+ * integrity, cache, streaming, and structural tool visibility; applications
+ * continue to own prompts, tools, policies, and any decision to execute a tool.
+ */
+function createArcaneAI({
+  llm = null,
+  provider = null,
+  loadPolicy = "on-demand",
+} = {}) {
+  const selected = llm ?? provider;
+  if (!selected) throw new TypeError("createArcaneAI requires an llm provider.");
+  const controller = selected instanceof ModelController
+    ? selected
+    : createModelController({ provider: selected, loadPolicy });
+
+  return Object.freeze({
+    llm: controller,
+    runtime: BROWSER_WASM_RUNTIME_AUTHORITY,
+    status: () => Object.freeze({ llm: controller.status() }),
+    load: (options) => controller.load(options),
+    unload: (options) => controller.unload(options),
+    probe: (options) => controller.probe(options),
+    fetchRequest: (options) => controller.fetchRequest(options),
+    streamRequest: (options) => controller.streamRequest(options),
+    dispose: (options) => controller.dispose(options),
+  });
+}
+
+export {
+  BROWSER_WASM_RUNTIME_AUTHORITY,
+  createArcaneAI,
+  createBrowserModelSource,
+  createBrowserWasmLlmProvider,
+  createDbopfsModelStore,
+};

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

@@ -0,0 +1,390 @@
+import { Wllama } from "./wllama/index.mjs";
+
+const MODULE_URL = new URL("./wllama/index.mjs", import.meta.url).href;
+const WASM_URL = new URL("./wllama/wllama.wasm", import.meta.url).href;
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const nested of Object.values(value)) deepFreeze(nested);
+  return Object.freeze(value);
+}
+
+export const BROWSER_WASM_RUNTIME_AUTHORITY = deepFreeze({
+  protocol: "arcane-ai-browser-wasm/1",
+  provider: "wllama",
+  package: {
+    name: "@wllama/wllama",
+    version: "3.6.0",
+    sourceRevision: "f16050d8d51a00602c6a2a6b8ac9c09f490eea7f",
+    resolved: "https://registry.npmjs.org/@wllama/wllama/-/wllama-3.6.0.tgz",
+    npmIntegrity: "sha512-NN3ZBXqaaUwGXTQubkNvsCaLPjN2XVa0bVS40OYCE8zquYmRc2W3oHYEgwvuSWWDB8aUqTLyMioySCXNkcnD1w==",
+    tarballBytes: 5_671_369,
+    tarballSha256: "137c35ceccb4911a9b0ce9b427889f75991654ec6a6d1dd8fabd879b14b07a1b",
+    licenseSpdx: "MIT",
+    license: {
+      path: "ai/wllama/LICENCE",
+      bytes: 1_071,
+      sha256: "5866e3bd7e3cbd3f7c8bea6efd8a1e7fa7cc8de68c30f428aff7c6584a0fb720",
+    },
+  },
+  llamaCpp: {
+    sourceRevision: "4df29be4f4c3673f428170fda944a5b19f743bb8",
+    licenseSpdx: "MIT",
+    license: {
+      path: "ai/wllama/llama.cpp-LICENSE",
+      bytes: 1_078,
+      sha256: "94f29bbed6a22c35b992c5c6ebf0e7c92f13b836b90f36f461c9cf2f0f1d010d",
+    },
+  },
+  runtimeAssets: {
+    module: {
+      path: "ai/wllama/index.mjs",
+      url: MODULE_URL,
+      bytes: 373_519,
+      sha256: "4637e42d636010493a9b274fbbe70bfd8120365da726b1d9e589d85ca84a00d6",
+      mediaType: "text/javascript",
+    },
+    wasm: {
+      path: "ai/wllama/wllama.wasm",
+      url: WASM_URL,
+      bytes: 8_524_865,
+      sha256: "95c6ff9ef2a03ff2c63bc91db132f0126a0bd0456b272cd8ae2e0f592fb059f6",
+      mediaType: "application/wasm",
+    },
+  },
+  networkPolicy: {
+    compatibilityRuntime: "disabled",
+    remoteModelHelpers: false,
+    modelInput: "verified-local-file-only",
+  },
+});
+
+function runtimeCapabilitySnapshot() {
+  const navigatorObject = globalThis.navigator;
+  return Object.freeze({
+    webAssembly: typeof globalThis.WebAssembly === "object",
+    opfs: typeof navigatorObject?.storage?.getDirectory === "function",
+    webgpu: Boolean(navigatorObject?.gpu),
+    crossOriginIsolated: globalThis.crossOriginIsolated === true,
+    secureContext: globalThis.isSecureContext === true,
+    hardwareConcurrency: Number.isSafeInteger(navigatorObject?.hardwareConcurrency)
+      ? navigatorObject.hardwareConcurrency
+      : null,
+  });
+}
+
+function normalizePositiveInteger(value, fallback, { maximum = Number.MAX_SAFE_INTEGER } = {}) {
+  if (value === undefined || value === null) return fallback;
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 1 || number > maximum) {
+    throw new RangeError(`Expected an integer from 1 through ${maximum}.`);
+  }
+  return number;
+}
+
+/**
+ * Creates one packaged Wllama session. This factory has no network or browser
+ * side effects until load() is called. Runtime URLs are fixed relative to this
+ * module so the same bytes work from npm and a materialized /arcane/sdk tree.
+ */
+export function createPackagedWllamaRuntime({ logger = console } = {}) {
+  let engine = null;
+  let pending = null;
+  const trackedOperations = new Set();
+  const sessionExitPromises = new WeakMap();
+
+  function cancellationError(reason, fallback = "The Wllama operation was cancelled.") {
+    return reason instanceof Error ? reason : new Error(reason ? String(reason) : fallback);
+  }
+
+  function trackOperation(rawOperation) {
+    const raw = Promise.resolve(rawOperation);
+    raw.catch(() => undefined);
+    let rejectCancellation;
+    const cancellation = new Promise((_, reject) => {
+      rejectCancellation = reject;
+    });
+    let cancelled = false;
+    const record = {
+      cancel(reason) {
+        if (cancelled) return false;
+        cancelled = true;
+        rejectCancellation(cancellationError(reason));
+        return true;
+      },
+    };
+    trackedOperations.add(record);
+    const result = Promise.race([raw, cancellation]).finally(() => {
+      trackedOperations.delete(record);
+    });
+    result.catch(() => undefined);
+    return Object.freeze({ raw, result, cancel: record.cancel });
+  }
+
+  function cancelTrackedOperations(reason) {
+    for (const operation of [...trackedOperations]) operation.cancel(reason);
+  }
+
+  function requireConfigurableDataProperty(object, key, label) {
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (!descriptor?.configurable || !("value" in descriptor) || descriptor.get || descriptor.set) {
+      throw new Error(`Pinned Wllama ${label} is not a configurable data property.`);
+    }
+    return descriptor;
+  }
+
+  function guardLoadingSession(session) {
+    const sessionDescriptor = requireConfigurableDataProperty(session, "proxy", "proxy");
+    let proxy = sessionDescriptor.value;
+    let cancelled = null;
+    const workerGuards = new Map();
+
+    function guardProxy(nextProxy) {
+      if (!nextProxy || workerGuards.has(nextProxy)) return;
+      const descriptor = requireConfigurableDataProperty(nextProxy, "worker", "proxy worker");
+      let worker = descriptor.value;
+      Object.defineProperty(nextProxy, "worker", {
+        enumerable: descriptor.enumerable,
+        configurable: true,
+        get: () => worker,
+        set(value) {
+          if (value && cancelled) {
+            value.terminate?.();
+            throw cancelled;
+          }
+          worker = value;
+        },
+      });
+      workerGuards.set(nextProxy, () => {
+        Object.defineProperty(nextProxy, "worker", { ...descriptor, value: worker });
+      });
+      if (worker && cancelled) {
+        worker.terminate?.();
+        throw cancelled;
+      }
+    }
+
+    if (proxy) guardProxy(proxy);
+    Object.defineProperty(session, "proxy", {
+      enumerable: sessionDescriptor.enumerable,
+      configurable: true,
+      get: () => proxy,
+      set(value) {
+        if (value && cancelled) {
+          value.worker?.terminate?.();
+          throw cancelled;
+        }
+        proxy = value;
+        if (value) guardProxy(value);
+      },
+    });
+
+    return Object.freeze({
+      cancel(reason) {
+        cancelled ||= cancellationError(reason, "The Wllama model load was cancelled.");
+        const current = proxy;
+        current?.worker?.terminate?.();
+        try {
+          current?.abort?.(cancelled.message, "");
+        } catch {
+          // The tracked operation gate remains the stable cancellation result.
+        }
+        return cancelled;
+      },
+      restore() {
+        for (const restoreWorker of workerGuards.values()) restoreWorker();
+        workerGuards.clear();
+        Object.defineProperty(session, "proxy", { ...sessionDescriptor, value: proxy });
+      },
+    });
+  }
+
+  function exitSession(session, reason) {
+    if (!session) return Promise.resolve(false);
+    let exitPromise = sessionExitPromises.get(session);
+    if (!exitPromise) {
+      const attempt = Promise.resolve().then(() => {
+        try {
+          session.proxy?.abort?.(cancellationError(reason).message, "");
+        } catch {
+          // Public session.exit() still owns Worker termination.
+        }
+        return session.exit();
+      }).then(() => true);
+      exitPromise = attempt.catch((error) => {
+        // A failed cleanup attempt is not proof that this session is closed.
+        // Evict only this attempt so a later exit() can retry the same handle.
+        if (sessionExitPromises.get(session) === exitPromise) {
+          sessionExitPromises.delete(session);
+        }
+        throw error;
+      });
+      sessionExitPromises.set(session, exitPromise);
+    }
+    return exitPromise;
+  }
+
+  function newEngine() {
+    const next = new Wllama({ default: WASM_URL }, {
+      logger,
+      allowOffline: true,
+    });
+    next.setCompat(null);
+    const resources = next.getWorkerResources();
+    if (resources.compat !== false || resources.wasmPath !== WASM_URL || resources.jsPath) {
+      throw new Error("The packaged Wllama resource projection was not exact.");
+    }
+    return next;
+  }
+
+  function capabilities() {
+    return runtimeCapabilitySnapshot();
+  }
+
+  async function load(files, options = {}) {
+    if (!Array.isArray(files) || files.length === 0) {
+      throw new TypeError("Wllama load() requires at least one verified File or Blob.");
+    }
+    if (typeof globalThis.WebAssembly !== "object") {
+      throw new Error("WebAssembly is unavailable in this browser.");
+    }
+    if (engine || pending) {
+      throw new Error("The packaged Wllama runtime is already loaded or loading.");
+    }
+
+    // Wllama defaults to a CDN compatibility runtime. Arcane never admits it.
+    const next = newEngine();
+
+    const threads = normalizePositiveInteger(options.threads, 1, { maximum: 64 });
+    const contextTokens = normalizePositiveInteger(options.contextTokens, 4_096, {
+      maximum: 1_048_576,
+    });
+    const loadOptions = {
+      n_threads: threads,
+      n_ctx: contextTokens,
+      n_gpu_layers: Number.isSafeInteger(options.gpuLayers) ? options.gpuLayers : 0,
+    };
+    if (options.batchTokens !== undefined) {
+      loadOptions.n_batch = normalizePositiveInteger(options.batchTokens, 512, {
+        maximum: contextTokens,
+      });
+    }
+    if (options.microBatchTokens !== undefined) {
+      loadOptions.n_ubatch = normalizePositiveInteger(options.microBatchTokens, 128, {
+        maximum: contextTokens,
+      });
+    }
+
+    const loadGuard = guardLoadingSession(next);
+    const operation = trackOperation(Promise.resolve().then(() => next.loadModel(files, loadOptions)));
+    operation.raw.finally(loadGuard.restore).catch(() => undefined);
+    const cancel = (reason) => {
+      const error = loadGuard.cancel(reason);
+      operation.cancel(error);
+    };
+    pending = Object.freeze({
+      engine: next,
+      cancel,
+    });
+    const signal = options.signal ?? null;
+    const onAbort = () => cancel(signal.reason);
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener?.("abort", onAbort, { once: true });
+    try {
+      await operation.result;
+      if (pending?.engine !== next) throw new Error("Wllama load was cancelled.");
+      pending = null;
+      engine = next;
+    } catch (error) {
+      try {
+        await exitSession(next, error);
+        if (pending?.engine === next) pending = null;
+      } catch {
+        // Preserve the exact pending session for a later runtime.exit() retry.
+        // The original load failure remains the stable public rejection.
+      }
+      throw error;
+    } finally {
+      signal?.removeEventListener?.("abort", onAbort);
+    }
+
+    return Object.freeze({
+      loaded: true,
+      contextTokens,
+      threads,
+      metadata: engine.getModelMetadata?.() ?? null,
+    });
+  }
+
+  function assertLoaded() {
+    if (!engine?.isModelLoaded?.()) throw new Error("The packaged Wllama model is not loaded.");
+    return engine;
+  }
+
+  async function chat(options) {
+    const session = assertLoaded();
+    return trackOperation(
+      Promise.resolve().then(() => session.createChatCompletion({ ...options, stream: false })),
+    ).result;
+  }
+
+  async function stream(options, onData) {
+    if (typeof onData !== "function") {
+      throw new TypeError("Wllama stream() requires an onData callback.");
+    }
+    // Wllama owns the request slot until this promise settles. Its documented
+    // abortSignal path cancels the llama.cpp request in a finally block.
+    const session = assertLoaded();
+    return trackOperation(
+      Promise.resolve().then(() => session.createChatCompletion({ ...options, stream: true, onData })),
+    ).result;
+  }
+
+  async function exit() {
+    const current = engine;
+    const loading = pending;
+    const reason = new Error("Wllama was cancelled by unload.");
+    loading?.cancel(reason);
+    cancelTrackedOperations(reason);
+    const sessions = new Set([current, loading?.engine].filter(Boolean));
+    if (!sessions.size) return false;
+    await Promise.all([...sessions].map((session) => exitSession(session, reason)));
+    // Retain ownership through cleanup failure. Clear only the exact handles
+    // whose exit attempts completed successfully; replacement sessions, if
+    // any, remain owned by the runtime.
+    if (engine === current) engine = null;
+    if (pending === loading) pending = null;
+    return true;
+  }
+
+  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")) {
+      throw new TypeError("Wllama probe args must be an array of strings.");
+    }
+    const temporary = newEngine();
+    // testBackendOps owns and closes its temporary worker. It requires browser
+    // multithreading, but that is a probe capability—not model admission.
+    const result = await temporary.testBackendOps(args);
+    return Object.freeze({
+      ...result,
+      args: Object.freeze([...args]),
+      origin: globalThis.location?.origin ?? null,
+      capabilities: capabilities(),
+      runtime: BROWSER_WASM_RUNTIME_AUTHORITY,
+    });
+  }
+
+  return Object.freeze({
+    authority: BROWSER_WASM_RUNTIME_AUTHORITY,
+    runtimeAssets: BROWSER_WASM_RUNTIME_AUTHORITY.runtimeAssets,
+    capabilities,
+    load,
+    chat,
+    stream,
+    probe,
+    exit,
+    isLoaded: () => Boolean(engine?.isModelLoaded?.()),
+    isLoading: () => Boolean(pending),
+  });
+}

package/browser-runtime/ai/internal/sha256.mjs

@@ -0,0 +1,166 @@
+const ROUND_CONSTANTS = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5,
+  0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
+  0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+  0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3,
+  0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5,
+  0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+function rotateRight(value, bits) {
+  return (value >>> bits) | (value << (32 - bits));
+}
+
+function toBytes(value) {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  throw new TypeError("SHA-256 input must be bytes.");
+}
+
+/**
+ * Dependency-free incremental SHA-256. It retains one 64-byte tail and never
+ * buffers an entire model file in JavaScript memory.
+ */
+export function createStreamingSha256() {
+  const state = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
+    0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  const schedule = new Uint32Array(64);
+  const tail = new Uint8Array(64);
+  let tailLength = 0;
+  let byteLength = 0;
+  let finished = false;
+
+  function compress(block, offset = 0) {
+    for (let index = 0; index < 16; index += 1) {
+      const cursor = offset + (index * 4);
+      schedule[index] = (
+        (block[cursor] << 24)
+        | (block[cursor + 1] << 16)
+        | (block[cursor + 2] << 8)
+        | block[cursor + 3]
+      ) >>> 0;
+    }
+    for (let index = 16; index < 64; index += 1) {
+      const previous = schedule[index - 15];
+      const prior = schedule[index - 2];
+      const sigma0 = (
+        rotateRight(previous, 7) ^ rotateRight(previous, 18) ^ (previous >>> 3)
+      ) >>> 0;
+      const sigma1 = (
+        rotateRight(prior, 17) ^ rotateRight(prior, 19) ^ (prior >>> 10)
+      ) >>> 0;
+      schedule[index] = (
+        schedule[index - 16] + sigma0 + schedule[index - 7] + sigma1
+      ) >>> 0;
+    }
+
+    let a = state[0];
+    let b = state[1];
+    let c = state[2];
+    let d = state[3];
+    let e = state[4];
+    let f = state[5];
+    let g = state[6];
+    let h = state[7];
+
+    for (let index = 0; index < 64; index += 1) {
+      const sum1 = (rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25)) >>> 0;
+      const choice = ((e & f) ^ ((~e) & g)) >>> 0;
+      const temporary1 = (
+        h + sum1 + choice + ROUND_CONSTANTS[index] + schedule[index]
+      ) >>> 0;
+      const sum0 = (rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22)) >>> 0;
+      const majority = ((a & b) ^ (a & c) ^ (b & c)) >>> 0;
+      const temporary2 = (sum0 + majority) >>> 0;
+
+      h = g;
+      g = f;
+      f = e;
+      e = (d + temporary1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temporary1 + temporary2) >>> 0;
+    }
+
+    state[0] = (state[0] + a) >>> 0;
+    state[1] = (state[1] + b) >>> 0;
+    state[2] = (state[2] + c) >>> 0;
+    state[3] = (state[3] + d) >>> 0;
+    state[4] = (state[4] + e) >>> 0;
+    state[5] = (state[5] + f) >>> 0;
+    state[6] = (state[6] + g) >>> 0;
+    state[7] = (state[7] + h) >>> 0;
+  }
+
+  function update(value) {
+    if (finished) throw new Error("SHA-256 digest is already finalized.");
+    const input = toBytes(value);
+    byteLength += input.byteLength;
+    if (!Number.isSafeInteger(byteLength)) {
+      throw new RangeError("SHA-256 input exceeds the supported byte length.");
+    }
+
+    let offset = 0;
+    if (tailLength) {
+      const take = Math.min(64 - tailLength, input.byteLength);
+      tail.set(input.subarray(0, take), tailLength);
+      tailLength += take;
+      offset = take;
+      if (tailLength === 64) {
+        compress(tail);
+        tailLength = 0;
+      }
+    }
+
+    while (offset + 64 <= input.byteLength) {
+      compress(input, offset);
+      offset += 64;
+    }
+    if (offset < input.byteLength) {
+      tail.set(input.subarray(offset), 0);
+      tailLength = input.byteLength - offset;
+    }
+    return api;
+  }
+
+  function digestHex() {
+    if (finished) throw new Error("SHA-256 digest is already finalized.");
+    finished = true;
+    const finalLength = tailLength < 56 ? 64 : 128;
+    const finalBlocks = new Uint8Array(finalLength);
+    finalBlocks.set(tail.subarray(0, tailLength));
+    finalBlocks[tailLength] = 0x80;
+    let bitLength = BigInt(byteLength) * 8n;
+    for (let index = 0; index < 8; index += 1) {
+      finalBlocks[finalLength - 1 - index] = Number(bitLength & 0xffn);
+      bitLength >>= 8n;
+    }
+    for (let offset = 0; offset < finalLength; offset += 64) compress(finalBlocks, offset);
+    return [...state].map((word) => word.toString(16).padStart(8, "0")).join("");
+  }
+
+  const api = Object.freeze({
+    update,
+    digestHex,
+    get bytes() {
+      return byteLength;
+    },
+  });
+  return api;
+}