arcane-os 0.34.0 → 0.34.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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`

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.34.0` 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.34.0 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/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:

package/docs/reference/runtime-modules.md

@@ -164,6 +164,21 @@ entry points. `streamMessage(...)` and `streamRequest(options)` deliver
 incremental responses. The positional and object forms share the existing
 provider implementations; neither form is a retired compatibility API.
 
+`fetchRequest({model,...})` and `streamRequest({model,...})` accept an optional
+request-local model. On the built-in TWiN Cloud route, its exact value becomes
+the outbound `model` field; native Ollama receives the same request-local value.
+Omitting it or passing `undefined` preserves the configured model. Each built-in
+request captures its model before asynchronous callbacks, so concurrent requests
+may use different models without assigning `ai.model`, changing provider
+selection, or loading/unloading another model. Request observers and retries
+receive that request's model. Stream/native completion metadata uses it only
+when the provider omits its own `model` field.
+
+Registered providers receive a supplied `model` unchanged in their request
+payload; an omitted value remains absent. The provider owns interpretation.
+This option does not switch a loaded browser-WASM model or its lifecycle:
+explicit provider/model selection and activation remain necessary there.
+
 Built-in cloud chat decodes an HTTP error body once as JSON or text and rejects
 with that complete value unchanged. It does not reconstruct an Error, replace
 the message, or add `providerMessage`, `status`, or an SDK failure code to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.34.0",
+  "version": "0.34.1",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -86,7 +86,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/twin-cloud.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/twin-cloud.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/runtime/arcane/modules/AI.js

@@ -4443,7 +4443,8 @@ class AI {
             function ignoreBuiltInLLMProviderRequest(){},
             signal,
             payload.reasoningEffort,
-            onRetry
+            onRetry,
+            payload.model
         );
     }
 
@@ -4474,7 +4475,8 @@ class AI {
             function ignoreBuiltInLLMStreamResult(){},
             payload.reasoningEffort,
             observeToolText,
-            onRetry
+            onRetry,
+            payload.model
         );
     }
 
@@ -4555,7 +4557,7 @@ class AI {
         });
     }
 
-    #openAICompatibleOllamaResponse(response={},id=Date.now()){
+    #openAICompatibleOllamaResponse(response={},id=Date.now(),model=this.model){
         const responseRecord=isPlainAIRecord(response)?response:{};
         const message=isPlainAIRecord(responseRecord.message)
             ?responseRecord.message
@@ -4597,7 +4599,7 @@ class AI {
                 :Math.floor(Date.now()/1000),
             model:Object.hasOwn(responseRecord,'model')
                 ?responseRecord.model
-                :this.model,
+                :model,
             choices:[
                 {
                     index:0,
@@ -4620,6 +4622,7 @@ class AI {
 
     async streamRequest({
         messages=[],
+        model,
         structuredOutput=false,
         localOnly=false,
         onChunk=function ignoreStreamChunk(){},
@@ -4676,6 +4679,7 @@ class AI {
         if(this.#shouldUseProviderRuntime('llm',this.llmService,localOnly)){
             const request={
                 messages,
+                ...(model!==undefined?{model}:{}),
                 structuredOutput,
                 tools,
                 toolChoice,
@@ -4801,7 +4805,8 @@ class AI {
                 onDataResult,
                 normalizedReasoningEffort,
                 observeToolText,
-                onRetry
+                onRetry,
+                model
             );
             const structuralToolCalls=normalizeAICompletionToolCalls(
                 completion
@@ -4910,7 +4915,8 @@ class AI {
         dataResultHandler=function ignoreBuiltInStreamDataResult(){},
         reasoningEffort,
         observeToolText=null,
-        onRetry = null
+        onRetry = null,
+        model=this.model
     ){
         let speechTurnCompleted=false;
 
@@ -4934,7 +4940,7 @@ class AI {
             reasoningEffort===undefined?this.reasoningEffort:reasoningEffort
         );
         const request={
-            model:this.model,
+            model,
             messages:messages, 
             stream:true
         }
@@ -4981,7 +4987,7 @@ class AI {
             const ollamaMessages=this.#ollamaMessages(messages,tool_choice);
             const adaptNativeToolCalls=value=>this.#openAICompatibleOllamaToolCalls(value,id);
             const ollamaRequest={
-                model:this.model,
+                model,
                 messages:ollamaMessages,
                 stream:true,
                 ...(normalizedReasoningEffort
@@ -5091,7 +5097,8 @@ class AI {
                             :nativeContent
                     }
                 },
-                id
+                id,
+                model
             );
             const structuralToolCalls=normalizeAICompletionToolCalls(
                 nativeCompletion
@@ -5583,7 +5590,7 @@ class AI {
             created:Object.hasOwn(streamMetadata,'created')
                 ?streamMetadata.created
                 :Math.floor(Date.now()/1000),
-            model:Object.hasOwn(streamMetadata,'model')?streamMetadata.model:this.model,
+            model:Object.hasOwn(streamMetadata,'model')?streamMetadata.model:model,
             choices:completionChoices
         };
         const terminalToolCalls=normalizeAICompletionToolCalls(completion);
@@ -5628,6 +5635,7 @@ class AI {
 
     async fetchRequest({
         messages=[],
+        model,
         structuredOutput=false,
         localOnly=false,
         tools=[],
@@ -5670,6 +5678,7 @@ class AI {
             }
             const request={
                 messages,
+                ...(model!==undefined?{model}:{}),
                 structuredOutput,
                 tools,
                 toolChoice,
@@ -5726,7 +5735,8 @@ class AI {
             onRequest,
             signal,
             normalizedReasoningEffort,
-            onRetry
+            onRetry,
+            model
         );
     }
 
@@ -5780,7 +5790,8 @@ class AI {
         requestHandler=function ignoreFetchRequest(){},
         signal=null,
         reasoningEffort,
-        onRetry = null
+        onRetry = null,
+        model=this.model
     ){
         validateAIStructuralRequest(messages,tools,parallel_tool_calls);
         this.#assertServiceConfigured(this.llmService);
@@ -5799,7 +5810,7 @@ class AI {
             reasoningEffort===undefined?this.reasoningEffort:reasoningEffort
         );
         const request={
-            model:this.model,
+            model,
             messages:messages, 
             stream:false
         }
@@ -5838,7 +5849,7 @@ class AI {
             const ollamaTools=this.#ollamaTools(tools,tool_choice);
             const ollamaMessages=this.#ollamaMessages(messages,tool_choice);
             const nativeRequest={
-                model:this.model,
+                model,
                 messages:ollamaMessages,
                 stream:false,
                 ...(normalizedReasoningEffort
@@ -5869,7 +5880,8 @@ class AI {
             }
             const responseJSON=this.#openAICompatibleOllamaResponse(
                 nativeResponse,
-                id
+                id,
+                model
             );
             this.#assertRequiredOllamaToolCall(
                 normalizeAICompletionToolCalls(responseJSON),