arcane-os 0.56.0 → 0.58.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.58.0
+
+- Add native ONNX sessions through `arcane-os/local-ai/onnx` and browser Core
+  access through `arcane-os/ai/core-onnx`. Explicit runtime selection uses the
+  upstream Node runtime distribution, retained per-session workers, complete
+  tensor transport, authoritative loaded state and owned cancellation/exit.
+  Apps select their graphs, feeds and processing; no model is chosen or fetched.
+- Add native Nemotron diarization runtime preparation, helper build and Core
+  integration. Preserve complete framed input/output, independent streams,
+  cancellation and process drain. Runtime/model selection remains explicit.
+- Add the reusable Core preferences service and Git text snapshots, preserving
+  complete caller data and existing application-owned storage and repository
+  choices. Extend raw process I/O without changing existing UTF-8 defaults.
+- Add shared WebKit document lifecycle and macOS native host composition source,
+  portable target contracts, and explicit packaged HTTP serving through the
+  existing HTTP server. Default HTTPS and ordinary browser behavior remain.
+  macOS executable build and platform acceptance remain separately pending.
+- No automatic runtime/model installation, application default switch or saved
+  data migration is introduced. Native host archive delivery is separate from
+  npm publication; this release does not claim an available Windows/Mac archive.
+
+## 0.57.0
+
+- Add local model chat through explicit llama.cpp/Ollama runtime requirements,
+  reusable installation and bundling, a retained Core local-AI service, and an
+  optional browser-to-Core provider. Preserve complete requests and streamed
+  responses, model readiness, cancellation and owned process shutdown. Apps own
+  model selection and defaults; preparation does not block ordinary page startup.
+- Add authored Core service selection and launch context. Factories receive
+  authored options and the separate app-root/runtime context; explicit launch
+  context overrides remain supported. Portable packages can bundle explicitly
+  selected local-AI runtimes without changing browser-only output.
+- Add Windows x64 executable packaging through the public Windows native
+  provider and the matching release's retained WebView2/Node SEA host asset.
+  Client injection precedes app scripts, service requests retain complete JSON,
+  and accepted service work drains before the owned Core process exits.
+- Add `runProcess` cancellation mode `close-input` for owned graceful shutdown;
+  the existing `terminate-tree` default remains unchanged. Includes separately
+  delivered macOS process source, without claiming a complete macOS host.
+- Correct the documented Node document-library subpath and lexical-search
+  example. No preferences service, Nemotron diarization, native ONNX, native
+  Kokoro or local image generation is introduced in this release.
+
 ## 0.56.0
 
 - Add explicit `package.nativeResources` selection for native-only application

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.56.0` SDK contract. Development applications declare
+This checkout defines the `0.58.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;
@@ -131,7 +131,7 @@ each device. Keep these local files ignored by Git. The same certificate pair
 works for any selected app in that workspace. The command reports missing TLS
 files instead of starting an HTTP listener.
 
-HTTPS is the default for development and required for packaged browser previews.
+HTTPS is the default for development and packaged browser previews.
 Plain `npm run dev` binds to localhost with the same workspace certificate pair.
 An explicit `--host` overrides the bind address, and `--port` selects the HTTPS port.
 The paired HTTP listener returns 308 redirects and uses an OS-assigned port
@@ -152,6 +152,10 @@ This selects one HTTP content listener and prints HTTP network URLs. It reads
 no certificate pair and serves the same application and generated PWA routes.
 PWA and storage availability still depend on the browser's secure-context
 rules; see [HTTP development](docs/reference/cli.md#explicit-http-development).
+API callers may also explicitly select `http:true` with `mode:'packaged'` to
+serve the selected packaged web root through the same listener owner. See
+[`startDevServer()`](docs/reference/sdk-api.md#startdevserver) for readiness,
+start-URL and shutdown behavior.
 
 Open the URL printed by the server. The generated page owns its import map and
 Arcane theme; its application module is `modules/App.js` at the repository root.

package/browser-runtime/ai/core-local.mjs

@@ -0,0 +1,306 @@
+import Is from '../dependencies/strong-type/index.js';
+import {getInstalledCoreClient} from '../core/client.mjs';
+
+const is = new Is(false);
+const PROVIDER_PROTOCOL = 'arcane-ai-provider/2';
+const AUTHORITY_PROTOCOL = 'arcane-ai-model-authority/1';
+
+function localAIError(code, message, cause) {
+    const error = cause === undefined ? new Error(message) : new Error(message, {cause});
+    error.code = code;
+    return error;
+}
+
+function cancelled(reason) {
+    const error = localAIError('ARCANE_AI_REQUEST_ABORTED', 'The local AI request was cancelled.', reason);
+    error.name = 'AbortError';
+    return error;
+}
+
+/**
+ * Browser-safe llama.cpp access through an existing Core connection. The app
+ * selects its model; Core owns the running engine and its loaded sessions.
+ * Creating this provider neither connects a transport nor installs a runtime.
+ */
+export function createCoreLocalAIProvider({client = getInstalledCoreClient(), id = 'llama.cpp'} = {}) {
+    if (!is.string(id) || !id.trim()) throw new TypeError('The Core AI provider id must be a nonempty string.');
+    if (client !== null && (!is.function(client?.invoke) || !is.function(client?.events?.on))) {
+        throw new TypeError('The Core AI client must expose invoke and events.on.');
+    }
+
+    let runtime = null;
+    let models = [];
+    let selection = null;
+    let disposed = false;
+    let loading = false;
+    let sequence = 0;
+    let lifecycleRevision = 0;
+    const requests = new Set();
+
+    function requireClient() {
+        if (disposed) throw localAIError('ARCANE_AI_PROVIDER_DISPOSED', 'The Core AI provider is disposed.');
+        if (!client) throw localAIError('ARCANE_AI_CORE_UNAVAILABLE', 'Local llama.cpp requires an available Core connection.');
+        return client;
+    }
+
+    function requireSelection(value) {
+        if (value?.providerId !== id || !is.string(value?.modelId) || !value.modelId
+            || value.localOnly !== true) {
+            throw localAIError('ARCANE_AI_MODEL_AUTHORITY_REQUIRED', 'The local provider requires an explicit matching provider and model.');
+        }
+        return value;
+    }
+
+    function loadedModel() {
+        return selection && models.find(function selectedModel(model) {
+            return model.id === selection.modelId && model.loaded === true;
+        });
+    }
+
+    function modelReady() {
+        return runtime?.available === true && runtime.state === 'ready' && Boolean(loadedModel());
+    }
+
+    function status() {
+        const loaded = !disposed && modelReady();
+        return {
+            state: disposed ? 'disposed' : loading ? 'loading' : loaded ? 'ready'
+                : runtime?.error ? 'error' : runtime?.available === true ? 'unloaded' : 'unavailable',
+            loaded,
+            busy: loading || requests.size > 0,
+            modelId: selection?.modelId ?? null,
+            available: !disposed && runtime?.available === true,
+            installed: runtime?.installed === true,
+            error: runtime?.error ?? null
+        };
+    }
+
+    function acceptRuntime(value) {
+        runtime = value ?? null;
+        models = is.array(runtime?.models) ? runtime.models : [];
+        for (const request of requests) {
+            const model = models.find(function requestModel(record) { return record.id === request.modelId; });
+            if (model?.loaded === true) request.loaded = true;
+            if (runtime?.available !== true || (request.loaded && (runtime.state !== 'ready' || model?.loaded !== true))) {
+                request.controller.abort(localAIError('ARCANE_AI_MODEL_NOT_READY', 'The requested local model is no longer ready.', runtime?.error));
+            }
+        }
+        return status();
+    }
+
+    const unsubscribe = client?.events.on('localai.state', function localRuntimeChanged(snapshot) {
+        if (disposed || !is.array(snapshot?.runtimes)) return;
+        lifecycleRevision += 1;
+        acceptRuntime(snapshot.runtimes.find(function llamaRuntime(value) {
+            return value.id === 'llama.cpp';
+        }));
+    }) ?? function noCoreSubscription() {};
+
+    function authority(value) {
+        return {protocol: AUTHORITY_PROTOCOL, providerId: id, modelId: value.modelId};
+    }
+
+    async function inspect(value, {signal} = {}) {
+        requireSelection(value);
+        if (signal?.aborted) throw cancelled(signal.reason);
+        try {
+            const core = requireClient();
+            const statusRevision = lifecycleRevision;
+            const current = await core.invoke('llama.status', {}, {signal});
+            if (lifecycleRevision === statusRevision) acceptRuntime(current);
+            if (runtime?.available !== true) {
+                return {
+                    available: false,
+                    code: 'ARCANE_AI_PROVIDER_UNAVAILABLE',
+                    message: 'The local llama.cpp runtime is unavailable.',
+                    error: runtime?.error ?? null
+                };
+            }
+            if (!models.some(function matchesModel(model) { return model.id === value.modelId; })) {
+                return {
+                    available: false,
+                    code: 'ARCANE_AI_MODEL_UNAVAILABLE',
+                    message: 'The selected model is unavailable in the local llama.cpp runtime.'
+                };
+            }
+            return {available: true, authority: authority(value)};
+        } catch (error) {
+            if (signal?.aborted || error?.name === 'AbortError') throw error;
+            acceptRuntime({...runtime, available: false, state: 'error', error});
+            return {available: false, code: error.code ?? 'ARCANE_AI_CORE_UNAVAILABLE', message: error.message, error};
+        }
+    }
+
+    async function load({selection: value, signal, progress} = {}) {
+        const core = requireClient();
+        requireSelection(value);
+        if (signal?.aborted) throw cancelled(signal.reason);
+        selection = value;
+        loading = true;
+        try {
+            progress?.({phase: 'loading', modelId: value.modelId});
+            const revision = lifecycleRevision;
+            const current = await core.invoke('llama.load', {model: value.modelId}, {signal});
+            if (lifecycleRevision === revision) acceptRuntime(current);
+            if (!modelReady()) throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'Core did not report the selected model loaded and ready.', current?.error);
+            progress?.({phase: 'ready', modelId: value.modelId});
+            return {authority: authority(value), status: {...status(), state: 'ready', busy: false}};
+        } finally {
+            loading = false;
+        }
+    }
+
+    function ownRequest(signal, modelId) {
+        const controller = new AbortController();
+        function forwardAbort() { controller.abort(signal.reason); }
+        signal?.addEventListener('abort', forwardAbort, {once: true});
+        if (signal?.aborted) forwardAbort();
+        const request = {controller, result: null, modelId, loaded: models.some(function loadedTarget(model) {
+            return model.id === modelId && model.loaded === true;
+        })};
+        requests.add(request);
+        request.release = function releaseRequest() {
+            signal?.removeEventListener('abort', forwardAbort);
+            requests.delete(request);
+        };
+        return request;
+    }
+
+    function streamRequest(core, parameters, signal) {
+        const request = ownRequest(signal, parameters.model);
+        const chunks = [];
+        const readers = [];
+        let complete = false;
+        let failure = null;
+        sequence += 1;
+        const streamId = is.function(core.uuid) ? core.uuid()
+            : globalThis.crypto?.randomUUID?.() ?? `${id}:${Date.now()}:${sequence}:${Math.random()}`;
+
+        function flush() {
+            while (readers.length && chunks.length && !request.controller.signal.aborted) {
+                readers.shift().resolve({value: chunks.shift(), done: false});
+            }
+            if (!complete || (chunks.length && !request.controller.signal.aborted)) return;
+            while (readers.length) {
+                const reader = readers.shift();
+                if (failure) reader.reject(failure);
+                else reader.resolve({value: undefined, done: true});
+            }
+        }
+
+        const stopChunks = core.events.on('llama.chunk', function receiveChunk(event) {
+            if (event?.streamId !== streamId || complete || request.controller.signal.aborted) return;
+            chunks.push(event.chunk);
+            flush();
+        });
+
+        request.result = Promise.resolve().then(function invokeStream() {
+            return core.invoke('llama.chat', {...parameters, stream: true, streamId}, {signal: request.controller.signal});
+        }).then(function streamCompleted(result) {
+            if (request.controller.signal.aborted) throw cancelled(request.controller.signal.reason);
+            return result;
+        }).catch(function streamFailed(error) {
+            failure = error;
+            throw error;
+        }).finally(function releaseStream() {
+            complete = true;
+            stopChunks();
+            request.release();
+            flush();
+        });
+        request.result.catch(function observeRetainedStreamFailure() {});
+
+        function cancel(reason) {
+            if (!complete) request.controller.abort(reason);
+            return request.result.then(function cancelledAfterSuccess() {}, function cancelledAfterFailure() {});
+        }
+
+        return {
+            result: request.result,
+            cancel,
+            [Symbol.asyncIterator]() {
+                return {
+                    next() {
+                        if (request.controller.signal.aborted) return Promise.reject(failure ?? cancelled(request.controller.signal.reason));
+                        if (chunks.length) return Promise.resolve({value: chunks.shift(), done: false});
+                        if (complete) return failure ? Promise.reject(failure) : Promise.resolve({value: undefined, done: true});
+                        return new Promise(function awaitChunk(resolve, reject) { readers.push({resolve, reject}); });
+                    },
+                    async return() {
+                        await cancel();
+                        return {value: undefined, done: true};
+                    }
+                };
+            }
+        };
+    }
+
+    async function request({selection: value, operation, payload, signal} = {}) {
+        const core = requireClient();
+        requireSelection(value);
+        if (signal?.aborted) throw cancelled(signal.reason);
+        if (loading || selection?.modelId !== value.modelId) {
+            throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'Load the selected local model before requesting inference.');
+        }
+        const model = payload?.model ?? value.modelId;
+        if (!models.some(function knownModel(record) { return record.id === model; })) {
+            const revision = lifecycleRevision;
+            const current = await core.invoke('llama.status', {}, {signal});
+            if (lifecycleRevision === revision) acceptRuntime(current);
+        }
+        if (!models.some(function knownModel(record) { return record.id === model; })) {
+            throw localAIError('ARCANE_AI_MODEL_UNAVAILABLE', 'The requested model is unavailable in the local llama.cpp runtime.');
+        }
+        if (runtime?.available !== true || runtime.state !== 'ready'
+            || (model === value.modelId && !modelReady())) {
+            throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'The requested local runtime or selected model is not ready.');
+        }
+        const parameters = {model, payload};
+        if (operation === 'stream') return streamRequest(core, parameters, signal);
+        if (operation !== 'chat') throw localAIError('ARCANE_AI_PROVIDER_OPERATION_UNAVAILABLE', 'The local llama.cpp provider supports chat and stream.');
+        const pending = ownRequest(signal, model);
+        pending.result = Promise.resolve().then(function invokeChat() {
+            return core.invoke('llama.chat', {...parameters, stream: false}, {signal: pending.controller.signal});
+        }).then(function chatCompleted(result) {
+            if (pending.controller.signal.aborted) throw cancelled(pending.controller.signal.reason);
+            return result;
+        }).finally(pending.release);
+        return pending.result;
+    }
+
+    async function unload({selection: value = selection, signal} = {}) {
+        const core = requireClient();
+        if (signal?.aborted) throw cancelled(signal.reason);
+        for (const request of requests) request.controller.abort();
+        await Promise.allSettled([...requests].map(function activeResult(request) { return request.result; }));
+        if (!value) return status();
+        requireSelection(value);
+        const revision = lifecycleRevision;
+        const current = await core.invoke('llama.unload', {model: value.modelId}, {signal});
+        if (lifecycleRevision === revision) acceptRuntime(current);
+        selection = null;
+        return status();
+    }
+
+    async function dispose(options = {}) {
+        if (disposed) return status();
+        if (selection || requests.size) await unload(options);
+        disposed = true;
+        unsubscribe();
+        return status();
+    }
+
+    return {
+        protocol: PROVIDER_PROTOCOL,
+        role: 'llm',
+        id,
+        localOnly: true,
+        catalog: function catalog() { return [...models]; },
+        status,
+        inspect,
+        load,
+        request,
+        unload,
+        dispose
+    };
+}

package/browser-runtime/ai/core-onnx.mjs

@@ -0,0 +1,96 @@
+import {getInstalledCoreClient} from '../core/client.mjs';
+import {createArcaneEventSource} from '../event-manager.mjs';
+import {encodeTensorMap, decodeTensorMap, encodeTensorFetches} from './onnx-tensors.mjs';
+
+function unavailable(message) {
+    const error = new Error(message);
+    error.code = 'ARCANE_ONNX_CORE_UNAVAILABLE';
+    return error;
+}
+
+/** Optional system ONNX access. Construction neither connects nor installs. */
+export function createCoreONNXRuntime({client = getInstalledCoreClient()} = {}) {
+    const owner = {};
+    const events = createArcaneEventSource(owner, {source: 'core-onnx', eventTypes: ['onnx.state']});
+    const lifetime = new AbortController();
+    const pending = new Set();
+    let state = {id: 'onnx', installed: false, available: false, state: 'unknown', models: []};
+    let revision = 0;
+    let closed = false;
+
+    function current() { return {...state, busy: pending.size > 0, closed}; }
+    function publish() { events.dispatch('onnx.state', current()); }
+    function accept(value) {
+        state = value ?? {id: 'onnx', installed: false, available: false, state: 'unavailable', models: []};
+        revision += 1;
+        publish();
+    }
+
+    const unsubscribe = client?.events.on('localai.state', function localStateChanged(snapshot) {
+        if (!closed) accept(snapshot?.runtimes?.find(function onnxRuntime(runtime) { return runtime.id === 'onnx'; }));
+    }) ?? function noCoreSubscription() {};
+
+    async function invoke(method, parameters, {signal, timeoutMs = 0} = {}) {
+        if (closed) throw unavailable('The Core ONNX accessor is closed.');
+        if (!client) throw unavailable('Local ONNX requires an available Core connection.');
+        const request = {};
+        const operationSignal = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
+        operationSignal.throwIfAborted();
+        pending.add(request);
+        publish();
+        try {
+            return await client.invoke(method, parameters, {signal: operationSignal, timeoutMs});
+        } finally {
+            pending.delete(request);
+            if (!closed) publish();
+        }
+    }
+
+    async function inspect(options) {
+        const before = revision;
+        try {
+            const result = await invoke('onnx.status', {}, options);
+            if (!closed && revision === before) accept(result);
+            return current();
+        } catch (error) {
+            if (!closed && !options?.signal?.aborted && revision === before) {
+                accept({...state, available: false, state: 'unavailable', error});
+            }
+            throw error;
+        }
+    }
+
+    async function load({id, model, sessionOptions, signal, timeoutMs} = {}) {
+        return invoke('onnx.load', {id, model, sessionOptions}, {signal, timeoutMs});
+    }
+
+    async function run({id, feeds, fetches, runOptions, signal, timeoutMs} = {}) {
+        const result = await invoke('onnx.run', {
+            id, feeds: encodeTensorMap(feeds),
+            fetches: encodeTensorFetches(fetches), runOptions
+        }, {signal, timeoutMs});
+        return decodeTensorMap(result);
+    }
+
+    function unload({id, signal, timeoutMs} = {}) {
+        return invoke('onnx.unload', {id}, {signal, timeoutMs});
+    }
+
+    function subscribe(listener) {
+        const stop = events.on('onnx.state', function changed(event) { listener(event.detail); });
+        try { listener(current()); } catch (error) { stop(); throw error; }
+        return stop;
+    }
+
+    function close() {
+        if (closed) return;
+        closed = true;
+        lifetime.abort();
+        unsubscribe();
+        state = {...state, available: false, state: 'closed'};
+        publish();
+        events.dispose();
+    }
+
+    return {load, run, unload, inspect, current, subscribe, close};
+}

package/browser-runtime/ai/onnx-tensors.mjs

@@ -0,0 +1,85 @@
+import Is from '../dependencies/strong-type/index.js';
+
+const is = new Is(false);
+const typedArrays = {
+    Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array,
+    Int32Array, Uint32Array, Float32Array, Float64Array,
+    BigInt64Array, BigUint64Array, Float16Array: globalThis.Float16Array
+};
+
+/** Tensor framing belongs at JSON transport boundaries, outside inference. */
+export function encodeTensorMap(tensors) {
+    if (tensors === undefined || tensors === null) return tensors;
+    return Object.fromEntries(Object.entries(tensors).map(function encodeEntry([name, tensor]) {
+        return [name, tensor === null ? null : {
+            type: tensor.type, dims: tensor.dims, data: encodeTensorData(tensor.data)
+        }];
+    }));
+}
+
+export function decodeTensorMap(tensors) {
+    if (tensors === undefined || tensors === null) return tensors;
+    return Object.fromEntries(Object.entries(tensors).map(function decodeEntry([name, tensor]) {
+        return [name, tensor === null ? null : {
+            type: tensor.type, dims: tensor.dims, data: decodeTensorData(tensor.data)
+        }];
+    }));
+}
+
+export function encodeTensorFetches(fetches) {
+    return is.array(fetches) ? fetches : encodeTensorMap(fetches);
+}
+
+export function decodeTensorFetches(fetches) {
+    return is.array(fetches) ? fetches : decodeTensorMap(fetches);
+}
+
+function encodeTensorData(data) {
+    if (is.typedArray(data)) {
+        const arrayType = Object.prototype.toString.call(data).slice(8, -1);
+        const content = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        return {encoding: 'base64', arrayType, content: encodeBase64(content)};
+    }
+    if (is.array(data)) return data.map(encodeScalar);
+    return data;
+}
+
+function decodeTensorData(data) {
+    if (data?.encoding === 'base64') {
+        const Constructor = typedArrays[data.arrayType];
+        if (!is.function(Constructor)) {
+            throw new TypeError(`Tensor data representation ${data.arrayType} is unavailable in this runtime.`);
+        }
+        const content = decodeBase64(data.content);
+        return new Constructor(content.buffer);
+    }
+    if (is.array(data)) return data.map(decodeScalar);
+    return data;
+}
+
+function encodeScalar(value) {
+    if (is.bigint(value)) return {encoding: 'bigint', value: String(value)};
+    if (is.negativeZero(value)) return {encoding: 'number', value: '-0'};
+    if (is.number(value) && !is.finite(value)) return {encoding: 'number', value: String(value)};
+    return value;
+}
+
+function decodeScalar(value) {
+    if (value?.encoding === 'bigint') return BigInt(value.value);
+    if (value?.encoding === 'number') return Number(value.value);
+    return value;
+}
+
+function encodeBase64(content) {
+    if (is.function(content.toBase64)) return content.toBase64();
+    let binary = '';
+    for (const value of content) binary += String.fromCharCode(value);
+    return btoa(binary);
+}
+
+function decodeBase64(content) {
+    if (is.function(Uint8Array.fromBase64)) return Uint8Array.fromBase64(content);
+    return Uint8Array.from(atob(content), function characterCode(character) {
+        return character.charCodeAt(0);
+    });
+}