@livekit/agents 1.1.0 → 1.2.1

package/src/llm/chat_context.test.ts

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import { describe, expect, it } from 'vitest';
+import { initializeLogger } from '../log.js';
+import { FakeLLM } from '../voice/testing/fake_llm.js';
 import {
   type AudioContent,
   ChatContext,
@@ -13,6 +15,20 @@ import {
   ReadonlyChatContext,
 } from './chat_context.js';
 
+initializeLogger({ pretty: false, level: 'error' });
+
+const summaryXml = (summary: string) =>
+  ['<chat_history_summary>', summary, '</chat_history_summary>'].join('\n');
+
+class TrackingFakeLLM extends FakeLLM {
+  chatCalls = 0;
+
+  chat(...args: Parameters<FakeLLM['chat']>) {
+    this.chatCalls += 1;
+    return super.chat(...args);
+  }
+}
+
 describe('ChatContext.toJSON', () => {
   it('should match snapshot for empty context', () => {
     const context = new ChatContext();
@@ -283,6 +299,170 @@ describe('ChatContext.toJSON', () => {
   });
 });
 
+describe('ChatContext._summarize', () => {
+  it('includes function calls in the summarization source and keeps chronological order', async () => {
+    const ctx = new ChatContext();
+    ctx.addMessage({ role: 'system', content: 'System prompt', createdAt: 0 });
+    ctx.addMessage({ role: 'user', content: 'hello', createdAt: 1000 });
+    ctx.addMessage({ role: 'assistant', content: 'hi there', createdAt: 2000 });
+    ctx.insert(
+      FunctionCall.create({
+        callId: 'call_1',
+        name: 'lookup',
+        args: '{"order":"123"}',
+        createdAt: 2500,
+      }),
+    );
+    ctx.insert(
+      new FunctionCallOutput({
+        callId: 'call_1',
+        name: 'lookup',
+        output: '{"status":"delivered"}',
+        isError: false,
+        createdAt: 2600,
+      }),
+    );
+    ctx.addMessage({ role: 'user', content: 'my color is blue', createdAt: 3000 });
+    ctx.addMessage({ role: 'assistant', content: 'noted', createdAt: 4000 });
+
+    const fake = new FakeLLM([
+      {
+        input: [
+          'Conversation to summarize:',
+          '',
+          '<user>',
+          'hello',
+          '</user>',
+          '<assistant>',
+          'hi there',
+          '</assistant>',
+          '<function_call name="lookup" call_id="call_1">',
+          '{"order":"123"}',
+          '</function_call>',
+          '<function_call_output name="lookup" call_id="call_1">',
+          '{"status":"delivered"}',
+          '</function_call_output>',
+        ].join('\n'),
+        content: 'condensed head',
+      },
+    ]);
+
+    await ctx._summarize(fake, { keepLastTurns: 1 });
+
+    const summary = ctx.items.find(
+      (item) =>
+        item.type === 'message' && item.role === 'assistant' && item.extra?.is_summary === true,
+    );
+    expect(summary).toBeDefined();
+    if (!summary || summary.type !== 'message') {
+      throw new Error('summary message is missing');
+    }
+
+    expect(summary.textContent).toBe(summaryXml('condensed head'));
+    expect(summary.createdAt).toBeCloseTo(2999.999999, 6);
+    expect(ctx.items.filter((item) => item.type === 'function_call')).toHaveLength(0);
+    expect(ctx.items.filter((item) => item.type === 'function_call_output')).toHaveLength(0);
+
+    const createdAts = ctx.items.map((item) => item.createdAt);
+    const sorted = [...createdAts].sort((a, b) => a - b);
+    expect(createdAts).toEqual(sorted);
+  });
+
+  it('preserves interleaved tool items that belong to the recent tail', async () => {
+    const ctx = new ChatContext();
+    ctx.addMessage({ role: 'system', content: 'System prompt', createdAt: 0 });
+    ctx.addMessage({ role: 'user', content: 'my earbuds are broken', createdAt: 1000 });
+    ctx.addMessage({
+      role: 'assistant',
+      content: 'Can you share your order number?',
+      createdAt: 2000,
+    });
+    ctx.addMessage({ role: 'user', content: 'Order #123', createdAt: 3000 });
+    ctx.insert(
+      FunctionCall.create({
+        callId: 'call_2',
+        name: 'lookup_order',
+        args: '{"order":"123"}',
+        createdAt: 3500,
+      }),
+    );
+    ctx.insert(
+      new FunctionCallOutput({
+        callId: 'call_2',
+        name: 'lookup_order',
+        output: '{"status":"delivered"}',
+        isError: false,
+        createdAt: 3600,
+      }),
+    );
+    ctx.addMessage({
+      role: 'assistant',
+      content: 'Found your order. Let me check the warranty.',
+      createdAt: 4000,
+    });
+    ctx.addMessage({ role: 'user', content: 'Thanks.', createdAt: 5000 });
+    ctx.addMessage({ role: 'assistant', content: 'You are under warranty.', createdAt: 6000 });
+
+    const fake = new FakeLLM([
+      {
+        input: [
+          'Conversation to summarize:',
+          '',
+          '<user>',
+          'my earbuds are broken',
+          '</user>',
+          '<assistant>',
+          'Can you share your order number?',
+          '</assistant>',
+        ].join('\n'),
+        content: 'older summary',
+      },
+    ]);
+
+    await ctx._summarize(fake, { keepLastTurns: 2 });
+
+    const functionItems = ctx.items.filter(
+      (item) => item.type === 'function_call' || item.type === 'function_call_output',
+    );
+    expect(functionItems).toHaveLength(2);
+    expect(functionItems.map((item) => item.createdAt)).toEqual([3500, 3600]);
+
+    const rawTailMessages = ctx.items.filter(
+      (item) =>
+        item.type === 'message' &&
+        (item.role === 'user' || item.role === 'assistant') &&
+        item.extra?.is_summary !== true,
+    );
+    expect(rawTailMessages).toHaveLength(4);
+    expect(rawTailMessages.map((item) => item.textContent)).toEqual([
+      'Order #123',
+      'Found your order. Let me check the warranty.',
+      'Thanks.',
+      'You are under warranty.',
+    ]);
+
+    const createdAts = ctx.items.map((item) => item.createdAt);
+    const sorted = [...createdAts].sort((a, b) => a - b);
+    expect(createdAts).toEqual(sorted);
+  });
+
+  it('skips summarization when the recent-turn budget already covers the history', async () => {
+    const ctx = new ChatContext();
+    ctx.addMessage({ role: 'system', content: 'System prompt', createdAt: 0 });
+    ctx.addMessage({ role: 'user', content: 'hello', createdAt: 1000 });
+    ctx.addMessage({ role: 'assistant', content: 'hi there', createdAt: 2000 });
+
+    const llm = new TrackingFakeLLM();
+    const originalIds = ctx.items.map((item) => item.id);
+
+    const result = await ctx._summarize(llm, { keepLastTurns: 1 });
+
+    expect(result).toBe(ctx);
+    expect(llm.chatCalls).toBe(0);
+    expect(ctx.items.map((item) => item.id)).toEqual(originalIds);
+  });
+});
+
 describe('ReadonlyChatContext with immutable array', () => {
   it('should have readonly property set to true', () => {
     const items: ChatItem[] = [
@@ -448,3 +628,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);
+    });
+  });
+});