arcane-os 0.5.6 → 0.5.7

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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.7` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -176,8 +176,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 +192,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.7 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run check
@@ -197,7 +203,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.7
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -213,7 +219,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.7` 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 +240,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.7.tgz
 npm run check
 npm ci
 ```
@@ -244,7 +250,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.7` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -382,7 +388,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.6` exposes one browser target and five explicitly paired
+Version `0.5.7` 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.7",
   "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/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){