@livekit/agents 1.0.34 → 1.0.36

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

@@ -0,0 +1,226 @@
+import type { AgentHandoffItem, ChatItem } from '../../llm/chat_context.js';
+import type { Task } from '../../utils.js';
+import type { Agent } from '../agent.js';
+import { type SpeechHandle } from '../speech_handle.js';
+import { type AgentHandoffAssertOptions, type AgentHandoffEvent, type ChatMessageEvent, type EventType, type FunctionCallAssertOptions, type FunctionCallEvent, type FunctionCallOutputAssertOptions, type FunctionCallOutputEvent, type MessageAssertOptions, type RunEvent } from './types.js';
+/**
+ * Result of a test run containing recorded events and assertion utilities.
+ *
+ * @example
+ * ```typescript
+ * const result = await session.run({ userInput: 'Hello' });
+ * result.expect.nextEvent().isMessage({ role: 'assistant' });
+ * result.expect.noMoreEvents();
+ * ```
+ */
+export declare class RunResult<T = unknown> {
+    private _events;
+    private doneFut;
+    private userInput?;
+    private handles;
+    private lastSpeechHandle?;
+    private runAssert?;
+    constructor(options?: {
+        userInput?: string;
+    });
+    /**
+     * List of all recorded events generated during the run.
+     */
+    get events(): RunEvent[];
+    /**
+     * Provides an assertion helper for verifying the run events.
+     */
+    get expect(): RunAssert;
+    /**
+     * Returns the final output of the run after completion.
+     *
+     * @throws Error - Not implemented yet.
+     */
+    get finalOutput(): T;
+    /**
+     * Indicates whether the run has finished processing all events.
+     */
+    done(): boolean;
+    /**
+     * Wait for the RunResult to complete. Returns `this` for method chaining.
+     *
+     * @example
+     * ```ts
+     * const result = session.run({ userInput: 'Hi!' });
+     * await result.wait();  // waits for completion
+     * result.expect.nextEvent().isMessage({ role: 'assistant' });
+     * ```
+     */
+    wait(): Promise<this>;
+    /**
+     * @internal
+     * Records an agent handoff event.
+     */
+    _agentHandoff(params: {
+        item: AgentHandoffItem;
+        oldAgent?: Agent;
+        newAgent: Agent;
+    }): void;
+    /**
+     * @internal
+     * Called when a chat item is added during the run.
+     */
+    _itemAdded(item: ChatItem): void;
+    /**
+     * @internal
+     * Watch a speech handle or task for completion.
+     */
+    _watchHandle(handle: SpeechHandle | Task<void>): void;
+    /**
+     * @internal
+     * Unwatch a handle.
+     */
+    _unwatchHandle(handle: SpeechHandle | Task<void>): void;
+    private _markDoneIfNeeded;
+    private _markDone;
+    /**
+     * Find the correct insertion index to maintain chronological order.
+     */
+    private _findInsertionIndex;
+}
+/**
+ * Assertion helper for verifying run events in sequence.
+ */
+export declare class RunAssert {
+    private _events;
+    private _currentIndex;
+    constructor(runResult: RunResult);
+    /**
+     * Access a specific event by index for assertions.
+     * Supports negative indices (e.g., -1 for last event).
+     *
+     * @example
+     * ```typescript
+     * result.expect.at(0).isMessage({ role: 'user' });
+     * result.expect.at(-1).isMessage({ role: 'assistant' });
+     * ```
+     */
+    at(index: number): EventAssert;
+    /**
+     * Advance to the next event, optionally filtering by type.
+     *
+     * @example
+     * ```typescript
+     * result.expect.nextEvent().isMessage({ role: 'assistant' });
+     * result.expect.nextEvent({ type: 'function_call' }).isFunctionCall({ name: 'foo' });
+     * ```
+     */
+    nextEvent(options?: {
+        type?: EventType;
+    }): EventAssert;
+    /**
+     * Skip a specified number of upcoming events without assertions.
+     *
+     * @example
+     * ```typescript
+     * result.expect.skipNext(2);
+     * ```
+     */
+    skipNext(count?: number): this;
+    /**
+     * Assert that there are no further events.
+     *
+     * @example
+     * ```typescript
+     * result.expect.noMoreEvents();
+     * ```
+     */
+    noMoreEvents(): void;
+    private _currentEvent;
+    /** @internal */
+    _raiseWithDebugInfo(message: string, index?: number): never;
+}
+/**
+ * Assertion wrapper for a single event.
+ */
+export declare class EventAssert {
+    protected _event: RunEvent;
+    protected _parent: RunAssert;
+    protected _index: number;
+    constructor(event: RunEvent, parent: RunAssert, index: number);
+    /**
+     * Get the underlying event.
+     */
+    event(): RunEvent;
+    protected _raise(message: string): never;
+    /**
+     * Verify this event is a message with optional role matching.
+     *
+     * @example
+     * ```typescript
+     * result.expect.nextEvent().isMessage({ role: 'assistant' });
+     * ```
+     */
+    isMessage(options?: MessageAssertOptions): MessageAssert;
+    /**
+     * Verify this event is a function call with optional name/args matching.
+     *
+     * @example
+     * ```typescript
+     * result.expect.nextEvent().isFunctionCall({ name: 'order_item', args: { id: 'big_mac' } });
+     * ```
+     */
+    isFunctionCall(options?: FunctionCallAssertOptions): FunctionCallAssert;
+    /**
+     * Verify this event is a function call output with optional matching.
+     *
+     * @example
+     * ```typescript
+     * result.expect.nextEvent().isFunctionCallOutput({ isError: false });
+     * ```
+     */
+    isFunctionCallOutput(options?: FunctionCallOutputAssertOptions): FunctionCallOutputAssert;
+    /**
+     * Verify this event is an agent handoff with optional type matching.
+     *
+     * @example
+     * ```typescript
+     * result.expect.nextEvent().isAgentHandoff({ newAgentType: MyAgent });
+     * ```
+     */
+    isAgentHandoff(options?: AgentHandoffAssertOptions): AgentHandoffAssert;
+}
+/**
+ * Assertion wrapper for message events.
+ */
+export declare class MessageAssert extends EventAssert {
+    protected _event: ChatMessageEvent;
+    constructor(event: ChatMessageEvent, parent: RunAssert, index: number);
+    event(): ChatMessageEvent;
+}
+/**
+ * Assertion wrapper for function call events.
+ */
+export declare class FunctionCallAssert extends EventAssert {
+    protected _event: FunctionCallEvent;
+    constructor(event: FunctionCallEvent, parent: RunAssert, index: number);
+    event(): FunctionCallEvent;
+}
+/**
+ * Assertion wrapper for function call output events.
+ */
+export declare class FunctionCallOutputAssert extends EventAssert {
+    protected _event: FunctionCallOutputEvent;
+    constructor(event: FunctionCallOutputEvent, parent: RunAssert, index: number);
+    event(): FunctionCallOutputEvent;
+}
+/**
+ * Assertion wrapper for agent handoff events.
+ */
+export declare class AgentHandoffAssert extends EventAssert {
+    protected _event: AgentHandoffEvent;
+    constructor(event: AgentHandoffEvent, parent: RunAssert, index: number);
+    event(): AgentHandoffEvent;
+}
+/**
+ * Custom assertion error for test failures.
+ */
+export declare class AssertionError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=run_result.d.ts.map

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

@@ -0,0 +1,226 @@
+import type { AgentHandoffItem, ChatItem } from '../../llm/chat_context.js';
+import type { Task } from '../../utils.js';
+import type { Agent } from '../agent.js';
+import { type SpeechHandle } from '../speech_handle.js';
+import { type AgentHandoffAssertOptions, type AgentHandoffEvent, type ChatMessageEvent, type EventType, type FunctionCallAssertOptions, type FunctionCallEvent, type FunctionCallOutputAssertOptions, type FunctionCallOutputEvent, type MessageAssertOptions, type RunEvent } from './types.js';
+/**
+ * Result of a test run containing recorded events and assertion utilities.
+ *
+ * @example
+ * ```typescript
+ * const result = await session.run({ userInput: 'Hello' });
+ * result.expect.nextEvent().isMessage({ role: 'assistant' });
+ * result.expect.noMoreEvents();
+ * ```
+ */
+export declare class RunResult<T = unknown> {
+    private _events;
+    private doneFut;
+    private userInput?;
+    private handles;
+    private lastSpeechHandle?;
+    private runAssert?;
+    constructor(options?: {
+        userInput?: string;
+    });
+    /**
+     * List of all recorded events generated during the run.
+     */
+    get events(): RunEvent[];
+    /**
+     * Provides an assertion helper for verifying the run events.
+     */
+    get expect(): RunAssert;
+    /**
+     * Returns the final output of the run after completion.
+     *
+     * @throws Error - Not implemented yet.
+     */
+    get finalOutput(): T;
+    /**
+     * Indicates whether the run has finished processing all events.
+     */
+    done(): boolean;
+    /**
+     * Wait for the RunResult to complete. Returns `this` for method chaining.
+     *
+     * @example
+     * ```ts
+     * const result = session.run({ userInput: 'Hi!' });
+     * await result.wait();  // waits for completion
+     * result.expect.nextEvent().isMessage({ role: 'assistant' });
+     * ```
+     */
+    wait(): Promise<this>;
+    /**
+     * @internal
+     * Records an agent handoff event.
+     */
+    _agentHandoff(params: {
+        item: AgentHandoffItem;
+        oldAgent?: Agent;
+        newAgent: Agent;
+    }): void;
+    /**
+     * @internal
+     * Called when a chat item is added during the run.
+     */
+    _itemAdded(item: ChatItem): void;
+    /**
+     * @internal
+     * Watch a speech handle or task for completion.
+     */
+    _watchHandle(handle: SpeechHandle | Task<void>): void;
+    /**
+     * @internal
+     * Unwatch a handle.
+     */
+    _unwatchHandle(handle: SpeechHandle | Task<void>): void;
+    private _markDoneIfNeeded;
+    private _markDone;
+    /**
+     * Find the correct insertion index to maintain chronological order.
+     */
+    private _findInsertionIndex;
+}
+/**
+ * Assertion helper for verifying run events in sequence.
+ */
+export declare class RunAssert {
+    private _events;
+    private _currentIndex;
+    constructor(runResult: RunResult);
+    /**
+     * Access a specific event by index for assertions.
+     * Supports negative indices (e.g., -1 for last event).
+     *
+     * @example
+     * ```typescript
+     * result.expect.at(0).isMessage({ role: 'user' });
+     * result.expect.at(-1).isMessage({ role: 'assistant' });
+     * ```
+     */
+    at(index: number): EventAssert;
+    /**
+     * Advance to the next event, optionally filtering by type.
+     *
+     * @example
+     * ```typescript
+     * result.expect.nextEvent().isMessage({ role: 'assistant' });
+     * result.expect.nextEvent({ type: 'function_call' }).isFunctionCall({ name: 'foo' });
+     * ```
+     */
+    nextEvent(options?: {
+        type?: EventType;
+    }): EventAssert;
+    /**
+     * Skip a specified number of upcoming events without assertions.
+     *
+     * @example
+     * ```typescript
+     * result.expect.skipNext(2);
+     * ```
+     */
+    skipNext(count?: number): this;
+    /**
+     * Assert that there are no further events.
+     *
+     * @example
+     * ```typescript
+     * result.expect.noMoreEvents();
+     * ```
+     */
+    noMoreEvents(): void;
+    private _currentEvent;
+    /** @internal */
+    _raiseWithDebugInfo(message: string, index?: number): never;
+}
+/**
+ * Assertion wrapper for a single event.
+ */
+export declare class EventAssert {
+    protected _event: RunEvent;
+    protected _parent: RunAssert;
+    protected _index: number;
+    constructor(event: RunEvent, parent: RunAssert, index: number);
+    /**
+     * Get the underlying event.
+     */
+    event(): RunEvent;
+    protected _raise(message: string): never;
+    /**
+     * Verify this event is a message with optional role matching.
+     *
+     * @example
+     * ```typescript
+     * result.expect.nextEvent().isMessage({ role: 'assistant' });
+     * ```
+     */
+    isMessage(options?: MessageAssertOptions): MessageAssert;
+    /**
+     * Verify this event is a function call with optional name/args matching.
+     *
+     * @example
+     * ```typescript
+     * result.expect.nextEvent().isFunctionCall({ name: 'order_item', args: { id: 'big_mac' } });
+     * ```
+     */
+    isFunctionCall(options?: FunctionCallAssertOptions): FunctionCallAssert;
+    /**
+     * Verify this event is a function call output with optional matching.
+     *
+     * @example
+     * ```typescript
+     * result.expect.nextEvent().isFunctionCallOutput({ isError: false });
+     * ```
+     */
+    isFunctionCallOutput(options?: FunctionCallOutputAssertOptions): FunctionCallOutputAssert;
+    /**
+     * Verify this event is an agent handoff with optional type matching.
+     *
+     * @example
+     * ```typescript
+     * result.expect.nextEvent().isAgentHandoff({ newAgentType: MyAgent });
+     * ```
+     */
+    isAgentHandoff(options?: AgentHandoffAssertOptions): AgentHandoffAssert;
+}
+/**
+ * Assertion wrapper for message events.
+ */
+export declare class MessageAssert extends EventAssert {
+    protected _event: ChatMessageEvent;
+    constructor(event: ChatMessageEvent, parent: RunAssert, index: number);
+    event(): ChatMessageEvent;
+}
+/**
+ * Assertion wrapper for function call events.
+ */
+export declare class FunctionCallAssert extends EventAssert {
+    protected _event: FunctionCallEvent;
+    constructor(event: FunctionCallEvent, parent: RunAssert, index: number);
+    event(): FunctionCallEvent;
+}
+/**
+ * Assertion wrapper for function call output events.
+ */
+export declare class FunctionCallOutputAssert extends EventAssert {
+    protected _event: FunctionCallOutputEvent;
+    constructor(event: FunctionCallOutputEvent, parent: RunAssert, index: number);
+    event(): FunctionCallOutputEvent;
+}
+/**
+ * Assertion wrapper for agent handoff events.
+ */
+export declare class AgentHandoffAssert extends EventAssert {
+    protected _event: AgentHandoffEvent;
+    constructor(event: AgentHandoffEvent, parent: RunAssert, index: number);
+    event(): AgentHandoffEvent;
+}
+/**
+ * Custom assertion error for test failures.
+ */
+export declare class AssertionError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=run_result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run_result.d.ts","sourceRoot":"","sources":["../../../src/voice/testing/run_result.ts"],"names":[],"mappings":"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"}