arcane-os 0.5.7 → 0.5.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.5.8
+
+- Added provider-neutral `reasoningEffort` to `AI.fetchRequest()` and
+  `AI.streamRequest()`, accepting `none`, `low`, `medium`, `high`, or
+  `max`. TWiN Cloud forwards an explicit value as `reasoning_effort`, omits
+  the field when unspecified, and preserves explicit
+  `openai-gpt-oss-120b` or `openai-gpt-oss-20b` model selection with the
+  existing streaming and structural-tool behavior.
+
 ## 0.5.7
 
 - Added `PersistentAIChatSession.open()` for model-authored conversation

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.5.7` SDK contract. Applications pin one exact npm
+This checkout defines the `0.5.8` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -93,6 +93,13 @@ on device: Whisper (`LOCAL_SPEACH` / `whisper-small`) owns transcription and
 Kokoro (`LOCAL_SPEACH` / `kokoro`) owns speech synthesis. Neither audio route
 uses the TWiN key, and no OpenAI audio key is required.
 
+`fetchRequest()` and `streamRequest()` accept the provider-neutral
+`reasoningEffort` option with `none`, `low`, `medium`, `high`, or `max`. TWiN
+Cloud maps it to DigitalOcean Serverless Inference `reasoning_effort`; omitting
+it preserves the provider default. TWiN Cloud defaults to
+`openai-gpt-oss-120b`, and applications may explicitly select
+`openai-gpt-oss-20b` without changing streaming or structural-tool behavior.
+
 ## Browser-local AI
 
 `arcane-os/ai/browser-wasm` provides the shared Wllama LLM provider. The app
@@ -192,7 +199,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.5.7 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.5.8 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run check
@@ -203,7 +210,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.5.7
+npm install --save-dev --save-exact arcane-os@0.5.8
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -219,7 +226,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.5.7` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.5.8` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -240,7 +247,7 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.7.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.8.tgz
 npm run check
 npm ci
 ```
@@ -250,7 +257,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.5.7` registry package and
+the local declaration with the exact `arcane-os@0.5.8` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -388,7 +395,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.7` exposes one browser target and five explicitly paired
+Version `0.5.8` exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The

package/package.json

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

package/runtime/arcane/modules/AI.js

@@ -30,6 +30,7 @@ const TTS_ANY_PUNCTUATION_AT_END=/(?<!\p{P})(?:(?<![\p{L}\p{N}])\p{P}+|\p{P}+(?!
 credentials='omit';
 
 const LEGACY_AI_SERVICES=new Set(['OPENAI','OLLAMA','LOCAL_SPEACH']);
+const AI_REASONING_EFFORTS=new Set(['none','low','medium','high','max']);
 export const AI_READY_EVENT='ai-ready';
 const AI_TTS_FAILURE_EVENT='ai-tts-failure';
 export const AI_INITIALIZATION_ERROR_CODES=completeValue({
@@ -128,6 +129,20 @@ function normalizeAIRequestAbort(error){
     return normalized;
 }
 
+function normalizeAIReasoningEffort(value){
+    if(value===undefined||value===null||value===''){
+        return '';
+    }
+    if(typeof value!=='string'||!AI_REASONING_EFFORTS.has(value)){
+        const error=new TypeError(
+            'AI reasoningEffort must be none, low, medium, high, or max.'
+        );
+        error.code='AI_REASONING_EFFORT_INVALID';
+        throw error;
+    }
+    return value;
+}
+
 function legacyAIProviderError(message,code,cause){
     const error=cause===undefined
         ?new Error(message)
@@ -2000,7 +2015,7 @@ class AI {
                 ||model;
         }
         if(service==='OPENAI'){
-            return this.#models.OPENAI;
+            return model==='OPENAI'?this.#models.OPENAI:model;
         }
         return model;
     }
@@ -4126,7 +4141,8 @@ class AI {
             parallelToolCalls,
             payload.id??Date.now(),
             function ignoreLegacyLLMProviderRequest(){},
-            signal
+            signal,
+            payload.reasoningEffort
         );
     }
 
@@ -4153,7 +4169,9 @@ class AI {
             payload.structuredOutput??false,
             false,
             true,
-            emitLegacyLLMStreamData
+            emitLegacyLLMStreamData,
+            function ignoreLegacyLLMStreamResult(){},
+            payload.reasoningEffort
         );
     }
 
@@ -4323,9 +4341,13 @@ class AI {
         minP,
         seed,
         stop,
-        templateOptions
+        templateOptions,
+        reasoningEffort
     }={}){
         validateAIStructuralRequest(messages,tools,parallelToolCalls);
+        const normalizedReasoningEffort=normalizeAIReasoningEffort(
+            reasoningEffort===undefined?this.reasoningEffort:reasoningEffort
+        );
         if(localOnly!==true&&localOnly!==false){
             throw new TypeError('AI localOnly must be a boolean.');
         }
@@ -4355,7 +4377,10 @@ class AI {
                 ...(minP!==undefined?{minP}:{}),
                 ...(seed!==undefined?{seed}:{}),
                 ...(stop!==undefined?{stop}:{}),
-                ...(templateOptions!==undefined?{templateOptions}:{})
+                ...(templateOptions!==undefined?{templateOptions}:{}),
+                ...(normalizedReasoningEffort
+                    ?{reasoningEffort:normalizedReasoningEffort}
+                    :{})
             };
             const displayId=`M-${id}`;
             let handle=null;
@@ -4457,7 +4482,8 @@ class AI {
                 false,
                 true,
                 onDataChunk,
-                onDataResult
+                onDataResult,
+                normalizedReasoningEffort
             );
             const structuralToolCalls=normalizeAICompletionToolCalls(
                 completion
@@ -4563,7 +4589,8 @@ class AI {
         finishSpeech=true,
         returnCompletion=false,
         dataChunkHandler=function ignoreLegacyStreamDataChunk(){},
-        dataResultHandler=function ignoreLegacyStreamDataResult(){}
+        dataResultHandler=function ignoreLegacyStreamDataResult(){},
+        reasoningEffort
     ){
         let speechTurnCompleted=false;
 
@@ -4583,6 +4610,9 @@ class AI {
                 structuredOutput
             );
 
+        const normalizedReasoningEffort=normalizeAIReasoningEffort(
+            reasoningEffort===undefined?this.reasoningEffort:reasoningEffort
+        );
         const request={
             model:this.model,
             messages:messages, 
@@ -4603,8 +4633,11 @@ class AI {
             }
         }
 
-        if(this.llmService==='OLLAMA'&&this.reasoningEffort){
-            request.reasoning_effort=this.reasoningEffort;
+        if(
+            normalizedReasoningEffort
+            &&(this.llmService==='OPENAI'||this.llmService==='OLLAMA')
+        ){
+            request.reasoning_effort=normalizedReasoningEffort;
         }
 
         let isThinking=true;
@@ -4631,7 +4664,9 @@ class AI {
                 model:this.model,
                 messages:ollamaMessages,
                 stream:true,
-                ...(this.reasoningEffort?{think:this.reasoningEffort}:{}),
+                ...(normalizedReasoningEffort
+                    ?{think:normalizedReasoningEffort}
+                    :{}),
                 ...(structuredOutputFormat?{format:structuredOutputFormat}:{}),
                 ...(ollamaTools.length?{tools:ollamaTools}:{})
             };
@@ -5272,9 +5307,13 @@ class AI {
         minP,
         seed,
         stop,
-        templateOptions
+        templateOptions,
+        reasoningEffort
     }={}){
         validateAIStructuralRequest(messages,tools,parallelToolCalls);
+        const normalizedReasoningEffort=normalizeAIReasoningEffort(
+            reasoningEffort===undefined?this.reasoningEffort:reasoningEffort
+        );
         if(localOnly!==true&&localOnly!==false){
             throw new TypeError('AI localOnly must be a boolean.');
         }
@@ -5306,7 +5345,10 @@ class AI {
                 ...(minP!==undefined?{minP}:{}),
                 ...(seed!==undefined?{seed}:{}),
                 ...(stop!==undefined?{stop}:{}),
-                ...(templateOptions!==undefined?{templateOptions}:{})
+                ...(templateOptions!==undefined?{templateOptions}:{}),
+                ...(normalizedReasoningEffort
+                    ?{reasoningEffort:normalizedReasoningEffort}
+                    :{})
             };
             await this.#reportRequest(onRequest,request,id);
             if(signal?.aborted){
@@ -5332,7 +5374,7 @@ class AI {
             return response;
         }
 
-        return this.fetch(
+        return this.#fetchLegacy(
             messages,
             onResponse,
             structuredOutput,
@@ -5341,7 +5383,8 @@ class AI {
             parallelToolCalls,
             id,
             onRequest,
-            signal
+            signal,
+            normalizedReasoningEffort
         );
     }
 
@@ -5354,7 +5397,7 @@ class AI {
         parallel_tool_calls,
         id=Date.now(),
         requestHandler=function ignoreFetchRequest(){},
-        signal=null,
+        signal=null
     ){
         if(this.#shouldUseProviderRuntime('llm',this.llmService,false)){
             return this.fetchRequest({
@@ -5394,6 +5437,7 @@ class AI {
         id=Date.now(),
         requestHandler=function ignoreFetchRequest(){},
         signal=null,
+        reasoningEffort
     ){
         validateAIStructuralRequest(messages,tools,parallel_tool_calls);
         this.#assertServiceConfigured(this.llmService);
@@ -5408,6 +5452,9 @@ class AI {
         }
         const structuredOutputFormat=this.#structuredOutputFormat(structuredOutput);
 
+        const normalizedReasoningEffort=normalizeAIReasoningEffort(
+            reasoningEffort===undefined?this.reasoningEffort:reasoningEffort
+        );
         const request={
             model:this.model,
             messages:messages, 
@@ -5428,8 +5475,11 @@ class AI {
             }
         }
 
-        if(this.llmService==='OLLAMA'&&this.reasoningEffort){
-            request.reasoning_effort=this.reasoningEffort;
+        if(
+            normalizedReasoningEffort
+            &&(this.llmService==='OPENAI'||this.llmService==='OLLAMA')
+        ){
+            request.reasoning_effort=normalizedReasoningEffort;
         }
 
         const nativeOllama=this.#nativeOllama();
@@ -5448,7 +5498,9 @@ class AI {
                 model:this.model,
                 messages:ollamaMessages,
                 stream:false,
-                ...(this.reasoningEffort?{think:this.reasoningEffort}:{}),
+                ...(normalizedReasoningEffort
+                    ?{think:normalizedReasoningEffort}
+                    :{}),
                 ...(structuredOutputFormat?{format:structuredOutputFormat}:{}),
                 ...(ollamaTools.length?{tools:ollamaTools}:{})
             };