@livekit/agents 1.0.46 → 1.0.48

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,8 @@ import {
   ReadonlyChatContext,
 } from './chat_context.js';
 
+initializeLogger({ pretty: false, level: 'error' });
+
 describe('ChatContext.toJSON', () => {
   it('should match snapshot for empty context', () => {
     const context = new ChatContext();
@@ -283,6 +287,50 @@ describe('ChatContext.toJSON', () => {
   });
 });
 
+describe('ChatContext._summarize', () => {
+  it('keeps chronological timestamps with summary + tail', 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(
+      new FunctionCallOutput({
+        callId: 'call_1',
+        name: 'lookup',
+        output: '{"ok":true}',
+        isError: false,
+        createdAt: 3500,
+      }),
+    );
+    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:\n\nuser: hello\nassistant: hi there',
+        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.createdAt).toBeCloseTo(2999.999, 6);
+
+    const createdAts = ctx.items.map((item) => item.createdAt);
+    const sorted = [...createdAts].sort((a, b) => a - b);
+    expect(createdAts).toEqual(sorted);
+  });
+});
+
 describe('ReadonlyChatContext with immutable array', () => {
   it('should have readonly property set to true', () => {
     const items: ChatItem[] = [

package/src/llm/chat_context.ts

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { AudioFrame, VideoFrame } from '@livekit/rtc-node';
 import { createImmutableArray, shortuuid } from '../utils.js';
+import type { LLM } from './llm.js';
 import { type ProviderFormat, toChatCtx } from './provider_format/index.js';
 import type { JSONObject, JSONValue, ToolContext } from './tool_context.js';
 
@@ -95,12 +96,15 @@ export class ChatMessage {
 
   createdAt: number;
 
+  extra: Record<string, unknown>;
+
   constructor(params: {
     role: ChatRole;
     content: ChatContent[] | string;
     id?: string;
     interrupted?: boolean;
     createdAt?: number;
+    extra?: Record<string, unknown>;
   }) {
     const {
       role,
@@ -108,12 +112,14 @@ export class ChatMessage {
       id = shortuuid('item_'),
       interrupted = false,
       createdAt = Date.now(),
+      extra = {},
     } = params;
     this.id = id;
     this.role = role;
     this.content = Array.isArray(content) ? content : [content];
     this.interrupted = interrupted;
     this.createdAt = createdAt;
+    this.extra = extra;
   }
 
   static create(params: {
@@ -122,6 +128,7 @@ export class ChatMessage {
     id?: string;
     interrupted?: boolean;
     createdAt?: number;
+    extra?: Record<string, unknown>;
   }) {
     return new ChatMessage(params);
   }
@@ -401,6 +408,7 @@ export class AgentHandoffItem {
   }
 }
 
+// TODO(parity): Add AgentConfigUpdate type to ChatItem union
 export type ChatItem = ChatMessage | FunctionCall | FunctionCallOutput | AgentHandoffItem;
 
 export class ChatContext {
@@ -431,6 +439,7 @@ export class ChatContext {
     id?: string;
     interrupted?: boolean;
     createdAt?: number;
+    extra?: Record<string, unknown>;
   }): ChatMessage {
     const msg = new ChatMessage(params);
     if (params.createdAt !== undefined) {
@@ -463,11 +472,13 @@ export class ChatContext {
     return idx !== -1 ? idx : undefined;
   }
 
+  // TODO(parity): Add excludeConfigUpdate option when AgentConfigUpdate is ported
   copy(
     options: {
       excludeFunctionCall?: boolean;
       excludeInstructions?: boolean;
       excludeEmptyMessage?: boolean;
+      excludeHandoff?: boolean;
       toolCtx?: ToolContext<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
     } = {},
   ): ChatContext {
@@ -475,6 +486,7 @@ export class ChatContext {
       excludeFunctionCall = false,
       excludeInstructions = false,
       excludeEmptyMessage = false,
+      excludeHandoff = false,
       toolCtx,
     } = options;
     const items: ChatItem[] = [];
@@ -500,6 +512,10 @@ export class ChatContext {
         continue;
       }
 
+      if (excludeHandoff && item.type === 'agent_handoff') {
+        continue;
+      }
+
       if (toolCtx !== undefined && isToolCallOrOutput(item) && toolCtx[item.name] === undefined) {
         continue;
       }
@@ -510,6 +526,42 @@ export class ChatContext {
     return new ChatContext(items);
   }
 
+  // TODO(parity): Add excludeConfigUpdate option when AgentConfigUpdate is ported
+  merge(
+    other: ChatContext,
+    options: {
+      excludeFunctionCall?: boolean;
+      excludeInstructions?: boolean;
+    } = {},
+  ): ChatContext {
+    const { excludeFunctionCall = false, excludeInstructions = false } = options;
+    const existingIds = new Set(this._items.map((item) => item.id));
+
+    for (const item of other.items) {
+      if (excludeFunctionCall && ['function_call', 'function_call_output'].includes(item.type)) {
+        continue;
+      }
+
+      if (
+        excludeInstructions &&
+        item.type === 'message' &&
+        (item.role === 'system' || item.role === 'developer')
+      ) {
+        continue;
+      }
+
+      if (existingIds.has(item.id)) {
+        continue;
+      }
+
+      const idx = this.findInsertionIndex(item.createdAt);
+      this._items.splice(idx, 0, item);
+      existingIds.add(item.id);
+    }
+
+    return this;
+  }
+
   truncate(maxItems: number): ChatContext {
     if (maxItems <= 0) return this;
 
@@ -727,6 +779,112 @@ export class ChatContext {
     return true;
   }
 
+  async _summarize(llm: LLM, options: { keepLastTurns?: number } = {}): Promise<ChatContext> {
+    const { keepLastTurns = 2 } = options;
+
+    const toSummarize: ChatMessage[] = [];
+    for (const item of this._items) {
+      if (item.type !== 'message') continue;
+      if (item.role !== 'user' && item.role !== 'assistant') continue;
+      if (item.extra?.is_summary === true) continue;
+
+      const text = (item.textContent ?? '').trim();
+      if (text) {
+        toSummarize.push(item);
+      }
+    }
+
+    if (toSummarize.length === 0) {
+      return this;
+    }
+
+    const tailN = Math.max(0, Math.min(toSummarize.length, keepLastTurns * 2));
+    let head: ChatMessage[];
+    let tail: ChatMessage[];
+    if (tailN === 0) {
+      head = toSummarize;
+      tail = [];
+    } else {
+      head = toSummarize.slice(0, -tailN);
+      tail = toSummarize.slice(-tailN);
+    }
+
+    if (head.length === 0) {
+      return this;
+    }
+
+    const sourceText = head
+      .map((m) => `${m.role}: ${(m.textContent ?? '').trim()}`)
+      .join('\n')
+      .trim();
+
+    if (!sourceText) {
+      return this;
+    }
+
+    // TODO: refactor this into LLMStream.collect API.
+    const promptCtx = new ChatContext();
+    promptCtx.addMessage({
+      role: 'system',
+      content:
+        'Compress older chat history into a short, faithful summary.\n' +
+        'Focus on user goals, constraints, decisions, key facts/preferences/entities, and pending tasks.\n' +
+        'Exclude chit-chat and greetings. Be concise.',
+    });
+    promptCtx.addMessage({
+      role: 'user',
+      content: `Conversation to summarize:\n\n${sourceText}`,
+    });
+
+    const chunks: string[] = [];
+    for await (const chunk of llm.chat({ chatCtx: promptCtx })) {
+      if (chunk.delta?.content) {
+        chunks.push(chunk.delta.content);
+      }
+    }
+
+    const summary = chunks.join('').trim();
+    if (!summary) {
+      return this;
+    }
+
+    const tailStartTs = tail.length > 0 ? tail[0]!.createdAt : Infinity;
+
+    const preserved: ChatItem[] = [];
+    for (const it of this._items) {
+      if (
+        (it.type === 'function_call' || it.type === 'function_call_output') &&
+        it.createdAt < tailStartTs
+      ) {
+        continue;
+      }
+
+      if (it.type === 'message' && (it.role === 'user' || it.role === 'assistant')) {
+        continue;
+      }
+
+      preserved.push(it);
+    }
+
+    this._items = preserved;
+
+    const createdAtHint =
+      tail.length > 0 ? tail[0]!.createdAt - 1e-3 : head[head.length - 1]!.createdAt + 1e-3;
+
+    this.addMessage({
+      role: 'assistant',
+      content: `[history summary]\n${summary}`,
+      createdAt: createdAtHint,
+      extra: { is_summary: true },
+    });
+
+    for (const msg of tail) {
+      this.insert(msg);
+    }
+
+    return this;
+  }
+
   /**
    * Indicates whether the context is read-only
    */

package/src/llm/index.ts

@@ -6,6 +6,7 @@ export {
   isFunctionTool,
   tool,
   ToolError,
+  ToolFlag,
   type AgentHandoff,
   type FunctionTool,
   type ProviderDefinedTool,

package/src/llm/provider_format/index.ts

@@ -3,9 +3,12 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { ChatContext } from '../chat_context.js';
 import { toChatCtx as toChatCtxGoogle } from './google.js';
-import { toChatCtx as toChatCtxOpenai } from './openai.js';
+import {
+  toChatCtx as toChatCtxOpenai,
+  toResponsesChatCtx as toResponsesChatCtxOpenai,
+} from './openai.js';
 
-export type ProviderFormat = 'openai' | 'google';
+export type ProviderFormat = 'openai' | 'openai.responses' | 'google';
 
 export async function toChatCtx(
   format: ProviderFormat,
@@ -15,6 +18,8 @@ export async function toChatCtx(
   switch (format) {
     case 'openai':
       return await toChatCtxOpenai(chatCtx, injectDummyUserMessage);
+    case 'openai.responses':
+      return await toResponsesChatCtxOpenai(chatCtx, injectDummyUserMessage);
     case 'google':
       return await toChatCtxGoogle(chatCtx, injectDummyUserMessage);
     default: