@servicetitan/titan-chatbot-api 8.0.0 → 9.0.0

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