arcane-os 0.3.0 → 0.3.2

package/runtime/arcane/components/chat.html

@@ -4,6 +4,8 @@
         display: block;
         height: 100%;
         min-width: 0;
+        min-inline-size:0;
+        max-inline-size:100%;
         min-height: 0;
         --arcane-chat-gap: var(--arcane-space-3, .75rem);
         --arcane-chat-radius: var(--arcane-radius-large, 1rem);
@@ -15,12 +17,15 @@
         justify-content: flex-end;
         box-sizing: border-box;
         width: min(100%, 72rem);
+        min-width:0;
+        min-inline-size:0;
+        max-inline-size:100%;
         height: 100%;
         min-height: 0;
         margin-inline: auto;
         padding: clamp(.65rem, 1.5vw, 1.25rem);
         gap: var(--arcane-chat-gap);
-        overflow: hidden;
+        overflow: visible;
     }
 
     .chat_area .thinking{
@@ -129,15 +134,34 @@
         border:0;
     }
 
+    .chat_session_status{
+        display:block;
+        flex:0 0 auto;
+        min-height:1.25em;
+        padding-inline:.25rem;
+        color:var(--text-color);
+        font-size:.82rem;
+        overflow-wrap:anywhere;
+    }
+
+    .chat_session_status[data-state="error"]{
+        color:var(--danger-color,var(--text-color));
+    }
+
     .chat_output {
         flex:1 1 auto;
+        display:flow-root;
         box-sizing: border-box;
         width: 100%;
         min-height:0;
+        min-inline-size:0;
+        max-inline-size:100%;
         margin: 0;
         padding: clamp(1rem, 2vw, 1.5rem);
         list-style: none;
+        overflow-x: hidden;
         overflow-y: auto;
+        overscroll-behavior: contain;
         scrollbar-gutter: stable;
         border: 1px solid var(--arcane-border, var(--border-color));
         border-radius: var(--arcane-chat-radius);
@@ -148,12 +172,16 @@
     .chat_output > li {
         box-sizing: border-box;
         width: auto;
+        min-width: 0;
+        min-inline-size:0;
+        max-inline-size:min(92%,48rem);
         max-width: min(92%, 48rem);
         margin: 0 0 .85rem;
         padding: .85rem 1rem;
         clear: both;
         border: 1px solid var(--arcane-border, var(--border-color));
         border-radius: calc(var(--arcane-chat-radius) - .1rem);
+        overflow-x: hidden;
         overflow-wrap: anywhere;
     }
 
@@ -173,6 +201,93 @@
         text-align: right;
     }
 
+    .message_header{
+        display:block;
+        margin:0 0 .65rem;
+    }
+
+    .message_timestamp{
+        display:block;
+        margin-top:.65rem;
+        color:currentColor;
+        font-size:.72rem;
+        line-height:1.2;
+        opacity:.7;
+        text-align:right;
+    }
+
+    .message_tool_calls{
+        display:grid;
+        box-sizing:border-box;
+        width:100%;
+        min-width:0;
+        min-inline-size:0;
+        max-inline-size:100%;
+        max-width:100%;
+        gap:.55rem;
+        margin-top:.75rem;
+    }
+
+    .message_tool_call{
+        box-sizing:border-box;
+        width:100%;
+        min-width:0;
+        min-inline-size:0;
+        max-inline-size:100%;
+        max-width:100%;
+        padding:.65rem;
+        border:1px solid currentColor;
+        border-radius:var(--arcane-radius-small,.3rem);
+        overflow-x:hidden;
+        overflow-wrap:anywhere;
+    }
+
+    .message_tool_message{
+        margin:.45rem 0 0;
+        white-space:pre-wrap;
+        overflow-wrap:anywhere;
+    }
+
+    .message_tool_details{
+        box-sizing:border-box;
+        width:100%;
+        min-width:0;
+        min-inline-size:0;
+        max-inline-size:100%;
+        max-width:100%;
+        margin-top:.55rem;
+        overflow-x:hidden;
+    }
+
+    .message_tool_details summary{
+        cursor:pointer;
+        overflow-wrap:anywhere;
+    }
+
+    .message_tool_call pre{
+        box-sizing:border-box;
+        width:100%;
+        min-width:0;
+        min-inline-size:0;
+        max-inline-size:100%;
+        max-width:100%;
+        margin:.45rem 0 0;
+        white-space:pre-wrap;
+        word-break:break-word;
+        overflow-x:auto;
+        overflow-wrap:anywhere;
+    }
+
+    .message_tool_call code{
+        display:block;
+        box-sizing:border-box;
+        min-inline-size:0;
+        max-inline-size:100%;
+        white-space:inherit;
+        word-break:inherit;
+        overflow-wrap:anywhere;
+    }
+
     .chat_output li ul,
     .chat_output li ol {
         display: block;
@@ -230,6 +345,7 @@
     }
 
     .ai_activation_copy {
+        flex:1 1 auto;
         min-width:0;
     }
 
@@ -244,6 +360,18 @@
         font-size:.9rem;
     }
 
+    .ai_activation_progress{
+        display:block;
+        width:100%;
+        height:.6rem;
+        margin-block-start:.7rem;
+        accent-color:var(--arcane-action,var(--primary-color));
+    }
+
+    .ai_activation_progress[hidden]{
+        display:none;
+    }
+
     .ai_activation button {
         flex:0 0 auto;
         min-height:2.65rem;
@@ -271,7 +399,6 @@
         box-sizing: border-box;
         width: 100%;
         min-height: 3rem;
-        max-height: 10rem;
         margin: 0;
         padding: .82rem .9rem;
         border: 1px solid var(--arcane-border, var(--border-color));
@@ -281,8 +408,8 @@
         font: inherit;
         font-size: 1rem;
         line-height: 1.35;
-        resize: none;
-        overflow-y: auto;
+        resize: vertical;
+        overflow: visible;
     }
 
     .chat_input:focus-visible {
@@ -380,6 +507,16 @@
         outline-offset: .18rem;
     }
 
+    :host([presentation="basic"]) .chat_input_area {
+        grid-template-columns:minmax(0,1fr) auto;
+    }
+
+    :host([presentation="basic"]) #chat_upload,
+    :host([presentation="basic"]) #file_upload_input,
+    :host([presentation="basic"]) .controls {
+        display:none;
+    }
+
     @media (max-width: 44rem) {
         .chat_area {
             padding: var(--arcane-space-2, .5rem);
@@ -453,8 +590,7 @@
         background: var(--border-color);
         padding:.4em;
         border: 1px solid var(--accent-color);
-        max-height: 15em;
-        overflow: auto;
+        overflow: visible;
     }
 </style>
 
@@ -479,6 +615,13 @@
         >Starting the elapsed timer.</span>
     </section>
     <ul type='text' class='chat_output' id='chat_output' tabindex='-1' aria-label='Conversation transcript'></ul>
+    <output
+        id="chat_session_status"
+        class="chat_session_status"
+        role="status"
+        aria-live="polite"
+        data-state="idle"
+    >Chat session is not connected.</output>
     <section
         id="ai_activation"
         class="ai_activation"
@@ -490,11 +633,17 @@
         <span class="ai_activation_copy">
             <strong id="ai_activation_title">Language model not active</strong>
             <span id="ai_activation_status">Start the selected language model to enable chat.</span>
+            <progress
+                id="ai_activation_progress"
+                class="ai_activation_progress"
+                aria-label="Language model activation progress"
+                hidden
+            ></progress>
         </span>
         <button type="button" id="ai_activation_button">Start language model</button>
     </section>
     <div class="chat_input_area">
-        <textarea type='text' class='chat_input' id='chat_input'></textarea>
+        <textarea type='text' class='chat_input' id='chat_input' placeholder='Message' aria-label='Message'></textarea>
         <button type="button" id="chat_upload" class="chat_upload" title="Upload files" aria-label="Upload files">
             <img class='upload-icon' src="./arcane/img/upload.svg" />
         </button>
@@ -503,7 +652,7 @@
             <img class='send-icon' src="./arcane/img/send.svg" />
         </button>
     </div>
-    <html-import id="speech" href="./arcane/components/speech.html?v=3"></html-import>
+    <span id="speech_mount"></span>
     <section class="controls">
         <select id="languages">
             <option value="english" selected>English</option>
@@ -690,12 +839,27 @@
     }=await import('arcane-os/event-manager');
 
     const host=this;
+    const componentURL=new URL(
+        host.getAttribute('href')||'./arcane/components/chat.html',
+        document.baseURI
+    );
+    const speechMount=host.shadowRoot.querySelector('#speech_mount');
+    const speechImport=document.createElement('html-import');
+    speechImport.id='speech';
+    speechImport.setAttribute(
+        'href',
+        new URL('./speech.html?v=3',componentURL).href
+    );
+    speechMount.replaceWith(speechImport);
     const events=createArcaneEventSource(
         host,
         {
             source:'arcane.component.chat',
             eventTypes:[
                 'chat-ready',
+                'chat-session-bound',
+                'chat-session-message',
+                'chat-session-error',
                 'chat-send-message',
                 'chat-send-error',
                 'chat-file-uploaded',
@@ -714,7 +878,8 @@
     const textArea=shadowRoot.querySelector('#chat_input');
     const chatOutput = shadowRoot.querySelector('#chat_output');
     const send = shadowRoot.querySelector('#chat_submit');
-    const speech = shadowRoot.querySelector('#speech');
+    const chatSessionStatus=shadowRoot.querySelector('#chat_session_status');
+    const speech = speechImport;
     const uploadBtn = shadowRoot.querySelector('#chat_upload');
     const fileInput = shadowRoot.querySelector('#file_upload_input');
     const conversationTimeboxPanel=shadowRoot.querySelector('#conversation_timebox');
@@ -723,17 +888,20 @@
     const aiActivationPanel=shadowRoot.querySelector('#ai_activation');
     const aiActivationTitle=shadowRoot.querySelector('#ai_activation_title');
     const aiActivationStatus=shadowRoot.querySelector('#ai_activation_status');
+    const aiActivationProgress=shadowRoot.querySelector('#ai_activation_progress');
     const aiActivationButton=shadowRoot.querySelector('#ai_activation_button');
     const [
         {default:MD},
         {default:FileEntity},
         {ConversationSubmissionBarrier,requireConversationTimeboxDelivery},
-        {requestAIRuntimeIntent,subscribeAIRuntimeState}
+        {requestAIRuntimeIntent,subscribeAIRuntimeState},
+        {createPersistentAIChatSession}
     ]=await Promise.all([
         import('../modules/MD.js'),
         import('../entities/File.js'),
         import('../modules/ConversationTimebox.js'),
-        import('../modules/AIRuntimeState.js')
+        import('../modules/AIRuntimeState.js'),
+        import('../modules/PersistentAIChatSession.js')
     ]);
 
     host.language=host.language||'English';
@@ -746,6 +914,7 @@
     let latestAIRuntimeRoles=null;
     const hostSubmissionBarrier=new ConversationSubmissionBarrier();
     const aiRuntimeStateAbortController=new AbortController();
+    const AI_TTS_FAILURE_EVENT='ai-tts-failure';
     let programmaticSubmissionQueue=Promise.resolve(true);
     let conversationTimeboxController=null;
     let conversationTimeboxUnsubscribe=null;
@@ -754,10 +923,23 @@
     let hostSubmissionGeneration=0;
     let eventOperationSequence=0;
     let destroyed=false;
+    let boundChatSession=null;
+    let boundChatAI=null;
+    let sessionBindingPending=false;
+    let sessionMessagePending=false;
+    let activeSessionMessageToken=null;
+    let sessionBindingGeneration=0;
+    let sessionMessageSequence=0;
+    let pendingStructuralToolCall=null;
+    let pendingStructuralToolMessage='';
     const activeSubmissionOwnerships=new Set();
-    const conversationTimeboxRetryDelays=Object.freeze([0,500,1_500]);
-    const chatReasons=Object.freeze({
+    const conversationTimeboxRetryDelays=[0,500,1_500];
+    const chatReasons={
         ready:'chat-ready',
+        sessionBindingCompleted:'session-binding-completed',
+        sessionBindingRejected:'session-binding-rejected',
+        sessionMessageCompleted:'session-message-completed',
+        sessionMessageRejected:'session-message-rejected',
         messageSubmissionRequested:'message-submission-requested',
         messageSubmissionCancelled:'message-submission-cancelled',
         callerSignalAborted:'caller-signal-aborted',
@@ -771,8 +953,12 @@
         languageModelActivationRejected:'language-model-activation-rejected',
         speechSynthesisRejected:'speech-synthesis-rejected',
         conversationTimeboxDeliveryRejected:'conversation-timebox-delivery-rejected'
-    });
-    const chatErrorCodes=Object.freeze({
+    };
+    const chatErrorCodes={
+        destroyed:'ARCANE_CHAT_DESTROYED',
+        sessionAlreadyBound:'ARCANE_CHAT_SESSION_ALREADY_BOUND',
+        sessionBindingRejected:'ARCANE_CHAT_SESSION_BINDING_REJECTED',
+        sessionMessageRejected:'ARCANE_CHAT_SESSION_MESSAGE_REJECTED',
         messageSubmissionAborted:'ARCANE_CHAT_MESSAGE_SUBMISSION_ABORTED',
         languageModelActivationRejected:'ARCANE_CHAT_LANGUAGE_MODEL_ACTIVATION_REQUEST_REJECTED',
         hostMessageSubmissionRejected:'ARCANE_CHAT_HOST_MESSAGE_SUBMISSION_REJECTED',
@@ -780,7 +966,7 @@
         languageChangeCallbackRejected:'ARCANE_CHAT_LANGUAGE_CHANGE_CALLBACK_REJECTED',
         speechSynthesisRejected:'ARCANE_CHAT_SPEECH_SYNTHESIS_REQUEST_REJECTED',
         conversationTimeboxDeliveryRejected:'ARCANE_CHAT_CONVERSATION_TIMEBOX_DELIVERY_REJECTED'
-    });
+    };
 
     function nextChatOperationId(kind){
         eventOperationSequence+=1;
@@ -826,15 +1012,528 @@
 
     function publicErrorFields(error,boundaryCode){
         let causeCode='';
+        let message='';
         try{
-            causeCode=typeof error?.code==='string'?error.code.trim():'';
+            causeCode=typeof error?.code==='string'?error.code:'';
+            message=typeof error?.message==='string'?error.message:'';
         }catch{}
-        return Object.freeze({
+        return {
+            error,
             code:boundaryCode,
-            ...(causeCode&&causeCode!==boundaryCode?{causeCode}:{})
+            ...(causeCode&&causeCode!==boundaryCode?{causeCode}:{}),
+            ...(message?{message}:{})
+        };
+    }
+
+    function chatError(message,code){
+        const error=new Error(message);
+        error.code=code;
+        return error;
+    }
+
+    function isPlainRecord(value){
+        return Boolean(value)
+            &&typeof value==='object'
+            &&!Array.isArray(value)
+            &&Object.getPrototypeOf(value)===Object.prototype;
+    }
+
+    function visibleErrorMessage(error,fallback){
+        try{
+            // Only errors deliberately classified by their owner may provide UI copy.
+            // Provider and protocol diagnostics remain complete in console/events.
+            if(error?.userSafe===true){
+                const message=typeof error.userMessage==='string'
+                    ?error.userMessage
+                    :error.message;
+                if(typeof message==='string'&&message.trim()){
+                    return message;
+                }
+            }
+        }catch{}
+        return fallback;
+    }
+
+    function visibleProgressText(value,fallback,field){
+        if(typeof value==='string'){
+            return value||fallback;
+        }
+        if(value&&typeof value==='object'){
+            console.error(`Arcane chat progress ${field} is not text.`,value);
+            return visibleErrorMessage(value,fallback);
+        }
+        if(value!==undefined&&value!==null&&value!==''){
+            const error=new TypeError(
+                `Arcane chat progress ${field} must be text.`,
+                {cause:value}
+            );
+            console.error(`Arcane chat progress ${field} is not text.`,error);
+        }
+        return fallback;
+    }
+
+    function setSessionStatus(state,message){
+        const status={state:String(state),message:String(message)};
+        host.sessionStatus=status;
+        chatSessionStatus.dataset.state=status.state;
+        chatSessionStatus.value=status.message;
+        chatSessionStatus.textContent=status.message;
+        return status;
+    }
+
+    function compatibleChatSession(session){
+        return Boolean(session)
+            &&typeof session==='object'
+            &&typeof session.ready==='function'
+            &&typeof session.history==='function'
+            &&typeof session.send==='function';
+    }
+
+    function scrollTranscriptToBottom(){
+        chatOutput.scrollTop=chatOutput.scrollHeight;
+        return true;
+    }
+
+    function transcriptTime(timestamp){
+        const time=chatOutput.ownerDocument.createElement('time');
+        time.className='message_timestamp';
+        const value=timestamp instanceof Date
+            ?timestamp
+            :new Date(timestamp);
+        if(timestamp!==undefined&&timestamp!==null&&Number.isFinite(value.getTime())){
+            time.dateTime=value.toISOString();
+            time.textContent=value.toLocaleTimeString([],{
+                hour:'2-digit',
+                minute:'2-digit',
+                hourCycle:'h23'
+            });
+            time.title=value.toLocaleString();
+        }else{
+            time.textContent='Time unavailable';
+            time.setAttribute('aria-label','Message time unavailable');
+        }
+        return time;
+    }
+
+    function normalizeVisibleToolCalls(value){
+        if(value===undefined) return [];
+        if(!Array.isArray(value)){
+            const failure=new TypeError('Chat session tool calls must be an array.');
+            failure.code='AI_CHAT_INVALID_TOOL_CALL';
+            throw failure;
+        }
+        return value.map((call,index)=>{
+            if(
+                !call
+                ||typeof call!=='object'
+                ||Array.isArray(call)
+                ||call.type!=='function'
+                ||!call.function
+                ||typeof call.function!=='object'
+                ||Array.isArray(call.function)
+                ||typeof call.id!=='string'
+                ||!call.id.trim()
+                ||typeof call.function.name!=='string'
+                ||!call.function.name.trim()
+                ||typeof call.function.arguments!=='string'
+            ){
+                const failure=new TypeError(`Chat session tool call ${index+1} is invalid.`);
+                failure.code='AI_CHAT_INVALID_TOOL_CALL';
+                throw failure;
+            }
+            structuralToolMessage(call);
+            return call;
         });
     }
 
+    function structuralToolMessage(call){
+        let argumentsRecord;
+        try{
+            argumentsRecord=JSON.parse(call.function.arguments);
+        }catch(error){
+            const failure=new TypeError(
+                'Structural tool call arguments must encode a JSON object.',
+                {cause:error}
+            );
+            failure.code='AI_CHAT_INVALID_TOOL_CALL';
+            throw failure;
+        }
+        if(!isPlainRecord(argumentsRecord)){
+            const failure=new TypeError(
+                'Structural tool call arguments must encode a JSON object.'
+            );
+            failure.code='AI_CHAT_INVALID_TOOL_CALL';
+            throw failure;
+        }
+        if(typeof argumentsRecord.message!=='string'||!argumentsRecord.message.trim()){
+            const failure=new TypeError(
+                'Structural tool call arguments must include a nonempty user-facing message.'
+            );
+            failure.code='AI_CHAT_TOOL_MESSAGE_REQUIRED';
+            throw failure;
+        }
+        return argumentsRecord.message;
+    }
+
+    function setPendingStructuralToolCall(call=null){
+        if(call===null){
+            pendingStructuralToolCall=null;
+            pendingStructuralToolMessage='';
+            return null;
+        }
+        pendingStructuralToolMessage=structuralToolMessage(call);
+        pendingStructuralToolCall={
+            id:call.id,
+            type:'function',
+            function:{
+                name:call.function.name,
+                arguments:call.function.arguments
+            }
+        };
+        return pendingStructuralToolCall;
+    }
+
+    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 pendingStructuralToolSummary(){
+        return pendingStructuralToolCall
+            ?{
+                id:pendingStructuralToolCall.id,
+                name:pendingStructuralToolCall.function.name,
+                message:pendingStructuralToolMessage
+            }
+            :null;
+    }
+
+    function appendVisibleToolCall(item,call){
+        const toolCalls=item.querySelector('.message_tool_calls')
+            ??item.ownerDocument.createElement('section');
+        if(!toolCalls.classList.contains('message_tool_calls')){
+            toolCalls.className='message_tool_calls';
+            toolCalls.setAttribute('aria-label','Tool calls');
+            item.insertBefore(toolCalls,item.querySelector('.message_timestamp'));
+        }
+        const existing=[...toolCalls.children].find(
+            candidate=>candidate.dataset.toolCallId===call.id
+        );
+        if(existing) return existing;
+        const entry=item.ownerDocument.createElement('article');
+        entry.className='message_tool_call';
+        entry.dataset.toolCallId=call.id;
+        const heading=item.ownerDocument.createElement('strong');
+        heading.textContent=`Tool: ${call.function.name}`;
+        const userMessage=item.ownerDocument.createElement('p');
+        userMessage.className='message_tool_message';
+        userMessage.textContent=structuralToolMessage(call);
+        const details=item.ownerDocument.createElement('details');
+        details.className='message_tool_details';
+        const summary=item.ownerDocument.createElement('summary');
+        summary.textContent='Tool call details';
+        const argumentsBlock=item.ownerDocument.createElement('pre');
+        const code=item.ownerDocument.createElement('code');
+        code.textContent=call.function.arguments;
+        argumentsBlock.append(code);
+        details.append(summary,argumentsBlock);
+        entry.append(heading,userMessage,details);
+        toolCalls.append(entry);
+        scrollTranscriptToBottom();
+        return entry;
+    }
+
+    function setTranscriptMessageContent(item,content,timestamp){
+        if(typeof content!=='string'){
+            throw new TypeError('Chat session message content must be a string.');
+        }
+        item.querySelector('.thinking')?.remove();
+        const markdown=item.querySelector('.markdown');
+        markdown.raw=content;
+        markdown.innerHTML=new MD(content).rendered;
+        if(timestamp!==undefined){
+            item.querySelector('.message_timestamp')?.replaceWith(
+                transcriptTime(timestamp)
+            );
+        }
+        scrollTranscriptToBottom();
+        return item;
+    }
+
+    function setTranscriptMessageTimestamp(item,timestamp){
+        const current=item?.querySelector?.('.message_timestamp');
+        if(!current||timestamp===undefined||timestamp===null){
+            return false;
+        }
+        current.replaceWith(transcriptTime(timestamp));
+        scrollTranscriptToBottom();
+        return true;
+    }
+
+    function latestCommittedTranscriptTurn(transcript,requestMessage){
+        if(!Array.isArray(transcript)) return null;
+        const requestRole=requestMessage?.role??'user';
+        const requestContent=requestMessage?.content;
+        for(let index=transcript.length-1;index>0;index--){
+            const response=transcript[index];
+            const request=transcript[index-1];
+            if(
+                response?.role==='assistant'
+                &&request?.role===requestRole
+                &&request.content===requestContent
+                &&(
+                    requestRole!=='tool'
+                    ||request.tool_call_id===requestMessage.tool_call_id
+                )
+            ){
+                return {request,response};
+            }
+        }
+        return null;
+    }
+
+    function createTranscriptMessage(role,content,name,{timestamp,toolCalls}={}){
+        if(typeof content!=='string'){
+            throw new TypeError('Chat session message content must be a string.');
+        }
+        const item=chatOutput.ownerDocument.createElement('li');
+        item.className=role==='user'?'user':'ai';
+        item.dataset.role=role;
+        const header=chatOutput.ownerDocument.createElement('header');
+        header.className='message_header';
+        const heading=chatOutput.ownerDocument.createElement('strong');
+        heading.textContent=name;
+        header.append(heading);
+        const markdown=chatOutput.ownerDocument.createElement('div');
+        markdown.className='markdown';
+        markdown.raw=content;
+        markdown.innerHTML=new MD(content).rendered;
+        item.append(header,markdown,transcriptTime(timestamp));
+        for(const call of normalizeVisibleToolCalls(toolCalls)){
+            appendVisibleToolCall(item,call);
+        }
+        return item;
+    }
+
+    function appendTranscriptMessage(role,content,name,{timestamp=Date.now(),toolCalls}={}){
+        const item=createTranscriptMessage(role,content,name,{timestamp,toolCalls});
+        chatOutput.append(item);
+        scrollTranscriptToBottom();
+        return item;
+    }
+
+    function renderSessionHistory(history){
+        if(!Array.isArray(history)){
+            throw new TypeError('Chat session history must be an array.');
+        }
+        const fragment=chatOutput.ownerDocument.createDocumentFragment();
+        const rendered=[];
+        let restoredPendingToolCall=null;
+        for(const message of history){
+            if(!message||typeof message!=='object'||Array.isArray(message)){
+                throw new TypeError('Chat session history contains an invalid message.');
+            }
+            if(message.role==='system'){
+                if(restoredPendingToolCall){
+                    throw chatError(
+                        'Saved chat contains a system record before its pending structural tool result.',
+                        'AI_CHAT_INCOHERENT_PERSISTENCE'
+                    );
+                }
+                continue;
+            }
+            if(!['assistant','tool','user'].includes(message.role)){
+                throw new TypeError(`Chat session history contains an unsupported role: ${message.role}.`);
+            }
+            if(typeof message.content!=='string'){
+                throw new TypeError('Chat session history message content must be a string.');
+            }
+            if(message.role==='tool'&&!message.content.trim()){
+                throw chatError(
+                    'Saved chat contains a blank structural tool result.',
+                    'AI_CHAT_INVALID_TOOL_MESSAGE'
+                );
+            }
+            const calls=normalizeVisibleToolCalls(message.tool_calls);
+            if(calls.length>1){
+                throw chatError(
+                    'Saved chat contains parallel structural tool calls.',
+                    'AI_CHAT_PARALLEL_TOOLS_UNSUPPORTED'
+                );
+            }
+            if(message.role!=='assistant'&&calls.length){
+                throw chatError(
+                    'Only assistant records may contain structural tool calls.',
+                    'AI_CHAT_INVALID_TOOL_CALL'
+                );
+            }
+            if(message.role==='tool'){
+                if(
+                    !restoredPendingToolCall
+                    ||typeof message.tool_call_id!=='string'
+                    ||message.tool_call_id!==restoredPendingToolCall.id
+                ){
+                    throw chatError(
+                        'Saved chat contains a tool result that does not match its pending structural tool call.',
+                        'AI_CHAT_INVALID_TOOL_MESSAGE'
+                    );
+                }
+                restoredPendingToolCall=null;
+            }else{
+                if(restoredPendingToolCall){
+                    throw chatError(
+                        'Saved chat continues before its pending structural tool result.',
+                        'AI_CHAT_TOOL_RESULT_REQUIRED'
+                    );
+                }
+                if(calls.length){
+                    restoredPendingToolCall=calls[0];
+                }
+            }
+            const name=message.role==='user'
+                ?host.name
+                :message.role==='tool'
+                ?'Tool'
+                :host.aiName;
+            const item=createTranscriptMessage(message.role,message.content,name,{
+                timestamp:message.timestamp,
+                toolCalls:calls,
+            });
+            fragment.append(item);
+            rendered.push(item);
+        }
+        setPendingStructuralToolCall(restoredPendingToolCall);
+        chatOutput.replaceChildren(fragment);
+        scrollTranscriptToBottom();
+        return rendered;
+    }
+
+    async function bindSession(options={}){
+        if(destroyed){
+            throw chatError(
+                'The chat component has been destroyed and cannot bind a session.',
+                chatErrorCodes.destroyed
+            );
+        }
+        if(!isPlainRecord(options)){
+            throw new TypeError('Chat session binding options must be a plain object.');
+        }
+        const unsupported=Object.keys(options).find(
+            key=>!['ai','session','sessionOptions'].includes(key)
+        );
+        if(unsupported){
+            throw new TypeError(`Unsupported chat session binding option: ${unsupported}.`);
+        }
+        if(sessionBindingPending||boundChatSession){
+            throw chatError(
+                'This chat component already has a session binding.',
+                chatErrorCodes.sessionAlreadyBound
+            );
+        }
+        const ai=options.ai??null;
+        const suppliedSession=options.session??null;
+        const sessionOptions=options.sessionOptions??{};
+        if((ai===null)===(suppliedSession===null)){
+            throw new TypeError('Specify exactly one of ai or session when binding chat.');
+        }
+        if(!isPlainRecord(sessionOptions)){
+            throw new TypeError('sessionOptions must be a plain object.');
+        }
+        if(suppliedSession!==null&&Object.keys(sessionOptions).length>0){
+            throw new TypeError('sessionOptions cannot be used with an existing session.');
+        }
+        if(suppliedSession!==null&&!compatibleChatSession(suppliedSession)){
+            throw new TypeError('session must expose ready(), history(), and send().');
+        }
+
+        const operationId=nextChatOperationId('session-binding');
+        const generation=++sessionBindingGeneration;
+        sessionBindingPending=true;
+        setSessionStatus('binding','Opening chat session…');
+        try{
+            const session=suppliedSession??await createPersistentAIChatSession({
+                ...sessionOptions,
+                ai
+            });
+            await session.ready();
+            const history=typeof session.transcript==='function'
+                ?await session.transcript()
+                :await session.history();
+            if(destroyed||generation!==sessionBindingGeneration){
+                throw chatError(
+                    'The chat component was destroyed before session binding completed.',
+                    chatErrorCodes.destroyed
+                );
+            }
+            renderSessionHistory(history);
+            boundChatSession=session;
+            boundChatAI=ai??session.ai??null;
+            host.session=session;
+            setSessionStatus(
+                pendingStructuralToolMessage?'tool':'ready',
+                pendingStructuralToolMessage||'Chat ready.'
+            );
+            applyAIAvailability(host.aiAvailability);
+            sessionBindingPending=false;
+            const detail={
+                chat:host,
+                session,
+                ai:boundChatAI,
+                history,
+                pendingTool:pendingStructuralToolSummary()
+            };
+            dispatchChatEvent(
+                'chat-session-bound',
+                detail,
+                {
+                    bubbles:true,
+                    composed:true,
+                    operationId,
+                    publicDetail:{
+                        ...detail,
+                        reason:chatReasons.sessionBindingCompleted
+                    }
+                }
+            );
+            return session;
+        }catch(error){
+            if(!destroyed&&generation===sessionBindingGeneration){
+                const internalProtocolFailure=internalStructuralToolFailure(error);
+                console.error('Arcane saved chat could not be opened.',error);
+                const message=internalProtocolFailure
+                    ?'This saved chat could not be opened.'
+                    :visibleErrorMessage(error,'The chat session could not be opened.');
+                setSessionStatus('error',message);
+                dispatchChatEvent(
+                    'chat-session-error',
+                    {phase:'binding',error,options},
+                    {
+                        bubbles:true,
+                        composed:true,
+                        operationId,
+                        publicDetail:{
+                            phase:'binding',
+                            options,
+                            reason:chatReasons.sessionBindingRejected,
+                            ...publicErrorFields(
+                                error,
+                                chatErrorCodes.sessionBindingRejected
+                            )
+                        }
+                    }
+                );
+            }
+            throw error;
+        }finally{
+            if(generation===sessionBindingGeneration){
+                sessionBindingPending=false;
+            }
+        }
+    }
+
     function isAbortSignal(value){
         return value!==null
             &&typeof value==='object'
@@ -879,11 +1578,11 @@
             return true;
         }
 
-        const ownership=Object.freeze({
+        const ownership={
             signal:controller.signal,
             abort:abortChatSubmission,
             release:releaseChatSubmissionOwnership
-        });
+        };
         activeSubmissionOwnerships.add(ownership);
 
         function followAbortSignal(signal,fallbackReason){
@@ -940,6 +1639,7 @@
         panel:aiActivationPanel,
         title:aiActivationTitle,
         status:aiActivationStatus,
+        progress:aiActivationProgress,
         button:aiActivationButton
     });
 
@@ -949,8 +1649,18 @@
     host.setInitialSpeechMuted=setInitialSpeechMuted;
     host.setConversationComplete=setConversationComplete;
     host.bindConversationTimebox=bindConversationTimebox;
+    host.bindSession=bindSession;
     host.submitMessage=submitMessage;
+    host.submitToolResult=submitToolResult;
+    Object.defineProperty(host,'pendingTool',{
+        configurable:true,
+        enumerable:true,
+        get:pendingStructuralToolSummary
+    });
     host.destroy=destroy;
+    host.session=null;
+    host.sessionStatus={state:'idle',message:'Chat session is not connected.'};
+    host.modelName=typeof host.modelName==='string'?host.modelName:'';
     host.aiAvailability={llm:false,stt:false,tts:false};
     host.conversationComplete=false;
     applyAIAvailability(host.aiAvailability);
@@ -965,6 +1675,17 @@
         destroy,
         {once:true,signal:aiRuntimeStateAbortController.signal}
     );
+    window.addEventListener(
+        AI_TTS_FAILURE_EVENT,
+        function reportActiveRuntimeTTSFailure(event){
+            const aiRuntime=boundChatAI??globalThis.ai;
+            if(!aiRuntime||event.detail?.ai!==aiRuntime){
+                return;
+            }
+            reportTTSError(event.detail?.error,event.detail?.boundary);
+        },
+        {signal:aiRuntimeStateAbortController.signal}
+    );
 
     function setConversationComplete(complete=true){
         if(typeof complete!=='boolean'){
@@ -975,11 +1696,14 @@
         chatArea.dataset.conversationComplete=String(complete);
         textArea.disabled=complete;
         uploadBtn.disabled=complete;
-        send.disabled=complete||!host.aiAvailability.llm;
+        send.disabled=complete
+            ||!host.aiAvailability.llm
+            ||sessionMessagePending
+            ||Boolean(pendingStructuralToolMessage);
         if(complete){
             textArea.blur?.();
             chatOutput.focus?.({preventScroll:true});
-            chatOutput.scrollTop=chatOutput.scrollHeight;
+            scrollTranscriptToBottom();
         }
         return complete;
     }
@@ -1020,7 +1744,7 @@
             status=''
         }={}
     ){
-        const messageId=String(id).trim();
+        const messageId=String(id);
         const normalizedTotal=Number.isFinite(Number(total))
             ?Math.max(0,Math.floor(Number(total)))
             :0;
@@ -1075,19 +1799,21 @@
         const warningLabel=normalizedFailed>0
             ?` · ${normalizedFailed} warning${normalizedFailed===1?'':'s'}`
             :'';
+        const visibleLabel=visibleProgressText(label,'Working','label');
+        const visibleStatus=visibleProgressText(status,'Streaming','status');
         const progressStatus=isIndeterminate
-            ?`${String(status||'Streaming')}${warningLabel}`
+            ?`${visibleStatus}${warningLabel}`
             :`${normalizedCurrent} of ${normalizedTotal}${warningLabel}`;
         const percent=normalizedTotal>0
             ?normalizedCurrent/normalizedTotal*100
             :0;
 
-        labelElement.textContent=String(label||'Working');
+        labelElement.textContent=visibleLabel;
         countElement.textContent=progressStatus;
         progress.classList.toggle('indeterminate',isIndeterminate);
         fill.style.width=isIndeterminate?'32%':`${percent}%`;
         progress.setAttribute('role','progressbar');
-        progress.setAttribute('aria-label',String(label||'Working'));
+        progress.setAttribute('aria-label',visibleLabel);
         if(isIndeterminate){
             progress.removeAttribute('aria-valuemin');
             progress.removeAttribute('aria-valuemax');
@@ -1099,9 +1825,9 @@
         }
         progress.setAttribute(
             'aria-valuetext',
-            `${String(label||'Working')} ${progressStatus}`
+            `${visibleLabel} ${progressStatus}`
         );
-        chatOutput.scrollTop=chatOutput.scrollHeight;
+        scrollTranscriptToBottom();
         return true;
     }
 
@@ -1134,8 +1860,13 @@
 
     function applyAIAvailability(availability){
         host.aiAvailability={...availability};
-        send.disabled=host.conversationComplete||!availability.llm;
-        send.title=availability.llm
+        send.disabled=host.conversationComplete
+            ||!availability.llm
+            ||sessionMessagePending
+            ||Boolean(pendingStructuralToolMessage);
+        send.title=pendingStructuralToolMessage
+            ?pendingStructuralToolMessage
+            :availability.llm
             ?'Send message'
             :'The selected language model service is unavailable.';
         send.setAttribute('aria-label',send.title);
@@ -1146,6 +1877,7 @@
         panel,
         title,
         status,
+        progress,
         button,
         publish=dispatchChatEvent,
         createOperationId=nextChatOperationId,
@@ -1159,13 +1891,6 @@
         let requestGeneration=0;
         let destroyed=false;
 
-        function visibleError(error,fallback){
-            const message=typeof error?.message==='string'
-                ?error.message.trim()
-                :'';
-            return (message||fallback).slice(0,240);
-        }
-
         function cancellation(error){
             return error?.name==='AbortError'
                 ||['ARCANE_AI_REQUEST_ABORTED','AI_CHAT_ABORTED'].includes(error?.code);
@@ -1178,15 +1903,76 @@
                 &&role.modelId.length>0;
         }
 
+        function modelDisplayName(){
+            const configured=typeof host.modelName==='string'
+                ?host.modelName.trim()
+                :'';
+            return configured||role?.modelId||'the selected language model';
+        }
+
+    function byteProgressUnit(value){
+        const unit=String(value??'')
+            .trim()
+            .toLowerCase()
+            .replace(/[\s_-]+/g,'');
+        return unit.includes('byte')
+            ||unit.includes('octet')
+            ||/^(?:[kmgtpe]?i?b)(?:(?:\/|per)?(?:s|sec|second))?$/u.test(unit);
+        }
+
+        function determinateProgress(){
+            const total=Number(role?.progress?.total);
+            const completed=Number(role?.progress?.completed);
+            const unit=typeof role?.progress?.unit==='string'&&role.progress.unit
+                ?role.progress.unit
+                :'items';
+            if(
+                byteProgressUnit(unit)
+                ||!Number.isFinite(total)
+                ||total<=0
+                ||!Number.isFinite(completed)
+            ){
+                return null;
+            }
+            return {
+                completed:Math.max(0,completed),
+                total,
+                unit
+            };
+        }
+
         function progressMessage(){
-            if(!role?.progress){
-                return 'The selected language model is loading.';
+            const measured=determinateProgress();
+            const phase=typeof role?.progress?.phase==='string'&&role.progress.phase
+                ?role.progress.phase
+                :'loading';
+            const parts=[
+                `Loading ${modelDisplayName()} through the Arcane SDK`,
+                phase
+            ];
+            if(measured){
+                parts.push(`${measured.completed} of ${measured.total} ${measured.unit}`);
+            }
+            parts.push('The first activation can take several minutes; keep this tab open');
+            return parts.join(' · ');
+        }
+
+        function renderProgress(){
+            const visible=requestPending||role?.state==='loading';
+            progress.hidden=!visible;
+            if(!visible){
+                progress.removeAttribute('value');
+                progress.removeAttribute('max');
+                return;
+            }
+            const measured=determinateProgress();
+            if(!measured){
+                progress.removeAttribute('value');
+                progress.removeAttribute('max');
+                return;
             }
-            const progress=role.progress;
-            const amount=progress.total===null
-                ?`${progress.completed} ${progress.unit}`
-                :`${progress.completed} of ${progress.total} ${progress.unit}`;
-            return `${progress.phase}, ${amount}${progress.heartbeat?', active heartbeat':''}.`;
+            progress.max=measured.total;
+            progress.value=Math.min(measured.completed,measured.total);
         }
 
         function render(){
@@ -1200,6 +1986,7 @@
                 'aria-busy',
                 String(requestPending||['loading','unloading'].includes(role?.state))
             );
+            renderProgress();
             if(!visible){
                 return;
             }
@@ -1211,9 +1998,9 @@
                 return;
             }
             if(role.state==='loading'){
-                title.textContent='Starting language model';
+                title.textContent=`Loading ${modelDisplayName()}`;
                 status.textContent=progressMessage();
-                button.textContent='Cancel loading';
+                button.textContent='Cancel activation';
                 button.disabled=false;
                 return;
             }
@@ -1226,7 +2013,7 @@
             }
             if(role.state==='error'||requestError){
                 title.textContent='Language model activation failed';
-                status.textContent=requestError||visibleError(
+                status.textContent=requestError||visibleErrorMessage(
                     role.error,
                     'The selected language model could not start.'
                 );
@@ -1258,8 +2045,8 @@
                 return false;
             }
             requestError='';
-            const intent=Object.freeze({role:'llm',action,reason:'user'});
-            const request=Object.freeze({intent,state:role});
+            const intent={role:'llm',action,reason:'user'};
+            const request={intent,state:role};
             const operationId=typeof role?.operationId==='string'&&role.operationId
                 ?role.operationId
                 :createOperationId('llm-activation');
@@ -1272,12 +2059,7 @@
                     composed:true,
                     cancelable:true,
                     operationId,
-                    publicDetail:{
-                        role:'llm',
-                        action,
-                        reason:reasons.languageModelActivationRequested,
-                        state:role.state
-                    }
+                    publicDetail:request
                 }
             );
             if(!accepted||destroyed||generation!==requestGeneration){
@@ -1301,22 +2083,20 @@
                     &&['unloaded','unloading'].includes(role?.state)){
                     return false;
                 }
-                const message=visibleError(
+                const message=visibleErrorMessage(
                     error,
                     `The language model ${action} request failed.`
                 );
                 requestError=message;
+                console.error('Arcane language model activation request failed.',error);
                 publish(
                     'chat-ai-activation-error',
-                    Object.freeze({request,error,message}),
+                    {request,error,message},
                     {
                         bubbles:true,
                         composed:true,
                         operationId,
-                        publicDetail:{
-                            role:'llm',
-                            action,
-                            reason:reasons.languageModelActivationRejected,
+                        publicDetail:{request,error,message,
                             ...readErrorFields(
                                 error,
                                 errorCodes.languageModelActivationRejected
@@ -1342,6 +2122,13 @@
             if(destroyed){
                 return;
             }
+            if(
+                nextRole?.state==='error'
+                &&nextRole.error
+                &&nextRole.error!==role?.error
+            ){
+                console.error('Arcane language model runtime failed.',nextRole.error);
+            }
             if(role?.state!==nextRole.state
                 ||role?.providerId!==nextRole.providerId
                 ||role?.modelId!==nextRole.modelId
@@ -1366,7 +2153,7 @@
         }
 
         button.addEventListener('click',activateSelectedAI);
-        return Object.freeze({request,synchronize,destroy});
+        return {request,synchronize,destroy};
     }
 
     function synchronizeAIRuntimeState(snapshot){
@@ -1421,6 +2208,7 @@
         try{
             controller.start();
         }catch(error){
+            console.error('Arcane conversation timebox could not start.',error);
             conversationTimeboxStatus.textContent='The elapsed timer could not start.';
             conversationTimeboxPanel.dataset.error='true';
             conversationTimeboxUnsubscribe?.();
@@ -1503,7 +2291,7 @@
         const operationId=typeof context?.operationId==='string'&&context.operationId
             ?context.operationId
             :nextChatOperationId('conversation-timebox');
-        const deliveryContext=Object.freeze({...context,operationId});
+        const deliveryContext={...context,operationId};
         const prior=programmaticSubmissionQueue.catch(
             function ignorePriorProgrammaticSubmissionFailure(){
                 return false;
@@ -1613,7 +2401,7 @@
                         }
                     }
                 );
-                console.error('The conversation timebox message could not be sent.');
+                console.error('The conversation timebox message could not be sent.',error);
                 return false;
             }
         );
@@ -1663,19 +2451,36 @@
     );
 
     async function streamMessage(text='', id='', isThinking){
+        if(typeof text!=='string'){
+            if(text instanceof Error){
+                console.error('Arcane chat stream delivered an Error as content.',text);
+                throw text;
+            }
+            const error=new TypeError(
+                'Arcane chat stream content must be text.',
+                {cause:text}
+            );
+            error.code='ARCANE_CHAT_STREAM_CONTENT_INVALID';
+            console.error('Arcane chat stream delivered invalid content.',error);
+            throw error;
+        }
         if(!id){
             console.warn('Streaming messages require ids, none specified.')
             return false;
         }
 
-        let message=chatOutput.querySelector(`#message-${id}`);
+        let message=[...chatOutput.children].find(
+            candidate=>candidate.id===`message-${id}`
+        )||null;
         
         if(!message){
             await receivedMessage(host.aiName,isThinking?'':text,id);
             if(!isThinking){
                 return false;
             }
-            message=chatOutput.querySelector(`#message-${id}`);
+            message=[...chatOutput.children].find(
+                candidate=>candidate.id===`message-${id}`
+            )||null;
             if(!message){
                 return false;
             }
@@ -1688,7 +2493,10 @@
         if(isThinking && !thinkingHTML){
             thinkingHTML=message.ownerDocument.createElement('span');
             thinkingHTML.className='thinking';
-            message.append(thinkingHTML);
+            message.insertBefore(
+                thinkingHTML,
+                message.querySelector('.message_timestamp')
+            );
         }
 
         if(isThinking){
@@ -1699,7 +2507,7 @@
             thinkingHTML.append(
                 message.ownerDocument.createTextNode(String(text))
             );
-            chatOutput.scrollTop = chatOutput.scrollHeight;
+            scrollTranscriptToBottom();
             return true;
         }
 
@@ -1712,7 +2520,7 @@
             &&host.aiAvailability.tts
             &&speech.muted===false
         ){
-            const aiRuntime=globalThis.ai;
+            const aiRuntime=boundChatAI??globalThis.ai;
             if(typeof aiRuntime?.streamTTS==='function'){
                 void Promise.resolve(aiRuntime.streamTTS(text)).catch(
                     reportTTSError
@@ -1732,7 +2540,7 @@
 
         target.innerHTML=new MD(target.raw).rendered;
         
-        chatOutput.scrollTop = chatOutput.scrollHeight;
+        scrollTranscriptToBottom();
     }
 
     textArea.addEventListener(
@@ -1780,7 +2588,7 @@
                             cancelable:true,
                             operationId,
                             publicDetail:{
-                                size:Number.isFinite(file.size)?file.size:null,
+                                file,
                                 type:String(file.type||''),
                                 reason:chatReasons.fileStorageCompleted
                             }
@@ -1796,7 +2604,7 @@
                             composed:true,
                             operationId,
                             publicDetail:{
-                                size:Number.isFinite(file.size)?file.size:null,
+                                file,
                                 type:String(file.type||''),
                                 reason:chatReasons.fileStorageRejected,
                                 ...publicErrorFields(
@@ -1879,13 +2687,6 @@
         {signal:aiRuntimeStateAbortController.signal}
     );
 
-    function getMilTime() {
-        const now = new Date();
-        const hours = String(now.getHours()).padStart(2, '0');
-        const minutes = String(now.getMinutes()).padStart(2, '0');
-        return `${hours}:${minutes}`;
-    }
-
     async function resizeTextArea(e={}) {
         if(e.key && e.key == 'Enter' && !e.shiftKey && !send.disabled){
             e.preventDefault();
@@ -1894,11 +2695,423 @@
 
         // Reset height to shrink to content size
         textArea.style.height = 'auto';
-        let scrollHeight = textArea.scrollHeight;
-        let computedStyle = window.getComputedStyle(textArea);
-        let lineHeight = parseInt(computedStyle.lineHeight, 10) || parseInt(computedStyle.fontSize, 10) * 1.2;
-        let maxHeight = lineHeight * 10;
-        textArea.style.height = `${Math.min(scrollHeight, maxHeight)}px`;
+        textArea.style.height = `${textArea.scrollHeight}px`;
+    }
+
+    function renderSessionMessageFailure(messageId,error){
+        const message=[...chatOutput.children].find(
+            candidate=>candidate.id===`message-${messageId}`
+        )||null;
+        if(!message){
+            return false;
+        }
+        message.classList.add('session_error');
+        message.querySelector('.thinking')?.remove();
+        const markdown=message.querySelector('.markdown');
+        const text=visibleErrorMessage(error,'The AI request failed.');
+        markdown.raw=text;
+        markdown.innerHTML=new MD(text).rendered;
+        scrollTranscriptToBottom();
+        return true;
+    }
+
+    function internalStructuralToolFailure(error){
+        return [
+            'ARCANE_AI_TOOL_CALL_INVALID',
+            'ARCANE_AI_PARALLEL_TOOLS_UNSUPPORTED',
+            'ARCANE_AI_TOOL_MESSAGE_REQUIRED',
+            'AI_CHAT_INVALID_TOOL_CALL',
+            'AI_CHAT_INVALID_TOOL_MESSAGE',
+            'AI_CHAT_INCOHERENT_PERSISTENCE',
+            'AI_CHAT_PARALLEL_TOOLS_UNSUPPORTED',
+            'AI_CHAT_STREAM_TOOL_CALL_MISMATCH',
+            'AI_CHAT_TOOL_MESSAGE_REQUIRED',
+            'AI_CHAT_TOOL_RESULT_NOT_PENDING',
+            'AI_CHAT_TOOL_RESULT_REQUIRED',
+            'AI_CHAT_TRANSACTION_SETTLED'
+        ].includes(error?.code);
+    }
+
+    function restoreRejectedStructuralDraft(messageId,operationId,text){
+        const response=[...chatOutput.children].find(
+            candidate=>candidate.id===`message-${messageId}`
+        )||null;
+        const request=[...chatOutput.children].find(
+            candidate=>candidate.dataset.operationId===operationId
+        )||null;
+        response?.remove();
+        request?.remove();
+        const existing=textArea.value;
+        if(existing!==text){
+            textArea.value=existing
+                ?`${text}\n${existing}`
+                :text;
+        }
+        textArea.style.height='auto';
+        textArea.style.height=`${textArea.scrollHeight}px`;
+        scrollTranscriptToBottom();
+        return Boolean(response||request);
+    }
+
+    async function sendMessageThroughBoundSession(
+        text,
+        context,
+        sessionRequestMessage={content:text,role:'user'},
+        perTurnRequest=null
+    ){
+        const session=boundChatSession;
+        const bindingGeneration=sessionBindingGeneration;
+        if(!session){
+            throw chatError(
+                'The chat session is not bound.',
+                chatErrorCodes.sessionBindingRejected
+            );
+        }
+        if(sessionMessagePending){
+            throw chatError(
+                'A chat session message is already active.',
+                'AI_CHAT_BUSY'
+            );
+        }
+
+        const request={
+            message:sessionRequestMessage,
+            signal:context.signal,
+            ...(perTurnRequest===null?{}:{request:perTurnRequest})
+        };
+        const previousPendingToolCall=pendingStructuralToolCall;
+        let streamedStructuralToolCall=null;
+        const messageId=`session-${++sessionMessageSequence}`;
+        const sessionMessageToken=Symbol(messageId);
+        activeSessionMessageToken=sessionMessageToken;
+        sessionMessagePending=true;
+        applyAIAvailability(host.aiAvailability);
+        setSessionStatus('sending','AI is responding…');
+        try{
+            await receivedMessage(host.aiName,'',messageId);
+            await streamMessage('',messageId,true);
+            setMessageProgress(
+                messageId,
+                {
+                    label:'AI response',
+                    indeterminate:true,
+                    status:'Working'
+                }
+            );
+            const result=typeof session.stream==='function'
+                ?await session.stream(
+                    request,
+                    {
+                        onChunk:async function renderSessionStreamChunk(chunk,requestId,isThinking){
+                            if(
+                                destroyed
+                                ||bindingGeneration!==sessionBindingGeneration
+                                ||session!==boundChatSession
+                            ) return false;
+                            return streamMessage(chunk,messageId,isThinking);
+                        },
+                        onToolCall:async function renderSessionToolCall(call){
+                            if(
+                                destroyed
+                                ||bindingGeneration!==sessionBindingGeneration
+                                ||session!==boundChatSession
+                            ) return false;
+                            const message=[...chatOutput.children].find(
+                                candidate=>candidate.id===`message-${messageId}`
+                            )||null;
+                            if(!message) return false;
+                            const normalized=normalizeVisibleToolCalls([call])[0];
+                            if(
+                                streamedStructuralToolCall
+                                &&!sameStructuralToolCall(streamedStructuralToolCall,normalized)
+                            ){
+                                throw chatError(
+                                    'The streamed structural tool call changed before completion.',
+                                    'AI_CHAT_STREAM_TOOL_CALL_MISMATCH'
+                                );
+                            }
+                            if(streamedStructuralToolCall){
+                                return true;
+                            }
+                            streamedStructuralToolCall=normalized;
+                            setPendingStructuralToolCall(normalized);
+                            appendVisibleToolCall(message,normalized);
+                            setSessionStatus('tool',pendingStructuralToolMessage);
+                            return true;
+                        }
+                    }
+                )
+                :await session.send(request);
+            if(
+                destroyed
+                ||bindingGeneration!==sessionBindingGeneration
+                ||session!==boundChatSession
+            ){
+                return false;
+            }
+            if(!result||typeof result!=='object'||Array.isArray(result)){
+                throw new TypeError('The chat session returned an invalid result.');
+            }
+            if(!result.message||typeof result.message.content!=='string'){
+                throw new TypeError('The chat session result must contain assistant message content.');
+            }
+            const committedTurn=typeof session.transcript==='function'
+                ?latestCommittedTranscriptTurn(
+                    await session.transcript(),
+                    sessionRequestMessage
+                )
+                :null;
+            const message=[...chatOutput.children].find(
+                candidate=>candidate.id===`message-${messageId}`
+            )||null;
+            if(!message){
+                throw new Error('The active chat response card is unavailable.');
+            }
+            setTranscriptMessageContent(
+                message,
+                result.message.content,
+                committedTurn?.response?.timestamp??result.message.timestamp
+            );
+            const requestMessage=[...chatOutput.children].find(
+                candidate=>candidate.dataset.operationId===context.operationId
+            )||null;
+            setTranscriptMessageTimestamp(
+                requestMessage,
+                committedTurn?.request?.timestamp
+            );
+            const terminalToolCalls=normalizeVisibleToolCalls(result.message.tool_calls);
+            if(terminalToolCalls.length>1){
+                throw chatError(
+                    'The chat session returned parallel structural tool calls.',
+                    'AI_CHAT_PARALLEL_TOOLS_UNSUPPORTED'
+                );
+            }
+            if(
+                streamedStructuralToolCall
+                &&(
+                    terminalToolCalls.length!==1
+                    ||!sameStructuralToolCall(
+                        streamedStructuralToolCall,
+                        terminalToolCalls[0]
+                    )
+                )
+            ){
+                throw chatError(
+                    'The terminal structural tool call does not match the streamed call.',
+                    'AI_CHAT_STREAM_TOOL_CALL_MISMATCH'
+                );
+            }
+            if(!streamedStructuralToolCall&&terminalToolCalls.length){
+                appendVisibleToolCall(message,terminalToolCalls[0]);
+            }
+            setPendingStructuralToolCall(
+                terminalToolCalls.length?terminalToolCalls.at(-1):null
+            );
+            setSessionStatus(
+                pendingStructuralToolMessage?'tool':'ready',
+                pendingStructuralToolMessage||'Chat ready.'
+            );
+            const detail={
+                session,
+                request,
+                result,
+                message:result.message,
+                context
+            };
+            if(activeSessionMessageToken===sessionMessageToken){
+                activeSessionMessageToken=null;
+                sessionMessagePending=false;
+                applyAIAvailability(host.aiAvailability);
+            }
+            dispatchChatEvent(
+                'chat-session-message',
+                detail,
+                {
+                    bubbles:true,
+                    composed:true,
+                    operationId:context.operationId||null,
+                    publicDetail:{
+                        ...detail,
+                        reason:chatReasons.sessionMessageCompleted
+                    }
+                }
+            );
+            return result;
+        }catch(error){
+            if(!destroyed&&bindingGeneration===sessionBindingGeneration){
+                setPendingStructuralToolCall(previousPendingToolCall);
+            }
+            if(
+                !destroyed
+                &&bindingGeneration===sessionBindingGeneration
+                &&internalStructuralToolFailure(error)
+            ){
+                if(sessionRequestMessage.role==='tool'){
+                    const response=[...chatOutput.children].find(
+                        candidate=>candidate.id===`message-${messageId}`
+                    )||null;
+                    const requestMessage=[...chatOutput.children].find(
+                        candidate=>candidate.dataset.operationId===context.operationId
+                    )||null;
+                    response?.remove();
+                    requestMessage?.remove();
+                    scrollTranscriptToBottom();
+                }else{
+                    restoreRejectedStructuralDraft(messageId,context.operationId,text);
+                }
+                console.error('Arcane structural tool protocol failure.',error);
+                setSessionStatus(
+                    pendingStructuralToolCall?'tool':'ready',
+                    pendingStructuralToolMessage||'Chat ready.'
+                );
+            }else if(!destroyed&&bindingGeneration===sessionBindingGeneration){
+                console.error('Arcane chat request failed.',error);
+                if(sessionRequestMessage.role==='tool'){
+                    const requestMessage=[...chatOutput.children].find(
+                        candidate=>candidate.dataset.operationId===context.operationId
+                    )||null;
+                    requestMessage?.remove();
+                }
+                renderSessionMessageFailure(messageId,error);
+                setSessionStatus(
+                    'error',
+                    visibleErrorMessage(error,'The AI request failed.')
+                );
+                dispatchChatEvent(
+                    'chat-session-error',
+                    {phase:'message',session,request,context,error},
+                    {
+                        bubbles:true,
+                        composed:true,
+                        operationId:context.operationId||null,
+                        publicDetail:{
+                            phase:'message',
+                            session,
+                            request,
+                            context,
+                            reason:chatReasons.sessionMessageRejected,
+                            ...publicErrorFields(
+                                error,
+                                chatErrorCodes.sessionMessageRejected
+                            )
+                        }
+                    }
+                );
+            }
+            throw error;
+        }finally{
+            if(activeSessionMessageToken===sessionMessageToken){
+                activeSessionMessageToken=null;
+                sessionMessagePending=false;
+            }
+            if(!destroyed&&activeSessionMessageToken===null){
+                applyAIAvailability(host.aiAvailability);
+            }
+        }
+    }
+
+    async function submitToolResult(options={},context={}){
+        if(destroyed||host.conversationComplete){
+            return false;
+        }
+        if(!isPlainRecord(options)||!isPlainRecord(context)){
+            throw new TypeError('Tool-result options and context must be plain objects.');
+        }
+        const unsupportedOption=Object.keys(options).find(
+            key=>!['disposition','message','persist','request','toolCallId'].includes(key)
+        );
+        if(unsupportedOption){
+            throw new TypeError(`Unsupported tool-result option: ${unsupportedOption}.`);
+        }
+        const unsupportedContext=Object.keys(context).find(
+            key=>!['operationId','signal'].includes(key)
+        );
+        if(unsupportedContext){
+            throw new TypeError(`Unsupported tool-result context: ${unsupportedContext}.`);
+        }
+        if(!boundChatSession||sessionBindingPending||sessionMessagePending){
+            return false;
+        }
+        if(!host.aiAvailability.llm){
+            return false;
+        }
+        if(!pendingStructuralToolCall){
+            const error=new TypeError('There is no pending structural tool call to settle.');
+            error.code='AI_CHAT_TOOL_RESULT_NOT_PENDING';
+            throw error;
+        }
+        const disposition=options.disposition;
+        const dispositions=new Map([
+            ['executed','Executed'],
+            ['declined','Declined'],
+            ['cancelled','Cancelled'],
+            ['not-executed','Not executed']
+        ]);
+        if(!dispositions.has(disposition)){
+            throw new TypeError(
+                'Tool-result disposition must be executed, declined, cancelled, or not-executed.'
+            );
+        }
+        if(typeof options.message!=='string'||!options.message.trim()){
+            throw new TypeError('Tool-result message must contain user-facing text.');
+        }
+        const perTurnRequest=options.request??null;
+        if(perTurnRequest!==null&&!isPlainRecord(perTurnRequest)){
+            throw new TypeError('Tool-result request options must be a plain object.');
+        }
+        const managedRequestField=perTurnRequest&&Object.keys(perTurnRequest).find(
+            key=>['messages','onChunk','onResponse','onToolCall','signal','stream'].includes(key)
+        );
+        if(managedRequestField){
+            throw new TypeError(
+                `Tool-result request.${managedRequestField} is managed by the chat session.`
+            );
+        }
+        const toolCallId=options.toolCallId??pendingStructuralToolCall.id;
+        if(typeof toolCallId!=='string'||toolCallId!==pendingStructuralToolCall.id){
+            const error=new TypeError('Tool-result ID does not match the pending structural tool call.');
+            error.code='AI_CHAT_INVALID_TOOL_MESSAGE';
+            throw error;
+        }
+        const persist=options.persist??true;
+        if(typeof persist!=='boolean'){
+            throw new TypeError('Tool-result persist must be boolean.');
+        }
+
+        const text=`${dispositions.get(disposition)} — ${options.message}`;
+        const operationId=typeof context.operationId==='string'&&context.operationId
+            ?context.operationId
+            :nextChatOperationId('tool-result');
+        const ownership=createChatSubmissionOwnership(context.signal??null);
+        const eventContext={
+            source:'tool',
+            synthetic:true,
+            operationId,
+            signal:ownership.signal
+        };
+        if(ownership.signal.aborted){
+            ownership.release();
+            return false;
+        }
+        try{
+            const visibleMessage=appendTranscriptMessage('tool',text,'Tool');
+            visibleMessage.dataset.operationId=operationId;
+            const result=sendMessageThroughBoundSession(
+                text,
+                eventContext,
+                {
+                    content:text,
+                    persist,
+                    role:'tool',
+                    tool_call_id:toolCallId
+                },
+                perTurnRequest
+            );
+            return observeHostSubmission(result,eventContext,ownership);
+        }catch(error){
+            ownership.release();
+            throw error;
+        }
     }
 
     function observeHostSubmission(result,context,ownership){
@@ -1913,6 +3126,9 @@
                 if(destroyed||context.signal.aborted){
                     return false;
                 }
+                if(internalStructuralToolFailure(error)){
+                    return false;
+                }
                 dispatchChatEvent(
                     'chat-send-error',
                     {error,context:{...context}},
@@ -1930,7 +3146,7 @@
                         }
                     }
                 );
-                console.error('The chat message could not be submitted.');
+                console.error('The chat message could not be submitted.',error);
                 return false;
             }
         ).finally(
@@ -1957,12 +3173,15 @@
         if(!host.aiAvailability.llm){
             return false;
         }
-        const submissionContext=Object.freeze({
+        if(sessionBindingPending||sessionMessagePending||pendingStructuralToolMessage){
+            return false;
+        }
+        const submissionContext={
             source:'user',
             preserveDraft:false,
             synthetic:false,
             ...context
-        });
+        };
         const text=textOverride.length>0?textOverride:textArea.value;
         if(!text.trim()){
             return false;
@@ -1972,13 +3191,11 @@
             ?submissionContext.operationId
             :nextChatOperationId('message');
         const ownership=createChatSubmissionOwnership(submissionContext.signal??null);
-        const eventContext=Object.freeze(
-            {
-                ...submissionContext,
-                operationId,
-                signal:ownership.signal
-            }
-        );
+        const eventContext={
+            ...submissionContext,
+            operationId,
+            signal:ownership.signal
+        };
         if(ownership.signal.aborted){
             ownership.release();
             return false;
@@ -1997,7 +3214,8 @@
                     cancelable:true,
                     operationId,
                     publicDetail:{
-                        messageLength:text.length,
+                        message:text,
+                        context:eventContext,
                         source:eventContext.source,
                         synthetic:eventContext.synthetic===true,
                         reason:chatReasons.messageSubmissionRequested
@@ -2022,7 +3240,6 @@
             return false;
         }
         try{
-            const messageTime = getMilTime();
             if(!eventContext.preserveDraft){
                 textArea.value='';
             }
@@ -2031,32 +3248,28 @@
             // console.log(forceText,text,1);
             if(!eventContext.synthetic&&!eventContext.reuseVisibleMessage){
                 hostSubmissionGeneration++;
-                chatOutput.innerHTML += `
-                    <li class='user'>
-                        <strong>${host.name} ${messageTime}:</strong>
-                        <br>
-                        <br>
-                        <div class='markdown'>
-                            ${new MD(text).rendered}
-                        </div>
-                    </li>
-                `;
-            }
-            chatOutput.scrollTop = chatOutput.scrollHeight;
+                const visibleMessage=appendTranscriptMessage('user',text,host.name);
+                visibleMessage.dataset.operationId=operationId;
+            }
+            scrollTranscriptToBottom();
 
             if(host.aiAvailability.tts&&speech.muted===false){
-                const aiRuntime=globalThis.ai;
+                const aiRuntime=boundChatAI??globalThis.ai;
                 aiRuntime?.stopAudio?.();
                 if(typeof aiRuntime?.resumeAudio==='function'){
                     void Promise.resolve(aiRuntime.resumeAudio()).catch(
-                        reportTTSError
+                        function reportPlaybackResumeFailure(error){
+                            reportTTSError(error,'playback-resume');
+                        }
                     );
                 }
             }
 
             let result;
             try{
-                result=host.sendMessage(text,eventContext);
+                result=boundChatSession
+                    ?sendMessageThroughBoundSession(text,eventContext)
+                    :host.sendMessage(text,eventContext);
             }catch(error){
                 result=Promise.reject(error);
             }
@@ -2068,45 +3281,46 @@
     }
 
     async function receivedMessage(name = 'Assistant', text = '', id=''){
-        const messageTime = getMilTime();
-        //console.log(text)
-        chatOutput.innerHTML += `
-            <li class='ai' ${id? `id="message-${id}"`:''}>
-                <strong>${name} ${messageTime}:</strong>
-                <br>
-                <br>
-                <div class='markdown'>
-                    ${new MD(text).rendered}
-                </div>
-            </li>
-        `;
-        chatOutput.scrollTop = chatOutput.scrollHeight;
-    }
-
-    function reportTTSError(error){
+        const message=appendTranscriptMessage('assistant',text,name);
+        if(id){
+            message.id=`message-${id}`;
+        }
+        scrollTranscriptToBottom();
+        return message;
+    }
+
+    function reportTTSError(error,boundary='synthesis'){
         if(destroyed){
             return false;
         }
         if(typeof speech.reportTTSError==='function'){
             try{
-                speech.reportTTSError(error);
+                speech.reportTTSError(error,boundary);
                 return true;
             }catch(reportingError){
                 error=reportingError;
             }
         }
 
-        const message=typeof error?.message==='string'&&error.message.trim()
-            ?error.message.trim().slice(0,240)
-            :'Speech synthesis failed.';
+        const message=visibleErrorMessage(
+            error,
+            boundary==='decode'
+                ?'Speech audio could not be decoded.'
+                :boundary==='playback-start'
+                    ?'Speech playback could not start.'
+                    :boundary==='playback-resume'
+                        ?'Speech playback could not resume.'
+                        :'Speech synthesis failed.'
+        );
         dispatchChatEvent(
             'chat-speech-synthesis-error',
-            {error,message},
+            {boundary,error,message},
             {
                 bubbles:true,
                 composed:true,
                 operationId:nextChatOperationId('speech-synthesis'),
                 publicDetail:{
+                    boundary,
                     reason:chatReasons.speechSynthesisRejected,
                     ...publicErrorFields(
                         error,
@@ -2115,14 +3329,16 @@
                 }
             }
         );
-        console.error('Speech synthesis failed.');
+        console.error('Speech synthesis failed.',error);
         return false;
     }
 
     function destroy(){
         if(destroyed){
-            return;
+            return false;
         }
+        sessionBindingGeneration+=1;
+        setSessionStatus('destroyed','Chat closed.');
         destroyed=true;
         const destroyReason=createChatSubmissionAbort(
             chatReasons.componentDestroyed,
@@ -2138,9 +3354,17 @@
         conversationTimeboxUnsubscribe=null;
         conversationTimeboxController=null;
         initialSpeechMuteListenerInstalled=false;
+        sessionBindingPending=false;
+        sessionMessagePending=false;
+        activeSessionMessageToken=null;
+        setPendingStructuralToolCall();
+        boundChatSession=null;
+        boundChatAI=null;
+        host.session=null;
         speech.destroy?.();
         events.dispose();
         host.ready=false;
+        return true;
     }
 
     // Initialize and adjust on input