@servicetitan/titan-chatbot-api 8.0.0 → 9.0.0

package/dist/streaming/agent-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-stream.d.ts","sourceRoot":"","sources":["../../src/streaming/agent-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC,kEAAkE;AAClE,MAAM,MAAM,cAAc,GACpB,SAAS,GACT,aAAa,GACb,iBAAiB,GACjB,aAAa,GACb,OAAO,GACP,SAAS,CAAC;AAEhB,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,MAAM,CAAC,WAAW;IAC5D,oFAAoF;IACpF,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC,yFAAyF;IACzF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IACtC;;;;;OAKG;IACH,YAAY,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpD,YAAY,CAAC,IAAI,IAAI,CAAC;IACtB,WAAW,CAAC,IAAI,IAAI,CAAC;IACrB,cAAc,CAAC,IAAI,IAAI,CAAC;IACxB,SAAS,CAAC,IAAI,IAAI,CAAC;IACnB,WAAW,CAAC,IAAI,IAAI,CAAC;CACxB;AAED,yDAAyD;AACzD,qBAAa,gBAAiB,SAAQ,KAAK;gBAC3B,OAAO,CAAC,EAAE,MAAM;CAI/B;AAED,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D,6DAA6D;AAC7D,eAAO,MAAM,WAAW;;;;;;;;CAQd,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAAC,UAAU,CAE5F"}

package/dist/streaming/agent-stream.js

@@ -0,0 +1,28 @@
+import { Models } from '../api-client';
+/** Raised when the backend emits a `run.error` event. */ export class AgentStreamError extends Error {
+    constructor(message){
+        super(message !== null && message !== void 0 ? 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'
+};
+/**
+ * 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) {
+    return Models.BotMessage.fromJS(data);
+}
+
+//# sourceMappingURL=agent-stream.js.map

package/dist/streaming/agent-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/streaming/agent-stream.ts"],"sourcesContent":["import { Models } from '../api-client';\n\n/** Final run status reported by the backend on `run.finished`. */\nexport type AgentRunStatus =\n    | 'Success'\n    | 'Guardrailed'\n    | 'PendingApproval'\n    | 'Bifurcation'\n    | 'Error'\n    | 'Timeout';\n\nexport interface AgentPlanStep {\n    id: string;\n    title: string;\n    description?: string;\n}\n\nexport interface AgentInputOption {\n    label: string;\n    value: string;\n    style?: string;\n}\n\nexport interface AgentInputRequest {\n    kind: string;\n    prompt?: string;\n    options?: AgentInputOption[];\n}\n\n/**\n * Decoded payload of the terminal `run.finished` event. The backend sends a full `BotMessage`\n * (same field names: `answer`, `guardFlag`, `isGuardrailed`, `scoredUrls`, `agentOptions`,\n * `workflowPlan`, `sessionId`, …) plus a little streaming-only metadata — so the mapping to the\n * shared model is trivial (see {@link convertAgentFinishToBotMessage}).\n */\nexport interface AgentRunFinishedData extends Models.IBotMessage {\n    /** Final run status (streaming-only metadata, not part of the BotMessage model). */\n    status?: AgentRunStatus;\n    /** Total run duration in ms (streaming-only metadata). */\n    durationMs?: number;\n    /** Backend run identifier (streaming-only metadata). */\n    runId?: string;\n    /** Monotonic event sequence number (streaming-only metadata). */\n    seq?: number;\n}\n\n/**\n * Callbacks + config the consumer supplies to a streamed message. Maps the chatbot's agent events\n * onto progress updates and exposes the generic connection lifecycle for logging / keepalive / fallback.\n */\nexport interface AgentStreamHandlers {\n    /** Inactivity threshold before `onInactivity` fires (defaults applied by the caller). */\n    inactivityTimeoutMs?: number;\n    onStatus?(text: string): void;\n    onText?(text: string): void;\n    onPlan?(steps: AgentPlanStep[]): void;\n    /**\n     * Marks the plan step with the given id as the active one (earlier steps become done, later\n     * ones stay pending). Driven by an explicit `activeStepId` on `plan.proposed` or a `stepId` on\n     * `status.changed` when the backend supplies it; absent that, the first step is activated on\n     * `plan.proposed`. Mid-plan advancement therefore requires backend step correlation.\n     */\n    onStepActive?(id: string): void;\n    onInputRequested?(request: AgentInputRequest): void;\n    onInactivity?(): void;\n    onConnected?(): void;\n    onDisconnected?(): void;\n    onTimeout?(): void;\n    onCompleted?(): void;\n}\n\n/** Raised when the backend emits a `run.error` event. */\nexport class AgentStreamError extends Error {\n    constructor(message?: string) {\n        super(message ?? 'Something went wrong during this step. Please try again.');\n        this.name = 'AgentStreamError';\n    }\n}\n\n/** Path of the v2 streaming endpoint, appended to the configured base URL. */\nexport const AGENT_STREAM_PATH = '/api/v2/message/stream';\n\n/** SSE event names emitted by the backend agent pipeline. */\nexport const AGENT_EVENT = {\n    RunStarted: 'run.started',\n    RunFinished: 'run.finished',\n    RunError: 'run.error',\n    StatusChanged: 'status.changed',\n    TextAppended: 'text.appended',\n    PlanProposed: 'plan.proposed',\n    InputRequested: 'input.requested',\n} as const;\n\n/**\n * Map a terminal `run.finished` payload to the shared `BotMessage` model. The payload is already\n * BotMessage-shaped, so `fromJS` does everything: it reads the backend's `guardFlag`/`isGuardrailed`\n * verbatim, wraps nested data into real instances (`scoredUrls`, `agentOptions`, `workflowPlan` and\n * its `steps`/`inputs`) so `toJSON()` can serialize it for session storage, and ignores the\n * streaming-only metadata (`status`, `durationMs`, `runId`, `seq`).\n */\nexport function convertAgentFinishToBotMessage(data: AgentRunFinishedData): Models.BotMessage {\n    return Models.BotMessage.fromJS(data);\n}\n"],"names":["Models","AgentStreamError","Error","message","name","AGENT_STREAM_PATH","AGENT_EVENT","RunStarted","RunFinished","RunError","StatusChanged","TextAppended","PlanProposed","InputRequested","convertAgentFinishToBotMessage","data","BotMessage","fromJS"],"mappings":"AAAA,SAASA,MAAM,QAAQ,gBAAgB;AAuEvC,uDAAuD,GACvD,OAAO,MAAMC,yBAAyBC;IAClC,YAAYC,OAAgB,CAAE;QAC1B,KAAK,CAACA,oBAAAA,qBAAAA,UAAW;QACjB,IAAI,CAACC,IAAI,GAAG;IAChB;AACJ;AAEA,4EAA4E,GAC5E,OAAO,MAAMC,oBAAoB,yBAAyB;AAE1D,2DAA2D,GAC3D,OAAO,MAAMC,cAAc;IACvBC,YAAY;IACZC,aAAa;IACbC,UAAU;IACVC,eAAe;IACfC,cAAc;IACdC,cAAc;IACdC,gBAAgB;AACpB,EAAW;AAEX;;;;;;CAMC,GACD,OAAO,SAASC,+BAA+BC,IAA0B;IACrE,OAAOf,OAAOgB,UAAU,CAACC,MAAM,CAACF;AACpC"}

package/dist/streaming/index.d.ts

@@ -0,0 +1,3 @@
+export * from './agent-stream';
+export * from './run-agent-stream';
+//# sourceMappingURL=index.d.ts.map

package/dist/streaming/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/streaming/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}

package/dist/streaming/index.js

@@ -0,0 +1,4 @@
+export * from './agent-stream';
+export * from './run-agent-stream';
+
+//# sourceMappingURL=index.js.map

package/dist/streaming/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/streaming/index.ts"],"sourcesContent":["export * from './agent-stream';\nexport * from './run-agent-stream';\n"],"names":[],"mappings":"AAAA,cAAc,iBAAiB;AAC/B,cAAc,qBAAqB"}

package/dist/streaming/run-agent-stream.d.ts

@@ -0,0 +1,23 @@
+import { Models } from '../api-client';
+import { AgentStreamHandlers } 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 declare function runAgentStream({ abortSignal, body, fetch, handlers, headers, url, }: RunAgentStreamOptions): Promise<Models.BotMessage>;
+//# sourceMappingURL=run-agent-stream.d.ts.map

package/dist/streaming/run-agent-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-agent-stream.d.ts","sourceRoot":"","sources":["../../src/streaming/run-agent-stream.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAKH,mBAAmB,EAEtB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,qBAAqB;IAClC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,0DAA0D;IAC1D,IAAI,EAAE,OAAO,CAAC;IACd,qGAAqG;IACrG,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,mEAAmE;IACnE,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAC3B,WAAW,EACX,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,OAAO,EACP,GAAG,GACN,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAsEpD"}

package/dist/streaming/run-agent-stream.js

@@ -0,0 +1,83 @@
+import { ChatSseClient } from '@servicetitan/titan-chat-ui-common';
+import { AGENT_EVENT, AgentStreamError, convertAgentFinishToBotMessage } from './agent-stream';
+/**
+ * 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 }) {
+    return new Promise((resolve, reject)=>{
+        let finished;
+        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)=>{
+                    var _handlers_onStatus;
+                    (_handlers_onStatus = handlers.onStatus) === null || _handlers_onStatus === void 0 ? void 0 : _handlers_onStatus.call(handlers, d.text);
+                    if (d.stepId !== undefined) {
+                        var _handlers_onStepActive;
+                        (_handlers_onStepActive = handlers.onStepActive) === null || _handlers_onStepActive === void 0 ? void 0 : _handlers_onStepActive.call(handlers, d.stepId);
+                    }
+                },
+                [AGENT_EVENT.TextAppended]: (d)=>{
+                    var _handlers_onText;
+                    return (_handlers_onText = handlers.onText) === null || _handlers_onText === void 0 ? void 0 : _handlers_onText.call(handlers, d.text);
+                },
+                [AGENT_EVENT.PlanProposed]: (d)=>{
+                    var _d_activeStepId;
+                    var _handlers_onPlan, _d_steps_, _d_steps;
+                    (_handlers_onPlan = handlers.onPlan) === null || _handlers_onPlan === void 0 ? void 0 : _handlers_onPlan.call(handlers, d.steps);
+                    // Activate the explicitly-signalled step, else default to the first.
+                    const activeId = (_d_activeStepId = d.activeStepId) !== null && _d_activeStepId !== void 0 ? _d_activeStepId : (_d_steps = d.steps) === null || _d_steps === void 0 ? void 0 : (_d_steps_ = _d_steps[0]) === null || _d_steps_ === void 0 ? void 0 : _d_steps_.id;
+                    if (activeId !== undefined) {
+                        var _handlers_onStepActive;
+                        (_handlers_onStepActive = handlers.onStepActive) === null || _handlers_onStepActive === void 0 ? void 0 : _handlers_onStepActive.call(handlers, activeId);
+                    }
+                },
+                [AGENT_EVENT.InputRequested]: (d)=>{
+                    var _handlers_onInputRequested;
+                    return (_handlers_onInputRequested = handlers.onInputRequested) === null || _handlers_onInputRequested === void 0 ? void 0 : _handlers_onInputRequested.call(handlers, {
+                        kind: d.kind,
+                        prompt: d.prompt,
+                        options: d.options
+                    });
+                },
+                [AGENT_EVENT.RunFinished]: (d)=>{
+                    finished = d;
+                },
+                [AGENT_EVENT.RunError]: (d)=>{
+                    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);
+    });
+}
+
+//# sourceMappingURL=run-agent-stream.js.map

package/dist/streaming/run-agent-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/streaming/run-agent-stream.ts"],"sourcesContent":["import { ChatSseClient } from '@servicetitan/titan-chat-ui-common';\nimport { Models } from '../api-client';\nimport {\n    AGENT_EVENT,\n    AgentPlanStep,\n    AgentRunFinishedData,\n    AgentStreamError,\n    AgentStreamHandlers,\n    convertAgentFinishToBotMessage,\n} from './agent-stream';\n\nexport interface RunAgentStreamOptions {\n    /** Fully-constructed streaming endpoint URL. */\n    url: string;\n    /** Request headers (auth, X-Client-ID, …). */\n    headers?: Record<string, string>;\n    /** Request body, serialized as JSON by the SSE client. */\n    body: unknown;\n    /** Custom `fetch` (same as the regular API client) so auth/headers/credentials apply identically. */\n    fetch?: typeof fetch;\n    /** Progress + lifecycle callbacks (and the inactivity timeout). */\n    handlers: AgentStreamHandlers;\n    abortSignal?: AbortSignal;\n}\n\n/**\n * Shared SSE consumption used by every {@link IChatbotApiClient} adapter: opens a {@link ChatSseClient},\n * maps the agent events onto the supplied handlers, and resolves the final {@link Models.BotMessage}\n * from `run.finished` (or rejects on `run.error` / a fatal connection error). The only per-adapter\n * differences — the URL, headers and body — are passed in by the caller.\n */\nexport function runAgentStream({\n    abortSignal,\n    body,\n    fetch,\n    handlers,\n    headers,\n    url,\n}: RunAgentStreamOptions): Promise<Models.BotMessage> {\n    return new Promise<Models.BotMessage>((resolve, reject) => {\n        let finished: AgentRunFinishedData | undefined;\n\n        const client = new ChatSseClient({\n            url,\n            headers,\n            fetch,\n            signal: abortSignal,\n            body,\n            inactivityTimeoutMs: handlers.inactivityTimeoutMs,\n            isTerminalEvent: e =>\n                e.event === AGENT_EVENT.RunFinished || e.event === AGENT_EVENT.RunError,\n            handlers: {\n                [AGENT_EVENT.StatusChanged]: (d: { text: string; stepId?: string }) => {\n                    handlers.onStatus?.(d.text);\n                    if (d.stepId !== undefined) {\n                        handlers.onStepActive?.(d.stepId);\n                    }\n                },\n                [AGENT_EVENT.TextAppended]: (d: { text: string }) => handlers.onText?.(d.text),\n                [AGENT_EVENT.PlanProposed]: (d: {\n                    steps: AgentPlanStep[];\n                    activeStepId?: string;\n                }) => {\n                    handlers.onPlan?.(d.steps);\n                    // Activate the explicitly-signalled step, else default to the first.\n                    const activeId = d.activeStepId ?? d.steps?.[0]?.id;\n                    if (activeId !== undefined) {\n                        handlers.onStepActive?.(activeId);\n                    }\n                },\n                [AGENT_EVENT.InputRequested]: (d: any) =>\n                    handlers.onInputRequested?.({\n                        kind: d.kind,\n                        prompt: d.prompt,\n                        options: d.options,\n                    }),\n                [AGENT_EVENT.RunFinished]: (d: AgentRunFinishedData) => {\n                    finished = d;\n                },\n                [AGENT_EVENT.RunError]: (d: { message?: string }) => {\n                    reject(new AgentStreamError(d.message));\n                },\n            },\n            onConnected: handlers.onConnected,\n            onDisconnected: handlers.onDisconnected,\n            onTimeout: handlers.onTimeout,\n            onInactivity: handlers.onInactivity,\n            onCompleted: handlers.onCompleted,\n            onError: reject,\n        });\n\n        client.start().then(() => {\n            if (finished) {\n                try {\n                    resolve(convertAgentFinishToBotMessage(finished));\n                } catch (err) {\n                    reject(err);\n                }\n                return;\n            }\n            /*\n             * Stream completed without `run.finished`. A run.error / fatal onError may have\n             * already rejected (subsequent reject calls are no-ops); otherwise the server closed\n             * the connection unexpectedly — reject so the returned Promise never hangs.\n             */\n            reject(new AgentStreamError('Stream ended without a run.finished event'));\n        }, reject);\n    });\n}\n"],"names":["ChatSseClient","AGENT_EVENT","AgentStreamError","convertAgentFinishToBotMessage","runAgentStream","abortSignal","body","fetch","handlers","headers","url","Promise","resolve","reject","finished","client","signal","inactivityTimeoutMs","isTerminalEvent","e","event","RunFinished","RunError","StatusChanged","d","onStatus","text","stepId","undefined","onStepActive","TextAppended","onText","PlanProposed","onPlan","steps","activeId","activeStepId","id","InputRequested","onInputRequested","kind","prompt","options","message","onConnected","onDisconnected","onTimeout","onInactivity","onCompleted","onError","start","then","err"],"mappings":"AAAA,SAASA,aAAa,QAAQ,qCAAqC;AAEnE,SACIC,WAAW,EAGXC,gBAAgB,EAEhBC,8BAA8B,QAC3B,iBAAiB;AAgBxB;;;;;CAKC,GACD,OAAO,SAASC,eAAe,EAC3BC,WAAW,EACXC,IAAI,EACJC,KAAK,EACLC,QAAQ,EACRC,OAAO,EACPC,GAAG,EACiB;IACpB,OAAO,IAAIC,QAA2B,CAACC,SAASC;QAC5C,IAAIC;QAEJ,MAAMC,SAAS,IAAIf,cAAc;YAC7BU;YACAD;YACAF;YACAS,QAAQX;YACRC;YACAW,qBAAqBT,SAASS,mBAAmB;YACjDC,iBAAiBC,CAAAA,IACbA,EAAEC,KAAK,KAAKnB,YAAYoB,WAAW,IAAIF,EAAEC,KAAK,KAAKnB,YAAYqB,QAAQ;YAC3Ed,UAAU;gBACN,CAACP,YAAYsB,aAAa,CAAC,EAAE,CAACC;wBAC1BhB;qBAAAA,qBAAAA,SAASiB,QAAQ,cAAjBjB,yCAAAA,wBAAAA,UAAoBgB,EAAEE,IAAI;oBAC1B,IAAIF,EAAEG,MAAM,KAAKC,WAAW;4BACxBpB;yBAAAA,yBAAAA,SAASqB,YAAY,cAArBrB,6CAAAA,4BAAAA,UAAwBgB,EAAEG,MAAM;oBACpC;gBACJ;gBACA,CAAC1B,YAAY6B,YAAY,CAAC,EAAE,CAACN;wBAAwBhB;4BAAAA,mBAAAA,SAASuB,MAAM,cAAfvB,uCAAAA,sBAAAA,UAAkBgB,EAAEE,IAAI;;gBAC7E,CAACzB,YAAY+B,YAAY,CAAC,EAAE,CAACR;wBAMRA;wBAFjBhB,kBAEmCgB,WAAAA;qBAFnChB,mBAAAA,SAASyB,MAAM,cAAfzB,uCAAAA,sBAAAA,UAAkBgB,EAAEU,KAAK;oBACzB,qEAAqE;oBACrE,MAAMC,YAAWX,kBAAAA,EAAEY,YAAY,cAAdZ,6BAAAA,mBAAkBA,WAAAA,EAAEU,KAAK,cAAPV,gCAAAA,YAAAA,QAAS,CAAC,EAAE,cAAZA,gCAAAA,UAAca,EAAE;oBACnD,IAAIF,aAAaP,WAAW;4BACxBpB;yBAAAA,yBAAAA,SAASqB,YAAY,cAArBrB,6CAAAA,4BAAAA,UAAwB2B;oBAC5B;gBACJ;gBACA,CAAClC,YAAYqC,cAAc,CAAC,EAAE,CAACd;wBAC3BhB;4BAAAA,6BAAAA,SAAS+B,gBAAgB,cAAzB/B,iDAAAA,gCAAAA,UAA4B;wBACxBgC,MAAMhB,EAAEgB,IAAI;wBACZC,QAAQjB,EAAEiB,MAAM;wBAChBC,SAASlB,EAAEkB,OAAO;oBACtB;;gBACJ,CAACzC,YAAYoB,WAAW,CAAC,EAAE,CAACG;oBACxBV,WAAWU;gBACf;gBACA,CAACvB,YAAYqB,QAAQ,CAAC,EAAE,CAACE;oBACrBX,OAAO,IAAIX,iBAAiBsB,EAAEmB,OAAO;gBACzC;YACJ;YACAC,aAAapC,SAASoC,WAAW;YACjCC,gBAAgBrC,SAASqC,cAAc;YACvCC,WAAWtC,SAASsC,SAAS;YAC7BC,cAAcvC,SAASuC,YAAY;YACnCC,aAAaxC,SAASwC,WAAW;YACjCC,SAASpC;QACb;QAEAE,OAAOmC,KAAK,GAAGC,IAAI,CAAC;YAChB,IAAIrC,UAAU;gBACV,IAAI;oBACAF,QAAQT,+BAA+BW;gBAC3C,EAAE,OAAOsC,KAAK;oBACVvC,OAAOuC;gBACX;gBACA;YACJ;YACA;;;;aAIC,GACDvC,OAAO,IAAIX,iBAAiB;QAChC,GAAGW;IACP;AACJ"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/titan-chatbot-api",
-    "version": "8.0.0",
+    "version": "9.0.0",
     "description": "Chatbot client API package",
     "repository": {
         "type": "git",
@@ -17,10 +17,13 @@
         "push:local": "yalc push"
     },
     "dependencies": {
-        "@servicetitan/titan-chat-ui-common": "^8.0.0",
+        "@servicetitan/titan-chat-ui-common": "^9.0.0",
         "lodash": "^4.18.1",
         "nanoid": "^5.1.5"
     },
+    "devDependencies": {
+        "@microsoft/fetch-event-source": "^2.0.1"
+    },
     "peerDependencies": {
         "@servicetitan/log-service": ">=27",
         "@servicetitan/react-ioc": ">=24",
@@ -42,5 +45,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "3af2e2dd99b7d735dbb763075de074986f866ce3"
+    "gitHead": "028073fe571014741da70bcff173d617e2738125"
 }

package/src/api-client/__mocks__/chatbot-api-client.mock.ts

@@ -9,4 +9,5 @@ export class ChatbotApiClientMock implements IChatbotApiClient {
     patchSession = jest.fn();
     deleteSession = jest.fn();
     getTranscripts = jest.fn();
+    streamMessage = jest.fn();
 }

package/src/api-client/base/chatbot-api-client.ts

@@ -1,5 +1,6 @@
 import { symbolToken } from '@servicetitan/react-ioc';
 import { Models } from '..';
+import { AgentStreamHandlers } from '../../streaming';
 
 /**
  * Token for injecting the chatbot client settings for proper initialization of the client.
@@ -25,6 +26,16 @@ export interface IChatbotClientSettings {}
 export interface IChatbotApiClient {
     postFeedback(body: Models.IFeedback, abortSignal?: AbortSignal): Promise<Models.Feedback>;
     postMessage(body: Models.IUserMessage, abortSignal?: AbortSignal): Promise<Models.BotMessage>;
+    /**
+     * Streaming variant of {@link postMessage}: consumes the SSE agent-progress stream, forwarding
+     * progress events to `handlers`, and resolves with the final {@link Models.BotMessage}.
+     * Optional — clients that do not support streaming omit it, and consumers fall back to {@link postMessage}.
+     */
+    streamMessage?(
+        body: Models.IUserMessage,
+        handlers: AgentStreamHandlers,
+        abortSignal?: AbortSignal
+    ): Promise<Models.BotMessage>;
     postFollowUpEmail(
         body: Models.IUserMessage,
         abortSignal?: AbortSignal

package/src/api-client/index.ts

@@ -1,5 +1,4 @@
 export * as ApiClientTitanChat from './titan-chat';
-export * as ApiClientHelpCenter from './help-center';
 export * as Models from './models';
 export * as ModelsMocks from './models/__mocks__/models.mock';
 export * as ClientMocks from './__mocks__/chatbot-api-client.mock';

package/src/api-client/titan-chat/__tests__/chatbot-api-client-stream.test.ts

@@ -0,0 +1,208 @@
+import { beforeEach, describe, expect, jest, test } from '@jest/globals';
+import { type EventSourceMessage, fetchEventSource } from '@microsoft/fetch-event-source';
+import { Models } from '../..';
+import type { AgentStreamHandlers } from '../../../streaming';
+import { ChatbotApiClient, IChatbotClientSettingsTitanChat } from '../chatbot-api-client';
+
+jest.mock('@microsoft/fetch-event-source');
+
+const fetchEventSourceMock = fetchEventSource as jest.MockedFunction<typeof fetchEventSource>;
+
+const okResponse = () =>
+    ({ ok: true, status: 200, headers: { get: () => 'text/event-stream' } }) as unknown as Response;
+const evt = (event: string, data: unknown): EventSourceMessage => ({
+    id: '',
+    event,
+    data: JSON.stringify(data),
+});
+
+/** Mock that opens, exposes init, and stays pending until the client aborts. */
+function captureOpen() {
+    const capture: { init?: any; opened: Promise<void> } = { opened: undefined as any };
+    capture.opened = new Promise<void>(markOpened => {
+        fetchEventSourceMock.mockImplementation((_url, init) => {
+            capture.init = init;
+            markOpened();
+            return Promise.resolve(init.onopen?.(okResponse())).then(
+                () =>
+                    new Promise<void>(resolve => {
+                        const s: AbortSignal | null | undefined = init.signal;
+                        if (s?.aborted) {
+                            resolve();
+                        } else {
+                            s?.addEventListener('abort', () => resolve(), { once: true });
+                        }
+                    })
+            );
+        });
+    });
+    return capture;
+}
+
+/** The same custom fetch the regular API client would use (injects auth, etc.). */
+const customFetch = ((_url: any, _init?: any) => Promise.resolve(new Response())) as typeof fetch;
+
+const settings: IChatbotClientSettingsTitanChat = {
+    version: '2',
+    clientId: 'help-center',
+    constructorParametersFactory: () => ({
+        baseUrl: 'https://api.test/base',
+        httpClient: { fetch: customFetch },
+    }),
+    streamHeadersFactory: () => ({ Authorization: 'Bearer t' }),
+};
+
+describe('ChatbotApiClient (titan-chat).streamMessage', () => {
+    beforeEach(() => {
+        fetchEventSourceMock.mockReset();
+    });
+
+    test('opens the versioned stream endpoint with X-Client-ID + extra headers and the message body', async () => {
+        const capture = captureOpen();
+        const client = new ChatbotApiClient(settings);
+
+        const promise = client.streamMessage(
+            new Models.UserMessage({
+                sessionId: 9,
+                question: 'hi',
+                experience: Models.Experience.MultiTurn,
+            }),
+            {}
+        );
+        await capture.opened;
+
+        expect(String((fetchEventSourceMock.mock.calls[0] as any[])[0])).toBe(
+            'https://api.test/base/api/v2/message/stream'
+        );
+        expect(capture.init.method).toBe('POST');
+        expect(capture.init.headers).toMatchObject({
+            'X-Client-ID': 'help-center',
+            'Authorization': 'Bearer t',
+            'Accept': 'text/event-stream',
+        });
+        const sent = JSON.parse(capture.init.body);
+        expect(sent.question).toBe('hi');
+        expect(sent.sessionId).toBe(9);
+
+        capture.init.onmessage(evt('run.finished', { seq: 1, status: 'Success', answer: 'done' }));
+        await promise;
+    });
+
+    test('forwards the configured httpClient.fetch so SSE uses the same request config as the API', async () => {
+        const capture = captureOpen();
+        const client = new ChatbotApiClient(settings);
+
+        const promise = client.streamMessage(
+            new Models.UserMessage({ question: 'q', experience: Models.Experience.MultiTurn }),
+            {}
+        );
+        await capture.opened;
+
+        // fetchEventSource receives the same fetch the regular client uses → auth/headers apply identically.
+        expect(capture.init.fetch).toBe(customFetch);
+
+        capture.init.onmessage(evt('run.finished', { seq: 1, status: 'Success', answer: 'done' }));
+        await promise;
+    });
+
+    test('maps agent events and resolves a BotMessage from run.finished', async () => {
+        const capture = captureOpen();
+        const handlers: AgentStreamHandlers = { onStatus: jest.fn(), onText: jest.fn() };
+        const client = new ChatbotApiClient(settings);
+
+        const promise = client.streamMessage(
+            new Models.UserMessage({ question: 'q', experience: Models.Experience.MultiTurn }),
+            handlers
+        );
+        await capture.opened;
+
+        capture.init.onmessage(evt('status.changed', { seq: 1, text: 'Thinking…' }));
+        capture.init.onmessage(evt('text.appended', { seq: 2, text: '✓ done step' }));
+        capture.init.onmessage(
+            evt('run.finished', { seq: 3, status: 'Success', answer: 'final', sessionId: 5 })
+        );
+
+        const bot = await promise;
+        expect(handlers.onStatus).toHaveBeenCalledWith('Thinking…');
+        expect(handlers.onText).toHaveBeenCalledWith('✓ done step');
+        expect(bot).toBeInstanceOf(Models.BotMessage);
+        expect(bot.answer).toBe('final');
+        expect(bot.sessionId).toBe(5);
+    });
+
+    test('plan.proposed forwards steps and activates the first step by default', async () => {
+        const capture = captureOpen();
+        const handlers: AgentStreamHandlers = { onPlan: jest.fn(), onStepActive: jest.fn() };
+        const client = new ChatbotApiClient(settings);
+
+        const promise = client.streamMessage(
+            new Models.UserMessage({ question: 'q', experience: Models.Experience.MultiTurn }),
+            handlers
+        );
+        await capture.opened;
+
+        capture.init.onmessage(
+            evt('plan.proposed', {
+                seq: 1,
+                steps: [
+                    { id: 'a', title: 'Look up' },
+                    { id: 'b', title: 'Answer' },
+                ],
+            })
+        );
+        capture.init.onmessage(evt('run.finished', { seq: 2, status: 'Success', answer: 'x' }));
+
+        await promise;
+        expect(handlers.onPlan).toHaveBeenCalledWith([
+            { id: 'a', title: 'Look up' },
+            { id: 'b', title: 'Answer' },
+        ]);
+        expect(handlers.onStepActive).toHaveBeenCalledWith('a');
+    });
+
+    test('plan.proposed honors an explicit activeStepId', async () => {
+        const capture = captureOpen();
+        const handlers: AgentStreamHandlers = { onStepActive: jest.fn() };
+        const client = new ChatbotApiClient(settings);
+
+        const promise = client.streamMessage(
+            new Models.UserMessage({ question: 'q', experience: Models.Experience.MultiTurn }),
+            handlers
+        );
+        await capture.opened;
+
+        capture.init.onmessage(
+            evt('plan.proposed', {
+                seq: 1,
+                activeStepId: 'b',
+                steps: [
+                    { id: 'a', title: 'Look up' },
+                    { id: 'b', title: 'Answer' },
+                ],
+            })
+        );
+        capture.init.onmessage(evt('run.finished', { seq: 2, status: 'Success', answer: 'x' }));
+
+        await promise;
+        expect(handlers.onStepActive).toHaveBeenCalledWith('b');
+    });
+
+    test('status.changed advances the active step when it carries a stepId', async () => {
+        const capture = captureOpen();
+        const handlers: AgentStreamHandlers = { onStatus: jest.fn(), onStepActive: jest.fn() };
+        const client = new ChatbotApiClient(settings);
+
+        const promise = client.streamMessage(
+            new Models.UserMessage({ question: 'q', experience: Models.Experience.MultiTurn }),
+            handlers
+        );
+        await capture.opened;
+
+        capture.init.onmessage(evt('status.changed', { seq: 1, text: 'Searching…', stepId: 'b' }));
+        capture.init.onmessage(evt('run.finished', { seq: 2, status: 'Success', answer: 'x' }));
+
+        await promise;
+        expect(handlers.onStatus).toHaveBeenCalledWith('Searching…');
+        expect(handlers.onStepActive).toHaveBeenCalledWith('b');
+    });
+});

package/src/api-client/titan-chat/chatbot-api-client.ts

@@ -1,5 +1,6 @@
 import { inject, injectable } from '@servicetitan/react-ioc';
 import { Models } from '..';
+import { AgentStreamHandlers, runAgentStream } from '../../streaming';
 import {
     CHATBOT_CLIENT_SETTINGS,
     FirstParameterType,
@@ -10,6 +11,9 @@ import {
 // eslint-disable-next-line no-restricted-imports
 import { Client } from './native-client';
 
+/** Streaming endpoint template, mirroring the generated client's `/api/v{version}/message`. */
+const AGENT_STREAM_PATH_TEMPLATE = '/api/v{version}/message/stream';
+
 /**
  * Settings for the chatbot client, which includes a factory for constructor parameters, and additional settings
  * like version and clientId which are used in the API calls.
@@ -21,6 +25,11 @@ export interface IChatbotClientSettingsTitanChat extends IChatbotClientSettings
     };
     version: string;
     clientId: string;
+    /**
+     * Extra headers for the SSE streaming request. `X-Client-ID` is always sent (from `clientId`);
+     * use this for anything the fetch http client would otherwise add (e.g. Authorization). Optional.
+     */
+    streamHeadersFactory?: () => Record<string, string>;
 }
 
 /**
@@ -30,6 +39,10 @@ export interface IChatbotClientSettingsTitanChat extends IChatbotClientSettings
 @injectable()
 export class ChatbotApiClient implements IChatbotApiClient {
     private readonly client: Client;
+    /** Same base URL the generated `Client` uses, so streaming URLs are built identically. */
+    private readonly baseUrl: string;
+    /** Same `fetch` the generated `Client` uses, so the SSE request gets identical auth/headers. */
+    private readonly httpFetch?: typeof fetch;
 
     get version(): string {
         return this.chatbotApiClientSettings.version;
@@ -46,6 +59,13 @@ export class ChatbotApiClient implements IChatbotApiClient {
         const { baseUrl, httpClient } =
             this.chatbotApiClientSettings.constructorParametersFactory();
         this.client = new Client(baseUrl, httpClient);
+        // Mirror the generated client's `this.baseUrl = baseUrl ?? ""`.
+        this.baseUrl = baseUrl ?? '';
+        /*
+         * Reuse the same fetch the generated client uses, so the SSE request goes through the
+         * consumer's request configuration (auth token, X-HC-Instance, credentials, …).
+         */
+        this.httpFetch = httpClient?.fetch as typeof fetch | undefined;
     }
 
     postFeedback(body: Models.Feedback, abortSignal?: AbortSignal) {
@@ -56,6 +76,32 @@ export class ChatbotApiClient implements IChatbotApiClient {
         return this.client.message(this.version, this.clientId, body, abortSignal);
     }
 
+    streamMessage(
+        body: Models.IUserMessage,
+        handlers: AgentStreamHandlers,
+        abortSignal?: AbortSignal
+    ): Promise<Models.BotMessage> {
+        /*
+         * Build the URL exactly as the generated Client does for `/api/v{version}/message`:
+         * substitute {version}, then strip a dangling query separator.
+         */
+        const url = (this.baseUrl + AGENT_STREAM_PATH_TEMPLATE)
+            .replace('{version}', encodeURIComponent('' + this.version))
+            .replace(/[?&]$/, '');
+
+        return runAgentStream({
+            url,
+            fetch: this.httpFetch,
+            headers: {
+                'X-Client-ID': this.clientId,
+                ...(this.chatbotApiClientSettings.streamHeadersFactory?.() ?? {}),
+            },
+            body,
+            handlers,
+            abortSignal,
+        });
+    }
+
     postFollowUpEmail(body: Models.UserMessage, abortSignal?: AbortSignal) {
         return this.client.followUpEmail(this.version, this.clientId, body, abortSignal);
     }

package/src/index.ts

@@ -1,7 +1,12 @@
 /* eslint-disable no-restricted-imports */
 export * from './api-client';
 export * from './stores';
+export * from './streaming';
 export type * from './models';
+// Runtime helpers from models (the `export type *` above is type-only).
+export {
+    isChatbotStreamingEnabled,
+    DEFAULT_STREAMING_INACTIVITY_TIMEOUT_MS,
+} from './models/chatbot-customizations';
 export * from './hooks/use-customization-chatbot';
-export * as NativeClientHC from './api-client/help-center/native-client';
 export * as NativeClientTC from './api-client/titan-chat/native-client';

package/src/models/__tests__/chatbot-customizations.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from '@jest/globals';
+import { ChatbotCustomizations, isChatbotStreamingEnabled } from '../chatbot-customizations';
+
+describe('ChatbotCustomizations streaming setting', () => {
+    test('streaming is disabled when customizations are undefined', () => {
+        expect(isChatbotStreamingEnabled(undefined)).toBe(false);
+    });
+
+    test('streaming is disabled when the streaming setting is absent', () => {
+        const c: ChatbotCustomizations = { feedback: { title: 'x' } };
+        expect(isChatbotStreamingEnabled(c)).toBe(false);
+    });
+
+    test('streaming is disabled when explicitly false', () => {
+        const c: ChatbotCustomizations = { streaming: { enabled: false } };
+        expect(isChatbotStreamingEnabled(c)).toBe(false);
+    });
+
+    test('streaming is enabled only when explicitly true', () => {
+        const c: ChatbotCustomizations = {
+            streaming: { enabled: true, inactivityTimeoutMs: 16_000 },
+        };
+        expect(isChatbotStreamingEnabled(c)).toBe(true);
+        expect(c.streaming?.inactivityTimeoutMs).toBe(16_000);
+    });
+});

package/src/models/chatbot-customizations.ts

@@ -10,6 +10,19 @@ export type FilterDefaultSelectionFn = (filterKey: string, optionKey: string) =>
 
 export type ChatbotCustomizations = ChatCustomizations &
     Partial<{
+        /**
+         * Agent-progress SSE streaming. Disabled by default; when disabled (or when the streaming
+         * endpoint is unreachable at connect time) the widget falls back to the non-streaming path.
+         */
+        streaming?: {
+            /** Opt in to the SSE streaming send-path. Defaults to false. */
+            enabled?: boolean;
+            /**
+             * Inactivity threshold (ms) before the "Still working on it…" keepalive is shown.
+             * Defaults to 16000 (matching the legacy hard timeout).
+             */
+            inactivityTimeoutMs?: number;
+        };
         timeouts?: {
             chatbotRequestTimeoutMs?: number;
         };
@@ -31,3 +44,10 @@ export type ChatbotCustomizations = ChatCustomizations &
             isDefaultSelected?: FilterDefaultSelectionFn;
         };
     }>;
+
+/** Default inactivity threshold before the keepalive message is shown (ms). */
+export const DEFAULT_STREAMING_INACTIVITY_TIMEOUT_MS = 16_000;
+
+/** Whether the SSE streaming send-path is enabled. Defaults to off. */
+export const isChatbotStreamingEnabled = (customizations?: ChatbotCustomizations): boolean =>
+    customizations?.streaming?.enabled ?? false;

package/src/models/index.ts

@@ -1 +1 @@
-export type * from './chatbot-customizations';
+export * from './chatbot-customizations';