/**
 * Test fixtures and helpers for Agent testing.
 * This module provides utilities for testing Agent-related implementations.
 */
import type { Agent } from '../agent/agent.js';
import type { AgentResult, InvokableAgent } from '../types/agent.js';
import type { StopReason } from '../types/messages.js';
import { Message } from '../types/messages.js';
import type { Role } from '../types/messages.js';
import type { JSONValue } from '../types/json.js';
import { ToolRegistry } from '../registry/tool-registry.js';
import type { HookableEvent } from '../hooks/events.js';
import type { HookableEventConstructor, HookCallback } from '../hooks/types.js';
import { type LoopMetricsMatcher } from './metrics-helpers.js';
/**
 * A hook registration captured by the mock agent's addHook.
 */
export type TrackedHook = {
    eventType: HookableEventConstructor<HookableEvent>;
    callback: HookCallback<HookableEvent>;
};
/**
 * Data for creating a mock Agent.
 */
export interface MockAgentData {
    /**
     * Messages for the agent.
     */
    messages?: Message[];
    /**
     * Initial state for the agent.
     */
    appState?: Record<string, JSONValue>;
    /**
     * Optional tool registry for the agent.
     */
    toolRegistry?: ToolRegistry;
    /**
     * Additional properties to spread onto the mock agent.
     */
    extra?: Partial<Agent>;
}
/**
 * A mock Agent with a `trackedHooks` array populated by `addHook` calls.
 */
export type MockAgent = Agent & {
    trackedHooks: TrackedHook[];
};
/**
 * Helper to create a mock Agent for testing.
 * Provides minimal Agent interface with messages, appState, and tool registry.
 * `addHook` captures registrations into `trackedHooks` for test inspection.
 *
 * @param data - Optional mock agent data
 * @returns Mock Agent with trackedHooks
 */
export declare function createMockAgent(data?: MockAgentData): MockAgent;
/**
 * Creates a Message with the given role containing a single TextBlock.
 *
 * @param role - The message role
 * @param text - The text content
 * @returns A Message with the specified role
 */
export declare function textMessage(role: Role, text: string): Message;
/**
 * Finds the tracked hook for the given event type and invokes it with the provided event.
 * Throws if no hook is registered for that event type.
 *
 * @param agent - The mock agent with tracked hooks
 * @param event - The event instance to dispatch
 */
export declare function invokeTrackedHook<T extends HookableEvent>(agent: MockAgent, event: T): Promise<void>;
/**
 * Options for building an AgentResult matcher.
 */
export interface AgentResultMatcher extends Omit<LoopMetricsMatcher, 'cycleCount'> {
    /**
     * Expected stop reason from the final model response.
     */
    stopReason: StopReason;
    /**
     * Expected text content in the last assistant message's TextBlock.
     * When provided, asserts exact text match in a TextBlock with role 'assistant'.
     * When omitted, only validates lastMessage exists with role 'assistant'.
     */
    messageText?: string;
    /**
     * Expected number of agent loop cycles.
     */
    cycleCount: number;
    /**
     * Expected number of traces. When provided, asserts exact array length.
     * When omitted, asserts traces array exists with at least one element.
     */
    traceCount?: number;
    /**
     * Expected `invocationState` on the result. When provided, the full object
     * must match exactly — extra keys fail. When omitted, only asserts
     * `invocationState` is present (any object).
     */
    invocationState?: Record<string, unknown>;
}
/**
 * Creates an asymmetric matcher that validates AgentResult structure and values.
 * Reduces nesting in test assertions by providing a clean, readable matcher.
 *
 * @param options - Expected result values
 * @returns An asymmetric matcher suitable for use in expect().toEqual()
 *
 * @example
 * ```typescript
 * expect(result).toEqual(expectAgentResult({
 *   stopReason: 'endTurn',
 *   messageText: 'Hello',
 *   cycleCount: 1,
 * }))
 * ```
 */
export declare function expectAgentResult(options: AgentResultMatcher): AgentResult;
/**
 * Creates a minimal InvokableAgent that sleeps for `delayMs` before resolving,
 * aborting the sleep early when the invocation's `cancelSignal` fires. Used to
 * exercise timeout and cancellation behavior deterministically without spinning
 * up a full Agent.
 *
 * @param id - The agent id
 * @param delayMs - How long the agent should sleep before returning
 * @param structuredOutput - Optional structured output (e.g. a swarm handoff). When present,
 *   its `message` field is used as the assistant text.
 */
export declare function createCancellableAgent(id: string, delayMs: number, structuredOutput?: {
    agentId?: string;
    message: string;
}): InvokableAgent;
//# sourceMappingURL=agent-helpers.d.ts.map