arcane-os 0.92.0 → 0.94.0

package/src/core/hosts/windows/ArcaneWindowControl.cs

@@ -38,7 +38,7 @@ namespace Arcane.Core.Hosts.Windows
         {
             if (appControl == null) return;
             appControlScript = await browser.AddScriptToExecuteOnDocumentCreatedAsync(
-                "globalThis[" + AppControlDocumentKey + "] = globalThis.crypto.randomUUID();");
+                "globalThis[" + AppControlDocumentKey + "] ??= globalThis.crypto.randomUUID();");
             if (closing) return;
             browser.NavigationStarting += AppControlNavigationStarting;
             browser.NavigationCompleted += AppControlNavigationCompleted;
@@ -140,7 +140,7 @@ namespace Arcane.Core.Hosts.Windows
                 { "url", webView.Source == null ? null : webView.Source.AbsoluteUri },
                 { "documentGeneration", appControlGeneration }, { "ready", AppControlDocumentReady() },
                 { "window", AppControlWindow() },
-                { "operations", new string[] { "status", "inspect", "capture", "act", "key", "resize" } }
+                { "operations", new string[] { "status", "diagnostics", "inspect", "capture", "act", "key", "resize" } }
             };
         }
 
@@ -158,6 +158,7 @@ namespace Arcane.Core.Hosts.Windows
         {
             cancellation.ThrowIfCancellationRequested();
             if (method == "app.control.status") return AppControlStatus();
+            if (method == "app.control.diagnostics") return nativeDiagnostics.Snapshot(parameters);
             if (method != "app.control.inspect" && method != "app.control.capture" && method != "app.control.act"
                 && method != "app.control.key" && method != "app.control.resize")
                 throw new ArgumentException("Unknown app-control method: " + method);

package/src/core/services/speech.mjs

@@ -44,8 +44,8 @@ function waitForLoad(task, signal) {
 /** 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}
+        stt: {engine: stt, operation: 'transcribe', state: null, loading: null, changing: null, unsubscribe: null},
+        tts: {engine: tts, operation: 'synthesize', state: null, loading: null, changing: null, unsubscribe: null}
     };
     for (const [name, role] of Object.entries(roles)) {
         if (role.engine == null) {
@@ -124,6 +124,36 @@ export function createSpeechService({stt, tts, signal} = {}) {
         publish();
     }
 
+    function observeRoleTask(name, task, startup = false) {
+        const role = roles[name];
+        role.changing = task;
+        // Explicit load cancellation belongs to that caller's wait, not another
+        // inference request. Only the service-owned startup is a shared wait.
+        role.loading = startup ? task : null;
+        jobs.add(task);
+        function settled(error, failed) {
+            jobs.delete(task);
+            // An older startup or activation must not replace the selected state.
+            if (role.loading === task) role.loading = null;
+            if (role.changing !== task) return;
+            role.changing = null;
+            if (closed) return;
+            if (failed && startup && !closing) {
+                roleFailed(name, error);
+            } else {
+                role.state = role.engine.current();
+                publish();
+            }
+        }
+        task.then(
+            function speechRoleSettled() { settled(undefined, false); },
+            function speechRoleFailed(error) { settled(error, true); }
+        ).catch(function speechRoleObserverFailed(error) {
+            console.error('Speech role state observer failed.', error);
+        });
+        return task;
+    }
+
     function startRole(name) {
         const role = roles[name];
         if (!role.engine || closing) {
@@ -142,34 +172,60 @@ export function createSpeechService({stt, tts, signal} = {}) {
             roleFailed(name, error);
             return;
         }
+        // Replay can synchronously select an activation or close the service.
+        if (role.changing || closing || closed) return;
         const task = Promise.resolve().then(
             async function loadSpeechEngine() {
                 lifetimeSignal.throwIfAborted();
-                await role.engine.load(
+                if (role.changing !== task) return;
+                return 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);
             }
         );
+        observeRoleTask(name, task, true);
+    }
+
+    function changeRole(operation, parameters, request) {
+        if (closing || closed) {
+            throw failure('CORE_CLOSING', 'The speech service is closing.');
+        }
+        if (!parameters || !is.object(parameters) || is.array(parameters)
+            || !['stt', 'tts'].includes(parameters.role)) {
+            throw failure('SPEECH_ROLE_INVALID', 'Select the stt or tts speech role.');
+        }
+        const {role: name, ...selection} = parameters;
+        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.`);
+        }
+        if (!is.function(role.engine[operation])) {
+            throw failure('SPEECH_OPERATION_UNAVAILABLE', `The ${name} speech engine does not support ${operation}().`);
+        }
+        let acknowledgementFailed = false;
+        let acknowledgementError;
+        const task = Promise.resolve().then(async function changeSpeechRole() {
+            if (acknowledgementFailed) throw acknowledgementError;
+            operationSignal.throwIfAborted();
+            const result = await role.engine[operation]({...selection, signal: operationSignal});
+            operationSignal.throwIfAborted();
+            return result;
+        });
+        // Retain ownership before an acknowledgement observer can close or reenter.
+        observeRoleTask(name, task);
+        try {
+            request.emit?.('speech.progress', {
+                requestId: request.requestId, role: name, operation,
+                status: 'Thinking', progress: {phase: 'accepted'}
+            });
+        } catch (error) {
+            acknowledgementFailed = true;
+            acknowledgementError = error;
+        }
+        return task;
     }
 
     function invoke(name, parameters, request) {
@@ -340,6 +396,12 @@ export function createSpeechService({stt, tts, signal} = {}) {
         },
         methods: {
             'speech.status': current,
+            'speech.load': function load(parameters, request = {}) {
+                return changeRole('load', parameters, request);
+            },
+            'speech.unload': function unload(parameters, request = {}) {
+                return changeRole('unload', parameters, request);
+            },
             'speech.transcribe': function transcribe(parameters, request = {}) {
                 return invoke('stt', parameters, request);
             },

package/src/core-native-diagnostics-source.mjs

@@ -0,0 +1,13 @@
+import {readFile} from 'node:fs/promises';
+
+/** Project the one canonical diagnostic observer into a document-start script. */
+export async function createNativeDiagnosticsSource() {
+    const source = await readFile(new URL('../browser-runtime/core/native-diagnostics.mjs', import.meta.url), 'utf8');
+    return `(function installArcaneNativeDiagnostics(global){
+    'use strict';
+    if(global.top!==undefined&&global.top!==global)return;
+${source.replace(/^export (?=(?:async )?function )/gmu, '')}
+    installNativeDiagnostics(global);
+})(globalThis);
+`;
+}

package/src/import-map.mjs

@@ -44,6 +44,7 @@ const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/websocket-client','sdk/websocket-client.mjs'],
     ['arcane-os/core/client','sdk/core/client.mjs'],
     ['arcane-os/core/contracts','sdk/core/contracts.mjs'],
+    ['arcane-os/core/native-diagnostics','sdk/core/native-diagnostics.mjs'],
     ['arcane-os/document-acquisition','sdk/document-acquisition.mjs'],
     ['arcane-os/logging','sdk/logging.mjs'],
     ['arcane-os/browser-device','sdk/browser-device.mjs'],

package/src/local-ai/config.mjs

@@ -8,7 +8,17 @@ 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', 'whisper.cpp'];
+export const LOCAL_AI_RUNTIME_IDS = ['llama.cpp', 'ollama', 'onnx', 'stable-diffusion.cpp', 'whisper.cpp', 'kokoro-native'];
+
+/** Describe the selected helper without acquiring it or selecting model assets. */
+export function normalizeKokoroRuntimeRequirement(record) {
+    for (const field of ['helperRoot', 'helperExecutable', 'espeakDataDirectory', 'libraryDirectory']) {
+        if (record[field] !== undefined && (!is.string(record[field]) || record[field] === '')) {
+            throw new ArcaneError(ERROR_CODES.usage, `kokoro-native ${field} must be a nonempty path.`);
+        }
+    }
+    return {...record};
+}
 
 /** Select a llama distribution without discovering hardware or acquiring it. */
 export function normalizeLlamaRuntimeRequirement(record) {
@@ -79,6 +89,7 @@ export function normalizeLocalAIConfig(value) {
         if (record.id === 'llama.cpp') return normalizeLlamaRuntimeRequirement(record);
         if (record.id === 'stable-diffusion.cpp') return normalizeImageRuntimeRequirement(record);
         if (record.id === 'whisper.cpp') return normalizeWhisperRuntimeRequirement(record);
+        if (record.id === 'kokoro-native') return normalizeKokoroRuntimeRequirement(record);
         return {...record};
     });
     return {...value, runtimes};

package/src/local-ai/dev.mjs

@@ -9,7 +9,9 @@ import {normalizeLocalAIConfig} from './config.mjs';
 import {discoverLocalAIRuntimes} from './discover.mjs';
 import {ensureLocalAIRuntimes} from './install.mjs';
 import {createWhisperRuntime} from './whisper/index.mjs';
+import {createNativeKokoroRuntime} from './kokoro/index.mjs';
 import {createExecutionDeviceCatalog} from './execution-devices.mjs';
+import {ArcaneError, ERROR_CODES} from '../errors.mjs';
 
 /** Local engines share the ordinary app-service development transport. */
 export function createDevelopmentLocalAI({
@@ -24,7 +26,7 @@ export function createDevelopmentLocalAI({
     const localConfig = {
         ...selected,
         runtimes: selected.runtimes.filter(function selectedChatRuntime(requirement) {
-            return requirement.id !== 'stable-diffusion.cpp' && requirement.id !== 'whisper.cpp';
+            return !['stable-diffusion.cpp', 'whisper.cpp', 'kokoro-native'].includes(requirement.id);
         })
     };
     const service = createLocalAIService(
@@ -48,7 +50,7 @@ export function createDevelopmentLocalAI({
         return requirement.id === 'stable-diffusion.cpp';
     });
     if (imageSelected || selected.runtimes.some(function selectedProjectedRuntime(requirement) {
-        return ['onnx', 'llama.cpp'].includes(requirement.id);
+        return ['onnx', 'llama.cpp', 'kokoro-native'].includes(requirement.id);
     })) {
         modelAssets = createModelAssetService({appRoot});
         definitions.push(modelAssets);
@@ -71,8 +73,13 @@ export function createDevelopmentLocalAI({
     const whisperRequirement = selected.runtimes.find(function selectedWhisperRuntime(requirement) {
         return requirement.id === 'whisper.cpp';
     });
+    const kokoroRequirement = selected.runtimes.find(function selectedKokoroRuntime(requirement) {
+        return requirement.id === 'kokoro-native';
+    });
+    let stt;
+    let tts;
     if (whisperRequirement) {
-        const stt = createWhisperRuntime(
+        stt = createWhisperRuntime(
             {
                 modelId: whisperRequirement.modelId,
                 temporaryDirectory: path.join(appRoot, '.arcane', 'speech', 'whisper'),
@@ -85,7 +92,49 @@ export function createDevelopmentLocalAI({
                 }
             }
         );
-        speechService = createSpeechService({stt, signal});
+    }
+    if (kokoroRequirement) {
+        tts = createNativeKokoroRuntime({
+            modelId: kokoroRequirement.modelId,
+            model: kokoroRequirement.model,
+            revision: kokoroRequirement.revision,
+            dtype: kokoroRequirement.dtype,
+            paths: kokoroRequirement.paths,
+            assetProjectionId: kokoroRequirement.assetProjectionId,
+            resourcePaths: kokoroRequirement.resourcePaths,
+            sessionOptions: kokoroRequirement.sessionOptions,
+            executionPreference: kokoroRequirement.executionPreference,
+            executionTarget: kokoroRequirement.executionTarget,
+            modelAssets, signal, onEvent,
+            async prepare({signal: activationSignal}) {
+                if (!localConfig.runtimes.some(function selectedONNX(requirement) { return requirement.id === 'onnx'; })) {
+                    throw new ArcaneError(ERROR_CODES.targetUnavailable, 'Native Kokoro requires an explicitly selected onnx runtime.');
+                }
+                const preparation = new AbortController();
+                const preparationSignal = AbortSignal.any([activationSignal, preparation.signal]);
+                function preparationFailed(error) {
+                    preparation.abort(error);
+                    throw error;
+                }
+                // Helper acquisition and the existing ONNX owner's startup are
+                // independent. Join both before native activation can continue.
+                const outcomes = await Promise.allSettled([
+                    waitForKokoroONNX(preparationSignal).catch(preparationFailed),
+                    ensureLocalAIRuntimes({
+                        runtimes: [kokoroRequirement], directory, signal: preparationSignal, onEvent
+                    }).catch(preparationFailed)
+                ]);
+                const failures = outcomes.filter(function failed(result) { return result.status === 'rejected'; })
+                    .map(function cause(result) { return result.reason; });
+                if (failures.length === 1) throw failures[0];
+                if (failures.length) throw new AggregateError(failures, 'Native Kokoro preparation failed.');
+                preparationSignal.throwIfAborted();
+                return {onnx: outcomes[0].value, runtime: outcomes[1].value[0]};
+            }
+        });
+    }
+    if (stt || tts) {
+        speechService = createSpeechService({stt, tts, signal});
         definitions.push(speechService);
     }
     const core = createDevelopmentCore(
@@ -101,6 +150,24 @@ export function createDevelopmentLocalAI({
             }
         }
     );
+    function waitForKokoroONNX(activationSignal) {
+        activationSignal.throwIfAborted();
+        let cancel;
+        const cancelled = new Promise(function observePreparationCancellation(_resolve, reject) {
+            cancel = function stopWaitingForONNX() { reject(activationSignal.reason); };
+            activationSignal.addEventListener('abort', cancel, {once: true});
+        });
+        const ready = core.ready.then(async function existingONNXOwner(runtime) {
+            activationSignal.throwIfAborted();
+            const owner = await runtime.getService('local-ai');
+            activationSignal.throwIfAborted();
+            return owner.getONNXRuntime();
+        });
+        // Cancel this selected activation's wait without stopping the shared owner.
+        return Promise.race([ready, cancelled]).finally(function releaseONNXWait() {
+            activationSignal.removeEventListener('abort', cancel);
+        });
+    }
     function current() {
         return {
             ...core.current(),

package/src/local-ai/install.mjs

@@ -10,7 +10,7 @@ import {ArcaneError,ERROR_CODES,normalizeError,throwIfAborted} from '../errors.m
 import {createEventQueue} from '../event-queue.mjs';
 import {runProcess} from '../process.mjs';
 import {extractLocalAIArchive} from './archive.mjs';
-import {normalizeImageRuntimeRequirement,normalizeLlamaRuntimeRequirement} from './config.mjs';
+import {normalizeImageRuntimeRequirement,normalizeKokoroRuntimeRequirement,normalizeLlamaRuntimeRequirement} from './config.mjs';
 import {normalizeWhisperRuntimeRequirement} from './whisper/config.mjs';
 import {bundledWhisperRuntime, installedWhisperRuntime, installWhisperDistribution, whisperRuntimeSelection} from './whisper/install.mjs';
 
@@ -28,6 +28,21 @@ function selectedONNXNativeDistribution(runtime,platform,architecture){
         ?onnxWindowsDistribution:null;
 }
 
+function kokoroRuntimeSelection(runtime) {
+    return JSON.stringify(
+        {
+            source: runtime.helperRoot ? 'directory' : runtime.url ? 'archive' : 'sdk-release',
+            version: runtime.version ?? null,
+            url: runtime.url ?? null,
+            helperRoot: runtime.helperRoot ? path.resolve(runtime.helperRoot) : null,
+            helperExecutable: runtime.helperExecutable ?? null,
+            espeakDataDirectory: runtime.espeakDataDirectory ?? null,
+            libraryDirectory: runtime.libraryDirectory ?? null,
+            sdkVersion: !runtime.helperRoot && !runtime.url ? packageMetadata.version : null
+        }
+    );
+}
+
 function selectRuntimes(runtimes){
     if(!is.array(runtimes)){
         throw new ArcaneError(ERROR_CODES.usage,'Local AI runtimes must be an array.');
@@ -37,14 +52,23 @@ function selectRuntimes(runtimes){
         const requirement=is.string(item)?{id:item}:item;
         const runtime=requirement?.id==='stable-diffusion.cpp'?normalizeImageRuntimeRequirement(requirement)
             :requirement?.id==='whisper.cpp'?normalizeWhisperRuntimeRequirement(requirement)
+            :requirement?.id==='kokoro-native'?normalizeKokoroRuntimeRequirement(requirement)
             :requirement?.id==='llama.cpp'?normalizeLlamaRuntimeRequirement(requirement):requirement;
-        if(!runtime||!['llama.cpp','ollama','nemo-speech','onnx','stable-diffusion.cpp','whisper.cpp'].includes(runtime.id)){
+        if(!runtime||!['llama.cpp','ollama','nemo-speech','onnx','stable-diffusion.cpp','whisper.cpp','kokoro-native'].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 (runtime.id === 'kokoro-native') {
+            if (runtime.helperRoot && runtime.url) {
+                throw new ArcaneError(ERROR_CODES.usage, 'Select either a kokoro-native helperRoot or an archive URL for this operation.');
+            }
+            if (prior && kokoroRuntimeSelection(prior) !== kokoroRuntimeSelection(runtime)) {
+                throw new ArcaneError(ERROR_CODES.usage, 'Select one complete kokoro-native helper requirement for this operation.');
+            }
+        }
         if(prior&&(prior.version!==runtime.version||prior.url!==runtime.url
             ||(['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)&&prior.backend!==runtime.backend)
             ||(runtime.id==='llama.cpp'&&prior.companionUrl!==runtime.companionUrl))){
@@ -111,6 +135,20 @@ async function selectRelease(runtime,platform,architecture,signal){
     if (runtime.id === 'stable-diffusion.cpp') {
         return selectImageRelease(runtime, platform, architecture, signal);
     }
+    if (runtime.id === 'kokoro-native') {
+        if (runtime.helperRoot) return null;
+        if (!runtime.url) {
+            if (platform !== 'win32' || architecture !== 'x64') {
+                throw new ArcaneError(ERROR_CODES.targetUnavailable, `Supply a complete kokoro-native archive URL or helperRoot for ${platform}/${architecture}.`);
+            }
+            const name = 'arcane-kokoro-windows-x64.tar.gz';
+            return {
+                version: packageMetadata.version,
+                url: `https://github.com/TheWizardNexus/arcane-os-sdk/releases/download/${packageMetadata.version}/${name}`,
+                name
+            };
+        }
+    }
     const backend=runtime.id==='llama.cpp'?llamaBackendCandidate(runtime,platform,architecture):undefined;
     if(runtime.url){
         const name=path.posix.basename(new URL(runtime.url).pathname);
@@ -432,6 +470,7 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
             throw error;
         }
         if(installation.requestVersion!==(runtime.version??null)||installation.requestUrl!==(runtime.url??null))continue;
+        if (runtime.id === 'kokoro-native' && installation.requestKokoro !== kokoroRuntimeSelection(runtime)) continue;
         if (runtime.id === 'stable-diffusion.cpp' && installation.requestBackend !== runtime.backend) continue;
         if(runtime.id==='llama.cpp'&&((installation.requestBackend??'auto')!==runtime.backend
             ||(installation.requestCompanionUrl??null)!==(runtime.companionUrl??null)))continue;
@@ -445,6 +484,10 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
         if(record?.id!==runtime.id||record.platform!==platform||record.architecture!==architecture)continue;
         if(runtime.id==='llama.cpp'&&record.backend!==undefined&&record.backend!==llamaBackend)continue;
         try{
+            if (runtime.id === 'kokoro-native') {
+                if (await installedKokoroRuntime(record, signal)) return record;
+                continue;
+            }
             if(runtime.id==='whisper.cpp'){
                 if(await installedWhisperRuntime(record,signal,!reuseWhisper))return reuseWhisper?{runtime:record,requirement:whisperRequirement}:record;
                 continue;
@@ -507,6 +550,51 @@ async function installedRuntime(base,runtime,platform,architecture,signal,reuseW
     return null;
 }
 
+function kokoroRuntimeLocations(runtime, root, platform) {
+    const sourceRoot = runtime.helperRoot ? path.resolve(runtime.helperRoot) : root;
+    const defaults = {
+        helperExecutable: path.join('bin', `arcane-kokoro${platform === 'win32' ? '.exe' : ''}`),
+        espeakDataDirectory: 'share',
+        libraryDirectory: 'bin'
+    };
+    const locations = {};
+    for (const [field, fallback] of Object.entries(defaults)) {
+        const selected = path.resolve(sourceRoot, runtime[field] ?? fallback);
+        const relative = path.relative(sourceRoot, selected);
+        if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new ArcaneError(ERROR_CODES.usage, `kokoro-native ${field} must belong to the selected complete helper tree so it can be relocated.`);
+        }
+        locations[field] = path.join(root, relative);
+    }
+    return locations;
+}
+
+async function installedKokoroRuntime(record, signal) {
+    throwIfAborted(signal);
+    const locations = [record.helperExecutable, record.espeakDataDirectory, record.libraryDirectory];
+    const missingLocation = locations.some(
+        function missingKokoroLocation(location) {
+            return !is.string(location);
+        }
+    );
+    if (missingLocation) return false;
+    // eSpeak's data argument is the parent of its espeak-ng-data directory.
+    locations.push(path.join(record.espeakDataDirectory, 'espeak-ng-data'));
+    const entries = await Promise.all(
+        locations.map(
+            function inspectKokoroLocation(location) {
+                return stat(location);
+            }
+        )
+    );
+    throwIfAborted(signal);
+    return entries.every(
+        function kokoroLocationPresent(info, index) {
+            return index === 0 ? info.isFile() : info.isDirectory();
+        }
+    );
+}
+
 async function runtimeExecutable(root,id,platform,signal){
     const filename=`${id==='llama.cpp'?'llama-server':'ollama'}${platform==='win32'?'.exe':''}`;
     const directories=[root];
@@ -645,6 +733,22 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
                 release,
                 {root, directory, platform, architecture, signal, onEvent}
             );
+        } else if (runtime.id === 'kokoro-native' && runtime.helperRoot) {
+            const sourceRoot = path.resolve(runtime.helperRoot);
+            const destination = path.relative(sourceRoot, root);
+            if (destination !== '..' && !destination.startsWith(`..${path.sep}`) && !path.isAbsolute(destination)) {
+                throw new ArcaneError(ERROR_CODES.usage, 'The kokoro-native installation directory must be outside helperRoot so copying does not include its own output.');
+            }
+            locations = {version: runtime.version ?? 'custom', ...kokoroRuntimeLocations(runtime, root, platform)};
+            await onEvent(
+                {
+                    type: 'local-ai.install.copying',
+                    message: 'Copying the selected complete Kokoro helper tree.',
+                    data: {id: runtime.id, platform, architecture}
+                }
+            );
+            const files = [];
+            await copyRuntimeTree(sourceRoot, root, root, files, signal);
         }else{
             const assets=[{url:release.url,name:release.name,archive}];
             if(companionArchive){
@@ -679,13 +783,17 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
                 ...(runtime.id==='llama.cpp'?{backend:release.backend,requestedBackend:release.requestedBackend}:{}),
                 ...(runtime.id==='nemo-speech'
                 ?await nemoRuntimeDirectories(root,signal)
+                :runtime.id==='kokoro-native'?kokoroRuntimeLocations(runtime,root,platform)
                 :{executable:await runtimeExecutable(root,runtime.id,platform,signal)})};
         }
         const record={id:runtime.id,platform,architecture,root,...locations,...(runtime.version?{requestedVersion:runtime.version}:{})};
+        if (runtime.id === 'kokoro-native' && !await installedKokoroRuntime(record, signal)) {
+            throw new ArcaneError(ERROR_CODES.operationFailed, 'Kokoro preparation did not produce the selected helper executable, eSpeak data, and library directory.');
+        }
         throwIfAborted(signal);
         if(archive)await unlink(archive);
         if(companionArchive)await unlink(companionArchive);
-        await writeFile(path.join(attempt,'installation.json'),`${JSON.stringify({requestVersion:runtime.version??null,requestUrl:runtime.url??null,...(['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?{requestBackend:runtime.backend}:{}),...(runtime.id==='llama.cpp'?{requestCompanionUrl:runtime.companionUrl??null}:{}),...(runtime.id==='whisper.cpp'?{requestWhisper:whisperRuntimeSelection(runtime)}:{}),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,...(['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?{requestBackend:runtime.backend}:{}),...(runtime.id==='llama.cpp'?{requestCompanionUrl:runtime.companionUrl??null}:{}),...(runtime.id==='whisper.cpp'?{requestWhisper:whisperRuntimeSelection(runtime)}:{}),...(runtime.id==='kokoro-native'?{requestKokoro:kokoroRuntimeSelection(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;
@@ -705,7 +813,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,['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?runtime.backend:null,runtime.id==='whisper.cpp'?whisperRuntimeSelection(runtime):null,runtime.id==='llama.cpp'?runtime.companionUrl??null:null]);
+    const key=JSON.stringify([options.directory,options.platform,options.architecture,runtime.id,runtime.version??null,runtime.url??null,['stable-diffusion.cpp','llama.cpp'].includes(runtime.id)?runtime.backend:null,runtime.id==='whisper.cpp'?whisperRuntimeSelection(runtime):null,runtime.id==='llama.cpp'?runtime.companionUrl??null:null,runtime.id==='kokoro-native'?kokoroRuntimeSelection(runtime):null]);
     let entry=installations.get(key);
     if(entry?.controller.signal.aborted){
         // The prior cancelled attempt owns its cleanup. A later request waits
@@ -855,7 +963,7 @@ export async function bundleLocalAIRuntimes({runtimes=[],directory,outputRoot,pl
         const relative=`runtime/local-ai/${runtime.id}`;
         const destination=path.join(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']){
+        for(const field of ['executable','modulePath','includeDirectory','libraryDirectory','binaryDirectory','cmakeDirectory','libraryPath','bindingModulePath','helperExecutable','espeakDataDirectory']){
             if(runtime[field]===undefined)continue;
             bundled[field]=path.posix.join(relative,path.relative(runtime.root,runtime[field]).split(path.sep).join('/'));
         }