arcane-os 0.13.2 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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
+  muted. Preserve pending speech cleanup, unmuted flushing, explicit public
+  speech methods, and model response callbacks across all streaming routes.
+
 ## 0.13.2
 
 - Correct the PWA development guide to describe live descriptor refresh and

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-speech.md

@@ -598,6 +598,12 @@ boundary; `finishTTS()` flushes any remaining text. It is not a playback-ended
 notification. Do not mute or dispose immediately after it if playback should
 continue.
 
+Automatic model-stream completion reads the AI instance's current mute state.
+While muted, it clears pending speech text and formatting state and stops
+prepared playback without invoking `finishTTS()` or `streamTTS()`. Unmuted
+completion keeps its ordinary speech flush. Explicit calls to either public
+speech method retain their existing behavior.
+
 ## Automatic speech-input formatting cleanup
 
 Every TTS entrypoint removes repeated same formatting marks from the outbound