arcane-os 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.5.6
+
+- Sanitized newly persisted chat history into complete human-readable user,
+  assistant, and public tool-result records without storing internal prompts,
+  provider envelopes, raw tool protocol fields, or hidden request metadata.
+  Existing stored rows remain untouched.
+- Made `persist: false` turn-scoped: the request can use the complete temporary
+  turn, then retains neither side in model history, memory, DBOPFS, nor the Chat
+  transcript after the operation settles.
+
+## 0.5.5
+
+- Added configurable complete text-to-speech stream segmentation through
+  `AI.configureTTSSegmentation()`. Applications can speak on Unicode punctuation
+  or a whole-word cadence without discarding any text, while apostrophes,
+  commas, and hyphens that join Unicode letters or numbers remain intact.
+  Synthesis and playback stay sequential, and mute or cancellation still stops
+  the complete queue.
+
 ## 0.5.4
 
 - Reduced Browser-WASM HTTP Range parts from roughly 128 MB to roughly 4 MB

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.4` SDK contract. Applications pin one exact npm
+This checkout defines the `0.5.6` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -153,6 +153,24 @@ must supply each runtime/model selection explicitly. Speech roles
 load, cancel, unload, fail, and recover independently, so speech failure never
 silently falls back or prevents text chat.
 
+Applications that need faster spoken-response onset can configure the shared
+TTS stream without taking over synthesis or playback:
+
+```js
+ai.configureTTSSegmentation({
+    punctuation:'any',
+    wordCadence:4
+});
+```
+
+The compatibility default remains sentence punctuation with no word cadence.
+The configured stream preserves every character and punctuation mark, chooses
+the earliest complete boundary, and keeps synthesis and playback sequential.
+Any-punctuation mode recognizes boundaries without requiring whitespace while
+keeping apostrophes, commas, and hyphens that join Unicode letters or numbers
+inside the same segment.
+Mute, stop, provider transition, and cancellation still govern the whole queue.
+
 The SDK runtime also owns `DBOPFSDocumentLibrary`,
 `DocumentLexicalSearch`, and `PersistentAIChatSession`. Document bootstrap is
 schema-driven and explicit; chat never searches a corpus unless the app wires
@@ -168,7 +186,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.4 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.5.6 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run check
@@ -179,7 +197,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.4
+npm install --save-dev --save-exact arcane-os@0.5.6
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -195,7 +213,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.4` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.5.6` 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`,
@@ -216,7 +234,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.4.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.6.tgz
 npm run check
 npm ci
 ```
@@ -226,7 +244,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.4` registry package and
+the local declaration with the exact `arcane-os@0.5.6` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -364,7 +382,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.4` exposes one browser target and five explicitly paired
+Version `0.5.6` 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.4",
+  "version": "0.5.6",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/runtime/arcane/components/chat.html

@@ -1333,12 +1333,13 @@
     }
 
     function sameTranscriptRequest(actual,expected){
-        return actual?.role===expected?.role
-            &&actual.content===expected.content
-            &&(
-                expected.role!=='tool'
-                ||actual.tool_call_id===expected.tool_call_id
-            );
+        if(actual?.role!==expected?.role) return false;
+        if(expected.role==='tool'){
+            return actual.content===(expected.message??expected.content)
+                &&(expected.name===undefined||actual.name===expected.name)
+                &&(expected.status===undefined||actual.status===expected.status);
+        }
+        return actual.content===expected.content;
     }
 
     function latestCommittedTranscriptTurn(transcript,requestMessages){
@@ -1460,18 +1461,20 @@
                 }
                 if(actionable){
                     if(message.role==='tool'){
-                        if(
-                            typeof message.tool_call_id!=='string'
-                            ||!message.tool_call_id.trim()
-                            ||!message.content.trim()
-                            ||!restoredPendingToolCalls.has(message.tool_call_id)
-                        ){
-                            throw chatError(
-                                'Saved chat contains a tool result that does not match a pending structural tool call.',
-                                'AI_CHAT_INVALID_TOOL_MESSAGE'
-                            );
+                        if(message.tool_call_id!==undefined){
+                            if(
+                                typeof message.tool_call_id!=='string'
+                                ||!message.tool_call_id.trim()
+                                ||!message.content.trim()
+                                ||!restoredPendingToolCalls.has(message.tool_call_id)
+                            ){
+                                throw chatError(
+                                    'Saved chat contains a tool result that does not match a pending structural tool call.',
+                                    'AI_CHAT_INVALID_TOOL_MESSAGE'
+                                );
+                            }
+                            restoredPendingToolCalls.delete(message.tool_call_id);
                         }
-                        restoredPendingToolCalls.delete(message.tool_call_id);
                     }else{
                         if(restoredPendingToolCalls.size){
                             throw chatError(
@@ -1489,7 +1492,9 @@
                 const name=message.role==='user'
                     ?host.name
                     :message.role==='tool'
-                    ?'Tool'
+                    ?typeof message.name==='string'&&message.name.trim()
+                        ?`Tool · ${message.name}`
+                        :'Tool'
                     :message.role==='system'
                     ?'System'
                     :host.aiName;
@@ -3069,6 +3074,7 @@
         if(!sessionRequestMessages.length){
             throw new TypeError('A chat session request must contain at least one message.');
         }
+        const retainTurn=sessionRequestMessages.every(message=>message.persist!==false);
         const request={
             ...(sessionRequestMessages.length===1
                 ?{message:sessionRequestMessages[0]}
@@ -3179,22 +3185,29 @@
                         ??committedTurn?.request?.timestamp
                 );
             }
-            const terminalToolCalls=normalizeVisibleToolCalls(result.message.tool_calls);
-            if(
-                streamedStructuralToolCalls.length
-                &&!sameStructuralToolCalls(streamedStructuralToolCalls,terminalToolCalls)
-            ){
-                throw chatError(
-                    'The terminal structural tool calls do not match the streamed calls.',
-                    'AI_CHAT_STREAM_TOOL_CALL_MISMATCH'
-                );
-            }
-            if(!streamedStructuralToolCalls.length){
-                for(const call of terminalToolCalls){
-                    appendVisibleToolCall(message,call);
+            if(retainTurn){
+                const terminalToolCalls=normalizeVisibleToolCalls(result.message.tool_calls);
+                if(
+                    streamedStructuralToolCalls.length
+                    &&!sameStructuralToolCalls(streamedStructuralToolCalls,terminalToolCalls)
+                ){
+                    throw chatError(
+                        'The terminal structural tool calls do not match the streamed calls.',
+                        'AI_CHAT_STREAM_TOOL_CALL_MISMATCH'
+                    );
                 }
+                if(!streamedStructuralToolCalls.length){
+                    for(const call of terminalToolCalls){
+                        appendVisibleToolCall(message,call);
+                    }
+                }
+                setPendingStructuralToolCalls(terminalToolCalls);
+            }else{
+                for(const requestMessage of requestMessages) requestMessage.remove();
+                message.remove();
+                setPendingStructuralToolCalls(previousPendingToolCalls);
+                scrollTranscriptToBottom();
             }
-            setPendingStructuralToolCalls(terminalToolCalls);
             setSessionStatus(
                 pendingStructuralToolMessage?'tool':'ready',
                 pendingStructuralToolMessage||'Chat ready.'
@@ -3339,7 +3352,7 @@
         if(!Array.isArray(options.results)||options.results.length===0){
             throw new TypeError('Tool results must be a nonempty array.');
         }
-        const dispositions=new Map([
+        const statuses=new Map([
             ['executed','Executed'],
             ['declined','Declined'],
             ['cancelled','Cancelled'],
@@ -3369,7 +3382,7 @@
                 throw new TypeError(`Tool result ${index+1} must be a plain object.`);
             }
             const unsupportedResultField=Object.keys(result).find(
-                key=>!['disposition','message','persist','toolCallId'].includes(key)
+                key=>!['disposition','message','persist','status','toolCallId'].includes(key)
             );
             if(unsupportedResultField){
                 throw new TypeError(
@@ -3388,9 +3401,17 @@
                 error.code='AI_CHAT_INVALID_TOOL_MESSAGE';
                 throw error;
             }
-            if(!dispositions.has(result.disposition)){
+            if(
+                result.status!==undefined
+                &&result.disposition!==undefined
+                &&result.status!==result.disposition
+            ){
+                throw new TypeError('Tool-result status and legacy disposition must match.');
+            }
+            const status=result.status??result.disposition;
+            if(!statuses.has(status)){
                 throw new TypeError(
-                    'Tool-result disposition must be executed, declined, cancelled, or not-executed.'
+                    'Tool-result status must be executed, declined, cancelled, or not-executed.'
                 );
             }
             if(typeof result.message!=='string'||!result.message.trim()){
@@ -3401,9 +3422,12 @@
                 throw new TypeError('Tool-result persist must be boolean.');
             }
             resultsById.set(toolCallId,{
-                content:`${dispositions.get(result.disposition)} — ${result.message}`,
+                content:`${statuses.get(status)} — ${result.message}`,
+                message:result.message,
+                name:pendingById.get(toolCallId).function.name,
                 persist,
                 role:'tool',
+                status,
                 tool_call_id:toolCallId
             });
         }
@@ -3440,7 +3464,11 @@
         }
         try{
             for(const result of orderedResults){
-                const visibleMessage=appendTranscriptMessage('tool',result.content,'Tool');
+                const visibleMessage=appendTranscriptMessage(
+                    'tool',
+                    result.content,
+                    `Tool · ${result.name}`
+                );
                 visibleMessage.dataset.operationId=operationId;
                 visibleMessage.dataset.toolCallId=result.tool_call_id;
             }
@@ -3472,7 +3500,7 @@
             throw new TypeError('Tool-result options must be a plain object.');
         }
         const unsupportedOption=Object.keys(options).find(
-            key=>!['disposition','message','persist','request','toolCallId'].includes(key)
+            key=>!['disposition','message','persist','request','status','toolCallId'].includes(key)
         );
         if(unsupportedOption){
             throw new TypeError(`Unsupported tool-result option: ${unsupportedOption}.`);

package/runtime/arcane/entities/Chat.js

@@ -102,6 +102,96 @@ function copyToolCalls(value){
     });
 }
 
+function structuralToolMessage(call){
+    const argumentRecord=JSON.parse(call.function.arguments);
+    return argumentRecord.message;
+}
+
+function storedStructuralToolCalls(value){
+    if(value===undefined) return [];
+    if(!Array.isArray(value)){
+        console.error('Arcane stored assistant tool calls were not an array and were not retained.');
+        return [];
+    }
+    const result=[];
+    for(const [index,call] of value.entries()){
+        try{
+            result.push(copyToolCalls([call])[0]);
+        }catch(error){
+            console.error(
+                `Arcane stored assistant tool call ${index+1} had no usable user-facing message and was not retained.`,
+                error
+            );
+        }
+    }
+    return result;
+}
+
+function storedToolRecord({content,name,status,timestamp}){
+    if(typeof content!=='string'||!content.trim()) return [];
+    return [{
+        role:'tool',
+        content,
+        ...(typeof name==='string'&&name.trim()?{name}:{}),
+        ...(typeof status==='string'&&status.trim()?{status}:{}),
+        ...(timestamp!==undefined?{timestamp}:{}),
+    }];
+}
+
+function storedChatRecords(messages,{memoryOnly=false}={}){
+    const result=[];
+    for(const message of messages){
+        if(!plainRecord(message)) continue;
+        if(message.persistence_excluded===true) continue;
+        if(memoryOnly&&message.memory_excluded===true) continue;
+        const timestamp=message.timestamp;
+        if(message.role==='user'){
+            if(typeof message.content!=='string') continue;
+            result.push({
+                role:'user',
+                content:message.content,
+                ...(timestamp!==undefined?{timestamp}:{}),
+            });
+            continue;
+        }
+        if(message.role==='assistant'){
+            const content=message.content===undefined||message.content===null
+                ?''
+                :String(message.content);
+            if(content){
+                result.push({
+                    role:'assistant',
+                    content,
+                    ...(timestamp!==undefined?{timestamp}:{}),
+                });
+            }
+            for(const call of storedStructuralToolCalls(message.tool_calls)){
+                result.push(...storedToolRecord({
+                    content:structuralToolMessage(call),
+                    name:call.function.name,
+                    status:'requested',
+                    timestamp,
+                }));
+            }
+            continue;
+        }
+        if(message.role==='tool'){
+            const protocolResult=typeof message.tool_call_id==='string'&&message.tool_call_id;
+            result.push(...storedToolRecord({
+                content:protocolResult?message.persistence_message:message.content,
+                name:message.persistence_name??message.name,
+                status:message.persistence_status??message.status,
+                timestamp,
+            }));
+        }
+    }
+    return result;
+}
+
+function retainedChatMessages(messages){
+    return messages.filter(message=>message?.persistence_excluded!==true);
+}
+
 function turnMessage(value,label){
     if(!plainRecord(value)||!['tool','user'].includes(value.role)||typeof value.content!=='string'){
         throw new TypeError(`${label} must be a user or tool message.`);
@@ -179,6 +269,9 @@ function pendingToolCalls(messages){
         }
         if(message.role==='tool'){
             const toolCallId=message.tool_call_id;
+            if(toolCallId===undefined){
+                continue;
+            }
             if(typeof toolCallId!=='string'||!toolCallId.trim()){
                 throw coded(
                     new TypeError(`Chat message ${index+1} has an invalid tool_call_id.`),
@@ -231,18 +324,8 @@ function turnMessages(requestMessage,requestMessages){
  *
  * @property {string|number} content
  * Message text content.
- * @property {boolean} [memory_excluded]
- * Internal persistence marker omitted from model-facing messages.
- * @property {boolean} [ui_hidden]
- * Legacy persistence metadata retained without suppressing the public transcript.
- * @property {boolean} [persistence_excluded]
- * Internal marker for session-only messages omitted from durable chat and memory.
- * @property {Array<Object>} [tool_calls]
- * Assistant tool calls retained in the saved conversation log.
- * @property {string} [reasoning_content]
- * Optional complete provider reasoning retained with an assistant record.
- * @property {string} [tool_call_id]
- * Matching tool-call identifier for a tool result.
+ * Active provider messages may also contain transient protocol and internal
+ * fields. The DBOPFS projection never retains those fields.
  */
 
 /**
@@ -258,13 +341,12 @@ function turnMessages(requestMessage,requestMessages){
  *     chat-1719930112231.json
  * ```
  *
- * File contents:
+ * New file contents:
  *
  * ```
  * [
- *   { "role":"system","content":"..." },
- *   { "role":"user","content":"Hello" },
- *   { "role":"assistant","content":"Hi there" }
+ *   { "role":"user","content":"Hello","timestamp":1719930112231 },
+ *   { "role":"assistant","content":"Hi there","timestamp":1719930112240 }
  * ]
  * ```
  *
@@ -328,6 +410,9 @@ class ChatEntity{
     /** Number of leading in-memory messages durably present in the chat file. */
     #persistedMessageCount=0;
 
+    /** Existing stored records preserved exactly while new records use the narrow format. */
+    #preservedStoredMessageCount=0;
+
     /** Serializes snapshot and append writes for this chat instance. */
     #persistenceQueue=Promise.resolve();
 
@@ -375,8 +460,10 @@ class ChatEntity{
      * @returns {Array<*>}
      */
     get messages(){
-        pendingToolCalls(this.#messages);
-        return this.#messages.map(function publicChatMessage(message){
+        const retainedMessages=retainedChatMessages(this.#messages);
+        pendingToolCalls(retainedMessages);
+        return retainedMessages
+            .map(function publicChatMessage(message){
             const copy={...message};
             if(copy.tool_calls){
                 copy.tool_calls=copyToolCalls(copy.tool_calls).map(call=>({
@@ -388,19 +475,27 @@ class ChatEntity{
             delete copy.persistence_excluded;
             delete copy.ui_hidden;
             delete copy.timestamp;
+            delete copy.persistence_message;
+            delete copy.persistence_name;
+            delete copy.persistence_status;
+            if(copy.role==='tool'&&copy.tool_call_id===undefined){
+                delete copy.name;
+                delete copy.status;
+                copy.role='assistant';
+            }
             return copy;
         });
     }
 
     /**
-     * Returns the UI-visible conversation records with their persisted timestamps.
-     * Model-facing callers should continue to use `messages`, which intentionally
-     * omits display metadata.
+     * Returns the sanitized human-readable conversation records. User and
+     * assistant records contain only role, complete visible content, and timestamp.
+     * Tool records may also contain their public name and result status.
      *
      * @returns {Array<*>}
      */
     get transcript(){
-        return this.#messages.map(function publicTranscriptMessage(message){
+        return storedChatRecords(this.#messages).map(function publicTranscriptMessage(message){
             return copyCompleteValue(message);
         });
     }
@@ -417,6 +512,7 @@ class ChatEntity{
         }
         this.#messages=v.map(message=>copyCompleteValue(message));
         this.#persistedMessageCount=0;
+        this.#preservedStoredMessageCount=0;
         this.#saved=false;
         return this.transcript;
     }
@@ -465,7 +561,7 @@ class ChatEntity{
         if(!is.boolean(persist)){
             throw new Error('persist must be boolean');
         }
-        if(pendingToolCalls(this.#messages).size){
+        if(pendingToolCalls(retainedChatMessages(this.#messages)).size){
             throw coded(
                 new TypeError('The pending structural tool results must be supplied before a new user turn.'),
                 'AI_CHAT_TOOL_RESULT_REQUIRED'
@@ -509,7 +605,7 @@ class ChatEntity{
         if(!is.boolean(persist)){
             throw new Error('persist must be boolean');
         }
-        if(pendingToolCalls(this.#messages).size){
+        if(pendingToolCalls(retainedChatMessages(this.#messages)).size){
             throw coded(
                 new TypeError('The pending structural tool results must be supplied before another assistant turn.'),
                 'AI_CHAT_TOOL_RESULT_REQUIRED'
@@ -537,7 +633,8 @@ class ChatEntity{
 
     /**
      * Adds an assistant tool call and its result as one hidden, atomic log exchange.
-     * The host application decides whether anything is rendered in the chat UI.
+     * The active provider context keeps the complete exchange. New durable history
+     * retains only the call's required user-facing arguments.message record.
      */
     addToolExchange({id='',name='',arguments:argumentValue='',result='',persist=true}={}){
         const toolCallId=id;
@@ -553,7 +650,7 @@ class ChatEntity{
         if(!is.boolean(persist)){
             throw new TypeError('persist must be boolean.');
         }
-        if(pendingToolCalls(this.#messages).size){
+        if(pendingToolCalls(retainedChatMessages(this.#messages)).size){
             throw coded(
                 new TypeError('The pending structural tool results must be supplied before another tool exchange.'),
                 'AI_CHAT_TOOL_RESULT_REQUIRED'
@@ -629,7 +726,7 @@ class ChatEntity{
                 'AI_CHAT_INCOHERENT_PERSISTENCE'
             );
         }
-        const pendingTools=pendingToolCalls(this.#messages);
+        const pendingTools=pendingToolCalls(retainedChatMessages(this.#messages));
         const userRequest=requests.find(message=>message.role==='user');
         const toolRequests=requests.filter(message=>message.role==='tool');
         if(userRequest&&pendingTools.size){
@@ -690,15 +787,10 @@ class ChatEntity{
         };
         if(!extractMemory||toolCalls?.length) assistantRecord.memory_excluded=true;
         else delete assistantRecord.memory_excluded;
-        if(!messagePersist){
-            for(const requestRecord of requestRecords){
-                requestRecord.persistence_excluded=true;
-            }
-        }
-        if(!responsePersist) assistantRecord.persistence_excluded=true;
-        else delete assistantRecord.persistence_excluded;
-
-        const appended=this.#appendMessages([...requestRecords,assistantRecord],{prepared:true});
+        const appended=this.#appendMessages(
+            [...requestRecords,assistantRecord],
+            {persist:messagePersist,prepared:true}
+        );
         if(extractMemory&&messagePersist&&responsePersist&&!toolCalls?.length&&this.persist){
             return Promise.resolve(appended).then(result=>{
                 this.#queueMemoryUpdate(memoryRequest);
@@ -729,6 +821,7 @@ class ChatEntity{
             const systemMessage=this.#messages.find(message=>message.role==='system');
             this.#messages=systemMessage?[systemMessage]:[];
             this.#persistedMessageCount=0;
+            this.#preservedStoredMessageCount=0;
             this.#saved=true;
             return this.transcript;
         }
@@ -751,7 +844,8 @@ class ChatEntity{
                     }
                 });
         this.#messages=loadedMessages;
-        this.#persistedMessageCount=this.#durableMessages().length;
+        this.#preservedStoredMessageCount=loadedMessages.length;
+        this.#persistedMessageCount=loadedMessages.length;
         this.#saved=true;
 
         return this.transcript;
@@ -762,7 +856,8 @@ class ChatEntity{
             throw new TypeError('Memory request must be a function.');
         }
         return this.#writeMemory(
-            this.#durableMessages().map(message=>({...message})),
+            storedChatRecords(this.#messages,{memoryOnly:true})
+                .map(message=>({...message})),
             request
         );
     }
@@ -844,7 +939,11 @@ ${JSON.stringify(transcript)}`
     }
 
     #queueMemoryUpdate(request){
-        const snapshot=this.#durableMessages().map(message=>copyCompleteValue(message));
+        const snapshot=storedChatRecords(
+            this.#messages,
+            {memoryOnly:true}
+        )
+            .map(message=>copyCompleteValue(message));
         const queued=this.#memoryQueue.then(()=>this.#writeMemory(snapshot,request));
         this.#memoryQueue=queued.catch(()=>{
             console.warn('Unable to update chat memory.');
@@ -889,12 +988,11 @@ ${JSON.stringify(transcript)}`
      *
      * The log file is stored in **NDJSON format** (newline-delimited JSON).
      *
-     * Example stored file:
+     * Example newly stored file:
      *
      * ```
-     * {"role":"system","content":"You are a calm evaluator"}
-     * {"role":"user","content":"Hello"}
-     * {"role":"assistant","content":"Hi there"}
+     * {"role":"user","content":"Hello","timestamp":1719930112231}
+     * {"role":"assistant","content":"Hi there","timestamp":1719930112240}
      * ```
      *
      * Each call to `appendMessage` writes one JSON object followed
@@ -948,21 +1046,25 @@ ${JSON.stringify(transcript)}`
     }
 
     #durableMessages(){
-        return this.#messages.filter(
-            message=>!message||typeof message!=='object'||message.persistence_excluded!==true
-        );
+        return [
+            ...this.#messages
+                .slice(0,this.#preservedStoredMessageCount)
+                .map(message=>copyCompleteValue(message)),
+            ...storedChatRecords(
+                this.#messages.slice(this.#preservedStoredMessageCount)
+            ),
+        ];
     }
 
     async #appendMessages(messages,{persist=true,prepared=false}={}){
-        const records=Array.from(messages||[]).map(message=>
-            prepared?message:(persist?message:{...message,persistence_excluded:true})
-        );
+        const records=Array.from(messages||[]).map(message=>prepared?message:{...message});
         if(!records.length){
             return false;
         }
+        if(!persist) return false;
 
         this.#messages.push(...records);
-        const durableRecords=records.filter(message=>message.persistence_excluded!==true);
+        const durableRecords=storedChatRecords(records);
         if(durableRecords.length){
             this.#saved=false;
         }
@@ -994,17 +1096,8 @@ ${JSON.stringify(transcript)}`
                     );
                 }
                 const durableSnapshot=this.#durableMessages();
-                const durableIndex=durableSnapshot.indexOf(durableRecords[0]);
-                const durableRecordsAreContiguous=durableRecords.every(
-                    (record,index)=>durableSnapshot[durableIndex+index]===record
-                );
-                if(durableIndex<0||!durableRecordsAreContiguous){
-                    throw coded(
-                        new Error('Durable chat records changed before persistence completed.'),
-                        'AI_CHAT_INCOHERENT_PERSISTENCE'
-                    );
-                }
-                const lastDurableIndex=durableIndex+durableRecords.length-1;
+                const durableIndex=durableSnapshot.length-durableRecords.length;
+                const lastDurableIndex=durableSnapshot.length-1;
                 if(this.#persistedMessageCount===durableIndex){
                     await dbopfs.set(
                         this.#tableName,

package/runtime/arcane/modules/AI.js

@@ -17,6 +17,16 @@ const completeValue=(value)=>value;
 
 let credentials='include';
 const LEGACY_TTS_RESPONSE_FORMAT='opus';
+const DEFAULT_TTS_SEGMENTATION={
+    punctuation:'sentence',
+    wordCadence:null
+};
+const TTS_PUNCTUATION_MODES=new Set(['sentence','any','none']);
+// A complete punctuation run is a boundary unless the whole run consists of
+// apostrophe, comma, or dash punctuation joining Unicode letters or numbers.
+// The streaming expression leaves a trailing joining run for the next chunk.
+const TTS_ANY_PUNCTUATION=/(?<!\p{P})(?:(?<![\p{L}\p{N}])\p{P}+(?!\p{P})(?=[\s\S])|\p{P}+(?!\p{P})(?=[^\p{L}\p{N}])|\p{P}*[^\P{P}'\u2019\uFF07,\u060C\u3001\uFF0C\p{Pd}]\p{P}*)(?!\p{P})/gu;
+const TTS_ANY_PUNCTUATION_AT_END=/(?<!\p{P})(?:(?<![\p{L}\p{N}])\p{P}+|\p{P}+(?![\p{L}\p{N}])|\p{P}*[^\P{P}'\u2019\uFF07,\u060C\u3001\uFF0C\p{Pd}]\p{P}*)(?!\p{P})/gu;
 credentials='omit';
 
 const LEGACY_AI_SERVICES=new Set(['OPENAI','OLLAMA','LOCAL_SPEACH']);
@@ -142,6 +152,38 @@ function isPlainAIRecord(value){
     return prototype===Object.prototype||prototype===null;
 }
 
+function normalizeTTSSegmentation(value,current=DEFAULT_TTS_SEGMENTATION){
+    if(value===undefined||value===null){
+        return {...current};
+    }
+    if(!isPlainAIRecord(value)){
+        throw new TypeError('TTS segmentation must be a plain object.');
+    }
+
+    const punctuation=value.punctuation===undefined
+        ?current.punctuation
+        :value.punctuation;
+    if(!TTS_PUNCTUATION_MODES.has(punctuation)){
+        throw new TypeError(
+            'TTS segmentation punctuation must be sentence, any, or none.'
+        );
+    }
+
+    const wordCadence=value.wordCadence===undefined
+        ?current.wordCadence
+        :value.wordCadence;
+    if(
+        wordCadence!==null
+        &&(!Number.isSafeInteger(wordCadence)||wordCadence<1)
+    ){
+        throw new RangeError(
+            'TTS segmentation wordCadence must be null or a positive integer.'
+        );
+    }
+
+    return {punctuation,wordCadence};
+}
+
 function requireAIToolMessageSchemas(value,label='AI tools'){
     if(!Array.isArray(value)){
         throw aiStructuralError(
@@ -1069,6 +1111,7 @@ class AI {
     #speechControlGeneration=0;
     #speechFailureSequence=0;
     #stopOllamaReady=null;
+    #ttsSegmentation={...DEFAULT_TTS_SEGMENTATION};
     #preferenceTuple=completeValue([
         'OPENAI',
         'LOCAL_SPEACH',
@@ -5512,6 +5555,18 @@ class AI {
         return responseJSON;
     }
 
+    get ttsSegmentation(){
+        return {...this.#ttsSegmentation};
+    }
+
+    configureTTSSegmentation(options={}){
+        this.#ttsSegmentation=normalizeTTSSegmentation(
+            options,
+            this.#ttsSegmentation
+        );
+        return this.ttsSegmentation;
+    }
+
     streamTTS(
         text='',
         end=false
@@ -5563,10 +5618,16 @@ class AI {
         let remainder=this.audioMessageChunks;
 
         while(remainder.length>0){
-            const terminator=this.#findSpeechTerminator(remainder,end);
-            let boundary=terminator
-                ?terminator.index+terminator[0].length
-                :-1;
+            const punctuationBoundary=this.#findSpeechPunctuationBoundary(
+                remainder,
+                end
+            );
+            const cadenceBoundary=this.#findSpeechCadenceBoundary(remainder,end);
+            let boundary=punctuationBoundary;
+
+            if(boundary<0||(cadenceBoundary>0&&cadenceBoundary<boundary)){
+                boundary=cadenceBoundary;
+            }
 
             if(boundary<0&&end){
                 boundary=remainder.length;
@@ -5588,7 +5649,14 @@ class AI {
         return segments;
     }
 
-    #findSpeechTerminator(text,end=false){
+    #findSpeechPunctuationBoundary(text,end=false){
+        if(this.#ttsSegmentation.punctuation==='none'){
+            return -1;
+        }
+        if(this.#ttsSegmentation.punctuation==='any'){
+            return this.#findAnySpeechPunctuationBoundary(text,end);
+        }
+
         const pattern=end
             ?/(?:[\u3002\uFF01\uFF1F]|[.!?](?=\s|$))/g
             :/(?:[\u3002\uFF01\uFF1F]|[.!?](?=\s+\S))/g;
@@ -5602,10 +5670,71 @@ class AI {
                 continue;
             }
 
-            return terminator;
+            return this.#includeSpeechBoundaryWhitespace(
+                text,
+                terminator.index+terminator[0].length
+            );
         }
 
-        return null;
+        return -1;
+    }
+
+    #findAnySpeechPunctuationBoundary(text,end=false){
+        const pattern=end
+            ?TTS_ANY_PUNCTUATION_AT_END
+            :TTS_ANY_PUNCTUATION;
+        pattern.lastIndex=0;
+        const firstContent=text.search(/\S/u);
+        let punctuation;
+
+        while((punctuation=pattern.exec(text))){
+            if(firstContent<0||punctuation.index<=firstContent){
+                continue;
+            }
+            const boundary=punctuation.index+punctuation[0].length;
+            return this.#includeSpeechBoundaryWhitespace(text,boundary);
+        }
+
+        return -1;
+    }
+
+    #findSpeechCadenceBoundary(text,end=false){
+        const wordCadence=this.#ttsSegmentation.wordCadence;
+        if(wordCadence===null){
+            return -1;
+        }
+
+        const words=/\S+/gu;
+        let word;
+        let wordCount=0;
+
+        while((word=words.exec(text))){
+            wordCount+=1;
+            if(wordCount!==wordCadence){
+                continue;
+            }
+            const boundary=word.index+word[0].length;
+            if(boundary===text.length&&!end){
+                return -1;
+            }
+            if(boundary<text.length&&!/\s/u.test(text[boundary])){
+                return -1;
+            }
+            return this.#includeSpeechBoundaryWhitespace(text,boundary);
+        }
+
+        return -1;
+    }
+
+    #includeSpeechBoundaryWhitespace(text,boundary){
+        let completeBoundary=boundary;
+        while(
+            completeBoundary<text.length
+            &&/\s/u.test(text[completeBoundary])
+        ){
+            completeBoundary+=1;
+        }
+        return completeBoundary;
     }
 
     #isSpeechAbbreviation(text,periodIndex){

package/runtime/arcane/modules/PersistentAIChatSession.js

@@ -197,24 +197,57 @@ function normalizeSend(input){
             throw new TypeError('messages accepts only tool-result messages.');
         }
         let toolCallId=null;
+        let persistenceMessage=null;
+        let persistenceName=null;
+        let persistenceStatus=null;
         if(role==='tool'){
             if(typeof value.tool_call_id!=='string'||!value.tool_call_id.trim()){
                 throw new TypeError(`${label}.tool_call_id is required for tool messages.`);
             }
             toolCallId=value.tool_call_id;
+            if(value.message!==undefined){
+                if(typeof value.message!=='string'||!value.message.trim()){
+                    throw new TypeError(`${label}.message must contain user-facing text when provided.`);
+                }
+                persistenceMessage=value.message;
+            }
+            if(value.name!==undefined){
+                if(typeof value.name!=='string'||!value.name.trim()){
+                    throw new TypeError(`${label}.name must contain text when provided.`);
+                }
+                persistenceName=value.name;
+            }
+            if(value.status!==undefined){
+                if(typeof value.status!=='string'||!value.status.trim()){
+                    throw new TypeError(`${label}.status must contain text when provided.`);
+                }
+                persistenceStatus=value.status;
+            }
         }else if(value.tool_call_id!==undefined){
             throw new TypeError(`${label}.tool_call_id is supported only for tool messages.`);
         }
         const completeMessage={...value};
         delete completeMessage.persist;
+        delete completeMessage.message;
+        delete completeMessage.name;
+        delete completeMessage.status;
+        const providerMessage={
+            ...completeMessage,
+            content:value.content,
+            role,
+            ...(toolCallId?{tool_call_id:toolCallId}:{})
+        };
         return {
             persist:boolean(value.persist,`${label}.persist`,true),
-            message:{
-                ...completeMessage,
-                content:value.content,
-                role,
-                ...(toolCallId?{tool_call_id:toolCallId}:{})
-            }
+            message:providerMessage,
+            entityMessage:role==='tool'
+                ?{
+                    ...providerMessage,
+                    ...(persistenceMessage?{persistence_message:persistenceMessage}:{}),
+                    ...(persistenceName?{persistence_name:persistenceName}:{}),
+                    ...(persistenceStatus?{persistence_status:persistenceStatus}:{}),
+                }
+                :providerMessage,
         };
     });
     const messagePersist=normalizedMessages[0].persist;
@@ -245,6 +278,7 @@ function normalizeSend(input){
     if(!signalLike(input.signal)) throw new TypeError('signal must be an AbortSignal.');
     return {
         messagePersist,
+        entityRequestMessages:normalizedMessages.map(item=>item.entityMessage),
         requestMessages:normalizedMessages.map(item=>item.message),
         responsePersist,
         request:{...request},
@@ -262,7 +296,7 @@ function fileName(value){
 /**
  * Composes the configured chat session with one automatically selected
  * ChatEntity. Request-only context is delegated to ConfiguredAIChatSession;
- * per-turn persistence affects DBOPFS and memory, never the live model context.
+ * persist:false uses the turn for one request and retains it nowhere afterward.
  */
 class PersistentAIChatSession{
     #activeStream=null;
@@ -550,6 +584,11 @@ class PersistentAIChatSession{
                     );
                 }
             }
+            if(!settings.messagePersist){
+                prepared.rollback();
+                prepared=null;
+                return result;
+            }
             await this.#entity.addTurn({
                 assistantMessage:result.message,
                 extractMemory:this.#memory&&settings.messagePersist&&settings.responsePersist,
@@ -560,9 +599,9 @@ class PersistentAIChatSession{
                     })
                 ),
                 messagePersist:settings.messagePersist,
-                ...(settings.requestMessages.length===1
-                    ?{requestMessage:settings.requestMessages[0]}
-                    :{requestMessages:settings.requestMessages}),
+                ...(settings.entityRequestMessages.length===1
+                    ?{requestMessage:settings.entityRequestMessages[0]}
+                    :{requestMessages:settings.entityRequestMessages}),
                 responsePersist:settings.responsePersist,
             });
             const committed=prepared.commit();