arcane-os 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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
+  openings. Its application-authored bootstrap remains transient, while the
+  complete nonblank assistant response is committed atomically as durable
+  assistant-only chat history and survives maintenance and reload.
+
 ## 0.5.6
 
 - Sanitized newly persisted chat history into complete human-readable user,

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.6` 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
@@ -176,8 +183,14 @@ The SDK runtime also owns `DBOPFSDocumentLibrary`,
 schema-driven and explicit; chat never searches a corpus unless the app wires
 that library into the request context builder. Persistent chat automatically
 maintains recurring model context and `ChatEntity` history/memory. A turn may
-set `persist:false` to remain in the current session context without entering
-durable chat or memory. `createArcaneAI(...).createChatSession(options)` wires
+set `persist:false` to participate in one request and response only; after that
+operation settles, neither side remains in subsequent model context, the
+retained transcript, durable chat, memory, or DBOPFS.
+For an automatic model-authored opening, call
+`session.open({message:{content:bootstrap,persist:false}})`: the bootstrap is
+request-only, while the complete nonblank assistant response becomes the first
+durable conversation row without a fabricated user turn.
+`createArcaneAI(...).createChatSession(options)` wires
 that session to the same selected LLM controller, creates its `ChatEntity`, and
 uses the same controller for automatic memory extraction.
 
@@ -186,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.6 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
@@ -197,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.6
+npm install --save-dev --save-exact arcane-os@0.5.8
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -213,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.6` 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`,
@@ -234,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.6.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.8.tgz
 npm run check
 npm ci
 ```
@@ -244,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.6` 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
@@ -382,7 +395,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.6` 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.6",
+  "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/entities/Chat.js

@@ -1,7 +1,7 @@
 import Is from '../../node_modules/strong-type/index.js';
 import '../modules/DBOPFS.js';
 import '../modules/AI.js';
-import {hasUserEntry} from '../modules/ChatRecords.js';
+import {hasConversationEntry,hasUserEntry} from '../modules/ChatRecords.js';
 import {normalizeMemoryContent} from '../modules/MemoryRecords.js';
 
 const is = new Is(false);
@@ -925,7 +925,7 @@ ${JSON.stringify(transcript)}`
      * @returns {Promise<*>}
      */
     async save(){
-        if(!hasUserEntry(this.#durableMessages())){
+        if(!hasConversationEntry(this.#durableMessages())){
             this.#saved=false;
             return false;
         }
@@ -1073,7 +1073,7 @@ ${JSON.stringify(transcript)}`
             return;
         }
 
-        if(!hasUserEntry(this.#durableMessages())){
+        if(!hasConversationEntry(this.#durableMessages())){
             return false;
         }
 

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}:{})
             };

package/runtime/arcane/modules/ChatRecords.js

@@ -8,6 +8,20 @@ function hasUserEntry(chat=[]){
     );
 }
 
+function hasConversationEntry(chat=[]){
+    const messages=Array.isArray(chat)
+        ?chat
+        :chat?.messages||[];
+
+    return hasUserEntry(messages)||messages.some(
+        message=>
+            message?.role==='assistant'
+            &&typeof message.content==='string'
+            &&Boolean(message.content.trim())
+    );
+}
+
 export {
+    hasConversationEntry,
     hasUserEntry
 };

package/runtime/arcane/modules/ConfiguredAIChatSession.js

@@ -584,6 +584,83 @@ export default class ConfiguredAIChatSession{
         return context;
     }
 
+    /** Prepares one transient bootstrap request whose assistant response alone may be committed. */
+    async prepareOpening(input,options={}){
+        if(!isPlainRecord(options)) throw new TypeError('Chat opening options must be a plain object.');
+        const unsupported=Object.keys(options).find(key=>!['request','signal'].includes(key));
+        if(unsupported) throw new TypeError(`Unsupported chat opening option: ${unsupported}`);
+        if(!signalLike(options.signal)) throw new TypeError('signal must be an AbortSignal.');
+        if(options.signal?.aborted) throw abortError();
+        const turnRequest=normalizeRequestOptions(options.request,'request');
+        const [normalizedInputMessage]=normalizeInputMessages(input);
+        if(normalizedInputMessage.role!=='user'){
+            throw new TypeError('The chat opening bootstrap must be a user message.');
+        }
+        const inputMessage=message('user',normalizedInputMessage.content);
+        if(this.#pending){
+            throw coded(new Error('A chat request is already active for this session.'),'AI_CHAT_BUSY');
+        }
+        if(this.#conversation.length){
+            throw coded(
+                new Error('The chat already contains a retained conversation turn.'),
+                'AI_CHAT_OPENING_EXISTS',
+            );
+        }
+        this.#pending=true;
+        try{
+            const context=await this.#contextFor(inputMessage.content,options.signal);
+            if(options.signal?.aborted) throw abortError();
+            const transientContext=context
+                ?message('user',context)
+                :null;
+            const requestMessages=completeHistory(
+                this.#systemPrompt,
+                [...(transientContext?[transientContext]:[]),inputMessage],
+            );
+            let providerResponse;
+            try{
+                providerResponse=await this.#chat({
+                    ...this.#request,
+                    ...turnRequest,
+                    ...(options.signal?{signal:options.signal}:{}),
+                    messages:requestMessages.map(publicMessage),
+                });
+            }catch(error){
+                if(options.signal?.aborted) throw abortError();
+                throw error;
+            }
+            const response=normalizeResponse(providerResponse);
+            if(options.signal?.aborted) throw abortError();
+            if(response.message.tool_calls?.length||!response.message.content.trim()){
+                throw coded(
+                    new TypeError('The model-authored chat opening must contain visible assistant text.'),
+                    'AI_CHAT_INVALID_OPENING_RESPONSE',
+                );
+            }
+            const openingMessage=message('assistant',response.message.content);
+            let settled=false;
+            return {
+                response,
+                commit:()=>{
+                    if(settled) throw coded(new Error('The prepared chat opening is already settled.'),'AI_CHAT_TRANSACTION_SETTLED');
+                    this.#conversation=[openingMessage];
+                    settled=true;
+                    this.#pending=false;
+                    return response;
+                },
+                rollback:()=>{
+                    if(settled) return false;
+                    settled=true;
+                    this.#pending=false;
+                    return true;
+                },
+            };
+        }catch(error){
+            this.#pending=false;
+            throw error;
+        }
+    }
+
     async prepare(input,options={}){
         if(!isPlainRecord(options)) throw new TypeError('Chat send options must be a plain object.');
         const unsupported=Object.keys(options).find(key=>!['request','signal'].includes(key));

package/runtime/arcane/modules/DataMaintenance.js

@@ -1,5 +1,5 @@
 import './DBOPFS.js';
-import {hasUserEntry} from './ChatRecords.js';
+import {hasConversationEntry,hasUserEntry} from './ChatRecords.js';
 import {hasMemoryContent} from './MemoryRecords.js';
 import {arcaneEvents} from 'arcane-os/event-manager';
 
@@ -16,7 +16,7 @@ async function clearEmptyChatsAndMemories(){
             true
         );
 
-        if(!hasUserEntry(chat)){
+        if(!hasConversationEntry(chat)){
             emptyChats.push(chatFileNames[i]);
         }
     }
@@ -96,6 +96,7 @@ function waitForDBOPFS(){
 
 export {
     clearEmptyChatsAndMemories,
+    hasConversationEntry,
     hasMemoryContent,
     hasUserEntry
 };

package/runtime/arcane/modules/PersistentAIChatSession.js

@@ -286,6 +286,35 @@ function normalizeSend(input){
     };
 }
 
+function normalizeOpening(input){
+    if(!isPlainRecord(input)) throw new TypeError('Persistent chat opening input must be a plain object.');
+    assertKnownKeys(input,new Set(['message','request','signal']),'Persistent chat opening input');
+    if(!isPlainRecord(input.message)) throw new TypeError('message must be a plain object.');
+    assertKnownKeys(input.message,new Set(['content','persist','role']),'message');
+    if(typeof input.message.content!=='string'||!input.message.content.trim()){
+        throw new TypeError('message.content must contain text.');
+    }
+    const role=input.message.role??'user';
+    if(role!=='user') throw new TypeError('message.role must be user.');
+    if(input.message.persist!==undefined&&input.message.persist!==false){
+        throw new TypeError('The chat opening bootstrap is always nonpersistent.');
+    }
+    const request=input.request??{};
+    if(!isPlainRecord(request)) throw new TypeError('request must be a plain object.');
+    const managedRequestField=Object.keys(request).find(
+        key=>SESSION_MANAGED_REQUEST_FIELDS.has(key)
+    );
+    if(managedRequestField){
+        throw new TypeError(`request.${managedRequestField} is managed by the chat session.`);
+    }
+    if(!signalLike(input.signal)) throw new TypeError('signal must be an AbortSignal.');
+    return {
+        message:{role:'user',content:input.message.content},
+        request:{...request},
+        signal:input.signal??null,
+    };
+}
+
 function fileName(value){
     if(typeof value!=='string'||value.length===0){
         throw new TypeError('chatFileName must be a nonempty string.');
@@ -506,6 +535,54 @@ class PersistentAIChatSession{
         return this.#entity.settleMemory();
     }
 
+    /** Persists one model-authored opening while retaining none of its bootstrap request. */
+    async open(input){
+        const settings=normalizeOpening(input);
+        if(this.#pending){
+            throw coded(new Error('A chat request is already active for this session.'),'AI_CHAT_BUSY');
+        }
+        this.#pending=true;
+        let prepared=null;
+        try{
+            await this.ready();
+            if(this.#historyError)throw this.#historyError;
+            if(this.#entity.persist!==true){
+                throw coded(
+                    new Error('The model-authored chat opening requires durable chat persistence.'),
+                    'AI_CHAT_PERSISTENCE_UNAVAILABLE',
+                );
+            }
+            await this.#entity.settleMemory();
+            prepared=await this.#configured.prepareOpening(
+                settings.message,
+                {request:settings.request,signal:settings.signal},
+            );
+            await this.#entity.addAIMessage(
+                prepared.response.message.content,
+                {extractMemory:false,persist:true},
+            );
+            const committed=prepared.commit();
+            prepared=null;
+            const assistantRecord=this.#entity.transcript.at(-1);
+            return assistantRecord?.role==='assistant'
+                ?{
+                    ...committed,
+                    message:{
+                        ...committed.message,
+                        ...(assistantRecord.timestamp!==undefined
+                            ?{timestamp:assistantRecord.timestamp}
+                            :{}),
+                    },
+                }
+                :committed;
+        }catch(error){
+            prepared?.rollback();
+            throw error;
+        }finally{
+            this.#pending=false;
+        }
+    }
+
     async #requestTurn(input,streamHandlers=null){
         const settings=normalizeSend(input);
         if(this.#pending){