@csntgao/uni-base 0.1.0

package/packages/core/src/client.ts

@@ -0,0 +1,1132 @@
+import {
+  createAuthenticateFrame,
+  createPingFrame,
+  createSubscriptionFrame,
+  hashText,
+  parseAiEmployeeEvent,
+  parseJsonRecord,
+} from './protocol'
+import type {
+  AiEmployeeClientErrorDetail,
+  AiEmployeeClientEventMap,
+  AiEmployeeClientListener,
+  AiEmployeeClientOptions,
+  AiEmployeeClientStartResult,
+  AiEmployeeConnectionState,
+  AiEmployeeErrorCode,
+  AiEmployeeFirstMessageOptions,
+  AiEmployeeFirstMessageRequest,
+  AiEmployeeFirstMessageRequestState,
+  AiEmployeeFirstMessageRequestStore,
+  AiEmployeeFirstMessageResult,
+  AiEmployeeMessage,
+  AiEmployeeReconnectOptions,
+  AiEmployeeTransportErrorCode,
+  AiEmployeeWebSocketFactory,
+} from './types'
+
+type UntypedListener = (detail: unknown) => void
+type JsonRecord = Record<string, unknown>
+
+const DEFAULT_RECONNECT: AiEmployeeReconnectOptions = {
+  initialDelayMs: 1_000,
+  maximumDelayMs: 30_000,
+  factor: 2,
+  jitter: 0.2,
+}
+const MAX_SEEN_MESSAGE_IDS = 2_000
+const LOCAL_MESSAGE_MATCH_WINDOW_MS = 30_000
+const MAX_AVAILABILITY_RECONNECTS = 3
+const FIRST_MESSAGE_STORAGE_PREFIX = 'uniplat.ai-employee.first-message'
+
+type AuthenticationRetryMode = 'token' | 'availability' | 'never'
+
+interface SocketAuthenticationFailure {
+  generation: number
+  retryMode: AuthenticationRetryMode
+}
+
+interface PendingFirstMessage {
+  fingerprint: string
+  requestId: string
+}
+
+export class AiEmployeeClientError extends Error {
+  readonly code: AiEmployeeErrorCode
+
+  constructor(code: AiEmployeeErrorCode, message: string) {
+    super(message)
+    this.name = 'AiEmployeeClientError'
+    this.code = code
+  }
+}
+
+export class AiEmployeeTransportError extends Error {
+  readonly code: AiEmployeeTransportErrorCode
+
+  constructor(code: AiEmployeeTransportErrorCode) {
+    super('AI Employee transport request failed.')
+    this.name = 'AiEmployeeTransportError'
+    this.code = code
+  }
+}
+
+export class AiEmployeeClient {
+  readonly aeCode: string
+  readonly agentCode: string
+
+  private readonly realtimeUrl: string
+  private readonly transport: AiEmployeeClientOptions['transport']
+  private readonly webSocketFactory: AiEmployeeWebSocketFactory
+  private readonly reconnectOptions: AiEmployeeReconnectOptions
+  private readonly minimumHeartbeatMs: number
+  private readonly requestIdFactory: () => string
+  private readonly firstMessageRequestStore: AiEmployeeFirstMessageRequestStore | null
+  private readonly firstMessageRequestScope: string
+  private readonly listeners = new Map<keyof AiEmployeeClientEventMap, Set<UntypedListener>>()
+  private readonly seenMessageIds = new Set<string>()
+  private readonly pendingLocalMessages = new Map<string, number>()
+  private assistantReceivedInCurrentTurn = false
+
+  private socket: WebSocket | null = null
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null
+  private initializePromise: Promise<AiEmployeeClientStartResult> | null = null
+  private currentMessages: AiEmployeeMessage[] = []
+  private currentSessionId: string | null
+  private currentState: AiEmployeeConnectionState = 'idle'
+  private reconnectAttempt = 0
+  private socketGeneration = 0
+  private lifecycleGeneration = 0
+  private shouldReconnect = false
+  private destroyed = false
+  private sending = false
+  private processing = false
+  private localMessageSequence = 0
+  private replayHistoryOnNextSubscription = false
+  private socketAuthenticationFailure: SocketAuthenticationFailure | null = null
+  private availabilityReconnectAttempt = 0
+  private pendingFirstMessage: PendingFirstMessage | null = null
+
+  constructor(options: AiEmployeeClientOptions) {
+    this.realtimeUrl = validateRealtimeUrl(options.realtimeUrl)
+    this.aeCode = requiredText(options.aeCode, 'aeCode')
+    this.agentCode = requiredText(options.agentCode, 'agentCode')
+    if (!options.transport) {
+      throw new AiEmployeeClientError('INVALID_CONFIGURATION', '缺少 transport 配置。')
+    }
+    if (typeof options.transport.createSessionWithFirstMessage !== 'function') {
+      throw new AiEmployeeClientError(
+        'INVALID_CONFIGURATION',
+        'transport 缺少首条消息原子创建能力。',
+      )
+    }
+    this.transport = options.transport
+    this.currentSessionId = normalizeSessionId(options.sessionId)
+    this.reconnectOptions = normalizeReconnectOptions(options.reconnect)
+    this.minimumHeartbeatMs = Math.max(1, options.minimumHeartbeatMs ?? 5_000)
+    this.requestIdFactory = options.requestIdFactory ?? createRequestId
+    this.firstMessageRequestStore =
+      options.firstMessageRequestStore === undefined
+        ? createSessionFirstMessageRequestStore()
+        : options.firstMessageRequestStore
+    this.firstMessageRequestScope = `${this.aeCode}:${this.agentCode}`
+    this.webSocketFactory =
+      options.webSocketFactory ??
+      ((url) => {
+        if (typeof WebSocket === 'undefined') {
+          throw new AiEmployeeClientError('WEBSOCKET_UNAVAILABLE', '当前运行环境不支持 WebSocket。')
+        }
+        return new WebSocket(url)
+      })
+  }
+
+  get connectionState(): AiEmployeeConnectionState {
+    return this.currentState
+  }
+
+  get sessionId(): string | null {
+    return this.currentSessionId
+  }
+
+  get messages(): readonly AiEmployeeMessage[] {
+    return [...this.currentMessages]
+  }
+
+  get isProcessing(): boolean {
+    return this.processing
+  }
+
+  get isDestroyed(): boolean {
+    return this.destroyed
+  }
+
+  on<K extends keyof AiEmployeeClientEventMap>(
+    type: K,
+    listener: AiEmployeeClientListener<K>,
+  ): () => void {
+    this.assertUsable()
+    const listeners = this.listeners.get(type) ?? new Set<UntypedListener>()
+    const untypedListener = listener as UntypedListener
+    listeners.add(untypedListener)
+    this.listeners.set(type, listeners)
+    return () => listeners.delete(untypedListener)
+  }
+
+  connect(): Promise<AiEmployeeClientStartResult> {
+    return this.start()
+  }
+
+  start(): Promise<AiEmployeeClientStartResult> {
+    this.assertUsable()
+    if (this.initializePromise) return this.initializePromise
+
+    const lifecycle = this.lifecycleGeneration
+    const pending = this.initialize(lifecycle)
+    this.initializePromise = pending
+    const clearPending = () => {
+      if (this.initializePromise === pending) this.initializePromise = null
+    }
+    void pending.then(clearPending, clearPending)
+    return pending
+  }
+
+  async bindSession(sessionId: string): Promise<AiEmployeeClientStartResult> {
+    this.assertUsable()
+    const target = requiredText(sessionId, 'sessionId')
+    const lifecycle = ++this.lifecycleGeneration
+    this.stopConnection(false)
+    this.currentSessionId = target
+    this.currentMessages = []
+    this.seenMessageIds.clear()
+    this.pendingLocalMessages.clear()
+    this.assistantReceivedInCurrentTurn = false
+    this.pendingFirstMessage = null
+    await this.clearStoredFirstMessageRequest()
+    this.replayHistoryOnNextSubscription = false
+    this.shouldReconnect = true
+    await this.refreshHistory(lifecycle)
+    this.assertUsable()
+    if (!this.isCurrentLifecycle(lifecycle)) {
+      throw new AiEmployeeClientError('SESSION_UNAVAILABLE', '会话切换已被新的操作替代。')
+    }
+    if (this.isCurrentLifecycle(lifecycle)) this.openSocket(false)
+    return { sessionId: target, messages: this.messages }
+  }
+
+  async startNewConversation(): Promise<AiEmployeeClientStartResult> {
+    this.assertUsable()
+    this.initializePromise = null
+    this.lifecycleGeneration += 1
+    this.stopConnection(false)
+    this.currentSessionId = null
+    this.currentMessages = []
+    this.seenMessageIds.clear()
+    this.pendingLocalMessages.clear()
+    this.assistantReceivedInCurrentTurn = false
+    this.pendingFirstMessage = null
+    await this.clearStoredFirstMessageRequest()
+    this.replayHistoryOnNextSubscription = false
+    this.shouldReconnect = true
+    this.openSocket(false)
+    return { sessionId: null, messages: [] }
+  }
+
+  async refreshMessages(): Promise<readonly AiEmployeeMessage[]> {
+    this.assertUsable()
+    if (!this.currentSessionId) {
+      throw new AiEmployeeClientError('SESSION_UNAVAILABLE', '尚未绑定数字员工会话。')
+    }
+    await this.refreshHistory(this.lifecycleGeneration)
+    return this.messages
+  }
+
+  async sendMessage(
+    content: string,
+    options: AiEmployeeFirstMessageOptions = {},
+  ): Promise<AiEmployeeMessage> {
+    this.assertUsable()
+    const normalizedContent = content.trim()
+    if (!normalizedContent) {
+      throw new AiEmployeeClientError('EMPTY_MESSAGE', '消息内容不能为空。')
+    }
+    if (this.sending) {
+      throw new AiEmployeeClientError('SEND_IN_PROGRESS', '上一条消息仍在发送中。')
+    }
+    this.sending = true
+    try {
+      const sessionId = this.currentSessionId
+      return sessionId
+        ? await this.sendFollowUp(sessionId, normalizedContent)
+        : await this.sendFirstMessage(normalizedContent, options)
+    } catch (error) {
+      if (error instanceof AiEmployeeClientError) throw error
+      if (transportErrorCode(error) === 'IDEMPOTENCY_CONFLICT') {
+        const detail = this.emitError(
+          'FIRST_MESSAGE_CONFLICT',
+          '首条消息内容已变化，请开启新对话后重试。',
+          false,
+        )
+        throw new AiEmployeeClientError(detail.code, detail.message)
+      }
+      if (transportErrorCode(error) === 'TOO_MANY_REQUESTS') {
+        const detail = this.emitError('RATE_LIMITED', '请求过于频繁，请稍后再试。', false)
+        throw new AiEmployeeClientError(detail.code, detail.message)
+      }
+      const detail = this.emitError('SEND_FAILED', '消息发送失败，请稍后重试。', true)
+      throw new AiEmployeeClientError(detail.code, detail.message)
+    } finally {
+      this.sending = false
+    }
+  }
+
+  disconnect(): void {
+    if (this.destroyed) return
+    this.lifecycleGeneration += 1
+    this.stopConnection(true)
+  }
+
+  destroy(): void {
+    if (this.destroyed) return
+    this.lifecycleGeneration += 1
+    this.stopConnection(false)
+    this.destroyed = true
+    this.initializePromise = null
+    this.setState('destroyed')
+    this.listeners.clear()
+    this.currentMessages = []
+    this.seenMessageIds.clear()
+    this.pendingLocalMessages.clear()
+    this.assistantReceivedInCurrentTurn = false
+    this.pendingFirstMessage = null
+  }
+
+  private async sendFollowUp(sessionId: string, content: string): Promise<AiEmployeeMessage> {
+    this.assistantReceivedInCurrentTurn = false
+    await this.transport.sendMessage(sessionId, content)
+    this.assertUsable()
+    const now = new Date()
+    const message: AiEmployeeMessage = {
+      id: `local:${now.getTime()}:${++this.localMessageSequence}`,
+      sessionId,
+      role: 'user',
+      content,
+      createdAt: now.toISOString(),
+    }
+    for (const [pendingContent, sentAt] of this.pendingLocalMessages) {
+      if (now.getTime() - sentAt > LOCAL_MESSAGE_MATCH_WINDOW_MS) {
+        this.pendingLocalMessages.delete(pendingContent)
+      }
+    }
+    this.pendingLocalMessages.set(content, now.getTime())
+    this.appendMessage(message, 'local')
+    this.setProcessing(true)
+    return message
+  }
+
+  private async sendFirstMessage(
+    content: string,
+    options: AiEmployeeFirstMessageOptions,
+  ): Promise<AiEmployeeMessage> {
+    this.assistantReceivedInCurrentTurn = false
+    const createSessionWithFirstMessage = this.transport.createSessionWithFirstMessage
+    const lifecycle = this.lifecycleGeneration
+    const normalizedOptions = normalizeFirstMessageOptions(options)
+    const fingerprint = firstMessageFingerprint(content, normalizedOptions)
+    if (!this.pendingFirstMessage || this.pendingFirstMessage.fingerprint !== fingerprint) {
+      const stored = await this.loadStoredFirstMessageRequest()
+      this.pendingFirstMessage =
+        stored?.fingerprint === fingerprint
+          ? stored
+          : { fingerprint, requestId: requiredRequestId(this.requestIdFactory()) }
+      await this.saveStoredFirstMessageRequest(this.pendingFirstMessage)
+    }
+    this.assertUsable()
+    if (!this.isCurrentLifecycle(lifecycle) || this.currentSessionId) {
+      this.pendingFirstMessage = null
+      await this.clearStoredFirstMessageRequest()
+      throw new AiEmployeeClientError('SESSION_UNAVAILABLE', '首条消息受理已被新的操作替代。')
+    }
+    const request: AiEmployeeFirstMessageRequest = {
+      requestId: this.pendingFirstMessage.requestId,
+      aeCode: this.aeCode,
+      agentCode: this.agentCode,
+      content,
+      attachments: normalizedOptions.attachments,
+      trustedContext: normalizedOptions.trustedContext,
+    }
+    const rawResult = await createSessionWithFirstMessage.call(this.transport, request)
+    const result = normalizeFirstMessageResult(rawResult, this.aeCode, this.agentCode)
+    this.assertUsable()
+    if (!this.isCurrentLifecycle(lifecycle) || this.currentSessionId) {
+      this.pendingFirstMessage = null
+      await this.clearStoredFirstMessageRequest()
+      throw new AiEmployeeClientError('SESSION_UNAVAILABLE', '首条消息受理已被新的操作替代。')
+    }
+
+    this.currentSessionId = result.sessionId
+    this.pendingFirstMessage = null
+    await this.clearStoredFirstMessageRequest()
+    const message: AiEmployeeMessage = {
+      id: result.messageId,
+      sessionId: result.sessionId,
+      role: 'user',
+      content,
+      createdAt: result.createdAt ?? result.startedAt,
+    }
+    this.appendMessage(message, 'local')
+    this.setProcessing(true)
+    this.replayHistoryOnNextSubscription = true
+    this.subscribeCurrentSession(true)
+    return message
+  }
+
+  private async initialize(lifecycle: number): Promise<AiEmployeeClientStartResult> {
+    if (!this.currentSessionId) {
+      this.shouldReconnect = true
+      this.openSocket(false)
+      return { sessionId: null, messages: [] }
+    }
+
+    await this.refreshHistory(lifecycle)
+    this.assertUsable()
+    if (!this.isCurrentLifecycle(lifecycle)) {
+      throw new AiEmployeeClientError('SESSION_UNAVAILABLE', '会话初始化已被新的操作替代。')
+    }
+    this.shouldReconnect = true
+    this.openSocket(false)
+    return { sessionId: this.currentSessionId, messages: this.messages }
+  }
+
+  private async loadStoredFirstMessageRequest(): Promise<PendingFirstMessage | null> {
+    if (!this.firstMessageRequestStore) return null
+    try {
+      const state = await this.firstMessageRequestStore.load(this.firstMessageRequestScope)
+      if (!state || typeof state.fingerprint !== 'string') return null
+      return {
+        fingerprint: state.fingerprint,
+        requestId: requiredRequestId(state.requestId),
+      }
+    } catch {
+      return null
+    }
+  }
+
+  private async saveStoredFirstMessageRequest(state: PendingFirstMessage): Promise<void> {
+    if (!this.firstMessageRequestStore) return
+    try {
+      await this.firstMessageRequestStore.save(this.firstMessageRequestScope, state)
+    } catch {
+      // Storage is a recovery enhancement; an unavailable store must not block sending.
+    }
+  }
+
+  private async clearStoredFirstMessageRequest(): Promise<void> {
+    if (!this.firstMessageRequestStore) return
+    try {
+      await this.firstMessageRequestStore.clear(this.firstMessageRequestScope)
+    } catch {
+      // A stale recovery entry is still guarded by the request fingerprint and backend conflict.
+    }
+  }
+
+  private async refreshHistory(lifecycle: number): Promise<boolean> {
+    const sessionId = this.currentSessionId
+    if (!sessionId) return false
+    try {
+      const history = await this.transport.listMessages(sessionId)
+      if (!this.isCurrentLifecycle(lifecycle) || this.currentSessionId !== sessionId) return false
+      this.replaceHistory(history, sessionId)
+      return true
+    } catch {
+      if (this.isCurrentLifecycle(lifecycle)) {
+        this.emitError('HISTORY_LOAD_FAILED', '历史消息加载失败，实时连接仍会继续。', true)
+      }
+      return false
+    }
+  }
+
+  private replaceHistory(history: readonly AiEmployeeMessage[], sessionId: string): void {
+    const unique = new Map<string, AiEmployeeMessage>()
+    for (const candidate of history) {
+      const normalized = normalizeHistoryMessage(candidate, sessionId)
+      if (normalized) unique.set(normalized.id, normalized)
+    }
+    this.currentMessages = [...unique.values()]
+    this.seenMessageIds.clear()
+    for (const message of this.currentMessages) this.rememberMessageId(message.id)
+    this.emit('history', { sessionId, messages: this.messages })
+  }
+
+  private openSocket(isReconnect: boolean): void {
+    if (this.destroyed || !this.shouldReconnect) return
+    this.clearReconnectTimer()
+    this.closeCurrentSocket()
+    this.setState(isReconnect ? 'reconnecting' : 'connecting')
+
+    let socket: WebSocket
+    try {
+      socket = this.webSocketFactory(this.realtimeUrl)
+    } catch {
+      this.emitError('WEBSOCKET_UNAVAILABLE', '无法建立实时连接。', true)
+      this.scheduleReconnect()
+      return
+    }
+
+    const generation = ++this.socketGeneration
+    this.socket = socket
+    this.socketAuthenticationFailure = null
+    socket.onopen = () => void this.authenticateSocket(socket, generation)
+    socket.onmessage = (event) => void this.handleSocketData(event.data, socket, generation)
+    socket.onerror = () => {
+      if (!this.isCurrentSocket(socket, generation)) return
+      this.emitError('WEBSOCKET_ERROR', '实时连接发生异常。', true)
+    }
+    socket.onclose = (event) => this.handleSocketClose(socket, generation, event.code)
+  }
+
+  private async authenticateSocket(socket: WebSocket, generation: number): Promise<void> {
+    if (!this.isCurrentSocket(socket, generation)) return
+    this.setState('authenticating')
+    let accessToken = ''
+    try {
+      accessToken = (await this.transport.getAccessToken()).trim()
+    } catch {
+      // Authentication errors are deliberately not propagated because they may contain credentials.
+    }
+
+    if (!this.isCurrentSocket(socket, generation)) return
+    if (!accessToken) {
+      this.emitError('TOKEN_UNAVAILABLE', '无法获取实时连接凭证。', true)
+      socket.close()
+      return
+    }
+    socket.send(JSON.stringify(createAuthenticateFrame(accessToken)))
+    accessToken = ''
+  }
+
+  private async handleSocketData(
+    data: unknown,
+    socket: WebSocket,
+    generation: number,
+  ): Promise<void> {
+    if (!this.isCurrentSocket(socket, generation)) return
+    let raw = ''
+    if (typeof data === 'string') raw = data
+    else if (data instanceof Blob) raw = await data.text()
+    else if (data instanceof ArrayBuffer) raw = new TextDecoder().decode(data)
+    else {
+      this.emitError('PROTOCOL_ERROR', '收到无法识别的实时消息。', true)
+      return
+    }
+    if (!this.isCurrentSocket(socket, generation)) return
+    const message = parseJsonRecord(raw)
+    if (!message) {
+      this.emitError('PROTOCOL_ERROR', '收到无法解析的实时消息。', true)
+      return
+    }
+    this.handleServerMessage(message, socket, generation)
+  }
+
+  private handleServerMessage(message: JsonRecord, socket: WebSocket, generation: number): void {
+    const type = text(message.type)
+    if (type === 'realtime_ready') {
+      const channels = record(message.channels)
+      const aiChannel = record(channels.ai_employee)
+      if (aiChannel.available !== true) {
+        this.emitError('CHANNEL_UNAVAILABLE', '数字员工实时通道不可用。', false)
+        this.shouldReconnect = false
+        socket.close()
+        return
+      }
+      this.reconnectAttempt = 0
+      this.availabilityReconnectAttempt = 0
+      this.startHeartbeat(numberValue(message.heartbeat_interval_seconds), socket, generation)
+      if (this.currentSessionId) {
+        this.subscribeCurrentSession(this.replayHistoryOnNextSubscription, true)
+      } else {
+        this.setState('connected')
+      }
+      return
+    }
+
+    if (type === 'realtime_event' && message.channel === 'ai_employee') {
+      this.handleAiEmployeeEvent(message.event)
+      return
+    }
+
+    if (type === 'channel_error' && message.channel === 'ai_employee') {
+      this.handleChannelError(text(message.code))
+      return
+    }
+
+    if (type === 'authentication_error') {
+      const failure = authenticationFailure(text(message.code))
+      this.socketAuthenticationFailure = { generation, retryMode: failure.retryMode }
+      this.emitError(failure.code, failure.message, failure.retryMode !== 'never')
+      return
+    }
+
+    if (type === 'protocol_error') {
+      this.emitError('PROTOCOL_ERROR', '实时连接协议异常。', false)
+    }
+  }
+
+  private handleAiEmployeeEvent(rawEvent: unknown): void {
+    const event = parseAiEmployeeEvent(rawEvent)
+    if (event.kind === 'ignored' || event.sessionId !== this.currentSessionId) return
+    if (event.kind === 'session-title') {
+      this.emit('title', { sessionId: event.sessionId, title: event.title })
+      return
+    }
+
+    if (event.result.processing === true) this.assistantReceivedInCurrentTurn = false
+    if (event.result.processing !== undefined) this.setProcessing(event.result.processing)
+    for (const message of event.result.messages) {
+      if (message.role === 'user') this.assistantReceivedInCurrentTurn = false
+      if (message.role === 'user' && this.matchesPendingLocalMessage(message)) continue
+      this.appendMessage(message, 'realtime')
+      if (message.role === 'assistant') this.assistantReceivedInCurrentTurn = true
+    }
+    if (event.result.fallbackResult && !this.assistantReceivedInCurrentTurn) {
+      this.appendMessage(event.result.fallbackResult, 'realtime')
+    }
+  }
+
+  private subscribeCurrentSession(replayHistory: boolean, channelReady = false): void {
+    const sessionId = this.currentSessionId
+    const socket = this.socket
+    if (
+      !sessionId ||
+      !socket ||
+      socket.readyState !== 1 ||
+      (!channelReady && this.currentState !== 'connected')
+    )
+      return
+    this.setState('subscribing')
+    socket.send(JSON.stringify(createSubscriptionFrame(sessionId, 'subscribe', replayHistory)))
+    this.replayHistoryOnNextSubscription = false
+    this.setState('connected')
+    this.emit('ready', { sessionId })
+  }
+
+  private matchesPendingLocalMessage(message: AiEmployeeMessage): boolean {
+    const sentAt = this.pendingLocalMessages.get(message.content)
+    if (sentAt === undefined) return false
+    this.pendingLocalMessages.delete(message.content)
+    return Date.now() - sentAt <= LOCAL_MESSAGE_MATCH_WINDOW_MS
+  }
+
+  private appendMessage(message: AiEmployeeMessage, source: 'local' | 'realtime'): void {
+    if (this.seenMessageIds.has(message.id)) return
+    this.rememberMessageId(message.id)
+    this.currentMessages = [...this.currentMessages, message]
+    this.emit('message', { sessionId: message.sessionId, message, source })
+  }
+
+  private rememberMessageId(id: string): void {
+    this.seenMessageIds.add(id)
+    if (this.seenMessageIds.size <= MAX_SEEN_MESSAGE_IDS) return
+    const oldest = this.seenMessageIds.values().next().value
+    if (typeof oldest === 'string') this.seenMessageIds.delete(oldest)
+  }
+
+  private handleChannelError(code: string): void {
+    if (code === 'SESSION_NOT_FOUND') {
+      this.emitError('SESSION_NOT_FOUND', '会话不存在或当前用户无权访问。', false)
+    } else {
+      this.emitError('CHANNEL_UNAVAILABLE', '数字员工实时通道暂不可用。', true)
+    }
+    this.setProcessing(false)
+  }
+
+  private startHeartbeat(intervalSeconds: number, socket: WebSocket, generation: number): void {
+    this.clearHeartbeatTimer()
+    const requestedMs =
+      Number.isFinite(intervalSeconds) && intervalSeconds > 0 ? intervalSeconds * 1_000 : 25_000
+    const intervalMs = Math.max(this.minimumHeartbeatMs, requestedMs)
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.isCurrentSocket(socket, generation) || socket.readyState !== 1) return
+      socket.send(JSON.stringify(createPingFrame()))
+    }, intervalMs)
+  }
+
+  private handleSocketClose(socket: WebSocket, generation: number, code: number): void {
+    if (!this.isCurrentSocket(socket, generation)) return
+    this.socket = null
+    this.clearHeartbeatTimer()
+    const authenticationFailure =
+      this.socketAuthenticationFailure?.generation === generation
+        ? this.socketAuthenticationFailure
+        : null
+    this.socketAuthenticationFailure = null
+    if (!this.shouldReconnect || this.destroyed) {
+      if (!this.destroyed) this.setState('disconnected')
+      return
+    }
+
+    if (authenticationFailure?.retryMode === 'never') {
+      this.shouldReconnect = false
+      this.setState('disconnected')
+      return
+    }
+
+    if (code === 4400 || code === 4403) {
+      this.shouldReconnect = false
+      if (!authenticationFailure) {
+        const errorCode = code === 4403 ? 'AUTHENTICATION_FAILED' : 'PROTOCOL_ERROR'
+        const message = code === 4403 ? '当前身份无权建立实时连接。' : '实时连接协议不受支持。'
+        this.emitError(errorCode, message, false)
+      }
+      this.setState('disconnected')
+      return
+    }
+
+    if (authenticationFailure?.retryMode === 'availability' || code === 1013) {
+      if (!authenticationFailure) {
+        this.emitError('REALTIME_UNAVAILABLE', '实时鉴权服务暂不可用，正在重试。', true)
+      }
+      this.scheduleAvailabilityReconnect()
+      return
+    }
+
+    if (code === 4401) {
+      if (!authenticationFailure) {
+        this.emitError('AUTHENTICATION_FAILED', '连接凭证已失效，正在重新连接。', true)
+      }
+    }
+    this.scheduleReconnect()
+  }
+
+  private scheduleAvailabilityReconnect(): void {
+    if (this.availabilityReconnectAttempt >= MAX_AVAILABILITY_RECONNECTS) {
+      this.shouldReconnect = false
+      this.emitError('REALTIME_UNAVAILABLE', '实时鉴权服务持续不可用，请稍后重试。', false)
+      this.setState('disconnected')
+      return
+    }
+    this.availabilityReconnectAttempt += 1
+    this.scheduleReconnect()
+  }
+
+  private scheduleReconnect(): void {
+    if (this.destroyed || !this.shouldReconnect || this.reconnectTimer) return
+    this.setState('reconnecting')
+    const baseDelay = Math.min(
+      this.reconnectOptions.initialDelayMs * this.reconnectOptions.factor ** this.reconnectAttempt,
+      this.reconnectOptions.maximumDelayMs,
+    )
+    const jitterRange = baseDelay * this.reconnectOptions.jitter
+    const delay = Math.max(0, baseDelay - jitterRange + Math.random() * jitterRange * 2)
+    this.reconnectAttempt += 1
+    const lifecycle = this.lifecycleGeneration
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      void this.recoverAndReconnect(lifecycle)
+    }, delay)
+  }
+
+  private async recoverAndReconnect(lifecycle: number): Promise<void> {
+    if (!this.isCurrentLifecycle(lifecycle) || !this.shouldReconnect) return
+    const historyRecovered = await this.refreshHistory(lifecycle)
+    if (!this.isCurrentLifecycle(lifecycle) || !this.shouldReconnect) return
+    this.replayHistoryOnNextSubscription = !historyRecovered
+    this.openSocket(true)
+  }
+
+  private stopConnection(setDisconnectedState: boolean): void {
+    this.shouldReconnect = false
+    this.clearReconnectTimer()
+    this.clearHeartbeatTimer()
+    this.socketAuthenticationFailure = null
+    this.closeCurrentSocket()
+    this.setProcessing(false)
+    if (setDisconnectedState) this.setState('disconnected')
+  }
+
+  private closeCurrentSocket(): void {
+    const socket = this.socket
+    this.socket = null
+    this.socketGeneration += 1
+    this.socketAuthenticationFailure = null
+    if (socket && socket.readyState < 2) socket.close()
+  }
+
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
+    this.reconnectTimer = null
+  }
+
+  private clearHeartbeatTimer(): void {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
+    this.heartbeatTimer = null
+  }
+
+  private setState(next: AiEmployeeConnectionState): void {
+    if (this.currentState === next) return
+    const previous = this.currentState
+    this.currentState = next
+    this.emit('connection-state-change', { previous, current: next })
+  }
+
+  private setProcessing(processing: boolean): void {
+    if (this.processing === processing) return
+    this.processing = processing
+    this.emit('processing-state-change', { processing })
+  }
+
+  private emitError(
+    code: AiEmployeeErrorCode,
+    message: string,
+    recoverable: boolean,
+  ): AiEmployeeClientErrorDetail {
+    const detail = { code, message, recoverable }
+    this.emit('error', detail)
+    return detail
+  }
+
+  private emit<K extends keyof AiEmployeeClientEventMap>(
+    type: K,
+    detail: AiEmployeeClientEventMap[K],
+  ): void {
+    for (const listener of this.listeners.get(type) ?? []) listener(detail)
+  }
+
+  private isCurrentSocket(socket: WebSocket, generation: number): boolean {
+    return !this.destroyed && this.socket === socket && this.socketGeneration === generation
+  }
+
+  private isCurrentLifecycle(generation: number): boolean {
+    return !this.destroyed && this.lifecycleGeneration === generation
+  }
+
+  private assertUsable(): void {
+    if (this.destroyed) {
+      throw new AiEmployeeClientError('CLIENT_DESTROYED', '客户端已销毁。')
+    }
+  }
+}
+
+function validateRealtimeUrl(rawUrl: string): string {
+  let url: URL
+  try {
+    url = new URL(rawUrl)
+  } catch {
+    throw new AiEmployeeClientError('INVALID_CONFIGURATION', 'realtimeUrl 不是有效地址。')
+  }
+  if (!['ws:', 'wss:'].includes(url.protocol)) {
+    throw new AiEmployeeClientError('INVALID_CONFIGURATION', 'realtimeUrl 只允许 ws: 或 wss:。')
+  }
+  if (url.search || url.hash || url.username || url.password) {
+    throw new AiEmployeeClientError(
+      'INVALID_CONFIGURATION',
+      'realtimeUrl 不允许包含查询参数、片段或用户凭据。',
+    )
+  }
+  return url.toString()
+}
+
+function requiredText(value: string, field: string): string {
+  const normalized = typeof value === 'string' ? value.trim() : ''
+  if (!normalized) {
+    throw new AiEmployeeClientError('INVALID_CONFIGURATION', `${field} 不能为空。`)
+  }
+  return normalized
+}
+
+function normalizeSessionId(value: string | undefined): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+function normalizeFirstMessageOptions(options: AiEmployeeFirstMessageOptions): {
+  attachments: AiEmployeeFirstMessageRequest['attachments']
+  trustedContext: AiEmployeeFirstMessageRequest['trustedContext']
+} {
+  const attachments = (options.attachments ?? []).map((attachment) => {
+    const transactionId =
+      typeof attachment.transactionId === 'string' ? attachment.transactionId.trim() : ''
+    const fspath = typeof attachment.fspath === 'string' ? attachment.fspath.trim() : ''
+    if (
+      !transactionId ||
+      !fspath.startsWith('fs/') ||
+      fspath.includes('\\') ||
+      fspath.split('/').some((segment) => segment === '..')
+    ) {
+      throw new AiEmployeeClientError('SEND_FAILED', '首条消息附件引用无效。')
+    }
+    return { transactionId, fspath }
+  })
+  const trustedContext = options.trustedContext ?? null
+  if (
+    trustedContext !== null &&
+    (typeof trustedContext !== 'object' || Array.isArray(trustedContext))
+  ) {
+    throw new AiEmployeeClientError('SEND_FAILED', '首条消息上下文无效。')
+  }
+  return { attachments, trustedContext }
+}
+
+function firstMessageFingerprint(
+  content: string,
+  options: ReturnType<typeof normalizeFirstMessageOptions>,
+): string {
+  const serialized = stableFirstMessageString([
+    content,
+    options.attachments,
+    options.trustedContext,
+  ])
+  return `v1:${hashText(serialized)}:${hashText(`first-message:${serialized}`)}:${serialized.length}`
+}
+
+function stableFirstMessageString(value: unknown): string {
+  const seen = new WeakSet<object>()
+  const normalize = (candidate: unknown): unknown => {
+    if (candidate === null || typeof candidate !== 'object') return candidate
+    if (seen.has(candidate)) {
+      throw new AiEmployeeClientError('SEND_FAILED', '首条消息上下文无效。')
+    }
+    seen.add(candidate)
+    if (Array.isArray(candidate)) {
+      const result = candidate.map((item) => normalize(item))
+      seen.delete(candidate)
+      return result
+    }
+    const source = candidate as Record<string, unknown>
+    const result: Record<string, unknown> = {}
+    for (const key of Object.keys(source).sort()) result[key] = normalize(source[key])
+    seen.delete(candidate)
+    return result
+  }
+  return JSON.stringify(normalize(value))
+}
+
+function requiredRequestId(value: string): string {
+  const requestId = typeof value === 'string' ? value.trim() : ''
+  if (
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(requestId)
+  ) {
+    throw new AiEmployeeClientError('INVALID_CONFIGURATION', 'requestIdFactory 必须返回 UUID。')
+  }
+  return requestId
+}
+
+function createRequestId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID()
+  }
+  if (typeof crypto === 'undefined' || typeof crypto.getRandomValues !== 'function') {
+    throw new AiEmployeeClientError('INVALID_CONFIGURATION', '当前环境无法安全生成 request_id。')
+  }
+  const bytes = crypto.getRandomValues(new Uint8Array(16))
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80
+  const value = [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+  return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`
+}
+
+function normalizeFirstMessageResult(
+  value: AiEmployeeFirstMessageResult,
+  expectedAeCode: string,
+  expectedAgentCode: string,
+): AiEmployeeFirstMessageResult {
+  if (!value || typeof value !== 'object') {
+    throw new AiEmployeeClientError('SEND_FAILED', '首条消息受理响应无效。')
+  }
+  const sessionId = requiredFirstMessageResultText(value.sessionId)
+  const messageId = requiredFirstMessageResultText(value.messageId)
+  const executionId = requiredFirstMessageResultText(value.executionId)
+  const aeCode = requiredFirstMessageResultText(value.aeCode)
+  const agentCode = requiredFirstMessageResultText(value.agentCode)
+  const conversationType = requiredFirstMessageResultText(value.conversationType)
+  if (aeCode !== expectedAeCode || agentCode !== expectedAgentCode) {
+    throw new AiEmployeeClientError('SEND_FAILED', '首条消息受理响应与当前数字员工不匹配。')
+  }
+  if (value.status !== 'running' && value.status !== 'queued') {
+    throw new AiEmployeeClientError('SEND_FAILED', '首条消息受理状态无效。')
+  }
+  const startedAt = requiredIsoDate(value.startedAt, 'transport startedAt')
+  const result: AiEmployeeFirstMessageResult = {
+    sessionId,
+    messageId,
+    executionId,
+    status: value.status,
+    startedAt,
+    aeCode,
+    agentCode,
+    conversationType,
+  }
+  if (typeof value.title === 'string' && value.title.trim()) result.title = value.title.trim()
+  if (value.createdAt) result.createdAt = requiredIsoDate(value.createdAt, 'transport createdAt')
+  return result
+}
+
+function requiredIsoDate(value: string, field: string): string {
+  const normalized = requiredFirstMessageResultText(value)
+  if (!Number.isFinite(Date.parse(normalized))) {
+    throw new AiEmployeeClientError('SEND_FAILED', `${field} 不是有效时间。`)
+  }
+  return normalized
+}
+
+function requiredFirstMessageResultText(value: unknown): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new AiEmployeeClientError('SEND_FAILED', '首条消息受理响应无效。')
+  }
+  return value.trim()
+}
+
+function authenticationFailure(code: string): {
+  code: AiEmployeeErrorCode
+  message: string
+  retryMode: AuthenticationRetryMode
+} {
+  if (code === 'UNAUTHORIZED') {
+    return {
+      code: 'AUTHENTICATION_FAILED',
+      message: '连接凭证已失效，正在重新连接。',
+      retryMode: 'token',
+    }
+  }
+  if (code === 'ORGANIZATION_CONTEXT_REQUIRED') {
+    return {
+      code: 'ORGANIZATION_CONTEXT_REQUIRED',
+      message: '请选择企业/团队后再开始咨询。',
+      retryMode: 'never',
+    }
+  }
+  if (code === 'INVALID_ARGUMENT') {
+    return {
+      code: 'PROTOCOL_ERROR',
+      message: '实时连接协议不受支持。',
+      retryMode: 'never',
+    }
+  }
+  if (isRealtimeAvailabilityFailure(code)) {
+    return {
+      code: 'REALTIME_UNAVAILABLE',
+      message: '实时鉴权服务暂不可用，正在重试。',
+      retryMode: 'availability',
+    }
+  }
+  if (code === 'AI_EMPLOYEE_NOT_AVAILABLE' || code === 'APPLICATION_NOT_SUPPORTED') {
+    return {
+      code: 'CHANNEL_UNAVAILABLE',
+      message: '当前数字员工暂不可用。',
+      retryMode: 'never',
+    }
+  }
+  if (code === 'ACCESS_DENIED') {
+    return {
+      code: 'AUTHENTICATION_FAILED',
+      message: '当前身份无权建立实时连接。',
+      retryMode: 'never',
+    }
+  }
+  return {
+    code: 'AUTHENTICATION_FAILED',
+    message: '实时连接认证失败。',
+    retryMode: 'never',
+  }
+}
+
+function transportErrorCode(error: unknown): AiEmployeeTransportErrorCode | null {
+  if (error instanceof AiEmployeeTransportError) return error.code
+  if (!error || typeof error !== 'object' || !('code' in error)) return null
+  switch (error.code) {
+    case 'UNAUTHORIZED':
+    case 'ACCESS_DENIED':
+    case 'AI_EMPLOYEE_NOT_AVAILABLE':
+    case 'APPLICATION_NOT_SUPPORTED':
+    case 'ORGANIZATION_CONTEXT_REQUIRED':
+    case 'INVALID_ARGUMENT':
+    case 'IDEMPOTENCY_CONFLICT':
+    case 'REALTIME_UNAVAILABLE':
+    case 'TOO_MANY_REQUESTS':
+      return error.code
+    default:
+      return null
+  }
+}
+
+function createSessionFirstMessageRequestStore(): AiEmployeeFirstMessageRequestStore | null {
+  try {
+    if (typeof sessionStorage === 'undefined') return null
+  } catch {
+    return null
+  }
+  const key = (scope: string) => `${FIRST_MESSAGE_STORAGE_PREFIX}:${hashText(scope)}`
+  return {
+    load(scope) {
+      const raw = sessionStorage.getItem(key(scope))
+      if (!raw) return null
+      const parsed: unknown = JSON.parse(raw)
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+      const state = parsed as Partial<AiEmployeeFirstMessageRequestState>
+      return typeof state.fingerprint === 'string' && typeof state.requestId === 'string'
+        ? { fingerprint: state.fingerprint, requestId: state.requestId }
+        : null
+    },
+    save(scope, state) {
+      sessionStorage.setItem(
+        key(scope),
+        JSON.stringify({ fingerprint: state.fingerprint, requestId: state.requestId }),
+      )
+    },
+    clear(scope) {
+      sessionStorage.removeItem(key(scope))
+    },
+  }
+}
+
+function isRealtimeAvailabilityFailure(code: string): boolean {
+  return (
+    code === 'REALTIME_UNAVAILABLE' || code === 'KANBAN_AUTH_FAILED' || code.startsWith('SERVICE_')
+  )
+}
+
+function normalizeReconnectOptions(
+  options: AiEmployeeClientOptions['reconnect'],
+): AiEmployeeReconnectOptions {
+  return {
+    initialDelayMs: positiveNumber(options?.initialDelayMs, DEFAULT_RECONNECT.initialDelayMs),
+    maximumDelayMs: positiveNumber(options?.maximumDelayMs, DEFAULT_RECONNECT.maximumDelayMs),
+    factor: Math.max(1, positiveNumber(options?.factor, DEFAULT_RECONNECT.factor)),
+    jitter: Math.min(1, Math.max(0, options?.jitter ?? DEFAULT_RECONNECT.jitter)),
+  }
+}
+
+function positiveNumber(value: number | undefined, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback
+}
+
+function normalizeHistoryMessage(
+  candidate: AiEmployeeMessage,
+  expectedSessionId: string,
+): AiEmployeeMessage | null {
+  if (!candidate || typeof candidate !== 'object') return null
+  const id = text(candidate.id).trim()
+  const content = text(candidate.content).trim()
+  const role = candidate.role
+  if (!id || !content || !['user', 'assistant', 'system', 'error'].includes(role)) return null
+  return {
+    id,
+    sessionId: expectedSessionId,
+    role,
+    content: role === 'error' ? '消息处理出现异常，请稍后重试。' : content,
+    createdAt: text(candidate.createdAt) || new Date().toISOString(),
+  }
+}
+
+function text(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function record(value: unknown): JsonRecord {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as JsonRecord)
+    : {}
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === 'number' ? value : Number.NaN
+}