@xmov/avatar 2.1.0 → 2.1.1

package/src/agent/index.ts

@@ -1,1393 +0,0 @@
-import XmovAvatar from "../index";
-import type { ISessionResponse } from "../modules/ResourceManager";
-import type { IAudioPlaybackData, IAvatarOptions, IInitParams } from "../types";
-import { AgentE2EClient } from "./e2e-client";
-import { MicrophoneController } from "./microphone";
-import { logAudioChunkContent } from "./audio-debug";
-import { AgentAudioUplink } from "./audio-uplink";
-import type { AgentAudioBlock } from "./audio-uplink";
-import { DEFAULT_AGENT_AUDIO } from "./types";
-import type {
-  AgentASRResult,
-  AgentASRStartOptions,
-  AgentASRState,
-  AgentClientMessage,
-  AgentConversationEvent,
-  AgentError,
-  AgentErrorDomain,
-  AgentLLMResponse,
-  AgentReconnectOptions,
-  AgentSemanticJudgeResult,
-  AgentServerEvent,
-  AgentSessionInfo,
-  AgentState,
-  XingyunAvatarAgentCallbacks,
-  XingyunAvatarAgentInitParams,
-  XingyunAvatarAgentOptions,
-} from "./types";
-
-interface AgentRuntimeOptions {
-  e2eServer?: string;
-  authToken?: string;
-  audio?: XingyunAvatarAgentOptions["audio"];
-  requestedEnableAec?: boolean;
-  callbacks?: XingyunAvatarAgentCallbacks;
-  webSocketCtor?: typeof WebSocket;
-  debugAudioChunks?: boolean;
-}
-
-type AgentParentOptions = IAvatarOptions & {
-  sessionRequestData: Record<string, unknown>;
-};
-
-interface InitialSessionAttempt {
-  sessionInfo: ISessionResponse;
-  e2ePromise: Promise<void>;
-  ttsaReadyPromise: Promise<void>;
-  resolveTtsaReady: () => void;
-}
-
-function hasSerializableConfig(config: Record<string, unknown> | undefined) {
-  if (config === undefined) {
-    return false;
-  }
-  const serializedConfig = JSON.stringify(config);
-  return serializedConfig !== undefined && serializedConfig !== "{}";
-}
-
-const CLOSE_CODE_MESSAGES: Record<number, string> = {
-  1006: "E2E WebSocket 异常断开：未收到 Close frame，请检查 E2EMPServer 日志或中间网络",
-  4000: "E2E WebSocket 路径未知",
-  4001: "E2E Token 无效",
-  4002: "E2E Session 不存在",
-  4009: "E2E 配额超限",
-  4010: "E2E 服务端主动断开",
-};
-
-const RETRYABLE_CLOSE_CODES = new Set([1001, 1006, 1011, 1012, 1013, 1014]);
-const DEFAULT_RECONNECT_OPTIONS: Required<AgentReconnectOptions> = {
-  enabled: true,
-  maxAttempts: 6,
-  initialDelayMs: 500,
-  maxDelayMs: 8000,
-};
-
-function validateAgentConfigSource(
-  label: "ASR" | "TTS" | "Brain",
-  id: number | undefined,
-  config: Record<string, unknown> | undefined,
-) {
-  if (config !== undefined && (!config || Array.isArray(config) || typeof config !== "object")) {
-    throw new Error(`Agent ${label} JSON Config 必须是对象`);
-  }
-  if (id !== undefined && hasSerializableConfig(config)) {
-    throw new Error(`Agent ${label} 配置不能同时提供 ID 和 JSON Config`);
-  }
-}
-
-function normalizeBrainConfig(config: XingyunAvatarAgentOptions["brain_config"]) {
-  if (!config || !hasSerializableConfig(config)) {
-    return undefined;
-  }
-  const extraBody = config.extra_body;
-  if (extraBody !== undefined && (!extraBody || Array.isArray(extraBody) || typeof extraBody !== "object")) {
-    throw new Error("Agent Brain extra_body 必须是 JSON 对象");
-  }
-  return {
-    ...config,
-  };
-}
-
-function validateAgentObjectConfig(
-  label: "features" | "extras",
-  config: Record<string, unknown> | undefined,
-) {
-  if (config !== undefined && (!config || Array.isArray(config) || typeof config !== "object")) {
-    throw new Error(`Agent ${label} 必须是对象`);
-  }
-}
-
-export default class XingyunAvatarAgent extends XmovAvatar {
-  private e2eClient: AgentE2EClient | null = null;
-  private microphone: MicrophoneController | null = null;
-  private stopASRPromise: Promise<void> | null = null;
-  private initializationPromise: Promise<ISessionResponse | null | undefined> | null = null;
-  private rejectInitialization: ((error: Error) => void) | null = null;
-  private initialSessionAttempt: InitialSessionAttempt | null = null;
-  private initialSessionGeneration = 0;
-  private readonly initialTtsaReadySessionIds = new Set<string>();
-  private initialTtsaReadyBeforeSession = false;
-  private asrStartGeneration = 0;
-  private agentState: AgentState = "idle";
-  private asrState: AgentASRState = "idle";
-  private agentDestroyed = false;
-  private agentDestroying = false;
-  private suppressNextVoiceEnd = false;
-  private audioInputEnabled: boolean;
-  private farendAudioEnabled = false;
-  private readonly audioUplink: AgentAudioUplink;
-  private originalOnAudioPlaybackData?: IAvatarOptions["onAudioPlaybackData"];
-  private playbackDataHandler?: IAvatarOptions["onAudioPlaybackData"];
-  private readonly agentOptions: AgentRuntimeOptions;
-  private readonly reconnectOptions: Required<AgentReconnectOptions>;
-  private reconnectTimer: number | null = null;
-  private reconnectAttempt = 0;
-  private reconnectInFlight = false;
-  private sessionReloadFallback = false;
-  private waitingForTtsaReload = false;
-  private stateBeforeReconnect: AgentState = "ready";
-  private reportingInitializationFailure = false;
-  private readonly handleOnlineForReconnect = () => {
-    if (this.agentState !== "reconnecting" || this.reconnectInFlight || this.sessionReloadFallback) {
-      return;
-    }
-    this.clearReconnectTimer();
-    this.scheduleE2EReconnect(true);
-  };
-
-  constructor(options: XingyunAvatarAgentOptions) {
-    validateAgentConfigSource("ASR", options.asr_id, options.asr_config);
-    validateAgentConfigSource("TTS", undefined, options.tts_config);
-    validateAgentConfigSource("Brain", options.llm_id, options.brain_config);
-    validateAgentObjectConfig("features", options.features);
-    validateAgentObjectConfig("extras", options.extras);
-    const {
-      e2eServer,
-      authToken,
-      audio,
-      reconnect,
-      agentCallbacks,
-      webSocketCtor,
-      asr_id: asrId,
-      asr_config: asrConfig,
-      tts_config: ttsConfig,
-      features,
-      extras,
-      llm_id: llmId,
-      brain_config: brainConfig,
-      session_speak_req_id: configuredSessionSpeakReqId,
-      ...avatarOptions
-    } = options;
-    const originalOnMessage = avatarOptions.onMessage;
-    const originalOnRenderChange = avatarOptions.onRenderChange;
-    const originalOnNetworkInfo = avatarOptions.onNetworkInfo;
-    const originalOnSpeakStateChange = avatarOptions.onSpeakStateChange;
-    const originalOnVoiceStateChange = avatarOptions.onVoiceStateChange;
-    const originalOnAudioPlaybackData = avatarOptions.onAudioPlaybackData;
-    const playbackDataHandler = (data: IAudioPlaybackData) => {
-      instance?.forwardFarendAudio(data);
-      originalOnAudioPlaybackData?.(data);
-    };
-    const sessionSpeakReqId = configuredSessionSpeakReqId ?? 1;
-    const normalizedBrainConfig = normalizeBrainConfig(brainConfig);
-    let instance: XingyunAvatarAgent | undefined;
-
-    const parentOptions: AgentParentOptions = {
-      ...avatarOptions,
-      session_speak_req_id: sessionSpeakReqId,
-      sessionRequestData: {
-        ...(asrId !== undefined ? { asr_id: asrId } : {}),
-        ...(hasSerializableConfig(asrConfig) ? { asr_config: asrConfig } : {}),
-        ...(hasSerializableConfig(ttsConfig) ? { tts_config: ttsConfig } : {}),
-        ...(hasSerializableConfig(features) ? { features } : {}),
-        ...(hasSerializableConfig(extras) ? { extras } : {}),
-        ...(llmId !== undefined ? { llm_id: llmId } : {}),
-        ...(normalizedBrainConfig !== undefined
-          ? { brain_config: normalizedBrainConfig }
-          : {}),
-        session_speak_req_id: sessionSpeakReqId,
-      },
-      enableClientInterrupt: avatarOptions.enableClientInterrupt ?? true,
-      onMessage: (error) => {
-        originalOnMessage(error);
-        if (!instance?.reportingInitializationFailure) {
-          instance?.emitError("sdk", String(error.code || "AVATAR_ERROR"), error.message || "Avatar SDK 错误", true, error);
-        }
-      },
-      onRenderChange: (state) => {
-        originalOnRenderChange?.(state);
-        instance?.safeEmit(() => agentCallbacks?.onRenderChange?.(state));
-      },
-      onNetworkInfo: (info) => {
-        originalOnNetworkInfo?.(info);
-        instance?.safeEmit(() => agentCallbacks?.onNetworkInfo?.(info));
-      },
-      onSpeakStateChange: (state, clientSpeakId) => {
-        originalOnSpeakStateChange?.(state, clientSpeakId);
-        instance?.safeEmit(() => agentCallbacks?.onSpeakStateChange?.({ state, clientSpeakId }));
-        if (["speak_start", "start", "started"].includes(state)) {
-          instance?.emitConversation({ state: "speaking" });
-        }
-        if (["speak_end", "end", "ended", "completed", "finish", "finished"].includes(state)) {
-          instance?.emitConversation({ state: "completed" });
-        }
-      },
-      onVoiceStateChange: (state, duration, clientSpeakId) => {
-        if (state === "end") {
-          instance?.forwardVoiceEnd();
-        }
-        originalOnVoiceStateChange?.(state, duration, clientSpeakId);
-      },
-      ...(originalOnAudioPlaybackData
-        ? {
-            onAudioPlaybackData: playbackDataHandler,
-          }
-        : {}),
-    };
-
-    super(parentOptions);
-    instance = this;
-    this.agentOptions = {
-      e2eServer,
-      authToken,
-      audio,
-      requestedEnableAec: typeof features?.speech_frontend?.enable_aec === "boolean"
-        ? features.speech_frontend.enable_aec
-        : undefined,
-      callbacks: agentCallbacks,
-      webSocketCtor,
-      debugAudioChunks: Boolean(avatarOptions.enableDebugger),
-    };
-    this.audioInputEnabled = audio?.inputEnabled ?? false;
-    this.originalOnAudioPlaybackData = originalOnAudioPlaybackData;
-    this.playbackDataHandler = playbackDataHandler;
-    this.reconnectOptions = this.normalizeReconnectOptions(reconnect);
-    this.audioUplink = new AgentAudioUplink({
-      sendBinary: (frame) => this.e2eClient?.sendBinary(frame),
-      onError: (error) => this.handleAudioUplinkError(error),
-    });
-  }
-
-  getAgentState() {
-    return this.agentState;
-  }
-
-  // Kept for callers that adopted the first Agent preview.
-  getState() {
-    return this.getAgentState();
-  }
-
-  getASRState() {
-    return this.asrState;
-  }
-
-  override init(params: XingyunAvatarAgentInitParams = {}): Promise<ISessionResponse | null | undefined> {
-    if (this.initializationPromise) {
-      return this.initializationPromise;
-    }
-    const initializationPromise = this.initialize(params).finally(() => {
-      if (this.initializationPromise === initializationPromise) {
-        this.initializationPromise = null;
-      }
-    });
-    this.initializationPromise = initializationPromise;
-    return initializationPromise;
-  }
-
-  private async initialize(params: XingyunAvatarAgentInitParams): Promise<ISessionResponse | null | undefined> {
-    this.assertNotDestroyed();
-    this.setAgentState("initializing");
-    const initializationAbortPromise = new Promise<never>((_, reject) => {
-      this.rejectInitialization = reject;
-    });
-    void initializationAbortPromise.catch(() => {});
-
-    try {
-      const initParams: IInitParams = {
-        ...params,
-        onDownloadProgress: params.onDownloadProgress || (() => {}),
-      };
-      const sessionInfo = await super.init(initParams);
-      this.assertNotDestroyed();
-      if (!sessionInfo) {
-        throw new Error("XmovAvatar 初始化未返回 sessionInfo");
-      }
-      this.applySessionFeatures(sessionInfo);
-
-      this.assertNotDestroyed();
-      this.beginInitialSession(sessionInfo);
-      while (true) {
-        const attempt = this.initialSessionAttempt;
-        if (!attempt) {
-          throw new Error("Agent 初始化缺少会话连接任务");
-        }
-        await Promise.race([
-          Promise.all([attempt.e2ePromise, attempt.ttsaReadyPromise]),
-          initializationAbortPromise,
-        ]);
-        if (attempt === this.initialSessionAttempt) {
-          break;
-        }
-      }
-      this.assertNotDestroyed();
-      this.assertE2EOpen();
-      const initializedSessionInfo = this.initialSessionAttempt?.sessionInfo || sessionInfo;
-      this.setAgentState("ready");
-      this.start();
-      return initializedSessionInfo;
-    } catch (error) {
-      if (!this.agentDestroyed && !this.agentDestroying) {
-        this.e2eClient?.disconnect(1000, "agent_init_failed");
-        this.e2eClient = null;
-        await this.cleanupBeforeInitComplete("agent_init_failed");
-        try {
-          this.setAgentState("failed");
-        } catch {
-          // Initialization failure must preserve the internal terminal state.
-        }
-        this.reportingInitializationFailure = true;
-        try {
-          this.reportInitializationFailure("Agent 初始化失败", error);
-        } catch {
-          // A legacy callback must not replace the original initialization error.
-        } finally {
-          this.reportingInitializationFailure = false;
-        }
-        try {
-          this.emitError("sdk", "AGENT_INIT_FAILED", "Agent 初始化失败", true, error);
-        } catch {
-          // A business callback must not interrupt initialization cleanup.
-        }
-        this.agentDestroyed = true;
-      }
-      throw error;
-    } finally {
-      this.rejectInitialization = null;
-      this.initialSessionGeneration += 1;
-      this.initialSessionAttempt?.resolveTtsaReady();
-      this.initialSessionAttempt = null;
-      this.initialTtsaReadySessionIds.clear();
-      this.initialTtsaReadyBeforeSession = false;
-    }
-  }
-
-  private beginInitialSession(sessionInfo: ISessionResponse) {
-    const previousAttempt = this.initialSessionAttempt;
-    const generation = ++this.initialSessionGeneration;
-    previousAttempt?.resolveTtsaReady();
-
-    let resolveTtsaReady = () => {};
-    const ttsaReadyPromise = new Promise<void>((resolve) => {
-      resolveTtsaReady = resolve;
-    });
-    const e2ePromise = this.replaceE2EConnection(sessionInfo.e2e_resp).catch((error) => {
-      if (generation !== this.initialSessionGeneration) {
-        return;
-      }
-      throw error;
-    });
-    const attempt: InitialSessionAttempt = {
-      sessionInfo,
-      e2ePromise,
-      ttsaReadyPromise,
-      resolveTtsaReady,
-    };
-    this.initialSessionAttempt = attempt;
-
-    if (this.initialTtsaReadySessionIds.delete(sessionInfo.session_id)) {
-      attempt.resolveTtsaReady();
-    } else if (!previousAttempt && this.initialTtsaReadyBeforeSession) {
-      this.initialTtsaReadyBeforeSession = false;
-      attempt.resolveTtsaReady();
-    }
-
-    void e2ePromise.catch(() => {});
-    return e2ePromise;
-  }
-
-  override start() {
-    if (this.agentState === "initializing") {
-      return;
-    }
-    if (this.agentState === "running") {
-      return;
-    }
-    if (this.agentState === "reconnecting") {
-      if (
-        this.waitingForTtsaReload
-        && this.e2eClient?.isOpen
-      ) {
-        if (this.stateBeforeReconnect === "running") {
-          super.start();
-        }
-        this.finishReconnect();
-      }
-      return;
-    }
-    this.assertE2EOpen();
-    super.start();
-    this.setAgentState("running");
-  }
-
-  protected override onTtsaReady(sessionInfo?: ISessionResponse) {
-    if (this.rejectInitialization) {
-      const attempt = this.initialSessionAttempt;
-      const sessionId = sessionInfo?.session_id;
-      if (attempt && (!sessionId || attempt.sessionInfo.session_id === sessionId)) {
-        attempt.resolveTtsaReady();
-      } else if (sessionId) {
-        this.initialTtsaReadySessionIds.add(sessionId);
-      } else {
-        this.initialTtsaReadyBeforeSession = true;
-      }
-      return;
-    }
-    if (this.agentState === "reconnecting") {
-      this.start();
-      return;
-    }
-    if (this.agentState === "running") {
-      super.start();
-    }
-  }
-
-  private abortInitialization(error: Error) {
-    this.rejectInitialization?.(error);
-  }
-
-  override async stop() {
-    if (this.agentDestroyed) {
-      return;
-    }
-    const wasReconnecting = this.agentState === "reconnecting";
-    if (wasReconnecting) {
-      this.stateBeforeReconnect = "stopped";
-    }
-    await this.stopASR();
-    await super.stop();
-    if (!wasReconnecting) {
-      this.setAgentState("stopped");
-    }
-  }
-
-  override speak(...args: Parameters<XmovAvatar["speak"]>) {
-    if (args[2] ?? true) {
-      this.suppressNextVoiceEnd = true;
-    }
-    return super.speak(...args);
-  }
-
-  override async destroy(reason = "user") {
-    if (this.agentDestroyed) {
-      if (this.agentState !== "destroyed") {
-        this.setAgentState("destroyed");
-      }
-      return;
-    }
-    if (this.agentDestroying) {
-      return;
-    }
-    this.agentDestroying = true;
-    this.abortInitialization(new Error("Agent 初始化已取消"));
-    this.cancelReconnect();
-    this.cancelSessionRestart();
-    try {
-      await this.stopASR();
-    } catch (error) {
-      this.emitError("sdk", "AGENT_ASR_STOP_FAILED", "Agent 销毁时停止 ASR 失败", false, error);
-    }
-
-    this.e2eClient?.disconnect(1000, reason);
-    this.e2eClient = null;
-    this.audioUplink.reset();
-
-    try {
-      await super.destroy(reason);
-    } finally {
-      this.agentDestroyed = true;
-      this.agentDestroying = false;
-      this.setAgentState("destroyed");
-    }
-  }
-
-  async ask(text: string): Promise<void> {
-    this.assertRunning();
-    this.suppressNextVoiceEnd = false;
-    this.emitConversation({ state: "asking", text });
-    this.sendControl({
-      type: "ask",
-      message: { text },
-    });
-  }
-
-  async speakByE2E(text: string): Promise<void> {
-    this.assertRunning();
-    this.suppressNextVoiceEnd = false;
-    this.emitConversation({ state: "speaking-directly", text });
-    this.sendControl({
-      type: "speak",
-      message: {
-        text,
-        is_start: true,
-        is_end: true,
-      },
-    });
-  }
-
-  async startASR(options: AgentASRStartOptions = {}): Promise<void> {
-    this.assertRunning();
-    this.suppressNextVoiceEnd = false;
-    if (this.stopASRPromise) {
-      await this.stopASRPromise;
-      this.assertRunning();
-    }
-    if (this.microphone?.isRecording) {
-      return;
-    }
-    this.assertAudioChunkDuration();
-    const inputStream = options.inputStream
-      ? this.cloneASRInputStream(options.inputStream)
-      : undefined;
-
-    const asrStartGeneration = ++this.asrStartGeneration;
-    const restoreDisabledStateOnFailure = !this.audioInputEnabled;
-    const microphone = new MicrophoneController({
-      audio: this.agentOptions.audio,
-      debugAudioChunks: this.agentOptions.debugAudioChunks,
-      inputStream,
-      usePcmWebCodecs: this.farendAudioEnabled,
-      onFrame: (data, timestamp) => {
-        if (this.agentState === "running" && this.e2eClient?.isOpen) {
-          try {
-            this.sendAudioFrame({
-              data,
-              timestamp: timestamp ?? Date.now() - (
-                this.agentOptions.audio?.chunkMs || DEFAULT_AGENT_AUDIO.chunkMs
-              ),
-            });
-          } catch {
-            // A close can race the isOpen check. Do not let the recorder
-            // callback escape, and do not send control events on a broken stream.
-            this.stopASRAfterSocketClose();
-          }
-        }
-      },
-      onError: (error) => this.handleMicrophoneError(microphone, error),
-    });
-    this.microphone = microphone;
-
-    try {
-      this.audioUplink.startInput();
-      if (restoreDisabledStateOnFailure) {
-        this.enableAudioInput();
-      }
-      this.emitConversation({ state: "asking" });
-      this.assertASRStartActive(asrStartGeneration);
-      this.setASRState("requesting-permission");
-      this.assertASRStartActive(asrStartGeneration);
-      this.setASRState("starting");
-      this.assertASRStartActive(asrStartGeneration);
-      await microphone.start();
-      this.assertRunning();
-      if (this.farendAudioEnabled) {
-        this.restartAudioPlaybackCapture();
-      }
-      this.setASRState("listening");
-    } catch (error) {
-      await microphone.stop();
-      const isCancelled = (error as { agentCode?: string })?.agentCode === "AUDIO_FIXED_TRACK_CANCELLED";
-      const isCurrentStart = asrStartGeneration === this.asrStartGeneration;
-      const connectionUsable = !this.agentDestroyed
-        && !this.agentDestroying
-        && this.agentState === "running"
-        && Boolean(this.e2eClient?.isOpen);
-      if (this.microphone === microphone) {
-        this.microphone = null;
-      }
-      if (isCurrentStart && !isCancelled && restoreDisabledStateOnFailure && this.e2eClient?.isOpen) {
-        try {
-          this.disableAudioInput();
-        } catch {
-          // sendControl has already reported the transport failure.
-        }
-      }
-      if (isCurrentStart && !this.agentDestroyed && !this.agentDestroying) {
-        if (isCancelled && connectionUsable) {
-          this.setASRState("idle");
-        } else if (!isCancelled) {
-          this.setASRState("failed");
-        }
-      }
-      if (isCancelled && !connectionUsable) {
-        this.assertRunning();
-      }
-      throw error;
-    }
-  }
-
-  private cloneASRInputStream(inputStream: MediaStream) {
-    const track = inputStream.getAudioTracks().find((candidate) => candidate.readyState !== "ended");
-    if (!track) {
-      throw new Error("ASR 输入流不包含有效音频轨道");
-    }
-    return new MediaStream([track.clone()]);
-  }
-
-  private assertASRStartActive(asrStartGeneration: number) {
-    if (asrStartGeneration === this.asrStartGeneration) {
-      return;
-    }
-    const error = new Error("麦克风启动已取消") as Error & {
-      agentCode?: string;
-      retryable?: boolean;
-    };
-    error.name = "AbortError";
-    error.agentCode = "AUDIO_FIXED_TRACK_CANCELLED";
-    error.retryable = true;
-    throw error;
-  }
-
-  stopASR(): Promise<void> {
-    this.asrStartGeneration += 1;
-    if (this.stopASRPromise) {
-      return this.stopASRPromise;
-    }
-
-    const microphone = this.microphone;
-    if (!microphone?.isRecording) {
-      if (this.e2eClient?.isOpen) {
-        this.disableAudioInput();
-      }
-      return Promise.resolve();
-    }
-
-    this.microphone = null;
-    this.stopASRPromise = this.finishStopASR(microphone).finally(() => {
-      this.stopASRPromise = null;
-    });
-    return this.stopASRPromise;
-  }
-
-  private async finishStopASR(microphone: MicrophoneController, notifyServer = true) {
-    this.setASRState("stopping");
-    await microphone.stop();
-    await this.audioUplink.drain();
-    if (notifyServer) {
-      this.disableAudioInput();
-      this.setASRState("idle");
-    } else {
-      this.setASRState("failed");
-    }
-  }
-
-  async interruptConversation(reason = "user") {
-    if (this.agentDestroyed) {
-      return;
-    }
-
-    void reason;
-
-    this.sendControl({
-      type: "interrupt",
-    });
-    super.interrupt("speak");
-    this.emitConversation({ state: "interrupted" });
-  }
-
-  protected override async onSessionReloaded(sessionInfo: ISessionResponse): Promise<void> {
-    if (this.agentDestroyed || this.agentDestroying) {
-      return;
-    }
-    if (this.initializationPromise && this.agentState === "initializing") {
-      this.applySessionFeatures(sessionInfo);
-      await this.beginInitialSession(sessionInfo);
-      return;
-    }
-    if (this.agentState !== "reconnecting") {
-      this.stateBeforeReconnect = this.readRestorableState();
-      this.setAgentState("reconnecting");
-    }
-    this.clearReconnectTimer();
-    this.sessionReloadFallback = true;
-    this.applySessionFeatures(sessionInfo);
-    await this.replaceE2EConnection(sessionInfo.e2e_resp);
-    this.waitingForTtsaReload = true;
-    this.sessionReloadFallback = false;
-  }
-
-  protected override onSessionReloadExhausted(error?: unknown): void {
-    if (this.rejectInitialization) {
-      this.abortInitialization(
-        error instanceof Error ? error : new Error("Agent 初始化期间 TTSA Session 恢复失败"),
-      );
-      return;
-    }
-    if (this.agentState === "reconnecting") {
-      this.failReconnect(error);
-    }
-  }
-
-  override reloadSuccess() {
-    super.reloadSuccess();
-  }
-
-  private async replaceE2EConnection(sessionInfo?: AgentSessionInfo) {
-    const { wsUrl, token } = this.resolveE2EConnection(sessionInfo);
-    const previousClient = this.e2eClient;
-    this.audioUplink.reset();
-    let client: AgentE2EClient;
-    client = new AgentE2EClient({
-      wsUrl,
-      token,
-      audioInputEnabled: this.audioInputEnabled,
-      WebSocketCtor: this.agentOptions.webSocketCtor,
-      onStateChange: (state) => {
-        if (this.e2eClient === client) {
-          if (state === "open") {
-            this.audioUplink.reset(Date.now());
-          }
-          this.safeEmit(() => this.agentOptions.callbacks?.onSocketStateChange?.(state));
-        }
-      },
-      onEvent: (event) => {
-        if (this.e2eClient === client) {
-          this.handleServerEvent(event);
-        }
-      },
-      onError: (error) => {
-        if (
-          this.e2eClient === client
-          && this.agentState !== "initializing"
-          && this.agentState !== "reconnecting"
-        ) {
-          this.emitError("network", "E2E_SOCKET_ERROR", error.message, true, error);
-        }
-      },
-      onClose: (event) => {
-        if (this.e2eClient === client) {
-          this.handleSocketClose(event);
-        }
-      },
-    });
-    this.e2eClient = client;
-    previousClient?.disconnect(1000, "e2e_connection_replaced");
-    await client.connect();
-  }
-
-  private resolveE2EConnection(sessionInfo?: AgentSessionInfo) {
-    const hasResponseWsUrl = Boolean(sessionInfo?.ws_url);
-    const hasResponseToken = Boolean(sessionInfo?.e2e_token);
-    if (hasResponseWsUrl !== hasResponseToken) {
-      throw new Error("统一 session 响应的 e2e_resp 必须同时返回 ws_url 和 e2e_token");
-    }
-    if (hasResponseWsUrl && hasResponseToken) {
-      return { wsUrl: sessionInfo?.ws_url as string, token: sessionInfo?.e2e_token as string };
-    }
-
-    const hasConfiguredWsUrl = Boolean(this.agentOptions.e2eServer);
-    const hasConfiguredToken = Boolean(this.agentOptions.authToken);
-    if (hasConfiguredWsUrl !== hasConfiguredToken) {
-      throw new Error("e2eServer 和 authToken 必须同时配置");
-    }
-    if (!hasConfiguredWsUrl) {
-      throw new Error("统一 session 响应未返回 e2e_resp.ws_url，且未配置 e2eServer");
-    }
-    return {
-      wsUrl: this.agentOptions.e2eServer as string,
-      token: this.agentOptions.authToken as string,
-    };
-  }
-
-  private sendControl(message: AgentClientMessage) {
-    try {
-      this.e2eClient?.send(message);
-    } catch (error) {
-      this.emitError("network", "E2E_SEND_FAILED", "E2E WebSocket 发送失败", true, error);
-      throw error;
-    }
-  }
-
-  private assertAudioChunkDuration() {
-    const chunkMs = this.agentOptions.audio?.chunkMs || DEFAULT_AGENT_AUDIO.chunkMs;
-    if (!this.farendAudioEnabled || chunkMs === DEFAULT_AGENT_AUDIO.chunkMs) {
-      return;
-    }
-    const error = new Error("AU v1 音频分片固定为 100ms") as Error & {
-      agentCode?: string;
-      retryable?: boolean;
-    };
-    error.name = "NotSupportedError";
-    error.agentCode = "AUDIO_CHUNK_DURATION_UNSUPPORTED";
-    error.retryable = false;
-    this.emitError("sdk", error.agentCode, error.message, error.retryable, error);
-    throw error;
-  }
-
-  private sendAudioFrame(frame: AgentAudioBlock) {
-    if (!this.farendAudioEnabled) {
-      if (this.agentOptions.debugAudioChunks) {
-        void logAudioChunkContent("[Agent][E2E] nearend raw WebM/Opus chunk", frame.data, {
-          timestamp: frame.timestamp,
-        });
-      }
-      try {
-        this.e2eClient?.sendBinary(frame.data);
-      } catch (error) {
-        this.handleAudioUplinkError(
-          error instanceof Error ? error : new Error("E2E nearend 音频帧发送失败"),
-        );
-      }
-      return;
-    }
-
-    if (this.agentOptions.debugAudioChunks) {
-      void logAudioChunkContent("[Agent][E2E] nearend AU chunk", frame.data, {
-        timestamp: frame.timestamp,
-        stream_id: 1,
-      });
-    }
-    this.audioUplink.offerNearend(frame);
-  }
-
-  private handleAudioUplinkError(error: Error) {
-    this.emitError(
-      "network",
-      "E2E_AUDIO_SEND_FAILED",
-      this.farendAudioEnabled ? "E2E AU 音频帧发送失败" : "E2E 音频帧发送失败",
-      true,
-      error,
-    );
-    const microphone = this.microphone;
-    if (!microphone?.isRecording || this.stopASRPromise) {
-      return;
-    }
-
-    this.setASRState("failed");
-    this.microphone = null;
-    const cleanupPromise = this.finishFailedASR(microphone).finally(() => {
-      if (this.stopASRPromise === cleanupPromise) {
-        this.stopASRPromise = null;
-      }
-    });
-    this.stopASRPromise = cleanupPromise;
-  }
-
-  private applySessionFeatures(sessionInfo: ISessionResponse) {
-    const returnedEnableAec = sessionInfo.e2e_resp?.features?.speech_frontend?.enable_aec
-      ?? sessionInfo.features?.speech_frontend?.enable_aec;
-    this.farendAudioEnabled = typeof returnedEnableAec === "boolean"
-      ? returnedEnableAec
-      : this.agentOptions.requestedEnableAec
-        ?? this.agentOptions.audio?.echoCancellationEnabled
-        ?? false;
-
-    if (!this.farendAudioEnabled) {
-      this.audioUplink.clearFarend();
-    }
-
-    if (this.farendAudioEnabled || this.originalOnAudioPlaybackData) {
-      this.setAudioPlaybackDataHandler(this.playbackDataHandler);
-      if (this.farendAudioEnabled) {
-        void this.enableAudioPlaybackCapture();
-      }
-      return;
-    }
-    this.setAudioPlaybackDataHandler(undefined);
-  }
-
-  private forwardFarendAudio(data: IAudioPlaybackData) {
-    const microphoneRecording = Boolean(this.microphone?.isRecording);
-    const e2eOpen = Boolean(this.e2eClient?.isOpen);
-    if (!this.farendAudioEnabled || !microphoneRecording || !e2eOpen) {
-      (globalThis as typeof globalThis & {
-        avatarSDKLogger?: { log?: (...args: unknown[]) => void };
-      }).avatarSDKLogger?.log?.("[Agent][AudioUplink]", "farend.drop", {
-        reason: !this.farendAudioEnabled
-          ? "aec_disabled"
-          : !microphoneRecording
-            ? "microphone_not_recording"
-            : "e2e_not_open",
-        timestamp: data.timestamp,
-        isFirstChunk: data.isFirstChunk,
-      });
-      return;
-    }
-
-    if (this.agentOptions.debugAudioChunks) {
-      void logAudioChunkContent("[Agent][E2E] farend AU chunk", data.data, {
-        timestamp: data.timestamp,
-        stream_id: 2,
-        codec: data.codec,
-        sampleRate: data.sampleRate,
-        channels: 1,
-        samples: data.samples,
-        speech_id: data.speech_id,
-        isFirstChunk: data.isFirstChunk,
-      });
-    }
-    this.audioUplink.offerFarend({
-      data: data.data,
-      timestamp: data.timestamp,
-      isFirstChunk: data.isFirstChunk,
-    });
-  }
-
-  private handleMicrophoneError(microphone: MicrophoneController, error: Error) {
-    const codedError = error as Error & { agentCode?: string; retryable?: boolean };
-    const isRecorderError = error.name === "MediaRecorderError";
-    const isEncoderError = error.name === "AudioEncoderError";
-    const isAudioPipelineError = isRecorderError || isEncoderError;
-    const isCapabilityError = error.name === "NotSupportedError";
-    const isSDKAudioError = Boolean(codedError.agentCode);
-    const wasStopping = this.asrState === "stopping";
-    const shouldCleanup = isAudioPipelineError && this.microphone === microphone && !wasStopping;
-
-    if (shouldCleanup) {
-      this.microphone = null;
-      const cleanupPromise = this.finishFailedASR(microphone).finally(() => {
-        if (this.stopASRPromise === cleanupPromise) {
-          this.stopASRPromise = null;
-        }
-      });
-      this.stopASRPromise = cleanupPromise;
-    }
-
-    this.emitError(
-      isAudioPipelineError ? "asr" : isSDKAudioError || isCapabilityError ? "sdk" : "permission",
-      codedError.agentCode || (
-        isRecorderError
-          ? "MEDIA_RECORDER_ERROR"
-          : isEncoderError
-            ? "AUDIO_ENCODER_ERROR"
-            : "MICROPHONE_ERROR"
-      ),
-      error.message,
-      codedError.retryable ?? !isCapabilityError,
-      error,
-    );
-  }
-
-  private async finishFailedASR(microphone: MicrophoneController) {
-    try {
-      await microphone.stop();
-      await this.audioUplink.drain();
-    } catch (stopError) {
-      this.emitError("sdk", "MICROPHONE_CLEANUP_FAILED", "麦克风异常后的资源清理失败", false, stopError);
-    }
-
-    try {
-      this.disableAudioInput();
-    } catch {
-      // sendControl has already reported the transport failure.
-    }
-  }
-
-  private enableAudioInput() {
-    if (this.audioInputEnabled) {
-      return;
-    }
-    this.sendControl({
-      type: "event",
-      message: "audio_input_on",
-    });
-    this.audioInputEnabled = true;
-    this.e2eClient?.setAudioInputEnabled(true);
-  }
-
-  private disableAudioInput() {
-    if (!this.audioInputEnabled) {
-      return;
-    }
-    this.sendControl({
-      type: "event",
-      message: "audio_input_off",
-    });
-    this.audioInputEnabled = false;
-    this.e2eClient?.setAudioInputEnabled(false);
-  }
-
-  private handleServerEvent(event: AgentServerEvent) {
-    if (this.agentDestroyed || this.agentDestroying) {
-      return;
-    }
-
-    switch (event.type) {
-      case "pong":
-        return;
-      case "asr_result":
-        this.handleASRResult(event);
-        return;
-      case "llm_response":
-        this.handleLLMResponse(event);
-        return;
-      case "semantic_judge_round_result":
-        this.handleSemanticJudgeResult(event);
-        return;
-      case "error":
-        this.handleBackendError(event);
-        return;
-      default:
-        return;
-    }
-  }
-
-  private handleASRResult(event: AgentServerEvent) {
-    const result: AgentASRResult = {
-      text: typeof event.text === "string" ? event.text : "",
-      isFinal: event.is_final === true,
-      raw: event,
-    };
-    this.safeEmit(() => this.agentOptions.callbacks?.onASRResult?.(result));
-  }
-
-  private handleLLMResponse(event: AgentServerEvent) {
-    if (event.event !== "chunk" && event.event !== "done") {
-      return;
-    }
-
-    const usage = event.usage;
-    const response: AgentLLMResponse = {
-      event: event.event,
-      ...(typeof event.text === "string" ? { text: event.text } : {}),
-      ...(event.is_first === true ? { isFirst: true } : {}),
-      ...(usage
-        ? {
-            usage: {
-              promptTokens: this.readFiniteNumber(usage.prompt_tokens),
-              completionTokens: this.readFiniteNumber(usage.completion_tokens),
-              totalTokens: this.readFiniteNumber(usage.total_tokens),
-              cachedTokens: this.readFiniteNumber(usage.cached_tokens),
-            },
-          }
-        : {}),
-      raw: event,
-    };
-    this.safeEmit(() => this.agentOptions.callbacks?.onLLMResponse?.(response));
-  }
-
-  private handleSemanticJudgeResult(event: AgentServerEvent) {
-    if (!event.message || typeof event.message !== "object") {
-      return;
-    }
-
-    const message = event.message as Record<string, unknown>;
-    const result: AgentSemanticJudgeResult = {
-      query: typeof message.query === "string" ? message.query : "",
-      meaningful: message.meaningful === true,
-      action: typeof message.action === "string" ? message.action : "",
-      raw: event,
-    };
-    this.safeEmit(() => this.agentOptions.callbacks?.onSemanticJudgeResult?.(result));
-  }
-
-  private forwardVoiceEnd() {
-    if (this.suppressNextVoiceEnd) {
-      this.suppressNextVoiceEnd = false;
-      return;
-    }
-    if (
-      this.agentDestroyed ||
-      this.agentDestroying ||
-      this.agentState !== "running" ||
-      !this.e2eClient?.isOpen
-    ) {
-      return;
-    }
-
-    try {
-      this.sendControl({ type: "event", message: "voice_end" });
-    } catch {
-      // sendControl has already reported the transport failure. A render
-      // callback must not throw back into the TTSA frame processing chain.
-    }
-  }
-
-  private readFiniteNumber(value: unknown) {
-    return typeof value === "number" && Number.isFinite(value) ? value : 0;
-  }
-
-  private handleBackendError(event: AgentServerEvent) {
-    const supportedDomains: AgentErrorDomain[] = ["permission", "network", "asr", "brain", "ttsa", "quota", "sdk"];
-    const domain = supportedDomains.includes(event.domain as AgentErrorDomain)
-      ? event.domain as AgentErrorDomain
-      : "sdk";
-    const code = String(event.code ?? "BACKEND_ERROR");
-    const message = typeof event.message === "string" ? event.message : "E2E 后端错误";
-    if (domain === "asr") {
-      this.stopASRAfterSocketClose();
-    }
-    this.emitConversation({ state: "failed" });
-    this.emitError(domain, code, message, domain !== "quota", event);
-  }
-
-  private handleSocketClose(event: CloseEvent) {
-    if (this.agentDestroyed || this.agentDestroying) {
-      return;
-    }
-    if (this.rejectInitialization) {
-      this.abortInitialization(
-        new Error(`Agent 初始化期间 E2E WebSocket 已关闭: ${event.code} ${event.reason || ""}`.trim()),
-      );
-      return;
-    }
-    this.audioUplink.reset();
-    this.stopASRAfterSocketClose();
-    if (this.shouldReconnect(event)) {
-      this.beginReconnect(event);
-      return;
-    }
-    this.setAgentState("failed");
-    const domain: AgentErrorDomain = event.code === 4009 ? "quota" : "network";
-    const message = event.reason || CLOSE_CODE_MESSAGES[event.code] || "E2E WebSocket 已关闭";
-    this.emitError(domain, `E2E_CLOSE_${event.code}`, message, domain !== "quota", {
-      code: event.code,
-      reason: event.reason,
-      wasClean: event.wasClean,
-    });
-  }
-
-  private shouldReconnect(event: CloseEvent) {
-    return this.reconnectOptions.enabled
-      && this.agentState !== "idle"
-      && this.agentState !== "initializing"
-      && this.agentState !== "destroyed"
-      && RETRYABLE_CLOSE_CODES.has(event.code);
-  }
-
-  private beginReconnect(event: CloseEvent) {
-    if (this.agentState !== "reconnecting") {
-      this.stateBeforeReconnect = this.readRestorableState();
-      this.reconnectAttempt = 0;
-      this.sessionReloadFallback = false;
-      this.setAgentState("reconnecting");
-      globalThis.addEventListener?.("online", this.handleOnlineForReconnect);
-      this.emitError("network", "E2E_RECONNECTING", "E2E WebSocket 已断开，正在重连", true, {
-        code: event.code,
-        reason: event.reason,
-        wasClean: event.wasClean,
-      });
-    }
-    this.audioInputEnabled = false;
-    this.e2eClient?.setAudioInputEnabled(false);
-    this.scheduleE2EReconnect(false);
-  }
-
-  private scheduleE2EReconnect(immediate: boolean) {
-    if (
-      this.agentDestroyed
-      || this.agentDestroying
-      || this.agentState !== "reconnecting"
-      || this.reconnectTimer !== null
-      || this.reconnectInFlight
-      || this.sessionReloadFallback
-    ) {
-      return;
-    }
-    if (this.reconnectAttempt >= this.reconnectOptions.maxAttempts) {
-      void this.fallbackToSessionReload();
-      return;
-    }
-
-    const delay = immediate ? 0 : this.getReconnectDelay(this.reconnectAttempt);
-    // @ts-ignore
-    this.reconnectTimer = globalThis.setTimeout(() => {
-      this.reconnectTimer = null;
-      void this.attemptE2EReconnect();
-    }, delay);
-  }
-
-  private async attemptE2EReconnect() {
-    const client = this.e2eClient;
-    if (!client || this.agentDestroyed || this.agentDestroying || this.agentState !== "reconnecting") {
-      return;
-    }
-
-    this.reconnectInFlight = true;
-    this.reconnectAttempt += 1;
-    try {
-      await client.connect();
-      if (this.e2eClient === client && !this.agentDestroyed && !this.agentDestroying) {
-        if (!this.waitingForTtsaReload) {
-          this.finishReconnect();
-        }
-      }
-    } catch {
-      if (this.e2eClient === client && !this.agentDestroyed && !this.agentDestroying) {
-        this.scheduleE2EReconnect(false);
-      }
-    } finally {
-      this.reconnectInFlight = false;
-      if (
-        this.e2eClient === client
-        && this.agentState === "reconnecting"
-        && this.reconnectTimer === null
-        && !this.sessionReloadFallback
-      ) {
-        this.scheduleE2EReconnect(false);
-      }
-    }
-  }
-
-  private async fallbackToSessionReload() {
-    if (this.sessionReloadFallback || this.agentDestroyed || this.agentDestroying) {
-      return;
-    }
-    this.sessionReloadFallback = true;
-    this.clearReconnectTimer();
-    try {
-      await this.restartSessionForTransport("e2e_reconnect_exhausted");
-    } catch (error) {
-      this.failReconnect(error);
-    }
-  }
-
-  private finishReconnect() {
-    const nextState = this.stateBeforeReconnect;
-    this.cancelReconnect();
-    if (this.asrState !== "idle") {
-      this.setASRState("idle");
-    }
-    this.setAgentState(nextState);
-  }
-
-  private failReconnect(cause?: unknown) {
-    this.cancelReconnect();
-    this.setAgentState("failed");
-    this.emitConversation({ state: "failed" });
-    this.emitError(
-      "network",
-      "E2E_RECONNECT_EXHAUSTED",
-      "E2E WebSocket 重连失败，请重新初始化 Agent",
-      false,
-      cause,
-    );
-  }
-
-  private cancelReconnect() {
-    this.clearReconnectTimer();
-    globalThis.removeEventListener?.("online", this.handleOnlineForReconnect);
-    this.reconnectAttempt = 0;
-    this.reconnectInFlight = false;
-    this.sessionReloadFallback = false;
-    this.waitingForTtsaReload = false;
-  }
-
-  private clearReconnectTimer() {
-    if (this.reconnectTimer !== null) {
-      globalThis.clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-  }
-
-  private getReconnectDelay(attempt: number) {
-    const baseDelay = Math.min(
-      this.reconnectOptions.maxDelayMs,
-      this.reconnectOptions.initialDelayMs * (2 ** attempt),
-    );
-    if (baseDelay === 0) {
-      return 0;
-    }
-    return Math.round(baseDelay * (0.8 + Math.random() * 0.4));
-  }
-
-  private readRestorableState(): AgentState {
-    if (this.agentState === "running" || this.agentState === "stopped" || this.agentState === "ready") {
-      return this.agentState;
-    }
-    return "ready";
-  }
-
-  private normalizeReconnectOptions(options?: AgentReconnectOptions): Required<AgentReconnectOptions> {
-    const initialDelayMs = this.readNonNegativeNumber(
-      options?.initialDelayMs,
-      DEFAULT_RECONNECT_OPTIONS.initialDelayMs,
-    );
-    return {
-      enabled: options?.enabled ?? DEFAULT_RECONNECT_OPTIONS.enabled,
-      maxAttempts: Math.max(1, Math.floor(this.readNonNegativeNumber(
-        options?.maxAttempts,
-        DEFAULT_RECONNECT_OPTIONS.maxAttempts,
-      ))),
-      initialDelayMs,
-      maxDelayMs: Math.max(initialDelayMs, this.readNonNegativeNumber(
-        options?.maxDelayMs,
-        DEFAULT_RECONNECT_OPTIONS.maxDelayMs,
-      )),
-    };
-  }
-
-  private readNonNegativeNumber(value: unknown, fallback: number) {
-    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
-  }
-
-  private stopASRAfterSocketClose() {
-    this.asrStartGeneration += 1;
-    if (this.stopASRPromise) {
-      return;
-    }
-    const microphone = this.microphone;
-    if (!microphone?.isRecording) {
-      return;
-    }
-
-    this.microphone = null;
-    this.stopASRPromise = this.finishStopASR(microphone, false)
-      .catch((error) => {
-        this.emitError("sdk", "MICROPHONE_CLEANUP_FAILED", "WebSocket 断开后清理麦克风失败", false, error);
-      })
-      .finally(() => {
-        this.stopASRPromise = null;
-      });
-  }
-
-  private setAgentState(state: AgentState) {
-    this.agentState = state;
-    if (!this.agentDestroyed || state === "destroyed") {
-      this.agentOptions.callbacks?.onAgentStateChange?.(state);
-    }
-  }
-
-  private setASRState(state: AgentASRState) {
-    this.asrState = state;
-    this.safeEmit(() => this.agentOptions.callbacks?.onASRStateChange?.(state));
-  }
-
-  private emitConversation(event: AgentConversationEvent) {
-    this.safeEmit(() => this.agentOptions.callbacks?.onConversationChange?.(event));
-  }
-
-  private emitError(
-    domain: AgentErrorDomain,
-    code: string,
-    message: string,
-    retryable?: boolean,
-    cause?: unknown,
-  ) {
-    const error: AgentError = { domain, code, message, retryable, cause };
-    if (domain === "asr") {
-      this.setASRState("failed");
-    }
-    this.safeEmit(() => this.agentOptions.callbacks?.onError?.(error));
-  }
-
-  private safeEmit(callback: () => void) {
-    if (!this.agentDestroyed && !this.agentDestroying) {
-      callback();
-    }
-  }
-
-  private assertRunning() {
-    this.assertE2EOpen();
-    if (this.agentState !== "running") {
-      throw new Error("Agent 尚未启动，请先调用 start()");
-    }
-  }
-
-  private assertE2EOpen() {
-    this.assertNotDestroyed();
-    if (!this.e2eClient?.isOpen) {
-      throw new Error("Agent 尚未连接 E2E WebSocket");
-    }
-  }
-
-  private assertNotDestroyed() {
-    if (this.agentDestroyed || this.agentDestroying) {
-      throw new Error("Agent 已销毁");
-    }
-  }
-
-}
-
-export * from "./types";
-export { AgentE2EClient } from "./e2e-client";
-export { MicrophoneController } from "./microphone";