arcane-os 0.5.10 → 0.5.12

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.10",
+  "version": "0.5.12",
   "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",

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;
@@ -5673,7 +5673,8 @@ class AI {
 
     streamTTS(
         text='',
-        end=false
+        end=false,
+        options={}
     ){
         if(this.muted){
             if(end){
@@ -5682,6 +5683,12 @@ class AI {
             return Promise.resolve(false);
         }
 
+        const {voice,speed,waitForPlayback=false}=options;
+        const pauseAfterMs=Number(options.pauseAfterMs??0);
+        if(!Number.isFinite(pauseAfterMs)||pauseAfterMs<0){
+            throw new RangeError('Speech pauses must be a nonnegative number of milliseconds.');
+        }
+
         this.audioMessageChunks+=String(text||'');
         const outputs=this.#extractSpeechSegments(end);
 
@@ -5702,8 +5709,13 @@ class AI {
         const generation=this.speechGeneration;
         const jobs=[];
 
-        for(const output of outputs){
-            jobs.push(this.#queueSpeechJob(output,generation));
+        for(const [index,output] of outputs.entries()){
+            jobs.push(this.#queueSpeechJob(output,generation,{
+                voice,
+                speed,
+                waitForPlayback,
+                pauseAfterMs:index===outputs.length-1?pauseAfterMs:0
+            }));
         }
 
         return Promise.all(jobs).then(
@@ -5857,7 +5869,7 @@ class AI {
         return this.#speechAbbreviations.has(token);
     }
 
-    #queueSpeechJob(text,generation){
+    #queueSpeechJob(text,generation,options={}){
         const job={
             abortController:null,
             audioBuffer:null,
@@ -5867,13 +5879,22 @@ class AI {
             scheduledStart:null,
             sourceNode:null,
             state:'queued',
-            text
+            text,
+            voice:options.voice,
+            speed:options.speed,
+            pauseAfterMs:options.pauseAfterMs??0,
+            resolvePlayback:null
         };
         const runtime=this;
+        const playback=options.waitForPlayback===true
+            ?new Promise(function captureSpeechPlaybackCompletion(resolve){
+                job.resolvePlayback=resolve;
+            })
+            :null;
 
         this.speechJobs.push(job);
 
-        return Promise.resolve().then(
+        const preparation=Promise.resolve().then(
             function synthesizeAvailableSpeech(){
                 return runtime.#prepareSpeechJob(job);
             }
@@ -5886,6 +5907,7 @@ class AI {
                 );
             }
         );
+        return playback||preparation;
     }
 
     async #prepareSpeechJob(job){
@@ -5914,16 +5936,18 @@ class AI {
     async #requestSpeechAudio(job){
         job.abortController=new AbortController();
         const selection=this.#providerRuntime.selection('tts');
-        const voice=selection?this.#providerSpeechVoice():null;
+        const voice=job.voice===undefined
+            ?(selection?this.#providerSpeechVoice():null)
+            :job.voice;
         const response=await this.fetchTTS(
             {
                 model:selection?.modelId||this.modelTTS,
                 input:job.text,
-                ...(voice?{voice}:{}),
+                ...(job.voice!==undefined||voice?{voice}:{}),
                 responseFormat:selection
                     ?this.#providerSpeechResponseFormat()
                     :this.audioFormat,
-                speed:this.voiceSpeed
+                speed:job.speed===undefined?this.voiceSpeed:job.speed
             },
             job.abortController.signal
         );
@@ -6294,6 +6318,8 @@ class AI {
         for(const job of this.speechJobs){
             job.abortController?.abort();
             job.state='cancelled';
+            job.resolvePlayback?.(false);
+            job.resolvePlayback=null;
 
             if(job.sourceNode){
                 job.sourceNode.onended=null;
@@ -6370,6 +6396,22 @@ class AI {
             if(attempt===this.speechResumeAttempt){
                 this.speechResumePending=false;
             }
+            if(context?.state==='closed'){
+                this.#clearSpeechUnlock();
+                const jobs=this.speechJobs.filter(function usesClosedSpeechContext(job){
+                    return job.audioContext===context;
+                });
+                if(!jobs.length){
+                    this.#publishTTSFailure(error,{
+                        boundary:'playback-resume',
+                        generation:this.speechGeneration
+                    });
+                }
+                for(const job of jobs){
+                    this.#failSpeechJob(job,error,'playback-resume');
+                }
+                return false;
+            }
             this.#waitForSpeechGesture(error,context);
             if(error?.name!=='NotAllowedError'){
                 this.#publishTTSFailure(error,{
@@ -6543,7 +6585,7 @@ class AI {
                     job.state='scheduled';
                     job.scheduledStart=scheduledStart;
                     job.scheduledEnd=hasKnownDuration
-                        ?scheduledStart+duration
+                        ?scheduledStart+duration+(job.pauseAfterMs??0)/1000
                         :null;
                     job.sourceNode.__arcaneStarted=true;
                     if(!this.currentSpeechJob){
@@ -6606,6 +6648,11 @@ class AI {
             job.sourceNode.onended=null;
         }
 
+        if(job.scheduledEnd===null&&job.pauseAfterMs>0){
+            this.speechScheduleContext=job.audioContext;
+            this.speechScheduleTime=
+                (Number(job.audioContext?.currentTime)||0)+job.pauseAfterMs/1000;
+        }
         job.state='complete';
         this.#removeSpeechJob(job);
 
@@ -6727,6 +6774,8 @@ class AI {
     }
 
     #removeSpeechJob(job){
+        job.resolvePlayback?.(job.state==='complete');
+        job.resolvePlayback=null;
         const jobIndex=this.speechJobs.indexOf(job);
 
         if(jobIndex>=0){

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) {