arcane-os 0.62.0 → 0.64.0

package/src/core/repositories.mjs

@@ -0,0 +1,210 @@
+import {mkdir, readdir} from 'node:fs/promises';
+import {homedir} from 'node:os';
+import path from 'node:path';
+import Is from 'strong-type';
+import {ArcaneError, throwIfAborted} from '../errors.mjs';
+import {runProcess} from '../process.mjs';
+import {repositoryPull, repositoryPush, repositoryStatus} from '../repository.mjs';
+
+const is = new Is(false);
+const directoryOperations = new Map();
+
+/** Resolve persistent native data without creating or migrating anything. */
+export function resolveArcaneDataPaths({dataRoot} = {}) {
+    let root = dataRoot;
+    if (root === undefined) {
+        const home = homedir();
+        switch (process.platform) {
+            case 'win32':
+                root = path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'ArcaneData');
+                break;
+            case 'darwin':
+                root = path.join(home, 'Library', 'Application Support', 'ArcaneData');
+                break;
+            case 'linux': {
+                const xdg = process.env.XDG_DATA_HOME;
+                const base = xdg && path.isAbsolute(xdg) ? xdg : path.join(home, '.local', 'share');
+                root = path.join(base, 'ArcaneData');
+                break;
+            }
+            default:
+                throw new ArcaneError(
+                    'ARCANE_DATA_ROOT_REQUIRED',
+                    'This native host must supply its persistent ArcaneData directory through dataRoot.'
+                );
+        }
+    }
+    requireString(root, 'dataRoot');
+    const resolved = path.resolve(root);
+    return {dataRoot: resolved, repositoriesRoot: path.join(resolved, 'Repos')};
+}
+
+/** One connected checkout, composed into an application's own Core service. */
+export function createRepositoryWorkspace(
+    {name, directory, dataRoot, remote, branch, onEvent, run = runProcess} = {}
+) {
+    let selected = directory;
+    if (selected === undefined) {
+        requireString(name, 'name');
+        if (name === '.' || name === '..' || /[/\\]/u.test(name)) {
+            throw new TypeError('name must be one directory name; use directory for an explicit repository path.');
+        }
+        selected = path.join(resolveArcaneDataPaths({dataRoot}).repositoriesRoot, name);
+    }
+    requireString(selected, 'directory');
+    if (remote !== undefined) requireString(remote, 'remote');
+    if (branch !== undefined) requireString(branch, 'branch');
+    if (!is.function(run)) throw new TypeError('run must implement the SDK process adapter.');
+    const repositoryDirectory = path.resolve(selected);
+    const pending = new Set();
+    let opened = false;
+    let closing = null;
+
+    async function prepare(signal) {
+        throwIfAborted(signal);
+        if (opened) return {directory: repositoryDirectory, cloned: false};
+        let entries;
+        try {
+            entries = await readdir(repositoryDirectory);
+        } catch (error) {
+            if (error.code !== 'ENOENT') throw error;
+            entries = [];
+        }
+        throwIfAborted(signal);
+        if (entries.length) {
+            // A parent checkout or a bare object cache is not this connection's
+            // working root. Inspection never changes an existing destination.
+            const result = await run(
+                'git',
+                ['rev-parse', '--is-inside-work-tree', '--show-prefix'],
+                {cwd: repositoryDirectory, signal, onEvent}
+            );
+            throwIfAborted(signal);
+            const [inside, prefix] = result.stdout.split(/\r?\n/u);
+            if (inside !== 'true' || prefix !== '') {
+                throw new ArcaneError(
+                    'ARCANE_REPOSITORY_DIRECTORY_INVALID',
+                    'The selected nonempty directory is not a Git working repository root.',
+                    {details: result}
+                );
+            }
+            opened = true;
+            return {directory: repositoryDirectory, cloned: false};
+        }
+        requireString(remote, 'remote');
+        await mkdir(path.dirname(repositoryDirectory), {recursive: true});
+        throwIfAborted(signal);
+        const arguments_ = ['clone', '--progress'];
+        if (branch !== undefined) arguments_.push('--branch', branch);
+        arguments_.push('--', remote, repositoryDirectory);
+        const result = await run(
+            'git',
+            arguments_,
+            {cwd: path.dirname(repositoryDirectory), signal, onEvent}
+        );
+        throwIfAborted(signal);
+        opened = true;
+        return {directory: repositoryDirectory, cloned: true, stdout: result.stdout, stderr: result.stderr};
+    }
+
+    function accept(operation, signal) {
+        try {
+            throwIfAborted(signal);
+            if (closing) throw new ArcaneError('CORE_CLOSING', 'The repository workspace is closing.');
+        } catch (error) {
+            return Promise.reject(error);
+        }
+        const result = orderDirectoryOperation(
+            repositoryDirectory,
+            async function runRepositoryOperation() {
+                throwIfAborted(signal);
+                return operation();
+            }
+        );
+        pending.add(result);
+        function settled() {
+            pending.delete(result);
+        }
+        result.then(settled, settled);
+        return result;
+    }
+
+    function open({signal} = {}) {
+        return accept(
+            function openRepository() {
+                return prepare(signal);
+            },
+            signal
+        );
+    }
+
+    function status({signal} = {}) {
+        return accept(
+            async function readRepositoryStatus() {
+                await prepare(signal);
+                return repositoryStatus({workspaceRoot: repositoryDirectory, signal, onEvent, run});
+            },
+            signal
+        );
+    }
+
+    function pull({signal} = {}) {
+        return accept(
+            async function pullRepository() {
+                await prepare(signal);
+                return repositoryPull({workspaceRoot: repositoryDirectory, signal, onEvent, run});
+            },
+            signal
+        );
+    }
+
+    function push({signal} = {}) {
+        return accept(
+            async function pushRepository() {
+                await prepare(signal);
+                return repositoryPush({workspaceRoot: repositoryDirectory, signal, onEvent, run});
+            },
+            signal
+        );
+    }
+
+    function close() {
+        if (!closing) {
+            closing = Promise.allSettled([...pending]).then(
+                function operationsDrained(results) {
+                    const failures = results.filter(
+                        function failed(result) {
+                            return result.status === 'rejected';
+                        }
+                    ).map(
+                        function reason(result) {
+                            return result.reason;
+                        }
+                    );
+                    if (failures.length) throw new AggregateError(failures, 'Repository operations failed while draining.');
+                }
+            );
+        }
+        return closing;
+    }
+
+    return {directory: repositoryDirectory, open, status, pull, push, close, drain: close, dispose: close};
+}
+
+function requireString(value, name) {
+    if (!is.string(value) || value === '') throw new TypeError(`${name} must be a nonempty string.`);
+}
+
+function orderDirectoryOperation(directory, operation) {
+    const key = process.platform === 'win32' ? directory.toLowerCase() : directory;
+    const previous = directoryOperations.get(key) ?? Promise.resolve();
+    const result = previous.then(operation, operation);
+    function releaseQueue() {
+        if (directoryOperations.get(key) === tail) directoryOperations.delete(key);
+    }
+    // Only the scheduling tail settles successfully after an error. Each caller
+    // retains its complete failure; a later operation can retry the same path.
+    const tail = result.then(releaseQueue, releaseQueue);
+    directoryOperations.set(key, tail);
+    return result;
+}

package/src/core/services/speech.mjs

@@ -0,0 +1,361 @@
+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,
+                    requestId: request.requestId,
+                    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,9 +3,12 @@ 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';
+import {SDXL_BASE_1_0_MODEL} from './image-models/sdxl.mjs';
+import {normalizeWhisperRuntimeRequirement} from './whisper/config.mjs';
 
 const is = new Is(false);
-export const LOCAL_AI_RUNTIME_IDS = ['llama.cpp', 'ollama', 'onnx', 'stable-diffusion.cpp'];
+export const LOCAL_AI_RUNTIME_IDS = ['llama.cpp', 'ollama', 'onnx', 'stable-diffusion.cpp', 'whisper.cpp'];
 
 /** Image requirements describe assets without acquiring or loading a model. */
 export function normalizeImageRuntimeRequirement(record) {
@@ -18,9 +21,11 @@ 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 === 'sdxl-base-1.0' ? SDXL_BASE_1_0_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, flux2-klein-4b, or sdxl-base-1.0).');
             }
             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.`);
@@ -57,6 +62,7 @@ export function normalizeLocalAIConfig(value) {
             throw new ArcaneError(ERROR_CODES.usage, `Unknown local AI runtime: ${String(record?.id ?? item)}.`);
         }
         if (record.id === 'stable-diffusion.cpp') return normalizeImageRuntimeRequirement(record);
+        if (record.id === 'whisper.cpp') return normalizeWhisperRuntimeRequirement(record);
         return {...record};
     });
     return {...value, runtimes};

package/src/local-ai/dev.mjs

@@ -1,12 +1,15 @@
+import path from 'node:path';
 import Is from 'strong-type';
 import {createCoreRuntime} from '../core/runtime.mjs';
 import {createLocalAIService} from '../core/services/local-ai.mjs';
 import {createLocalImageService} from '../core/services/image.mjs';
 import {createModelAssetService} from '../core/services/model-assets.mjs';
+import {createSpeechService} from '../core/services/speech.mjs';
 import {CORE_PROTOCOL, CoreError, serializeCoreError} from '../../browser-runtime/core/contracts.mjs';
 import {normalizeLocalAIConfig} from './config.mjs';
 import {discoverLocalAIRuntimes} from './discover.mjs';
 import {ensureLocalAIRuntimes} from './install.mjs';
+import {createWhisperRuntime} from './whisper/index.mjs';
 
 const is = new Is(false);
 
@@ -84,6 +87,7 @@ export function createDevelopmentLocalAI({config, appRoot, directory, applicatio
     let runtime;
     let service;
     let imageService;
+    let speechService;
     let modelAssets;
     let stopFrames;
     let preparationError = null;
@@ -162,6 +166,7 @@ export function createDevelopmentLocalAI({config, appRoot, directory, applicatio
         for (const record of current.services) writeFrame(connection, event('core.service.state', record));
         writeFrame(connection, event('localai.state', service.current()));
         if (imageService) writeFrame(connection, event('image.state', imageService.current()));
+        if (speechService) writeFrame(connection, event('speech.state', speechService.current()));
         if (modelAssets) writeFrame(connection, event('modelAssets.state', modelAssets.current()));
     }
 
@@ -170,7 +175,7 @@ export function createDevelopmentLocalAI({config, appRoot, directory, applicatio
         const localConfig = {
             ...selected,
             runtimes: selected.runtimes.filter(function selectedChatRuntime(requirement) {
-                return requirement.id !== 'stable-diffusion.cpp';
+                return requirement.id !== 'stable-diffusion.cpp' && requirement.id !== 'whisper.cpp';
             })
         };
         service = createLocalAIService(
@@ -203,6 +208,30 @@ export function createDevelopmentLocalAI({config, appRoot, directory, applicatio
             );
             services.push(modelAssets, imageService);
         }
+        const whisperRequirement = selected.runtimes.find(
+            function selectedWhisperRuntime(requirement) {
+                return requirement.id === 'whisper.cpp';
+            }
+        );
+        if (whisperRequirement) {
+            const stt = createWhisperRuntime(
+                {
+                    modelId: whisperRequirement.modelId,
+                    temporaryDirectory: path.join(appRoot, '.arcane', 'speech', 'whisper'),
+                    onEvent,
+                    async prepare({signal, onEvent: report}) {
+                        const installed = await ensureLocalAIRuntimes(
+                            {runtimes: [whisperRequirement], directory, signal, onEvent: report}
+                        );
+                        return installed[0];
+                    }
+                }
+            );
+            speechService = createSpeechService(
+                {stt, signal: operationSignal}
+            );
+            services.push(speechService);
+        }
         runtime = createCoreRuntime({application, version, services});
         stopFrames = runtime.onFrame(routeFrame);
         runtime.start();
@@ -387,7 +416,8 @@ export function createDevelopmentLocalAI({config, appRoot, directory, applicatio
         return {state: closed ? 'closed' : preparationError ? 'error' : runtime ? 'ready' : 'preparing',
             error: preparationError ? serializeCoreError(preparationError) : null,
             core: runtime?.current() ?? null, localAI: service?.current() ?? null,
-            image: imageService?.current() ?? null};
+            image: imageService?.current() ?? null,
+            speech: speechService?.current() ?? null};
     }
 
     function close() {