@4onstudios/iris-agent 0.1.0

package/dist/api/core/agent/tools/fileContent.js

@@ -0,0 +1,227 @@
+import fs from "fs/promises";
+import path from "path";
+import { z } from "zod";
+import { getWorkspaceTree } from "../../library/workspaceIdentity.js";
+async function getFileHandleFromPath(rootHandle, filePath) {
+    const parts = filePath.split("/").filter(Boolean);
+    let currentHandle = rootHandle;
+    for (let i = 0; i < parts.length - 1; i++) {
+        currentHandle = await currentHandle.getDirectoryHandle(parts[i]);
+    }
+    return currentHandle.getFileHandle(parts[parts.length - 1]);
+}
+function searchInStructure(node, fileName, currentPath = "") {
+    const nodePath = currentPath ? `${currentPath}/${node.name}` : node.name;
+    if (node.type === "file" && node.name === fileName) {
+        return {
+            found: true,
+            path: node.path || nodePath,
+            node,
+        };
+    }
+    if (node.type === "folder" && node.children) {
+        for (const child of node.children) {
+            const result = searchInStructure(child, fileName, nodePath);
+            if (result.found) {
+                return result;
+            }
+        }
+    }
+    return { found: false };
+}
+/**
+ * Tool for finding and reading file content by searching through directory tree
+ * Supports both filesystem (Node.js) and web-based File System Access API
+ *
+ * @param {Object} params - The parameters for finding file content
+ * @param {string} params.rootFolder - Root directory to start searching from
+ * @param {string} params.fileName - Exact file name to search for (including extension)
+ * @param {number} [params.concurrency=32] - Maximum number of parallel filesystem operations
+ * @param {boolean} [params.isWebMode=false] - Whether running in web mode (uses File System Access API)
+ * @returns {Promise<Object>} Object containing found status, file path, and content or error
+ */
+export async function findFileContent({ rootFolder, fileName, concurrency = 32, isWebMode = false, }) {
+    try {
+        // Web mode: Use File System Access API via window.directoryHandle
+        if (isWebMode) {
+            console.log("🌐 Web mode: searching for", fileName, "in workspace structure");
+            // Check if we have access to the workspace structure
+            const workspaceStructure = typeof window === "undefined"
+                ? undefined
+                : getWorkspaceTree() || undefined;
+            if (!workspaceStructure) {
+                return {
+                    found: false,
+                    error: "No workspace structure available in web mode. Please open a folder first.",
+                };
+            }
+            const searchResult = searchInStructure(workspaceStructure, fileName);
+            if (!searchResult.found) {
+                return {
+                    found: false,
+                    error: `File not found: ${fileName}`,
+                };
+            }
+            // Now read the file content using File System Access API
+            const directoryHandle = window.directoryHandle;
+            if (!directoryHandle) {
+                return {
+                    found: true,
+                    path: searchResult.path,
+                    content: null,
+                    error: "File found but no directory handle available to read content. File must be opened in the editor first.",
+                };
+            }
+            try {
+                const fileHandle = await getFileHandleFromPath(directoryHandle, searchResult.path);
+                // Request permission if needed
+                const permission = await fileHandle.queryPermission({ mode: "read" });
+                if (permission !== "granted") {
+                    const newPermission = await fileHandle.requestPermission({
+                        mode: "read",
+                    });
+                    if (newPermission !== "granted") {
+                        return {
+                            found: true,
+                            path: searchResult.path,
+                            content: null,
+                            error: "Permission denied to read file",
+                        };
+                    }
+                }
+                // Read the file
+                const fileData = await fileHandle.getFile();
+                const content = await fileData.text();
+                return {
+                    found: true,
+                    path: searchResult.path,
+                    content,
+                };
+            }
+            catch (err) {
+                const error = err;
+                return {
+                    found: true,
+                    path: searchResult.path,
+                    content: null,
+                    error: `Error reading file: ${error.message}`,
+                };
+            }
+        }
+        // Node.js filesystem mode (default)
+        const maxConcurrency = Math.max(1, Math.min(concurrency, 128));
+        // Validate root folder
+        try {
+            const stat = await fs.stat(rootFolder);
+            if (!stat.isDirectory()) {
+                return {
+                    found: false,
+                    error: `rootFolder is not a directory: ${rootFolder}`,
+                };
+            }
+        }
+        catch (err) {
+            void err;
+            return {
+                found: false,
+                error: `rootFolder does not exist or is not accessible: ${rootFolder}`,
+            };
+        }
+        const queue = [rootFolder];
+        let found = false;
+        let foundPath = "";
+        let content = "";
+        const workers = Array.from({ length: maxConcurrency }, async () => {
+            while (!found) {
+                const dir = queue.shift();
+                if (!dir) {
+                    // Nothing left for this worker
+                    break;
+                }
+                let entries;
+                try {
+                    entries = await fs.readdir(dir);
+                }
+                catch (err) {
+                    void err;
+                    // unreadable dir; skip
+                    continue;
+                }
+                for (const entry of entries) {
+                    if (found)
+                        break;
+                    const fullPath = path.join(dir, entry);
+                    let stat;
+                    try {
+                        stat = await fs.stat(fullPath);
+                    }
+                    catch (err) {
+                        void err;
+                        // cannot stat; skip
+                        continue;
+                    }
+                    if (stat.isFile() && entry === fileName) {
+                        try {
+                            content = await fs.readFile(fullPath, "utf8");
+                            foundPath = fullPath;
+                            found = true;
+                            break;
+                        }
+                        catch (err) {
+                            void err;
+                            // can't read; keep searching
+                            continue;
+                        }
+                    }
+                    if (stat.isDirectory()) {
+                        queue.push(fullPath);
+                    }
+                }
+            }
+        });
+        await Promise.all(workers);
+        if (!found) {
+            return {
+                found: false,
+                error: `File not found: ${fileName}`,
+            };
+        }
+        return {
+            found: true,
+            path: foundPath,
+            content,
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            found: false,
+            error: err.message,
+        };
+    }
+}
+/**
+ * Tool metadata for agent system
+ */
+export const findFileContentTool = {
+    description: "Traverse a folder tree starting at rootFolder and return the content of the first file whose name matches fileName. Supports both Node.js filesystem and web-based File System Access API. Useful for finding configuration files, specific source files, or any file by exact name across a directory structure.",
+    parameters: z.object({
+        rootFolder: z.string().describe("Root directory to start searching from"),
+        fileName: z
+            .string()
+            .describe("Exact file name to search for (including extension)"),
+        concurrency: z
+            .number()
+            .int()
+            .positive()
+            .max(128)
+            .default(32)
+            .describe("Maximum number of parallel filesystem operations (default: 32, max: 128). Only used in Node.js mode."),
+        isWebMode: z
+            .boolean()
+            .default(false)
+            .describe("Whether running in web mode (uses File System Access API via the active workspace tree)"),
+    }),
+    execute: findFileContent,
+};
+export default findFileContentTool;

package/dist/api/core/agent/tools/findDefinition.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Find Definition Tool
+ * Uses LSP to find where a symbol is defined (go to definition)
+ */
+type LocationRange = {
+    start: {
+        line: number;
+        character: number;
+    };
+    end: {
+        line: number;
+        character: number;
+    };
+};
+type ParsedDefinitionLocation = {
+    filePath: string;
+    line: number;
+    character: number;
+    endLine: number;
+    endCharacter: number;
+    range: LocationRange;
+};
+type FindDefinitionParams = {
+    filePath: string;
+    line: number;
+    character: number;
+};
+type FindDefinitionResult = {
+    success: true;
+    sourceFile: string;
+    sourcePosition: {
+        line: number;
+        character: number;
+    };
+    definitions: ParsedDefinitionLocation[];
+    primaryDefinition: ParsedDefinitionLocation;
+    context: string | null;
+    count: number;
+} | {
+    success: false;
+    message?: string;
+    error?: string;
+    filePath: string;
+    position: {
+        line: number;
+        character: number;
+    };
+};
+declare const findDefinitionTool: {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            filePath: {
+                type: string;
+                description: string;
+            };
+            line: {
+                type: string;
+                description: string;
+            };
+            character: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    execute({ filePath, line, character, }: FindDefinitionParams): Promise<FindDefinitionResult>;
+};
+export default findDefinitionTool;

package/dist/api/core/agent/tools/findDefinition.js

@@ -0,0 +1,109 @@
+/**
+ * Find Definition Tool
+ * Uses LSP to find where a symbol is defined (go to definition)
+ */
+import { coreLsp } from "../../library/lsp/coreLsp.js";
+import fs from "fs/promises";
+const findDefinitionTool = {
+    name: "findDefinition",
+    description: `Find the definition location of a symbol at a specific position.
+Goes to where a function, class, variable, or import is defined.
+Returns file path, line, and character of the definition.
+
+Use this when you need to:
+- Navigate to function/class definition
+- Find where a variable is declared
+- Trace imports to their source
+- Understand symbol origins`,
+    parameters: {
+        type: "object",
+        properties: {
+            filePath: {
+                type: "string",
+                description: "Absolute path to the file containing the symbol",
+            },
+            line: {
+                type: "number",
+                description: "Line number (1-based) where the symbol is located",
+            },
+            character: {
+                type: "number",
+                description: "Character position (1-based) within the line",
+            },
+        },
+        required: ["filePath", "line", "character"],
+    },
+    async execute({ filePath, line, character, }) {
+        try {
+            // Verify file exists
+            await fs.access(filePath);
+            // Get definition from LSP
+            const definitions = await coreLsp.getDefinition(filePath, line, character);
+            if (!definitions ||
+                (Array.isArray(definitions) && definitions.length === 0)) {
+                return {
+                    success: false,
+                    message: `No definition found for symbol at ${filePath}:${line}:${character}`,
+                    filePath,
+                    position: { line, character },
+                };
+            }
+            // Handle both single location and array of locations
+            const locations = (Array.isArray(definitions)
+                ? definitions
+                : [definitions]);
+            // Parse locations
+            const parsedLocations = locations.map((loc) => {
+                const uri = loc.uri || loc.targetUri;
+                const range = loc.range || loc.targetRange;
+                if (!uri || !range) {
+                    throw new Error("Definition location is missing uri or range");
+                }
+                // Convert file:// URI to path
+                const definitionPath = uri.replace("file://", "");
+                return {
+                    filePath: definitionPath,
+                    line: range.start.line + 1, // Convert to 1-based
+                    character: range.start.character + 1,
+                    endLine: range.end.line + 1,
+                    endCharacter: range.end.character + 1,
+                    range,
+                };
+            });
+            // Read context from definition location
+            const primaryLocation = parsedLocations[0];
+            let context = null;
+            try {
+                const fileContent = await fs.readFile(primaryLocation.filePath, "utf-8");
+                const lines = fileContent.split("\n");
+                // Get 3 lines before and after for context
+                const startLine = Math.max(0, primaryLocation.line - 4);
+                const endLine = Math.min(lines.length, primaryLocation.line + 3);
+                context = lines.slice(startLine, endLine).join("\n");
+            }
+            catch (err) {
+                const error = err;
+                console.warn("Could not read definition context:", error.message || String(err) || "Unknown error");
+            }
+            return {
+                success: true,
+                sourceFile: filePath,
+                sourcePosition: { line, character },
+                definitions: parsedLocations,
+                primaryDefinition: primaryLocation,
+                context,
+                count: parsedLocations.length,
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false,
+                error: err.message,
+                filePath,
+                position: { line, character },
+            };
+        }
+    },
+};
+export default findDefinitionTool;

package/dist/api/core/agent/tools/findReferences.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Find References Tool
+ * Uses LSP to find all references to a symbol in the workspace
+ */
+type LocationRange = {
+    start: {
+        line: number;
+        character: number;
+    };
+    end: {
+        line: number;
+        character: number;
+    };
+};
+type ReferenceLocation = {
+    line: number;
+    character: number;
+    endLine: number;
+    endCharacter: number;
+    range: LocationRange;
+    context?: string;
+};
+type ReferenceFileGroup = {
+    filePath: string;
+    references: ReferenceLocation[];
+    count: number;
+    error?: string;
+};
+type FindReferencesParams = {
+    filePath: string;
+    line: number;
+    character: number;
+    includeDeclaration?: boolean;
+};
+type FindReferencesResult = {
+    success: true;
+    sourceFile: string;
+    sourcePosition: {
+        line: number;
+        character: number;
+    };
+    totalReferences: number;
+    totalFiles: number;
+    files: ReferenceFileGroup[];
+    hasMore: boolean;
+    allFiles: string[];
+} | {
+    success: false;
+    message?: string;
+    error?: string;
+    filePath: string;
+    position: {
+        line: number;
+        character: number;
+    };
+    count?: number;
+};
+declare const findReferencesTool: {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            filePath: {
+                type: string;
+                description: string;
+            };
+            line: {
+                type: string;
+                description: string;
+            };
+            character: {
+                type: string;
+                description: string;
+            };
+            includeDeclaration: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+        };
+        required: string[];
+    };
+    execute({ filePath, line, character, includeDeclaration, }: FindReferencesParams): Promise<FindReferencesResult>;
+};
+export default findReferencesTool;

package/dist/api/core/agent/tools/findReferences.js

@@ -0,0 +1,135 @@
+/**
+ * Find References Tool
+ * Uses LSP to find all references to a symbol in the workspace
+ */
+import { coreLsp } from "../../library/lsp/coreLsp.js";
+import fs from "fs/promises";
+const findReferencesTool = {
+    name: "findReferences",
+    description: `Find all references to a symbol in the workspace.
+Shows everywhere a function, class, variable, or type is used.
+Useful for impact analysis before refactoring.
+
+Use this when you need to:
+- See all usages of a function/class
+- Understand impact of changes
+- Find where a symbol is called
+- Prepare for safe refactoring`,
+    parameters: {
+        type: "object",
+        properties: {
+            filePath: {
+                type: "string",
+                description: "Absolute path to the file containing the symbol",
+            },
+            line: {
+                type: "number",
+                description: "Line number (1-based) where the symbol is located",
+            },
+            character: {
+                type: "number",
+                description: "Character position (1-based) within the line",
+            },
+            includeDeclaration: {
+                type: "boolean",
+                description: "Whether to include the declaration in results (default: true)",
+                default: true,
+            },
+        },
+        required: ["filePath", "line", "character"],
+    },
+    async execute({ filePath, line, character, includeDeclaration = true, }) {
+        try {
+            // Verify file exists
+            await fs.access(filePath);
+            // Get references from LSP
+            const referencesResult = await coreLsp.getReferences(filePath, line, character, includeDeclaration);
+            const references = referencesResult;
+            if (!references || references.length === 0) {
+                return {
+                    success: false,
+                    message: `No references found for symbol at ${filePath}:${line}:${character}`,
+                    filePath,
+                    position: { line, character },
+                    count: 0,
+                };
+            }
+            // Group references by file
+            const referencesByFile = new Map();
+            for (const ref of references) {
+                const uri = ref.uri;
+                const range = ref.range;
+                if (!uri || !range?.start || !range?.end) {
+                    continue;
+                }
+                // Convert file:// URI to path
+                const refPath = uri.replace("file://", "");
+                if (!referencesByFile.has(refPath)) {
+                    referencesByFile.set(refPath, []);
+                }
+                referencesByFile.get(refPath).push({
+                    line: range.start.line + 1, // Convert to 1-based
+                    character: range.start.character + 1,
+                    endLine: range.end.line + 1,
+                    endCharacter: range.end.character + 1,
+                    range,
+                });
+            }
+            // Read context for each reference (limit to first 5 files to avoid huge responses)
+            const filesWithContext = [];
+            const fileEntries = Array.from(referencesByFile.entries()).slice(0, 5);
+            for (const [refPath, locations] of fileEntries) {
+                try {
+                    const fileContent = await fs.readFile(refPath, "utf-8");
+                    const lines = fileContent.split("\n");
+                    const locationsWithContext = locations.map((loc) => {
+                        // Get context line
+                        const contextLine = lines[loc.line - 1] || "";
+                        return {
+                            ...loc,
+                            context: contextLine.trim(),
+                        };
+                    });
+                    filesWithContext.push({
+                        filePath: refPath,
+                        references: locationsWithContext,
+                        count: locationsWithContext.length,
+                    });
+                }
+                catch (err) {
+                    const error = err;
+                    console.warn("Could not read reference context:", error.message || String(err) || "Unknown error");
+                    filesWithContext.push({
+                        filePath: refPath,
+                        references: locations,
+                        count: locations.length,
+                        error: "Could not read file",
+                    });
+                }
+            }
+            // Summary statistics
+            const totalFiles = referencesByFile.size;
+            const totalReferences = references.length;
+            return {
+                success: true,
+                sourceFile: filePath,
+                sourcePosition: { line, character },
+                totalReferences,
+                totalFiles,
+                files: filesWithContext,
+                hasMore: totalFiles > 5,
+                allFiles: Array.from(referencesByFile.keys()),
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false,
+                error: err.message,
+                filePath,
+                position: { line, character },
+            };
+        }
+    },
+};
+export default findReferencesTool;

package/dist/api/core/agent/tools/formatDocument.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Format Document Tool
+ * Uses LSP to format an entire file according to language server formatting rules.
+ */
+type FormatDocumentParams = {
+    filePath: string;
+    tabSize?: number;
+    insertSpaces?: boolean;
+    trimTrailingWhitespace?: boolean;
+    insertFinalNewline?: boolean;
+    trimFinalNewlines?: boolean;
+};
+type FormattingEdit = {
+    startLine: number;
+    startCharacter: number;
+    endLine: number;
+    endCharacter: number;
+    newText: string;
+};
+type FormatDocumentResult = {
+    success: true;
+    filePath: string;
+    editCount: number;
+    edits: FormattingEdit[];
+    summary: string;
+} | {
+    success: false;
+    message?: string;
+    error?: string;
+    filePath: string;
+};
+declare const formatDocumentTool: {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            filePath: {
+                type: string;
+                description: string;
+            };
+            tabSize: {
+                type: string;
+                description: string;
+            };
+            insertSpaces: {
+                type: string;
+                description: string;
+            };
+            trimTrailingWhitespace: {
+                type: string;
+                description: string;
+            };
+            insertFinalNewline: {
+                type: string;
+                description: string;
+            };
+            trimFinalNewlines: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    execute({ filePath, tabSize, insertSpaces, trimTrailingWhitespace, insertFinalNewline, trimFinalNewlines, }: FormatDocumentParams): Promise<FormatDocumentResult>;
+};
+export default formatDocumentTool;