@livekit/agents 1.1.0 → 1.2.1

package/dist/voice/testing/run_result.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/voice/testing/run_result.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { z } from 'zod';\nimport type { AgentHandoffItem, ChatItem, ChatRole } from '../../llm/chat_context.js';\nimport { ChatContext } from '../../llm/chat_context.js';\nimport type { LLM } from '../../llm/llm.js';\nimport { tool } from '../../llm/tool_context.js';\nimport type { Task } from '../../utils.js';\nimport { Future } from '../../utils.js';\nimport type { Agent } from '../agent.js';\nimport { type SpeechHandle, isSpeechHandle } from '../speech_handle.js';\nimport {\n  type AgentHandoffAssertOptions,\n  type AgentHandoffEvent,\n  type ChatMessageEvent,\n  type EventType,\n  type FunctionCallAssertOptions,\n  type FunctionCallEvent,\n  type FunctionCallOutputAssertOptions,\n  type FunctionCallOutputEvent,\n  type MessageAssertOptions,\n  type RunEvent,\n  isAgentHandoffEvent,\n  isChatMessageEvent,\n  isFunctionCallEvent,\n  isFunctionCallOutputEvent,\n} from './types.js';\n\n// Type for agent constructor (used in assertions)\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype AgentConstructor = new (...args: any[]) => Agent;\n// In JS we use a zod schema so runtime validation and TS generic inference stay aligned.\ntype OutputSchema<T> = z.ZodType<T>;\n\n// Environment variable for verbose output\nconst evalsVerbose = parseInt(process.env.LIVEKIT_EVALS_VERBOSE || '0', 10);\n\n/**\n * Result of a test run containing recorded events and assertion utilities.\n *\n * @example\n * ```typescript\n * const result = await session.run({ userInput: 'Hello' });\n * result.expect.nextEvent().isMessage({ role: 'assistant' });\n * result.expect.noMoreEvents();\n * ```\n */\nexport class RunResult<T = unknown> {\n  private _events: RunEvent[] = [];\n  private doneFut = new Future<void>();\n  private userInput?: string;\n  private outputType?: OutputSchema<T>;\n  private finalOutputValue?: T;\n  private hasFinalOutput = false;\n\n  private handles: Set<SpeechHandle | Task<void>> = new Set();\n  private lastSpeechHandle?: SpeechHandle;\n  private runAssert?: RunAssert;\n  // Store per-handle closures so _unwatchHandle can remove callbacks symmetrically.\n  private doneCallbacks = new Map<SpeechHandle | Task<void>, () => void>();\n\n  private readonly itemAddedCallback = (item: ChatItem) => this._itemAdded(item);\n\n  constructor(options?: { userInput?: string; outputType?: OutputSchema<T> }) {\n    this.userInput = options?.userInput;\n    this.outputType = options?.outputType;\n  }\n\n  /**\n   * List of all recorded events generated during the run.\n   */\n  get events(): RunEvent[] {\n    return this._events;\n  }\n\n  /**\n   * Provides an assertion helper for verifying the run events.\n   */\n  get expect(): RunAssert {\n    if (evalsVerbose) {\n      const eventsStr = formatEvents(this._events)\n        .map((line) => `      ${line}`)\n        .join('\\n');\n      console.log(\n        `\\n+ RunResult {\\n    userInput: \"${this.userInput}\"\\n    events: [\\n${eventsStr}\\n    ]\\n  }`,\n      );\n    }\n\n    // Cache the RunAssert so cursor position persists across multiple .expect accesses\n    if (!this.runAssert) {\n      this.runAssert = new RunAssert(this);\n    }\n    return this.runAssert;\n  }\n\n  /**\n   * Returns the final output of the run after completion.\n   */\n  get finalOutput(): T {\n    if (!this.doneFut.done) {\n      throw new Error('cannot retrieve finalOutput, RunResult is not done');\n    }\n\n    if (!this.hasFinalOutput) {\n      throw new Error('no final output');\n    }\n\n    return this.finalOutputValue as T;\n  }\n\n  /**\n   * Indicates whether the run has finished processing all events.\n   */\n  done(): boolean {\n    return this.doneFut.done;\n  }\n\n  /**\n   * Wait for the RunResult to complete. Returns `this` for method chaining.\n   *\n   * @example\n   * ```ts\n   * const result = session.run({ userInput: 'Hi!' });\n   * await result.wait();  // waits for completion\n   * result.expect.nextEvent().isMessage({ role: 'assistant' });\n   * ```\n   */\n  async wait(): Promise<this> {\n    await this.doneFut.await;\n    return this;\n  }\n\n  /**\n   * @internal\n   * Records an agent handoff event.\n   */\n  _agentHandoff(params: { item: AgentHandoffItem; oldAgent?: Agent; newAgent: Agent }): void {\n    const event: AgentHandoffEvent = {\n      type: 'agent_handoff',\n      item: params.item,\n      oldAgent: params.oldAgent,\n      newAgent: params.newAgent,\n    };\n    const index = this._findInsertionIndex(event.item.createdAt);\n    this._events.splice(index, 0, event);\n  }\n\n  /**\n   * @internal\n   * Called when a chat item is added during the run.\n   */\n  _itemAdded(item: ChatItem): void {\n    if (this.doneFut.done) {\n      return;\n    }\n\n    let event: RunEvent | undefined;\n\n    if (item.type === 'message') {\n      event = { type: 'message', item };\n    } else if (item.type === 'function_call') {\n      event = { type: 'function_call', item };\n    } else if (item.type === 'function_call_output') {\n      event = { type: 'function_call_output', item };\n    }\n\n    if (event) {\n      const index = this._findInsertionIndex(item.createdAt);\n      this._events.splice(index, 0, event);\n    }\n  }\n\n  /**\n   * @internal\n   * Watch a speech handle or task for completion.\n   */\n  _watchHandle(handle: SpeechHandle | Task<void>): void {\n    if (this.handles.has(handle)) return;\n\n    this.handles.add(handle);\n\n    if (isSpeechHandle(handle)) {\n      handle._addItemAddedCallback(this.itemAddedCallback);\n    }\n\n    const doneCallback = () => this._markDoneIfNeeded(handle);\n\n    this.doneCallbacks.set(handle, doneCallback);\n    handle.addDoneCallback(doneCallback);\n  }\n\n  /**\n   * @internal\n   * Unwatch a handle.\n   */\n  _unwatchHandle(handle: SpeechHandle | Task<void>): void {\n    this.handles.delete(handle);\n    const doneCallback = this.doneCallbacks.get(handle);\n\n    if (doneCallback) {\n      handle.removeDoneCallback(doneCallback);\n      this.doneCallbacks.delete(handle);\n    }\n\n    if (isSpeechHandle(handle)) {\n      handle._removeItemAddedCallback(this.itemAddedCallback);\n    }\n  }\n\n  /** @internal */\n  _watchedHandleCount(): number {\n    return this.handles.size;\n  }\n\n  /** @internal – Reject the run with an error (e.g. when deferred generateReply fails). */\n  _reject(error: Error): void {\n    if (!this.doneFut.done) {\n      this.doneFut.reject(error);\n    }\n  }\n\n  /** @internal */\n  _markDoneIfNeeded(handle?: SpeechHandle | Task<void> | null): void {\n    if (isSpeechHandle(handle)) {\n      this.lastSpeechHandle = handle;\n    }\n\n    const allDone = [...this.handles].every((h) => (isSpeechHandle(h) ? h.done() : h.done));\n    if (allDone) {\n      this._markDone();\n    }\n  }\n\n  private _markDone(): void {\n    if (this.doneFut.done) {\n      return;\n    }\n\n    if (!this.lastSpeechHandle) {\n      this.doneFut.resolve();\n      return;\n    }\n\n    const finalOutput = this.lastSpeechHandle._maybeRunFinalOutput;\n    if (finalOutput instanceof Error) {\n      this.doneFut.reject(finalOutput);\n      return;\n    }\n\n    if (this.outputType) {\n      const result = this.outputType.safeParse(finalOutput);\n      if (!result.success) {\n        this.doneFut.reject(\n          new Error(`Expected output matching provided zod schema: ${result.error.message}`),\n        );\n        return;\n      }\n      this.finalOutputValue = result.data;\n      this.hasFinalOutput = true;\n      this.doneFut.resolve();\n      return;\n    }\n\n    if (finalOutput !== undefined) {\n      this.finalOutputValue = finalOutput as T;\n      this.hasFinalOutput = true;\n    }\n    this.doneFut.resolve();\n  }\n\n  /**\n   * Find the correct insertion index to maintain chronological order.\n   */\n  private _findInsertionIndex(createdAt: number): number {\n    for (let i = this._events.length - 1; i >= 0; i--) {\n      if (this._events[i]!.item.createdAt <= createdAt) {\n        return i + 1;\n      }\n    }\n    return 0;\n  }\n}\n\n/**\n * Assertion helper for verifying run events in sequence.\n */\nexport class RunAssert {\n  private _events: RunEvent[];\n  private _currentIndex = 0;\n\n  constructor(runResult: RunResult) {\n    this._events = runResult.events;\n  }\n\n  /**\n   * Access a specific event by index for assertions.\n   * Supports negative indices (e.g., -1 for last event).\n   *\n   * @example\n   * ```typescript\n   * result.expect.at(0).isMessage({ role: 'user' });\n   * result.expect.at(-1).isMessage({ role: 'assistant' });\n   * ```\n   */\n  at(index: number): EventAssert {\n    let normalizedIndex = index;\n    if (index < 0) {\n      normalizedIndex = this._events.length + index;\n    }\n\n    if (normalizedIndex < 0 || normalizedIndex >= this._events.length) {\n      this._raiseWithDebugInfo(\n        `at(${index}) out of range (total events: ${this._events.length})`,\n        normalizedIndex,\n      );\n    }\n\n    return new EventAssert(this._events[normalizedIndex]!, this, normalizedIndex);\n  }\n\n  /**\n   * Advance to the next event, optionally filtering by type.\n   *\n   * @example\n   * ```typescript\n   * result.expect.nextEvent().isMessage({ role: 'assistant' });\n   * result.expect.nextEvent({ type: 'function_call' }).isFunctionCall({ name: 'foo' });\n   * ```\n   */\n  nextEvent(options?: { type?: EventType }): EventAssert {\n    while (true) {\n      const evAssert = this._currentEvent();\n      this._currentIndex++;\n\n      if (!options?.type || evAssert.event().type === options.type) {\n        return evAssert;\n      }\n    }\n  }\n\n  /**\n   * Skip a specified number of upcoming events without assertions.\n   *\n   * @example\n   * ```typescript\n   * result.expect.skipNext(2);\n   * ```\n   */\n  skipNext(count: number = 1): this {\n    for (let i = 0; i < count; i++) {\n      if (this._currentIndex >= this._events.length) {\n        this._raiseWithDebugInfo(`Tried to skip ${count} event(s), but only ${i} were available.`);\n      }\n      this._currentIndex++;\n    }\n    return this;\n  }\n\n  /**\n   * Conditionally skip the next event if it matches the specified criteria.\n   * Returns the event assertion if matched and skipped, or undefined if not matched.\n   *\n   * @example\n   * ```typescript\n   * // Skip optional assistant message before function call\n   * result.expect.skipNextEventIf({ type: 'message', role: 'assistant' });\n   * result.expect.nextEvent().isFunctionCall({ name: 'foo' });\n   * ```\n   */\n  skipNextEventIf(\n    options:\n      | { type: 'message'; role?: ChatRole }\n      | { type: 'function_call'; name?: string; args?: Record<string, unknown> }\n      | { type: 'function_call_output'; output?: string; isError?: boolean }\n      | { type: 'agent_handoff'; newAgentType?: AgentConstructor },\n  ):\n    | MessageAssert\n    | FunctionCallAssert\n    | FunctionCallOutputAssert\n    | AgentHandoffAssert\n    | undefined {\n    if (this._currentIndex >= this._events.length) {\n      return undefined;\n    }\n\n    try {\n      const evAssert = this._currentEvent();\n\n      if (options.type === 'message') {\n        const { role } = options;\n        const result = evAssert.isMessage({ role });\n        this._currentIndex++;\n        return result;\n      } else if (options.type === 'function_call') {\n        const { name, args } = options;\n        const result = evAssert.isFunctionCall({\n          name,\n          args,\n        });\n        this._currentIndex++;\n        return result;\n      } else if (options.type === 'function_call_output') {\n        const { output, isError } = options;\n        const result = evAssert.isFunctionCallOutput({\n          output,\n          isError,\n        });\n        this._currentIndex++;\n        return result;\n      } else if (options.type === 'agent_handoff') {\n        const { newAgentType } = options;\n        const result = evAssert.isAgentHandoff({ newAgentType });\n        this._currentIndex++;\n        return result;\n      }\n    } catch {\n      // Assertion failed, event doesn't match criteria\n      return undefined;\n    }\n\n    return undefined;\n  }\n\n  /**\n   * Get an EventRangeAssert for a range of events.\n   * Similar to Python's slice access: expect[0:3] or expect[:]\n   *\n   * @param start - Start index (inclusive), defaults to 0\n   * @param end - End index (exclusive), defaults to events.length\n   *\n   * @example\n   * ```typescript\n   * // Search all events\n   * result.expect.range().containsFunctionCall({ name: 'foo' });\n   * // Search first 3 events\n   * result.expect.range(0, 3).containsMessage({ role: 'assistant' });\n   * ```\n   */\n  range(start?: number, end?: number): EventRangeAssert {\n    const startIdx = start ?? 0;\n    const endIdx = end ?? this._events.length;\n    const events = this._events.slice(startIdx, endIdx);\n    return new EventRangeAssert(events, this, { start: startIdx, end: endIdx });\n  }\n\n  /**\n   * Assert that a function call matching criteria exists anywhere in the events.\n   *\n   * @example\n   * ```typescript\n   * result.expect.containsFunctionCall({ name: 'order_item' });\n   * ```\n   */\n  containsFunctionCall(options?: FunctionCallAssertOptions): FunctionCallAssert {\n    return this.range().containsFunctionCall(options);\n  }\n\n  /**\n   * Assert that a message matching criteria exists anywhere in the events.\n   *\n   * @example\n   * ```typescript\n   * result.expect.containsMessage({ role: 'assistant' });\n   * ```\n   */\n  containsMessage(options?: MessageAssertOptions): MessageAssert {\n    return this.range().containsMessage(options);\n  }\n\n  /**\n   * Assert that a function call output matching criteria exists anywhere in the events.\n   *\n   * @example\n   * ```typescript\n   * result.expect.containsFunctionCallOutput({ isError: false });\n   * ```\n   */\n  containsFunctionCallOutput(options?: FunctionCallOutputAssertOptions): FunctionCallOutputAssert {\n    return this.range().containsFunctionCallOutput(options);\n  }\n\n  /**\n   * Assert that an agent handoff matching criteria exists anywhere in the events.\n   *\n   * @example\n   * ```typescript\n   * result.expect.containsAgentHandoff({ newAgentType: MyAgent });\n   * ```\n   */\n  containsAgentHandoff(options?: AgentHandoffAssertOptions): AgentHandoffAssert {\n    return this.range().containsAgentHandoff(options);\n  }\n\n  /**\n   * Assert that there are no further events.\n   *\n   * @example\n   * ```typescript\n   * result.expect.noMoreEvents();\n   * ```\n   */\n  noMoreEvents(): void {\n    if (this._currentIndex < this._events.length) {\n      const event = this._events[this._currentIndex]!;\n      this._raiseWithDebugInfo(`Expected no more events, but found: ${event.type}`);\n    }\n  }\n\n  private _currentEvent(): EventAssert {\n    if (this._currentIndex >= this._events.length) {\n      this._raiseWithDebugInfo('Expected another event, but none left.');\n    }\n    return this.at(this._currentIndex);\n  }\n\n  /** @internal */\n  _raiseWithDebugInfo(message: string, index?: number): never {\n    const markerIndex = index ?? this._currentIndex;\n    const eventsStr = formatEvents(this._events, markerIndex).join('\\n');\n    throw new AssertionError(`${message}\\nContext around failure:\\n${eventsStr}`);\n  }\n}\n\n/**\n * Assertion wrapper for a single event.\n */\nexport class EventAssert {\n  protected _event: RunEvent;\n  protected _parent: RunAssert;\n  protected _index: number;\n\n  constructor(event: RunEvent, parent: RunAssert, index: number) {\n    this._event = event;\n    this._parent = parent;\n    this._index = index;\n  }\n\n  /**\n   * Get the underlying event.\n   */\n  event(): RunEvent {\n    return this._event;\n  }\n\n  protected _raise(message: string): never {\n    this._parent._raiseWithDebugInfo(message, this._index);\n  }\n\n  /**\n   * Verify this event is a message with optional role matching.\n   *\n   * @example\n   * ```typescript\n   * result.expect.nextEvent().isMessage({ role: 'assistant' });\n   * ```\n   */\n  isMessage(options?: MessageAssertOptions): MessageAssert {\n    if (!isChatMessageEvent(this._event)) {\n      this._raise(`Expected ChatMessageEvent, got ${this._event.type}`);\n    }\n\n    if (options?.role && this._event.item.role !== options.role) {\n      this._raise(`Expected role '${options.role}', got '${this._event.item.role}'`);\n    }\n\n    return new MessageAssert(this._event, this._parent, this._index);\n  }\n\n  /**\n   * Verify this event is a function call with optional name/args matching.\n   *\n   * @example\n   * ```typescript\n   * result.expect.nextEvent().isFunctionCall({ name: 'order_item', args: { id: 'big_mac' } });\n   * ```\n   */\n  isFunctionCall(options?: FunctionCallAssertOptions): FunctionCallAssert {\n    if (!isFunctionCallEvent(this._event)) {\n      this._raise(`Expected FunctionCallEvent, got ${this._event.type}`);\n    }\n\n    if (options?.name && this._event.item.name !== options.name) {\n      this._raise(`Expected call name '${options.name}', got '${this._event.item.name}'`);\n    }\n\n    if (options?.args) {\n      let actual: Record<string, unknown>;\n      try {\n        actual = JSON.parse(this._event.item.args);\n      } catch {\n        this._raise(`Failed to parse function call arguments: ${this._event.item.args}`);\n      }\n\n      for (const [key, value] of Object.entries(options.args)) {\n        if (!(key in actual) || actual[key] !== value) {\n          this._raise(\n            `For key '${key}', expected ${JSON.stringify(value)}, got ${JSON.stringify(actual[key])}`,\n          );\n        }\n      }\n    }\n\n    return new FunctionCallAssert(this._event, this._parent, this._index);\n  }\n\n  /**\n   * Verify this event is a function call output with optional matching.\n   *\n   * @example\n   * ```typescript\n   * result.expect.nextEvent().isFunctionCallOutput({ isError: false });\n   * ```\n   */\n  isFunctionCallOutput(options?: FunctionCallOutputAssertOptions): FunctionCallOutputAssert {\n    if (!isFunctionCallOutputEvent(this._event)) {\n      this._raise(`Expected FunctionCallOutputEvent, got ${this._event.type}`);\n    }\n\n    if (options?.output !== undefined && this._event.item.output !== options.output) {\n      this._raise(`Expected output '${options.output}', got '${this._event.item.output}'`);\n    }\n\n    if (options?.isError !== undefined && this._event.item.isError !== options.isError) {\n      this._raise(`Expected isError=${options.isError}, got ${this._event.item.isError}`);\n    }\n\n    return new FunctionCallOutputAssert(this._event, this._parent, this._index);\n  }\n\n  /**\n   * Verify this event is an agent handoff with optional type matching.\n   *\n   * @example\n   * ```typescript\n   * result.expect.nextEvent().isAgentHandoff({ newAgentType: MyAgent });\n   * ```\n   */\n  isAgentHandoff(options?: AgentHandoffAssertOptions): AgentHandoffAssert {\n    if (!isAgentHandoffEvent(this._event)) {\n      this._raise(`Expected AgentHandoffEvent, got ${this._event.type}`);\n    }\n\n    const event = this._event;\n\n    if (options?.newAgentType) {\n      const actualType = event.newAgent.constructor.name;\n      if (!(event.newAgent instanceof options.newAgentType)) {\n        this._raise(`Expected new_agent '${options.newAgentType.name}', got '${actualType}'`);\n      }\n    }\n\n    return new AgentHandoffAssert(event, this._parent, this._index);\n  }\n}\n\n/**\n * Assertion wrapper for a range of events.\n * Provides contains*() methods to search within the range.\n */\nexport class EventRangeAssert {\n  private _events: RunEvent[];\n  private _parent: RunAssert;\n  private _range: { start: number; end: number };\n\n  constructor(events: RunEvent[], parent: RunAssert, range: { start: number; end: number }) {\n    this._events = events;\n    this._parent = parent;\n    this._range = range;\n  }\n\n  /**\n   * Assert that a function call matching criteria exists in this event range.\n   *\n   * @example\n   * ```typescript\n   * result.expect.range(0, 3).containsFunctionCall({ name: 'foo' });\n   * ```\n   */\n  containsFunctionCall(options?: FunctionCallAssertOptions): FunctionCallAssert {\n    for (let idx = 0; idx < this._events.length; idx++) {\n      const ev = this._events[idx]!;\n      const candidate = new EventAssert(ev, this._parent, this._range.start + idx);\n      try {\n        return candidate.isFunctionCall(options);\n      } catch {\n        // Continue searching\n      }\n    }\n\n    this._parent._raiseWithDebugInfo(\n      `No FunctionCallEvent satisfying criteria found in range [${this._range.start}:${this._range.end}]`,\n    );\n  }\n\n  /**\n   * Assert that a message matching criteria exists in this event range.\n   *\n   * @example\n   * ```typescript\n   * result.expect.range(0, 2).containsMessage({ role: 'assistant' });\n   * ```\n   */\n  containsMessage(options?: MessageAssertOptions): MessageAssert {\n    for (let idx = 0; idx < this._events.length; idx++) {\n      const ev = this._events[idx]!;\n      const candidate = new EventAssert(ev, this._parent, this._range.start + idx);\n      try {\n        return candidate.isMessage(options);\n      } catch {\n        // Continue searching\n      }\n    }\n\n    this._parent._raiseWithDebugInfo(\n      `No ChatMessageEvent matching criteria found in range [${this._range.start}:${this._range.end}]`,\n    );\n  }\n\n  /**\n   * Assert that a function call output matching criteria exists in this event range.\n   *\n   * @example\n   * ```typescript\n   * result.expect.range(1, 4).containsFunctionCallOutput({ isError: true });\n   * ```\n   */\n  containsFunctionCallOutput(options?: FunctionCallOutputAssertOptions): FunctionCallOutputAssert {\n    for (let idx = 0; idx < this._events.length; idx++) {\n      const ev = this._events[idx]!;\n      const candidate = new EventAssert(ev, this._parent, this._range.start + idx);\n      try {\n        return candidate.isFunctionCallOutput(options);\n      } catch {\n        // Continue searching\n      }\n    }\n\n    this._parent._raiseWithDebugInfo(\n      `No FunctionCallOutputEvent matching criteria found in range [${this._range.start}:${this._range.end}]`,\n    );\n  }\n\n  /**\n   * Assert that an agent handoff matching criteria exists in this event range.\n   *\n   * @example\n   * ```typescript\n   * result.expect.range(0, 3).containsAgentHandoff({ newAgentType: MyAgent });\n   * ```\n   */\n  containsAgentHandoff(options?: AgentHandoffAssertOptions): AgentHandoffAssert {\n    for (let idx = 0; idx < this._events.length; idx++) {\n      const ev = this._events[idx]!;\n      const candidate = new EventAssert(ev, this._parent, this._range.start + idx);\n      try {\n        return candidate.isAgentHandoff(options);\n      } catch {\n        // Continue searching\n      }\n    }\n\n    this._parent._raiseWithDebugInfo(\n      `No AgentHandoffEvent matching criteria found in range [${this._range.start}:${this._range.end}]`,\n    );\n  }\n}\n\n/**\n * Assertion wrapper for message events.\n */\nexport class MessageAssert extends EventAssert {\n  protected declare _event: ChatMessageEvent;\n\n  constructor(event: ChatMessageEvent, parent: RunAssert, index: number) {\n    super(event, parent, index);\n  }\n\n  override event(): ChatMessageEvent {\n    return this._event;\n  }\n\n  /**\n   * Evaluate whether the message fulfills the given intent using an LLM.\n   *\n   * @param llm - LLM instance for judgment\n   * @param options - Options containing the intent description\n   * @returns Self for chaining further assertions\n   *\n   * @example\n   * ```typescript\n   * await result.expect\n   *   .nextEvent()\n   *   .isMessage({ role: 'assistant' })\n   *   .judge(llm, { intent: 'should ask for the drink size' });\n   * ```\n   */\n  async judge(llm: LLM, options: { intent: string }): Promise<MessageAssert> {\n    const { intent } = options;\n\n    // Extract text content from message\n    const content = this._event.item.content;\n    const msgContent =\n      typeof content === 'string'\n        ? content\n        : Array.isArray(content)\n          ? content.filter((c): c is string => typeof c === 'string').join(' ')\n          : '';\n\n    if (!msgContent) {\n      this._raise('The chat message is empty.');\n    }\n\n    if (!intent) {\n      this._raise('Intent is required to judge the message.');\n    }\n\n    // Create the check_intent tool\n    const checkIntentTool = tool({\n      description:\n        'Determines whether the message correctly fulfills the given intent. ' +\n        'Returns success=true if the message satisfies the intent, false otherwise. ' +\n        'Provide a concise reason justifying the result.',\n      parameters: z.object({\n        success: z.boolean().describe('Whether the message satisfies the intent'),\n        reason: z.string().describe('A concise explanation justifying the result'),\n      }),\n      execute: async ({ success, reason }: { success: boolean; reason: string }) => {\n        return { success, reason };\n      },\n    });\n\n    // Create chat context for the judge\n    const chatCtx = ChatContext.empty();\n    chatCtx.addMessage({\n      role: 'system',\n      content:\n        'You are a test evaluator for conversational agents.\\n' +\n        'You will be shown a message and a target intent. Determine whether the message accomplishes the intent.\\n' +\n        'Only respond by calling the `check_intent(success: bool, reason: str)` function with your final judgment.\\n' +\n        'Be strict: if the message does not clearly fulfill the intent, return `success = false` and explain why.',\n    });\n    chatCtx.addMessage({\n      role: 'user',\n      content:\n        'Check if the following message fulfills the given intent.\\n\\n' +\n        `Intent:\\n${intent}\\n\\n` +\n        `Message:\\n${msgContent}`,\n    });\n\n    // Call the LLM with the check_intent tool\n    let toolArgs: { success: boolean; reason: string } | undefined;\n\n    const stream = llm.chat({\n      chatCtx,\n      toolCtx: { check_intent: checkIntentTool },\n      toolChoice: { type: 'function', function: { name: 'check_intent' } },\n      extraKwargs: { temperature: 0 },\n    });\n\n    for await (const chunk of stream) {\n      if (!chunk.delta) continue;\n\n      if (chunk.delta.toolCalls && chunk.delta.toolCalls.length > 0) {\n        const toolCall = chunk.delta.toolCalls[0]!;\n        if (toolCall.args) {\n          try {\n            toolArgs = JSON.parse(toolCall.args);\n          } catch {\n            // Args might be streamed incrementally, keep the last valid parse\n          }\n        }\n      }\n    }\n\n    if (!toolArgs) {\n      this._raise('LLM did not return any arguments for evaluation.');\n    }\n\n    const { success, reason } = toolArgs;\n\n    if (!success) {\n      this._raise(`Judgment failed: ${reason}`);\n    } else if (evalsVerbose) {\n      const printMsg =\n        msgContent.length > 30 ? msgContent.slice(0, 30).replace(/\\n/g, '\\\\n') + '...' : msgContent;\n      console.log(`- Judgment succeeded for \\`${printMsg}\\`: \\`${reason}\\``);\n    }\n\n    return this;\n  }\n}\n\n/**\n * Assertion wrapper for function call events.\n */\nexport class FunctionCallAssert extends EventAssert {\n  protected declare _event: FunctionCallEvent;\n\n  constructor(event: FunctionCallEvent, parent: RunAssert, index: number) {\n    super(event, parent, index);\n  }\n\n  override event(): FunctionCallEvent {\n    return this._event;\n  }\n}\n\n/**\n * Assertion wrapper for function call output events.\n */\nexport class FunctionCallOutputAssert extends EventAssert {\n  protected declare _event: FunctionCallOutputEvent;\n\n  constructor(event: FunctionCallOutputEvent, parent: RunAssert, index: number) {\n    super(event, parent, index);\n  }\n\n  override event(): FunctionCallOutputEvent {\n    return this._event;\n  }\n}\n\n/**\n * Assertion wrapper for agent handoff events.\n */\nexport class AgentHandoffAssert extends EventAssert {\n  protected declare _event: AgentHandoffEvent;\n\n  constructor(event: AgentHandoffEvent, parent: RunAssert, index: number) {\n    super(event, parent, index);\n  }\n\n  override event(): AgentHandoffEvent {\n    return this._event;\n  }\n}\n\n/**\n * Custom assertion error for test failures.\n */\nexport class AssertionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'AssertionError';\n    Error.captureStackTrace?.(this, AssertionError);\n  }\n}\n\n// TODO: mockTools() utility for mocking tool implementations in tests\n// Will be implemented for test suites.\n// See Python run_result.py lines 1010-1031 for reference.\n\n/**\n * Format events for debug output, optionally marking a selected index.\n */\nfunction formatEvents(events: RunEvent[], selectedIndex?: number): string[] {\n  const lines: string[] = [];\n\n  for (let i = 0; i < events.length; i++) {\n    const event = events[i]!;\n    let prefix = '';\n    if (selectedIndex !== undefined) {\n      prefix = i === selectedIndex ? '>>>' : '   ';\n    }\n\n    let line: string;\n    if (isChatMessageEvent(event)) {\n      const { role, content, interrupted } = event.item;\n      const textContent =\n        typeof content === 'string'\n          ? content\n          : Array.isArray(content)\n            ? content.filter((c): c is string => typeof c === 'string').join(' ')\n            : '';\n      const truncated = textContent.length > 50 ? textContent.slice(0, 50) + '...' : textContent;\n      line = `${prefix}[${i}] { type: \"message\", role: \"${role}\", content: \"${truncated}\", interrupted: ${interrupted} }`;\n    } else if (isFunctionCallEvent(event)) {\n      const { name, args } = event.item;\n      line = `${prefix}[${i}] { type: \"function_call\", name: \"${name}\", args: ${args} }`;\n    } else if (isFunctionCallOutputEvent(event)) {\n      const { output, isError } = event.item;\n      const truncated = output.length > 50 ? output.slice(0, 50) + '...' : output;\n      line = `${prefix}[${i}] { type: \"function_call_output\", output: \"${truncated}\", isError: ${isError} }`;\n    } else if (isAgentHandoffEvent(event)) {\n      line = `${prefix}[${i}] { type: \"agent_handoff\", oldAgent: \"${event.oldAgent?.constructor.name}\", newAgent: \"${event.newAgent.constructor.name}\" }`;\n    } else {\n      line = `${prefix}[${i}] ${event}`;\n    }\n\n    lines.push(line);\n  }\n\n  return lines;\n}\n"],"mappings":"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","names":["success","reason"]}

package/dist/voice/testing/types.cjs

@@ -0,0 +1,46 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+__export(types_exports, {
+  isAgentHandoffEvent: () => isAgentHandoffEvent,
+  isChatMessageEvent: () => isChatMessageEvent,
+  isFunctionCallEvent: () => isFunctionCallEvent,
+  isFunctionCallOutputEvent: () => isFunctionCallOutputEvent
+});
+module.exports = __toCommonJS(types_exports);
+function isChatMessageEvent(event) {
+  return event.type === "message";
+}
+function isFunctionCallEvent(event) {
+  return event.type === "function_call";
+}
+function isFunctionCallOutputEvent(event) {
+  return event.type === "function_call_output";
+}
+function isAgentHandoffEvent(event) {
+  return event.type === "agent_handoff";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isAgentHandoffEvent,
+  isChatMessageEvent,
+  isFunctionCallEvent,
+  isFunctionCallOutputEvent
+});
+//# sourceMappingURL=types.cjs.map

package/dist/voice/testing/types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/voice/testing/types.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type {\n  AgentHandoffItem,\n  ChatMessage,\n  ChatRole,\n  FunctionCall,\n  FunctionCallOutput,\n} from '../../llm/chat_context.js';\nimport type { Agent } from '../agent.js';\n\n/**\n * Event representing an assistant or user message in the conversation.\n */\nexport interface ChatMessageEvent {\n  type: 'message';\n  item: ChatMessage;\n}\n\n/**\n * Event representing a function/tool call initiated by the LLM.\n */\nexport interface FunctionCallEvent {\n  type: 'function_call';\n  item: FunctionCall;\n}\n\n/**\n * Event representing the output/result of a function call.\n */\nexport interface FunctionCallOutputEvent {\n  type: 'function_call_output';\n  item: FunctionCallOutput;\n}\n\n/**\n * Event representing an agent handoff (switching from one agent to another).\n */\nexport interface AgentHandoffEvent {\n  type: 'agent_handoff';\n  item: AgentHandoffItem;\n  oldAgent?: Agent;\n  newAgent: Agent;\n}\n\n/**\n * Union type of all possible run events that can occur during a test run.\n */\nexport type RunEvent =\n  | ChatMessageEvent\n  | FunctionCallEvent\n  | FunctionCallOutputEvent\n  | AgentHandoffEvent;\n\n/**\n * Type guard to check if an event is a ChatMessageEvent.\n */\nexport function isChatMessageEvent(event: RunEvent): event is ChatMessageEvent {\n  return event.type === 'message';\n}\n\n/**\n * Type guard to check if an event is a FunctionCallEvent.\n */\nexport function isFunctionCallEvent(event: RunEvent): event is FunctionCallEvent {\n  return event.type === 'function_call';\n}\n\n/**\n * Type guard to check if an event is a FunctionCallOutputEvent.\n */\nexport function isFunctionCallOutputEvent(event: RunEvent): event is FunctionCallOutputEvent {\n  return event.type === 'function_call_output';\n}\n\n/**\n * Type guard to check if an event is an AgentHandoffEvent.\n */\nexport function isAgentHandoffEvent(event: RunEvent): event is AgentHandoffEvent {\n  return event.type === 'agent_handoff';\n}\n\n/**\n * Options for message assertion.\n */\nexport interface MessageAssertOptions {\n  role?: ChatRole;\n}\n\n/**\n * Options for function call assertion.\n */\nexport interface FunctionCallAssertOptions {\n  name?: string;\n  args?: Record<string, unknown>;\n}\n\n/**\n * Options for function call output assertion.\n */\nexport interface FunctionCallOutputAssertOptions {\n  output?: string;\n  isError?: boolean;\n}\n\n/**\n * Options for agent handoff assertion.\n */\nexport interface AgentHandoffAssertOptions {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  newAgentType?: new (...args: any[]) => Agent;\n}\n\n/**\n * Event type literals for type-safe event filtering.\n */\nexport type EventType = 'message' | 'function_call' | 'function_call_output' | 'agent_handoff';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA0DO,SAAS,mBAAmB,OAA4C;AAC7E,SAAO,MAAM,SAAS;AACxB;AAKO,SAAS,oBAAoB,OAA6C;AAC/E,SAAO,MAAM,SAAS;AACxB;AAKO,SAAS,0BAA0B,OAAmD;AAC3F,SAAO,MAAM,SAAS;AACxB;AAKO,SAAS,oBAAoB,OAA6C;AAC/E,SAAO,MAAM,SAAS;AACxB;","names":[]}

package/dist/voice/testing/types.d.cts

@@ -0,0 +1,83 @@
+import type { AgentHandoffItem, ChatMessage, ChatRole, FunctionCall, FunctionCallOutput } from '../../llm/chat_context.js';
+import type { Agent } from '../agent.js';
+/**
+ * Event representing an assistant or user message in the conversation.
+ */
+export interface ChatMessageEvent {
+    type: 'message';
+    item: ChatMessage;
+}
+/**
+ * Event representing a function/tool call initiated by the LLM.
+ */
+export interface FunctionCallEvent {
+    type: 'function_call';
+    item: FunctionCall;
+}
+/**
+ * Event representing the output/result of a function call.
+ */
+export interface FunctionCallOutputEvent {
+    type: 'function_call_output';
+    item: FunctionCallOutput;
+}
+/**
+ * Event representing an agent handoff (switching from one agent to another).
+ */
+export interface AgentHandoffEvent {
+    type: 'agent_handoff';
+    item: AgentHandoffItem;
+    oldAgent?: Agent;
+    newAgent: Agent;
+}
+/**
+ * Union type of all possible run events that can occur during a test run.
+ */
+export type RunEvent = ChatMessageEvent | FunctionCallEvent | FunctionCallOutputEvent | AgentHandoffEvent;
+/**
+ * Type guard to check if an event is a ChatMessageEvent.
+ */
+export declare function isChatMessageEvent(event: RunEvent): event is ChatMessageEvent;
+/**
+ * Type guard to check if an event is a FunctionCallEvent.
+ */
+export declare function isFunctionCallEvent(event: RunEvent): event is FunctionCallEvent;
+/**
+ * Type guard to check if an event is a FunctionCallOutputEvent.
+ */
+export declare function isFunctionCallOutputEvent(event: RunEvent): event is FunctionCallOutputEvent;
+/**
+ * Type guard to check if an event is an AgentHandoffEvent.
+ */
+export declare function isAgentHandoffEvent(event: RunEvent): event is AgentHandoffEvent;
+/**
+ * Options for message assertion.
+ */
+export interface MessageAssertOptions {
+    role?: ChatRole;
+}
+/**
+ * Options for function call assertion.
+ */
+export interface FunctionCallAssertOptions {
+    name?: string;
+    args?: Record<string, unknown>;
+}
+/**
+ * Options for function call output assertion.
+ */
+export interface FunctionCallOutputAssertOptions {
+    output?: string;
+    isError?: boolean;
+}
+/**
+ * Options for agent handoff assertion.
+ */
+export interface AgentHandoffAssertOptions {
+    newAgentType?: new (...args: any[]) => Agent;
+}
+/**
+ * Event type literals for type-safe event filtering.
+ */
+export type EventType = 'message' | 'function_call' | 'function_call_output' | 'agent_handoff';
+//# sourceMappingURL=types.d.ts.map

package/dist/voice/testing/types.d.ts

@@ -0,0 +1,83 @@
+import type { AgentHandoffItem, ChatMessage, ChatRole, FunctionCall, FunctionCallOutput } from '../../llm/chat_context.js';
+import type { Agent } from '../agent.js';
+/**
+ * Event representing an assistant or user message in the conversation.
+ */
+export interface ChatMessageEvent {
+    type: 'message';
+    item: ChatMessage;
+}
+/**
+ * Event representing a function/tool call initiated by the LLM.
+ */
+export interface FunctionCallEvent {
+    type: 'function_call';
+    item: FunctionCall;
+}
+/**
+ * Event representing the output/result of a function call.
+ */
+export interface FunctionCallOutputEvent {
+    type: 'function_call_output';
+    item: FunctionCallOutput;
+}
+/**
+ * Event representing an agent handoff (switching from one agent to another).
+ */
+export interface AgentHandoffEvent {
+    type: 'agent_handoff';
+    item: AgentHandoffItem;
+    oldAgent?: Agent;
+    newAgent: Agent;
+}
+/**
+ * Union type of all possible run events that can occur during a test run.
+ */
+export type RunEvent = ChatMessageEvent | FunctionCallEvent | FunctionCallOutputEvent | AgentHandoffEvent;
+/**
+ * Type guard to check if an event is a ChatMessageEvent.
+ */
+export declare function isChatMessageEvent(event: RunEvent): event is ChatMessageEvent;
+/**
+ * Type guard to check if an event is a FunctionCallEvent.
+ */
+export declare function isFunctionCallEvent(event: RunEvent): event is FunctionCallEvent;
+/**
+ * Type guard to check if an event is a FunctionCallOutputEvent.
+ */
+export declare function isFunctionCallOutputEvent(event: RunEvent): event is FunctionCallOutputEvent;
+/**
+ * Type guard to check if an event is an AgentHandoffEvent.
+ */
+export declare function isAgentHandoffEvent(event: RunEvent): event is AgentHandoffEvent;
+/**
+ * Options for message assertion.
+ */
+export interface MessageAssertOptions {
+    role?: ChatRole;
+}
+/**
+ * Options for function call assertion.
+ */
+export interface FunctionCallAssertOptions {
+    name?: string;
+    args?: Record<string, unknown>;
+}
+/**
+ * Options for function call output assertion.
+ */
+export interface FunctionCallOutputAssertOptions {
+    output?: string;
+    isError?: boolean;
+}
+/**
+ * Options for agent handoff assertion.
+ */
+export interface AgentHandoffAssertOptions {
+    newAgentType?: new (...args: any[]) => Agent;
+}
+/**
+ * Event type literals for type-safe event filtering.
+ */
+export type EventType = 'message' | 'function_call' | 'function_call_output' | 'agent_handoff';
+//# sourceMappingURL=types.d.ts.map

package/dist/voice/testing/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/voice/testing/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,IAAI,EAAE,kBAAkB,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,uBAAuB,GACvB,iBAAiB,CAAC;AAEtB;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,IAAI,gBAAgB,CAE7E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,IAAI,iBAAiB,CAE/E;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,IAAI,uBAAuB,CAE3F;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,IAAI,iBAAiB,CAE/E;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IAExC,YAAY,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,KAAK,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,eAAe,GAAG,sBAAsB,GAAG,eAAe,CAAC"}

package/dist/voice/testing/types.js

@@ -0,0 +1,19 @@
+function isChatMessageEvent(event) {
+  return event.type === "message";
+}
+function isFunctionCallEvent(event) {
+  return event.type === "function_call";
+}
+function isFunctionCallOutputEvent(event) {
+  return event.type === "function_call_output";
+}
+function isAgentHandoffEvent(event) {
+  return event.type === "agent_handoff";
+}
+export {
+  isAgentHandoffEvent,
+  isChatMessageEvent,
+  isFunctionCallEvent,
+  isFunctionCallOutputEvent
+};
+//# sourceMappingURL=types.js.map

package/dist/voice/testing/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/voice/testing/types.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type {\n  AgentHandoffItem,\n  ChatMessage,\n  ChatRole,\n  FunctionCall,\n  FunctionCallOutput,\n} from '../../llm/chat_context.js';\nimport type { Agent } from '../agent.js';\n\n/**\n * Event representing an assistant or user message in the conversation.\n */\nexport interface ChatMessageEvent {\n  type: 'message';\n  item: ChatMessage;\n}\n\n/**\n * Event representing a function/tool call initiated by the LLM.\n */\nexport interface FunctionCallEvent {\n  type: 'function_call';\n  item: FunctionCall;\n}\n\n/**\n * Event representing the output/result of a function call.\n */\nexport interface FunctionCallOutputEvent {\n  type: 'function_call_output';\n  item: FunctionCallOutput;\n}\n\n/**\n * Event representing an agent handoff (switching from one agent to another).\n */\nexport interface AgentHandoffEvent {\n  type: 'agent_handoff';\n  item: AgentHandoffItem;\n  oldAgent?: Agent;\n  newAgent: Agent;\n}\n\n/**\n * Union type of all possible run events that can occur during a test run.\n */\nexport type RunEvent =\n  | ChatMessageEvent\n  | FunctionCallEvent\n  | FunctionCallOutputEvent\n  | AgentHandoffEvent;\n\n/**\n * Type guard to check if an event is a ChatMessageEvent.\n */\nexport function isChatMessageEvent(event: RunEvent): event is ChatMessageEvent {\n  return event.type === 'message';\n}\n\n/**\n * Type guard to check if an event is a FunctionCallEvent.\n */\nexport function isFunctionCallEvent(event: RunEvent): event is FunctionCallEvent {\n  return event.type === 'function_call';\n}\n\n/**\n * Type guard to check if an event is a FunctionCallOutputEvent.\n */\nexport function isFunctionCallOutputEvent(event: RunEvent): event is FunctionCallOutputEvent {\n  return event.type === 'function_call_output';\n}\n\n/**\n * Type guard to check if an event is an AgentHandoffEvent.\n */\nexport function isAgentHandoffEvent(event: RunEvent): event is AgentHandoffEvent {\n  return event.type === 'agent_handoff';\n}\n\n/**\n * Options for message assertion.\n */\nexport interface MessageAssertOptions {\n  role?: ChatRole;\n}\n\n/**\n * Options for function call assertion.\n */\nexport interface FunctionCallAssertOptions {\n  name?: string;\n  args?: Record<string, unknown>;\n}\n\n/**\n * Options for function call output assertion.\n */\nexport interface FunctionCallOutputAssertOptions {\n  output?: string;\n  isError?: boolean;\n}\n\n/**\n * Options for agent handoff assertion.\n */\nexport interface AgentHandoffAssertOptions {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  newAgentType?: new (...args: any[]) => Agent;\n}\n\n/**\n * Event type literals for type-safe event filtering.\n */\nexport type EventType = 'message' | 'function_call' | 'function_call_output' | 'agent_handoff';\n"],"mappings":"AA0DO,SAAS,mBAAmB,OAA4C;AAC7E,SAAO,MAAM,SAAS;AACxB;AAKO,SAAS,oBAAoB,OAA6C;AAC/E,SAAO,MAAM,SAAS;AACxB;AAKO,SAAS,0BAA0B,OAAmD;AAC3F,SAAO,MAAM,SAAS;AACxB;AAKO,SAAS,oBAAoB,OAA6C;AAC/E,SAAO,MAAM,SAAS;AACxB;","names":[]}

package/dist/voice/transcription/synchronizer.cjs

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var synchronizer_exports = {};
 __export(synchronizer_exports, {
+  SpeakingRateData: () => SpeakingRateData,
   TranscriptionSynchronizer: () => TranscriptionSynchronizer,
   defaultTextSyncOptions: () => defaultTextSyncOptions
 });
@@ -28,6 +29,78 @@ var import_tokenize = require("../../tokenize/index.cjs");
 var import_utils = require("../../utils.cjs");
 var import_io = require("../io.cjs");
 const STANDARD_SPEECH_RATE = 3.83;
+class SpeakingRateData {
+  /** Timestamps of the speaking rate. */
+  timestamps = [];
+  /** Speed at the timestamp. */
+  speakingRate = [];
+  /** Accumulated speaking units up to the timestamp. */
+  speakIntegrals = [];
+  /** Buffer for text without timing annotations yet. */
+  textBuffer = [];
+  /**
+   * Add by speaking rate estimation.
+   */
+  addByRate(timestamp, speakingRate) {
+    const integral = this.speakIntegrals.length > 0 ? this.speakIntegrals[this.speakIntegrals.length - 1] : 0;
+    const dt = timestamp - this.pushedDuration;
+    const newIntegral = integral + speakingRate * dt;
+    this.timestamps.push(timestamp);
+    this.speakingRate.push(speakingRate);
+    this.speakIntegrals.push(newIntegral);
+  }
+  /**
+   * Add annotation from TimedString with start_time/end_time.
+   */
+  addByAnnotation(text, startTime, endTime) {
+    if (startTime !== void 0) {
+      const integral = this.speakIntegrals.length > 0 ? this.speakIntegrals[this.speakIntegrals.length - 1] : 0;
+      const dt = startTime - this.pushedDuration;
+      const textLen = this.textBuffer.reduce((sum, t) => sum + t.length, 0);
+      const newIntegral = integral + textLen;
+      const rate = dt > 0 ? textLen / dt : 0;
+      this.timestamps.push(startTime);
+      this.speakingRate.push(rate);
+      this.speakIntegrals.push(newIntegral);
+      this.textBuffer = [];
+    }
+    this.textBuffer.push(text);
+    if (endTime !== void 0) {
+      this.addByAnnotation("", endTime, void 0);
+    }
+  }
+  /**
+   * Get accumulated speaking units up to the given timestamp.
+   */
+  accumulateTo(timestamp) {
+    if (this.timestamps.length === 0) {
+      return 0;
+    }
+    let idx = 0;
+    for (let i = 0; i < this.timestamps.length; i++) {
+      if (this.timestamps[i] <= timestamp) {
+        idx = i + 1;
+      } else {
+        break;
+      }
+    }
+    if (idx === 0) {
+      return 0;
+    }
+    let integralT = this.speakIntegrals[idx - 1];
+    const dt = timestamp - this.timestamps[idx - 1];
+    const rate = idx < this.speakingRate.length ? this.speakingRate[idx] : this.speakingRate[idx - 1];
+    integralT += rate * dt;
+    if (idx < this.timestamps.length) {
+      integralT = Math.min(integralT, this.speakIntegrals[idx]);
+    }
+    return integralT;
+  }
+  /** Get the last pushed timestamp. */
+  get pushedDuration() {
+    return this.timestamps.length > 0 ? this.timestamps[this.timestamps.length - 1] : 0;
+  }
+}
 class SegmentSynchronizerImpl {
   constructor(options, nextInChain) {
     this.options = options;
@@ -42,7 +115,8 @@ class SegmentSynchronizerImpl {
     };
     this.audioData = {
       pushedDuration: 0,
-      done: false
+      done: false,
+      annotatedRate: null
     };
     this.outputStream = new import_identity_transform.IdentityTransform();
     this.outputStreamWriter = this.outputStream.writable.getWriter();
@@ -73,6 +147,9 @@ class SegmentSynchronizerImpl {
   get textInputEnded() {
     return this.textData.done;
   }
+  get hasPendingText() {
+    return this.textData.pushedText.length > this.textData.forwardedText.length;
+  }
   get readable() {
     return this.outputStream.readable;
   }
@@ -100,8 +177,22 @@ class SegmentSynchronizerImpl {
       this.logger.warn("SegmentSynchronizerImpl.pushText called after close");
       return;
     }
-    this.textData.sentenceStream.pushText(text);
-    this.textData.pushedText += text;
+    let textStr;
+    let startTime;
+    let endTime;
+    if ((0, import_io.isTimedString)(text)) {
+      textStr = text.text;
+      startTime = text.startTime;
+      endTime = text.endTime;
+      if (!this.audioData.annotatedRate) {
+        this.audioData.annotatedRate = new SpeakingRateData();
+      }
+      this.audioData.annotatedRate.addByAnnotation(textStr, startTime, endTime);
+    } else {
+      textStr = text;
+    }
+    this.textData.sentenceStream.pushText(textStr);
+    this.textData.pushedText += textStr;
   }
   endTextInput() {
     if (this.closed) {
@@ -121,6 +212,9 @@ class SegmentSynchronizerImpl {
         { textDone: this.textData.done, audioDone: this.audioData.done },
         "SegmentSynchronizerImpl.markPlaybackFinished called before text/audio input is done"
       );
+      if (!interrupted) {
+        this.playbackCompleted = true;
+      }
       return;
     }
     if (!interrupted) {
@@ -140,7 +234,6 @@ class SegmentSynchronizerImpl {
       if (done) {
         break;
       }
-      this.textData.forwardedText += text;
       await this.nextInChain.captureText(text);
     }
     reader.releaseLock();
@@ -171,16 +264,32 @@ class SegmentSynchronizerImpl {
         }
         const wordHphens = this.options.hyphenateWord(word).length;
         const elapsedSeconds = (Date.now() - this.startWallTime) / 1e3;
-        const targetHyphens = elapsedSeconds * this.options.speed;
-        const hyphensBehind = Math.max(0, targetHyphens - this.textData.forwardedHyphens);
-        let delay2 = Math.max(0, wordHphens - hyphensBehind) / this.speed;
+        let dHyphens = 0;
+        const annotated = this.audioData.annotatedRate;
+        if (annotated && annotated.pushedDuration >= elapsedSeconds) {
+          const targetLen = Math.floor(annotated.accumulateTo(elapsedSeconds));
+          const forwardedLen = this.textData.forwardedText.length;
+          if (targetLen >= forwardedLen) {
+            const dText = this.textData.pushedText.slice(forwardedLen, targetLen);
+            dHyphens = this.calcHyphens(dText).length;
+          } else {
+            const dText = this.textData.pushedText.slice(targetLen, forwardedLen);
+            dHyphens = -this.calcHyphens(dText).length;
+          }
+        } else {
+          const targetHyphens = elapsedSeconds * this.options.speed;
+          dHyphens = Math.max(0, targetHyphens - this.textData.forwardedHyphens);
+        }
+        let delayTime = Math.max(0, wordHphens - dHyphens) / this.speed;
         if (this.playbackCompleted) {
-          delay2 = 0;
+          delayTime = 0;
         }
-        await this.sleepIfNotClosed(delay2 / 2);
-        this.outputStreamWriter.write(sentence.slice(textCursor, endPos));
-        await this.sleepIfNotClosed(delay2 / 2);
+        await this.sleepIfNotClosed(delayTime / 2);
+        const forwardedWord = sentence.slice(textCursor, endPos);
+        this.outputStreamWriter.write(forwardedWord);
+        await this.sleepIfNotClosed(delayTime / 2);
         this.textData.forwardedHyphens += wordHphens;
+        this.textData.forwardedText += forwardedWord;
         textCursor = endPos;
       }
       if (textCursor < sentence.length) {
@@ -189,6 +298,14 @@ class SegmentSynchronizerImpl {
       }
     }
   }
+  calcHyphens(text) {
+    const words = this.options.splitWords(text);
+    const hyphens = [];
+    for (const [word] of words) {
+      hyphens.push(...this.options.hyphenateWord(word));
+    }
+    return hyphens;
+  }
   async sleepIfNotClosed(sleepTimeSeconds) {
     if (this.closed) {
       return;
@@ -220,7 +337,7 @@ class TranscriptionSynchronizer {
   rotateSegmentTask;
   _enabled = true;
   closed = false;
-  /* @internal */
+  /** @internal */
   _impl;
   logger = (0, import_log.log)();
   constructor(nextInChainAudio, nextInChainText, options = defaultTextSyncOptions) {
@@ -282,7 +399,7 @@ class TranscriptionSynchronizer {
 }
 class SyncedAudioOutput extends import_io.AudioOutput {
   constructor(synchronizer, nextInChainAudio) {
-    super(nextInChainAudio.sampleRate, nextInChainAudio);
+    super(nextInChainAudio.sampleRate, nextInChainAudio, { pause: true });
     this.synchronizer = synchronizer;
     this.nextInChainAudio = nextInChainAudio;
   }
@@ -311,6 +428,10 @@ class SyncedAudioOutput extends import_io.AudioOutput {
       return;
     }
     if (!this.pushedDuration) {
+      if (this.synchronizer._impl.hasPendingText) {
+        this.synchronizer._impl.endAudioInput();
+        return;
+      }
       this.synchronizer.rotateSegment();
       return;
     }
@@ -345,8 +466,9 @@ class SyncedTextOutput extends import_io.TextOutput {
   logger = (0, import_log.log)();
   async captureText(text) {
     await this.synchronizer.barrier();
+    const textStr = (0, import_io.isTimedString)(text) ? text.text : text;
     if (!this.synchronizer.enabled) {
-      await this.nextInChain.captureText(text);
+      await this.nextInChain.captureText(textStr);
       return;
     }
     this.capturing = true;
@@ -359,7 +481,8 @@ class SyncedTextOutput extends import_io.TextOutput {
     }
     this.synchronizer._impl.pushText(text);
   }
-  flush() {
+  async flush() {
+    await this.synchronizer.barrier();
     if (!this.synchronizer.enabled) {
       this.nextInChain.flush();
       return;
@@ -373,6 +496,7 @@ class SyncedTextOutput extends import_io.TextOutput {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  SpeakingRateData,
   TranscriptionSynchronizer,
   defaultTextSyncOptions
 });