arcane-os 0.3.0 → 0.3.2

package/runtime/arcane/modules/PersistentAIChatSession.js

@@ -1,5 +1,17 @@
 import ChatEntity from '../entities/Chat.js';
-import ConfiguredAIChatSession from './ConfiguredAIChatSession.js';
+import ConfiguredAIChatSession,{
+    normalizeStructuralToolCall
+} from './ConfiguredAIChatSession.js';
+
+const SESSION_MANAGED_REQUEST_FIELDS=new Set([
+    'messages',
+    'onChunk',
+    'onResponse',
+    'onToolCall',
+    'signal',
+    'stream',
+]);
+const PROVIDER_LIFECYCLE_FIELDS=new Set(['onChunk','onResponse','onToolCall']);
 
 function coded(error,code){
     if(!error.code) error.code=code;
@@ -33,6 +45,12 @@ function signalLike(value){
     );
 }
 
+function providerRequestWithoutLifecycleCallbacks(value){
+    return Object.fromEntries(
+        Object.entries(value).filter(([key])=>!PROVIDER_LIFECYCLE_FIELDS.has(key))
+    );
+}
+
 async function configuredArcaneChat(request){
     const api=globalThis.Arcane?.ai;
     if(typeof api?.chat!=='function'){
@@ -44,9 +62,90 @@ async function configuredArcaneChat(request){
     return api.chat(request);
 }
 
+function configuredAIChat(ai){
+    return function requestConfiguredAI(request){
+        return ai.fetchRequest(request);
+    };
+}
+
+function normalizeStreamHandlers(value){
+    if(value===undefined) return {};
+    if(!isPlainRecord(value)) throw new TypeError('Persistent chat stream handlers must be a plain object.');
+    assertKnownKeys(value,new Set(['onChunk','onToolCall']),'Persistent chat stream handlers');
+    for(const key of ['onChunk','onToolCall']){
+        if(value[key]!==undefined&&typeof value[key]!=='function'){
+            throw new TypeError(`${key} must be a function when provided.`);
+        }
+    }
+    return {
+        onChunk:value.onChunk??function ignorePersistentChatChunk(){},
+        onToolCall:value.onToolCall??function ignorePersistentChatToolCall(){},
+    };
+}
+
+function normalizeStreamResponse(terminal,output){
+    const value=terminal??output;
+    if(typeof value==='string'){
+        return {message:{role:'assistant',content:value}};
+    }
+    if(isPlainRecord(value)) return value;
+    throw coded(
+        new TypeError('The AI stream did not return a terminal response.'),
+        'AI_CHAT_INVALID_RESPONSE',
+    );
+}
+
+function terminalStructuralToolCall(response){
+    const hasMessage=Object.hasOwn(response,'message');
+    const hasChoices=Object.hasOwn(response,'choices');
+    if(hasMessage&&hasChoices){
+        throw coded(
+            new TypeError('The AI stream terminal response cannot mix message and choices envelopes.'),
+            'AI_CHAT_INVALID_RESPONSE',
+        );
+    }
+    const messages=hasMessage
+        ?[response.message]
+        :hasChoices&&Array.isArray(response.choices)
+            ?response.choices.map(choice=>choice?.message).filter(Boolean)
+            :[];
+    const calls=[];
+    for(let messageIndex=0;messageIndex<messages.length;messageIndex++){
+        const value=messages[messageIndex]?.tool_calls;
+        if(value===undefined) continue;
+        if(!Array.isArray(value)){
+            throw coded(
+                new TypeError('The AI stream terminal response contains invalid structural tool calls.'),
+                'AI_CHAT_INVALID_TOOL_CALL',
+            );
+        }
+        for(let callIndex=0;callIndex<value.length;callIndex++){
+            calls.push(normalizeStructuralToolCall(
+                value[callIndex],
+                `The terminal structural tool call ${messageIndex+1}.${callIndex+1}`,
+            ));
+        }
+    }
+    if(calls.length>1){
+        throw coded(
+            new TypeError('The AI stream terminal response contains parallel structural tool calls.'),
+            'AI_CHAT_PARALLEL_TOOLS_UNSUPPORTED',
+        );
+    }
+    return calls[0]??null;
+}
+
+function sameStructuralToolCall(left,right){
+    return Boolean(left&&right)
+        &&left.id===right.id
+        &&left.type===right.type
+        &&left.function.name===right.function.name
+        &&left.function.arguments===right.function.arguments;
+}
+
 function normalizeSend(input){
     if(!isPlainRecord(input)) throw new TypeError('Persistent chat input must be a plain object.');
-    assertKnownKeys(input,new Set(['message','response','signal']),'Persistent chat input');
+    assertKnownKeys(input,new Set(['message','request','response','signal']),'Persistent chat input');
     if(!isPlainRecord(input.message)) throw new TypeError('message must be a plain object.');
     assertKnownKeys(input.message,new Set(['content','persist','role','tool_call_id']),'message');
     if(typeof input.message.content!=='string'||!input.message.content.trim()){
@@ -74,17 +173,26 @@ function normalizeSend(input){
             'AI_CHAT_INCOHERENT_PERSISTENCE',
         );
     }
+    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 Object.freeze({
+    return {
         messagePersist,
-        requestMessage:Object.freeze({
+        requestMessage:{
             content:input.message.content,
             role,
             ...(toolCallId?{tool_call_id:toolCallId}:{}),
-        }),
+        },
         responsePersist,
+        request:{...request},
         signal:input.signal??null,
-    });
+    };
 }
 
 function fileName(value){
@@ -100,8 +208,10 @@ function fileName(value){
  * per-turn persistence affects DBOPFS and memory, never the live model context.
  */
 class PersistentAIChatSession{
+    #activeStream=null;
     #configured=null;
     #entity;
+    #fetchChat;
     #memory;
     #options;
     #pending=false;
@@ -113,7 +223,7 @@ class PersistentAIChatSession{
         assertKnownKeys(
             options,
             new Set([
-                'chat','chatEntity','chatFileName','contextBuilder','loadExisting','maxContextCharacters',
+                'ai','chat','chatEntity','chatFileName','contextBuilder','loadExisting','maxContextCharacters',
                 'maxMessageCharacters','maxMessages','memory','request','responseLength','systemPrompt'
             ]),
             'Persistent chat options',
@@ -121,8 +231,48 @@ class PersistentAIChatSession{
         if(options.chatEntity!==undefined&&!(options.chatEntity instanceof ChatEntity)){
             throw new TypeError('chatEntity must be a ChatEntity.');
         }
-        const chat=options.chat??configuredArcaneChat;
+        if(options.ai!==undefined&&(
+            !options.ai
+            ||typeof options.ai!=='object'
+            ||typeof options.ai.fetchRequest!=='function'
+        )){
+            throw new TypeError('ai must expose fetchRequest(request).');
+        }
+        if(options.ai!==undefined&&options.chat!==undefined){
+            throw coded(
+                new TypeError('Specify either ai or chat, not both.'),
+                'AI_CHAT_AMBIGUOUS_PROVIDER',
+            );
+        }
+        const chat=options.ai===undefined
+            ?options.chat??configuredArcaneChat
+            :configuredAIChat(options.ai);
         if(typeof chat!=='function') throw new TypeError('chat must be a function.');
+        if(options.request!==undefined&&!isPlainRecord(options.request)){
+            throw new TypeError('request must be a plain object.');
+        }
+        const request={...(options.request??{})};
+        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(
+            request.parallelToolCalls===true
+            ||request.parallel_tool_calls===true
+        ){
+            throw coded(
+                new TypeError('Persistent chat supports one structural tool call at a time.'),
+                'AI_CHAT_PARALLEL_TOOLS_UNSUPPORTED',
+            );
+        }
+        if(
+            request.parallelToolCalls===undefined
+            &&request.parallel_tool_calls===undefined
+        ){
+            request.parallelToolCalls=false;
+        }
         const systemPrompt=options.systemPrompt??'';
         if(typeof systemPrompt!=='string') throw new TypeError('systemPrompt must be a string.');
         this.#entity=options.chatEntity??new ChatEntity(systemPrompt);
@@ -138,7 +288,8 @@ class PersistentAIChatSession{
             throw new TypeError('loadExisting requires chatFileName or chatEntity.');
         }
         this.#memory=boolean(options.memory,'memory',true);
-        this.#options=Object.freeze({...options,chat,loadExisting,systemPrompt});
+        this.#fetchChat=chat;
+        this.#options={...options,chat,loadExisting,request,systemPrompt};
         this.#readyPromise=this.#initialize();
     }
 
@@ -150,6 +301,54 @@ class PersistentAIChatSession{
 
     get chatEntity(){return this.#entity;}
     get fileName(){return this.#entity.fileName;}
+    get ai(){return this.#options.ai??null;}
+
+    async #requestConfiguredAI(request){
+        const providerRequest=providerRequestWithoutLifecycleCallbacks(request);
+        if(!this.#activeStream) return this.#fetchChat(providerRequest);
+        if(typeof this.#options.ai?.streamRequest!=='function'){
+            return this.#fetchChat(providerRequest);
+        }
+        const activeStream=this.#activeStream;
+        let terminal=null;
+        let streamedToolCall=null;
+        let streamedToolDetails=[];
+        const output=await this.#options.ai.streamRequest({
+            ...providerRequest,
+            onChunk:activeStream.onChunk,
+            onToolCall:function retainStructuralToolCall(call,...details){
+                const normalized=normalizeStructuralToolCall(
+                    call,
+                    'The streamed structural tool call',
+                );
+                if(streamedToolCall&&!sameStructuralToolCall(streamedToolCall,normalized)){
+                    throw coded(
+                        new TypeError('The AI stream emitted divergent structural tool calls.'),
+                        'AI_CHAT_STREAM_TOOL_CALL_MISMATCH',
+                    );
+                }
+                streamedToolCall=normalized;
+                streamedToolDetails=details;
+            },
+            onResponse:async function retainPersistentChatTerminal(response){
+                terminal=response;
+            },
+        });
+        const response=normalizeStreamResponse(terminal,output);
+        const terminalToolCall=terminalStructuralToolCall(response);
+        if(streamedToolCall&&!sameStructuralToolCall(streamedToolCall,terminalToolCall)){
+            throw coded(
+                new TypeError(
+                    'The AI stream terminal response omitted or changed its structural tool call.'
+                ),
+                'AI_CHAT_STREAM_TOOL_CALL_MISMATCH',
+            );
+        }
+        activeStream.streamedToolCall=streamedToolCall;
+        activeStream.streamedToolDetails=streamedToolDetails;
+        activeStream.terminalToolCall=terminalToolCall;
+        return response;
+    }
 
     async #initialize(){
         if(this.#options.loadExisting) await this.#entity.load();
@@ -157,9 +356,12 @@ class PersistentAIChatSession{
         const storedSystem=storedMessages.find(message=>message.role==='system');
         const initialMessages=storedMessages
             .filter(message=>['user','assistant','tool'].includes(message.role))
-            .map(message=>Object.freeze({
+            .map(message=>({
                 role:message.role,
                 content:String(message.content??''),
+                ...(message.role==='assistant'&&Object.hasOwn(message,'reasoning_content')
+                    ?{reasoning_content:message.reasoning_content}
+                    :{}),
                 ...(message.tool_calls?{tool_calls:message.tool_calls}:{}),
                 ...(message.tool_call_id?{tool_call_id:message.tool_call_id}:{}),
             }));
@@ -171,12 +373,9 @@ class PersistentAIChatSession{
             }
         }
         const configuredOptions={
-            chat:this.#options.chat,
+            chat:request=>this.#requestConfiguredAI(request),
             contextBuilder:this.#options.contextBuilder,
             initialMessages,
-            maxContextCharacters:this.#options.maxContextCharacters,
-            maxMessageCharacters:this.#options.maxMessageCharacters,
-            maxMessages:this.#options.maxMessages,
             request:this.#options.request,
             systemPrompt:this.#options.systemPrompt||String(storedSystem?.content??''),
         };
@@ -200,12 +399,17 @@ class PersistentAIChatSession{
         return this.#configured.history();
     }
 
+    async transcript(){
+        await this.ready();
+        return this.#entity.transcript;
+    }
+
     async settleMemory(){
         await this.ready();
         return this.#entity.settleMemory();
     }
 
-    async send(input){
+    async #requestTurn(input,streamHandlers=null){
         const settings=normalizeSend(input);
         if(this.#pending){
             throw coded(new Error('A chat request is already active for this session.'),'AI_CHAT_BUSY');
@@ -233,12 +437,51 @@ class PersistentAIChatSession{
                     );
                 }
             }
-            prepared=await this.#configured.prepare(settings.requestMessage,{signal:settings.signal});
+            const streamState=streamHandlers?{
+                ...streamHandlers,
+                streamedToolCall:null,
+                streamedToolDetails:[],
+                terminalToolCall:null,
+            }:null;
+            if(streamState) this.#activeStream=streamState;
+            try{
+                prepared=await this.#configured.prepare(
+                    settings.requestMessage,
+                    {request:settings.request,signal:settings.signal},
+                );
+            }finally{
+                if(this.#activeStream===streamState) this.#activeStream=null;
+            }
             const result=prepared.response;
+            if(streamState){
+                const validatedToolCall=result.message.tool_calls?.[0]??null;
+                if(
+                    streamState.terminalToolCall
+                    &&!sameStructuralToolCall(streamState.terminalToolCall,validatedToolCall)
+                ){
+                    throw coded(
+                        new TypeError(
+                            'The validated AI response changed its terminal structural tool call.'
+                        ),
+                        'AI_CHAT_STREAM_TOOL_CALL_MISMATCH',
+                    );
+                }
+                if(validatedToolCall){
+                    await streamState.onToolCall(
+                        validatedToolCall,
+                        ...streamState.streamedToolDetails,
+                    );
+                }
+            }
             await this.#entity.addTurn({
                 assistantMessage:result.message,
                 extractMemory:this.#memory&&settings.messagePersist&&settings.responsePersist,
-                memoryRequest:messages=>this.#options.chat({messages}),
+                memoryRequest:messages=>this.#fetchChat(
+                    providerRequestWithoutLifecycleCallbacks({
+                        ...this.#options.request,
+                        messages,
+                    })
+                ),
                 messagePersist:settings.messagePersist,
                 requestMessage:settings.requestMessage,
                 responsePersist:settings.responsePersist,
@@ -250,7 +493,19 @@ class PersistentAIChatSession{
             for(const call of result.message.tool_calls??[]){
                 this.#toolCallPersistence.set(call.id,settings.responsePersist);
             }
-            return committed;
+            const transcript=this.#entity.transcript;
+            const assistantRecord=transcript.at(-1);
+            return assistantRecord?.role==='assistant'
+                ?{
+                    ...committed,
+                    message:{
+                        ...committed.message,
+                        ...(assistantRecord.timestamp!==undefined
+                            ?{timestamp:assistantRecord.timestamp}
+                            :{}),
+                    },
+                }
+                :committed;
         }catch(error){
             prepared?.rollback();
             throw error;
@@ -258,6 +513,14 @@ class PersistentAIChatSession{
             this.#pending=false;
         }
     }
+
+    async send(input){
+        return this.#requestTurn(input);
+    }
+
+    async stream(input,handlers={}){
+        return this.#requestTurn(input,normalizeStreamHandlers(handlers));
+    }
 }
 
 function createPersistentAIChatSession(options){