arcane-os 0.33.6 → 0.34.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.34.1
+
+- Honor an optional request-local `model` in `AI.fetchRequest()` and
+  `AI.streamRequest()`. Direct and registered built-in TWiN/native Ollama
+  requests carry the supplied model without changing the shared selection.
+  Calls that omit the option retain the selected default.
+- Preserve complete messages, streaming, tools, cancellation and request
+  observers. Provider-reported stream model metadata remains authoritative;
+  generated stream completion metadata falls back to the request's model.
+  The option does not load or switch a browser-WASM model.
+
+## 0.34.0
+
+- Add `createDigitalOceanFalTTSProvider` through `arcane-os/ai/browser-speech`
+  for DigitalOcean's asynchronous FAL speech service. Applications select the
+  model and voice and supply a current credential getter, which may return a
+  promise. Configuration and activation make no provider request; synthesis
+  preserves complete input and fetches returned audio without forwarding the
+  inference credential. Status polling never retries a paid submission.
+- Add `AI.configureSpeechProvider(role, provider, options)` for independent
+  STT or TTS replacement and removal, preserving the other selected role.
+  Credential waits, synthesis, and local polling follow cancellation and
+  provider teardown. Cancelling local work does not establish cancellation of
+  an already-submitted remote job.
+- Preserve explicit unmute intent while the canonical AI owner, selected
+  provider registration, or speech configuration is still becoming ready.
+  Muting and teardown cancel that pending activation.
+- Allow `user.updateExplicit(current => partialOrNull)` to make a conditional
+  profile update against fresh durable fields inside the existing serialized
+  write owner. Async callbacks are supported; `null` returns the fresh profile
+  without saving. Existing object and JSON updates remain supported. Timestamp
+  setters save only their changed fields so they preserve newer profile edits.
+
 ## 0.33.6
 
 - Resume transcript bottom-follow when an accepted non-synthetic user message

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.33.6` SDK contract. Applications pin one exact npm
+This checkout defines the `0.34.1` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -85,7 +85,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.33.6 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.34.1 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 ```

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

@@ -10,3 +10,4 @@ export {
   createBrowserKokoroProvider,
   createBrowserWhisperProvider,
 } from "./browser-speech-providers.mjs";
+export { createDigitalOceanFalTTSProvider } from "./digitalocean-speech.mjs";

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

@@ -0,0 +1,468 @@
+import Is from '../dependencies/strong-type/index.js';
+
+const is = new Is(false);
+const INVOKE_URL = 'https://inference.do-ai.run/v1/async-invoke';
+const POLL_INTERVAL_MS = 1000;
+
+function speechError(message, code, cause) {
+    const error = cause === undefined
+        ? new Error(message)
+        : new Error(
+            message,
+            {cause}
+        );
+    error.code = code;
+    return error;
+}
+
+function abortedSpeech(signal) {
+    const error = speechError(
+        'The cloud speech request was cancelled.',
+        'ARCANE_AI_REQUEST_ABORTED',
+        signal?.reason
+    );
+    error.name = 'AbortError';
+    return error;
+}
+
+function assertNotAborted(signal) {
+    if (signal?.aborted) throw abortedSpeech(signal);
+}
+
+function assertIdentifier(value, label) {
+    if (!is.string(value) || !value || value.trim() !== value) {
+        throw new TypeError(`${label} must be a nonempty string without surrounding whitespace.`);
+    }
+}
+
+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;
+    const seconds = Number(value);
+    if (is.finite(seconds) && seconds >= 0) return seconds * 1000;
+    const date = Date.parse(value);
+    return is.finite(date) ? Math.max(0, date - Date.now()) : null;
+}
+
+async function requireSuccessfulResponse(response, signal, operation) {
+    assertNotAborted(signal);
+    if (response.ok) return response;
+    const detail = await response.text();
+    assertNotAborted(signal);
+    throw speechError(
+        `DigitalOcean speech ${operation} failed with HTTP ${response.status}${detail ? `: ${detail}` : '.'}`,
+        'ARCANE_AI_CLOUD_SPEECH_HTTP_ERROR'
+    );
+}
+
+/**
+ * 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 the FIFO queue; cancellation stops only this adapter's credential wait.
+ */
+export function createDigitalOceanFalTTSProvider({
+    id,
+    model,
+    getApiKey,
+    maxConcurrentRequests = 4,
+    fetch: fetchImpl = globalThis.fetch
+} = {}) {
+    assertIdentifier(id, 'DigitalOcean speech provider id');
+    assertIdentifier(model?.id, 'DigitalOcean speech model id');
+    assertIdentifier(model?.defaultVoice, 'DigitalOcean speech default voice');
+    if (!is.function(getApiKey)) {
+        throw new TypeError('DigitalOcean speech getApiKey must be a function.');
+    }
+    if (!is.function(fetchImpl)) {
+        throw new TypeError('DigitalOcean speech requires Fetch.');
+    }
+    if (!is.safeInteger(maxConcurrentRequests) || maxConcurrentRequests < 1) {
+        throw new RangeError('DigitalOcean speech maxConcurrentRequests must be a positive safe integer.');
+    }
+
+    const modelId = model.id;
+    const defaultVoice = model.defaultVoice;
+    const activeRequests = new Set();
+    const credentialWaits = new Set();
+    let state = 'unloaded';
+    let generation = 0;
+    let unloadOperation = null;
+    let disposeOperation = null;
+
+    function authority() {
+        return {
+            protocol: 'arcane-ai-model-authority/1',
+            providerId: id,
+            modelId,
+            role: 'tts',
+            localOnly: false
+        };
+    }
+
+    function readApiKey(signal) {
+        assertNotAborted(signal);
+        return new Promise(
+            function waitForCloudSpeechCredential(resolve, reject) {
+                let settled = false;
+                function finishCredentialWait() {
+                    settled = true;
+                    credentialWaits.delete(cancelCredentialWait);
+                    signal?.removeEventListener('abort', cancelCredentialWait);
+                }
+                function rejectCredential(error) {
+                    if (settled) return;
+                    finishCredentialWait();
+                    reject(error);
+                }
+                function acceptCredential(apiKey) {
+                    if (settled) return;
+                    if (!is.string(apiKey) || !apiKey.trim()) {
+                        rejectCredential(
+                            speechError(
+                                'A DigitalOcean inference access key is required for cloud speech.',
+                                'ARCANE_AI_CLOUD_SPEECH_KEY_REQUIRED'
+                            )
+                        );
+                        return;
+                    }
+                    finishCredentialWait();
+                    resolve(apiKey);
+                }
+                function cancelCredentialWait() {
+                    rejectCredential(abortedSpeech(signal));
+                }
+                credentialWaits.add(cancelCredentialWait);
+                signal?.addEventListener(
+                    'abort',
+                    cancelCredentialWait,
+                    {once: true}
+                );
+                if (signal?.aborted) {
+                    cancelCredentialWait();
+                    return;
+                }
+                try {
+                    Promise.resolve(getApiKey()).then(acceptCredential, rejectCredential);
+                } catch (error) {
+                    rejectCredential(error);
+                }
+            }
+        );
+    }
+
+    function assertSelection(selection) {
+        if (selection && (selection.providerId !== id
+            || selection.modelId !== modelId
+            || selection.localOnly === true
+            || (selection.role !== undefined && selection.role !== 'tts'))) {
+            throw speechError(
+                'The selected cloud speech model does not match this provider.',
+                'ARCANE_AI_MODEL_AUTHORITY_REQUIRED'
+            );
+        }
+    }
+
+    function assertContext(context) {
+        if (context.role !== undefined && context.role !== 'tts') {
+            throw speechError('This provider supports only TTS.', 'ARCANE_AI_INVALID_REQUEST');
+        }
+        assertSelection(context.selection);
+        assertNotAborted(context.signal);
+    }
+
+    function status() {
+        const loaded = state === 'ready';
+        return {
+            providerId: id,
+            role: 'tts',
+            modelId,
+            localOnly: false,
+            state,
+            loaded,
+            busy: activeRequests.size > 0,
+            execution: {
+                requestedDevice: 'remote',
+                selectedDevice: loaded ? 'remote' : null,
+                maxConcurrentRequests,
+                activeRequestCount: activeRequests.size
+            }
+        };
+    }
+
+    async function synthesize(payload, controller, requestGeneration) {
+        const signal = controller.signal;
+        const apiKey = await readApiKey(signal);
+        assertNotAborted(signal);
+        const headers = {Authorization: `Bearer ${apiKey}`};
+        const response = await fetchImpl(
+            INVOKE_URL,
+            {
+                method: 'POST',
+                headers: {...headers, 'Content-Type': 'application/json'},
+                body: JSON.stringify(
+                    {
+                        model_id: modelId,
+                        input: {
+                            text: payload.input,
+                            voice: payload.voice ?? defaultVoice,
+                            speed: payload.speed ?? 1
+                        }
+                    }
+                ),
+                signal
+            }
+        );
+        await requireSuccessfulResponse(response, signal, 'submission');
+        let result = await response.json();
+        assertNotAborted(signal);
+        const requestId = result?.request_id;
+        while (result?.status === 'QUEUED' || result?.status === 'IN_PROGRESS') {
+            if (!is.string(requestId) || !requestId) {
+                throw speechError(
+                    'DigitalOcean speech returned a pending job without a request_id.',
+                    'ARCANE_AI_INVALID_PROVIDER_RESULT'
+                );
+            }
+            await waitForStatus(POLL_INTERVAL_MS, signal);
+            let statusResponse;
+            do {
+                statusResponse = await fetchImpl(
+                    `${INVOKE_URL}/${encodeURIComponent(requestId)}`,
+                    {method: 'GET', headers, signal}
+                );
+                assertNotAborted(signal);
+                const retryDelay = statusResponse.status === 429
+                    ? retryAfterDelay(statusResponse)
+                    : null;
+                if (retryDelay === null) break;
+                // Only status reads may be retried; submitting twice can create two paid jobs.
+                await statusResponse.text();
+                await waitForStatus(retryDelay, signal);
+            } while (true);
+            await requireSuccessfulResponse(statusResponse, signal, 'status read');
+            result = await statusResponse.json();
+            assertNotAborted(signal);
+        }
+        if (result?.status === 'FAILED') {
+            throw speechError(
+                `DigitalOcean speech generation failed: ${JSON.stringify(result)}`,
+                'ARCANE_AI_CLOUD_SPEECH_GENERATION_FAILED'
+            );
+        }
+        if (result?.status !== 'COMPLETED' || !is.string(result.output?.audio?.url)
+            || !result.output.audio.url) {
+            throw speechError(
+                `DigitalOcean speech returned an unsupported result: ${JSON.stringify(result)}`,
+                'ARCANE_AI_INVALID_PROVIDER_RESULT'
+            );
+        }
+        assertNotAborted(signal);
+        // The returned media URL has its own delivery authority; never forward the inference key.
+        const audioResponse = await fetchImpl(
+            result.output.audio.url,
+            {signal}
+        );
+        await requireSuccessfulResponse(audioResponse, signal, 'audio download');
+        const audio = await audioResponse.blob();
+        assertNotAborted(signal);
+        if (generation !== requestGeneration || state !== 'ready') {
+            throw speechError(
+                'The cloud speech result was superseded by a provider transition.',
+                'ARCANE_AI_OPERATION_SUPERSEDED'
+            );
+        }
+        return audio;
+    }
+
+    const provider = {
+        protocol: 'arcane-ai-provider/2',
+        role: 'tts',
+        id,
+        localOnly: false,
+        maxConcurrentRequests,
+
+        catalog() {
+            return [
+                {
+                    id: modelId,
+                    providerId: id,
+                    role: 'tts',
+                    localOnly: false,
+                    defaultVoice,
+                    speech: {responseFormats: ['provider-native'], defaultResponseFormat: 'provider-native'}
+                }
+            ];
+        },
+
+        async inspect(selection, context = {}) {
+            assertContext(context);
+            if (state === 'disposed' || disposeOperation) {
+                return {
+                    available: false,
+                    code: 'ARCANE_AI_PROVIDER_DISPOSED',
+                    message: 'The cloud speech provider is disposed.'
+                };
+            }
+            assertSelection(selection);
+            const inspectionGeneration = generation;
+            await readApiKey(context.signal);
+            assertNotAborted(context.signal);
+            if (generation !== inspectionGeneration) {
+                throw speechError('Cloud speech inspection was superseded.', 'ARCANE_AI_OPERATION_SUPERSEDED');
+            }
+            return {available: true, authority: authority()};
+        },
+
+        status,
+
+        async load(context = {}) {
+            assertContext(context);
+            if (state === 'disposed' || disposeOperation) {
+                throw speechError('The cloud speech provider is disposed.', 'ARCANE_AI_PROVIDER_DISPOSED');
+            }
+            if (unloadOperation) {
+                throw speechError('The cloud speech provider is unloading.', 'ARCANE_AI_OPERATION_SUPERSEDED');
+            }
+            const loadGeneration = generation;
+            if (state !== 'ready') state = 'loading';
+            try {
+                await readApiKey(context.signal);
+                assertNotAborted(context.signal);
+                if (generation !== loadGeneration) {
+                    throw speechError('Cloud speech activation was superseded.', 'ARCANE_AI_OPERATION_SUPERSEDED');
+                }
+            } catch (error) {
+                if (generation === loadGeneration && state === 'loading') state = 'unloaded';
+                throw error;
+            }
+            state = 'ready';
+            return status();
+        },
+
+        async request(context = {}) {
+            assertContext(context);
+            if (context.role !== 'tts' || context.operation !== 'synthesize') {
+                throw speechError('Cloud speech supports only TTS synthesis.', 'ARCANE_AI_INVALID_REQUEST');
+            }
+            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.');
+            }
+            if (payload.model !== undefined && payload.model !== modelId) {
+                throw speechError('The requested cloud speech model differs from the selection.', 'ARCANE_AI_MODEL_AUTHORITY_REQUIRED');
+            }
+            if (payload.voice !== undefined) assertIdentifier(payload.voice, 'Cloud speech voice');
+            if (payload.responseFormat !== undefined && payload.responseFormat !== 'provider-native') {
+                throw speechError('Cloud speech returns the provider-native audio format.', 'ARCANE_AI_UNSUPPORTED_RESPONSE_FORMAT');
+            }
+            const speed = payload.speed ?? 1;
+            if (!is.finite(speed) || speed < 0.7 || speed > 1.2) {
+                const error = new RangeError('Cloud speech speed must be from 0.7 through 1.2.');
+                error.code = 'ARCANE_AI_TTS_SPEED_INVALID';
+                throw error;
+            }
+
+            const controller = new AbortController();
+            function cancelCloudSpeechRequest() {
+                controller.abort(context.signal.reason);
+            }
+            context.signal?.addEventListener(
+                'abort',
+                cancelCloudSpeechRequest,
+                {once: true}
+            );
+            if (context.signal?.aborted) cancelCloudSpeechRequest();
+            const request = {controller, promise: null};
+            activeRequests.add(request);
+            request.promise = synthesize(payload, controller, generation);
+            try {
+                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);
+            }
+        },
+
+        unload(context = {}) {
+            assertContext(context);
+            if (state === 'disposed') {
+                return Promise.resolve(
+                    status()
+                );
+            }
+            if (unloadOperation) return unloadOperation;
+            state = 'unloading';
+            generation += 1;
+            for (const cancelCredentialWait of [...credentialWaits]) cancelCredentialWait();
+            const requests = [...activeRequests];
+            for (const request of requests) request.controller.abort('Cloud speech provider unloaded.');
+            unloadOperation = Promise.allSettled(
+                requests.map(
+                    function pendingCloudSpeechRequest(request) {
+                        return request.promise;
+                    }
+                )
+            ).then(
+                function finishCloudSpeechUnload() {
+                    state = 'unloaded';
+                    unloadOperation = null;
+                    return status();
+                }
+            );
+            return unloadOperation;
+        },
+
+        dispose(context = {}) {
+            assertContext(context);
+            if (state === 'disposed') {
+                return Promise.resolve(
+                    status()
+                );
+            }
+            if (disposeOperation) return disposeOperation;
+            disposeOperation = provider.unload(context).then(
+                function finishCloudSpeechDispose() {
+                    state = 'disposed';
+                    disposeOperation = null;
+                    return status();
+                }
+            );
+            return disposeOperation;
+        }
+    };
+    return provider;
+}

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

@@ -1,11 +1,91 @@
 # Browser speech providers
 
-`arcane-os/ai/browser-speech` is the browser-only SDK boundary for
-caller-selected Whisper speech-to-text and Kokoro text-to-speech runtimes. It
+`arcane-os/ai/browser-speech` supplies caller-selected Whisper speech-to-text,
+Kokoro text-to-speech, and DigitalOcean FAL text-to-speech providers. Its local path
 provides artifact storage, live module routing, role Workers, provider/2
 adapters, bounded parallel TTS synthesis, audio normalization, cancellation,
 and cleanup.
 
+## DigitalOcean FAL text-to-speech
+
+Use the same AI speech queue with an explicitly selected remote provider.
+The application supplies its current DigitalOcean inference key through a
+function returning a string or promise; never place that key in source, logs, or model records.
+This example receives an existing `ai` and application-owned key reader:
+
+```javascript
+import {createDigitalOceanFalTTSProvider} from 'arcane-os/ai/browser-speech';
+
+async function selectCloudVoice(ai, getApiKey) {
+  const provider = createDigitalOceanFalTTSProvider({
+    id: 'my-digitalocean-voice',
+    model: {
+      id: 'fal-ai/elevenlabs/tts/multilingual-v2',
+      defaultVoice: 'Rachel'
+    },
+    getApiKey,
+    maxConcurrentRequests: 4
+  });
+  await ai.configureSpeechProvider('tts', provider, {
+    modelId: provider.catalog()[0].id
+  });
+  return provider;
+}
+```
+
+Construction and configuration make no network request. Explicit
+`ai.setSpeechMuted(false)` awaits the key reader, checks credential presence, and activates
+the adapter; its ready state does not prove remote credential validity.
+Only synthesis submits text. Keep local STT configured independently, before
+or after this TTS selection. Existing shared Chat/Speech controls own user
+mute/unmute intent; do not reapply a saved unmute over a later manual mute.
+An asynchronous key reader may await the application's already-running key
+refresh at this activation boundary; it does not delay provider configuration
+or page rendering. Cancellation releases this request's wait without cancelling
+the application's shared refresh, and no late key result starts synthesis.
+
+Once explicit activation is requested, feed each arriving text chunk immediately through
+`ai.streamTTS(chunk)` and observe each promise without awaiting it ahead of
+the next chunk. Pending activation retains these segments in the existing queue
+until the selected provider is ready; text does not initiate activation itself.
+`ai.finishTTS()` submits the final remainder. The existing
+punctuation segmentation, concurrent provider queue, and original-order
+playback remain the only owners. Use
+`ai.configureTTSSegmentation({punctuation:'any',wordCadence:null})` when each
+punctuation boundary should submit promptly. This is incremental playback of
+completed synthesis jobs, not a live audio stream from DigitalOcean.
+
+The transport submits `POST https://inference.do-ai.run/v1/async-invoke`, then
+reads that job until its completed `output.audio.url` is available. Each
+segment is submitted once; only status reads retry a `429` with `Retry-After`.
+The audio download never receives the inference Authorization header.
+The selected multilingual-v2 service supports speed `0.7` through `1.2`;
+unsupported speeds reject rather than being silently clamped. Complete
+input remains intact except for the existing explicitly owned speech-only
+formatting cleanup described below. A cloud failure never selects local TTS.
+
+`ai.stopAudio()` cancels the current local request/poll/download/playback
+lifetime. Mute additionally unloads TTS. DigitalOcean exposes no documented
+job cancellation operation through this contract: a submitted remote job may
+continue after local cancellation. Browser use also depends on the inference
+and returned media endpoints allowing the requesting origin.
+
+Release this exact configured provider with:
+
+```javascript
+// Keep the provider returned by selectCloudVoice(ai, getApiKey).
+await ai.configureSpeechProvider('tts', null, {expectedProvider: provider});
+```
+
+The identity is rechecked inside the SDK's serialized configuration operation,
+so a later selected provider remains untouched. Returning to local TTS uses
+the normal TTS-only `configureBrowserSpeech()` configuration. Neither action
+unloads STT or changes its stored artifacts.
+
+Transport references: [DigitalOcean asynchronous inference](https://docs.digitalocean.com/reference/api/reference/serverless-inference/#inference_create_async_invoke),
+[DigitalOcean FAL guide](https://docs.digitalocean.com/products/inference/how-to/use-fal-models/),
+and [multilingual-v2 model schema](https://fal.ai/models/fal-ai/elevenlabs/tts/multilingual-v2/api).
+
 ## Quick start: say one sentence
 
 Use this in a browser application served by `arcane dev`, where the generated
@@ -844,8 +924,8 @@ records; this contract does not freeze them or shorten their content.
 | --- | --- | --- |
 | Browser | Shipped | Requires Workers, Fetch, Blob/File, object URLs, DBOPFS/OPFS, and Web Locks. Blob/File STT requests also require the browser audio decoder. |
 | Native WebView | Conditional | Available when the WebView exposes the browser APIs above. It does not invoke Core speech. |
-| Node | Importable, execution unavailable | The ESM subpath imports, but the SDK supplies no Node speech storage, Worker, or audio-decoder host. |
-| Cloud | Not offered | The SDK's built-in speech profile is device-only: Whisper owns STT and Kokoro owns TTS. |
+| Node | Remote adapter available; local execution unavailable | DigitalOcean FAL uses Fetch and Blob. The local providers have no SDK Node speech-storage, Worker, or audio-decoder host. |
+| Remote TTS | Explicitly selected | DigitalOcean FAL uses standard Fetch and Blob with an application-owned key; no Worker, OPFS, or local model is needed for this adapter. |
 
 STT and TTS own independent provider lifecycles. A failure or cancellation in
 one role does not disable the other role or authorize a fallback provider.
@@ -860,7 +940,8 @@ import {
   createBrowserSpeechArtifactGraph,
   createBrowserSpeechAuthority,
   createBrowserWhisperProvider,
-  createDbopfsSpeechArtifactStore
+  createDbopfsSpeechArtifactStore,
+  createDigitalOceanFalTTSProvider
 } from 'arcane-os/ai/browser-speech';
 ```
 

package/docs/reference/ai/twin-cloud.md

@@ -211,6 +211,38 @@ controller's `abort()` when the operation is cancelled or its page detaches.
 `streamRequest()` is the corresponding object-form streaming API. See the
 [AI module reference](../runtime-modules.md#aijs) for its complete options.
 
+## Use a model for one browser request
+
+Both object-form methods accept `model` for that request. For example, an
+application can use 20B for document search while retaining its configured
+120B conversation model:
+
+```javascript
+const result = await ai.fetchRequest({
+  model: 'openai-gpt-oss-20b',
+  messages: searchMessages
+});
+
+await ai.streamRequest({
+  model: 'openai-gpt-oss-20b',
+  messages: summaryMessages,
+  onChunk: displaySummaryChunk
+});
+```
+
+`searchMessages`, `summaryMessages`, and `displaySummaryChunk` are supplied by
+the application. Their content and callbacks keep their ordinary contracts.
+The exact model goes into each TWiN request payload without changing `ai.model`
+or selecting another provider. Concurrent calls can choose different models;
+later calls that omit `model` (or pass `undefined`) use the configured model.
+Retries keep the same request model. Provider-returned model metadata remains
+authoritative; an assembled stream completion uses the request model only when
+the response omits it.
+
+The browser API forwards an explicitly supplied model to registered providers,
+whose own request contract determines its meaning. This does not switch or
+activate the loaded model of a browser-WASM provider.
+
 ## Migrate saved preference tuples before using them
 
 The six tuple slots consumed by `ai.setAI(...tuple)` are: