arcane-os 0.13.2 → 0.14.0

package/docs/reference/ai/browser-wasm.md

@@ -320,6 +320,68 @@ Ordinary iteration exposes only text/reasoning chunks; raw structural deltas
 remain internal until the complete terminal result validates. Explicit
 `onResponse` or inspection consumers retain the complete raw terminal response.
 
+## Stream selected tool text
+
+Both `AI.streamRequest()` and this browser controller's `streamRequest()` accept
+`toolText:{name,field}` with `onToolText(text,call,displayId)`. Select the exact
+tool name and one root-level string argument. The callback receives newly
+decoded text in arrival order, preserving whitespace and JSON string escapes as
+their original characters. Its `call` record is
+`{id,name,field,index,choiceIndex}`: the actual normalized tool-call ID, matching
+tool name, selected field, call index within the response choice, and choice
+index. Delivery waits until the matching name and ID are known. `displayId` is
+the request's existing `M-${id}` display ID.
+
+This callback is distinct from ordinary `onChunk`; display the text in the
+corresponding tool turn and keep ordinary prose in its own existing turn.
+`onToolCall` still receives only the complete normalized call after terminal
+settlement. The text callback does not execute a tool, rewrite arguments, or
+retain a transcript. The application owns the completed call's execution and
+stores its complete visible result once through its normal history path.
+If a provider supplies arguments only at completion, the callback runs only
+when that actual complete response arrives. Repeated terminal snapshots do not
+replay text already emitted. Callback errors reach the request owner, and a
+cancelled or superseded request stops further text delivery.
+
+For example, an application that already supplies a closing-report tool can
+connect its existing display operations without parsing provider protocol:
+
+```javascript
+import {
+    formatConversationClosingReportText
+} from '/arcane/modules/ConversationClosingReport.js';
+
+async function streamClosingReport(ai, messages, closingTool, view, signal) {
+    return ai.streamRequest(
+        {
+            messages,
+            tools:[closingTool],
+            signal,
+            toolText:{name:closingTool.function.name, field:'final_message'},
+            onChunk:function appendOrdinaryText(text, displayId, thinking) {
+                return view.appendAssistantText(text, displayId, thinking);
+            },
+            onToolText:function appendClosingText(text, call, displayId) {
+                return view.appendToolText(
+                    formatConversationClosingReportText(text),
+                    call.id,
+                    displayId
+                );
+            }
+        }
+    );
+}
+```
+
+The application supplies `view` and the existing `closingTool`; those are not
+SDK exports. The formatter applies the same existing `&`, `<`, and `>` escaping
+used for the complete closing report, including whitespace-only chunks. The
+returned terminal call remains available to the application's normal tool
+execution and persistence path. These options do not change the tool schema,
+tool choice, or authored request content. Omitting `toolText` creates no text
+observer. Invalid selection or callback input throws `TypeError`; malformed
+selected argument text reports `ARCANE_AI_TOOL_TEXT_INVALID`.
+
 ## Errors and unavailable states
 
 Invalid configuration can throw `TypeError` or `RangeError`. Operational

package/docs/reference/inventory/package-api.json

@@ -6,7 +6,7 @@
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 208,
+  "memberCount": 209,
   "members": [
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
@@ -2902,7 +2902,23 @@
       "summary": "Creates the provider-neutral browser AI API module and LLM lifecycle controller around one compatible provider or controller.",
       "availability": "Browser; the selected provider observes its own WebAssembly, storage, and model readiness",
       "protocol": "arcane-ai-adapter/1",
-      "normalization": "Normalizes lazy or manual load, mutable complete lifecycle status, cancellation, complete all-choice nonstructural stream projection, complete provider data callbacks, single-choice text or multi-choice terminal output, required structural arguments.message, and atomic exact matching nonblank all-ID tool-result sequencing without executing tools; an existing ModelController retains its preconfigured load policy and rejects a new security option"
+      "normalization": "Normalizes lazy or manual load, mutable complete lifecycle status, cancellation, complete all-choice nonstructural stream projection, provider chunks with private structural fields removed, complete terminal data callbacks, optional toolText:{name,field} and distinct onToolText(text,call,displayId) delivery of selected decoded argument text, single-choice text or multi-choice terminal output, required structural arguments.message, and atomic exact matching nonblank all-ID tool-result sequencing without executing tools; an existing ModelController retains its preconfigured load policy and rejects a new security option"
+    },
+    {
+      "id": "tool-text-stream:createToolTextObserver",
+      "name": "createToolTextObserver",
+      "displayName": "createToolTextObserver()",
+      "kind": "function",
+      "signature": "createToolTextObserver(selection, onText, {signal}={})",
+      "entrypoints": [
+        "arcane-os/ai/tool-text-stream"
+      ],
+      "primaryImport": "arcane-os/ai/tool-text-stream",
+      "group": "AI provider integration",
+      "summary": "Observes one selected root string argument from actual tool-call chunks before provider structural filtering.",
+      "availability": "Compatible JavaScript module host; no browser capability required",
+      "protocol": "OpenAI-compatible tool-call deltas and complete message snapshots",
+      "normalization": "Returns null for absent selection or an async chunk observer; preserves decoded text and whitespace, emits actual normalized call identity metadata, observes each raw delta once, avoids replay from complete snapshots, awaits callbacks, and stops later observation after cancellation without altering payloads, executing tools, or persisting history"
     },
     {
       "id": "browser-wasm:createBrowserModelSource",

package/docs/reference/inventory/runtime-modules.json

@@ -10,7 +10,7 @@
   },
   "artifactCount": 85,
   "javascriptArtifactCount": 83,
-  "esmExportCount": 352,
+  "esmExportCount": 353,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -30,7 +30,7 @@
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
       "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Whisper STT and Kokoro TTS execution with default capacities 1 and 4 respectively, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, automatic repeated-formatting-mark removal from cloned outbound TTS input while caller and visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing, independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned. Both speech roles default execution.device to auto: webnn-npu when navigator.ml.createContext is exposed, then webgpu when navigator.gpu is exposed, then wasm for CPU execution. Failed backend loads clean up the pool before trying fresh Workers with the same prepared model and dtype; explicit devices never fall back. STT capacity only accepts 1; TTS accepts 1 through 4. Execution snapshots expose requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount for both roles; selectedDevice is null while unloaded and names the successful upstream session backend request when loaded. It does not prove every operation used the physical NPU: WebNN unsupported operations may use WASM, and compatibility depends on the browser, driver, hardware, and graph.",
-      "surface": "Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; automatic speech-input cleanup with SDK-internal preparation metadata; `prepareTTS({parts,storage,identity,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `playPreparedTTS(prepared,{signal,onState})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls, synthesis/transcription, and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
+      "surface": "Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; automatic speech-input cleanup with SDK-internal preparation metadata; `prepareTTS({parts,storage,identity,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `playPreparedTTS(prepared,{signal,onState})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
     },
     {
       "file": "runtime/arcane/modules/AIPreferenceRuntime.js",
@@ -456,13 +456,14 @@
         "conversationClosingReportInstruction",
         "createConversationClosingReportTool",
         "formatConversationClosingReport",
+        "formatConversationClosingReportText",
         "normalizeConversationClosingReport"
       ],
       "summary": "Defines the closing-report tool, instruction, result normalizer, call classifier, and formatter.",
       "availability": "Cross-host",
       "protocol": "In-process only",
       "normalization": "Required user-facing message remains distinct from the complete final_message; normalized results expose message, finalMessage, and rememberedActions.",
-      "surface": "Six constants/helpers for closing reports; the sole-call schema requires message and final_message."
+      "surface": "Seven constants/helpers for closing reports; the sole-call schema requires message and final_message. formatConversationClosingReportText(value) exposes the existing &, <, and > escaping for any string, including whitespace-only chunks, and the complete report formatter reuses it."
     },
     {
       "file": "runtime/arcane/modules/ConversationTimebox.js",

package/docs/reference/runtime-modules.md

@@ -432,7 +432,7 @@ declined, cancelled, or not-executed result.
 That tool-result content must be a nonblank string and is preserved exactly.
 
 `streamRequest()` owns the complete terminal callback sequence. `onDataChunk`
-receives each complete provider chunk before ordinary projection, while
+receives each provider chunk after private structural fields are removed, while
 `onChunk` receives every nonstructural content or reasoning value from every
 choice in provider order. After the stream settles, `onDataResult` receives the
 complete terminal completion, `onResponse` receives that same unprojected
@@ -442,8 +442,29 @@ output is the ordered structural-call array when the selected result contains
 tools, the complete completion object when it contains multiple choices, or
 the ordinary single-result text/completion otherwise; later choices are never
 discarded.
-Partial structural deltas remain private until the matching terminal envelope
-validates. Request observers receive
+Raw structural deltas remain private until the matching terminal envelope
+validates. To display one tool argument's text as it arrives, supply
+`toolText:{name,field}` and `onToolText(text,call,displayId)`. `name` is the exact
+tool name and `field` is one root-level string argument. The callback receives
+each newly decoded text fragment in order, including whitespace and JSON string
+escapes decoded to their original characters. Its `call` record contains
+`{id,name,field,index,choiceIndex}`; `id` is the actual normalized tool-call ID,
+`index` identifies the call within its choice, and `choiceIndex` identifies the
+response choice. Delivery starts once the matching tool name and call ID are
+known. `displayId` is the same `M-${id}` request display ID used by `onChunk`.
+
+`onToolText` is separate from ordinary `onChunk`, so callers can append to the
+tool's existing display without duplicating assistant prose or saved history.
+It observes text only: it does not execute a tool, alter arguments, persist a
+turn, or change the terminal callbacks. A provider that supplies arguments only
+at completion emits text only when that complete response arrives. Repeated
+terminal snapshots do not replay text already emitted. Omitting `toolText`
+preserves the existing callback path. Invalid selection or callback input throws
+`TypeError`; malformed selected argument text reports
+`ARCANE_AI_TOOL_TEXT_INVALID`. Callback errors reach the request owner and
+cancellation prevents later delivery.
+
+Request observers receive
 `onRequest(request,id,metadata)` and any transport metadata supplied by the
 selected route is forwarded unchanged. Every async native, HTTP, provider, and
 built-in callback is observed before the next callback or terminal settlement.
@@ -1609,7 +1630,7 @@ Defines the closing-report tool, instruction, result normalizer, call classifier
 
 ### Public surface
 
-Six constants/helpers for closing reports.
+Seven constants/helpers for closing reports.
 
 The generated sole-call schema requires both `message` and `final_message`.
 `message` is brief user-facing progress shown while the application accepts and
@@ -1617,9 +1638,14 @@ renders the call. `final_message` remains the complete terminal closeout and is
 never replaced by or duplicated into `message`; `remembered_actions` remains
 optional. `normalizeConversationClosingReport()` returns
 `{message,finalMessage,rememberedActions}`, while
-`formatConversationClosingReport()` escapes and renders only `finalMessage`.
+`formatConversationClosingReport()` normalizes the complete report and formats
+only `finalMessage`. Its shared `formatConversationClosingReportText(value)`
+operation accepts a string, including an empty or whitespace-only chunk, and
+replaces `&`, `<`, and `>` with `&amp;`, `&lt;`, and `&gt;` respectively. It
+preserves all other text and does not trim, validate a report, render, or persist
+anything. Use the same operation for live text chunks and complete final text.
 
-Exact exports: `CONVERSATION_CLOSING_REPORT_TOOL_NAME`, `classifyConversationClosingReportCalls`, `conversationClosingReportInstruction`, `createConversationClosingReportTool`, `formatConversationClosingReport`, `normalizeConversationClosingReport`.
+Exact exports: `CONVERSATION_CLOSING_REPORT_TOOL_NAME`, `classifyConversationClosingReportCalls`, `conversationClosingReportInstruction`, `createConversationClosingReportTool`, `formatConversationClosingReport`, `formatConversationClosingReportText`, `normalizeConversationClosingReport`.
 
 ### Availability and normalization
 
@@ -1628,9 +1654,11 @@ Exact exports: `CONVERSATION_CLOSING_REPORT_TOOL_NAME`, `classifyConversationClo
 ### Example
 
 ```javascript
-import * as module from '/arcane/modules/ConversationClosingReport.js';
+import {
+    formatConversationClosingReportText
+} from '/arcane/modules/ConversationClosingReport.js';
 
-console.log(Object.keys(module));
+console.log(formatConversationClosingReportText('Complete <draft> & next step.'));
 ```
 
 ## ConversationTimebox.js

package/docs/reference/sdk-api.md

@@ -3,7 +3,7 @@
 The npm package exposes a Node.js ESM control plane, the portable
 `arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`,
 `arcane-os/preference-store`, `arcane-os/speech-playback`,
-`arcane-os/speech-text`, and `arcane-os/browser-device` entrypoints, and the browser-only
+`arcane-os/speech-text`, `arcane-os/ai/tool-text-stream`, and `arcane-os/browser-device` entrypoints, and the browser-only
 `arcane-os/pwa`, `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints.
 Those package subpaths are distinct from application-facing projection modules
 in the managed browser map, such as `arcane/AIProviderRuntime`,
@@ -41,6 +41,7 @@ for the installed-inventory-derived physical-runtime contract in SDK `0.5.18`.
 | `arcane-os/browser-device` | Synchronous mobile or desktop identity hints for application-owned settings. |
 | `arcane-os/pwa` | Nonblocking PWA registration, worker updates, native installation state and a dismissible installation component. |
 | `arcane-os/ai/browser-wasm` | Caller-selected browser-local Wllama inference, complete DBOPFS model storage, streaming, cancellation, and structural tool-call results. |
+| `arcane-os/ai/tool-text-stream` | Shared selected tool-argument text observer for provider integration. |
 | `arcane-os/ai/browser-speech` | Caller-selected browser-local Whisper STT and Kokoro TTS provider mechanisms, ordinary upstream assets, materialized/native routing, Workers, and cancellation. |
 | `arcane-os/mail` | Portable Mail runtime, durable outbox, complete transport responses, and provider-neutral acceptance contracts. |
 
@@ -138,6 +139,7 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | `createNativeTargetAdapter()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `createReporter()` | function | `arcane-os` | Events, processes, and testing | Node |
 | `createToolchain()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
+| `createToolTextObserver()` | function | `arcane-os/ai/tool-text-stream` | AI provider integration | Compatible JavaScript module host; no browser capability required |
 | `createWorkspace()` | function | `arcane-os` | Workspace, doctor, repository, and server | Node |
 | `default()` | function | `arcane-os/testing` | Events, processes, and testing | Node |
 | `DEFAULT_TEST_TIMEOUT_MS` | constant | `arcane-os` | Events, processes, and testing | Node |
@@ -5905,8 +5907,20 @@ At least one `llm` or `provider` is required. The mutable API object contains
 delivers every choice's ordinary content/reasoning values in provider order,
 and returns ordinary terminal text for one choice, a structural-call array for
 selected tool output, or complete JSON text for a multi-choice completion.
-`onDataChunk` and `onDataResult` preserve the complete provider chunk and
-terminal record independently of that application-facing projection. Use
+`onDataChunk` receives provider chunks with private structural fields removed;
+`onDataResult` preserves the complete terminal record independently of that
+application-facing projection. Supply `toolText:{name,field}` with
+`onToolText(text,call,displayId)` to receive one selected root string argument
+as it arrives. `call` contains `{id,name,field,index,choiceIndex}` with the real
+normalized call ID, call position, and response-choice index. The SDK decodes
+JSON string escapes, preserves whitespace and order, and starts delivery once
+the matching tool name and call ID are known. `displayId` is the same request
+display ID as `onChunk`. This separate callback does not add ordinary prose,
+execute tools, or persist history. Complete-only providers emit the selected
+text only on actual completion; repeated terminal snapshots do not replay
+emitted text. Callback failures reach the request owner and cancellation
+prevents later delivery. Omitting `toolText` preserves the existing behavior.
+See the [tool-text example](ai/browser-wasm.md#stream-selected-tool-text). Use
 `ai.llm.stream()` for the async iterator; structural fragments remain private
 until the complete terminal result validates.
 
@@ -5991,6 +6005,61 @@ async function openLocalReviewAfterUserChoice() {
 }
 ```
 
+## createToolTextObserver()
+
+### Overview
+
+Creates the shared tool-text observer used by SDK provider integrations before
+private structural fields are removed. Application callers normally use
+`streamRequest({toolText,onToolText})` instead.
+
+### Signature and result
+
+```text
+createToolTextObserver(selection, onText, {signal}={})
+```
+
+`selection` is `{name,field}`: the exact tool name and one root string argument.
+`undefined`, `null`, or `false` selection returns `null`. An active selection
+requires nonblank string `name` and `field` values and an `onText` function;
+invalid configuration throws `TypeError`.
+
+The result is an async `observeToolText(chunk)` function. It accepts raw
+OpenAI-compatible `choices[].delta.tool_calls` fragments and complete
+`choices[].message.tool_calls` or `message.tool_calls` snapshots. `onText` is
+awaited with each newly decoded fragment and
+`{id,name,field,index,choiceIndex}`. It preserves decoded string content and
+whitespace, waits for the matching name and real normalized ID, and reports
+malformed selected argument text with `ARCANE_AI_TOOL_TEXT_INVALID`.
+
+### Availability and normalization
+
+**Compatible JavaScript module host.** One observer owns one request's call
+state. Consume each raw delta once, before any structural filtering; pass the
+same observer through the provider integration instead of creating another
+parser. Complete snapshots may be observed again without replaying emitted
+text. A complete-only response emits only when received. `signal` stops later
+observation after cancellation; callback errors propagate to the caller. The
+observer does not modify the supplied chunk, invoke tools, persist history, or
+start inference.
+
+### Example
+
+```javascript
+import {createToolTextObserver} from 'arcane-os/ai/tool-text-stream';
+
+function createProviderTextObserver(onText, signal) {
+    return createToolTextObserver(
+        {name:'prepare_conversation_closing_report', field:'final_message'},
+        onText,
+        {signal}
+    );
+}
+```
+
+The provider owner passes actual raw chunks to the returned observer and awaits
+it before continuing its existing filtered stream delivery.
+
 ## createBrowserModelSource()
 
 ### Overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -20,6 +20,7 @@
     "./speech-playback": "./runtime/arcane/modules/SpeechPlayback.js",
     "./speech-text": "./browser-runtime/speech-text.mjs",
     "./ai/browser-wasm": "./browser-runtime/ai/browser-wasm.mjs",
+    "./ai/tool-text-stream": "./browser-runtime/ai/tool-text-stream.mjs",
     "./ai/browser-speech": "./browser-runtime/ai/browser-speech.mjs",
     "./mail": "./src/mail-api.mjs",
     "./testing": "./src/testing.mjs",

package/runtime/arcane/modules/AI.js

@@ -18,6 +18,7 @@ import {normalizeOllamaModelIdentifier} from './OllamaModelIdentifier.js';
 import {arcaneLogging} from 'arcane-os/logging';
 import {MarkdownSpeech,stripSpeechFormatting} from 'arcane-os/speech-text';
 import {prepareSpeech} from './PreparedSpeech.js';
+import {createToolTextObserver} from 'arcane-os/ai/tool-text-stream';
 
 const completeValue=(value)=>value;
 
@@ -1470,7 +1471,7 @@ class AI {
                     status:statusBuiltInLLMProvider()
                 });
             },
-            request:function requestBuiltInLLMProvider(context={}){
+            request:function requestBuiltInLLMProvider(context={},controls={}){
                 if(context.signal?.aborted){
                     throw normalizeAIRequestAbort(context.signal.reason);
                 }
@@ -1502,7 +1503,8 @@ class AI {
                         function executeBuiltInLLMProviderStream(bridge){
                             return runtime.#requestBuiltInLLMStream(
                                 context.payload,
-                                bridge
+                                bridge,
+                                controls.observeToolText
                             );
                         },
                         context.signal
@@ -4285,7 +4287,7 @@ class AI {
         );
     }
 
-    #requestBuiltInLLMStream(payload={},bridge){
+    #requestBuiltInLLMStream(payload={},bridge,observeToolText=null){
         const parallelToolCalls=payload.parallelToolCalls!==undefined
             ?payload.parallelToolCalls
             :payload.parallel_tool_calls;
@@ -4310,7 +4312,8 @@ class AI {
             true,
             emitBuiltInLLMStreamData,
             function ignoreBuiltInLLMStreamResult(){},
-            payload.reasoningEffort
+            payload.reasoningEffort,
+            observeToolText
         );
     }
 
@@ -4459,6 +4462,8 @@ class AI {
         structuredOutput=false,
         localOnly=false,
         onChunk=function ignoreStreamChunk(){},
+        toolText,
+        onToolText,
         onComplete=function finishIgnoredStream(){},
         onDataChunk=function ignoreStreamDataChunk(){},
         onDataResult=function ignoreStreamDataResult(){},
@@ -4484,6 +4489,15 @@ class AI {
         reasoningEffort
     }={}){
         validateAIStructuralRequest(messages,tools,parallelToolCalls);
+        const observeToolText=createToolTextObserver(
+            toolText,
+            is.function(onToolText)
+                ?function reportAIStreamToolText(text,call){
+                    return onToolText(text,call,`M-${id}`);
+                }
+                :onToolText,
+            {signal}
+        );
         const normalizedReasoningEffort=normalizeAIReasoningEffort(
             reasoningEffort===undefined?this.reasoningEffort:reasoningEffort
         );
@@ -4538,7 +4552,8 @@ class AI {
                         payload:request,
                         localOnly,
                         signal
-                    }
+                    },
+                    {observeToolText}
                 );
                 for await(const chunk of handle){
                     if(signal?.aborted){
@@ -4589,7 +4604,7 @@ class AI {
                 if(signal?.aborted){
                     throw normalizeAIRequestAbort();
                 }
-                this.finishTTS();
+                this.#finishStreamingSpeech();
                 return result;
             }catch(error){
                 if(handle){
@@ -4622,7 +4637,8 @@ class AI {
                 true,
                 onDataChunk,
                 onDataResult,
-                normalizedReasoningEffort
+                normalizedReasoningEffort,
+                observeToolText
             );
             const structuralToolCalls=normalizeAICompletionToolCalls(
                 completion
@@ -4645,7 +4661,7 @@ class AI {
             if(signal?.aborted){
                 throw normalizeAIRequestAbort();
             }
-            this.finishTTS();
+            this.#finishStreamingSpeech();
             return result;
         }catch(error){
             this.stopAudio();
@@ -4729,7 +4745,8 @@ class AI {
         returnCompletion=false,
         dataChunkHandler=function ignoreBuiltInStreamDataChunk(){},
         dataResultHandler=function ignoreBuiltInStreamDataResult(){},
-        reasoningEffort
+        reasoningEffort,
+        observeToolText=null
     ){
         let speechTurnCompleted=false;
 
@@ -4845,6 +4862,12 @@ class AI {
                                 );
                             }
                             streamedNativeToolCalls=observed;
+                            if(observeToolText){
+                                await observeToolText({message:{tool_calls:observed}});
+                            }
+                        }
+                        if(signal?.aborted){
+                            return;
                         }
                         const thinking=seeThinking
                             ?String(message.thinking||'')
@@ -4918,6 +4941,12 @@ class AI {
                 structuralToolCalls,
                 tool_choice
             );
+            if(observeToolText){
+                await observeToolText(nativeCompletion);
+            }
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort();
+            }
             await dataResultHandler(nativeCompletion,id);
             for(const call of structuralToolCalls){
                 if(signal?.aborted){
@@ -4928,7 +4957,7 @@ class AI {
 
             const nativeResult=this.#providerCompletionOutput(nativeCompletion);
             if(finishSpeech){
-                this.finishTTS();
+                this.#finishStreamingSpeech();
             }
             await streamComplete(nativeResult,`M-${id}`,isThinking);
             speechTurnCompleted=true;
@@ -5096,6 +5125,12 @@ class AI {
                     'The AI stream returned a non-object event payload.'
                 );
             }
+            if(observeToolText){
+                await observeToolText(streamedResponse);
+            }
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort();
+            }
             const dataChunk=projectAIStreamChunk(streamedResponse);
             if(dataChunk!==OMITTED_AI_STREAM_DATA){
                 await dataChunkHandler(dataChunk,id);
@@ -5253,6 +5288,13 @@ class AI {
                 await drainSseBuffer(true);
             }
         }catch(error){
+            if(observeToolText){
+                await reader.cancel(error).catch(
+                    function reportToolTextReaderCleanupFailure(cleanupError){
+                        arcaneLogging.error('Arcane tool text reader cleanup failed.',cleanupError);
+                    }
+                );
+            }
             if(isAIRequestAbort(error,signal)){
                 throw normalizeAIRequestAbort(error);
             }
@@ -5383,6 +5425,12 @@ class AI {
             terminalToolCalls,
             'The built-in HTTP stream'
         );
+        if(observeToolText){
+            await observeToolText(completion);
+        }
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort();
+        }
         await dataResultHandler(completion,id);
         for(const call of terminalToolCalls){
             if(signal?.aborted){
@@ -5392,7 +5440,7 @@ class AI {
         }
         const streamResult=this.#providerCompletionOutput(completion);
         if(finishSpeech){
-            this.finishTTS();
+            this.#finishStreamingSpeech();
         }
         await streamComplete(streamResult, `M-${id}`,isThinking);
 
@@ -6075,6 +6123,16 @@ class AI {
         );
     }
 
+    #finishStreamingSpeech(){
+        if(this.muted){
+            for(const playback of this.#preparedSpeechPlaybacks) playback.stop();
+            this.audioMessageChunks='';
+            this.#markdownSpeech.reset();
+            return;
+        }
+        this.finishTTS();
+    }
+
     finishTTS(){
         this.#traceSpeech('finishTTS.call');
         return this.streamTTS('',true);

package/runtime/arcane/modules/AIProviderRuntime.js

@@ -3347,14 +3347,14 @@ export class AIProviderRuntime {
         return this.#disposeAllPromise;
     }
 
-    request(role, options = {}, {speechInputPrepared = false} = {}) {
+    request(role, options = {}, {speechInputPrepared = false, observeToolText = null} = {}) {
         if (SPEECH_ROLES.includes(role)) {
             arcaneLogging.debug('[Arcane speech runtime] request', role, options);
         }
-        return this.#requestRole(role, options, false, speechInputPrepared);
+        return this.#requestRole(role, options, false, speechInputPrepared, observeToolText);
     }
 
-    #requestRole(role, options, queued, speechInputPrepared = false) {
+    #requestRole(role, options, queued, speechInputPrepared = false, observeToolText = null) {
         this.#assertOpen();
         this.#assertNotConfiguring();
         assertRole(role);
@@ -3486,7 +3486,7 @@ export class AIProviderRuntime {
         }
         if ((!queued && slot.requestQueue.length)
             || slot.activeRequests.size >= maxConcurrentRequests) {
-            return this.#enqueueRoleRequest(slot, options);
+            return this.#enqueueRoleRequest(slot, options, observeToolText);
         }
         if (!slot.ready
             || providerStatus.state !== 'ready'
@@ -3556,6 +3556,17 @@ export class AIProviderRuntime {
         }
 
         if (options.operation === 'stream') {
+            const observeCurrentToolText = role === 'llm' && observeToolText
+                ? async function observeCurrentAIProviderToolText(chunk) {
+                    runtime.#assertCurrentRequest(
+                        slot, generation, requestSequence, requestRecord, controller.signal
+                    );
+                    await observeToolText(chunk);
+                    runtime.#assertCurrentRequest(
+                        slot, generation, requestSequence, requestRecord, controller.signal
+                    );
+                }
+                : null;
             let providerHandle = null;
             let providerOpenPromise = null;
             let iterator = null;
@@ -3796,7 +3807,8 @@ export class AIProviderRuntime {
                                     operation: options.operation,
                                     payload: options.payload,
                                     signal: controller.signal
-                                }
+                                },
+                                {observeToolText: observeCurrentToolText}
                             );
                         }
                     );
@@ -3862,6 +3874,7 @@ export class AIProviderRuntime {
                                         continue;
                                     }
                                     llmToolCallCorrelation.observe(result.value);
+                                    if (observeCurrentToolText) await observeCurrentToolText(result.value);
                                     const projected = projectLLMStreamChunk(result.value);
                                     if (projected !== OMITTED_LLM_STREAM_DATA) {
                                         publishProjectedAIProviderStreamChunk(projected);
@@ -3902,6 +3915,7 @@ export class AIProviderRuntime {
                                     )
                                     : value;
                                 llmToolCallCorrelation?.assertTerminal(terminalValue);
+                                if (observeCurrentToolText) await observeCurrentToolText(terminalValue);
                                 settleAIProviderStream(null, terminalValue);
                             } catch (error) {
                                 if (cleanupPromise) {
@@ -4208,7 +4222,7 @@ export class AIProviderRuntime {
         );
     }
 
-    #enqueueRoleRequest(slot, options) {
+    #enqueueRoleRequest(slot, options, observeToolText = null) {
         if (SPEECH_ROLES.includes(slot.role)) {
             arcaneLogging.debug('[Arcane speech runtime] queue.enqueue', {
                 role: slot.role,
@@ -4222,6 +4236,7 @@ export class AIProviderRuntime {
         return new Promise(function queueAIProviderRoleRequest(resolve, reject) {
             const entry = {
                 options,
+                observeToolText,
                 resolve,
                 reject,
                 detachSignal: null
@@ -4293,7 +4308,9 @@ export class AIProviderRuntime {
             }
             let operation;
             try {
-                operation = runtime.#requestRole(slot.role, entry.options, true);
+                operation = runtime.#requestRole(
+                    slot.role, entry.options, true, false, entry.observeToolText
+                );
             } catch (error) {
                 if (SPEECH_ROLES.includes(slot.role)) {
                     arcaneLogging.debug('[Arcane speech runtime] queue.error', slot.role, entry.options, error);