@livekit/agents 1.0.14 → 1.0.16

package/src/llm/chat_context.test.ts

@@ -448,3 +448,610 @@ describe('ReadonlyChatContext with immutable array', () => {
     expect(ids).toEqual(['msg_1', 'msg_2']);
   });
 });
+
+describe('ChatContext.isEquivalent', () => {
+  it('should return true for same reference', () => {
+    const ctx = new ChatContext();
+    ctx.addMessage({
+      id: 'msg_1',
+      role: 'user',
+      content: 'Hello',
+    });
+
+    expect(ctx.isEquivalent(ctx)).toBe(true);
+  });
+
+  it('should return true for identical empty contexts', () => {
+    const ctx1 = new ChatContext();
+    const ctx2 = new ChatContext();
+
+    expect(ctx1.isEquivalent(ctx2)).toBe(true);
+  });
+
+  it('should return false for contexts with different lengths', () => {
+    const ctx1 = new ChatContext();
+    ctx1.addMessage({
+      id: 'msg_1',
+      role: 'user',
+      content: 'Hello',
+    });
+
+    const ctx2 = new ChatContext();
+    ctx2.addMessage({
+      id: 'msg_1',
+      role: 'user',
+      content: 'Hello',
+    });
+    ctx2.addMessage({
+      id: 'msg_2',
+      role: 'assistant',
+      content: 'Hi',
+    });
+
+    expect(ctx1.isEquivalent(ctx2)).toBe(false);
+  });
+
+  it('should return false for contexts with different item IDs', () => {
+    const ctx1 = new ChatContext();
+    ctx1.addMessage({
+      id: 'msg_1',
+      role: 'user',
+      content: 'Hello',
+    });
+
+    const ctx2 = new ChatContext();
+    ctx2.addMessage({
+      id: 'msg_2',
+      role: 'user',
+      content: 'Hello',
+    });
+
+    expect(ctx1.isEquivalent(ctx2)).toBe(false);
+  });
+
+  it('should return false for contexts with different item types', () => {
+    const ctx1 = new ChatContext();
+    ctx1.addMessage({
+      id: 'msg_1',
+      role: 'user',
+      content: 'Hello',
+    });
+
+    const ctx2 = new ChatContext();
+    ctx2.insert(
+      new FunctionCall({
+        id: 'msg_1',
+        callId: 'call_1',
+        name: 'test',
+        args: '{}',
+      }),
+    );
+
+    expect(ctx1.isEquivalent(ctx2)).toBe(false);
+  });
+
+  describe('message comparison', () => {
+    it('should return true for identical messages', () => {
+      const ctx1 = new ChatContext();
+      ctx1.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: 'Hello',
+        interrupted: false,
+      });
+
+      const ctx2 = new ChatContext();
+      ctx2.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: 'Hello',
+        interrupted: false,
+      });
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(true);
+    });
+
+    it('should return false for messages with different roles', () => {
+      const ctx1 = new ChatContext();
+      ctx1.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: 'Hello',
+      });
+
+      const ctx2 = new ChatContext();
+      ctx2.addMessage({
+        id: 'msg_1',
+        role: 'assistant',
+        content: 'Hello',
+      });
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should return false for messages with different interrupted flags', () => {
+      const ctx1 = new ChatContext();
+      ctx1.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: 'Hello',
+        interrupted: false,
+      });
+
+      const ctx2 = new ChatContext();
+      ctx2.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: 'Hello',
+        interrupted: true,
+      });
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should return false for messages with different content', () => {
+      const ctx1 = new ChatContext();
+      ctx1.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: 'Hello',
+      });
+
+      const ctx2 = new ChatContext();
+      ctx2.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: 'World',
+      });
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should return true for messages with identical array content', () => {
+      const ctx1 = new ChatContext();
+      ctx1.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: ['Hello', 'World'],
+      });
+
+      const ctx2 = new ChatContext();
+      ctx2.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: ['Hello', 'World'],
+      });
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(true);
+    });
+
+    it('should return false for messages with different array content', () => {
+      const ctx1 = new ChatContext();
+      ctx1.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: ['Hello', 'World'],
+      });
+
+      const ctx2 = new ChatContext();
+      ctx2.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: ['Hello'],
+      });
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should return true for messages with identical image content', () => {
+      const imageContent: ImageContent = {
+        id: 'img_1',
+        type: 'image_content',
+        image: 'https://example.com/image.jpg',
+        inferenceDetail: 'high',
+        inferenceWidth: 1024,
+        inferenceHeight: 768,
+        mimeType: 'image/jpeg',
+        _cache: {},
+      };
+
+      const ctx1 = new ChatContext();
+      ctx1.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: ['Check this:', imageContent],
+      });
+
+      const ctx2 = new ChatContext();
+      ctx2.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: ['Check this:', { ...imageContent }],
+      });
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(true);
+    });
+
+    it('should return false for messages with different image content', () => {
+      const imageContent1: ImageContent = {
+        id: 'img_1',
+        type: 'image_content',
+        image: 'https://example.com/image1.jpg',
+        inferenceDetail: 'high',
+        _cache: {},
+      };
+
+      const imageContent2: ImageContent = {
+        id: 'img_2',
+        type: 'image_content',
+        image: 'https://example.com/image2.jpg',
+        inferenceDetail: 'high',
+        _cache: {},
+      };
+
+      const ctx1 = new ChatContext();
+      ctx1.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: ['Check this:', imageContent1],
+      });
+
+      const ctx2 = new ChatContext();
+      ctx2.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: ['Check this:', imageContent2],
+      });
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+  });
+
+  describe('function call comparison', () => {
+    it('should return true for identical function calls', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          args: '{"location": "Paris"}',
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          args: '{"location": "Paris"}',
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(true);
+    });
+
+    it('should return false for function calls with different names', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          args: '{}',
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_time',
+          args: '{}',
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should return false for function calls with different call IDs', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          args: '{}',
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_2',
+          name: 'get_weather',
+          args: '{}',
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should return false for function calls with different arguments', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          args: '{"location": "Paris"}',
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          args: '{"location": "London"}',
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should ignore timestamps', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          args: '{}',
+          createdAt: 1000,
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          args: '{}',
+          createdAt: 2000,
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(true);
+    });
+  });
+
+  describe('function call output comparison', () => {
+    it('should return true for identical function call outputs', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: '{"temperature": 22}',
+          isError: false,
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: '{"temperature": 22}',
+          isError: false,
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(true);
+    });
+
+    it('should return false for function call outputs with different names', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: '{}',
+          isError: false,
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_time',
+          output: '{}',
+          isError: false,
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should return false for function call outputs with different call IDs', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: '{}',
+          isError: false,
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_2',
+          name: 'get_weather',
+          output: '{}',
+          isError: false,
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should return false for function call outputs with different output values', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: '{"temperature": 22}',
+          isError: false,
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: '{"temperature": 25}',
+          isError: false,
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should return false for function call outputs with different error flags', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: 'Error occurred',
+          isError: false,
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: 'Error occurred',
+          isError: true,
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(false);
+    });
+
+    it('should ignore timestamps', () => {
+      const ctx1 = new ChatContext();
+      ctx1.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: '{}',
+          isError: false,
+          createdAt: 1000,
+        }),
+      );
+
+      const ctx2 = new ChatContext();
+      ctx2.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: '{}',
+          isError: false,
+          createdAt: 2000,
+        }),
+      );
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(true);
+    });
+  });
+
+  describe('complex context comparison', () => {
+    it('should return true for identical complex contexts', () => {
+      const ctx1 = new ChatContext();
+      ctx1.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: 'What is the weather?',
+      });
+      ctx1.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          args: '{"location": "Paris"}',
+        }),
+      );
+      ctx1.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: '{"temperature": 22}',
+          isError: false,
+        }),
+      );
+      ctx1.addMessage({
+        id: 'msg_2',
+        role: 'assistant',
+        content: 'The weather is 22°C',
+      });
+
+      const ctx2 = new ChatContext();
+      ctx2.addMessage({
+        id: 'msg_1',
+        role: 'user',
+        content: 'What is the weather?',
+      });
+      ctx2.insert(
+        new FunctionCall({
+          id: 'func_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          args: '{"location": "Paris"}',
+        }),
+      );
+      ctx2.insert(
+        new FunctionCallOutput({
+          id: 'output_1',
+          callId: 'call_1',
+          name: 'get_weather',
+          output: '{"temperature": 22}',
+          isError: false,
+        }),
+      );
+      ctx2.addMessage({
+        id: 'msg_2',
+        role: 'assistant',
+        content: 'The weather is 22°C',
+      });
+
+      expect(ctx1.isEquivalent(ctx2)).toBe(true);
+    });
+  });
+});

package/src/llm/chat_context.ts

@@ -513,6 +513,112 @@ export class ChatContext {
     return 0;
   }
 
+  /**
+   * Return true if `other` has the same sequence of items with matching
+   * essential fields (IDs, types, and payload) as this context.
+   *
+   * Comparison rules:
+   * - Messages: compares the full `content` list, `role` and `interrupted`.
+   * - Function calls: compares `name`, `callId`, and `args`.
+   * - Function call outputs: compares `name`, `callId`, `output`, and `isError`.
+   *
+   * Does not consider timestamps or other metadata.
+   */
+  isEquivalent(other: ChatContext): boolean {
+    if (this === other) {
+      return true;
+    }
+
+    if (this.items.length !== other.items.length) {
+      return false;
+    }
+
+    for (let i = 0; i < this.items.length; i++) {
+      const a = this.items[i]!;
+      const b = other.items[i]!;
+
+      if (a.id !== b.id || a.type !== b.type) {
+        return false;
+      }
+
+      if (a.type === 'message' && b.type === 'message') {
+        if (
+          a.role !== b.role ||
+          a.interrupted !== b.interrupted ||
+          !this.compareContent(a.content, b.content)
+        ) {
+          return false;
+        }
+      } else if (a.type === 'function_call' && b.type === 'function_call') {
+        if (a.name !== b.name || a.callId !== b.callId || a.args !== b.args) {
+          return false;
+        }
+      } else if (a.type === 'function_call_output' && b.type === 'function_call_output') {
+        if (
+          a.name !== b.name ||
+          a.callId !== b.callId ||
+          a.output !== b.output ||
+          a.isError !== b.isError
+        ) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Compare two content arrays for equality.
+   */
+  private compareContent(a: ChatContent[], b: ChatContent[]): boolean {
+    if (a.length !== b.length) {
+      return false;
+    }
+
+    for (let i = 0; i < a.length; i++) {
+      const contentA = a[i]!;
+      const contentB = b[i]!;
+
+      if (typeof contentA === 'string' && typeof contentB === 'string') {
+        if (contentA !== contentB) {
+          return false;
+        }
+        continue;
+      }
+
+      if (typeof contentA !== typeof contentB) {
+        return false;
+      }
+
+      if (typeof contentA === 'object' && typeof contentB === 'object') {
+        if (contentA.type === 'image_content' && contentB.type === 'image_content') {
+          if (
+            contentA.id !== contentB.id ||
+            contentA.image !== contentB.image ||
+            contentA.inferenceDetail !== contentB.inferenceDetail ||
+            contentA.inferenceWidth !== contentB.inferenceWidth ||
+            contentA.inferenceHeight !== contentB.inferenceHeight ||
+            contentA.mimeType !== contentB.mimeType
+          ) {
+            return false;
+          }
+        } else if (contentA.type === 'audio_content' && contentB.type === 'audio_content') {
+          if (contentA.frame.length !== contentB.frame.length) {
+            return false;
+          }
+          if (contentA.transcript !== contentB.transcript) {
+            return false;
+          }
+        } else {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
   /**
    * Indicates whether the context is read-only
    */