arcane-os 0.5.9 → 0.5.11

package/examples/wasm-ai-demo/rag.js

@@ -0,0 +1,295 @@
+import DBOPFSDocumentLibrary from "arcane/DBOPFSDocumentLibrary";
+
+const DEFAULT_BOSS_BUNDLE_URL = "./rag/boss-library.json";
+const PROFILE_IDS = new Set(["general", "precrisis", "boss"]);
+const libraryEntries = new WeakMap();
+
+function normalizeProfileId(profileId) {
+  const normalized = String(profileId || "general").trim().toLowerCase();
+  if (!PROFILE_IDS.has(normalized)) {
+    throw new TypeError(`Unsupported example profile: ${normalized || "empty"}.`);
+  }
+  return normalized;
+}
+
+function reportStatus(onStatus, message) {
+  if (typeof onStatus === "function") onStatus(message);
+}
+
+function entryMap(dbopfs) {
+  let entries = libraryEntries.get(dbopfs);
+  if (!entries) {
+    entries = new Map();
+    libraryEntries.set(dbopfs, entries);
+  }
+  return entries;
+}
+
+function schemaFor(profileId, version = "1") {
+  return {
+    id: `wasm-ai-demo-${profileId}`,
+    table: `wasm_ai_demo_${profileId}_documents`,
+    version: String(version),
+  };
+}
+
+function createLibrary(dbopfs, profileId, version) {
+  return new DBOPFSDocumentLibrary({
+    db: dbopfs,
+    schema: schemaFor(profileId, version),
+  });
+}
+
+function splitTerms(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry).trim()).filter(Boolean);
+  }
+  return String(value || "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function bossRecord(document, index, sourcePath) {
+  const record = document && typeof document === "object" && !Array.isArray(document)
+    ? document
+    : {};
+  const id = String(record.id || `boss-library-${index + 1}`).trim();
+  const title = String(record.title || id).trim();
+  const body = String(record.text ?? record.body ?? "");
+  const terms = splitTerms(record.topics);
+  return {
+    body,
+    id,
+    kind: "boss-library",
+    mediaType: "text/markdown",
+    path: id,
+    searchTerms: terms,
+    sourcePath,
+    tags: ["boss", ...terms],
+    title,
+  };
+}
+
+async function fetchBossBundle(bundleUrl) {
+  const response = await fetch(bundleUrl, { cache: "no-store" });
+  if (!response.ok) {
+    throw new Error(`Unable to load the BOSS library: HTTP ${response.status}.`);
+  }
+  const bundle = await response.json();
+  if (!bundle || typeof bundle !== "object" || !Array.isArray(bundle.documents)) {
+    throw new TypeError("The BOSS library response must contain a documents array.");
+  }
+  return bundle;
+}
+
+async function readCorpus(library, signal) {
+  try {
+    return { ...(await library.search("", { signal })), bootstrapped: true };
+  } catch (error) {
+    if (error?.code === "DBOPFS_DOCUMENT_NOT_BOOTSTRAPPED") {
+      return { bootstrapped: false, failures: [], matches: [], total: 0 };
+    }
+    throw error;
+  }
+}
+
+async function prepareLibrary({ dbopfs, bundleUrl, initialLibrary, onStatus, profileId, signal }) {
+  let version = "1";
+  let bossDocuments = [];
+  if (profileId === "boss") {
+    reportStatus(onStatus, "Loading the BOSS document catalog…");
+    const bundle = await fetchBossBundle(bundleUrl);
+    version = String(bundle.schema_version ?? "1");
+    bossDocuments = bundle.documents.map((document, index) => (
+      bossRecord(document, index, bundleUrl)
+    ));
+  }
+
+  const library = profileId === "boss"
+    ? createLibrary(dbopfs, profileId, version)
+    : initialLibrary;
+  const existing = await readCorpus(library, signal);
+  const userDocuments = existing.matches.filter((document) => document.kind === "user-import");
+  const hasBossDocuments = existing.matches.some((document) => document.kind === "boss-library");
+  const needsBootstrap = !existing.bootstrapped || (profileId === "boss" && !hasBossDocuments);
+
+  if (needsBootstrap) {
+    const documents = profileId === "boss"
+      ? [...bossDocuments, ...userDocuments]
+      : userDocuments;
+    reportStatus(
+      onStatus,
+      profileId === "boss"
+        ? "Storing the BOSS library through the Arcane document library…"
+        : "Opening the Arcane document library…",
+    );
+    await library.bootstrap({
+      files: documents,
+      signal,
+      onProgress(progress) {
+        if (progress?.phase !== "writing") return;
+        reportStatus(
+          onStatus,
+          `Storing local documents ${progress.completed} of ${progress.total}…`,
+        );
+      },
+    });
+  }
+
+  return library;
+}
+
+async function libraryFor(profileId, { dbopfs, bundleUrl, onStatus, signal } = {}) {
+  const profile = normalizeProfileId(profileId);
+  const db = dbopfs ?? globalThis.dbopfs;
+  const initialLibrary = createLibrary(db, profile, "1");
+  if (db.readyPromise) await db.readyPromise;
+  const entries = entryMap(db);
+  let entry = entries.get(profile);
+  if (!entry) {
+    entry = {
+      library: null,
+      ready: prepareLibrary({
+        dbopfs: db,
+        bundleUrl: bundleUrl || DEFAULT_BOSS_BUNDLE_URL,
+        initialLibrary,
+        onStatus,
+        profileId: profile,
+        signal,
+      }),
+    };
+    entries.set(profile, entry);
+    try {
+      entry.library = await entry.ready;
+    } catch (error) {
+      entries.delete(profile);
+      throw error;
+    }
+  } else if (!entry.library) {
+    entry.library = await entry.ready;
+  }
+  return entry.library;
+}
+
+function corpusStats(corpus) {
+  const documents = corpus.matches || [];
+  const bossCount = documents.filter((document) => document.kind === "boss-library").length;
+  const userCount = documents.filter((document) => document.kind === "user-import").length;
+  return {
+    boss: bossCount,
+    bossCount,
+    bossDocuments: bossCount,
+    failures: corpus.failures || [],
+    imported: userCount,
+    total: documents.length,
+    userCount,
+    userDocuments: userCount,
+  };
+}
+
+async function initializeRag({
+  dbopfs = globalThis.dbopfs,
+  bundleUrl = DEFAULT_BOSS_BUNDLE_URL,
+  onStatus,
+  profileId = "general",
+  signal,
+} = {}) {
+  const library = await libraryFor(profileId, {
+    dbopfs,
+    bundleUrl,
+    onStatus,
+    signal,
+  });
+  const corpus = await library.search("", { signal });
+  reportStatus(onStatus, "Local Arcane document library ready.");
+  return corpusStats(corpus);
+}
+
+async function getRagStats(profileId = "general", {
+  dbopfs = globalThis.dbopfs,
+  signal,
+} = {}) {
+  const library = await libraryFor(profileId, { dbopfs, signal });
+  return corpusStats(await library.search("", { signal }));
+}
+
+async function importedDocument(file, profileId) {
+  const fallbackId = `${Date.now()}-${Math.random()}`;
+  const id = `user-${profileId}-${globalThis.crypto?.randomUUID?.() || fallbackId}`;
+  const body = await file.text();
+  return {
+    body,
+    id,
+    kind: "user-import",
+    mediaType: file.type === "text/markdown" ? "text/markdown" : "text/plain",
+    path: file.name || id,
+    searchTerms: splitTerms(file.name),
+    sourcePath: file.name || id,
+    tags: [profileId, "user-import"],
+    title: file.name || "Imported document",
+  };
+}
+
+async function importRagFiles(files, {
+  dbopfs = globalThis.dbopfs,
+  onStatus,
+  profileId = "general",
+  signal,
+} = {}) {
+  if (!Array.isArray(files)) throw new TypeError("RAG files must be an array.");
+  const profile = normalizeProfileId(profileId);
+  const library = await libraryFor(profile, { dbopfs, onStatus, signal });
+  const corpus = await library.search("", { signal });
+  const imported = [];
+  for (let index = 0; index < files.length; index += 1) {
+    if (signal?.aborted) throw signal.reason || new DOMException("Aborted", "AbortError");
+    const file = files[index];
+    if (!file || typeof file.text !== "function") {
+      throw new TypeError(`RAG file ${index + 1} is not a browser File.`);
+    }
+    reportStatus(onStatus, `Reading ${file.name || `document ${index + 1}`}…`);
+    imported.push(await importedDocument(file, profile));
+  }
+  await library.bootstrap({
+    files: [...corpus.matches, ...imported],
+    signal,
+    onProgress(progress) {
+      if (progress?.phase === "writing") {
+        reportStatus(
+          onStatus,
+          `Storing local documents ${progress.completed} of ${progress.total}…`,
+        );
+      }
+    },
+  });
+  return {
+    imported: imported.length,
+    stats: corpusStats(await library.search("", { signal })),
+  };
+}
+
+async function retrieveRagContext(query, {
+  dbopfs = globalThis.dbopfs,
+  profileId = "general",
+  signal,
+} = {}) {
+  const profile = normalizeProfileId(profileId);
+  const library = await libraryFor(profile, { dbopfs, signal });
+  const result = await library.buildContext(String(query || ""), { signal });
+  const text = result.text && profile === "boss"
+    ? ["<boss_library_context>", result.text, "</boss_library_context>"].join("\n\n")
+    : result.text;
+  return {
+    failures: result.failures,
+    matches: result.documents,
+    text,
+  };
+}
+
+export {
+  getRagStats,
+  importRagFiles,
+  initializeRag,
+  retrieveRagContext,
+};

package/examples/wasm-ai-demo/server.mjs

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { startSourceExampleServer } from "arcane-os";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const sdkRoot = path.resolve(root, "..", "..");
+const examplePath = "/examples/wasm-ai-demo";
+const requestedPort = Number.parseInt(process.argv[2] || "4173", 10);
+const port = Number.isFinite(requestedPort) ? requestedPort : 4173;
+const host = process.argv[3] || "0.0.0.0";
+const modelDirectory = process.env.ARCANE_WASM_MODEL_ROOT
+  ? path.resolve(process.env.ARCANE_WASM_MODEL_ROOT)
+  : path.join(root, "models");
+const tlsDirectory = process.env.ARCANE_WASM_TLS_ROOT
+  ? path.resolve(process.env.ARCANE_WASM_TLS_ROOT)
+  : path.join(root, "tls");
+const tlsKeyPath = path.join(tlsDirectory, "server-key.pem");
+const tlsCertificatePath = path.join(tlsDirectory, "server.pem");
+const tls = existsSync(tlsKeyPath) && existsSync(tlsCertificatePath)
+  ? {
+      key: readFileSync(tlsKeyPath),
+      cert: readFileSync(tlsCertificatePath),
+    }
+  : undefined;
+
+const running = await startSourceExampleServer({
+  crossOriginIsolated: true,
+  host,
+  mounts: [
+    {
+      include: [
+        "index.html",
+        "app.js",
+        "rag.js",
+        "profile-tools.js",
+        "profiles/",
+        "rag/",
+      ],
+      index: "index.html",
+      root,
+      urlPath: examplePath,
+    },
+    {
+      root: modelDirectory,
+      urlPath: `${examplePath}/models`,
+    },
+    {
+      root: path.join(sdkRoot, "src"),
+      urlPath: "/src",
+    },
+    {
+      root: path.join(sdkRoot, "browser-runtime"),
+      urlPath: "/browser-runtime",
+    },
+    {
+      include: ["arcane/", "strong-type/"],
+      root: path.join(sdkRoot, "runtime"),
+      urlPath: "/runtime",
+    },
+  ],
+  port,
+  startPath: `${examplePath}/`,
+  tls,
+});
+
+console.log(`Arcane WASM Voice Chat listening on ${running.origin}`);
+console.log(`Example URL: ${running.url}`);
+console.log(`Live Arcane SDK source: ${sdkRoot}`);
+
+await running.closed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -44,6 +44,15 @@
     "src/",
     "runtime/",
     "schemas/",
+    "docs/",
+    "examples/wasm-ai-demo/README.md",
+    "examples/wasm-ai-demo/index.html",
+    "examples/wasm-ai-demo/app.js",
+    "examples/wasm-ai-demo/server.mjs",
+    "examples/wasm-ai-demo/profile-tools.js",
+    "examples/wasm-ai-demo/rag.js",
+    "examples/wasm-ai-demo/profiles/",
+    "examples/wasm-ai-demo/rag/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -54,7 +63,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/packaging.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/site.test.mjs test/update-check.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/packaging.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/site.test.mjs test/update-check.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/native-provider-generation.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/runtime/arcane/modules/AI.js

@@ -23,7 +23,7 @@ const DEFAULT_TTS_SEGMENTATION={
 };
 const DEFAULT_BROWSER_TTS_EXECUTION={
     device:'auto',
-    maxConcurrentRequests:2
+    maxConcurrentRequests:4
 };
 const BROWSER_TTS_EXECUTION_DEVICES=new Set(['auto','webgpu','wasm']);
 const MAX_BROWSER_TTS_CONCURRENT_REQUESTS=4;

package/runtime/arcane/modules/AIProviderRuntime.js

@@ -2415,12 +2415,33 @@ export class AIProviderRuntime {
         return this.configure(selections);
     }
 
-    status(role = null) {
-        if (role === null) {
-            return getAIRuntimeState();
+    status(role = null, options = {}) {
+        if (role !== null) {
+            assertRole(role);
         }
-        assertRole(role);
-        return getAIRuntimeState().roles[role];
+        const snapshot = getAIRuntimeState();
+        if (options?.execution !== true) {
+            return role === null ? snapshot : snapshot.roles[role];
+        }
+
+        // Live provider inspection is explicit so ordinary lifecycle reads
+        // retain their sticky snapshot identity and never call a provider.
+        const roles = {...snapshot.roles};
+        for (const selectedRole of role === null ? AI_RUNTIME_ROLES : [role]) {
+            const provider = this.#providerFor(this.#slots[selectedRole]);
+            if (!provider) {
+                continue;
+            }
+            const providerStatus = validateProviderStatus(provider.status());
+            if (providerStatus.execution == null) {
+                continue;
+            }
+            roles[selectedRole] = {
+                ...roles[selectedRole],
+                execution: {...providerStatus.execution}
+            };
+        }
+        return role === null ? {...snapshot, roles} : roles[role];
     }
 
     catalog(role) {