arcane-os 0.62.0 → 0.64.0

package/src/local-ai/image-library.mjs

@@ -18,6 +18,15 @@ export function createImageLibrary(
 ) {
     const requireBinding = createRequire(bindingModulePath);
     const koffi = requireBinding(bindingModulePath);
+    const configuration = koffi.config();
+    // Async inference needs the normal native stack before Koffi creates its pools.
+    if (configuration.async_stack_size < configuration.sync_stack_size) {
+        koffi.config(
+            {
+                async_stack_size: configuration.sync_stack_size
+            }
+        );
+    }
     const library = loadLibrary(libraryPath);
     const backendDirectory = dirname(libraryPath);
     let backendLibrary;

package/src/local-ai/image-models/flux.mjs

@@ -0,0 +1,31 @@
+/** Distilled Klein model resources; acquisition belongs to the model asset owner. */
+export const FLUX2_KLEIN_4B_MODEL = {
+    id: 'flux2-klein-4b',
+    name: 'FLUX.2 Klein 4B',
+    family: 'flux',
+    resources: {
+        diffusion_model: {
+            url: 'https://huggingface.co/black-forest-labs/FLUX.2-klein-4B/resolve/e7b7dc27f91deacad38e78976d1f2b499d76a294/flux-2-klein-4b.safetensors',
+            filename: 'flux-2-klein-4b.safetensors'
+        },
+        vae: {
+            url: 'https://huggingface.co/black-forest-labs/FLUX.2-small-decoder/resolve/a3efc24f613ef42d9428af62fdbd6f5fd8856c4a/full_encoder_small_decoder.safetensors',
+            filename: 'full_encoder_small_decoder.safetensors'
+        },
+        llm: {
+            url: 'https://huggingface.co/Qwen/Qwen3-4B-GGUF/resolve/bc640142c66e1fdd12af0bd68f40445458f3869b/Qwen3-4B-Q8_0.gguf',
+            filename: 'Qwen3-4B-Q8_0.gguf'
+        }
+    },
+    context: {},
+    defaults: {
+        sample_params: {
+            sample_steps: 4,
+            sample_method: 'euler',
+            guidance: {
+                txt_cfg: 1
+            }
+        }
+    },
+    operations: ['txt2img']
+};

package/src/local-ai/image-models/sdxl.mjs

@@ -0,0 +1,18 @@
+/** Official complete SDXL checkpoint; acquisition belongs to the model asset owner. */
+export const SDXL_BASE_1_0_MODEL = {
+    id: 'sdxl-base-1.0',
+    name: 'SDXL Base 1.0',
+    family: 'sdxl',
+    resources: {
+        model: {
+            url: 'https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/462165984030d82259a11f4367a4eed129e94a7b/sd_xl_base_1.0.safetensors',
+            filename: 'sd_xl_base_1.0.safetensors'
+        }
+    },
+    context: {},
+    defaults: {
+        width: 1024,
+        height: 1024
+    },
+    operations: ['txt2img']
+};

package/src/local-ai/install.mjs

@@ -10,6 +10,8 @@ import {createEventQueue} from '../event-queue.mjs';
 import {runProcess} from '../process.mjs';
 import {extractLocalAIArchive} from './archive.mjs';
 import {normalizeImageRuntimeRequirement} from './config.mjs';
+import {normalizeWhisperRuntimeRequirement} from './whisper/config.mjs';
+import {bundledWhisperRuntime, installedWhisperRuntime, installWhisperDistribution, whisperRuntimeSelection} from './whisper/install.mjs';
 
 const is=new Is(false);
 const installations=new Map();
@@ -21,11 +23,15 @@ function selectRuntimes(runtimes){
     const selected=new Map();
     for(const item of runtimes){
         const requirement=is.string(item)?{id:item}:item;
-        const runtime=requirement?.id==='stable-diffusion.cpp'?normalizeImageRuntimeRequirement(requirement):requirement;
-        if(!runtime||!['llama.cpp','ollama','nemo-speech','onnx','stable-diffusion.cpp'].includes(runtime.id)){
+        const runtime=requirement?.id==='stable-diffusion.cpp'?normalizeImageRuntimeRequirement(requirement)
+            :requirement?.id==='whisper.cpp'?normalizeWhisperRuntimeRequirement(requirement):requirement;
+        if(!runtime||!['llama.cpp','ollama','nemo-speech','onnx','stable-diffusion.cpp','whisper.cpp'].includes(runtime.id)){
             throw new ArcaneError(ERROR_CODES.targetUnavailable,`Local AI runtime installation is unavailable for ${String(runtime?.id)}.`);
         }
         const prior=selected.get(runtime.id);
+        if(prior&&runtime.id==='whisper.cpp'&&whisperRuntimeSelection(prior)!==whisperRuntimeSelection(runtime)){
+            throw new ArcaneError(ERROR_CODES.usage,'Select one complete whisper.cpp runtime and model requirement for this operation.');
+        }
         if(prior&&(prior.version!==runtime.version||prior.url!==runtime.url||(runtime.id==='stable-diffusion.cpp'&&prior.backend!==runtime.backend))){
             throw new ArcaneError(ERROR_CODES.usage,`Select one ${runtime.id} runtime version and URL for this operation.`);
         }
@@ -351,7 +357,7 @@ function bundledImageModelResource(resource, descriptor, model, role, runtimeRoo
     return bundled;
 }
 
-async function installedRuntime(base,runtime,platform,architecture,signal){
+async function installedRuntime(base,runtime,platform,architecture,signal,reuseWhisper=false){
     let entries;
     try{
         entries=await readdir(base,{withFileTypes:true});
@@ -374,9 +380,19 @@ async function installedRuntime(base,runtime,platform,architecture,signal){
         }
         if(installation.requestVersion!==(runtime.version??null)||installation.requestUrl!==(runtime.url??null))continue;
         if (runtime.id === 'stable-diffusion.cpp' && installation.requestBackend !== runtime.backend) continue;
+        let whisperRequirement;
+        if (runtime.id === 'whisper.cpp') {
+            if (!installation.requestWhisper) continue;
+            whisperRequirement = JSON.parse(installation.requestWhisper);
+            if (whisperRuntimeSelection(whisperRequirement, !reuseWhisper) !== whisperRuntimeSelection(runtime, !reuseWhisper)) continue;
+        }
         const record=installation.runtime;
         if(record?.id!==runtime.id||record.platform!==platform||record.architecture!==architecture)continue;
         try{
+            if(runtime.id==='whisper.cpp'){
+                if(await installedWhisperRuntime(record,signal,!reuseWhisper))return reuseWhisper?{runtime:record,requirement:whisperRequirement}:record;
+                continue;
+            }
             if (runtime.id === 'stable-diffusion.cpp') {
                 const locations = [record.libraryPath, record.bindingModulePath];
                 if (!Array.isArray(record.variants) || record.variants.length === 0) continue;
@@ -524,10 +540,11 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
         await onEvent({type:'local-ai.install.available',message:`${runtime.id} ${installed.version} is already installed.`,data:installed});
         return installed;
     }
+    const reusableWhisper=runtime.id==='whisper.cpp'?await installedRuntime(base,runtime,platform,architecture,signal,true):null;
     if(runtime.id==='onnx'&&(!['win32','linux','darwin'].includes(platform)||!['x64','arm64'].includes(architecture))){
         throw new ArcaneError(ERROR_CODES.targetUnavailable,`onnxruntime-node has no supported ${platform}/${architecture} CPU runtime.`);
     }
-    const release=runtime.id==='onnx'?null:await selectRelease(runtime,platform,architecture,signal);
+    const release=['onnx','whisper.cpp'].includes(runtime.id)?null:await selectRelease(runtime,platform,architecture,signal);
     throwIfAborted(signal);
     await mkdir(base,{recursive:true});
     const attempt=await mkdtemp(path.join(base,'install-'));
@@ -538,6 +555,8 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
         let locations;
         if(runtime.id==='onnx'){
             locations=await installONNXPackage(runtime,{root,directory,platform,architecture,signal,onEvent});
+        } else if (runtime.id === 'whisper.cpp') {
+            locations = await installWhisperDistribution(runtime, {root, directory, platform, architecture, signal, onEvent, upstreamResponse, reusable: reusableWhisper});
         } else if (runtime.id === 'stable-diffusion.cpp') {
             locations = await installImageDistribution(
                 release,
@@ -556,7 +575,7 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
         const record={id:runtime.id,platform,architecture,root,...locations,...(runtime.version?{requestedVersion:runtime.version}:{})};
         throwIfAborted(signal);
         if(archive)await unlink(archive);
-        await writeFile(path.join(attempt,'installation.json'),`${JSON.stringify({requestVersion:runtime.version??null,requestUrl:runtime.url??null,...(runtime.id==='stable-diffusion.cpp'?{requestBackend:runtime.backend}:{}),runtime:record},null,2)}\n`,{flag:'wx',signal});
+        await writeFile(path.join(attempt,'installation.json'),`${JSON.stringify({requestVersion:runtime.version??null,requestUrl:runtime.url??null,...(runtime.id==='stable-diffusion.cpp'?{requestBackend:runtime.backend}:{}),...(runtime.id==='whisper.cpp'?{requestWhisper:whisperRuntimeSelection(runtime)}:{}),runtime:record},null,2)}\n`,{flag:'wx',signal});
         completed=true;
         await onEvent({type:'local-ai.install.completed',message:`${runtime.id} ${record.version} is available.`,data:record});
         return record;
@@ -576,7 +595,7 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
 
 function shareInstallation(runtime,options){
     throwIfAborted(options.signal);
-    const key=JSON.stringify([options.directory,options.platform,options.architecture,runtime.id,runtime.version??null,runtime.url??null,runtime.id==='stable-diffusion.cpp'?runtime.backend:null]);
+    const key=JSON.stringify([options.directory,options.platform,options.architecture,runtime.id,runtime.version??null,runtime.url??null,runtime.id==='stable-diffusion.cpp'?runtime.backend:null,runtime.id==='whisper.cpp'?whisperRuntimeSelection(runtime):null]);
     let entry=installations.get(key);
     if(entry?.controller.signal.aborted){
         // The prior cancelled attempt owns its cleanup. A later request waits
@@ -725,7 +744,7 @@ export async function bundleLocalAIRuntimes({runtimes=[],directory,outputRoot,pl
         const files=[];
         const relative=`runtime/local-ai/${runtime.id}`;
         const destination=path.join(root,relative);
-        const bundled={...runtime,root:relative};
+        const bundled=runtime.id==='whisper.cpp'?bundledWhisperRuntime(runtime,relative):{...runtime,root:relative};
         for(const field of ['executable','modulePath','includeDirectory','libraryDirectory','binaryDirectory','cmakeDirectory','libraryPath','bindingModulePath']){
             if(runtime[field]===undefined)continue;
             bundled[field]=path.posix.join(relative,path.relative(runtime.root,runtime[field]).split(path.sep).join('/'));

package/src/local-ai/whisper/build.mjs

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {mkdir} from 'node:fs/promises';
+import Is from 'strong-type';
+import {runProcess} from '../../process.mjs';
+
+const is = new Is(false);
+
+/** Build only the persistent first-party helper against an installed runtime. */
+export async function buildWhisperHelper({
+    runtime,
+    outputRoot,
+    cmake = 'cmake',
+    generator,
+    cmakeArgs = [],
+    env,
+    signal,
+    onEvent
+} = {}) {
+    if (!is.string(runtime?.directory) || !is.string(runtime?.sourceDirectory) || !is.string(outputRoot)) {
+        throw new TypeError('The selected Whisper runtime directory, matching sourceDirectory, and helper outputRoot are required.');
+    }
+    const root = path.resolve(outputRoot);
+    const build = path.join(root, 'build');
+    const source = fileURLToPath(new URL('./native/', import.meta.url));
+    await mkdir(root, {recursive: true});
+    const options = {env, signal, onEvent};
+    const configure = await runProcess(cmake, [
+        '-S', source,
+        '-B', build,
+        ...(generator ? ['-G', generator] : []),
+        `-DWHISPER_SOURCE_DIRECTORY=${path.resolve(runtime.sourceDirectory)}`,
+        `-DWHISPER_RUNTIME_DIRECTORY=${path.resolve(runtime.directory)}`,
+        `-DCMAKE_INSTALL_PREFIX=${root}`,
+        '-DCMAKE_BUILD_TYPE=Release',
+        ...cmakeArgs
+    ], options);
+    const compile = await runProcess(cmake, ['--build', build, '--config', 'Release'], options);
+    const install = await runProcess(cmake, ['--install', build, '--config', 'Release'], options);
+    return {
+        platform: process.platform,
+        architecture: process.arch,
+        root,
+        executable: path.join(root, 'bin', process.platform === 'win32' ? 'arcane-whisper.exe' : 'arcane-whisper'),
+        runtimeDirectory: path.resolve(runtime.directory),
+        diagnostics: {configure, compile, install}
+    };
+}

package/src/local-ai/whisper/config.mjs

@@ -0,0 +1,61 @@
+import Is from 'strong-type';
+import path from 'node:path';
+import {ArcaneError, ERROR_CODES} from '../../errors.mjs';
+
+const is = new Is(false);
+
+export const WHISPER_SMALL_MODEL = {
+    id: 'whisper-small',
+    url: 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin',
+    filename: 'ggml-small.bin'
+};
+
+/** Describe a selected native runtime and models without acquiring them. */
+export function normalizeWhisperRuntimeRequirement(record) {
+    if (record.helperRoot !== undefined && (!is.string(record.helperRoot) || !record.helperRoot)) {
+        throw new ArcaneError(ERROR_CODES.usage, 'Whisper helperRoot must name the complete selected helper directory.');
+    }
+    const helperRoot = record.helperRoot ?? (is.string(record.helperExecutable) ? path.dirname(record.helperExecutable) : undefined);
+    const backend = record.backend ?? 'auto';
+    if (!['auto', 'cuda', 'metal', 'cpu'].includes(backend)) {
+        throw new ArcaneError(ERROR_CODES.usage, `Unknown whisper.cpp backend: ${String(backend)}.`);
+    }
+    if (record.models !== undefined && !is.array(record.models)) {
+        throw new ArcaneError(ERROR_CODES.usage, 'whisper.cpp models must be an array of selected model IDs or descriptors.');
+    }
+    const models = (record.models ?? []).map(function selectedWhisperModel(value) {
+        const model = value === 'whisper-small' ? WHISPER_SMALL_MODEL : value;
+        if (!model || !is.object(model) || is.array(model) || !is.string(model.id) || !model.id) {
+            throw new ArcaneError(ERROR_CODES.usage, 'A Whisper model needs a descriptor with an id, or the built-in whisper-small model ID.');
+        }
+        if ((!is.string(model.path) || !model.path) && (!is.string(model.url) || !model.url)) {
+            throw new ArcaneError(ERROR_CODES.usage, `Whisper model ${model.id} needs its selected path or URL.`);
+        }
+        return {...model};
+    });
+    if (record.variants !== undefined && (!is.array(record.variants) || record.variants.length === 0)) {
+        throw new ArcaneError(ERROR_CODES.usage, 'whisper.cpp variants must be a nonempty array when supplied.');
+    }
+    const variants = record.variants?.map(function selectedWhisperVariant(variant) {
+        if (!variant || !is.object(variant) || is.array(variant) || !['cuda', 'metal', 'cpu'].includes(variant.backend)) {
+            throw new ArcaneError(ERROR_CODES.usage, 'Each Whisper runtime variant needs its cuda, metal, or cpu backend.');
+        }
+        if ((!is.string(variant.root) || !variant.root) && (!is.string(variant.url) || !variant.url)) {
+            throw new ArcaneError(ERROR_CODES.usage, `Whisper ${variant.backend} needs its complete runtime root or archive URL.`);
+        }
+        return {...variant};
+    });
+    if (record.modelId !== undefined && (!is.string(record.modelId) || !models.some(function matchingModel(model) {
+        return model.id === record.modelId;
+    }))) {
+        throw new ArcaneError(ERROR_CODES.usage, 'Whisper modelId must name one of the explicitly selected models.');
+    }
+    return {
+        ...record,
+        version: record.version ?? '1.9.4',
+        backend,
+        models,
+        ...(helperRoot === undefined ? {} : {helperRoot}),
+        ...(variants ? {variants} : {})
+    };
+}