arcane-os 0.56.0 → 0.57.0

package/src/local-ai/install.mjs

@@ -0,0 +1,344 @@
+import Is from 'strong-type';
+import {createWriteStream} from 'node:fs';
+import {chmod,copyFile,lstat,mkdir,mkdtemp,readFile,readdir,readlink,rm,stat,symlink,unlink,writeFile} from 'node:fs/promises';
+import path from 'node:path';
+import {Readable} from 'node:stream';
+import {pipeline} from 'node:stream/promises';
+import {ArcaneError,ERROR_CODES,normalizeError,throwIfAborted} from '../errors.mjs';
+import {createEventQueue} from '../event-queue.mjs';
+import {extractLocalAIArchive} from './archive.mjs';
+
+const is=new Is(false);
+const installations=new Map();
+
+function selectRuntimes(runtimes){
+    if(!is.array(runtimes)){
+        throw new ArcaneError(ERROR_CODES.usage,'Local AI runtimes must be an array.');
+    }
+    const selected=new Map();
+    for(const runtime of runtimes){
+        if(!runtime||!['llama.cpp','ollama'].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&&(prior.version!==runtime.version||prior.url!==runtime.url)){
+            throw new ArcaneError(ERROR_CODES.usage,`Select one ${runtime.id} runtime version and URL for this operation.`);
+        }
+        if(runtime.version!==undefined&&(!is.string(runtime.version)||!runtime.version)){
+            throw new ArcaneError(ERROR_CODES.usage,`${runtime.id} version must be a nonempty string.`);
+        }
+        if(runtime.url!==undefined&&(!is.string(runtime.url)||!runtime.url)){
+            throw new ArcaneError(ERROR_CODES.usage,`${runtime.id} URL must be a nonempty string.`);
+        }
+        selected.set(runtime.id,runtime);
+    }
+    return [...selected.values()];
+}
+
+function selectedDirectory(directory){
+    if(!is.string(directory)||!directory){
+        throw new ArcaneError(ERROR_CODES.usage,'Local AI installation needs an explicit directory.');
+    }
+    return path.resolve(directory);
+}
+
+function releaseAssetNames(id,version,platform,architecture){
+    if(id==='ollama'){
+        if(platform==='darwin'&&['x64','arm64'].includes(architecture))return ['ollama-darwin.tgz'];
+        const arch=architecture==='x64'?'amd64':architecture;
+        if(!['amd64','arm64'].includes(arch))return [];
+        if(platform==='win32')return [`ollama-windows-${arch}.zip`];
+        if(platform==='linux')return [`ollama-linux-${arch}.tar.zst`,`ollama-linux-${arch}.tgz`];
+        return [];
+    }
+    if(!['x64','arm64'].includes(architecture))return [];
+    if(platform==='win32')return [`llama-${version}-bin-win-cpu-${architecture}.zip`];
+    if(platform==='linux')return [`llama-${version}-bin-ubuntu-${architecture}.tar.gz`,`llama-${version}-bin-ubuntu-${architecture}.zip`];
+    if(platform==='darwin')return [`llama-${version}-bin-macos-${architecture}.tar.gz`,`llama-${version}-bin-macos-${architecture}.zip`];
+    if(platform==='android'&&architecture==='arm64')return [`llama-${version}-bin-android-arm64.tar.gz`];
+    return [];
+}
+
+async function upstreamResponse(url,signal){
+    throwIfAborted(signal);
+    const response=await fetch(url,{signal,headers:{'User-Agent':'arcane-os-local-ai'}});
+    if(!response.ok){
+        const body=await response.text();
+        throw new ArcaneError(ERROR_CODES.operationFailed,`Local AI download returned HTTP ${response.status}${body?`: ${body}`:''}.`);
+    }
+    return response;
+}
+
+async function selectRelease(runtime,platform,architecture,signal){
+    if(runtime.url){
+        const name=path.posix.basename(new URL(runtime.url).pathname);
+        return {version:runtime.version??'custom',url:runtime.url,name};
+    }
+    const repository=runtime.id==='llama.cpp'?'ggml-org/llama.cpp':'ollama/ollama';
+    const selected=runtime.version&&runtime.version!=='latest'
+        ?`tags/${encodeURIComponent(runtime.id==='ollama'&&!runtime.version.startsWith('v')?`v${runtime.version}`:runtime.version)}`
+        :'latest';
+    let release=await (await upstreamResponse(`https://api.github.com/repos/${repository}/releases/${selected}`,signal)).json();
+    if(runtime.id==='llama.cpp'){
+        // Stable llama.cpp releases identify their binary build explicitly.
+        const nightly=release.assets?.find(function isNightlySelection(asset){return asset.name==='nightly-tag.txt';});
+        if(nightly){
+            const tag=(await (await upstreamResponse(nightly.browser_download_url,signal)).text()).trim();
+            release=await (await upstreamResponse(`https://api.github.com/repos/${repository}/releases/tags/${encodeURIComponent(tag)}`,signal)).json();
+        }
+    }
+    // Select only published format variants for this exact target distribution.
+    const names=releaseAssetNames(runtime.id,release.tag_name,platform,architecture);
+    const asset=release.assets?.find(function isSelectedAsset(candidate){return names.includes(candidate.name);});
+    if(!asset){
+        throw new ArcaneError(ERROR_CODES.targetUnavailable,`${runtime.id} ${release.tag_name} has no published ${platform}/${architecture} runtime archive${names.length?` named ${names.join(' or ')}`:''}.`);
+    }
+    return {version:release.tag_name,url:asset.browser_download_url,name:asset.name};
+}
+
+async function installedRuntime(base,runtime,platform,architecture,signal){
+    let entries;
+    try{
+        entries=await readdir(base,{withFileTypes:true});
+    }catch(error){
+        if(error.code==='ENOENT')return null;
+        throw error;
+    }
+    for(const entry of entries){
+        throwIfAborted(signal);
+        if(!entry.isDirectory())continue;
+        let installation;
+        try{
+            installation=JSON.parse(await readFile(path.join(base,entry.name,'installation.json'),{encoding:'utf8',signal}));
+        }catch(error){
+            if(error.code==='ENOENT'||error instanceof SyntaxError)continue;
+            throw error;
+        }
+        if(installation.requestVersion!==(runtime.version??null)||installation.requestUrl!==(runtime.url??null))continue;
+        const record=installation.runtime;
+        if(record?.id!==runtime.id||record.platform!==platform||record.architecture!==architecture)continue;
+        try{
+            if((await stat(record.executable)).isFile())return {...record,...(runtime.version?{requestedVersion:runtime.version}:{})};
+        }catch(error){
+            if(error.code!=='ENOENT')throw error;
+        }
+    }
+    return null;
+}
+
+async function runtimeExecutable(root,id,platform,signal){
+    const filename=`${id==='llama.cpp'?'llama-server':'ollama'}${platform==='win32'?'.exe':''}`;
+    const directories=[root];
+    for(const directory of directories){
+        throwIfAborted(signal);
+        const entries=await readdir(directory,{withFileTypes:true});
+        for(const entry of entries){
+            const selected=path.join(directory,entry.name);
+            if(entry.name===filename&&(entry.isFile()||entry.isSymbolicLink()))return selected;
+            if(entry.isDirectory())directories.push(selected);
+        }
+    }
+    throw new ArcaneError(ERROR_CODES.operationFailed,`The ${id} archive does not contain ${filename}.`);
+}
+
+async function installRuntime(runtime,{directory,platform,architecture,signal,onEvent}){
+    const base=path.join(directory,runtime.id,`${platform}-${architecture}`,encodeURIComponent(runtime.version??'default'));
+    await onEvent({type:'local-ai.install.starting',message:`Preparing ${runtime.id} for ${platform}/${architecture}.`,data:{id:runtime.id,platform,architecture}});
+    const installed=await installedRuntime(base,runtime,platform,architecture,signal);
+    if(installed){
+        await onEvent({type:'local-ai.install.available',message:`${runtime.id} ${installed.version} is already installed.`,data:installed});
+        return installed;
+    }
+    const release=await selectRelease(runtime,platform,architecture,signal);
+    throwIfAborted(signal);
+    await mkdir(base,{recursive:true});
+    const attempt=await mkdtemp(path.join(base,'install-'));
+    const root=path.join(attempt,'runtime');
+    const archive=path.join(attempt,release.name);
+    let completed=false;
+    try{
+        await onEvent({type:'local-ai.install.downloading',message:`Downloading ${runtime.id} ${release.version}.`,data:{id:runtime.id,version:release.version,platform,architecture}});
+        const response=await upstreamResponse(release.url,signal);
+        await pipeline(Readable.fromWeb(response.body),createWriteStream(archive,{flags:'wx'}),{signal});
+        await onEvent({type:'local-ai.install.extracting',message:`Extracting ${runtime.id} ${release.version}.`,data:{id:runtime.id,version:release.version}});
+        await extractLocalAIArchive({archive,directory:root,signal,onEvent});
+        const executable=await runtimeExecutable(root,runtime.id,platform,signal);
+        const record={id:runtime.id,version:release.version,platform,architecture,root,executable,...(runtime.version?{requestedVersion:runtime.version}:{})};
+        throwIfAborted(signal);
+        await unlink(archive);
+        await writeFile(path.join(attempt,'installation.json'),`${JSON.stringify({requestVersion:runtime.version??null,requestUrl:runtime.url??null,runtime:record},null,2)}\n`,{flag:'wx',signal});
+        completed=true;
+        await onEvent({type:'local-ai.install.completed',message:`${runtime.id} ${release.version} is available.`,data:record});
+        return record;
+    }catch(error){
+        // Only this invocation's newly created incomplete attempt is removed.
+        // Previously installed runtimes are never overwritten or retired here.
+        if(!completed){
+            try{
+                await rm(attempt,{recursive:true,force:true});
+            }catch(cleanupError){
+                throw new AggregateError([error,cleanupError],`Installation of ${runtime.id} failed and its incomplete directory could not be removed.`);
+            }
+        }
+        throw error;
+    }
+}
+
+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]);
+    let entry=installations.get(key);
+    if(entry?.controller.signal.aborted){
+        // The prior cancelled attempt owns its cleanup. A later request waits
+        // for that narrow shared destination operation before starting afresh.
+        return entry.task.catch(function observeCancelledAttempt(){return undefined;}).then(function restartAfterCancellation(){
+            return shareInstallation(runtime,options);
+        });
+    }
+    if(!entry){
+        entry={controller:new AbortController(),consumers:new Set(),task:null};
+        installations.set(key,entry);
+    }
+    const current=entry;
+    return new Promise(function subscribeInstallation(resolve,reject){
+        let settled=false;
+        const consumer={onEvent:options.onEvent,finish,cancel,cancelError:null};
+        function finish(error,value){
+            if(settled)return;
+            settled=true;
+            options.signal?.removeEventListener('abort',abort);
+            current.consumers.delete(consumer);
+            if(current.consumers.size===0&&!current.controller.signal.aborted){
+                current.controller.abort(error);
+            }
+            if(consumer.cancelError)reject(consumer.cancelError);
+            else if(error)reject(error);
+            else resolve(value);
+        }
+        function abort(){
+            cancel(new ArcaneError(ERROR_CODES.cancelled,`Cancelled preparation of ${runtime.id}.`,{cause:options.signal?.reason,exitCode:130}));
+        }
+        function cancel(error){
+            if(settled)return;
+            consumer.cancelError??=error;
+            const hasOtherConsumer=[...current.consumers].some(function stillNeedsInstallation(subscriber){
+                return subscriber!==consumer&&!subscriber.cancelError;
+            });
+            if(hasOtherConsumer){
+                finish(consumer.cancelError);
+            }else{
+                // The last consumer stays joined until the download, extractor
+                // and incomplete-output cleanup have actually stopped.
+                current.controller.abort(consumer.cancelError);
+            }
+        }
+        async function publish(event){
+            await Promise.all([...current.consumers].map(async function sendConsumerEvent(subscriber){
+                if(subscriber.cancelError)return;
+                try{
+                    await subscriber.onEvent(event);
+                }catch(error){
+                    subscriber.cancel(error);
+                }
+            }));
+            throwIfAborted(current.controller.signal);
+        }
+        current.consumers.add(consumer);
+        options.signal?.addEventListener('abort',abort,{once:true});
+        if(options.signal?.aborted)abort();
+        if(!current.task){
+            current.task=installRuntime(runtime,{...options,signal:current.controller.signal,onEvent:publish});
+            void current.task.then(function installationCompleted(record){
+                installations.delete(key);
+                for(const subscriber of [...current.consumers])subscriber.finish(null,record);
+            },function installationFailed(error){
+                installations.delete(key);
+                for(const subscriber of [...current.consumers])subscriber.finish(normalizeError(error));
+            });
+        }
+    });
+}
+
+export async function ensureLocalAIRuntimes({runtimes=[],directory,platform=process.platform,architecture=process.arch,signal,onEvent}={}){
+    const selected=selectRuntimes(runtimes);
+    if(selected.length===0)return [];
+    const root=selectedDirectory(directory);
+    const controller=new AbortController();
+    const operationSignal=signal?AbortSignal.any([signal,controller.signal]):controller.signal;
+    const events=createEventQueue(onEvent,{onFailure:function cancelFailedObserver(error){controller.abort(error);}});
+    const startedAt=Date.now();
+    const heartbeat=setInterval(function reportInstallHeartbeat(){
+        void events.enqueue({type:'local-ai.install.heartbeat',message:'Local AI runtime preparation is active.',data:{elapsedMs:Date.now()-startedAt}},{coalesce:'local-ai.install.heartbeat'});
+    },5000);
+    heartbeat.unref?.();
+    try{
+        // There is one job per selected runtime, at most one llama.cpp and one
+        // Ollama job. Independent runtimes download and extract concurrently.
+        const outcomes=await Promise.allSettled(selected.map(function prepareRuntime(runtime){
+            return shareInstallation(runtime,{directory:root,platform,architecture,signal:operationSignal,onEvent:events.send});
+        }));
+        await events.drain();
+        const failures=outcomes.filter(function failedRuntime(outcome){return outcome.status==='rejected';});
+        if(failures.length===1)throw failures[0].reason;
+        if(failures.length>1)throw new AggregateError(failures.map(function runtimeFailure(outcome){return outcome.reason;}),'Local AI runtime preparation failed.');
+        throwIfAborted(operationSignal);
+        return outcomes.map(function completedRuntime(outcome){return outcome.value;});
+    }finally{
+        clearInterval(heartbeat);
+        await events.drain();
+    }
+}
+
+async function copyRuntimeTree(source,destination,outputRoot,files,signal){
+    throwIfAborted(signal);
+    const info=await lstat(source);
+    if(info.isDirectory()){
+        await mkdir(destination);
+        for(const entry of await readdir(source)){
+            await copyRuntimeTree(path.join(source,entry),path.join(destination,entry),outputRoot,files,signal);
+        }
+        await chmod(destination,info.mode);
+        return;
+    }
+    if(info.isSymbolicLink()){
+        await symlink(await readlink(source),destination);
+    }else{
+        await copyFile(source,destination);
+        await chmod(destination,info.mode);
+    }
+    files.push(path.relative(outputRoot,destination).split(path.sep).join('/'));
+}
+
+export async function bundleLocalAIRuntimes({runtimes=[],directory,outputRoot,platform=process.platform,architecture=process.arch,signal,onEvent}={}){
+    const selected=selectRuntimes(runtimes);
+    const root=selectedDirectory(outputRoot);
+    for(const runtime of selected){
+        const destination=path.join(root,'runtime','local-ai',runtime.id);
+        try{
+            await lstat(destination);
+        }catch(error){
+            if(error.code==='ENOENT')continue;
+            throw error;
+        }
+        throw new ArcaneError(ERROR_CODES.operationFailed,`Local AI bundle destination already exists: ${destination}. Select a fresh native staging directory.`);
+    }
+    const installed=await ensureLocalAIRuntimes({runtimes:selected,directory,platform,architecture,signal,onEvent});
+    if(installed.length===0)return {runtimes:[],files:[]};
+    await onEvent?.({type:'local-ai.bundle.starting',message:'Copying selected local AI runtimes into the native bundle.',data:{platform,architecture,runtimes:selected.map(function runtimeId(runtime){return runtime.id;})}});
+    await mkdir(path.join(root,'runtime','local-ai'),{recursive:true});
+    const outcomes=await Promise.allSettled(installed.map(async function bundleRuntime(runtime){
+        throwIfAborted(signal);
+        const files=[];
+        const relative=`runtime/local-ai/${runtime.id}`;
+        const destination=path.join(root,relative);
+        await copyRuntimeTree(runtime.root,destination,root,files,signal);
+        return {runtime:{...runtime,root:relative,executable:`${relative}/${path.relative(runtime.root,runtime.executable).split(path.sep).join('/')}`},files};
+    }));
+    const failures=outcomes.filter(function failedBundle(outcome){return outcome.status==='rejected';});
+    if(failures.length===1)throw failures[0].reason;
+    if(failures.length>1)throw new AggregateError(failures.map(function bundleFailure(outcome){return outcome.reason;}),'Local AI runtime bundling failed.');
+    const records=outcomes.map(function bundledRecord(outcome){return outcome.value.runtime;});
+    const files=outcomes.flatMap(function bundledFiles(outcome){return outcome.value.files;});
+    await onEvent?.({type:'local-ai.bundle.completed',message:'Selected local AI runtimes are included in the native bundle.',data:{platform,architecture,files}});
+    return {runtimes:records,files};
+}

package/src/local-ai/server.mjs

@@ -0,0 +1,262 @@
+import {mkdir} from 'node:fs/promises';
+import path from 'node:path';
+import Is from 'strong-type';
+import {ArcaneError,ERROR_CODES,errorRecord,normalizeError,throwIfAborted} from '../errors.mjs';
+import {createEventQueue} from '../event-queue.mjs';
+import {runProcess} from '../process.mjs';
+
+const is=new Is(false);
+
+export function localAIConnectionRefused(error){
+    if(error?.code==='ECONNREFUSED'||error?.cause?.code==='ECONNREFUSED')return true;
+    const failures=error?.errors??error?.cause?.errors;
+    return is.array(failures)&&failures.length>0&&failures.every(localAIConnectionRefused);
+}
+
+function localHostname(hostname){
+    return hostname==='localhost'||hostname==='127.0.0.1'||hostname==='[::1]'||hostname==='::1';
+}
+
+export function localAIServerURL(id,configuration={}){
+    return configuration.url??(id==='llama.cpp'?'http://127.0.0.1:8080':'http://127.0.0.1:11434');
+}
+
+export async function inspectLocalAIServer({id,url,signal}){
+    throwIfAborted(signal);
+    const endpoint=new URL(id==='llama.cpp'?'/health':'/api/version',url);
+    const response=await fetch(endpoint,{signal});
+    const content=await response.text();
+    throwIfAborted(signal);
+    let result=null;
+    try{
+        result=JSON.parse(content);
+    }catch(error){
+        if(!(error instanceof SyntaxError))throw error;
+    }
+    const ready=response.ok&&(id==='llama.cpp'?result?.status==='ok':is.string(result?.version)&&Boolean(result.version));
+    return {url,status:response.status,ready,version:id==='ollama'&&is.string(result?.version)?result.version:undefined,content,result};
+}
+
+async function probeServer(id,url,signal){
+    const observed=await inspectLocalAIServer({id,url,signal});
+    if(!observed.ready){
+        if(id==='llama.cpp'&&observed.status===503&&observed.result?.error?.message==='Loading model'){
+            throw new ArcaneError('LOCAL_AI_LOADING','llama.cpp is loading its model.',{details:observed});
+        }
+        throw new ArcaneError(ERROR_CODES.operationFailed,`${id} readiness returned HTTP ${observed.status}: ${observed.content}`,{details:observed});
+    }
+    return observed;
+}
+
+export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,onEvent,onState}={}){
+    if(!['llama.cpp','ollama'].includes(id)){
+        throw new ArcaneError(ERROR_CODES.usage,`Unsupported local AI server: ${String(id)}.`);
+    }
+    const url=localAIServerURL(id,configuration);
+    const endpoint=new URL(url);
+    const controller=new AbortController();
+    const operationSignal=signal?AbortSignal.any([signal,controller.signal]):controller.signal;
+    const events=createEventQueue(onEvent,{onFailure:fail});
+    let current={id,url,state:'starting',available:false,owned:false};
+    let owned=false;
+    let processTask=null;
+    let processObservation=null;
+    let startupTask=null;
+    let closeTask=null;
+    let closing=false;
+    let settled=false;
+    let readinessStarted=false;
+    let readinessTask=null;
+    let terminalFailure=null;
+    let resolveReady;
+    let rejectReady;
+    const output={stdout:'',stderr:''};
+    const ready=new Promise(function createReadiness(resolve,reject){
+        resolveReady=resolve;
+        rejectReady=reject;
+    });
+    // Readiness remains returned to the caller; this observer prevents a
+    // background start from creating an unhandled rejection before it is used.
+    void ready.catch(function observeReadinessFailure(){return undefined;});
+
+    async function publishState(state,error){
+        current={id,url,state,available:state==='ready',owned,...(error?{error:errorRecord(error)}:{})};
+        await onState?.(current);
+        await events.send({
+            type:`local-ai.server.${state}`,
+            message:error?`${id}: ${error.message}`:`${id} is ${state}.`,
+            data:{...current,...(error?{error}:{})}
+        });
+    }
+
+    function settleReady(error){
+        if(settled)return;
+        settled=true;
+        if(error)rejectReady(error);
+        else resolveReady(current);
+    }
+
+    async function fail(error){
+        const failure=normalizeError(error);
+        terminalFailure??=failure;
+        controller.abort(failure);
+        settleReady(failure);
+        try{
+            const state=closing?'stopped':failure.code==='LOCAL_AI_LOADING'?'loading':'error';
+            await publishState(state,state==='error'?failure:undefined);
+        }catch(observerError){
+            // Keep the callback failure visible on the returned observation;
+            // the operation's original failure remains on the ready Promise.
+            current={...current,available:false,error:errorRecord(observerError)};
+            throw observerError;
+        }
+    }
+
+    async function confirmReadiness(){
+        await probeServer(id,url,operationSignal);
+        throwIfAborted(operationSignal);
+        await publishState('ready');
+        throwIfAborted(operationSignal);
+        settleReady();
+    }
+
+    async function forwardProcessEvent(event){
+        await events.send(event);
+        if(readinessStarted||closing||operationSignal.aborted)return;
+        if(event.type==='process.stdout')output.stdout+=event.data?.line??event.message;
+        else if(event.type==='process.stderr')output.stderr+=event.data?.line??event.message;
+        else return;
+        const text=event.type==='process.stdout'?output.stdout:output.stderr;
+        // llama.cpp b11146 and b6000 emit these after HTTP/model readiness;
+        // Ollama emits its listener announcement before serving queued requests.
+        const announced=id==='llama.cpp'?/\b(?:llama_server:\s*listening on |main:\s*server is listening on )/u.test(text):/Listening on /u.test(text);
+        if(!announced)return;
+        readinessStarted=true;
+        // Do not hold the process-output callback while the health response
+        // waits for upstream startup; stdout/stderr must continue draining.
+        readinessTask=confirmReadiness().catch(fail);
+        void readinessTask.catch(function observeReadinessCallbackFailure(){return undefined;});
+    }
+
+    async function start(){
+        await publishState('starting');
+        throwIfAborted(operationSignal);
+        let existing=false;
+        try{
+            // Discovery may precede another runtime's installation. Read the
+            // endpoint at this actual launch boundary rather than presenting
+            // that earlier installation-selection snapshot as current health.
+            const observed=await probeServer(id,url,operationSignal);
+            if(runtime?.requestedVersion&&runtime.requestedVersion!=='latest'){
+                const requested=runtime.requestedVersion.replace(/^v/u,'');
+                if(!is.string(observed.version)||observed.version.replace(/^v/u,'')!==requested){
+                    throw new ArcaneError(ERROR_CODES.operationFailed,`The running ${id} service does not establish the requested version ${runtime.requestedVersion}. Select an available listener for that installed runtime.`,{details:observed});
+                }
+            }
+            existing=true;
+        }catch(error){
+            throwIfAborted(operationSignal);
+            // An HTTP error is an existing service's state. Only a refused
+            // connection allows starting the selected local executable.
+            if(!localAIConnectionRefused(error))throw error;
+            if(!localHostname(endpoint.hostname))throw error;
+        }
+        if(existing){
+            await publishState('ready');
+            throwIfAborted(operationSignal);
+            settleReady();
+            return;
+        }
+        if(!runtime?.executable){
+            throw new ArcaneError(ERROR_CODES.prerequisiteMissing,`No installed ${id} executable was supplied.`);
+        }
+        if(endpoint.protocol!=='http:'){
+            throw new ArcaneError(ERROR_CODES.usage,`${id} managed startup requires its direct HTTP listener URL.`);
+        }
+        if(!is.string(appRoot)||!appRoot){
+            throw new ArcaneError(ERROR_CODES.usage,`${id} managed startup needs its application root.`);
+        }
+        const args=configuration.args??[];
+        if(!is.array(args)||args.some(function nonStringArgument(argument){
+            return !is.string(argument);
+        })){
+            throw new ArcaneError(ERROR_CODES.usage,`${id} arguments must be an array of strings.`);
+        }
+        const modelsDirectory=path.resolve(appRoot,configuration.modelsDirectory??path.join('.arcane','models',id));
+        await mkdir(modelsDirectory,{recursive:true});
+        throwIfAborted(operationSignal);
+        const host=endpoint.hostname.replace(/^\[|\]$/gu,'');
+        const port=endpoint.port||'80';
+        const arguments_=id==='ollama'?['serve',...args]:[
+            '--host',host,'--port',port,'--jinja',
+            ...(configuration.model?['--model',path.resolve(appRoot,configuration.model)]:['--models-dir',modelsDirectory]),
+            ...args
+        ];
+        const env=id==='ollama'?{OLLAMA_HOST:endpoint.origin,OLLAMA_MODELS:modelsDirectory}:undefined;
+        owned=true;
+        await publishState('starting');
+        throwIfAborted(operationSignal);
+        processTask=runProcess(runtime.executable,arguments_,{
+            cwd:path.dirname(runtime.executable),env,signal:operationSignal,onEvent:forwardProcessEvent
+        });
+        processObservation=processTask.then(async function localServerExited(result){
+            if(terminalFailure)return;
+            if(closing||operationSignal.aborted){
+                settleReady(new ArcaneError(ERROR_CODES.cancelled,`${id} startup was cancelled.`,{exitCode:130}));
+                await publishState('stopped');
+                return;
+            }
+            await fail(new ArcaneError(ERROR_CODES.operationFailed,`${id} stopped with exit code ${result.code}.`,{details:result}));
+        },async function localServerFailed(error){
+            if(terminalFailure)return;
+            if(closing||(signal?.aborted&&!events.error)){
+                settleReady(normalizeError(error));
+                await publishState('stopped');
+                return;
+            }
+            await fail(error);
+        });
+        void processObservation.catch(function observeProcessCallbackFailure(error){
+            current={...current,state:'error',available:false,error:errorRecord(error)};
+            settleReady(error);
+        });
+    }
+
+    async function finishClose(){
+        closing=true;
+        operationSignal.removeEventListener('abort',observeLifetimeAbort);
+        controller.abort(new ArcaneError(ERROR_CODES.cancelled,`${id} was stopped by its owner.`,{exitCode:130}));
+        const startup=await Promise.allSettled([startupTask]);
+        const tasks=[processObservation,readinessTask].filter(function activeTask(task){return task!==null;});
+        const outcomes=await Promise.allSettled(tasks);
+        settleReady(new ArcaneError(ERROR_CODES.cancelled,`${id} startup was cancelled.`,{exitCode:130}));
+        await publishState('stopped');
+        await events.drain();
+        const failures=[...startup,...outcomes].filter(function failedTask(outcome){return outcome.status==='rejected';});
+        if(failures.length===1)throw failures[0].reason;
+        if(failures.length>1)throw new AggregateError(failures.map(function taskFailure(outcome){return outcome.reason;}),`${id} shutdown observers failed.`);
+    }
+
+    function close(){
+        closeTask??=finishClose();
+        return closeTask;
+    }
+
+    function observeLifetimeAbort(){
+        if(closing||terminalFailure)return;
+        void close().catch(function observeAbortShutdownFailure(error){
+            current={...current,state:'error',available:false,error:errorRecord(error)};
+            settleReady(error);
+        });
+    }
+
+    startupTask=start().catch(fail);
+    void startupTask.catch(function observeStartupCallbackFailure(error){
+        current={...current,state:'error',available:false,error:errorRecord(error)};
+        settleReady(error);
+    });
+    operationSignal.addEventListener('abort',observeLifetimeAbort,{once:true});
+    if(operationSignal.aborted)observeLifetimeAbort();
+
+    return {ready,url,close,get owned(){return owned;},get current(){return current;}};
+}

package/src/native/portable-layout.mjs

@@ -149,20 +149,45 @@ export async function copyCoreRuntime(root, files, signal, {
     return metadata;
 }
 
-export function coreEntrySource(application, version, services) {
+export function coreEntrySource(application, version, services, {localAI, runtimes = []} = {}) {
     const imports = services.map(function serviceImport(service, index) {
         const specifier = '../app/' + service.module.split('/').map(encodeURIComponent).join('/');
         return `import createService${index} from ${JSON.stringify(specifier)};`;
     });
+    // JSON parsing retains authored field names that have object-literal syntax.
     const definitions = services.map(function serviceDefinition(service, index) {
-        return `    createService${index}(${JSON.stringify(service.options === undefined ? {} : service.options)})`;
+        return `    createService${index}(JSON.parse(${JSON.stringify(JSON.stringify(service.options === undefined ? {} : service.options))}), context)`;
     });
+    if (localAI !== undefined) {
+        imports.push("import {createLocalAIService} from 'arcane-os/core/local-ai';");
+        definitions.push(`    createLocalAIService(JSON.parse(${JSON.stringify(JSON.stringify(localAI))}), context)`);
+    }
     return [
-        "import {startCoreHost} from 'arcane-os/core/host';",
+        "import {fileURLToPath} from 'node:url';",
+        "import {readCoreLaunchContext, startCoreHost} from 'arcane-os/core/host';",
         ...imports,
         '',
+        ...(localAI === undefined ? [] : [
+            '// Bundled runtime paths are artifact-root-relative POSIX paths.',
+            'function runtimePath(relative) {',
+            "    return fileURLToPath(new URL('../' + relative.split('/').map(encodeURIComponent).join('/'), import.meta.url));",
+            '}',
+            ''
+        ]),
+        '// Factories share launch context as their second argument; authored options stay first.',
+        '// Explicit launch fields override artifact-relative defaults unchanged.',
+        'const context = {',
+        "    appRoot: fileURLToPath(new URL('../app/', import.meta.url)),",
+        ...(localAI === undefined ? [] : [
+            `    runtimes: JSON.parse(${JSON.stringify(JSON.stringify(runtimes))}).map(function runtimeLocation(runtime) {`,
+            '        return {...runtime, root: runtimePath(runtime.root), executable: runtimePath(runtime.executable)};',
+            '    }),'
+        ]),
+        '    ...await readCoreLaunchContext()',
+        '};',
+        '',
         'const host = startCoreHost({',
-        `    application: ${JSON.stringify(application)},`,
+        `    application: JSON.parse(${JSON.stringify(JSON.stringify(application))}),`,
         `    version: ${JSON.stringify(version)},`,
         `    services: [\n${definitions.join(',\n')}\n    ]`,
         '});',