arcane-os 0.83.1 → 0.85.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.83.1",
+  "version": "0.85.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -43,6 +43,7 @@
     "./ai/core-onnx": "./browser-runtime/ai/core-onnx.mjs",
     "./ai/core-image": "./browser-runtime/ai/core-image.mjs",
     "./ai/core-model-assets": "./browser-runtime/ai/core-model-assets.mjs",
+    "./ai/model-observation": "./browser-runtime/ai/model-observation.mjs",
     "./ai/browser-decisions": "./browser-runtime/ai/browser-decisions.mjs",
     "./ai/tool-text-stream": "./browser-runtime/ai/tool-text-stream.mjs",
     "./ai/twin-cloud": "./browser-runtime/ai/twin-cloud.mjs",
@@ -75,6 +76,7 @@
     "./core/image": "./src/core/services/image.mjs",
     "./core/speech": "./src/core/services/speech.mjs",
     "./core/model-assets": "./src/core/services/model-assets.mjs",
+    "./core/model-observation": "./src/core/services/model-observation.mjs",
     "./diarization": "./src/diarization/index.mjs",
     "./diarization/build": "./src/diarization/build.mjs",
     "./local-ai": "./src/local-ai/install.mjs",

package/src/core/host.mjs

@@ -5,7 +5,7 @@ import Is from 'strong-type';
 import {createCoreRuntime} from './runtime.mjs';
 import {startCoreStdio} from './stdio.mjs';
 
-export {startSharedCoreHost, connectSharedCoreHost, runSharedCoreHost, startSharedCoreBridge} from './shared-host.mjs';
+export {startCoreListener, startSharedCoreHost, connectSharedCoreHost, runSharedCoreHost, startSharedCoreBridge} from './shared-host.mjs';
 
 const is = new Is(false);
 

package/src/core/runtime-connection.mjs

@@ -0,0 +1,168 @@
+import {randomUUID} from 'node:crypto';
+import Is from 'strong-type';
+import {CORE_PROTOCOL, CoreError, serializeCoreError} from '../../browser-runtime/core/contracts.mjs';
+
+const is = new Is(false);
+const owners = new WeakMap();
+
+function failure(code, message) {
+    return new CoreError({code, message});
+}
+
+function event(event, data) {
+    return {protocol: CORE_PROTOCOL, type: 'event', event, data, time: new Date().toISOString()};
+}
+
+function runtimeConnections(runtime) {
+    const existing = owners.get(runtime);
+    if (existing) return existing;
+    const connections = new Set();
+    const requests = new Map();
+    const prefix = `connection-${randomUUID()}:`;
+    let sequence = 0;
+
+    function route(frame) {
+        if (frame.type === 'response') {
+            const record = requests.get(frame.id);
+            if (record) {
+                record.release();
+                record.connection.send({...frame, id: record.id}, record);
+            }
+            return;
+        }
+        if (frame.type !== 'event') return;
+        if (Object.hasOwn(frame, 'requestId')) {
+            const record = requests.get(frame.requestId);
+            if (record) record.connection.send({...frame, requestId: record.id}, record);
+            return;
+        }
+        for (const connection of connections) connection.send(frame);
+    }
+
+    const unsubscribe = runtime.onFrame(route);
+    const owner = {
+        connections,
+        requests,
+        allocate(requestPrefix) {
+            // Every acceptance gets a fresh transport correlation. A retired
+            // service context must never target a later use of its client ID.
+            const active = runtime.current().activeRequests;
+            function inUse(candidate) {
+                return requests.has(candidate) || active.some(
+                    function activeRequest(request) { return request.id === candidate; }
+                );
+            }
+            let internalId;
+            do {
+                internalId = `${requestPrefix ?? ''}${prefix}${++sequence}`;
+            } while (inUse(internalId));
+            return internalId;
+        },
+        release() {
+            if (connections.size || requests.size) return;
+            unsubscribe();
+            owners.delete(runtime);
+        }
+    };
+    owners.set(runtime, owner);
+    return owner;
+}
+
+/** One transport connection borrows dispatch; only its host owns runtime.close. */
+export function createCoreRuntimeConnection({
+    runtime, send, requestPrefix, mapFrame, getReplayEvents, preserveContextRequestId = true
+}) {
+    const owner = runtimeConnections(runtime);
+    const requests = new Map();
+    const internalRequests = new Map();
+    let disconnected = false;
+
+    function deliver(frame, record) {
+        if (disconnected) return;
+        const outgoing = mapFrame ? mapFrame(frame, record) : frame;
+        if (outgoing !== undefined) send(outgoing);
+    }
+
+    function cancel(record) {
+        return runtime.handle(
+            {protocol: CORE_PROTOCOL, type: 'control', control: 'request.cancel', requestId: record.internalId}
+        );
+    }
+
+    function cancelAll() {
+        return Promise.all([...requests.values()].map(cancel));
+    }
+
+    function replay() {
+        const state = runtime.current();
+        if (state.state === 'ready') deliver(event('core.ready', {version: state.version, app: state.application}));
+        deliver(event('core.state', state));
+        for (const service of state.services) deliver(event('core.service.state', service));
+        // Only the existing owner's current snapshots, never requests/history.
+        for (const snapshot of getReplayEvents?.() ?? []) deliver(event(snapshot.event, snapshot.data));
+    }
+
+    async function handle(frame) {
+        if (disconnected) throw failure('CORE_CONNECTION_CLOSED', 'The Core connection is closed.');
+        if (frame?.protocol !== CORE_PROTOCOL) throw failure('INVALID_RPC_REQUEST', 'Unknown Core protocol.');
+        if (frame.type === 'control') {
+            if (frame.control === 'runtime.replay') return replay();
+            if (frame.control === 'requests.cancelAll') return cancelAll();
+            if (frame.control === 'request.cancel') {
+                const record = requests.get(frame.requestId);
+                return record ? cancel(record) : undefined;
+            }
+            throw failure('INVALID_RPC_CONTROL', 'Unknown Core control.');
+        }
+        if (frame.type !== 'request' || !is.string(frame.id) || !frame.id || !is.string(frame.method)) {
+            throw failure('INVALID_RPC_REQUEST', 'A Core request requires an id and method.');
+        }
+        if (requests.has(frame.id)) {
+            const answer = {protocol: CORE_PROTOCOL, type: 'response', id: frame.id, ok: false,
+                error: serializeCoreError(failure('RPC_REQUEST_ID_ACTIVE', 'The request id is already active on this connection.')),
+                time: new Date().toISOString()};
+            deliver(answer);
+            return answer;
+        }
+        const record = {connection, id: frame.id, internalId: owner.allocate(requestPrefix), release: releaseRequest};
+        function releaseRequest() {
+            if (requests.get(record.id) === record) requests.delete(record.id);
+            internalRequests.delete(record.internalId);
+            owner.requests.delete(record.internalId);
+            owner.release();
+        }
+        requests.set(record.id, record);
+        internalRequests.set(record.internalId, record);
+        owner.requests.set(record.internalId, record);
+        try {
+            return await runtime.handle(
+                {...frame, id: record.internalId},
+                {
+                    contextRequestId: preserveContextRequestId ? record.id : undefined,
+                    contextClientRequestId: record.id
+                }
+            );
+        } finally {
+            releaseRequest();
+        }
+    }
+
+    function close() {
+        if (disconnected) return Promise.resolve();
+        disconnected = true;
+        owner.connections.delete(connection);
+        const cancellation = cancelAll();
+        owner.release();
+        return cancellation;
+    }
+
+    const connection = {
+        handle,
+        close,
+        send: deliver,
+        has(id) { return requests.has(id); },
+        request(internalId) { return internalRequests.get(internalId); }
+    };
+    owner.connections.add(connection);
+    return connection;
+}

package/src/core/runtime.mjs

@@ -218,7 +218,7 @@ class CoreRuntime {
         return this.current();
     }
 
-    async handle(frame) {
+    async handle(frame, {contextRequestId, contextClientRequestId} = {}) {
         if (frame?.protocol !== CORE_PROTOCOL) throw failure('INVALID_RPC_REQUEST', 'Unknown Core protocol.');
         if (frame.type === 'control') {
             if (frame.control === 'runtime.replay') {
@@ -235,7 +235,13 @@ class CoreRuntime {
         if (frame.type !== 'request' || !is.string(frame.id) || !frame.id || !is.string(frame.method)) {
             throw failure('INVALID_RPC_REQUEST', 'A Core request requires an id and method.');
         }
-        const task = this.#answer(frame);
+        if (contextRequestId !== undefined && (!is.string(contextRequestId) || !contextRequestId)) {
+            throw failure('INVALID_RPC_REQUEST', 'A transport context request id must be a nonempty string.');
+        }
+        if (contextClientRequestId !== undefined && (!is.string(contextClientRequestId) || !contextClientRequestId)) {
+            throw failure('INVALID_RPC_REQUEST', 'A transport client request id must be a nonempty string.');
+        }
+        const task = this.#answer(frame, contextRequestId, contextClientRequestId);
         this.#responses.add(task);
         try {
             return await task;
@@ -244,7 +250,7 @@ class CoreRuntime {
         }
     }
 
-    async #answer(frame) {
+    async #answer(frame, contextRequestId, contextClientRequestId) {
         let result;
         let error;
         let ok = true;
@@ -254,7 +260,7 @@ class CoreRuntime {
             if (frame.method === 'system.ping') result = {ok: true};
             else if (frame.method === 'version.current') result = this.#version;
             else if (frame.method === 'app.current') result = this.#application;
-            else result = await this.#request(frame);
+            else result = await this.#request(frame, contextRequestId, contextClientRequestId);
         } catch (caught) {
             ok = false;
             error = caught;
@@ -270,7 +276,7 @@ class CoreRuntime {
         return response;
     }
 
-    #request(frame) {
+    #request(frame, contextRequestId, contextClientRequestId) {
         const registration = this.#methods.get(frame.method);
         if (!registration) {
             const namespace = frame.method.split('.')[0];
@@ -300,7 +306,13 @@ class CoreRuntime {
                     const result = await handle.call(
                         service.definition,
                         frame.parameters,
-                        {...runtime.#serviceContext(service, frame.id), requestId: frame.id, signal: controller.signal}
+                        {
+                            ...runtime.#serviceContext(service, frame.id),
+                            requestId: contextRequestId ?? frame.id,
+                            clientRequestId: contextClientRequestId ?? contextRequestId ?? frame.id,
+                            coreRequestId: frame.id,
+                            signal: controller.signal
+                        }
                     );
                     aborted(controller);
                     return result;

package/src/core/services/model-observation.mjs

@@ -0,0 +1,231 @@
+import Is from 'strong-type';
+import {CoreError} from '../../../browser-runtime/core/contracts.mjs';
+
+const is = new Is(false);
+
+function observationError(code, message) {
+    return new CoreError({code, message});
+}
+
+/** Observe supplied owners without acquiring, starting or replacing a model. */
+export function createModelObservationService({runtime, localAI = null, image = null, decisions = null} = {}) {
+    if (!is.function(runtime?.current) || !is.function(runtime?.onFrame)) {
+        throw new TypeError('Model observation requires the existing Core runtime.');
+    }
+    const owners = {localAI, image, decisions};
+    const observedMethods = new Set();
+    for (const owner of Object.values(owners)) {
+        if (owner === null) continue;
+        if (!is.function(owner.current)) throw new TypeError('An observed Core model owner must expose current().');
+        for (const method of Object.keys(owner.methods ?? {})) observedMethods.add(method);
+    }
+
+    const renderers = new Map();
+    const watchers = new Set();
+    const requests = new Map();
+    let stopFrames = null;
+    let disposed = false;
+
+    function current() {
+        return {
+            core: runtime.current(),
+            native: {
+                localAI: localAI?.current() ?? null,
+                image: image?.current() ?? null,
+                decisions: decisions?.current() ?? null
+            },
+            renderers: [...renderers.values()].map(function rendererState(renderer) {
+                return {
+                    attachmentRequestId: renderer.request.clientRequestId,
+                    coreRequestId: renderer.request.coreRequestId,
+                    owners: renderer.snapshot
+                };
+            })
+        };
+    }
+
+    function requireActive(request) {
+        request.signal.throwIfAborted();
+        if (disposed) throw observationError('MODEL_OBSERVATION_CLOSED', 'Model observation is closed.');
+    }
+
+    function requireContext(request) {
+        requireActive(request);
+        if (!is.string(request.clientRequestId) || !is.string(request.coreRequestId)) {
+            throw observationError('MODEL_OBSERVATION_CONTEXT_UNAVAILABLE',
+                'Model observation requires the actual client and Core request identities.');
+        }
+    }
+
+    function observeActiveRequests(snapshot) {
+        for (const request of snapshot.activeRequests) {
+            if (observedMethods.has(request.method)) requests.set(request.id, request.method);
+        }
+        // Core publishes request removal before its response. Keep correlation
+        // until that response arrives, rather than treating removal as settlement.
+    }
+
+    function stopFrameObservation() {
+        if (watchers.size) return;
+        stopFrames?.();
+        stopFrames = null;
+        requests.clear();
+    }
+
+    function send(watcher, event, value) {
+        if (!watchers.has(watcher) || watcher.request.signal.aborted) return;
+        try {
+            watcher.request.emit(event, {watchRequestId: watcher.request.clientRequestId, ...value});
+        } catch (error) {
+            watcher.stop(error);
+        }
+    }
+
+    function publishState() {
+        if (!watchers.size) return;
+        let snapshot;
+        try {
+            snapshot = current();
+        } catch (error) {
+            for (const watcher of [...watchers]) watcher.stop(error);
+            return;
+        }
+        for (const watcher of [...watchers]) send(watcher, 'model.observation.state', {snapshot});
+    }
+
+    function observeFrame(frame) {
+        try {
+            if (frame.type === 'response') {
+                const method = requests.get(frame.id);
+                requests.delete(frame.id);
+                if (method !== undefined && frame.ok === false) {
+                    for (const watcher of [...watchers]) {
+                        if (watcher.diagnostics) {
+                            send(watcher, 'model.observation.error', {source: 'core', method, frame});
+                        }
+                    }
+                }
+                return;
+            }
+            if (frame.type !== 'event') return;
+            if (frame.event === 'core.state') {
+                observeActiveRequests(frame.data);
+                publishState();
+            } else if (frame.event === 'localai.state' || frame.event === 'image.state'
+                || frame.event === 'decisions.state') {
+                publishState();
+            }
+        } catch (error) {
+            // An observation failure must settle observers, never the operation
+            // whose existing owner emitted this frame.
+            for (const watcher of [...watchers]) watcher.stop(error);
+        }
+    }
+
+    function hold(request, release) {
+        let reject;
+        let stopped = false;
+        const task = new Promise(function ownObservationRequest(_resolve, rejectRequest) {
+            reject = rejectRequest;
+        });
+        function stop(error) {
+            if (stopped) return;
+            stopped = true;
+            request.signal.removeEventListener('abort', aborted);
+            try {
+                release();
+            } catch (releaseError) {
+                error = new AggregateError([error, releaseError], 'Observation retirement failed.');
+            }
+            reject(error);
+        }
+        function aborted() {
+            stop(request.signal.reason ?? observationError('ARCANE_REQUEST_ABORTED', 'Model observation was cancelled.'));
+        }
+        request.signal.addEventListener('abort', aborted, {once: true});
+        return {task, stop, checkAbort: function checkObservationAbort() { if (request.signal.aborted) aborted(); }};
+    }
+
+    function watch({diagnostics = false} = {}, request) {
+        requireContext(request);
+        if (!is.boolean(diagnostics)) throw new TypeError('diagnostics must be a boolean.');
+        const watcher = {request, diagnostics, stop: null};
+        const owned = hold(request, function releaseWatcher() {
+            watchers.delete(watcher);
+            stopFrameObservation();
+        });
+        watcher.stop = owned.stop;
+        watchers.add(watcher);
+        try {
+            if (!stopFrames) stopFrames = runtime.onFrame(observeFrame);
+            observeActiveRequests(runtime.current());
+            send(watcher, 'model.observation.state', {snapshot: current()});
+            owned.checkAbort();
+        } catch (error) {
+            owned.stop(error);
+        }
+        return owned.task;
+    }
+
+    function attach({snapshot} = {}, request) {
+        requireContext(request);
+        if (!snapshot || !is.object(snapshot)) throw new TypeError('Renderer observation requires its current owner snapshots.');
+        if (renderers.has(request.coreRequestId)) {
+            throw observationError('MODEL_OBSERVATION_ATTACHMENT_ACTIVE', 'This Core attachment request is already active.');
+        }
+        const renderer = {request, snapshot, stop: null};
+        const owned = hold(request, function releaseRenderer() {
+            if (renderers.get(request.coreRequestId) === renderer) renderers.delete(request.coreRequestId);
+            publishState();
+        });
+        renderer.stop = owned.stop;
+        renderers.set(request.coreRequestId, renderer);
+        try {
+            request.emit('model.observation.renderer.attached', {
+                attachmentRequestId: request.clientRequestId,
+                coreRequestId: request.coreRequestId
+            });
+            publishState();
+            owned.checkAbort();
+        } catch (error) {
+            owned.stop(error);
+        }
+        return owned.task;
+    }
+
+    function publishRenderer({attachmentRequestId, coreRequestId, snapshot} = {}, request) {
+        requireActive(request);
+        const renderer = renderers.get(coreRequestId);
+        if (!renderer || renderer.request.clientRequestId !== attachmentRequestId || renderer.request.signal.aborted) {
+            throw observationError('MODEL_OBSERVATION_ATTACHMENT_RETIRED', 'The selected renderer observation attachment is no longer active.');
+        }
+        if (!snapshot || !is.object(snapshot)) throw new TypeError('Renderer observation requires its current owner snapshots.');
+        renderer.snapshot = snapshot;
+        publishState();
+        return {attachmentRequestId, coreRequestId};
+    }
+
+    function dispose() {
+        if (disposed) return;
+        disposed = true;
+        const error = observationError('MODEL_OBSERVATION_CLOSED', 'Model observation is closed.');
+        for (const watcher of [...watchers]) watcher.stop(error);
+        for (const renderer of [...renderers.values()]) renderer.stop(error);
+        stopFrameObservation();
+    }
+
+    return {
+        name: 'model-observation',
+        current,
+        dispose,
+        methods: {
+            'model.observation.current': function currentObservation(_parameters, request) {
+                requireActive(request);
+                return current();
+            },
+            'model.observation.watch': watch,
+            'model.observation.renderer.attach': attach,
+            'model.observation.renderer.publish': publishRenderer
+        }
+    };
+}