import { Doc, FieldType } from '../../../../../fields/Doc';
import { DocData } from '../../../../../fields/DocSymbols';
import { Observation } from '../types/types';
import { ParametersType, ToolInfo, Parameter } from '../types/tool_types';
import { BaseTool } from './BaseTool';
import { DocumentOptions } from '../../../../documents/Documents';
import { CollectionFreeFormDocumentView } from '../../../nodes/CollectionFreeFormDocumentView';
import { v4 as uuidv4 } from 'uuid';
import { LinkManager } from '../../../../util/LinkManager';
import { DocCast, StrCast } from '../../../../../fields/Types';

// Define the parameters for the DocumentMetadataTool
const parameterDefinitions: ReadonlyArray<Parameter> = [
    {
        name: 'action',
        type: 'string',
        required: true,
        description: 'The action to perform: "get" to retrieve metadata, "edit" to modify metadata, or "list" to enumerate documents',
    },
    {
        name: 'documentId',
        type: 'string',
        required: false,
        description: 'The ID of the document to get or edit metadata for. Required for "edit", optional for "get", ignored for "list"',
    },
    {
        name: 'fieldName',
        type: 'string',
        required: false,
        description: 'The name of the field to edit. Required for "edit" action. Field names can be provided with or without leading underscores',
    },
    {
        name: 'fieldValue',
        type: 'string',
        required: false,
        description: 'The new value for the field. Required for "edit" action. Can be a string, number, or boolean value depending on the field type',
    }
] as const;

type DocumentMetadataToolParamsType = typeof parameterDefinitions;

// Detailed description with usage guidelines for the DocumentMetadataTool
const toolDescription = `Extracts and modifies metadata from documents in the same Freeform view as the ChatBox. 
This tool helps you work with document properties, understand available fields, and edit document metadata.

The Dash document system organizes fields in two locations:
1. Layout documents: contain visual properties like position, dimensions, and appearance
2. Data documents: contain the actual content and document-specific data

This tool provides the following capabilities:
- Get metadata from all documents in the current Freeform view
- Get metadata from a specific document
- Edit metadata fields on documents (in either layout or data documents)
- List all available documents in the current view
- Understand which fields are stored where (layout vs data document)
- Get detailed information about all available document fields
- Support for all value types: strings, numbers, and booleans

IMPORTANT: Some fields have dependencies that must be handled for edits to work correctly:
- When editing "height", first set "layout_autoHeight" to false (as a boolean value, not a string)
- When editing "width", first set "layout_autoWidth" to false (as a boolean value, not a string)
- Check document metadata to identify other similar dependencies

Example: To change document height, first disable auto-height:
1. { action: "edit", documentId: "doc123", fieldName: "layout_autoHeight", fieldValue: false }
2. { action: "edit", documentId: "doc123", fieldName: "height", fieldValue: 300 }`;

// Extensive usage guidelines for the tool
const citationRules = `USAGE GUIDELINES:
To GET document metadata:
- Use action="get" with optional documentId to return metadata for one or all documents
- Returns field values, field definitions, and location information (layout vs data document)

To EDIT document metadata:
- Use action="edit" with required documentId, fieldName, and fieldValue parameters
- The tool will determine the correct document location automatically
- Field names can be provided with or without leading underscores (e.g., both "width" and "_width" work)
- Common fields like "width" and "height" are automatically mapped to "_width" and "_height"
- All value types are supported: strings, numbers, and booleans
- The tool will apply the edit to the correct document (layout or data) based on existing fields

HANDLING DEPENDENT FIELDS:
- When editing some fields, you may need to update related dependent fields
- For example, when changing "height", you should also set "layout_autoHeight" to false:
  1. First: { action: "edit", documentId: "doc123", fieldName: "layout_autoHeight", fieldValue: false }
  2. Then: { action: "edit", documentId: "doc123", fieldName: "height", fieldValue: 300 }
- Always check for dependent fields that might affect your edits, such as:
  - height → layout_autoHeight (set to false to allow manual height)
  - width → layout_autoWidth (set to false to allow manual width)
  - Other auto-sizing related properties

To LIST available documents:
- Use action="list" to get a simple list of all documents in the current view
- This is useful when you need to identify documents before getting details or editing them

Editing fields follows these rules:
1. First checks if the field exists on the layout document using Doc.Get
2. If it exists on the layout document, it's updated there
3. If it has an underscore prefix (_), it's created/updated on the layout document
4. Otherwise, the field is created/updated on the data document
5. Fields with leading underscores are automatically handled correctly

Examples:
- To list all documents: { action: "list" }
- To get all document metadata: { action: "get" }
- To get metadata for a specific document: { action: "get", documentId: "doc123" }
- To edit a field: { action: "edit", documentId: "doc123", fieldName: "backgroundColor", fieldValue: "#ff0000" }
- To edit a width property: { action: "edit", documentId: "doc123", fieldName: "width", fieldValue: 300 }
- To disable auto-height: { action: "edit", documentId: "doc123", fieldName: "layout_autoHeight", fieldValue: false }
- To edit height with dependent field:
  { action: "edit", documentId: "doc123", fieldName: "layout_autoHeight", fieldValue: false }
  { action: "edit", documentId: "doc123", fieldName: "height", fieldValue: 200 }`;

const documentMetadataToolInfo: ToolInfo<DocumentMetadataToolParamsType> = {
    name: 'documentMetadata',
    description: toolDescription,
    parameterRules: parameterDefinitions,
    citationRules: citationRules,
};

/**
 * A tool for extracting and modifying metadata from documents in a Freeform view.
 * This tool collects metadata from both layout and data documents in a Freeform view
 * and allows for editing document fields in the correct location.
 */
export class DocumentMetadataTool extends BaseTool<DocumentMetadataToolParamsType> {
    private freeformView: any;
    private chatBox: any;
    private chatBoxDocument: Doc | null = null;
    private documentsById: Map<string, Doc> = new Map();
    private layoutDocsById: Map<string, Doc> = new Map();
    private dataDocsById: Map<string, Doc> = new Map();
    private fieldMetadata: Record<string, any> = {};
    private readonly DOCUMENT_ID_FIELD = '_dash_document_id';

    constructor(chatBox: any) {
        super(documentMetadataToolInfo);
        this.chatBox = chatBox;
        
        // Store a direct reference to the ChatBox document
        if (chatBox && chatBox.Document) {
            this.chatBoxDocument = chatBox.Document;
            if (this.chatBoxDocument && this.chatBoxDocument.id) {
                console.log('DocumentMetadataTool initialized with ChatBox Document:', this.chatBoxDocument.id);
            } else {
                console.log('DocumentMetadataTool initialized with ChatBox Document (no ID)');
            }
        } else if (chatBox && chatBox.props && chatBox.props.Document) {
            this.chatBoxDocument = chatBox.props.Document;
            if (this.chatBoxDocument && this.chatBoxDocument.id) {
                console.log('DocumentMetadataTool initialized with ChatBox props.Document:', this.chatBoxDocument.id);
            } else {
                console.log('DocumentMetadataTool initialized with ChatBox props.Document (no ID)');
            }
        } else {
            console.warn('DocumentMetadataTool initialized without valid ChatBox Document reference');
        }
        
        this.initializeFieldMetadata();
    }

    /**
     * Extracts field metadata from DocumentOptions class
     */
    private initializeFieldMetadata() {
        // Parse DocumentOptions to extract field definitions
        const documentOptionsInstance = new DocumentOptions();
        const documentOptionsEntries = Object.entries(documentOptionsInstance);

        for (const [fieldName, fieldInfo] of documentOptionsEntries) {
            // Extract field information
            const fieldData: Record<string, any> = {
                name: fieldName,
                withoutUnderscore: fieldName.startsWith('_') ? fieldName.substring(1) : fieldName,
                description: '',
                type: 'unknown',
                required: false,
                defaultValue: undefined,
                possibleValues: [],
            };

            // Check if fieldInfo has description property (it's likely a FInfo instance)
            if (fieldInfo && typeof fieldInfo === 'object' && 'description' in fieldInfo) {
                fieldData.description = fieldInfo.description;
                
                // Extract field type if available
                if ('fieldType' in fieldInfo) {
                    fieldData.type = fieldInfo.fieldType;
                }
                
                // Extract possible values if available
                if ('values' in fieldInfo && Array.isArray(fieldInfo.values)) {
                    fieldData.possibleValues = fieldInfo.values;
                }
            }

            this.fieldMetadata[fieldName] = fieldData;
        }
    }

    /**
     * Gets all documents in the same Freeform view as the ChatBox
     * Uses the LinkManager to get all linked documents, similar to how ChatBox does it
     */
    private findDocumentsInFreeformView() {
        // Reset collections
        this.documentsById.clear();
        this.layoutDocsById.clear();
        this.dataDocsById.clear();

        try {
            // Use the LinkManager approach which is proven to work in ChatBox
            if (this.chatBoxDocument) {
                console.log('Finding documents linked to ChatBox document with ID:', this.chatBoxDocument.id);
                
                // Get directly linked documents via LinkManager
                const linkedDocs = LinkManager.Instance.getAllRelatedLinks(this.chatBoxDocument)
                    .map(d => DocCast(LinkManager.getOppositeAnchor(d, this.chatBoxDocument!)))
                    .map(d => DocCast(d?.annotationOn, d))
                    .filter(d => d);
                
                console.log(`Found ${linkedDocs.length} linked documents via LinkManager`);
                
                // Process the linked documents
                linkedDocs.forEach((doc: Doc) => {
                    if (doc) {
                        this.processDocument(doc);
                    }
                });
                
                // Include the ChatBox document itself
                this.processDocument(this.chatBoxDocument);
                
                // If we have access to the Document's parent, try to find sibling documents
                if (this.chatBoxDocument.parent) {
                    const parent = this.chatBoxDocument.parent;
                    console.log('Found parent document, checking for siblings');
                    
                    // Check if parent is a Doc type and has a childDocs function
                    if (parent && typeof parent === 'object' && 'childDocs' in parent && typeof parent.childDocs === 'function') {
                        try {
                            const siblingDocs = parent.childDocs();
                            if (Array.isArray(siblingDocs)) {
                                console.log(`Found ${siblingDocs.length} sibling documents via parent.childDocs()`);
                                siblingDocs.forEach((doc: Doc) => {
                                    if (doc) {
                                        this.processDocument(doc);
                                    }
                                });
                            }
                        } catch (e) {
                            console.warn('Error accessing parent.childDocs:', e);
                        }
                    }
                }
            } else if (this.chatBox && this.chatBox.linkedDocs) {
                // If we have direct access to the linkedDocs computed property from ChatBox
                console.log('Using ChatBox.linkedDocs directly');
                const linkedDocs = this.chatBox.linkedDocs;
                if (Array.isArray(linkedDocs)) {
                    console.log(`Found ${linkedDocs.length} documents via ChatBox.linkedDocs`);
                    linkedDocs.forEach((doc: Doc) => {
                        if (doc) {
                            this.processDocument(doc);
                        }
                    });
                }
                
                // Process the ChatBox document if available
                if (this.chatBox.Document) {
                    this.processDocument(this.chatBox.Document);
                }
            } else {
                console.warn('No ChatBox document reference available for finding linked documents');
            }

            console.log(`DocumentMetadataTool found ${this.documentsById.size} total documents`);
            
            // If we didn't find any documents, try a fallback method
            if (this.documentsById.size === 0 && this.chatBox) {
                console.log('No documents found, trying fallback method');
                
                // Try to access any field that might contain documents
                if (this.chatBox.props && this.chatBox.props.documents) {
                    const documents = this.chatBox.props.documents;
                    if (Array.isArray(documents)) {
                        console.log(`Found ${documents.length} documents via ChatBox.props.documents`);
                        documents.forEach((doc: Doc) => {
                            if (doc) {
                                this.processDocument(doc);
                            }
                        });
                    }
                }
            }
        } catch (error) {
            console.error('Error finding documents in Freeform view:', error);
        }
    }

    /**
     * Process a document by ensuring it has an ID and adding it to the appropriate collections
     * @param doc The document to process
     */
    private processDocument(doc: Doc) {
        // Ensure document has a persistent ID
        const docId = this.ensureDocumentId(doc);
        
        // Only add if we haven't already processed this document
        if (!this.documentsById.has(docId)) {
            this.documentsById.set(docId, doc);
            
            // Get layout doc (the document itself or its layout)
            const layoutDoc = Doc.Layout(doc);
            if (layoutDoc) {
                this.layoutDocsById.set(docId, layoutDoc);
            }
            
            // Get data doc
            const dataDoc = doc[DocData];
            if (dataDoc) {
                this.dataDocsById.set(docId, dataDoc);
            }
        }
    }

    /**
     * Ensures a document has a persistent ID stored in its metadata
     * @param doc The document to ensure has an ID
     * @returns The document's ID
     */
    private ensureDocumentId(doc: Doc): string {
        let docId: string | undefined;
        
        // First try to get the ID from our custom field
        if (doc[this.DOCUMENT_ID_FIELD]) {
            docId = String(doc[this.DOCUMENT_ID_FIELD]);
            return docId;
        }
        
        // Try different ways to get a document ID
        
        // 1. Try the direct id property if it exists
        if (doc.id && typeof doc.id === 'string') {
            docId = doc.id;
        }
        // 2. Try doc._id if it exists
        else if (doc._id && typeof doc._id === 'string') {
            docId = doc._id;
        }
        // 3. Try doc.data?.id if it exists
        else if (doc.data && typeof doc.data === 'object' && 'id' in doc.data && typeof doc.data.id === 'string') {
            docId = doc.data.id;
        }
        // 4. If none of the above work, generate a UUID
        else {
            docId = uuidv4();
            console.log(`Generated new UUID for document with title: ${doc.title || 'Untitled'}`);
        }
        
        // Store the ID in the document's metadata so it persists
        try {
            doc[this.DOCUMENT_ID_FIELD] = docId;
        } catch (e) {
            console.warn(`Could not assign ID to document property`, e);
        }
        
        return docId;
    }

    /**
     * Extracts metadata from a specific document
     * @param docId The ID of the document to extract metadata from
     * @returns An object containing the document's metadata
     */
    private extractDocumentMetadata(docId: string) {
        const doc = this.documentsById.get(docId);
        if (!doc) {
            return null;
        }

        const layoutDoc = this.layoutDocsById.get(docId);
        const dataDoc = this.dataDocsById.get(docId);
        
        const metadata: Record<string, any> = {
            id: docId,
            title: doc.title || '',
            type: doc.type || '',
            fields: {
                layout: {},
                data: {},
            },
            fieldLocationMap: {},
        };

        // Process all known field definitions
        Object.keys(this.fieldMetadata).forEach(fieldName => {
            const fieldDef = this.fieldMetadata[fieldName];
            const strippedName = fieldName.startsWith('_') ? fieldName.substring(1) : fieldName;
            
            // Check if field exists on layout document
            let layoutValue = undefined;
            if (layoutDoc) {
                layoutValue = layoutDoc[fieldName];
                if (layoutValue !== undefined) {
                    // Field exists on layout document
                    metadata.fields.layout[fieldName] = this.formatFieldValue(layoutValue);
                    metadata.fieldLocationMap[strippedName] = 'layout';
                }
            }
            
            // Check if field exists on data document
            let dataValue = undefined;
            if (dataDoc) {
                dataValue = dataDoc[fieldName];
                if (dataValue !== undefined) {
                    // Field exists on data document
                    metadata.fields.data[fieldName] = this.formatFieldValue(dataValue);
                    if (!metadata.fieldLocationMap[strippedName]) {
                        metadata.fieldLocationMap[strippedName] = 'data';
                    }
                }
            }
            
            // For fields with stripped names (without leading underscore),
            // also check if they exist on documents without the underscore
            if (fieldName.startsWith('_')) {
                const nonUnderscoreFieldName = fieldName.substring(1);
                
                if (layoutDoc) {
                    const nonUnderscoreLayoutValue = layoutDoc[nonUnderscoreFieldName];
                    if (nonUnderscoreLayoutValue !== undefined) {
                        metadata.fields.layout[nonUnderscoreFieldName] = this.formatFieldValue(nonUnderscoreLayoutValue);
                        metadata.fieldLocationMap[nonUnderscoreFieldName] = 'layout';
                    }
                }
                
                if (dataDoc) {
                    const nonUnderscoreDataValue = dataDoc[nonUnderscoreFieldName];
                    if (nonUnderscoreDataValue !== undefined) {
                        metadata.fields.data[nonUnderscoreFieldName] = this.formatFieldValue(nonUnderscoreDataValue);
                        if (!metadata.fieldLocationMap[nonUnderscoreFieldName]) {
                            metadata.fieldLocationMap[nonUnderscoreFieldName] = 'data';
                        }
                    }
                }
            }
        });

        // Add common field aliases for easier discovery
        // This helps users understand both width and _width refer to the same property
        if (metadata.fields.layout._width !== undefined && metadata.fields.layout.width === undefined) {
            metadata.fields.layout.width = metadata.fields.layout._width;
            metadata.fieldLocationMap.width = 'layout';
        }
        
        if (metadata.fields.layout._height !== undefined && metadata.fields.layout.height === undefined) {
            metadata.fields.layout.height = metadata.fields.layout._height;
            metadata.fieldLocationMap.height = 'layout';
        }

        return metadata;
    }

    /**
     * Edits a specific field on a document
     * @param docId The ID of the document to edit
     * @param fieldName The name of the field to edit
     * @param fieldValue The new value for the field (string, number, or boolean)
     * @returns Object with success status, message, and additional information
     */
    private editDocumentField(docId: string, fieldName: string, fieldValue: string | number | boolean): { 
        success: boolean; 
        message: string; 
        fieldName?: string; 
        originalFieldName?: string; 
        newValue?: any;
        warning?: string;
    } {
        // Normalize field name (handle with/without underscore)
        let normalizedFieldName = fieldName.startsWith('_') ? fieldName : fieldName;
        const strippedFieldName = fieldName.startsWith('_') ? fieldName.substring(1) : fieldName;
        
        // Handle common field name aliases (width → _width, height → _height)
        // Many document fields use '_' prefix for layout properties
        if (fieldName === 'width') {
            normalizedFieldName = '_width';
        } else if (fieldName === 'height') {
            normalizedFieldName = '_height';
        }
        
        // Get the documents
        const doc = this.documentsById.get(docId);
        if (!doc) {
            return { success: false, message: `Document with ID ${docId} not found` };
        }
        
        const layoutDoc = this.layoutDocsById.get(docId);
        const dataDoc = this.dataDocsById.get(docId);
        
        if (!layoutDoc && !dataDoc) {
            return { success: false, message: `Could not find layout or data document for document with ID ${docId}` };
        }
        
        try {
            // Convert the field value to the appropriate type based on field metadata
            const convertedValue = this.convertFieldValue(normalizedFieldName, fieldValue);
            
            let targetDoc: Doc | undefined;
            let targetLocation: string;
            
            // First, check if field exists on layout document using Doc.Get
            if (layoutDoc) {
                const fieldExistsOnLayout = Doc.Get(layoutDoc, normalizedFieldName, true) !== undefined;
                
                // If it exists on layout document, update it there
                if (fieldExistsOnLayout) {
                    targetDoc = layoutDoc;
                    targetLocation = 'layout';
                } 
                // If it has an underscore prefix, it's likely a layout property even if not yet set
                else if (normalizedFieldName.startsWith('_')) {
                    targetDoc = layoutDoc;
                    targetLocation = 'layout';
                }
                // Otherwise, look for or create on data document
                else if (dataDoc) {
                    targetDoc = dataDoc;
                    targetLocation = 'data';
                } 
                // If no data document available, default to layout
                else {
                    targetDoc = layoutDoc;
                    targetLocation = 'layout';
                }
            } 
            // If no layout document, use data document
            else if (dataDoc) {
                targetDoc = dataDoc;
                targetLocation = 'data';
            } else {
                return { success: false, message: `No valid document found for editing` };
            }
            
            if (!targetDoc) {
                return { success: false, message: `Target document not available` };
            }
            
            // Set the field value on the target document
            targetDoc[normalizedFieldName] = convertedValue;
            
            return { 
                success: true, 
                message: `Successfully updated field '${normalizedFieldName}' on ${targetLocation} document (ID: ${docId})`,
                fieldName: normalizedFieldName,
                originalFieldName: fieldName,
                newValue: convertedValue
            };
        } catch (error) {
            console.error('Error editing document field:', error);
            return { 
                success: false, 
                message: `Error updating field: ${error instanceof Error ? error.message : String(error)}` 
            };
        }
    }

    /**
     * Converts a string field value to the appropriate type based on field metadata
     * @param fieldName The name of the field
     * @param fieldValue The string value to convert
     * @returns The converted value with the appropriate type
     */
    private convertFieldValue(fieldName: string, fieldValue: any): any {
        // If fieldValue is already a number or boolean, we don't need to convert it from string
        if (typeof fieldValue === 'number' || typeof fieldValue === 'boolean') {
            return fieldValue;
        }
        
        // If fieldValue is a string "true" or "false", convert to boolean
        if (typeof fieldValue === 'string') {
            if (fieldValue.toLowerCase() === 'true') {
                return true;
            }
            if (fieldValue.toLowerCase() === 'false') {
                return false;
            }
        }
        
        // If fieldValue is not a string (and not a number or boolean), convert it to string
        if (typeof fieldValue !== 'string') {
            fieldValue = String(fieldValue);
        }
        
        // Get field metadata
        const normalizedFieldName = fieldName.startsWith('_') ? fieldName : `_${fieldName}`;
        const strippedFieldName = fieldName.startsWith('_') ? fieldName.substring(1) : fieldName;
        
        // Check both versions of the field name in metadata
        const fieldMeta = this.fieldMetadata[normalizedFieldName] || this.fieldMetadata[strippedFieldName];
        
        // Special handling for width and height without metadata
        if (!fieldMeta && (fieldName === '_width' || fieldName === '_height' || fieldName === 'width' || fieldName === 'height')) {
            const num = Number(fieldValue);
            return isNaN(num) ? fieldValue : num;
        }
        
        if (!fieldMeta) {
            // If no metadata found, just return the string value
            return fieldValue;
        }
        
        // Convert based on field type
        const fieldType = fieldMeta.type;
        
        if (fieldType === 'boolean') {
            // Convert to boolean
            return fieldValue.toLowerCase() === 'true';
        } else if (fieldType === 'number') {
            // Convert to number
            const num = Number(fieldValue);
            return isNaN(num) ? fieldValue : num;
        } else if (fieldType === 'date') {
            // Try to convert to date (stored as number timestamp)
            try {
                return new Date(fieldValue).getTime();
            } catch (e) {
                return fieldValue;
            }
        } else if (fieldType.includes('list') || fieldType.includes('array')) {
            // Try to parse as JSON array
            try {
                return JSON.parse(fieldValue);
            } catch (e) {
                return fieldValue;
            }
        } else if (fieldType === 'json' || fieldType === 'object') {
            // Try to parse as JSON object
            try {
                return JSON.parse(fieldValue);
            } catch (e) {
                return fieldValue;
            }
        }
        
        // Default to string
        return fieldValue;
    }

    /**
     * Formats a field value for JSON output
     * @param value The field value to format
     * @returns A JSON-friendly representation of the field value
     */
    private formatFieldValue(value: any): any {
        if (value === undefined || value === null) {
            return null;
        }
        
        // Handle Doc objects
        if (value instanceof Doc) {
            return {
                type: 'Doc',
                id: value.id || this.ensureDocumentId(value),
                title: value.title || '',
                docType: value.type || '',
            };
        }
        
        // Handle arrays and complex objects
        if (typeof value === 'object') {
            // If the object has a toString method, use it
            if (value.toString && value.toString !== Object.prototype.toString) {
                return value.toString();
            }
            
            try {
                // Try to convert to JSON string
                return JSON.stringify(value);
            } catch (e) {
                return '[Complex Object]';
            }
        }
        
        // Return primitive values as is
        return value;
    }

    /**
     * Executes the document metadata tool
     * @param args The arguments for the tool
     * @returns An observation with the results of the tool execution
     */
    async execute(args: ParametersType<DocumentMetadataToolParamsType>): Promise<Observation[]> {
        console.log('DocumentMetadataTool: Executing with args:', args);
        
        // Find all documents in the Freeform view
        this.findDocumentsInFreeformView();
        
        try {
            // Validate required input parameters based on action
            if (!this.inputValidator(args)) {
                return [{ 
                    type: 'text', 
                    text: `Error: Invalid or missing parameters for action "${args.action}". ${this.getParameterRequirementsByAction(String(args.action))}` 
                }];
            }
            
            // Ensure the action is valid and convert to string
            const action = String(args.action);
            if (!['get', 'edit', 'list'].includes(action)) {
                return [{ 
                    type: 'text', 
                    text: 'Error: Invalid action. Valid actions are "get", "edit", or "list".' 
                }];
            }

            // Safely convert documentId to string or undefined
            const documentId = args.documentId ? String(args.documentId) : undefined;
            
            // Perform the specified action
            switch (action) {
                case 'get': {
                    // Get metadata for a specific document or all documents
                    const result = this.getDocumentMetadata(documentId);
                    console.log('DocumentMetadataTool: Get metadata result:', result);
                    return [{ 
                        type: 'text', 
                        text: `Document metadata ${documentId ? 'for document ' + documentId : ''} retrieved successfully:\n${JSON.stringify(result, null, 2)}` 
                    }];
                }
                
                case 'edit': {
                    // Edit a specific field on a document
                    if (!documentId || !args.fieldName) {
                        return [{ 
                            type: 'text', 
                            text: 'Error: Document ID, field name, and field value are required for edit actions.' 
                        }];
                    }
                    
                    // Ensure document exists
                    if (!this.documentsById.has(documentId)) {
                        return [{ 
                            type: 'text', 
                            text: `Error: Document with ID ${documentId} not found.` 
                        }];
                    }
                    
                    // Get fieldValue in its original form - we'll handle conversion in editDocumentField
                    let fieldValue = args.fieldValue;
                    
                    // Only convert to string if it's neither boolean nor number
                    if (typeof fieldValue !== 'boolean' && typeof fieldValue !== 'number') {
                        fieldValue = String(fieldValue);
                    }
                    
                    const fieldName = String(args.fieldName);
                    
                    // Edit the field
                    const result = this.editDocumentField(
                        documentId,
                        fieldName,
                        fieldValue
                    );
                    
                    console.log('DocumentMetadataTool: Edit field result:', result);
                    
                    if (!result.success) {
                        return [{ type: 'text', text: result.message }];
                    }
                    
                    // Include warning if present
                    let responseText = result.message;
                    if (result.warning) {
                        responseText += `\n\n${result.warning}`;
                    }
                    
                    // Get the updated metadata to return
                    const updatedMetadata = this.getDocumentMetadata(documentId);
                    
                    return [{ 
                        type: 'text', 
                        text: `${responseText}\nUpdated metadata:\n${JSON.stringify(updatedMetadata, null, 2)}` 
                    }];
                }
                
                case 'list': {
                    // List all available documents in simple format
                    const docs = Array.from(this.documentsById.entries()).map(([id, doc]) => ({
                        id,
                        title: doc.title || 'Untitled Document',
                        type: doc.type || 'Unknown Type'
                    }));
                    
                    if (docs.length === 0) {
                        return [{ 
                            type: 'text', 
                            text: 'No documents found in the current view.' 
                        }];
                    }
                    
                    return [{ 
                        type: 'text', 
                        text: `Found ${docs.length} document(s) in the current view:\n${JSON.stringify(docs, null, 2)}` 
                    }];
                }
                
                default:
                    return [{ 
                        type: 'text', 
                        text: 'Error: Unknown action. Valid actions are "get", "edit", or "list".' 
                    }];
            }
        } catch (error) {
            console.error('DocumentMetadataTool execution error:', error);
            return [{ 
                type: 'text', 
                text: `Error executing DocumentMetadataTool: ${error instanceof Error ? error.message : String(error)}` 
            }];
        }
    }

    /**
     * Validates the input parameters for the DocumentMetadataTool
     * This custom validator allows numbers and booleans to be passed for fieldValue 
     * while maintaining compatibility with the standard validation
     * 
     * @param params The parameters to validate
     * @returns True if the parameters are valid, false otherwise
     */
    inputValidator(params: ParametersType<DocumentMetadataToolParamsType>): boolean {
        // Default validation for required fields
        if (params.action === undefined) {
            return false;
        }
        
        // For edit action, documentId, fieldName, and fieldValue are required
        if (params.action === 'edit') {
            if (!params.documentId || !params.fieldName || params.fieldValue === undefined) {
                return false;
            }
        }
        
        // For get action with documentId, documentId is required
        if (params.action === 'get' && params.documentId === '') {
            return false;
        }
        
        // Allow for numeric or boolean fieldValue even though the type is defined as string
        if (params.fieldValue !== undefined) {
            if (typeof params.fieldValue === 'number') {
                console.log('Numeric fieldValue detected, will be converted to string');
                // We'll convert it later, so don't fail validation
                return true;
            }
            
            if (typeof params.fieldValue === 'boolean') {
                console.log('Boolean fieldValue detected, will be converted appropriately');
                // We'll handle boolean conversion in the execute method
                return true;
            }
        }
        
        return true;
    }

    /**
     * Returns the parameter requirements for a specific action
     * @param action The action to get requirements for
     * @returns A string describing the required parameters
     */
    private getParameterRequirementsByAction(action?: string): string {
        if (!action) {
            return 'Please specify an action: "get", "edit", or "list".';
        }

        switch (action.toLowerCase()) {
            case 'get':
                return 'The "get" action accepts an optional documentId parameter.';
            case 'edit':
                return 'The "edit" action requires documentId, fieldName, and fieldValue parameters.';
            case 'list':
                return 'The "list" action does not require any additional parameters.';
            default:
                return `Unknown action "${action}". Valid actions are "get", "edit", or "list".`;
        }
    }

    /**
     * Gets metadata for a specific document or all documents
     * @param documentId Optional ID of a specific document to get metadata for
     * @returns Document metadata or metadata for all documents
     */
    private getDocumentMetadata(documentId?: string): any {
        if (documentId) {
            // Get metadata for a specific document
            return this.extractDocumentMetadata(documentId);
        } else {
            // Get metadata for all documents
            const documentsMetadata: Record<string, any> = {};
            for (const docId of this.documentsById.keys()) {
                documentsMetadata[docId] = this.extractDocumentMetadata(docId);
            }
            
            return {
                documentCount: this.documentsById.size,
                documents: documentsMetadata,
                fieldDefinitions: this.fieldMetadata
            };
        }
    }
}