arcane-os 0.69.0 → 0.71.0

package/browser-runtime/ai/model-resource-bridge.mjs

@@ -0,0 +1,231 @@
+import Is from '../dependencies/strong-type/index.js';
+
+const is = new Is(false);
+
+function errorRecord(value, seen = new Map()) {
+    if (!is.error(value)) return value;
+    if (seen.has(value)) return seen.get(value);
+    const record = {name: value.name, message: value.message, stack: value.stack};
+    seen.set(value, record);
+    for (const key of Object.getOwnPropertyNames(value)) {
+        if (key === 'cause') record[key] = errorRecord(value[key], seen);
+        else if (key === 'errors' && is.array(value[key])) {
+            record[key] = value[key].map(function recordError(error) {
+                return errorRecord(error, seen);
+            });
+        } else record[key] = value[key];
+    }
+    return record;
+}
+
+function reviveError(value, seen = new Map()) {
+    if (!value || !is.string(value.name) || !is.string(value.message)) return value;
+    if (seen.has(value)) return seen.get(value);
+    const error = new Error(value.message);
+    seen.set(value, error);
+    for (const [key, field] of Object.entries(value)) {
+        let item = field;
+        if (key === 'cause') item = reviveError(field, seen);
+        if (key === 'errors' && is.array(field)) {
+            item = field.map(function reviveNestedError(nested) {
+                return reviveError(nested, seen);
+            });
+        }
+        Object.defineProperty(error, key, {value: item, enumerable: true, configurable: true, writable: true});
+    }
+    return error;
+}
+
+function abortReason(signal) {
+    return signal?.reason ?? new DOMException('The model resource operation was cancelled.', 'AbortError');
+}
+
+/** The store stays at its owner; only requests and complete Blob handles cross. */
+export function createModelResourceHost({fetchResource, send, onError}) {
+    const operations = new Map();
+    const transportFailures = [];
+    let closed = false;
+    let closing;
+    function receive(message) {
+        if (message?.arcaneModelResource !== true) return false;
+        const {resourceId, op} = message;
+        if (op === 'cancel') {
+            operations.get(resourceId)?.controller.abort(reviveError(message.reason));
+            return true;
+        }
+        if (op !== 'fetch' || closed) return true;
+        const controller = new AbortController();
+        const operation = {controller};
+        operations.set(resourceId, operation);
+        async function runResourceFetch() {
+            try {
+                if (controller.signal.aborted) throw controller.signal.reason;
+                const result = await fetchResource(message.request.url, {
+                    ...message.request.options,
+                    signal: controller.signal,
+                    onProgress: function reportResourceProgress(progress) {
+                        if (!closed) send({arcaneModelResource: true, resourceId, op: 'progress', progress});
+                    }
+                });
+                if (!closed) send({arcaneModelResource: true, resourceId, op: 'result', result});
+            } catch (error) {
+                if (!closed) {
+                    try {
+                        send({arcaneModelResource: true, resourceId, op: 'error', error: errorRecord(error)});
+                    } catch (transportError) {
+                        throw new AggregateError([error, transportError], 'Model resource operation and error delivery failed.');
+                    }
+                }
+                else if (error !== controller.signal.reason && error?.name !== 'AbortError') throw error;
+            } finally {
+                operations.delete(resourceId);
+            }
+        }
+        // Publish ownership before invoking a store that can synchronously
+        // report progress and trigger reentrant Worker shutdown.
+        operation.promise = Promise.resolve().then(runResourceFetch);
+        // Keep transport failures observable at close without an unhandled
+        // rejection while the caller's Worker lifecycle is still active.
+        operation.promise.catch(function observeResourceFailure(error) {
+            transportFailures.push(error);
+            if (!closed) {
+                try {
+                    if (onError) onError(error);
+                    else globalThis.console?.error('Model resource transport failed.', error);
+                } catch (handlerError) {
+                    const failure = new AggregateError([error, handlerError], 'Model resource transport and its failure handler failed.');
+                    transportFailures.push(failure);
+                    globalThis.console?.error('Model resource failure handler failed.', failure);
+                }
+            }
+        });
+        return true;
+    }
+    function close(reason = abortReason()) {
+        if (closing) return closing;
+        closed = true;
+        let resolveClose;
+        let rejectClose;
+        closing = new Promise(function retainResourceClose(resolve, reject) {
+            resolveClose = resolve;
+            rejectClose = reject;
+        });
+        const pending = [...operations.values()];
+        for (const operation of pending) operation.controller.abort(reason);
+        Promise.allSettled(pending.map(function resourceSettlement(operation) {
+            return operation.promise;
+        })).then(function finishResourceClose() {
+            if (transportFailures.length) {
+                rejectClose(new AggregateError(transportFailures, 'Unable to settle model resource transport.'));
+            } else resolveClose();
+        });
+        return closing;
+    }
+    return {receive, close};
+}
+
+export function createModelResourceClient({send}) {
+    const pending = new Map();
+    let nextId = 1;
+    let closed = false;
+    let closeReason;
+    function receive(message) {
+        if (message?.arcaneModelResource !== true) return false;
+        const operation = pending.get(message.resourceId);
+        if (!operation) return true;
+        if (message.op === 'progress') {
+            try {
+                operation.onProgress?.(message.progress);
+            } catch (error) {
+                operation.cancel(error);
+            }
+            return true;
+        }
+        pending.delete(message.resourceId);
+        operation.release();
+        if (operation.cancelled) operation.reject(operation.reason);
+        else if (message.op === 'error') operation.reject(reviveError(message.error));
+        else operation.resolve(message.result);
+        return true;
+    }
+    async function fetchResource(input, {onProgress, ...options} = {}) {
+        if (closed) throw closeReason;
+        const request = new Request(input, options);
+        const signal = request.signal;
+        if (signal.aborted) throw abortReason(signal);
+        const requestOptions = {
+            method: request.method,
+            headers: [...request.headers],
+            mode: request.mode,
+            credentials: request.credentials,
+            cache: request.cache,
+            redirect: request.redirect,
+            referrer: request.referrer,
+            referrerPolicy: request.referrerPolicy,
+            integrity: request.integrity,
+            keepalive: request.keepalive
+        };
+        if (request.body) requestOptions.body = await request.blob();
+        if (closed) throw closeReason;
+        if (signal.aborted) throw abortReason(signal);
+        const resourceId = nextId++;
+        return new Promise(function requestModelResource(resolve, reject) {
+            const operation = {resolve, reject, onProgress, cancelled: false};
+            function cancel(reason) {
+                if (operation.cancelled) return;
+                operation.cancelled = true;
+                operation.reason = reason;
+                try {
+                    send({arcaneModelResource: true, resourceId, op: 'cancel', reason: errorRecord(reason)});
+                } catch (error) {
+                    pending.delete(resourceId);
+                    release();
+                    reject(new AggregateError([reason, error], 'Unable to cancel the model resource transport.'));
+                }
+            }
+            function cancelFromSignal() {
+                cancel(abortReason(signal));
+            }
+            function release() {
+                signal.removeEventListener('abort', cancelFromSignal);
+            }
+            operation.cancel = cancel;
+            operation.release = release;
+            pending.set(resourceId, operation);
+            signal.addEventListener('abort', cancelFromSignal, {once: true});
+            try {
+                send({arcaneModelResource: true, resourceId, op: 'fetch',
+                    request: {url: request.url, options: requestOptions}});
+            } catch (error) {
+                pending.delete(resourceId);
+                release();
+                reject(error);
+            }
+        });
+    }
+    async function fetch(input, options) {
+        const request = new Request(input, options);
+        const resource = await fetchResource(request, {onProgress: options?.onProgress});
+        const response = resource.status === 0 ? Response.error() : new Response(
+            request.method === 'HEAD' || [204, 205, 304].includes(resource.status) ? null : resource.file,
+            {status: resource.status, statusText: resource.statusText, headers: resource.headers}
+        );
+        Object.defineProperties(response, {
+            url: {value: resource.url, configurable: true},
+            redirected: {value: resource.redirected, configurable: true}
+        });
+        return response;
+    }
+    function close(reason = abortReason()) {
+        if (closed) return;
+        closed = true;
+        closeReason = reason;
+        for (const operation of pending.values()) {
+            operation.cancel(reason);
+            operation.release();
+            operation.reject(reason);
+        }
+        pending.clear();
+    }
+    return {receive, fetchResource, fetch, close};
+}

package/browser-runtime/ai/speech-worker-client.mjs

@@ -5,6 +5,7 @@ import {
   SPEECH_WORKER_PROTOCOL,
 } from "./speech-worker-runtime.mjs";
 import { arcaneLogging } from "../logging.mjs";
+import { createModelResourceHost } from './model-resource-bridge.mjs';
 
 const is = new Is(false);
 
@@ -47,6 +48,10 @@ function abortError(signal, role, op) {
   );
 }
 
+function reportSpeechTerminationFailure(error) {
+    arcaneLogging.error('Speech Worker termination failed.', error);
+}
+
 function validateWorker(worker) {
   if (!worker || !is.function(worker.postMessage) || !is.function(worker.terminate)) {
     throw new TypeError("The packaged speech worker did not create a Worker.");
@@ -72,8 +77,11 @@ class SpeechWorkerClient {
   #listeners = [];
   #terminated = false;
   #onTermination;
+  #fetchResource;
+  #resourceHost = null;
+  #terminationPromise = null;
 
-  constructor({ role, onTermination = () => undefined } = {}) {
+  constructor({ role, fetchResource = null, onTermination = () => undefined } = {}) {
     if (role !== "stt" && role !== "tts") {
       throw new TypeError('SpeechWorkerClient role must be "stt" or "tts".');
     }
@@ -89,6 +97,7 @@ class SpeechWorkerClient {
       name: role === "stt" ? "arcane-whisper-stt" : "arcane-kokoro-tts",
     });
     this.#onTermination = onTermination;
+    this.#fetchResource = fetchResource;
     WORKER_CLIENTS.add(this);
     this.#trace("created", { workerUrl: workerUrl.href });
   }
@@ -131,7 +140,25 @@ class SpeechWorkerClient {
       );
     }
     const worker = validateWorker(this.#createWorker());
+    const client = this;
     this.#worker = worker;
+    if (this.#fetchResource) {
+        this.#resourceHost = createModelResourceHost({
+            fetchResource: this.#fetchResource,
+            send: function sendSpeechResource(message) {
+                worker.postMessage(message);
+            },
+            onError: function speechResourceTransportFailed(error) {
+                const failure = clientError(
+                    'ARCANE_AI_WORKER_MESSAGE_ERROR',
+                    'Unable to deliver a resource to the speech Worker.',
+                    error,
+                    `${client.#role}-worker-message-rejected`,
+                );
+                void client.terminate(failure, { intentional: false }).catch(reportSpeechTerminationFailure);
+            },
+        });
+    }
     this.#trace("started");
     this.#listen(worker, "message", (event) => {
       this.#handleMessage(event.data);
@@ -142,7 +169,7 @@ class SpeechWorkerClient {
         "The speech Worker returned an unreadable message.",
         event,
         `${this.#role}-worker-message-rejected`,
-      ), { intentional: false }).catch(() => undefined);
+      ), { intentional: false }).catch(reportSpeechTerminationFailure);
     });
     this.#listen(worker, "error", (event) => {
       void this.terminate(clientError(
@@ -150,12 +177,13 @@ class SpeechWorkerClient {
         "The speech Worker crashed.",
         event,
         `${this.#role}-worker-crashed`,
-      ), { intentional: false }).catch(() => undefined);
+      ), { intentional: false }).catch(reportSpeechTerminationFailure);
     });
     return worker;
   }
 
   #handleMessage(message) {
+    if (this.#resourceHost?.receive(message)) return;
     this.#trace("response", { message });
     if (message?.protocol !== SPEECH_WORKER_PROTOCOL) {
       void this.terminate(clientError(
@@ -163,12 +191,12 @@ class SpeechWorkerClient {
         "The speech Worker protocol did not match the SDK.",
         undefined,
         `${this.#role}-worker-protocol-mismatch`,
-      ), { intentional: false }).catch(() => undefined);
+      ), { intentional: false }).catch(reportSpeechTerminationFailure);
       return;
     }
     if (is.safeInteger(message.id) && message.type === 'progress') {
         const pending = this.#pending.get(message.id);
-        if (pending?.op === 'load') pending.onProgress?.(message.progress);
+        pending?.onProgress?.(message.progress);
         return;
     }
     if (!is.safeInteger(message.id) || !is.boolean(message.ok)) {
@@ -177,7 +205,7 @@ class SpeechWorkerClient {
         "The speech Worker response envelope shape was rejected.",
         undefined,
         `${this.#role}-worker-response-envelope-shape-rejected`,
-      ), { intentional: false }).catch(() => undefined);
+      ), { intentional: false }).catch(reportSpeechTerminationFailure);
       return;
     }
     const pending = this.#pending.get(message.id);
@@ -201,7 +229,7 @@ class SpeechWorkerClient {
         `${this.#role}-worker-error-envelope-rejected`,
       );
       pending.reject(failure);
-      void this.terminate(failure, { intentional: false }).catch(() => undefined);
+      void this.terminate(failure, { intentional: false }).catch(reportSpeechTerminationFailure);
       return;
     }
     pending.reject(clientError(
@@ -272,20 +300,14 @@ class SpeechWorkerClient {
               error,
               `${operationSubject(client.#role, op)}-message-rejected`,
             );
-            void client.terminate(failure, { intentional: false }).catch(
-              function ignoreCancellationTerminationFailure() {
-                return undefined;
-              },
-            );
+            void client.terminate(failure, { intentional: false }).catch(reportSpeechTerminationFailure);
           }
           return;
         }
         void client.terminate(
           abortError(signal, client.#role, op),
           { intentional: true },
-        ).catch(function ignoreAbortTerminationFailure() {
-          return undefined;
-        });
+        ).catch(reportSpeechTerminationFailure);
       }
       signal?.addEventListener?.("abort", onAbort, { once: true });
       client.#pending.set(
@@ -313,11 +335,7 @@ class SpeechWorkerClient {
           `${operationSubject(client.#role, op)}-message-rejected`,
         );
         reject(failure);
-        void client.terminate(failure, { intentional: false }).catch(
-          function ignoreRequestTerminationFailure() {
-            return undefined;
-          },
-        );
+        void client.terminate(failure, { intentional: false }).catch(reportSpeechTerminationFailure);
       }
     });
   }
@@ -327,7 +345,7 @@ class SpeechWorkerClient {
     if (!is.boolean(intentional)) {
       throw new TypeError("Speech Worker termination intent must be a boolean.");
     }
-    if (this.#terminated) return;
+    if (this.#terminationPromise) return this.#terminationPromise;
     const terminationReason = is.error(reason) && WORKER_CLIENT_ERRORS.has(reason)
       ? reason
       : clientError(
@@ -349,15 +367,37 @@ class SpeechWorkerClient {
     const pendingOperations = [...this.#pending.values()];
     for (const pending of pendingOperations) pending.cleanup();
     this.#pending.clear();
+    const resourceHost = this.#resourceHost;
+    this.#resourceHost = null;
+    this.#transport = null;
+    const client = this;
+    const failures = [];
+    this.#terminationPromise = Promise.resolve().then(async function terminateSpeechResources() {
+        const settlements = await Promise.allSettled([
+            Promise.resolve().then(function closeSpeechResources() {
+                return resourceHost?.close(terminationReason);
+            }),
+            Promise.resolve().then(function terminateSpeechWorker() {
+                return worker?.terminate();
+            }),
+        ]);
+        for (const settlement of settlements) {
+            if (settlement.status === 'rejected') failures.push(settlement.reason);
+        }
+        for (const pending of pendingOperations) pending.reject(terminationReason);
+        client.#trace('terminated', { reason: terminationReason, intentional });
+        if (failures.length) {
+            throw new AggregateError(failures, 'Unable to complete speech Worker termination.', { cause: terminationReason });
+        }
+    });
+    // Revoke provider readiness immediately; reentrant pool cleanup joins the
+    // already-owned promise before releasing prepared files.
     try {
-      this.#transport = null;
-      const termination = worker?.terminate();
-      if (termination && is.function(termination.then)) await termination;
-    } finally {
-      for (const pending of pendingOperations) pending.reject(terminationReason);
-      this.#trace("terminated", { reason: terminationReason, intentional });
-      this.#onTermination(completeValue({ reason: terminationReason, intentional }));
+        this.#onTermination(completeValue({ reason: terminationReason, intentional }));
+    } catch (error) {
+        failures.push(error);
     }
+    return this.#terminationPromise;
   }
 }