@xmov/avatar 2.0.0-alpha.53 → 2.0.0-alpha.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmov/avatar",
-  "version": "2.0.0-alpha.53",
+  "version": "2.0.0-alpha.54",
   "description": "魔珐数字人 JS-SDK",
   "type": "module",
   "source": "src/index.ts",
@@ -10,12 +10,19 @@
       "default": "./dist/index.modern.js"
     },
     "./agent": {
-      "types": "./src/agent/index.ts",
+      "types": "./dist/agent/index.d.ts",
       "require": "./dist/agent/index.cjs",
       "default": "./dist/agent/avatar.modern.js"
     },
     "./agent/umd": "./dist/agent/index.umd.js"
   },
+  "typesVersions": {
+    "*": {
+      "agent": [
+        "dist/agent/index.d.ts"
+      ]
+    }
+  },
   "amdName": "XmovAvatar",
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.ts",

package/src/agent/__tests__/agent.test.ts

@@ -2153,10 +2153,17 @@ test("XingyunAvatarAgent rejects ambiguous non-empty config sources", () => {
   );
 });
 
-test("XingyunAvatarAgent extends XmovAvatar and preserves base speak", async () => {
+test("XingyunAvatarAgent extends XmovAvatar while keeping the base class behavior unchanged", async () => {
   MockWebSocket.instances = [];
   const { agent } = createAgent();
   const XmovAvatar = require("../../index");
+  const avatar = new XmovAvatar({});
+
+  avatar.speak("legacy TTSA speak");
+  const interruptedSpeechId = avatar.interrupt("speak");
+  assert.deepEqual(avatar.speeches, [["legacy TTSA speak"]]);
+  assert.deepEqual(avatar.interrupts, ["speak"]);
+  assert.equal(interruptedSpeechId, 1);
 
   await agent.init();
   const ws = MockWebSocket.instances[0];
@@ -2167,11 +2174,6 @@ test("XingyunAvatarAgent extends XmovAvatar and preserves base speak", async ()
 
   agent.start();
   assert.equal(agent.startCalls, 1);
-  agent.speak("legacy TTSA speak");
-  assert.deepEqual(agent.speeches, [["legacy TTSA speak"]]);
-  assert.deepEqual(ws.sent, []);
-  agent.avatarOptions.onVoiceStateChange("end");
-  assert.deepEqual(ws.sent, []);
 });
 
 test("XingyunAvatarAgent restarts TTSA after same-session ready without leaving stopped state", async () => {
@@ -2200,7 +2202,7 @@ test("XingyunAvatarAgent ignores an explicit start while init is pending", () =>
   assert.equal(agent.started, false);
 });
 
-test("XingyunAvatarAgent sends frozen ask and speak payloads without client IDs or providers", async () => {
+test("XingyunAvatarAgent sends frozen ask and canonical speak payloads without client IDs or providers", async () => {
   MockWebSocket.instances = [];
   const conversations = [];
   const { agent } = createAgent({
@@ -2215,15 +2217,34 @@ test("XingyunAvatarAgent sends frozen ask and speak payloads without client IDs
   assert.deepEqual(askPayload, { type: "ask", message: { text: "hello" } });
   assert.deepEqual(conversations.at(-1), { state: "asking", text: "hello" });
 
-  await agent.speakByE2E("welcome");
+  const speakResult = agent.speak("welcome");
+  assert.equal(speakResult, undefined);
   const speakPayload = JSON.parse(ws.sent.at(-1));
   assert.deepEqual(speakPayload, {
     type: "speak",
     message: { text: "welcome", is_start: true, is_end: true },
   });
+  assert.deepEqual(conversations.at(-1), { state: "speaking-directly", text: "welcome" });
+
+  const e2eSentCount = ws.sent.length;
+  const replayExtra = { client_speak_id: "replay", client_frame: 7 };
+  const replayResult = agent.speak("<speak>replay</speak>", false, true, replayExtra);
+  assert.equal(replayResult, undefined);
+  assert.deepEqual(agent.speeches.at(-1), ["<speak>replay</speak>", false, true, replayExtra]);
+  assert.equal(ws.sent.length, e2eSentCount);
+  agent.avatarOptions.onVoiceStateChange("end", 1200);
+  assert.equal(ws.sent.length, e2eSentCount);
+
+  const sentCount = ws.sent.length;
+  await agent.speakByE2E("deprecated welcome");
+  assert.equal(ws.sent.length, sentCount + 1);
+  assert.deepEqual(JSON.parse(ws.sent.at(-1)), {
+    type: "speak",
+    message: { text: "deprecated welcome", is_start: true, is_end: true },
+  });
 });
 
-test("XingyunAvatarAgent interrupts E2E and local playback without client IDs", async () => {
+test("XingyunAvatarAgent interrupts E2E and local playback through canonical and deprecated methods", async () => {
   MockWebSocket.instances = [];
   const { agent } = createAgent();
 
@@ -2231,9 +2252,16 @@ test("XingyunAvatarAgent interrupts E2E and local playback without client IDs",
   const ws = MockWebSocket.instances[0];
   await agent.ask("cancel me");
 
-  await agent.interruptConversation("user");
+  const interruptResult = agent.interrupt();
+  assert.equal(interruptResult, 1);
   assert.deepEqual(agent.interrupts, ["speak"]);
   assert.deepEqual(JSON.parse(ws.sent.at(-1)), { type: "interrupt" });
+
+  const sentCount = ws.sent.length;
+  await agent.interruptConversation("user");
+  assert.equal(ws.sent.length, sentCount + 1);
+  assert.deepEqual(agent.interrupts, ["speak", "speak"]);
+  assert.deepEqual(JSON.parse(ws.sent.at(-1)), { type: "interrupt" });
 });
 
 test("XingyunAvatarAgent keeps ASR listening when interrupting a conversation", async () => {
@@ -2248,7 +2276,7 @@ test("XingyunAvatarAgent keeps ASR listening when interrupting a conversation",
     const recorder = browser.recorders[0];
     ws.sent = [];
 
-    await agent.interruptConversation("user");
+    agent.interrupt();
     const audioAfterInterrupt = new Blob(["audio-after-interrupt"], {
       type: "audio/webm;codecs=opus",
     });

package/src/agent/index.ts

@@ -262,7 +262,9 @@ export default class XingyunAvatarAgent extends XmovAvatar {
     return this.agentState;
   }
 
-  // Kept for callers that adopted the first Agent preview.
+  /**
+   * @deprecated Use getAgentState() instead.
+   */
   getState() {
     return this.getAgentState();
   }
@@ -460,13 +462,6 @@ export default class XingyunAvatarAgent extends XmovAvatar {
     }
   }
 
-  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") {
@@ -510,7 +505,16 @@ export default class XingyunAvatarAgent extends XmovAvatar {
     });
   }
 
-  async speakByE2E(text: string): Promise<void> {
+  override speak(text: string): string | undefined {
+    // XmovAvatar Replay dispatches recorded TTSA events through this.speak(...).
+    // Preserve that inherited multi-argument call path without exposing it as
+    // the Agent's public E2E API.
+    if (arguments.length > 1) {
+      if (arguments[2] ?? true) {
+        this.suppressNextVoiceEnd = true;
+      }
+      return super.speak(text, arguments[1], arguments[2], arguments[3]);
+    }
     this.assertRunning();
     this.suppressNextVoiceEnd = false;
     this.emitConversation({ state: "speaking-directly", text });
@@ -522,6 +526,14 @@ export default class XingyunAvatarAgent extends XmovAvatar {
         is_end: true,
       },
     });
+    return undefined;
+  }
+
+  /**
+   * @deprecated Use speak(text) instead.
+   */
+  async speakByE2E(text: string): Promise<void> {
+    this.speak(text);
   }
 
   async startASR(options: AgentASRStartOptions = {}): Promise<void> {
@@ -670,18 +682,25 @@ export default class XingyunAvatarAgent extends XmovAvatar {
     }
   }
 
-  async interruptConversation(reason = "user") {
+  override interrupt(): number {
     if (this.agentDestroyed) {
-      return;
+      return 0;
     }
 
-    void reason;
-
     this.sendControl({
       type: "interrupt",
     });
-    super.interrupt("speak");
+    const interruptedSpeechId = super.interrupt("speak");
     this.emitConversation({ state: "interrupted" });
+    return interruptedSpeechId;
+  }
+
+  /**
+   * @deprecated Use interrupt() instead. The reason parameter is ignored.
+   */
+  async interruptConversation(reason = "user"): Promise<void> {
+    void reason;
+    this.interrupt();
   }
 
   protected override async onSessionReloaded(sessionInfo: ISessionResponse): Promise<void> {
@@ -717,10 +736,6 @@ export default class XingyunAvatarAgent extends XmovAvatar {
     }
   }
 
-  override reloadSuccess() {
-    super.reloadSuccess();
-  }
-
   private async replaceE2EConnection(sessionInfo?: AgentSessionInfo) {
     const { wsUrl, token } = this.resolveE2EConnection(sessionInfo);
     const previousClient = this.e2eClient;