@livekit/agents 1.0.36-dev.0 → 1.0.37

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

@@ -0,0 +1,374 @@
+import type { AgentHandoffItem, ChatItem, ChatRole } from '../../llm/chat_context.js';
+import type { LLM } from '../../llm/llm.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';
+type AgentConstructor = new (...args: any[]) => Agent;
+/**
+ * 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;
+    /**
+     * Conditionally skip the next event if it matches the specified criteria.
+     * Returns the event assertion if matched and skipped, or undefined if not matched.
+     *
+     * @example
+     * ```typescript
+     * // Skip optional assistant message before function call
+     * result.expect.skipNextEventIf({ type: 'message', role: 'assistant' });
+     * result.expect.nextEvent().isFunctionCall({ name: 'foo' });
+     * ```
+     */
+    skipNextEventIf(options: {
+        type: 'message';
+        role?: ChatRole;
+    } | {
+        type: 'function_call';
+        name?: string;
+        args?: Record<string, unknown>;
+    } | {
+        type: 'function_call_output';
+        output?: string;
+        isError?: boolean;
+    } | {
+        type: 'agent_handoff';
+        newAgentType?: AgentConstructor;
+    }): MessageAssert | FunctionCallAssert | FunctionCallOutputAssert | AgentHandoffAssert | undefined;
+    /**
+     * Get an EventRangeAssert for a range of events.
+     * Similar to Python's slice access: expect[0:3] or expect[:]
+     *
+     * @param start - Start index (inclusive), defaults to 0
+     * @param end - End index (exclusive), defaults to events.length
+     *
+     * @example
+     * ```typescript
+     * // Search all events
+     * result.expect.range().containsFunctionCall({ name: 'foo' });
+     * // Search first 3 events
+     * result.expect.range(0, 3).containsMessage({ role: 'assistant' });
+     * ```
+     */
+    range(start?: number, end?: number): EventRangeAssert;
+    /**
+     * Assert that a function call matching criteria exists anywhere in the events.
+     *
+     * @example
+     * ```typescript
+     * result.expect.containsFunctionCall({ name: 'order_item' });
+     * ```
+     */
+    containsFunctionCall(options?: FunctionCallAssertOptions): FunctionCallAssert;
+    /**
+     * Assert that a message matching criteria exists anywhere in the events.
+     *
+     * @example
+     * ```typescript
+     * result.expect.containsMessage({ role: 'assistant' });
+     * ```
+     */
+    containsMessage(options?: MessageAssertOptions): MessageAssert;
+    /**
+     * Assert that a function call output matching criteria exists anywhere in the events.
+     *
+     * @example
+     * ```typescript
+     * result.expect.containsFunctionCallOutput({ isError: false });
+     * ```
+     */
+    containsFunctionCallOutput(options?: FunctionCallOutputAssertOptions): FunctionCallOutputAssert;
+    /**
+     * Assert that an agent handoff matching criteria exists anywhere in the events.
+     *
+     * @example
+     * ```typescript
+     * result.expect.containsAgentHandoff({ newAgentType: MyAgent });
+     * ```
+     */
+    containsAgentHandoff(options?: AgentHandoffAssertOptions): AgentHandoffAssert;
+    /**
+     * 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 a range of events.
+ * Provides contains*() methods to search within the range.
+ */
+export declare class EventRangeAssert {
+    private _events;
+    private _parent;
+    private _range;
+    constructor(events: RunEvent[], parent: RunAssert, range: {
+        start: number;
+        end: number;
+    });
+    /**
+     * Assert that a function call matching criteria exists in this event range.
+     *
+     * @example
+     * ```typescript
+     * result.expect.range(0, 3).containsFunctionCall({ name: 'foo' });
+     * ```
+     */
+    containsFunctionCall(options?: FunctionCallAssertOptions): FunctionCallAssert;
+    /**
+     * Assert that a message matching criteria exists in this event range.
+     *
+     * @example
+     * ```typescript
+     * result.expect.range(0, 2).containsMessage({ role: 'assistant' });
+     * ```
+     */
+    containsMessage(options?: MessageAssertOptions): MessageAssert;
+    /**
+     * Assert that a function call output matching criteria exists in this event range.
+     *
+     * @example
+     * ```typescript
+     * result.expect.range(1, 4).containsFunctionCallOutput({ isError: true });
+     * ```
+     */
+    containsFunctionCallOutput(options?: FunctionCallOutputAssertOptions): FunctionCallOutputAssert;
+    /**
+     * Assert that an agent handoff matching criteria exists in this event range.
+     *
+     * @example
+     * ```typescript
+     * result.expect.range(0, 3).containsAgentHandoff({ newAgentType: MyAgent });
+     * ```
+     */
+    containsAgentHandoff(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;
+    /**
+     * Evaluate whether the message fulfills the given intent using an LLM.
+     *
+     * @param llm - LLM instance for judgment
+     * @param options - Options containing the intent description
+     * @returns Self for chaining further assertions
+     *
+     * @example
+     * ```typescript
+     * await result.expect
+     *   .nextEvent()
+     *   .isMessage({ role: 'assistant' })
+     *   .judge(llm, { intent: 'should ask for the drink size' });
+     * ```
+     */
+    judge(llm: LLM, options: {
+        intent: string;
+    }): Promise<MessageAssert>;
+}
+/**
+ * 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);
+}
+export {};
+//# 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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"}