arcane-os 0.48.0 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.49.0
+
+- Queue complete TWiN Cloud/FAL synthesis jobs through credential readiness,
+  submission, remote completion and the complete audio response. Excess jobs
+  wait in order; cancellation removes waiting work before submission. Preserve
+  independent follow-up HTTP concurrency and dispatch cadence, full input,
+  caller cancellation and original-order playback.
+- Queue initial POST attempts and eligible retries with a shared HTTP 429
+  cooldown. Preserve the bounded readable-rejection retry and never replay an
+  ambiguous POST network, JSON or error-body failure. Existing provider factory,
+  compatibility alias and configuration remain supported.
+- Expose optional ordinary Kokoro `model.voices` display records through the
+  synchronous provider catalog without loading or fetching a model. Applications
+  own their selected inventory and previews; metadata does not limit synthesis
+  voices or claim playback availability. Existing artifact-graph voice paths
+  retain their meaning. No new dependency, saved-data migration or default
+  provider change; native browser TTS is a separate subsequent increment.
+
 ## 0.48.0
 
 - Add opt-in Chat `transcriptionMode='draft'` and public `appendDraft(text)`.

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.48.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.49.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/browser-runtime/ai/browser-speech-artifacts.mjs

@@ -899,6 +899,9 @@ export function createBrowserSpeechAuthority({
   const dtype = model.dtype === undefined
     ? null
     : identifier(model.dtype, "Browser speech model dtype");
+  if (role === "tts" && model.voices !== undefined && !is.array(model.voices)) {
+    throw new TypeError("Browser Kokoro model voices must be an array.");
+  }
   const modelFiles = uniqueFiles(
     model.files ?? [],
     "Browser speech model",
@@ -967,6 +970,7 @@ export function createBrowserSpeechAuthority({
     revision: modelRevision,
     ...(dtype === null ? {} : { dtype }),
     defaultVoice: normalizedModel.defaultVoice,
+    ...(role === "tts" && model.voices !== undefined ? { voices: model.voices } : {}),
     runtime: completeValue({
       adapter: normalizedRuntime.adapter,
       version: normalizedRuntime.version,

package/browser-runtime/ai/browser-speech-providers.mjs

@@ -1151,7 +1151,7 @@ function createBrowserSpeechProvider({
     ...(authority.dtype ? { dtype: authority.dtype } : {}),
     runtime: authority.runtime,
     files: authority.files,
-    ...(authority.graph ? {
+    ...(authority.graph || authority.voices !== undefined ? {
       voices: authority.voices,
     } : {}),
     speech,

package/browser-runtime/ai/twin-cloud-speech.mjs

@@ -3,7 +3,7 @@ import Queue from '../dependencies/js-queue/queue.js';
 
 const is = new Is(false);
 const INVOKE_URL = 'https://inference.do-ai.run/v1/async-invoke';
-const SUBMISSION_RETRY_DELAY_MS = 1000;
+const RATE_LIMIT_RETRY_DELAY_MS = 1000;
 
 function speechError(message, code, cause) {
     const error = cause === undefined
@@ -36,30 +36,6 @@ function assertIdentifier(value, label) {
     }
 }
 
-function waitForStatus(delay, signal) {
-    assertNotAborted(signal);
-    return new Promise(
-        function waitForCloudSpeechStatus(resolve, reject) {
-            const timer = setTimeout(finishStatusWait, delay);
-            function finishStatusWait() {
-                signal.removeEventListener('abort', cancelStatusWait);
-                resolve();
-            }
-            function cancelStatusWait() {
-                clearTimeout(timer);
-                signal.removeEventListener('abort', cancelStatusWait);
-                reject(abortedSpeech(signal));
-            }
-            signal.addEventListener(
-                'abort',
-                cancelStatusWait,
-                {once: true}
-            );
-            if (signal.aborted) cancelStatusWait();
-        }
-    );
-}
-
 function retryAfterDelay(response) {
     const value = response.headers?.get?.('Retry-After');
     if (!value?.trim()) return null;
@@ -69,11 +45,11 @@ function retryAfterDelay(response) {
     return is.finite(date) ? Math.max(0, date - Date.now()) : null;
 }
 
-async function requireSuccessfulResponse(response, signal, operation) {
-    if (response.ok) return response;
+async function readResponseError(response, signal, operation) {
+    if (response.ok) return null;
     const detail = await response.text();
     assertNotAborted(signal);
-    throw speechError(
+    return speechError(
         `TWiN Cloud speech ${operation} failed with HTTP ${response.status}${detail ? `: ${detail}` : '.'}`,
         'ARCANE_AI_CLOUD_SPEECH_HTTP_ERROR'
     );
@@ -83,8 +59,8 @@ async function requireSuccessfulResponse(response, signal, operation) {
  * A remote provider/2 TTS adapter. The application selects the model and voice,
  * and getApiKey returns its current credential or the application's existing
  * refresh promise. Credentials never enter status or configuration. The runtime
- * owns whole-job admission and playback order. This provider owns immediate
- * submissions and one configurable queue for follow-up HTTP/body operations.
+ * owns playback order. This provider queues whole synthesis jobs, submission
+ * attempts, and follow-up HTTP/body operations under one shared 429 cooldown.
  */
 export function createTwinCloudTTSProvider({
     id,
@@ -115,18 +91,132 @@ export function createTwinCloudTTSProvider({
 
     const modelId = model.id;
     const defaultVoice = model.defaultVoice;
+    const requests = new Set();
     const activeRequests = new Set();
     const credentialWaits = new Set();
     let state = 'unloaded';
     let generation = 0;
     let unloadOperation = null;
     let disposeOperation = null;
+    const jobs = new Queue();
+    jobs.autoRun = false;
+    const submissions = new Queue();
+    submissions.autoRun = false;
     const followUps = new Queue();
     followUps.autoRun = false;
+    let cooldownUntil = 0;
+    let submissionTimer = null;
     let activeFollowUps = 0;
     let nextFollowUpStart = 0;
     let followUpTimer = null;
 
+    function dispatchJobs() {
+        while (state === 'ready' && activeRequests.size < maxConcurrentRequests && jobs.size) {
+            jobs.next();
+        }
+    }
+
+    function queueSynthesis(request, payload, requestGeneration) {
+        const signal = request.controller.signal;
+        assertNotAborted(signal);
+        return new Promise(
+            function enqueueCloudSpeechJob(resolve, reject) {
+                function cancelQueuedJob() {
+                    jobs.contents = jobs.contents.filter(
+                        function keepOtherJob(task) {return task !== startJob;}
+                    );
+                    signal.removeEventListener('abort', cancelQueuedJob);
+                    reject(abortedSpeech(signal));
+                    dispatchJobs();
+                }
+                function finishJob() {
+                    activeRequests.delete(request);
+                    dispatchJobs();
+                }
+                function startJob() {
+                    signal.removeEventListener('abort', cancelQueuedJob);
+                    activeRequests.add(request);
+                    // A slot belongs to the entire synthesis, including its
+                    // accepted remote job, every read, and the complete audio.
+                    synthesize(payload, request.controller, requestGeneration).then(
+                        function acceptCloudSpeechJob(audio) {
+                            finishJob();
+                            resolve(audio);
+                        },
+                        function rejectCloudSpeechJob(error) {
+                            finishJob();
+                            reject(error);
+                        }
+                    );
+                }
+                jobs.add(startJob);
+                signal.addEventListener(
+                    'abort',
+                    cancelQueuedJob,
+                    {once: true}
+                );
+                if (signal.aborted) cancelQueuedJob();
+                else dispatchJobs();
+            }
+        );
+    }
+
+    function dispatchSubmissions() {
+        clearTimeout(submissionTimer);
+        submissionTimer = null;
+        if (state !== 'ready' || !submissions.size) return;
+        const delay = cooldownUntil - Date.now();
+        if (delay > 0) {
+            submissionTimer = setTimeout(dispatchSubmissions, Math.min(2147483647, delay));
+            return;
+        }
+        // Each admitted job awaits its current attempt before requeueing, so
+        // whole-job capacity also bounds concurrent submission attempts.
+        while (state === 'ready' && submissions.size) submissions.next();
+    }
+
+    function queueSubmission(readResponse, signal) {
+        assertNotAborted(signal);
+        return new Promise(
+            function enqueueCloudSpeechSubmission(resolve, reject) {
+                function cancelQueuedSubmission() {
+                    submissions.contents = submissions.contents.filter(
+                        function keepOtherSubmission(task) {return task !== startSubmission;}
+                    );
+                    signal.removeEventListener('abort', cancelQueuedSubmission);
+                    reject(abortedSpeech(signal));
+                    dispatchSubmissions();
+                }
+                async function consumeSubmission() {
+                    assertNotAborted(signal);
+                    return await readResponse();
+                }
+                function startSubmission() {
+                    signal.removeEventListener('abort', cancelQueuedSubmission);
+                    consumeSubmission().then(resolve, reject);
+                }
+                submissions.add(startSubmission);
+                signal.addEventListener(
+                    'abort',
+                    cancelQueuedSubmission,
+                    {once: true}
+                );
+                if (signal.aborted) cancelQueuedSubmission();
+                else dispatchSubmissions();
+            }
+        );
+    }
+
+    function observeRateLimit(response) {
+        if (response.status !== 429) return;
+        cooldownUntil = Math.max(
+            cooldownUntil,
+            Date.now() + Math.max(RATE_LIMIT_RETRY_DELAY_MS, retryAfterDelay(response) ?? 0)
+        );
+        dispatchSubmissions();
+        dispatchFollowUps();
+    }
+
     function dispatchFollowUps() {
         clearTimeout(followUpTimer);
         followUpTimer = null;
@@ -136,18 +226,20 @@ export function createTwinCloudTTSProvider({
         const eligibleIndex = followUps.contents.findIndex(
             function eligibleFollowUp(task) {return task.eligibleAt <= now;}
         );
-        if (now < nextFollowUpStart || eligibleIndex === -1) {
+        const nextStart = Math.max(nextFollowUpStart, cooldownUntil);
+        if (now < nextStart || eligibleIndex === -1) {
             const firstEligibility = followUps.contents.reduce(
                 function earliestFollowUp(time, task) {return Math.min(time, task.eligibleAt);},
                 Infinity
             );
             // Long Retry-After dates may exceed the platform timer's range.
             // Revisit at that boundary without shortening the job's eligibility.
-            followUpTimer = setTimeout(dispatchFollowUps, Math.min(2147483647, Math.max(nextFollowUpStart, firstEligibility) - now));
+            followUpTimer = setTimeout(dispatchFollowUps, Math.min(2147483647, Math.max(nextStart, firstEligibility) - now));
             return;
         }
-        // A job's Retry-After does not hold up eligible siblings. Queue remains
-        // the sole pending-task owner, with FIFO order among eligible entries.
+        // Successful pending responses retain job-local Retry-After timing.
+        // HTTP 429 also applies the shared cooldown before any queued start.
+        // Queue owns pending tasks in FIFO order among eligible entries.
         if (eligibleIndex > 0) {
             const [eligibleTask] = followUps.contents.splice(eligibleIndex, 1);
             followUps.contents.unshift(eligibleTask);
@@ -287,7 +379,7 @@ export function createTwinCloudTTSProvider({
             localOnly: false,
             state,
             loaded,
-            busy: activeRequests.size > 0,
+            busy: requests.size > 0,
             execution: {
                 requestedDevice: 'remote',
                 selectedDevice: loaded ? 'remote' : null,
@@ -310,11 +402,12 @@ export function createTwinCloudTTSProvider({
                 // an identified job's status read can retry a network failure.
                 return {error, retryable: options.method === 'GET' && error instanceof TypeError};
             }
+            assertNotAborted(signal);
+            observeRateLimit(response);
             const nextEligibility = Date.now() + (retryAfterDelay(response) ?? 0);
-            try {
-                await requireSuccessfulResponse(response, signal, operation);
-            } catch (error) {
-                assertNotAborted(signal);
+            const error = await readResponseError(response, signal, operation);
+            assertNotAborted(signal);
+            if (error) {
                 return {error, retryable: response.status === 429, eligibleAt: nextEligibility};
             }
             // Parsing errors are not Fetch failures and must not replay a job.
@@ -325,7 +418,7 @@ export function createTwinCloudTTSProvider({
         while (true) {
             assertNotAborted(signal);
             const outcome = options.method === 'POST'
-                ? await readInferenceResponse()
+                ? await queueSubmission(readInferenceResponse, signal)
                 : await queueFollowUp(readInferenceResponse, signal, eligibleAt);
             assertNotAborted(signal);
             if (!outcome.error) return outcome;
@@ -333,11 +426,6 @@ export function createTwinCloudTTSProvider({
             retryError = outcome.error;
             console.warn(`Retrying the cloud speech ${operation} once.`, retryError);
             eligibleAt = outcome.eligibleAt ?? 0;
-            if (options.method === 'POST') {
-                // A readable submission rejection retains its own bounded retry
-                // delay. It never delays another job or enters the GET queue.
-                await waitForStatus(Math.max(SUBMISSION_RETRY_DELAY_MS, eligibleAt - Date.now()), signal);
-            }
         }
     }
 
@@ -402,7 +490,11 @@ export function createTwinCloudTTSProvider({
         const audio = await queueFollowUp(
             async function downloadCloudSpeechAudio() {
                 const audioResponse = await fetchImpl(result.output.audio.url, {signal});
-                await requireSuccessfulResponse(audioResponse, signal, 'audio download');
+                assertNotAborted(signal);
+                observeRateLimit(audioResponse);
+                const error = await readResponseError(audioResponse, signal, 'audio download');
+                assertNotAborted(signal);
+                if (error) throw error;
                 return await audioResponse.blob();
             },
             signal,
@@ -491,9 +583,6 @@ export function createTwinCloudTTSProvider({
             if (state !== 'ready' || unloadOperation || disposeOperation) {
                 throw speechError('The cloud speech provider is not ready.', 'ARCANE_AI_NOT_READY');
             }
-            if (activeRequests.size >= maxConcurrentRequests) {
-                throw speechError('The cloud speech provider is at capacity.', 'ARCANE_AI_PROVIDER_BUSY');
-            }
             const payload = context.payload;
             if (!is.string(payload?.input) || !payload.input.trim()) {
                 throw new TypeError('Cloud speech input must be a nonempty string.');
@@ -523,16 +612,16 @@ export function createTwinCloudTTSProvider({
             );
             if (context.signal?.aborted) cancelCloudSpeechRequest();
             const request = {controller, promise: null};
-            activeRequests.add(request);
-            request.promise = synthesize(payload, controller, generation);
+            requests.add(request);
             try {
+                request.promise = queueSynthesis(request, payload, generation);
                 return await request.promise;
             } catch (error) {
                 if (controller.signal.aborted) throw abortedSpeech(controller.signal);
                 throw error;
             } finally {
                 context.signal?.removeEventListener('abort', cancelCloudSpeechRequest);
-                activeRequests.delete(request);
+                requests.delete(request);
             }
         },
 
@@ -546,11 +635,15 @@ export function createTwinCloudTTSProvider({
             if (unloadOperation) return unloadOperation;
             state = 'unloading';
             generation += 1;
+            clearTimeout(submissionTimer);
+            submissionTimer = null;
+            clearTimeout(followUpTimer);
+            followUpTimer = null;
             for (const cancelCredentialWait of [...credentialWaits]) cancelCredentialWait();
-            const requests = [...activeRequests];
-            for (const request of requests) request.controller.abort('Cloud speech provider unloaded.');
+            const pendingRequests = [...requests];
+            for (const request of pendingRequests) request.controller.abort('Cloud speech provider unloaded.');
             unloadOperation = Promise.allSettled(
-                requests.map(
+                pendingRequests.map(
                     function pendingCloudSpeechRequest(request) {
                         return request.promise;
                     }

package/docs/reference/ai/browser-speech.md

@@ -138,11 +138,13 @@ playback remain the only owners. Use
 punctuation boundary should submit promptly. This is incremental playback of
 completed synthesis jobs, not a live audio stream from TWiN Cloud.
 
-The SDK submits `POST https://inference.do-ai.run/v1/async-invoke` immediately
-after credential readiness, outside the follow-up queue. It then reads that job
-until its completed `output.audio.url` is available. The provider's
-`maxConcurrentRequests` retains its whole-synthesis-job meaning; it is separate
-from `followUpQueue.maxConcurrentRequests`.
+The provider queues each complete synthesis job, including initial
+`POST https://inference.do-ai.run/v1/async-invoke` and any eligible submission
+retry. `maxConcurrentRequests` defaults to four whole jobs. Each slot remains
+occupied through credential readiness, submission, queued/running status, and
+the complete final audio response. Additional requests wait in order; cancelling
+a waiting job removes it before credential reading or submission. This capacity
+is separate from `followUpQueue.maxConcurrentRequests`.
 
 One provider-local `js-queue` owns only follow-up status/result GETs and the final
 audio GET. `followUpQueue` defaults to `{maxConcurrentRequests:4,intervalMs:250}`;
@@ -153,20 +155,31 @@ job awaits its current response and body before immediately enqueueing another
 request only when incomplete or eligible for a retry. There is no additional
 per-job polling delay.
 
-A readable `Retry-After` changes only the affected job's next eligibility, not
-sibling requests or initial submissions. A readable `429` permits one retry of
-that submission or status read; submission retries retain a one-second minimum, while
-follow-up retries use the queue cadence and any longer readable `Retry-After`.
+A successful pending response's `Retry-After` changes that job's next eligibility.
+A `429` applies a shared cooldown to all queued submission and follow-up starts,
+using a one-second minimum and any longer readable `Retry-After`. A completely
+readable `429` permits one retry of that submission or status read, within the
+same whole-job slot. Already dispatched operations retain their response ownership.
 An accepted job's status Fetch network failure may retry once for the same job;
-JSON parsing failures are not network retries. Repeated failures surface their
+Ambiguous POST network, JSON parsing, and error-body read failures never replay
+the submission. Repeated failures surface their
 complete diagnostics without an endless retry loop; a failed job does not cancel
 siblings. Retry diagnostics remain in the developer console, outside conversation
 history.
 
-The queue is created when this cloud factory is called, not when the browser
+The provider-local queues are created when this cloud factory is called, not when the browser
 speech entrypoint is imported. Local Kokoro and Whisper do not use this queue;
 their setup, Workers, synthesis/transcription, and lifecycle remain independent.
 
+Ordinary Kokoro descriptors may supply `model.voices` as complete display records,
+for example `{id:'af_heart',name:'Heart',lang:'en-US'}`. The synchronous
+`provider.catalog()[0].voices` preserves that array and its metadata without
+loading the model or fetching a catalog. The application supplies the inventory
+for its selected runtime; these records neither create a synthesis allow-list
+nor establish that a voice has loaded or played. Ordinary Worker configuration
+does not receive this display inventory. Existing artifact-graph voice paths
+retain their separate meaning.
+
 The SDK pins published `js-queue` through npm. Its browser Queue entry, original
 package metadata, and license are projected unchanged by
 `node tools/sync-js-queue.mjs` after an SDK dependency update. The existing runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",