/**
 * Agent Handoff - Transfer conversations between agents
 *
 * Python parity with praisonaiagents/agent/handoff.py:
 * - HandoffError, HandoffCycleError, HandoffDepthError, HandoffTimeoutError
 * - ContextPolicy enum
 * - HandoffConfig, HandoffInputData, HandoffResult
 * - Handoff class with safety checks
 * - RECOMMENDED_PROMPT_PREFIX, promptWithHandoffInstructions
 */
import type { EnhancedAgent } from './enhanced';
/**
 * Recommended prompt prefix for agents that support handoffs.
 * Python parity with praisonaiagents/agent/handoff.py
 */
export declare const RECOMMENDED_PROMPT_PREFIX = "You are a helpful assistant that can delegate tasks to specialized agents when appropriate.\nWhen you determine that a task would be better handled by another agent, use the appropriate handoff tool.\nAlways explain to the user why you are transferring them to another agent.";
/**
 * Build a prompt with handoff instructions appended.
 * Python parity with praisonaiagents/agent/handoff.py
 *
 * @param basePrompt - The base system prompt
 * @param handoffs - Array of Handoff objects
 * @returns Combined prompt with handoff instructions
 */
export declare function promptWithHandoffInstructions(basePrompt: string, handoffs: Handoff[]): string;
/**
 * Base exception for handoff errors.
 */
export declare class HandoffError extends Error {
    constructor(message: string);
}
/**
 * Raised when a cycle is detected in handoff chain.
 */
export declare class HandoffCycleError extends HandoffError {
    readonly chain: string[];
    constructor(chain: string[]);
}
/**
 * Raised when max handoff depth is exceeded.
 */
export declare class HandoffDepthError extends HandoffError {
    readonly depth: number;
    readonly maxDepth: number;
    constructor(depth: number, maxDepth: number);
}
/**
 * Raised when handoff times out.
 */
export declare class HandoffTimeoutError extends HandoffError {
    readonly timeout: number;
    readonly agentName: string;
    constructor(timeout: number, agentName: string);
}
/**
 * Policy for context sharing during handoff.
 */
export declare const ContextPolicy: {
    readonly FULL: "full";
    readonly SUMMARY: "summary";
    readonly NONE: "none";
    readonly LAST_N: "last_n";
};
export type ContextPolicyType = typeof ContextPolicy[keyof typeof ContextPolicy];
/**
 * Data passed to a handoff target agent.
 */
export interface HandoffInputData {
    messages: any[];
    context: Record<string, any>;
    sourceAgent?: string;
    handoffDepth?: number;
    handoffChain?: string[];
}
/**
 * Unified configuration for handoff behavior.
 * Python parity with HandoffConfig dataclass.
 */
export interface HandoffConfig {
    /** The target agent to hand off to */
    agent: EnhancedAgent;
    /** Custom tool name (defaults to transfer_to_<agent_name>) */
    name?: string;
    /** Custom tool description */
    description?: string;
    /** Condition function to determine if handoff should trigger */
    condition?: (context: HandoffContext) => boolean;
    /** Function to filter/transform input before passing to target agent */
    transformContext?: (messages: any[]) => any[];
    /** How to share context during handoff (default: summary for safety) */
    contextPolicy?: ContextPolicyType;
    /** Maximum tokens to include in context */
    maxContextTokens?: number;
    /** Maximum messages to include (for LAST_N policy) */
    maxContextMessages?: number;
    /** Whether to preserve system messages in context */
    preserveSystem?: boolean;
    /** Timeout for handoff execution in seconds */
    timeoutSeconds?: number;
    /** Maximum concurrent handoffs (0 = unlimited) */
    maxConcurrent?: number;
    /** Enable cycle detection to prevent infinite loops */
    detectCycles?: boolean;
    /** Maximum handoff chain depth */
    maxDepth?: number;
    /** Callback when handoff starts */
    onHandoff?: (context: HandoffContext) => void | Promise<void>;
    /** Callback when handoff completes */
    onComplete?: (result: HandoffResult) => void | Promise<void>;
    /** Callback when handoff fails */
    onError?: (error: Error) => void | Promise<void>;
}
export interface HandoffContext {
    messages: any[];
    lastMessage: string;
    topic?: string;
    metadata?: Record<string, any>;
}
export interface HandoffResult {
    handedOffTo: string;
    response: string;
    context: HandoffContext;
}
/**
 * Handoff class - Represents a handoff target
 */
export declare class Handoff {
    readonly targetAgent: EnhancedAgent;
    readonly name: string;
    readonly description: string;
    readonly condition?: (context: HandoffContext) => boolean;
    readonly transformContext?: (messages: any[]) => any[];
    constructor(config: HandoffConfig);
    /**
     * Check if handoff should be triggered
     */
    shouldTrigger(context: HandoffContext): boolean;
    /**
     * Execute the handoff
     */
    execute(context: HandoffContext): Promise<HandoffResult>;
    /**
     * Get tool definition for LLM
     */
    getToolDefinition(): {
        name: string;
        description: string;
        parameters: any;
    };
}
/**
 * Create a handoff configuration
 */
export declare function handoff(config: HandoffConfig): Handoff;
/**
 * Handoff filters - Common condition functions
 */
export declare const handoffFilters: {
    /**
     * Trigger handoff based on topic keywords
     */
    topic: (keywords: string | string[]) => (context: HandoffContext) => boolean;
    /**
     * Trigger handoff based on metadata
     */
    metadata: (key: string, value: any) => (context: HandoffContext) => boolean;
    /**
     * Always trigger
     */
    always: () => () => boolean;
    /**
     * Never trigger (manual only)
     */
    never: () => () => boolean;
    /**
     * Combine multiple conditions with AND
     */
    and: (...conditions: Array<(context: HandoffContext) => boolean>) => (context: HandoffContext) => boolean;
    /**
     * Combine multiple conditions with OR
     */
    or: (...conditions: Array<(context: HandoffContext) => boolean>) => (context: HandoffContext) => boolean;
};