arcane-os 0.62.0 → 0.63.0

package/src/core/services/speech.mjs

@@ -0,0 +1,360 @@
+import Is from 'strong-type';
+import {createArcaneEventSource} from '../../event-manager.mjs';
+import {CoreError, serializeCoreError} from '../../../browser-runtime/core/contracts.mjs';
+
+const is = new Is(false);
+
+function failure(code, message) {
+    return new CoreError(
+        {code, message}
+    );
+}
+
+function waitForLoad(task, signal) {
+    signal.throwIfAborted();
+    return new Promise(
+        function awaitSpeechLoad(resolve, reject) {
+            function cancelled() {
+                signal.removeEventListener('abort', cancelled);
+                reject(signal.reason);
+            }
+            signal.addEventListener(
+                'abort',
+                cancelled,
+                {once: true}
+            );
+            task.then(
+                function loaded(value) {
+                    signal.removeEventListener('abort', cancelled);
+                    if (signal.aborted) {
+                        reject(signal.reason);
+                    } else {
+                        resolve(value);
+                    }
+                },
+                function loadFailed(error) {
+                    signal.removeEventListener('abort', cancelled);
+                    reject(error);
+                }
+            );
+        }
+    );
+}
+
+/** Hosts supply selected engines; this service owns their independent lifetimes. */
+export function createSpeechService({stt, tts, signal} = {}) {
+    const roles = {
+        stt: {engine: stt, operation: 'transcribe', state: null, loading: null, unsubscribe: null},
+        tts: {engine: tts, operation: 'synthesize', state: null, loading: null, unsubscribe: null}
+    };
+    for (const [name, role] of Object.entries(roles)) {
+        if (role.engine == null) {
+            role.state = {providerId: '', modelId: null, state: 'unavailable', loaded: false, busy: false};
+            continue;
+        }
+        for (const method of ['current', 'subscribe', 'load', 'close', role.operation]) {
+            if (!is.function(role.engine[method])) {
+                throw new TypeError(`The ${name} speech engine requires ${method}().`);
+            }
+        }
+        role.state = role.engine.current();
+    }
+
+    const lifetime = new AbortController();
+    const lifetimeSignal = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
+    const owner = {};
+    const events = createArcaneEventSource(
+        owner,
+        {source: 'core-speech', eventTypes: ['speech.state']}
+    );
+    const jobs = new Set();
+    const publications = [];
+    let context;
+    let started = false;
+    let publishing = false;
+    let closing = null;
+    let closed = false;
+
+    function available(role) {
+        return started && !closing && !closed && role.state.loaded === true
+            && (role.state.state === 'ready' || role.state.state === 'running');
+    }
+
+    function current() {
+        const transcriptionAvailable = available(roles.stt);
+        const synthesisAvailable = available(roles.tts);
+        return {
+            ready: transcriptionAvailable && synthesisAvailable,
+            synthesisAvailable,
+            transcriptionAvailable,
+            status: closed ? 'closed' : closing ? 'closing' : started ? 'ok' : 'created',
+            ttsEngine: roles.tts.state.providerId ?? '',
+            sttEngine: roles.stt.state.providerId ?? '',
+            roles: {
+                stt: {...roles.stt.state, available: transcriptionAvailable},
+                tts: {...roles.tts.state, available: synthesisAvailable}
+            },
+            closed
+        };
+    }
+
+    function publish() {
+        publications.push(current());
+        if (publishing) {
+            return;
+        }
+        publishing = true;
+        try {
+            // A listener may close the service. Finish this snapshot before
+            // publishing the lifecycle change that listener caused.
+            while (publications.length) {
+                const snapshot = publications.shift();
+                events.dispatch('speech.state', snapshot);
+                context?.emit('speech.state', snapshot);
+            }
+        } finally {
+            publishing = false;
+        }
+    }
+
+    function roleFailed(name, error) {
+        const role = roles[name];
+        role.state = {...role.state, state: 'error', error: serializeCoreError(error)};
+        console.error(`The ${name} speech engine failed.`, error);
+        publish();
+    }
+
+    function startRole(name) {
+        const role = roles[name];
+        if (!role.engine || closing) {
+            return;
+        }
+        try {
+            role.unsubscribe = role.engine.subscribe(
+                function speechEngineChanged(state) {
+                    if (!closed) {
+                        role.state = state;
+                        publish();
+                    }
+                }
+            );
+        } catch (error) {
+            roleFailed(name, error);
+            return;
+        }
+        const task = Promise.resolve().then(
+            async function loadSpeechEngine() {
+                lifetimeSignal.throwIfAborted();
+                await role.engine.load(
+                    {signal: lifetimeSignal}
+                );
+                if (!closed) {
+                    role.state = role.engine.current();
+                    publish();
+                }
+            }
+        );
+        role.loading = task;
+        task.then(
+            function speechEngineLoaded() {
+                role.loading = null;
+            },
+            function speechEngineLoadFailed(error) {
+                role.loading = null;
+                if (!closing) {
+                    roleFailed(name, error);
+                }
+            }
+        ).catch(
+            function speechLoadObserverFailed(error) {
+                console.error('Speech load state observer failed.', error);
+            }
+        );
+    }
+
+    function invoke(name, parameters, request) {
+        if (closing || closed) {
+            throw failure('CORE_CLOSING', 'The speech service is closing.');
+        }
+        const role = roles[name];
+        const operationSignal = request.signal
+            ? AbortSignal.any([lifetimeSignal, request.signal]) : lifetimeSignal;
+        operationSignal.throwIfAborted();
+        if (!role.engine) {
+            throw failure('SPEECH_ENGINE_UNAVAILABLE', `No ${name} speech engine is configured.`);
+        }
+        request.emit?.(
+            'speech.progress',
+            {requestId: request.requestId, role: name, status: 'Thinking', progress: {phase: 'accepted'}}
+        );
+        const task = (async function invokeSpeechEngine() {
+            if (role.loading) {
+                await waitForLoad(role.loading, operationSignal);
+            }
+            operationSignal.throwIfAborted();
+            const result = await role.engine[role.operation](
+                parameters,
+                {
+                    signal: operationSignal,
+                    onProgress(progress) {
+                        if (!operationSignal.aborted) {
+                            request.emit?.(
+                                'speech.progress',
+                                {requestId: request.requestId, role: name, status: 'Thinking', progress}
+                            );
+                        }
+                    }
+                }
+            );
+            operationSignal.throwIfAborted();
+            return result;
+        })();
+        jobs.add(task);
+        function speechRequestSettled() {
+            jobs.delete(task);
+        }
+        task.then(speechRequestSettled, speechRequestSettled);
+        return task;
+    }
+
+    function notifyListener(listener, state) {
+        const result = listener(state);
+        if (result && is.function(result.then)) {
+            Promise.resolve(result).catch(
+                function speechListenerFailed(error) {
+                    console.error('Speech state listener failed.', error);
+                }
+            );
+        }
+    }
+
+    function subscribe(listener, {replay = true, signal: subscriptionSignal} = {}) {
+        if (!is.function(listener)) {
+            throw new TypeError('A speech state listener must be a function.');
+        }
+        if (closed) {
+            if (replay && !subscriptionSignal?.aborted) {
+                notifyListener(listener, current());
+            }
+            return function closedSubscription() {};
+        }
+        const unsubscribe = events.on(
+            'speech.state',
+            function speechStateChanged(event) {
+                notifyListener(listener, event.detail);
+            },
+            {signal: subscriptionSignal}
+        );
+        try {
+            if (replay && !subscriptionSignal?.aborted) {
+                notifyListener(listener, current());
+            }
+        } catch (error) {
+            unsubscribe();
+            throw error;
+        }
+        return unsubscribe;
+    }
+
+    function close() {
+        if (closing) {
+            return closing;
+        }
+        closing = Promise.resolve().then(
+            async function closeSpeechService() {
+                const shutdowns = Object.entries(roles).map(
+                    async function closeSpeechEngine([name, role]) {
+                        if (!role.engine) {
+                            return;
+                        }
+                        try {
+                            await role.engine.close();
+                            role.state = role.engine.current();
+                        } catch (error) {
+                            roleFailed(name, error);
+                            throw error;
+                        } finally {
+                            role.unsubscribe?.();
+                        }
+                    }
+                );
+                const loading = Object.values(roles).map(
+                    function speechLoadTask(role) {
+                        return role.loading;
+                    }
+                ).filter(Boolean);
+                const results = await Promise.allSettled([...shutdowns, ...loading, ...jobs]);
+                lifetimeSignal.removeEventListener('abort', abortService);
+                closed = true;
+                publish();
+                const failures = [];
+                for (let index = 0; index < shutdowns.length; index += 1) {
+                    if (results[index].status === 'rejected') {
+                        failures.push(results[index].reason);
+                    }
+                }
+                if (failures.length) {
+                    throw new AggregateError(failures, 'Speech service shutdown failed.');
+                }
+                return current();
+            }
+        );
+        lifetime.abort();
+        publish();
+        return closing;
+    }
+
+    function abortService() {
+        close().catch(
+            function speechShutdownFailed(error) {
+                console.error('Speech service shutdown failed.', error);
+            }
+        );
+    }
+
+    lifetimeSignal.addEventListener(
+        'abort',
+        abortService,
+        {once: true}
+    );
+
+    return {
+        name: 'speech',
+        current,
+        subscribe,
+        close,
+        start(currentContext) {
+            if (started || closing) {
+                return;
+            }
+            context = currentContext;
+            if (lifetimeSignal.aborted) {
+                abortService();
+                return;
+            }
+            started = true;
+            startRole('stt');
+            startRole('tts');
+            publish();
+        },
+        methods: {
+            'speech.status': current,
+            'speech.transcribe': function transcribe(parameters, request = {}) {
+                return invoke('stt', parameters, request);
+            },
+            'speech.synthesize': function synthesize(parameters, request = {}) {
+                return invoke('tts', parameters, request);
+            }
+        },
+        drain: close,
+        async dispose() {
+            try {
+                await close();
+            } finally {
+                events.dispose();
+            }
+        }
+    };
+}
+
+export default createSpeechService;

package/src/local-ai/config.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import Is from 'strong-type';
 import {ArcaneError, ERROR_CODES, throwIfAborted} from '../errors.mjs';
 import {SD14_MODEL} from './image-models/sd14.mjs';
+import {FLUX2_KLEIN_4B_MODEL} from './image-models/flux.mjs';
 
 const is = new Is(false);
 export const LOCAL_AI_RUNTIME_IDS = ['llama.cpp', 'ollama', 'onnx', 'stable-diffusion.cpp'];
@@ -18,9 +19,10 @@ export function normalizeImageRuntimeRequirement(record) {
     }
     const models = (record.models ?? []).map(
         function selectedImageModel(value) {
-            const model = value === 'sd14' ? SD14_MODEL : value;
+            const model = value === 'sd14' ? SD14_MODEL
+                : value === 'flux2-klein-4b' ? FLUX2_KLEIN_4B_MODEL : value;
             if (!model || !is.object(model) || is.array(model) || !is.string(model.id) || !model.id) {
-                throw new ArcaneError(ERROR_CODES.usage, 'An image model needs a descriptor with an id, or the built-in sd14 ID.');
+                throw new ArcaneError(ERROR_CODES.usage, 'An image model needs a descriptor with an id, or a built-in model ID (sd14 or flux2-klein-4b).');
             }
             if (!model.resources || !is.object(model.resources) || is.array(model.resources)) {
                 throw new ArcaneError(ERROR_CODES.usage, `Image model ${model.id} needs resources keyed by model role.`);

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/native/windows-provider.mjs

@@ -41,13 +41,30 @@ function portableRequest(target) {
     return {...target, target: 'portable', format: 'portable'};
 }
 
+function applicationExecutable(application) {
+    const name = is.string(application.displayName) && application.displayName
+        ? application.displayName : application.id;
+    // Derive a Windows filename without changing the application's name.
+    // These substitutions belong only to Windows' reserved filename syntax.
+    const filename = `${name}.exe`.replace(/[<>:"/\\|?*\u0000-\u001f]/gu, '_');
+    return /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/iu.test(filename)
+        ? `_${filename}` : filename;
+}
+
+function hostAssetPath(relative, executable) {
+    if (relative === 'Arcane.exe') return executable;
+    if (relative === 'Arcane.exe.config') return `${executable}.config`;
+    return relative;
+}
+
 async function emit(onEvent, event) {
     if (is.function(onEvent)) await onEvent(event);
 }
 
-async function hostFilesMissing(directory) {
+async function hostFilesMissing(directory, executable = 'Arcane.exe') {
     const missing = [];
-    for (const relative of HOST_FILES) {
+    for (const source of HOST_FILES) {
+        const relative = hostAssetPath(source, executable);
         try {
             if (!(await stat(path.join(directory, relative))).isFile()) missing.push(relative);
         } catch (error) {
@@ -58,9 +75,9 @@ async function hostFilesMissing(directory) {
     return missing;
 }
 
-async function requireHostDirectory(directory) {
+async function requireHostDirectory(directory, executable = 'Arcane.exe') {
     const resolved = await realpath(directory);
-    const missing = await hostFilesMissing(resolved);
+    const missing = await hostFilesMissing(resolved, executable);
     if (missing.length) {
         throw new ArcaneError(ERROR_CODES.prerequisiteMissing, 'The selected Windows host assets are incomplete.', {
             details: {hostDirectory: resolved, missing}
@@ -126,7 +143,7 @@ function contains(root, candidate) {
     return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
 }
 
-async function copyHostAssets(source, root, files, signal, relative = '', ancestors = new Set()) {
+async function copyHostAssets(source, root, files, signal, executable, relative = '', ancestors = new Set()) {
     throwIfAborted(signal);
     const canonical = await realpath(source);
     const output = await realpath(root);
@@ -139,11 +156,12 @@ async function copyHostAssets(source, root, files, signal, relative = '', ancest
     for (const entry of await readdir(source, {withFileTypes: true})) {
         throwIfAborted(signal);
         const selected = path.join(source, entry.name);
-        const destination = relative ? `${relative}/${entry.name}` : entry.name;
+        const sourceRelative = relative ? `${relative}/${entry.name}` : entry.name;
+        const destination = hostAssetPath(sourceRelative, executable);
         const information = await stat(selected);
         if (information.isDirectory()) {
             await mkdir(path.join(root, destination), {recursive: true});
-            await copyHostAssets(selected, root, files, signal, destination, parents);
+            await copyHostAssets(selected, root, files, signal, executable, sourceRelative, parents);
         } else if (information.isFile()) {
             await writeOutput(root, destination, await readFile(selected, {signal}), files, signal);
         } else {
@@ -152,7 +170,7 @@ async function copyHostAssets(source, root, files, signal, relative = '', ancest
     }
 }
 
-async function applyApplicationIcon(request, root, files) {
+async function applyApplicationIcon(request, root, files, executableName) {
     const {appDescriptor, release, signal, onEvent} = request;
     const icon = appDescriptor.native?.icon;
     if (!icon) return {};
@@ -168,7 +186,7 @@ async function applyApplicationIcon(request, root, files) {
         {signal}
     );
     throwIfAborted(signal);
-    const executable = path.join(root, 'Arcane.exe');
+    const executable = path.join(root, executableName);
     let branded;
     try {
         const launcher = await readFile(
@@ -268,14 +286,15 @@ export function createWindowsNativeProvider({services, hostDirectory} = {}) {
             try {
                 const host = selectedHost ?? await releasedHostDirectory(path.resolve(request.outputRoot), artifact.manifest.sdk.version, {signal, onEvent});
                 const files = [...artifact.manifest.files];
-                await copyHostAssets(host, root, files, signal);
-                const branding = await applyApplicationIcon(request, root, files);
+                const executable = applicationExecutable(request.appDescriptor);
+                await copyHostAssets(host, root, files, signal, executable);
+                const branding = await applyApplicationIcon(request, root, files, executable);
                 const manifest = {
                     ...artifact.manifest,
                     kind: 'arcane-windows-native',
                     target,
                     host: {
-                        executable: 'Arcane.exe',
+                        executable,
                         platform: 'windows', architecture: 'x64', runtime: 'webview2',
                         coreExecutable: 'runtime/ArcaneCore.exe',
                         coreLoader: 'runtime/arcane-core-loader.cjs',
@@ -296,7 +315,7 @@ export function createWindowsNativeProvider({services, hostDirectory} = {}) {
             throwIfAborted(signal);
             const target = windowsTarget(targetRequest);
             const result = await portable.verify({artifact, targetRequest: portableRequest(target), signal});
-            await requireHostDirectory(result.outputRoot);
+            await requireHostDirectory(result.outputRoot, result.manifest.host.executable);
             const verified = {...result, target: 'windows-x64', executable: true};
             await emit(onEvent, {type: 'native.verified', target: 'windows-x64', outputRoot: result.outputRoot});
             throwIfAborted(signal);
@@ -308,8 +327,13 @@ export function createWindowsNativeProvider({services, hostDirectory} = {}) {
             if (process.platform !== 'win32' || process.arch !== 'x64') {
                 throw new ArcaneError(ERROR_CODES.nativeRunUnsupported, 'Running this Windows x64 artifact requires a Windows x64 host.');
             }
-            const root = await requireHostDirectory(artifact?.target?.rootDir);
-            return runProcess(path.join(root, 'Arcane.exe'), ['--close-on-stdin-eof'], {
+            const directory = artifact?.target?.rootDir;
+            const manifest = JSON.parse(
+                await readFile(path.join(directory, MANIFEST), 'utf8')
+            );
+            const executable = manifest.host.executable;
+            const root = await requireHostDirectory(directory, executable);
+            return runProcess(path.join(root, executable), ['--close-on-stdin-eof'], {
                 cwd: root, signal, onEvent, cancellationMode: 'close-input'
             });
         }