@tagit/ai-client-core 0.5.0 → 0.6.0

package/README.md

@@ -52,6 +52,18 @@ import { AIClient, createDefaultConfig } from '@tagit/ai-client-core';
 
 const client = new AIClient(
   createDefaultConfig('uc-default-1lji40', 'https://ai.tagit.live', {
+    user: {
+      entityId: 'anonymous-or-authenticated-user-id',
+      userId: 'optional-friendly-user-id',
+      entityidType: 'internal_user_id',
+      entityidAlgo: 'native',
+      entityidOwner: 'your-service',
+    },
+    conversation: {
+      conversationId: 'optional-durable-conversation-id',
+      title: 'Optional conversation title',
+      memoryMaxTurns: 6,
+    },
     orchestrator: {
       apiKey: import.meta.env.VITE_TAGIT_AI_ORCHESTRATOR_API_KEY,
     },
@@ -68,7 +80,7 @@ const client = new AIClient(
 
 `AIClient` is the stateful engine:
 
-- builds the `/v1/chat` request
+- builds the `/v2/chat` request
 - manages the conversation transcript
 - streams assistant output
 - retries transient failures
@@ -81,7 +93,7 @@ const client = new AIClient(
 
 ### `OrchestratorRequest`
 
-`OrchestratorRequest` is the payload posted to the orchestrator `/v1/chat` endpoint.
+`OrchestratorRequest` is the payload posted to the orchestrator `/v2/chat` endpoint.
 
 ### `OrchestratorChunk`
 
@@ -106,14 +118,38 @@ const config = createDefaultConfig('uc-default-1lji40', 'https://ai.tagit.live',
 | Field | Type / values | Default | What it does | Example |
 |---|---|---:|---|---|
 | `useCaseId` | `string` | required | Runtime use case identifier used by the orchestrator. | `'uc-default-1lji40'` |
-| `orchestratorUrl` | URL string | required | Base URL for the orchestrator. Do not include `/v1/chat`. | `'https://ai.tagit.live'` |
+| `orchestratorUrl` | URL string | required | Base URL for the orchestrator. Do not include `/v2/chat`. | `'https://ai.tagit.live'` |
 | `options.orchestrator` | partial orchestrator config | `undefined` | Overrides specific orchestrator fields. | `{ apiKey: '...' }` |
+| `options.user` | user identity config | `undefined` | Shared identity used by orchestrator memory and collector events. | `{ entityId: 'user_123' }` |
+| `options.conversation` | conversation config | `undefined` | Durable conversation id, title, and memory window. | `{ memoryMaxTurns: 6 }` |
 | `options.collector` | partial collector config | `undefined` | Enables or customizes collector emission. | `{ enabled: false }` |
 | `options.ui` | partial UI config | `undefined` | Overrides client UI/runtime behavior. | `{ streaming: true }` |
 
+### Shared User Config
+
+The `user` block is the single identity source for V2. At minimum, production integrations should provide `user.entityId`. When `user.userId` is omitted, the SDK uses `user.entityId` as the orchestrator `user_id` and collector `content.contentData.userId`.
+
+| Field | Type / values | Required | What it does | Example |
+|---|---|---:|---|---|
+| `user.entityId` | string | yes for production | Primary user or anonymous entity identifier supplied by the host app. | `visitor_abc123` |
+| `user.userId` | string | no | Optional friendly/application user id. Defaults to `entityId`. | `sandro` |
+| `user.entityidType` | string | no | Entity type metadata for collector normalization. | `internal_user_id` |
+| `user.entityidAlgo` | string | no | Entity ID algorithm metadata. | `native` |
+| `user.entityidOwner` | string | no | Entity owner metadata. | `tagit.live` |
+
+### Shared Conversation Config
+
+The `conversation` block controls durable memory. The SDK sends only the current user message to the orchestrator; the orchestrator rehydrates recent history server-side using `conversationId` and `userId`.
+
+| Field | Type / values | Required | What it does | Example |
+|---|---|---:|---|---|
+| `conversation.conversationId` | string | no | Durable conversation identifier. Generated locally when omitted. | `conv-homepage-001` |
+| `conversation.title` | string | no | Optional user-facing title sent to the orchestrator. | `Homepage assistant` |
+| `conversation.memoryMaxTurns` | nonnegative integer | no | Server-side recent-history window. Use `0` to disable rehydration. | `6` |
+
 ### Orchestrator Config
 
-`orchestrator.baseUrl` should point to the orchestrator root URL, not `/v1/chat`. The client appends `/v1/chat` internally.
+`orchestrator.baseUrl` should point to the orchestrator root URL, not `/v2/chat`. The client appends `/v2/chat` internally.
 
 | Field | Type / values | Required | What it does | Example |
 |---|---|---:|---|---|
@@ -134,17 +170,14 @@ Collector is optional and can be disabled. When enabled, the client emits a TagI
 | `collector.baseUrl` | URL string | yes | Collector endpoint base URL. | `https://collector.tagit.live` |
 | `collector.tagId` | string | yes | Tag identifier used to route and classify collector events. | `tagit-site-demo` |
 | `collector.acceptCookies` | `boolean` | no | Whether the widget should request/set cookies when emitting collector events. | `true` |
-| `collector.userId` | string | no | Optional user identity for collector payloads. | `user_123` |
-| `collector.agentId` | string | no | Optional agent identity for collector payloads. | `uc-default-1lji40` |
-| `collector.entityId` | string | no | Optional entity identifier for the tracked subject. | `acct_456` |
-| `collector.entityidType` | string | no | Entity type metadata. | `account` |
-| `collector.entityidAlgo` | string | no | Entity ID algorithm metadata. | `sha256` |
-| `collector.entityidOwner` | string | no | Entity owner metadata. | `tagit` |
+| `collector.agentId` | string | no | Optional collector agent identity. Defaults to the request use case id. | `uc-default-1lji40` |
 | `collector.eventSubContext` | string | no | Optional sub-context identifier for the event surface. | `website-homepage` |
-| `collector.sessionId` | string | no | Optional session identifier. | `session_abc123` |
+| `collector.sessionId` | string | no | Optional collector session identifier. It is not the primary durable conversation id when `conversation.conversationId` exists. | `session_abc123` |
 | `collector.privacy.jurisdiction` | string | no | Privacy jurisdiction metadata. | `US-CA` |
 | `collector.privacy.purposesConsent.analytics` | `boolean` | no | Consent flag for analytics collection. | `true` |
 
+Legacy collector identity fields are still accepted for migration compatibility, but new integrations should put identity in the shared `user` block.
+
 ### UI Config
 
 | Field | Type / values | Default | What it does | Example |
@@ -177,7 +210,7 @@ const client = new AIClient(config, options);
 | `on(listener)` | `(): () => void` | Subscribes to client events and returns an unsubscribe function. | `client.on(handleEvent)` |
 | `sendMessage()` | `(message, options?) => Promise<void>` | Sends a user message and streams the orchestrator response. | `await client.sendMessage('Hello')` |
 | `cancel()` | `(): void` | Cancels the current in-flight request. | `client.cancel()` |
-| `clearHistory()` | `(): void` | Clears the transcript and resets the conversation ID. | `client.clearHistory()` |
+| `clearHistory()` | `(): void` | Clears the local transcript. If `conversation.conversationId` is configured, the durable id is preserved. | `client.clearHistory()` |
 | `trimHistoryBefore()` | `(messageId) => string \| null` | Removes a message and everything after it. | `client.trimHistoryBefore(id)` |
 
 ## Message Options
@@ -188,11 +221,18 @@ const client = new AIClient(config, options);
 |---|---|---|---|
 | `tools` | `'none' \| 'all' \| string[]` | Limits which MCP tools are available for the request. | `tools: 'none'` |
 | `useCaseMessage` | `string` | Injects an additional use-case instruction as a system message. | `useCaseMessage: 'Keep it short and direct.'` |
+| `userId` | `string` | Overrides the resolved user id for this request. | `userId: 'request-user'` |
+| `useCaseId` | `string` | Overrides the configured use case for this request. | `useCaseId: 'uc-other'` |
+| `snapshotId` | `string` | Overrides the configured snapshot for this request. | `snapshotId: 'snap-123'` |
+| `conversationId` | `string` | Overrides the durable conversation id for this request. | `conversationId: 'conv-other'` |
+| `conversationTitle` | `string` | Overrides the conversation title for this request. | `conversationTitle: 'Support chat'` |
+| `conversationMemoryMaxTurns` | `number` | Overrides the server-side memory window for this request. | `conversationMemoryMaxTurns: 0` |
 
 ```ts
 await client.sendMessage('Hello', {
   tools: 'none',
   useCaseMessage: 'You are helping a new customer onboard.',
+  conversationMemoryMaxTurns: 6,
 });
 ```
 
@@ -209,6 +249,11 @@ await client.sendMessage('Hello', {
 | `error` | `string \| undefined` | Safe user-facing error text. | `Request timed out before completion.` |
 | `lastError` | `ClientErrorInfo \| undefined` | Structured internal error details. | `{ code: 'TIMEOUT', ... }` |
 | `useCaseId` | `string` | Use case currently bound to the conversation. | `uc-default-1lji40` |
+| `workflowId` | `string \| undefined` | Latest workflow run id returned by a V2 workflow use case. | `wf_123` |
+| `workflowStatus` | `string \| undefined` | Latest workflow status returned by the orchestrator. | `completed` |
+| `checkpointPrompt` | `string \| undefined` | Latest checkpoint prompt returned by a workflow use case. | `Review before continuing?` |
+
+Checkpoint action UI is not included in the beta React widget. Consumers can inspect workflow metadata from state/events and add explicit continue/revise/cancel controls in a later integration.
 
 ## Client Events
 
@@ -239,24 +284,34 @@ await client.sendMessage('Hello', {
 
 ## Orchestrator Request Shape
 
-The core client posts a canonical request to `/v1/chat`.
+The core client posts a canonical request to `/v2/chat`.
 
 | Field | Type / values | Required | What it does | Example |
 |---|---|---:|---|---|
 | `use_case_id` | string | yes | Runtime use case identifier. | `uc-default-1lji40` |
 | `stream` | `boolean` | no | Requests SSE when `true`. | `true` |
-| `messages` | array | yes | Message history sent to the orchestrator. | `[{ role: 'user', content: 'Hello' }]` |
+| `messages` | array | yes | Current user message, plus optional `useCaseMessage` system instruction. Server-side memory comes from `conversation_id`. | `[{ role: 'user', content: 'Hello' }]` |
 | `tools` | `'none' \| 'all' \| string[]` | no | Limits which tools the orchestrator may use. | `['search_docs']` |
 | `snapshot_id` | string | no | Pins the request to a published orchestration snapshot. | `snapshot_2026_04_14` |
+| `runtime_version` | `'v2'` | yes | Runtime contract marker sent by the client. | `v2` |
+| `user_id` | string | yes | User id for ownership and conversation memory. | `visitor_abc123` |
+| `conversation_id` | string | yes | Durable conversation id. | `conv-homepage-001` |
+| `session_id` | string | no | Backward-compatible mirror of `conversation_id` during migration. | `conv-homepage-001` |
+| `conversation_title` | string | no | Optional conversation title. | `Homepage assistant` |
+| `conversation_memory_max_turns` | number | no | Server-side memory window. | `6` |
 
 Example:
 
 ```ts
 {
   use_case_id: 'uc-default-1lji40',
+  runtime_version: 'v2',
+  user_id: 'visitor_abc123',
+  conversation_id: 'conv-homepage-001',
+  session_id: 'conv-homepage-001',
+  conversation_memory_max_turns: 6,
   stream: true,
   messages: [
-    { role: 'system', content: 'Keep it short and direct.' },
     { role: 'user', content: 'How do I get started?' },
   ],
   tools: 'none',
@@ -301,7 +356,7 @@ import type { OrchestratorTransport } from '@tagit/ai-client-core';
 
 const transport: OrchestratorTransport = {
   async send(request, context) {
-    return fetch(`${context.baseUrl}/v1/chat`, {
+    return fetch(`${context.baseUrl}${context.endpointPath}`, {
       method: 'POST',
       headers: context.headers,
       body: JSON.stringify(request),

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { ClientConfig, ClientEventListener, ConversationState } from './types.js';
+import type { ClientConfig, ClientEventListener, ConversationState, SendMessageOptions } from './types.js';
 import { type OrchestratorTransport } from './transport.js';
 /**
  * Headless AI client core
@@ -34,6 +34,19 @@ export declare class AIClient {
      * Check if history exceeds max messages and emit warning event
      */
     private checkAndTrimHistory;
+    private getEndpointPath;
+    private buildRequestMessages;
+    resolveUserId(options?: Pick<SendMessageOptions, 'userId'>): string;
+    resolveConversationId(options?: Pick<SendMessageOptions, 'conversationId'>): string;
+    hasConfiguredConversationId(): boolean;
+    getResolvedIdentity(options?: Pick<SendMessageOptions, 'userId' | 'conversationId'>): {
+        userId: string;
+        conversationId: string;
+        entityId: string;
+        entityidType: string;
+        entityidAlgo: string;
+        entityidOwner: string;
+    };
     /**
      * Truncate error details to prevent massive error payloads
      */
@@ -41,10 +54,7 @@ export declare class AIClient {
     /**
      * Send a message and stream the response
      */
-    sendMessage(userMessage: string, options?: {
-        tools?: 'none' | 'all' | string[];
-        useCaseMessage?: string;
-    }): Promise<void>;
+    sendMessage(userMessage: string, options?: SendMessageOptions): Promise<void>;
     private streamResponseWithRetry;
     /**
      * Stream response from orchestrator
@@ -65,6 +75,7 @@ export declare class AIClient {
     private appendAssistantDelta;
     private applyTerminalContent;
     private handleNonStreamingResponse;
+    private applyWorkflowDetails;
     private extractAssistantText;
     private shouldAcceptDegradedCompletion;
     private hasAssistantContent;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,YAAY,EAEZ,mBAAmB,EACnB,iBAAiB,EAMlB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AASxB;;;GAGG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,WAAW,CAAmC;IACtD,OAAO,CAAC,SAAS,CAAwB;gBAGvC,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,qBAAqB,CAAC;KACnC;IAaH;;OAEG;IACH,QAAQ,IAAI,iBAAiB;IAI7B;;OAEG;IACH,EAAE,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,IAAI;IAO7C;;OAEG;IACH,OAAO,CAAC,IAAI;IAUZ;;OAEG;IACH,OAAO,CAAC,eAAe;IAUvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmB5B;;OAEG;IACG,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,EAAE,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GACvE,OAAO,CAAC,IAAI,CAAC;YAuDF,uBAAuB;IA0CrC;;OAEG;YACW,cAAc;IA4M5B;;OAEG;YACW,WAAW;IAoHzB;;;OAGG;YACW,mBAAmB;IA0BjC,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,oBAAoB;IAwB5B,OAAO,CAAC,oBAAoB;YAyBd,0BAA0B;IA0CxC,OAAO,CAAC,oBAAoB;IAkC5B,OAAO,CAAC,8BAA8B;IAgBtC,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,cAAc;IAgCtB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,0BAA0B;IAUlC,OAAO,CAAC,mBAAmB;IAyC3B;;OAEG;YACW,kBAAkB;IA8DhC;;OAEG;IACH,MAAM,IAAI,IAAI;IAUd;;;OAGG;IACH,YAAY,IAAI,IAAI;IAiBpB;;;;;OAKG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAWpD;AAED,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,YAAY,EAEZ,mBAAmB,EACnB,iBAAiB,EAMjB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AASxB;;;GAGG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,WAAW,CAAmC;IACtD,OAAO,CAAC,SAAS,CAAwB;gBAGvC,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,qBAAqB,CAAC;KACnC;IAiBH;;OAEG;IACH,QAAQ,IAAI,iBAAiB;IAI7B;;OAEG;IACH,EAAE,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,IAAI;IAO7C;;OAEG;IACH,OAAO,CAAC,IAAI;IAUZ;;OAEG;IACH,OAAO,CAAC,eAAe;IAUvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,oBAAoB;IAwB5B,aAAa,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,GAAG,MAAM;IAYnE,qBAAqB,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,GAAG,MAAM;IASnF,2BAA2B,IAAI,OAAO;IAItC,mBAAmB,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,gBAAgB,CAAC,GAAG;QACpF,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB;IAYD;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmB5B;;OAEG;IACG,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC;YAuDF,uBAAuB;IAyCrC;;OAEG;YACW,cAAc;IA0M5B;;OAEG;YACW,WAAW;IAqHzB;;;OAGG;YACW,mBAAmB;IA0BjC,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,oBAAoB;IAwB5B,OAAO,CAAC,oBAAoB;YA0Bd,0BAA0B;IA2CxC,OAAO,CAAC,oBAAoB;IA+C5B,OAAO,CAAC,oBAAoB;IAkC5B,OAAO,CAAC,8BAA8B;IAgBtC,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,cAAc;IAgCtB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,0BAA0B;IAUlC,OAAO,CAAC,mBAAmB;IA+C3B;;OAEG;YACW,kBAAkB;IAkEhC;;OAEG;IACH,MAAM,IAAI,IAAI;IAUd;;;OAGG;IACH,YAAY,IAAI,IAAI;IAmBpB;;;;;OAKG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAWpD;AAED,eAAe,QAAQ,CAAC"}

package/dist/client.js

@@ -50,8 +50,11 @@ export class AIClient {
         });
         this.config = validateConfig(config);
         this.transport = options?.transport ?? new FetchOrchestratorTransport();
+        const initialConversationId = this.config.conversation?.conversationId?.trim() ||
+            this.config.collector?.sessionId?.trim() ||
+            generateId();
         this.conversationState = {
-            id: generateId(),
+            id: initialConversationId,
             messages: [],
             isLoading: false,
             isStreaming: false,
@@ -111,6 +114,56 @@ export class AIClient {
             });
         }
     }
+    getEndpointPath() {
+        return '/v2/chat';
+    }
+    buildRequestMessages(useCaseMessage) {
+        const allMessages = this.conversationState.messages.map((msg) => ({
+            role: msg.role,
+            content: msg.content,
+        }));
+        let requestMessages = allMessages.slice(-1);
+        const trimmedUseCaseMessage = useCaseMessage?.trim();
+        if (trimmedUseCaseMessage) {
+            requestMessages = [
+                {
+                    role: 'system',
+                    content: trimmedUseCaseMessage,
+                },
+                ...requestMessages,
+            ];
+        }
+        return requestMessages;
+    }
+    resolveUserId(options) {
+        const user = this.config.user;
+        return (options?.userId?.trim() ||
+            user?.userId?.trim() ||
+            user?.entityId?.trim() ||
+            this.config.collector?.userId?.trim() ||
+            this.config.collector?.entityId?.trim() ||
+            this.conversationState.id);
+    }
+    resolveConversationId(options) {
+        return (options?.conversationId?.trim() ||
+            this.config.conversation?.conversationId?.trim() ||
+            this.config.collector?.sessionId?.trim() ||
+            this.conversationState.id);
+    }
+    hasConfiguredConversationId() {
+        return Boolean(this.config.conversation?.conversationId?.trim());
+    }
+    getResolvedIdentity(options) {
+        const userId = this.resolveUserId(options);
+        return {
+            userId,
+            conversationId: this.resolveConversationId(options),
+            entityId: this.config.user?.entityId?.trim() || this.config.collector?.entityId?.trim() || userId,
+            entityidType: this.config.user?.entityidType?.trim() || this.config.collector?.entityidType?.trim() || 'internal_user_id',
+            entityidAlgo: this.config.user?.entityidAlgo?.trim() || this.config.collector?.entityidAlgo?.trim() || 'native',
+            entityidOwner: this.config.user?.entityidOwner?.trim() || this.config.collector?.entityidOwner?.trim() || 'tagit-ai-client',
+        };
+    }
     /**
      * Truncate error details to prevent massive error payloads
      */
@@ -156,11 +209,11 @@ export class AIClient {
         this.conversationState.isLoading = true;
         this.emit({ type: 'message_added', message: userMsg });
         try {
-            await this.streamResponseWithRetry(options?.tools, options?.useCaseMessage);
+            await this.streamResponseWithRetry(options);
             // Emit collector event if configured
             if (this.config.collector?.enabled) {
                 const assistantMsg = this.findLatestAssistantMessage();
-                await this.emitCollectorEvent(userMsg, assistantMsg ?? null);
+                await this.emitCollectorEvent(userMsg, assistantMsg ?? null, options);
             }
         }
         catch (error) {
@@ -183,13 +236,13 @@ export class AIClient {
             this.emit({ type: 'state_synced' });
         }
     }
-    async streamResponseWithRetry(tools, useCaseMessage) {
+    async streamResponseWithRetry(options) {
         const retries = this.config.orchestrator.maxRetries ?? 0;
         const maxAttempts = Math.max(1, retries + 1);
         for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
             const baselineLength = this.conversationState.messages.length;
             try {
-                await this.streamResponse(tools, useCaseMessage);
+                await this.streamResponse(options);
                 return;
             }
             catch (error) {
@@ -219,32 +272,30 @@ export class AIClient {
     /**
      * Stream response from orchestrator
      */
-    async streamResponse(tools, useCaseMessage) {
-        const requestMessages = this.conversationState.messages.map((msg) => ({
-            role: msg.role,
-            content: msg.content,
-        }));
-        const trimmedUseCaseMessage = useCaseMessage?.trim();
-        if (trimmedUseCaseMessage) {
-            requestMessages.unshift({
-                role: 'system',
-                content: trimmedUseCaseMessage,
-            });
-        }
+    async streamResponse(options) {
+        const requestMessages = this.buildRequestMessages(options?.useCaseMessage);
+        const endpointPath = this.getEndpointPath();
         const request = {
-            use_case_id: this.config.orchestrator.useCaseId,
+            use_case_id: options?.useCaseId?.trim() || this.config.orchestrator.useCaseId,
             stream: this.config.ui?.streaming ?? true,
             messages: requestMessages,
         };
-        if (tools) {
-            request.tools = tools;
-        }
-        if (this.config.orchestrator.snapshotId) {
-            request.snapshot_id = this.config.orchestrator.snapshotId;
+        request.runtime_version = 'v2';
+        request.conversation_id = this.resolveConversationId(options);
+        request.session_id = request.conversation_id;
+        request.user_id = this.resolveUserId(options);
+        request.conversation_title = options?.conversationTitle ?? this.config.conversation?.title;
+        request.conversation_memory_max_turns = options?.conversationMemoryMaxTurns ?? this.config.conversation?.memoryMaxTurns;
+        if (options?.tools) {
+            request.tools = options.tools;
+        }
+        const snapshotId = options?.snapshotId?.trim() || this.config.orchestrator.snapshotId;
+        if (snapshotId) {
+            request.snapshot_id = snapshotId;
         }
         this.emit({
             type: 'orchestrator_request',
-            endpoint: `${this.config.orchestrator.baseUrl}/v1/chat`,
+            endpoint: `${this.config.orchestrator.baseUrl.replace(/\/+$/, '')}${endpointPath}`,
             request,
         });
         this.abortReason = null;
@@ -265,6 +316,7 @@ export class AIClient {
         try {
             const response = await this.transport.send(request, {
                 baseUrl: this.config.orchestrator.baseUrl,
+                endpointPath,
                 headers,
                 signal: this.abortController.signal,
             });
@@ -475,6 +527,7 @@ export class AIClient {
                 const text = this.extractAssistantText(chunk.data) ?? '';
                 const lastMsg = this.conversationState.messages[this.conversationState.messages.length - 1];
                 if (text.trim() && lastMsg?.role === 'assistant' && !lastMsg.content.trim()) {
+                    this.applyWorkflowDetails(chunk.data);
                     // Server batched the full response with no deltas — animate it in.
                     this.emit({ type: 'first_token', messageId: lastMsg.id });
                     await this.simulateDeltaStream(text, lastMsg.id);
@@ -576,6 +629,7 @@ export class AIClient {
         return target.id;
     }
     applyTerminalContent(data) {
+        this.applyWorkflowDetails(data);
         const text = this.extractAssistantText(data) ?? '';
         if (!text.trim()) {
             return;
@@ -614,6 +668,7 @@ export class AIClient {
         if (contentType.includes('application/json') || raw.trim().startsWith('{')) {
             try {
                 const parsed = JSON.parse(raw);
+                this.applyWorkflowDetails(parsed);
                 const extracted = this.extractAssistantText(parsed);
                 assistantText = extracted ?? raw;
             }
@@ -633,6 +688,48 @@ export class AIClient {
             this.emit({ type: 'first_token', messageId: assistantMsg.id });
         }
     }
+    applyWorkflowDetails(payload) {
+        const details = payload.details;
+        if (!details || typeof details !== 'object') {
+            return;
+        }
+        const workflow = details.workflow;
+        if (!workflow || typeof workflow !== 'object') {
+            return;
+        }
+        const workflowDetails = workflow;
+        const conversationId = typeof workflowDetails.conversationId === 'string'
+            ? workflowDetails.conversationId.trim()
+            : undefined;
+        const workflowId = typeof workflowDetails.workflowId === 'string'
+            ? workflowDetails.workflowId.trim()
+            : undefined;
+        const status = typeof workflowDetails.status === 'string'
+            ? workflowDetails.status.trim()
+            : undefined;
+        const checkpointPrompt = typeof workflowDetails.checkpointPrompt === 'string'
+            ? workflowDetails.checkpointPrompt
+            : undefined;
+        if (conversationId && conversationId !== this.conversationState.id) {
+            this.conversationState.id = conversationId;
+        }
+        if (workflowId) {
+            this.conversationState.workflowId = workflowId;
+        }
+        if (status) {
+            this.conversationState.workflowStatus = status;
+        }
+        if (checkpointPrompt !== undefined) {
+            this.conversationState.checkpointPrompt = checkpointPrompt;
+        }
+        this.emit({
+            type: 'workflow_metadata_updated',
+            conversationId: conversationId || this.conversationState.id,
+            workflowId,
+            status,
+            checkpointPrompt,
+        });
+    }
     extractAssistantText(payload) {
         const messages = payload.messages;
         if (Array.isArray(messages)) {
@@ -722,16 +819,18 @@ export class AIClient {
         }
         return undefined;
     }
-    buildCollectorEvent(userMessage, assistantMessage) {
+    buildCollectorEvent(userMessage, assistantMessage, options) {
         const collector = this.config.collector;
-        const userId = collector.userId ?? this.conversationState.id;
-        const agentId = collector.agentId ?? this.config.orchestrator.useCaseId;
-        const entityId = collector.entityId ?? userId;
-        const entityidType = collector.entityidType ?? 'internal_user_id';
-        const entityidAlgo = collector.entityidAlgo ?? 'native';
-        const entityidOwner = collector.entityidOwner ?? 'tagit-ai-client';
+        const resolved = this.getResolvedIdentity(options);
+        const userId = resolved.userId;
+        const requestUseCaseId = options?.useCaseId?.trim() || this.config.orchestrator.useCaseId;
+        const agentId = collector.agentId ?? requestUseCaseId;
+        const entityId = resolved.entityId;
+        const entityidType = resolved.entityidType;
+        const entityidAlgo = resolved.entityidAlgo;
+        const entityidOwner = resolved.entityidOwner;
         const acceptCookies = collector.acceptCookies ?? false;
-        const eventSubContext = collector.eventSubContext ?? this.config.orchestrator.useCaseId;
+        const eventSubContext = collector.eventSubContext ?? requestUseCaseId;
         return {
             tagId: collector.tagId,
             tagType: 'web-sdk-nativeId',
@@ -752,7 +851,7 @@ export class AIClient {
                 contentData: {
                     userId,
                     agentId,
-                    conversationId: this.conversationState.id,
+                    conversationId: resolved.conversationId,
                     userMessageId: userMessage.id,
                     agentMessageId: assistantMessage?.id ?? null,
                     userMessage: userMessage.content,
@@ -764,12 +863,12 @@ export class AIClient {
     /**
      * Emit a conversation event to the TagIt collector
      */
-    async emitCollectorEvent(userMessage, assistantMessage) {
+    async emitCollectorEvent(userMessage, assistantMessage, options) {
         if (!this.config.collector?.baseUrl || !this.config.collector?.tagId) {
             return;
         }
         const endpoint = this.config.collector.baseUrl;
-        const event = this.buildCollectorEvent(userMessage, assistantMessage);
+        const event = this.buildCollectorEvent(userMessage, assistantMessage, options);
         try {
             const MAX_PAYLOAD_SIZE = 16 * 1024;
             const body = JSON.stringify(event);
@@ -845,7 +944,9 @@ export class AIClient {
             });
         }
         this.conversationState.messages = [];
-        this.conversationState.id = generateId();
+        if (!this.hasConfiguredConversationId()) {
+            this.conversationState.id = generateId();
+        }
         this.conversationState.error = undefined;
         this.conversationState.lastError = undefined;
         this.conversationState.isStreaming = false;