@tagit/ai-client-core 1.2.0-beta.27.1 → 1.2.0-beta.29.1

package/README.md

@@ -285,7 +285,7 @@ Legacy collector identity fields are still accepted for migration compatibility,
 |---|---|---:|---|---|
 | `ui.theme` | `'light' \| 'dark'` | `undefined` | Forces the UI theme used by the React package. | `dark` |
 | `ui.streaming` | `boolean` | `true` | Enables streaming response handling. | `true` |
-| `ui.showToolCalls` | `boolean` | `true` | Shows tool call activity in the UI layer. | `true` |
+| `ui.showToolCalls` | `boolean` | `false` | Reserved for host-owned debug/tool-call UI. The built-in chat keeps tool execution out of the end-user message surface by default. | `false` |
 | `ui.maxMessageCharacters.user` | positive integer | `2000` | Maximum user message length before truncation. | `2000` |
 | `ui.maxMessageCharacters.assistant` | positive integer | `3000` | Maximum assistant message length before truncation. | `3000` |
 | `ui.maxHistoryMessages` | positive integer | `50` | Maximum messages preserved before history trimming warnings. | `50` |

package/dist/client.d.ts

@@ -89,11 +89,16 @@ export declare class AIClient {
      * Handle a single chunk from the orchestrator
      */
     private handleChunk;
+    private handleSseMessage;
+    private syncStreamSessionState;
     /**
-     * Drip-feed text word-by-word to simulate streaming when the server batched
-     * the entire response in one chunk. Targets ~1.5 s total regardless of length.
+     * Drip-feed text word-by-word when a provider or proxy batches a large answer
+     * into one chunk. This preserves a readable progressive reveal without
+     * changing the durable final text.
      */
     private simulateDeltaStream;
+    private shouldSmoothRevealDelta;
+    private appendAssistantText;
     private shouldRetry;
     private tryParseJson;
     private isCanonicalChunk;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -1,5 +1,7 @@
 import { validateConfig } from './config.js';
 import { FetchConversationHistoryTransport, FetchOrchestratorTransport, } from './transport.js';
+import { SseDecoder } from './sse.js';
+import { StreamSession } from './stream-session.js';
 /**
  * Generate a unique ID
  */
@@ -85,6 +87,7 @@ export class AIClient {
             isLoading: false,
             isStreaming: false,
             useCaseId: initialUseCaseId,
+            streamStatus: 'idle',
         };
         this.notifyActiveAgentChange(this.getActiveAgent());
     }
@@ -150,6 +153,7 @@ export class AIClient {
             isLoading: false,
             isStreaming: false,
             useCaseId: agent.useCaseId,
+            streamStatus: 'idle',
         };
         this.emit({
             type: 'active_agent_changed',
@@ -543,6 +547,15 @@ export class AIClient {
             const normalized = this.normalizeError(error);
             this.conversationState.error = normalized.safeMessage;
             this.conversationState.lastError = normalized;
+            this.conversationState.streamStatus = normalized.code === 'CANCELED' ? 'canceled' : 'failed';
+            this.conversationState.streamDiagnostics = [
+                ...(this.conversationState.streamDiagnostics ?? []),
+                {
+                    code: normalized.code,
+                    message: normalized.safeMessage,
+                    retryable: normalized.retryable,
+                },
+            ];
             if (normalized.code === 'CANCELED') {
                 this.emit({ type: 'request_canceled' });
             }
@@ -571,6 +584,15 @@ export class AIClient {
             catch (error) {
                 const normalized = this.normalizeError(error);
                 if (this.shouldAcceptDegradedCompletion(normalized, attempt, maxAttempts)) {
+                    this.conversationState.streamStatus = 'degraded';
+                    this.conversationState.streamDiagnostics = [
+                        ...(this.conversationState.streamDiagnostics ?? []),
+                        {
+                            code: normalized.code,
+                            message: normalized.safeMessage,
+                            retryable: normalized.retryable,
+                        },
+                    ];
                     this.emit({ type: 'streaming_completed' });
                     this.emit({
                         type: 'streaming_completed_degraded',
@@ -578,9 +600,13 @@ export class AIClient {
                     });
                     return;
                 }
-                // Remove incomplete assistant-side artifacts before next attempt.
-                this.conversationState.messages = this.conversationState.messages.slice(0, baselineLength);
                 if (this.shouldRetry(normalized, attempt, maxAttempts)) {
+                    // Remove incomplete assistant-side artifacts before next attempt.
+                    this.conversationState.messages = this.conversationState.messages.slice(0, baselineLength);
+                    this.conversationState.streamStatus = 'idle';
+                    this.conversationState.toolActivities = [];
+                    this.conversationState.usageEvents = [];
+                    this.conversationState.streamDiagnostics = [];
                     this.emit({
                         type: 'request_retried',
                         attempt: attempt + 1,
@@ -588,6 +614,9 @@ export class AIClient {
                     });
                     continue;
                 }
+                if (!normalized.details?.hasAssistantContent && !normalized.details?.hasToolActivity) {
+                    this.conversationState.messages = this.conversationState.messages.slice(0, baselineLength);
+                }
                 throw normalized;
             }
         }
@@ -596,6 +625,8 @@ export class AIClient {
      * Stream response from orchestrator
      */
     async streamResponse(options) {
+        const streamSession = new StreamSession();
+        this.syncStreamSessionState(streamSession.snapshot(), false);
         const requestMessages = this.buildRequestMessages(options?.useCaseMessage);
         const endpointPath = this.getEndpointPath();
         const request = {
@@ -680,8 +711,7 @@ export class AIClient {
                     retryable: true,
                 });
             }
-            const decoder = new TextDecoder();
-            let buffer = '';
+            const sseDecoder = new SseDecoder();
             let streamCompleted = false;
             let emittedFirstToken = false;
             try {
@@ -689,76 +719,32 @@ export class AIClient {
                     const { done, value } = await reader.read();
                     if (done)
                         break;
-                    buffer += decoder.decode(value, { stream: true });
-                    const lines = buffer.split('\n');
-                    buffer = lines.pop() || '';
-                    for (const line of lines) {
-                        if (line.startsWith('data: ')) {
-                            const dataStr = line.slice(6).trim();
-                            if (!dataStr)
-                                continue;
-                            if (dataStr === '[DONE]') {
-                                streamCompleted = true;
-                                continue;
-                            }
-                            const parsed = this.tryParseJson(dataStr);
-                            if (!parsed || !this.isCanonicalChunk(parsed)) {
-                                throw this.createError({
-                                    code: 'STREAM_FAILED',
-                                    message: 'Received non-canonical stream chunk payload',
-                                    safeMessage: 'The orchestrator returned an unsupported stream chunk format.',
-                                    retryable: true,
-                                    details: { chunk: dataStr },
-                                });
-                            }
-                            const result = await this.handleChunk(parsed);
-                            if (result.type === 'delta' && result.text && !emittedFirstToken) {
-                                emittedFirstToken = true;
-                                this.emit({ type: 'first_token', messageId: result.messageId });
-                            }
-                            if (result.type === 'complete') {
-                                streamCompleted = true;
-                            }
+                    const messages = sseDecoder.push(value);
+                    for (const message of messages) {
+                        const result = await this.handleSseMessage(message.data, streamSession);
+                        if (result.type === 'delta' && result.text && !emittedFirstToken) {
+                            emittedFirstToken = true;
+                            this.emit({ type: 'first_token', messageId: result.messageId });
+                        }
+                        if (result.type === 'complete') {
+                            streamCompleted = true;
                         }
                     }
                 }
-                // Process any remaining buffer
-                if (buffer && buffer.startsWith('data: ')) {
-                    const dataStr = buffer.slice(6).trim();
-                    if (dataStr) {
-                        try {
-                            if (dataStr === '[DONE]') {
-                                streamCompleted = true;
-                            }
-                            else {
-                                const parsed = this.tryParseJson(dataStr);
-                                if (!parsed || !this.isCanonicalChunk(parsed)) {
-                                    throw this.createError({
-                                        code: 'STREAM_FAILED',
-                                        message: 'Received non-canonical final stream chunk payload',
-                                        safeMessage: 'The orchestrator returned an unsupported stream chunk format.',
-                                        retryable: true,
-                                        details: { chunk: dataStr },
-                                    });
-                                }
-                                const result = await this.handleChunk(parsed);
-                                if (result.type === 'delta' && result.text && !emittedFirstToken) {
-                                    emittedFirstToken = true;
-                                    this.emit({ type: 'first_token', messageId: result.messageId });
-                                }
-                                if (result.type === 'complete') {
-                                    streamCompleted = true;
-                                }
-                            }
-                        }
-                        catch (error) {
-                            console.warn('Failed to parse final chunk:', error);
-                            throw error;
-                        }
+                const finalMessages = sseDecoder.flush();
+                for (const message of finalMessages) {
+                    const result = await this.handleSseMessage(message.data, streamSession, true);
+                    if (result.type === 'delta' && result.text && !emittedFirstToken) {
+                        emittedFirstToken = true;
+                        this.emit({ type: 'first_token', messageId: result.messageId });
+                    }
+                    if (result.type === 'complete') {
+                        streamCompleted = true;
                     }
                 }
                 if (!streamCompleted) {
-                    const hasAssistantContent = this.hasAssistantContent();
+                    const sessionSnapshot = streamSession.snapshot();
+                    const hasAssistantContent = this.hasAssistantContent() || sessionSnapshot.hasVisibleOutput;
                     throw this.createError({
                         code: 'STREAM_INCOMPLETE',
                         message: 'Stream ended before receiving a complete event',
@@ -766,6 +752,7 @@ export class AIClient {
                         retryable: true,
                         details: {
                             hasAssistantContent,
+                            hasToolActivity: sessionSnapshot.hasToolActivity,
                         },
                     });
                 }
@@ -786,7 +773,11 @@ export class AIClient {
     /**
      * Handle a single chunk from the orchestrator
      */
-    async handleChunk(chunk) {
+    async handleChunk(chunk, streamSession) {
+        const sessionResult = streamSession?.apply(chunk);
+        if (streamSession) {
+            this.syncStreamSessionState(streamSession.snapshot());
+        }
         switch (chunk.type) {
             case 'start':
                 {
@@ -805,14 +796,12 @@ export class AIClient {
                     const lastMessage = this.conversationState.messages[this.conversationState.messages.length - 1];
                     if (lastMessage && lastMessage.role === 'assistant') {
                         const text = String(chunk.data.text || '');
-                        lastMessage.content += text;
-                        // Truncate if exceeds limit
-                        const limit = this.config.ui?.maxMessageCharacters?.assistant ?? 3000;
-                        if (lastMessage.content.length > limit) {
-                            lastMessage.content = this.truncateMessage('assistant', lastMessage.content);
+                        if (this.shouldSmoothRevealDelta(text, lastMessage.content)) {
+                            await this.simulateDeltaStream(text, lastMessage.id);
+                        }
+                        else {
+                            this.appendAssistantText(lastMessage, text, lastMessage.id);
                         }
-                        this.emit({ type: 'message_updated', message: lastMessage });
-                        this.emit({ type: 'stream_delta', messageId: lastMessage.id, text });
                         return { type: 'delta', text, messageId: lastMessage.id };
                     }
                 }
@@ -853,6 +842,10 @@ export class AIClient {
                     }
                 }
                 return { type: 'none' };
+            case 'tool_progress':
+            case 'provider_usage':
+            case 'stream_error':
+                return { type: 'none' };
             case 'complete': {
                 const text = this.extractAssistantText(chunk.data) ?? '';
                 const lastMsg = this.conversationState.messages[this.conversationState.messages.length - 1];
@@ -869,6 +862,9 @@ export class AIClient {
             }
             case 'error':
                 {
+                    if (streamSession) {
+                        this.syncStreamSessionState(streamSession.snapshot());
+                    }
                     const payloadMessage = typeof chunk.data.message === 'string'
                         ? chunk.data.message
                         : typeof chunk.data.error === 'string'
@@ -883,13 +879,60 @@ export class AIClient {
                     });
                 }
             default:
-                console.warn('Unknown chunk type:', chunk.type);
+                if (sessionResult?.type === 'error') {
+                    throw this.createError({
+                        code: 'STREAM_FAILED',
+                        message: sessionResult.diagnostic.message,
+                        safeMessage: 'Orchestrator reported an error while streaming.',
+                        retryable: true,
+                        details: { diagnostic: sessionResult.diagnostic },
+                    });
+                }
                 return { type: 'none' };
         }
     }
+    async handleSseMessage(dataStr, streamSession, isFinalChunk = false) {
+        const data = dataStr.trim();
+        if (!data)
+            return { type: 'none' };
+        if (data === '[DONE]')
+            return { type: 'complete' };
+        const parsed = this.tryParseJson(data);
+        if (!parsed || !this.isCanonicalChunk(parsed)) {
+            throw this.createError({
+                code: 'STREAM_FAILED',
+                message: isFinalChunk
+                    ? 'Received non-canonical final stream chunk payload'
+                    : 'Received non-canonical stream chunk payload',
+                safeMessage: 'The orchestrator returned an unsupported stream chunk format.',
+                retryable: true,
+                details: { chunk: data },
+            });
+        }
+        return this.handleChunk(parsed, streamSession);
+    }
+    syncStreamSessionState(snapshot, emitEvent = true) {
+        this.conversationState.streamStatus = snapshot.status;
+        this.conversationState.toolActivities = snapshot.toolActivities;
+        this.conversationState.usageEvents = snapshot.usageEvents;
+        this.conversationState.streamDiagnostics = snapshot.diagnostics;
+        if (snapshot.workflowId) {
+            this.conversationState.workflowId = snapshot.workflowId;
+        }
+        if (snapshot.workflowStatus) {
+            this.conversationState.workflowStatus = snapshot.workflowStatus;
+        }
+        if (snapshot.checkpointPrompt !== undefined) {
+            this.conversationState.checkpointPrompt = snapshot.checkpointPrompt;
+        }
+        if (emitEvent) {
+            this.emit({ type: 'stream_state_updated' });
+        }
+    }
     /**
-     * Drip-feed text word-by-word to simulate streaming when the server batched
-     * the entire response in one chunk. Targets ~1.5 s total regardless of length.
+     * Drip-feed text word-by-word when a provider or proxy batches a large answer
+     * into one chunk. This preserves a readable progressive reveal without
+     * changing the durable final text.
      */
     async simulateDeltaStream(text, messageId) {
         // Split on word boundaries, keeping trailing whitespace with each token.
@@ -907,15 +950,35 @@ export class AIClient {
         while (i < tokens.length) {
             const chunk = tokens.slice(i, i + batchSize).join('');
             i += batchSize;
-            lastMessage.content += chunk;
-            this.emit({ type: 'message_updated', message: lastMessage });
-            this.emit({ type: 'stream_delta', messageId, text: chunk });
+            this.appendAssistantText(lastMessage, chunk, messageId);
             if (i < tokens.length) {
                 await new Promise((resolve) => setTimeout(resolve, INTERVAL_MS));
             }
         }
     }
+    shouldSmoothRevealDelta(text, currentContent) {
+        if ((this.config.ui?.streaming ?? true) === false)
+            return false;
+        if (!text.trim())
+            return false;
+        if (currentContent.trim())
+            return false;
+        return text.length >= 180 || (text.match(/\S+\s*/g)?.length ?? 0) >= 28;
+    }
+    appendAssistantText(message, text, messageId) {
+        message.content += text;
+        const limit = this.config.ui?.maxMessageCharacters?.assistant ?? 3000;
+        if (message.content.length > limit) {
+            message.content = this.truncateMessage('assistant', message.content);
+        }
+        this.emit({ type: 'message_updated', message });
+        this.emit({ type: 'stream_delta', messageId, text });
+    }
     shouldRetry(error, attempt, maxAttempts) {
+        if (error.code === 'STREAM_INCOMPLETE' &&
+            (error.details?.hasAssistantContent || error.details?.hasToolActivity)) {
+            return false;
+        }
         return error.retryable && error.code !== 'CANCELED' && attempt < maxAttempts;
     }
     tryParseJson(value) {
@@ -1093,10 +1156,7 @@ export class AIClient {
         if (error.code !== 'STREAM_INCOMPLETE') {
             return false;
         }
-        if (attempt < maxAttempts) {
-            return false;
-        }
-        return Boolean(error.details?.hasAssistantContent);
+        return Boolean(error.details?.hasAssistantContent) && !this.shouldRetry(error, attempt, maxAttempts);
     }
     hasAssistantContent() {
         return this.conversationState.messages.some((message) => message.role === 'assistant' && message.content.trim().length > 0);
@@ -1279,6 +1339,10 @@ export class AIClient {
         }
         this.conversationState.error = undefined;
         this.conversationState.lastError = undefined;
+        this.conversationState.streamStatus = 'idle';
+        this.conversationState.toolActivities = [];
+        this.conversationState.usageEvents = [];
+        this.conversationState.streamDiagnostics = [];
         this.conversationState.isStreaming = false;
         this.emit({ type: 'state_synced' });
     }
@@ -1305,6 +1369,7 @@ export class AIClient {
             isLoading: false,
             isStreaming: false,
             useCaseId: this.resolveHistoryUseCaseId(options),
+            streamStatus: 'idle',
         };
         this.setActiveConversationMetadata(conversationId, options?.title, {
             clearTitle: !options?.title?.trim(),
@@ -1357,6 +1422,7 @@ export class AIClient {
             useCaseId: identity.useCaseId,
             error: undefined,
             lastError: undefined,
+            streamStatus: 'idle',
         };
         this.setActiveConversationMetadata(conversation.conversationId, conversation.title);
         this.createdConversationIds.add(conversation.conversationId);