arcane-os 0.13.3 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.14.0
+
+- Add opt-in `toolText: {name, field}` and `onToolText(text, call, displayId)`
+  to model streaming requests. Decode the selected root string field as tool
+  arguments arrive, separately from ordinary text and final tool execution.
+  Preserve actual call identity, whitespace, ordered delivery, and cancellation
+  across HTTP, native, and browser provider routes.
+- Export `formatConversationClosingReportText(value)` so streamed closing text
+  uses the same existing formatting as the complete report.
+
 ## 0.13.3
 
 - Skip automatic TTS finalization calls when a model stream completes while

package/browser-runtime/ai/browser-wasm-llm-provider.mjs

@@ -2271,13 +2271,24 @@ function createCompletionAccumulator(modelId, requestId) {
   return completeValue({ push, result, hasToolCalls, correlateToolCalls });
 }
 
-function callbackStreamHandle({ runtime, request, signal, onSettled }) {
+function callbackStreamHandle({ runtime, request, signal, onSettled, observeToolText = null }) {
   const linked = linkAbortSignal(signal);
   const accumulator = createCompletionAccumulator(request.model ?? null, request.id);
   const chunks = [];
   const waiters = [];
   let ended = false;
   let terminalError = null;
+  let observation = Promise.resolve();
+  let observationError = null;
+
+  function publishChunk(chunk) {
+    if (ended || linked.controller.signal.aborted) return;
+    const publicChunk = projectPublicStreamChunk(chunk);
+    if (publicChunk === OMITTED_PUBLIC_STREAM_DATA) return;
+    const waiter = waiters.shift();
+    if (waiter) waiter.resolve({ value: publicChunk, done: false });
+    else chunks.push(publicChunk);
+  }
 
   function deliver(value) {
     // This gate prevents delivery after public cancellation. It is not proof
@@ -2287,11 +2298,20 @@ function callbackStreamHandle({ runtime, request, signal, onSettled }) {
       ? value
       : { ...value, id: request.id };
     accumulator.push(chunk);
-    const publicChunk = projectPublicStreamChunk(chunk);
-    if (publicChunk === OMITTED_PUBLIC_STREAM_DATA) return;
-    const waiter = waiters.shift();
-    if (waiter) waiter.resolve({ value: publicChunk, done: false });
-    else chunks.push(publicChunk);
+    if (!observeToolText) {
+      publishChunk(chunk);
+      return;
+    }
+    observation = observation.then(async function observeBrowserWasmChunk() {
+      if (ended) return;
+      throwIfAborted(linked.controller.signal);
+      await observeToolText(chunk);
+      publishChunk(chunk);
+    });
+    observation.catch(function cancelFailedBrowserWasmObservation(error) {
+      observationError ??= error;
+      linked.controller.abort(error);
+    });
   }
 
   function finish(error = null) {
@@ -2313,17 +2333,27 @@ function callbackStreamHandle({ runtime, request, signal, onSettled }) {
   );
   const result = (async () => {
     try {
-      await terminal;
+      const terminalValue = await terminal;
+      if (observeToolText) await observation;
+      throwIfAborted(linked.controller.signal);
+      if (observeToolText) await observeToolText(terminalValue);
       throwIfAborted(linked.controller.signal);
       const value = accumulator.result();
+      if (observeToolText) await observeToolText(value);
+      throwIfAborted(linked.controller.signal);
       finish();
       return value;
     } catch (error) {
-      const normalized = normalizeArcaneAIError(error, {
+      const normalized = normalizeArcaneAIError(observationError ?? error, {
         kind: "llm",
         operation: "request",
-        signal: normalizationSignal(error, linked.controller.signal),
+        signal: observationError ? null : normalizationSignal(error, linked.controller.signal),
       });
+      if (observeToolText) {
+        await observation.catch(function retainFirstBrowserWasmStreamFailure() {
+          // The failure captured above remains the terminal outcome.
+        });
+      }
       finish(normalized);
       throw normalized;
     }
@@ -2380,7 +2410,7 @@ function callbackStreamHandle({ runtime, request, signal, onSettled }) {
   return completeValue(handle);
 }
 
-function validatedV1StreamHandle(opened, request) {
+function validatedV1StreamHandle(opened, request, observeToolText = null, signal = null) {
   if (
     !opened
     || !is.object(opened)
@@ -2429,6 +2459,16 @@ function validatedV1StreamHandle(opened, request) {
   let publicStreamSettled = false;
   let publicStreamError = null;
 
+  function stopV1ToolTextObservation(reason) {
+    if (!observeToolText) return;
+    publicStreamError ??= reason instanceof Error ? reason : fail(
+      'ARCANE_AI_REQUEST_ABORTED',
+      'The browser-WASM request was cancelled.',
+      reason,
+    );
+    settlePublicStream(publicStreamError);
+  }
+
   function publishPublicChunk(value) {
     if (publicStreamSettled) return;
     const waiter = publicChunkWaiters.shift();
@@ -2459,10 +2499,24 @@ function validatedV1StreamHandle(opened, request) {
           return true;
         }
         accumulator.push(next.value);
+        if (observeToolText) {
+          if (publicStreamError !== null) throw publicStreamError;
+          throwIfAborted(signal);
+          await observeToolText(next.value);
+          if (publicStreamError !== null) throw publicStreamError;
+          throwIfAborted(signal);
+        }
         const projected = projectPublicStreamChunk(next.value);
         if (projected !== OMITTED_PUBLIC_STREAM_DATA) publishPublicChunk(projected);
       }
     } catch (error) {
+      if (observeToolText) {
+        Promise.resolve().then(function cancelFailedV1ToolTextStream() {
+          return opened.cancel(error);
+        }).catch(function reportFailedV1ToolTextCancellation(cleanupError) {
+          arcaneLogging.error('Arcane v1 tool-text stream cancellation failed.', cleanupError);
+        });
+      }
       settlePublicStream(error);
       throw error;
     }
@@ -2476,8 +2530,15 @@ function validatedV1StreamHandle(opened, request) {
   );
   terminalResult.catch(function retainV1StreamTerminalRejection() {});
   const result = Promise.all([terminalResult, privateStreamPump]).then(
-    function correlateV1StreamTerminal([terminal]) {
+    async function correlateV1StreamTerminal([terminal]) {
+      if (observeToolText && publicStreamError !== null) throw publicStreamError;
       accumulator.correlateToolCalls(terminal);
+      if (observeToolText) {
+        throwIfAborted(signal);
+        await observeToolText(terminal);
+        if (publicStreamError !== null) throw publicStreamError;
+        throwIfAborted(signal);
+      }
       return terminal;
     },
   );
@@ -2485,6 +2546,7 @@ function validatedV1StreamHandle(opened, request) {
   const handle = {
     result,
     cancel: function cancelValidatedV1Stream(reason) {
+      stopV1ToolTextObservation(reason);
       return opened.cancel(reason);
     },
     async next() {
@@ -2496,6 +2558,7 @@ function validatedV1StreamHandle(opened, request) {
       });
     },
     async return(value) {
+      stopV1ToolTextObservation('The stream consumer stopped before completion.');
       if (is.function(iterator.return)) {
         Promise.resolve().then(function returnUnderlyingV1Stream() {
           return iterator.return(value);
@@ -2511,6 +2574,7 @@ function validatedV1StreamHandle(opened, request) {
       return { value, done: true };
     },
     async throw(error) {
+      stopV1ToolTextObservation(error);
       await opened.cancel(error);
       throw error;
     },
@@ -3171,6 +3235,7 @@ export function createBrowserWasmLlmProvider({
         runtime,
         request,
         signal: externalSignal,
+        observeToolText: context.observeToolText,
         onSettled(error) {
           if (settled) return;
           settled = true;
@@ -3452,7 +3517,7 @@ export function adaptV1LlmProvider(provider) {
       });
       return status();
     },
-    request({ role = "llm", selection, operation, payload, signal = null } = {}) {
+    request({ role = "llm", selection, operation, payload, signal = null } = {}, controls = {}) {
       assertSelection(selection, role);
       assertActiveSelection(selection);
       throwIfAborted(signal);
@@ -3466,9 +3531,9 @@ export function adaptV1LlmProvider(provider) {
       }
       if (operation === "stream") {
         validateStructuralRequest(payload);
-        return Promise.resolve(methods.stream(payload, { signal })).then(
+        return Promise.resolve(methods.stream(payload, { signal, observeToolText: controls.observeToolText })).then(
           function wrapV1StreamResult(opened) {
-            return validatedV1StreamHandle(opened, payload);
+            return validatedV1StreamHandle(opened, payload, controls.observeToolText, signal);
           },
         );
       }

package/browser-runtime/ai/model-controller.mjs

@@ -1,6 +1,7 @@
 import Is from "../dependencies/strong-type/index.js";
 import { arcaneLogging } from '../logging.mjs';
 import { createArcaneEventSource } from "arcane-os/event-manager";
+import { createToolTextObserver } from './tool-text-stream.mjs';
 
 const is = new Is(false);
 
@@ -1311,13 +1312,22 @@ export class ModelController {
     }
   }
 
-  stream(request = {}) {
+  stream(request = {}, context = {}) {
     this.#assertOperational();
     request=structuralRequest(request);
     localRequirement(request, this.#provider);
     const controller = this;
     const externalSignal = request.signal ?? null;
     const linked = linkedAbortSignal(externalSignal);
+    const observeToolText = context.observeToolText ? async function observeActiveModelToolText(chunk) {
+      if (linked.controller.signal.aborted) {
+        throw normalizeArcaneAIError(null, { operation: 'request', signal: linked.controller.signal });
+      }
+      await context.observeToolText(chunk);
+      if (linked.controller.signal.aborted) {
+        throw normalizeArcaneAIError(null, { operation: 'request', signal: linked.controller.signal });
+      }
+    } : null;
     let opened = null;
     let openedIterator = null;
     let openError = null;
@@ -1363,6 +1373,7 @@ export class ModelController {
           kind: "llm",
           operation: "stream",
           signal: linked.controller.signal,
+          observeToolText,
         },
       );
       if (
@@ -1427,10 +1438,18 @@ export class ModelController {
             return true;
           }
           streamedToolCalls.observe(next.value);
+          if (observeToolText) await observeToolText(next.value);
           const projected=projectPublicStreamChunk(next.value);
           if(projected!==OMITTED_PUBLIC_STREAM_DATA)publishPublicChunk(projected);
         }
       }catch(error){
+        if (observeToolText) {
+          Promise.resolve().then(function cancelFailedModelToolTextStream() {
+            return opened.cancel(error);
+          }).catch(function reportFailedModelToolTextCancellation(cleanupError) {
+            arcaneLogging.error('Arcane model tool-text stream cancellation failed.', cleanupError);
+          });
+        }
         settlePublicStream(error);
         throw error;
       }
@@ -1446,8 +1465,9 @@ export class ModelController {
     });
     terminalResult.catch(()=>undefined);
 
-    const result = Promise.all([terminalResult,privateStreamPump]).then(([terminal]) => {
+    const result = Promise.all([terminalResult,privateStreamPump]).then(async function completeModelStream([terminal]) {
       streamedToolCalls.correlate(terminal);
+      if (observeToolText) await observeToolText(terminal);
       settlePublicStream();
       return terminal;
     }).catch((error)=>{
@@ -1533,10 +1553,18 @@ export class ModelController {
     this.#assertOperational();
     localRequirement(options, this.#provider);
     const id = requestIdentity(options.id);
-    const request = structuralRequest({ ...options, id });
+    const { toolText, onToolText, ...requestOptions } = options;
+    const request = structuralRequest({ ...requestOptions, id });
     const displayId = displayRequestId(id);
+    const observeToolText = createToolTextObserver(
+      toolText,
+      is.function(onToolText) ? function deliverSelectedToolText(text, call) {
+        return onToolText(text, call, displayId);
+      } : onToolText,
+      { signal: options.signal },
+    );
     fireAndForget(options.onRequest, request, id);
-    const handle = this.stream(request);
+    const handle = this.stream(request, { observeToolText });
 
     try {
       for await (const chunk of handle) {

package/browser-runtime/ai/tool-text-stream.mjs

@@ -0,0 +1,364 @@
+import Is from '../dependencies/strong-type/index.js';
+
+const is = new Is(false);
+const STRING_ESCAPES = {
+    '"': '"',
+    '\\': '\\',
+    '/': '/',
+    b: '\b',
+    f: '\f',
+    n: '\n',
+    r: '\r',
+    t: '\t'
+};
+
+function projectionError(message, cause) {
+    const error = new SyntaxError(
+        `Tool text projection ${message}`,
+        cause === undefined ? undefined : {cause}
+    );
+    error.code = 'ARCANE_AI_TOOL_TEXT_INVALID';
+    return error;
+}
+
+function isWhitespace(character) {
+    return character === ' ' || character === '\t'
+        || character === '\n' || character === '\r';
+}
+
+function createArgumentScanner(field, appendText, beginText, endText) {
+    const stack = [];
+    let started = false;
+    let finished = false;
+    let string = null;
+    let scalar = null;
+
+    function finishValue() {
+        stack[stack.length - 1].state = 'commaOrEnd';
+    }
+
+    function closeContainer() {
+        stack.pop();
+        if (stack.length) {
+            finishValue();
+        } else {
+            finished = true;
+        }
+    }
+
+    function acceptStringCharacter(character) {
+        if (string.key) {
+            if (stack.length === 1) string.value += character;
+        } else if (string.selected) {
+            appendText(character, string.offset);
+            string.offset += character.length;
+        }
+    }
+
+    function readStringCharacter(character) {
+        if (string.unicode !== null) {
+            if (!/[0-9a-fA-F]/.test(character)) {
+                throw projectionError('encountered an invalid Unicode escape.');
+            }
+            string.unicode += character;
+            if (string.unicode.length === 4) {
+                acceptStringCharacter(
+                    String.fromCharCode(Number.parseInt(string.unicode, 16))
+                );
+                string.unicode = null;
+            }
+            return;
+        }
+        if (string.escaped) {
+            string.escaped = false;
+            if (character === 'u') {
+                string.unicode = '';
+            } else if (Object.hasOwn(STRING_ESCAPES, character)) {
+                acceptStringCharacter(STRING_ESCAPES[character]);
+            } else {
+                throw projectionError('encountered an invalid string escape.');
+            }
+            return;
+        }
+        if (character === '\\') {
+            string.escaped = true;
+        } else if (character === '"') {
+            const frame = stack[stack.length - 1];
+            if (string.key) {
+                frame.key = string.value;
+                frame.state = 'colon';
+            } else {
+                if (string.selected) endText(string.offset);
+                finishValue();
+            }
+            string = null;
+        } else {
+            if (character.charCodeAt(0) < 32) {
+                throw projectionError('encountered an unescaped control character.');
+            }
+            acceptStringCharacter(character);
+        }
+    }
+
+    function startString(key, selected = false) {
+        string = {key, selected, value: '', offset: 0, escaped: false, unicode: null};
+        if (selected) beginText();
+    }
+
+    function startValue(character, frame) {
+        const selected = stack.length === 1 && frame.kind === 'object'
+            && frame.key === field;
+        if (selected && character !== '"') {
+            beginText();
+            endText(0);
+        }
+        if (character === '"') {
+            startString(false, selected);
+        } else if (character === '{') {
+            stack.push(
+                {kind: 'object', state: 'keyOrEnd', key: ''}
+            );
+        } else if (character === '[') {
+            stack.push(
+                {kind: 'array', state: 'valueOrEnd'}
+            );
+        } else if (character === '-' || character >= '0' && character <= '9'
+            || character === 't' || character === 'f' || character === 'n') {
+            scalar = character;
+        } else {
+            throw projectionError('encountered an invalid argument value.');
+        }
+    }
+
+    function appendArguments(fragment) {
+        for (let position = 0; position < fragment.length; position += 1) {
+            const character = fragment[position];
+            if (string) {
+                readStringCharacter(character);
+                continue;
+            }
+            if (scalar !== null) {
+                if (!isWhitespace(character) && character !== ','
+                    && character !== '}' && character !== ']') {
+                    scalar += character;
+                    continue;
+                }
+                try {
+                    JSON.parse(scalar);
+                } catch (cause) {
+                    throw projectionError('encountered an invalid argument value.', cause);
+                }
+                scalar = null;
+                finishValue();
+            }
+            if (isWhitespace(character)) continue;
+            if (finished) {
+                throw projectionError('encountered content after the argument object.');
+            }
+            if (!started) {
+                if (character !== '{') {
+                    throw projectionError('requires a root argument object.');
+                }
+                started = true;
+                stack.push(
+                    {kind: 'object', state: 'keyOrEnd', key: ''}
+                );
+                continue;
+            }
+            const frame = stack[stack.length - 1];
+            if (frame.state === 'keyOrEnd' || frame.state === 'key') {
+                if (character === '"') {
+                    startString(true);
+                } else if (character === '}' && frame.state === 'keyOrEnd') {
+                    closeContainer();
+                } else {
+                    throw projectionError('encountered an invalid object key.');
+                }
+            } else if (frame.state === 'colon') {
+                if (character !== ':') {
+                    throw projectionError('expected a colon after an object key.');
+                }
+                frame.state = 'value';
+            } else if (frame.state === 'value' || frame.state === 'valueOrEnd') {
+                if (character === ']' && frame.state === 'valueOrEnd') {
+                    closeContainer();
+                } else {
+                    startValue(character, frame);
+                }
+            } else if (character === ',') {
+                frame.state = frame.kind === 'object' ? 'key' : 'value';
+            } else if (character === (frame.kind === 'object' ? '}' : ']')) {
+                closeContainer();
+            } else {
+                throw projectionError('expected a comma or the end of an argument container.');
+            }
+        }
+    }
+
+    return appendArguments;
+}
+
+export function createToolTextObserver(selection, onText, {signal} = {}) {
+    if (selection === undefined || selection === null || selection === false) return null;
+    if (!is.object(selection) || is.array(selection)
+        || !is.string(selection.name) || !selection.name.trim()
+        || !is.string(selection.field) || !selection.field.trim()) {
+        throw new TypeError('AI toolText must name a tool and a root string field.');
+    }
+    if (!is.function(onText)) {
+        throw new TypeError('AI onToolText must be a function when toolText is selected.');
+    }
+    const name = selection.name;
+    const field = selection.field;
+    const choices = new Map();
+
+    function recordFor(choiceIndex, index) {
+        let calls = choices.get(choiceIndex);
+        if (!calls) {
+            calls = new Map();
+            choices.set(choiceIndex, calls);
+        }
+        let record = calls.get(index);
+        if (!record) {
+            record = {
+                id: '', name: '', index, choiceIndex, pending: [], scanner: null,
+                text: '', emitted: 0, textOpen: false
+            };
+            calls.set(index, record);
+        }
+        return record;
+    }
+
+    function prepareScanner(record) {
+        if (!record.scanner) {
+            record.scanner = createArgumentScanner(
+                field,
+                function appendSelectedToolText(text, offset) {
+                    for (let index = 0; index < text.length; index += 1) {
+                        const position = offset + index;
+                        if (position < record.text.length) {
+                            if (record.text[position] !== text[index]) {
+                                throw projectionError('received conflicting selected argument text.');
+                            }
+                        } else {
+                            record.text += text[index];
+                        }
+                    }
+                },
+                function beginSelectedToolText() {
+                    if (record.emitted === 0) record.text = '';
+                    record.textOpen = true;
+                },
+                function finishSelectedToolText(length) {
+                    if (length < record.text.length) {
+                        throw projectionError('received a shorter replacement for selected argument text.');
+                    }
+                    record.textOpen = false;
+                }
+            );
+        }
+        for (const fragment of record.pending) record.scanner(fragment);
+        record.pending = [];
+    }
+
+    function observeCompleteArguments(record, argumentsValue) {
+        let argumentsObject = argumentsValue;
+        if (is.string(argumentsObject)) {
+            try {
+                argumentsObject = JSON.parse(argumentsObject);
+            } catch (cause) {
+                throw projectionError('received invalid complete argument JSON.', cause);
+            }
+        }
+        if (!argumentsObject || !is.object(argumentsObject) || is.array(argumentsObject)) {
+            throw projectionError('requires a complete argument object.');
+        }
+        if (!Object.hasOwn(argumentsObject, field)) {
+            if (record.emitted > 0) {
+                throw projectionError('lost the selected argument field in a complete response.');
+            }
+            record.text = '';
+            record.textOpen = false;
+            return;
+        }
+        const text = argumentsObject[field];
+        if (!is.string(text)) {
+            throw projectionError('requires the selected argument field to be a string.');
+        }
+        // A terminal snapshot may repeat a complete value already streamed.
+        if (record.emitted > 0 && !text.startsWith(record.text)) {
+            throw projectionError('received conflicting complete argument text.');
+        }
+        record.text = text;
+        record.textOpen = false;
+    }
+
+    async function emitSelectedText(record) {
+        if (signal?.aborted || record.name !== name || !record.id) return;
+        let end = record.text.length;
+        if (record.textOpen && end > record.emitted) {
+            // Keep a split surrogate pair together without changing its code units.
+            const last = record.text.charCodeAt(end - 1);
+            if (last >= 0xD800 && last <= 0xDBFF) end -= 1;
+        }
+        if (end <= record.emitted) return;
+        const text = record.text.slice(record.emitted, end);
+        record.emitted = end;
+        await onText(
+            text,
+            {id: record.id, name: record.name, field, index: record.index, choiceIndex: record.choiceIndex}
+        );
+    }
+
+    async function observeCalls(calls, choiceIndex, complete) {
+        if (!is.array(calls)) return;
+        for (let position = 0; position < calls.length; position += 1) {
+            if (signal?.aborted) return;
+            const call = calls[position];
+            if (!call || !is.object(call)) continue;
+            const record = recordFor(choiceIndex, call.index ?? position);
+            if (is.string(call.id) && call.id) {
+                if (record.emitted && record.id !== call.id) {
+                    throw projectionError('changed the identity of a displayed tool call.');
+                }
+                record.id = call.id;
+            }
+            const functionValue = call.function && is.object(call.function)
+                ? call.function
+                : {};
+            if (is.string(functionValue.name)) {
+                const nextName = complete ? functionValue.name : record.name + functionValue.name;
+                if (record.emitted && nextName !== record.name) {
+                    throw projectionError('changed the name of a displayed tool call.');
+                }
+                record.name = nextName;
+            }
+            if (!name.startsWith(record.name)) {
+                record.pending = [];
+                continue;
+            }
+            if (!complete && is.string(functionValue.arguments)) {
+                record.pending.push(functionValue.arguments);
+            }
+            if (record.name !== name) continue;
+            prepareScanner(record);
+            if (complete) observeCompleteArguments(record, functionValue.arguments);
+            await emitSelectedText(record);
+        }
+    }
+
+    return async function observeToolText(chunk) {
+        if (signal?.aborted || !chunk || !is.object(chunk)) return;
+        if (is.array(chunk.choices)) {
+            for (let position = 0; position < chunk.choices.length; position += 1) {
+                if (signal?.aborted) return;
+                const choice = chunk.choices[position];
+                if (!choice || !is.object(choice)) continue;
+                const choiceIndex = choice.index ?? position;
+                await observeCalls(choice.delta?.tool_calls, choiceIndex, false);
+                await observeCalls(choice.message?.tool_calls, choiceIndex, true);
+            }
+        }
+        if (!signal?.aborted) await observeCalls(chunk.message?.tool_calls, 0, true);
+    };
+}

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.3",
+  "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){
@@ -4622,7 +4637,8 @@ class AI {
                 true,
                 onDataChunk,
                 onDataResult,
-                normalizedReasoningEffort
+                normalizedReasoningEffort,
+                observeToolText
             );
             const structuralToolCalls=normalizeAICompletionToolCalls(
                 completion
@@ -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){
@@ -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){

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);

package/runtime/arcane/modules/ConversationClosingReport.js

@@ -74,7 +74,7 @@ function parseArguments(value){
     return value;
 }
 
-function escapeRawHTML(value){
+export function formatConversationClosingReportText(value){
     return value
         .replaceAll('&','&')
         .replaceAll('<','&lt;')
@@ -240,7 +240,7 @@ export function formatConversationClosingReport(value){
             remembered_actions:value.rememberedActions,
         }
         :value;
-    return escapeRawHTML(
+    return formatConversationClosingReportText(
         normalizeConversationClosingReport(normalizedInput).finalMessage
     );
 }

package/src/import-map.mjs

@@ -27,6 +27,7 @@ const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/pwa','sdk/pwa.mjs'],
     ['arcane-os/speech-text','sdk/speech-text.mjs'],
     ['arcane-os/ai/browser-wasm',SDK_BROWSER_AI_ENTRY],
+    ['arcane-os/ai/tool-text-stream','sdk/ai/tool-text-stream.mjs'],
     ['arcane-os/ai/browser-speech',SDK_BROWSER_SPEECH_ENTRY]
 ]);
 function fail(message,code='ARCANE_IMPORT_MAP_INVALID'){