@servicetitan/titan-chatbot-api 7.1.2 → 9.0.0

package/src/stores/chatbot-ui-backend.store.ts

@@ -9,16 +9,25 @@ import {
     ChatUiEvent,
     ChatUiEventListener,
     IChatUiBackendStore,
+    StreamingProgressModel,
 } from '@servicetitan/titan-chat-ui-common';
 import axios from 'axios';
 import { makeObservable, runInAction } from 'mobx';
 import { CHATBOT_API_CLIENT, IChatbotApiClient, Models, ModelsUtils } from '../api-client';
+import {
+    DEFAULT_STREAMING_INACTIVITY_TIMEOUT_MS,
+    isChatbotStreamingEnabled,
+} from '../models/chatbot-customizations';
+import { AgentStreamError, AgentStreamHandlers } from '../streaming';
 import { withTimeout } from '../utils/axios-utils';
 import { CHATBOT_UI_STORE_TOKEN, ChatbotUiEvent, IChatbotUiStore } from './chatbot-ui.store';
 import { InitializeStore } from './initialize.store';
 
 const DEFAULT_CHATBOT_ASK_BOT_TIMEOUT_MS = 31000; // 31 seconds
 
+const STREAMING_KEEPALIVE_TEXT = 'Still working on it…';
+const STREAMING_STEP_ERROR = 'Something went wrong during this step. Please try again.';
+
 const isAbortedError = (error: unknown): boolean =>
     axios.isCancel(error) || (error as { name?: string } | null)?.name === 'AbortError';
 
@@ -28,6 +37,10 @@ export const CHATBOT_UI_BACKEND_STORE_TOKEN = symbolToken<IChatbotUiBackendStore
 
 export interface IChatbotUiBackendStore extends IChatUiBackendStore {
     session?: Models.ISession;
+    /** Live progress for the in-flight streamed run. */
+    streamingProgress: StreamingProgressModel;
+    /** Count of streaming → non-streaming fallbacks. */
+    streamingFallbackCount: number;
     initialize: () => void;
     saveCurrentState: () => void;
     deleteFromSessionStorage: () => void;
@@ -40,6 +53,12 @@ export interface IChatbotUiBackendStore extends IChatUiBackendStore {
 export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUiBackendStore {
     session?: Models.ISession;
     abortController!: AbortController;
+
+    /** Live progress for the in-flight streamed run (status line, activity log, steps, keepalive). */
+    readonly streamingProgress = new StreamingProgressModel();
+    /** Count of streaming → non-streaming fallbacks, tracked separately for regression detection. */
+    streamingFallbackCount = 0;
+
     @inject(CHATBOT_API_CLIENT) protected readonly chatbotApiClient!: IChatbotApiClient;
     @inject(CHATBOT_UI_STORE_TOKEN) protected readonly chatUiStore!: IChatbotUiStore;
 
@@ -112,7 +131,7 @@ export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUi
         selections: Models.Selections | undefined,
         timeoutMs?: number
     ) => {
-        await this.sendMessage(messageModel, selections, timeoutMs);
+        await this.routeSend(messageModel, selections, timeoutMs);
         resolve();
     };
 
@@ -127,7 +146,7 @@ export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUi
         }
         const selections = messageModel.data?.selections as Models.Selections | undefined;
         const timeoutMs = messageModel.data?.timeoutMs as number | undefined;
-        await this.sendMessage(messageModel as ChatMessageModelText, selections, timeoutMs);
+        await this.routeSend(messageModel as ChatMessageModelText, selections, timeoutMs);
         resolve();
     };
 
@@ -299,6 +318,21 @@ export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUi
         this.chatUiStore.addMessage(true, answer.answer, answer);
     }
 
+    /**
+     * Routes a send to the SSE streaming path when enabled (and supported by the client),
+     * otherwise to the existing non-streaming path. Default is non-streaming.
+     */
+    protected routeSend(
+        messageModel: ChatMessageModelText,
+        selections?: Models.Selections,
+        timeoutMs?: number
+    ): Promise<void> {
+        if (isChatbotStreamingEnabled(this.customizations) && this.chatbotApiClient.streamMessage) {
+            return this.sendMessageStreaming(messageModel, selections, timeoutMs);
+        }
+        return this.sendMessage(messageModel, selections, timeoutMs);
+    }
+
     protected async sendMessage(
         messageModel: ChatMessageModelText,
         selections?: Models.Selections,
@@ -360,6 +394,147 @@ export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUi
         }
     }
 
+    /**
+     * Streaming send-path: consumes the SSE agent-progress stream, rendering live progress and
+     * resolving the final answer on `run.finished`. Applies an inactivity-only timeout (no hard
+     * request timeout). Falls back transparently to {@link sendMessage} when the stream is
+     * unreachable at connect time — propagating the original per-message `timeoutMs` so the
+     * fallback behaves identically to the non-streaming path; surfaces a step error if the
+     * connection fails after connecting.
+     */
+    protected async sendMessageStreaming(
+        messageModel: ChatMessageModelText,
+        selections?: Models.Selections,
+        timeoutMs?: number
+    ) {
+        const question = messageModel.message;
+        const perRequestController = new AbortController();
+        const forwardStoreAbort = () =>
+            perRequestController.abort(this.abortController.signal.reason);
+        this.abortController.signal.addEventListener('abort', forwardStoreAbort, { once: true });
+
+        let connected = false;
+        try {
+            await this.startSession();
+            this.chatUiStore.setAgentTyping(true);
+            runInAction(() => this.streamingProgress.reset());
+
+            const inactivityTimeoutMs =
+                this.customizations?.streaming?.inactivityTimeoutMs ??
+                DEFAULT_STREAMING_INACTIVITY_TIMEOUT_MS;
+
+            // Apply a progress mutation, then scroll so the newest event stays in view.
+            const updateProgress = (mutate: () => void) => {
+                runInAction(mutate);
+                this.chatUiStore.triggerScroll();
+            };
+
+            const handlers: AgentStreamHandlers = {
+                inactivityTimeoutMs,
+                onStatus: text =>
+                    updateProgress(() => {
+                        this.streamingProgress.clearKeepalive();
+                        this.streamingProgress.setStatus(text);
+                    }),
+                onText: text =>
+                    updateProgress(() => {
+                        this.streamingProgress.clearKeepalive();
+                        this.streamingProgress.appendLog(text);
+                    }),
+                onPlan: steps =>
+                    updateProgress(() => {
+                        this.streamingProgress.clearKeepalive();
+                        this.streamingProgress.setSteps(steps);
+                    }),
+                onStepActive: id =>
+                    updateProgress(() => {
+                        this.streamingProgress.clearKeepalive();
+                        this.streamingProgress.setActiveStep(id);
+                    }),
+                onInactivity: () =>
+                    updateProgress(() =>
+                        this.streamingProgress.setKeepalive(STREAMING_KEEPALIVE_TEXT)
+                    ),
+                onConnected: () => {
+                    connected = true;
+                    this.logStreaming('connected');
+                },
+                onDisconnected: () => this.logStreaming('disconnected'),
+                onTimeout: () => this.logStreaming('timed_out'),
+                onCompleted: () => this.logStreaming('completed'),
+            };
+
+            const answer = await this.api(
+                'streamMessage',
+                new Models.UserMessage({
+                    sessionId: this.session!.id!,
+                    question,
+                    experience: Models.Experience.MultiTurn,
+                    selections,
+                }),
+                handlers,
+                perRequestController.signal
+            );
+
+            this.withSaveState(() => {
+                this.chatUiStore.setMessageState(messageModel, ChatMessageState.Delivered, {
+                    answerId: answer.id,
+                    selections,
+                });
+                this.processBotAnswer(answer);
+                this.chatUiStore.resetError(ChatRunState.Started);
+            });
+            /*
+             * Mark every plan step done and clear the transient keepalive; the rendered trail is
+             * faded by the UI once the final answer is shown. The next streamed send resets the model.
+             */
+            runInAction(() => {
+                this.streamingProgress.completeAllSteps();
+                this.streamingProgress.clearKeepalive();
+            });
+        } catch (error: unknown) {
+            if (isAbortedError(error)) {
+                return;
+            }
+
+            // Never connected → the endpoint was unreachable at connect time: fall back silently.
+            if (!connected) {
+                this.streamingFallbackCount += 1;
+                this.logStreaming('fallback');
+                runInAction(() => this.streamingProgress.reset());
+                await this.sendMessage(messageModel, selections, timeoutMs);
+                return;
+            }
+
+            // Connected then failed: surface the step error (the agent's message if provided).
+            this.withSaveState(() => {
+                this.chatUiStore.setMessageState(messageModel, ChatMessageState.Failed, {
+                    selections,
+                });
+            });
+            runInAction(() => this.streamingProgress.reset());
+            const message =
+                error instanceof AgentStreamError ? error.message : STREAMING_STEP_ERROR;
+            if (error instanceof ChatError) {
+                this.setChatError('FailedToSendMessage', error);
+            } else {
+                this.setError('FailedToSendMessage', 'Send message', message, error);
+            }
+        } finally {
+            this.abortController.signal.removeEventListener('abort', forwardStoreAbort);
+            this.chatUiStore.setAgentTyping(false);
+        }
+    }
+
+    /** Logs a streaming connection lifecycle phase (connected, disconnected, timed_out, completed, fallback). */
+    protected logStreaming(phase: string): void {
+        this.logService.info({
+            message: `Streaming ${phase}`,
+            category: 'TitanChatbot',
+            code: `TitanChatbot_Streaming_${phase}`,
+        });
+    }
+
     protected setSession(session?: Models.ISession) {
         this.session = session;
     }
@@ -400,8 +575,8 @@ export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUi
 
     protected async api<
         K extends keyof IChatbotApiClient,
-        Args extends Parameters<IChatbotApiClient[K]>,
-        Result extends ReturnType<IChatbotApiClient[K]>,
+        Args extends Parameters<NonNullable<IChatbotApiClient[K]>>,
+        Result extends ReturnType<NonNullable<IChatbotApiClient[K]>>,
     >(methodName: K, ...args: Args): Promise<Awaited<Result>> {
         const method = this.chatbotApiClient[methodName];
         if (method) {

package/src/stores/index.ts

@@ -1,14 +1,7 @@
-export {
-    CHATBOT_UI_BACKEND_STORE_TOKEN,
-    IChatbotUiBackendStore,
-    ChatbotUiBackendStore,
-} from './chatbot-ui-backend.store';
-export {
-    CHATBOT_UI_STORE_TOKEN,
-    IChatbotUiStore,
-    ChatbotUiStore,
-    ChatbotUiEvent,
-} from './chatbot-ui.store';
+export type { IChatbotUiBackendStore } from './chatbot-ui-backend.store';
+export { CHATBOT_UI_BACKEND_STORE_TOKEN, ChatbotUiBackendStore } from './chatbot-ui-backend.store';
+export type { IChatbotUiStore } from './chatbot-ui.store';
+export { CHATBOT_UI_STORE_TOKEN, ChatbotUiStore, ChatbotUiEvent } from './chatbot-ui.store';
 export {
     type IUiFilterOption,
     type IFilterStore,
@@ -18,4 +11,4 @@ export { InitializeStore, InitializeStoreStatus } from './initialize.store';
 export { MessageFeedbackStore } from './message-feedback.store';
 export { MessageFeedbackGuardrailStore } from './message-feedback-guardrail.store';
 export { SessionFeedbackStore } from './session-feedback.store';
-export { type FeedbackDraft, IMessageFeedbackBaseStore } from './message-feedback-base.store';
+export type { FeedbackDraft, IMessageFeedbackBaseStore } from './message-feedback-base.store';

package/src/streaming/__tests__/agent-stream.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from '@jest/globals';
+import { Models } from '../../api-client';
+import { convertAgentFinishToBotMessage } from '../agent-stream';
+
+describe('convertAgentFinishToBotMessage', () => {
+    test('preserves the backend BotMessage fields verbatim', () => {
+        // Real Bifurcation payload: backend sends guardFlag "BI" + isGuardrailed true.
+        const message = convertAgentFinishToBotMessage({
+            answer: 'pick one',
+            guardFlag: 'BI',
+            isGuardrailed: true,
+            sessionId: 122,
+            status: 'Bifurcation',
+        });
+
+        expect(message).toBeInstanceOf(Models.BotMessage);
+        expect(message.answer).toBe('pick one');
+        expect(message.guardFlag).toBe('BI');
+        expect(message.isGuardrailed).toBe(true);
+        expect(message.sessionId).toBe(122);
+    });
+
+    test('ignores streaming-only metadata (status, durationMs, runId, seq)', () => {
+        const message = convertAgentFinishToBotMessage({
+            answer: 'ok',
+            guardFlag: 'N',
+            isGuardrailed: false,
+            status: 'Success',
+            durationMs: 13603,
+            runId: 'ec66a0b47d99430a99b964f7478aadd7',
+            seq: 6,
+        });
+
+        const json = message.toJSON();
+        expect(json).not.toHaveProperty('status');
+        expect(json).not.toHaveProperty('durationMs');
+        expect(json).not.toHaveProperty('runId');
+        expect(json).not.toHaveProperty('seq');
+    });
+
+    test('wraps nested data into serializable instances (toJSON does not throw)', () => {
+        // Mirrors the decoded SSE JSON: nested data arrives as plain objects, not class instances.
+        const payload: any = {
+            answer: 'final',
+            guardFlag: 'BI',
+            isGuardrailed: true,
+            sessionId: 3,
+            scoredUrls: [{ url: 'https://kb/1', score: 0.9, title: 'Doc' }],
+            agentOptions: [{ agentId: 'playwright', passPhrase: 'Do it for me', caption: 'Auto' }],
+            workflowPlan: {
+                displayName: 'Refund',
+                estimatedRuntimeSec: 5,
+                steps: [{ number: 1, description: 'Look up order' }],
+            },
+        };
+        const message = convertAgentFinishToBotMessage(payload);
+
+        /*
+         * Regression: persisting chat state calls BotMessage.toJSON(), which iterates these and
+         * calls item.toJSON() on each — it threw "item.toJSON is not a function" for plain objects.
+         */
+        expect(() => JSON.stringify(message)).not.toThrow();
+        expect(message.scoredUrls?.[0]).toBeInstanceOf(Models.ScoredUrl);
+        expect(message.agentOptions?.[0]).toBeInstanceOf(Models.AgentOption);
+        expect(message.workflowPlan).toBeInstanceOf(Models.WorkflowPlan);
+        expect(message.workflowPlan?.steps[0]).toBeInstanceOf(Models.WorkflowStep);
+    });
+
+    test('handles a minimal payload with no nested data', () => {
+        const message = convertAgentFinishToBotMessage({
+            answer: 'x',
+            guardFlag: 'N',
+            isGuardrailed: false,
+        });
+        expect(message.scoredUrls).toBeUndefined();
+        expect(message.agentOptions).toBeUndefined();
+        expect(message.workflowPlan).toBeUndefined();
+        expect(() => JSON.stringify(message)).not.toThrow();
+    });
+});

package/src/streaming/agent-stream.ts

@@ -0,0 +1,103 @@
+import { Models } from '../api-client';
+
+/** Final run status reported by the backend on `run.finished`. */
+export type AgentRunStatus =
+    | 'Success'
+    | 'Guardrailed'
+    | 'PendingApproval'
+    | 'Bifurcation'
+    | 'Error'
+    | 'Timeout';
+
+export interface AgentPlanStep {
+    id: string;
+    title: string;
+    description?: string;
+}
+
+export interface AgentInputOption {
+    label: string;
+    value: string;
+    style?: string;
+}
+
+export interface AgentInputRequest {
+    kind: string;
+    prompt?: string;
+    options?: AgentInputOption[];
+}
+
+/**
+ * Decoded payload of the terminal `run.finished` event. The backend sends a full `BotMessage`
+ * (same field names: `answer`, `guardFlag`, `isGuardrailed`, `scoredUrls`, `agentOptions`,
+ * `workflowPlan`, `sessionId`, …) plus a little streaming-only metadata — so the mapping to the
+ * shared model is trivial (see {@link convertAgentFinishToBotMessage}).
+ */
+export interface AgentRunFinishedData extends Models.IBotMessage {
+    /** Final run status (streaming-only metadata, not part of the BotMessage model). */
+    status?: AgentRunStatus;
+    /** Total run duration in ms (streaming-only metadata). */
+    durationMs?: number;
+    /** Backend run identifier (streaming-only metadata). */
+    runId?: string;
+    /** Monotonic event sequence number (streaming-only metadata). */
+    seq?: number;
+}
+
+/**
+ * Callbacks + config the consumer supplies to a streamed message. Maps the chatbot's agent events
+ * onto progress updates and exposes the generic connection lifecycle for logging / keepalive / fallback.
+ */
+export interface AgentStreamHandlers {
+    /** Inactivity threshold before `onInactivity` fires (defaults applied by the caller). */
+    inactivityTimeoutMs?: number;
+    onStatus?(text: string): void;
+    onText?(text: string): void;
+    onPlan?(steps: AgentPlanStep[]): void;
+    /**
+     * Marks the plan step with the given id as the active one (earlier steps become done, later
+     * ones stay pending). Driven by an explicit `activeStepId` on `plan.proposed` or a `stepId` on
+     * `status.changed` when the backend supplies it; absent that, the first step is activated on
+     * `plan.proposed`. Mid-plan advancement therefore requires backend step correlation.
+     */
+    onStepActive?(id: string): void;
+    onInputRequested?(request: AgentInputRequest): void;
+    onInactivity?(): void;
+    onConnected?(): void;
+    onDisconnected?(): void;
+    onTimeout?(): void;
+    onCompleted?(): void;
+}
+
+/** Raised when the backend emits a `run.error` event. */
+export class AgentStreamError extends Error {
+    constructor(message?: string) {
+        super(message ?? 'Something went wrong during this step. Please try again.');
+        this.name = 'AgentStreamError';
+    }
+}
+
+/** Path of the v2 streaming endpoint, appended to the configured base URL. */
+export const AGENT_STREAM_PATH = '/api/v2/message/stream';
+
+/** SSE event names emitted by the backend agent pipeline. */
+export const AGENT_EVENT = {
+    RunStarted: 'run.started',
+    RunFinished: 'run.finished',
+    RunError: 'run.error',
+    StatusChanged: 'status.changed',
+    TextAppended: 'text.appended',
+    PlanProposed: 'plan.proposed',
+    InputRequested: 'input.requested',
+} as const;
+
+/**
+ * Map a terminal `run.finished` payload to the shared `BotMessage` model. The payload is already
+ * BotMessage-shaped, so `fromJS` does everything: it reads the backend's `guardFlag`/`isGuardrailed`
+ * verbatim, wraps nested data into real instances (`scoredUrls`, `agentOptions`, `workflowPlan` and
+ * its `steps`/`inputs`) so `toJSON()` can serialize it for session storage, and ignores the
+ * streaming-only metadata (`status`, `durationMs`, `runId`, `seq`).
+ */
+export function convertAgentFinishToBotMessage(data: AgentRunFinishedData): Models.BotMessage {
+    return Models.BotMessage.fromJS(data);
+}

package/src/streaming/index.ts

@@ -0,0 +1,2 @@
+export * from './agent-stream';
+export * from './run-agent-stream';

package/src/streaming/run-agent-stream.ts

@@ -0,0 +1,109 @@
+import { ChatSseClient } from '@servicetitan/titan-chat-ui-common';
+import { Models } from '../api-client';
+import {
+    AGENT_EVENT,
+    AgentPlanStep,
+    AgentRunFinishedData,
+    AgentStreamError,
+    AgentStreamHandlers,
+    convertAgentFinishToBotMessage,
+} from './agent-stream';
+
+export interface RunAgentStreamOptions {
+    /** Fully-constructed streaming endpoint URL. */
+    url: string;
+    /** Request headers (auth, X-Client-ID, …). */
+    headers?: Record<string, string>;
+    /** Request body, serialized as JSON by the SSE client. */
+    body: unknown;
+    /** Custom `fetch` (same as the regular API client) so auth/headers/credentials apply identically. */
+    fetch?: typeof fetch;
+    /** Progress + lifecycle callbacks (and the inactivity timeout). */
+    handlers: AgentStreamHandlers;
+    abortSignal?: AbortSignal;
+}
+
+/**
+ * Shared SSE consumption used by every {@link IChatbotApiClient} adapter: opens a {@link ChatSseClient},
+ * maps the agent events onto the supplied handlers, and resolves the final {@link Models.BotMessage}
+ * from `run.finished` (or rejects on `run.error` / a fatal connection error). The only per-adapter
+ * differences — the URL, headers and body — are passed in by the caller.
+ */
+export function runAgentStream({
+    abortSignal,
+    body,
+    fetch,
+    handlers,
+    headers,
+    url,
+}: RunAgentStreamOptions): Promise<Models.BotMessage> {
+    return new Promise<Models.BotMessage>((resolve, reject) => {
+        let finished: AgentRunFinishedData | undefined;
+
+        const client = new ChatSseClient({
+            url,
+            headers,
+            fetch,
+            signal: abortSignal,
+            body,
+            inactivityTimeoutMs: handlers.inactivityTimeoutMs,
+            isTerminalEvent: e =>
+                e.event === AGENT_EVENT.RunFinished || e.event === AGENT_EVENT.RunError,
+            handlers: {
+                [AGENT_EVENT.StatusChanged]: (d: { text: string; stepId?: string }) => {
+                    handlers.onStatus?.(d.text);
+                    if (d.stepId !== undefined) {
+                        handlers.onStepActive?.(d.stepId);
+                    }
+                },
+                [AGENT_EVENT.TextAppended]: (d: { text: string }) => handlers.onText?.(d.text),
+                [AGENT_EVENT.PlanProposed]: (d: {
+                    steps: AgentPlanStep[];
+                    activeStepId?: string;
+                }) => {
+                    handlers.onPlan?.(d.steps);
+                    // Activate the explicitly-signalled step, else default to the first.
+                    const activeId = d.activeStepId ?? d.steps?.[0]?.id;
+                    if (activeId !== undefined) {
+                        handlers.onStepActive?.(activeId);
+                    }
+                },
+                [AGENT_EVENT.InputRequested]: (d: any) =>
+                    handlers.onInputRequested?.({
+                        kind: d.kind,
+                        prompt: d.prompt,
+                        options: d.options,
+                    }),
+                [AGENT_EVENT.RunFinished]: (d: AgentRunFinishedData) => {
+                    finished = d;
+                },
+                [AGENT_EVENT.RunError]: (d: { message?: string }) => {
+                    reject(new AgentStreamError(d.message));
+                },
+            },
+            onConnected: handlers.onConnected,
+            onDisconnected: handlers.onDisconnected,
+            onTimeout: handlers.onTimeout,
+            onInactivity: handlers.onInactivity,
+            onCompleted: handlers.onCompleted,
+            onError: reject,
+        });
+
+        client.start().then(() => {
+            if (finished) {
+                try {
+                    resolve(convertAgentFinishToBotMessage(finished));
+                } catch (err) {
+                    reject(err);
+                }
+                return;
+            }
+            /*
+             * Stream completed without `run.finished`. A run.error / fatal onError may have
+             * already rejected (subsequent reject calls are no-ops); otherwise the server closed
+             * the connection unexpectedly — reject so the returned Promise never hangs.
+             */
+            reject(new AgentStreamError('Stream ended without a run.finished event'));
+        }, reject);
+    });
+}