@4onstudios/iris-agent 0.1.0

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

@@ -0,0 +1,282 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import fs from "fs/promises";
+import path from "path";
+/**
+ * getCodeContext tool - Fetches relevant code snippets for answering questions
+ * Similar to how VS Code Copilot finds and references code
+ */
+const getCodeContextTool = createTool({
+    id: "getCodeContext",
+    description: `Get code context and snippets relevant to a user's question. Use this tool when:
+- User asks about how code works or what it does
+- User wants to understand a specific function, class, or variable
+- User asks about connections between different parts of the code
+- User needs context about a specific file or feature
+
+This tool searches for relevant code and returns snippets with file paths and line numbers,
+formatted for display with proper code references (like VS Code Copilot style).`,
+    inputSchema: z.object({
+        query: z
+            .string()
+            .describe("The question or topic to find code context for (e.g., 'how does authentication work', 'where is the API called')"),
+        targetFiles: z
+            .array(z.string())
+            .optional()
+            .describe("Specific files to search in (relative paths)"),
+        symbols: z
+            .array(z.string())
+            .optional()
+            .describe("Specific symbol names to look for (function names, class names, variables)"),
+        includeDefinitions: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Whether to include symbol definitions"),
+        includeUsages: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Whether to include where symbols are used"),
+        maxResults: z
+            .number()
+            .optional()
+            .default(5)
+            .describe("Maximum number of code snippets to return"),
+        cwd: z.string().optional().describe("Working directory (workspace root)"),
+    }),
+    execute: async ({ query, targetFiles, symbols, includeDefinitions = true, includeUsages = true, maxResults = 5, cwd, }) => {
+        const workspacePath = cwd || process.cwd();
+        const results = {
+            success: true,
+            query,
+            codeReferences: [],
+            summary: "",
+        };
+        try {
+            // Helper to read file and extract snippet around a line
+            const extractSnippet = async (filePath, targetLine, contextLines = 5) => {
+                try {
+                    const absolutePath = path.isAbsolute(filePath)
+                        ? filePath
+                        : path.join(workspacePath, filePath);
+                    const content = await fs.readFile(absolutePath, "utf-8");
+                    const lines = content.split("\n");
+                    const startLine = Math.max(0, targetLine - contextLines - 1);
+                    const endLine = Math.min(lines.length - 1, targetLine + contextLines - 1);
+                    return {
+                        code: lines.slice(startLine, endLine + 1).join("\n"),
+                        startLine: startLine + 1,
+                        endLine: endLine + 1,
+                        totalLines: lines.length,
+                    };
+                }
+                catch {
+                    return null;
+                }
+            };
+            // Helper to find symbol definitions in a file
+            const findSymbolInFile = async (filePath, symbolName) => {
+                try {
+                    const absolutePath = path.isAbsolute(filePath)
+                        ? filePath
+                        : path.join(workspacePath, filePath);
+                    const content = await fs.readFile(absolutePath, "utf-8");
+                    const lines = content.split("\n");
+                    const matches = [];
+                    // Patterns for different types of definitions
+                    const patterns = [
+                        // Function declarations
+                        new RegExp(`^\\s*(async\\s+)?function\\s+${symbolName}\\s*\\(`, "m"),
+                        // Arrow functions and const/let/var declarations
+                        new RegExp(`^\\s*(export\\s+)?(const|let|var)\\s+${symbolName}\\s*=`, "m"),
+                        // Class declarations
+                        new RegExp(`^\\s*(export\\s+)?class\\s+${symbolName}\\b`, "m"),
+                        // Method definitions in classes
+                        new RegExp(`^\\s*(async\\s+)?${symbolName}\\s*\\([^)]*\\)\\s*{`, "m"),
+                        // TypeScript interface/type
+                        new RegExp(`^\\s*(export\\s+)?(interface|type)\\s+${symbolName}\\b`, "m"),
+                        // Object property (for enums, etc.)
+                        new RegExp(`\\b${symbolName}\\s*[:=]\\s*`, "m"),
+                    ];
+                    lines.forEach((line, index) => {
+                        for (const pattern of patterns) {
+                            if (pattern.test(line)) {
+                                matches.push({
+                                    line: index + 1,
+                                    type: "definition",
+                                    text: line.trim(),
+                                });
+                                break;
+                            }
+                        }
+                    });
+                    return matches;
+                }
+                catch {
+                    return [];
+                }
+            };
+            // Helper to find symbol usages in a file
+            const findUsagesInFile = async (filePath, symbolName) => {
+                try {
+                    const absolutePath = path.isAbsolute(filePath)
+                        ? filePath
+                        : path.join(workspacePath, filePath);
+                    const content = await fs.readFile(absolutePath, "utf-8");
+                    const lines = content.split("\n");
+                    const usages = [];
+                    const usagePattern = new RegExp(`\\b${symbolName}\\b`, "g");
+                    lines.forEach((line, index) => {
+                        if (usagePattern.test(line)) {
+                            // Skip if it's an import statement
+                            if (!line.trim().startsWith("import ")) {
+                                usages.push({
+                                    line: index + 1,
+                                    type: "usage",
+                                    text: line.trim(),
+                                });
+                            }
+                        }
+                    });
+                    return usages;
+                }
+                catch {
+                    return [];
+                }
+            };
+            // Get list of files to search
+            let filesToSearch = targetFiles || [];
+            // If no specific files, get relevant files from workspace
+            if (filesToSearch.length === 0) {
+                try {
+                    const { glob } = await import("glob");
+                    const pattern = "**/*.{js,jsx,ts,tsx,py,java,swift,kt,go,rs,c,cpp,cs}";
+                    const files = await glob(pattern, {
+                        cwd: workspacePath,
+                        ignore: [
+                            "**/node_modules/**",
+                            "**/dist/**",
+                            "**/build/**",
+                            "**/.git/**",
+                        ],
+                        nodir: true,
+                    });
+                    filesToSearch = files.slice(0, 20); // Limit to 20 files for performance
+                }
+                catch (e) {
+                    console.error("Error globbing files:", e);
+                }
+            }
+            // Search for symbols if provided
+            if (symbols && symbols.length > 0) {
+                for (const symbol of symbols) {
+                    for (const file of filesToSearch) {
+                        // Find definitions
+                        if (includeDefinitions) {
+                            const definitions = await findSymbolInFile(file, symbol);
+                            for (const def of definitions) {
+                                const snippet = await extractSnippet(file, def.line, 8);
+                                if (snippet) {
+                                    results.codeReferences.push({
+                                        filePath: file,
+                                        code: snippet.code,
+                                        startLine: snippet.startLine,
+                                        endLine: snippet.endLine,
+                                        description: `Definition of \`${symbol}\``,
+                                        symbol,
+                                        type: "definition",
+                                    });
+                                }
+                            }
+                        }
+                        // Find usages
+                        if (includeUsages) {
+                            const usages = await findUsagesInFile(file, symbol);
+                            // Limit usages per file
+                            for (const usage of usages.slice(0, 3)) {
+                                const snippet = await extractSnippet(file, usage.line, 3);
+                                if (snippet) {
+                                    results.codeReferences.push({
+                                        filePath: file,
+                                        code: snippet.code,
+                                        startLine: snippet.startLine,
+                                        endLine: snippet.endLine,
+                                        description: `Usage of \`${symbol}\``,
+                                        symbol,
+                                        type: "usage",
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // If query contains code snippet, search for it
+            const codePatterns = query.match(/`([^`]+)`/g);
+            if (codePatterns) {
+                for (const pattern of codePatterns) {
+                    const searchTerm = pattern.replace(/`/g, "");
+                    for (const file of filesToSearch) {
+                        try {
+                            const absolutePath = path.isAbsolute(file)
+                                ? file
+                                : path.join(workspacePath, file);
+                            const content = await fs.readFile(absolutePath, "utf-8");
+                            if (content.includes(searchTerm)) {
+                                const lines = content.split("\n");
+                                const lineIndex = lines.findIndex((l) => l.includes(searchTerm));
+                                if (lineIndex >= 0) {
+                                    const snippet = await extractSnippet(file, lineIndex + 1, 5);
+                                    if (snippet) {
+                                        results.codeReferences.push({
+                                            filePath: file,
+                                            code: snippet.code,
+                                            startLine: snippet.startLine,
+                                            endLine: snippet.endLine,
+                                            description: `Contains \`${searchTerm}\``,
+                                            type: "match",
+                                        });
+                                    }
+                                }
+                            }
+                        }
+                        catch {
+                            // Skip files that can't be read
+                        }
+                    }
+                }
+            }
+            // Limit results
+            results.codeReferences = results.codeReferences.slice(0, maxResults);
+            // Generate summary
+            if (results.codeReferences.length > 0) {
+                const defCount = results.codeReferences.filter((r) => r.type === "definition").length;
+                const usageCount = results.codeReferences.filter((r) => r.type === "usage").length;
+                const matchCount = results.codeReferences.filter((r) => r.type === "match").length;
+                const parts = [];
+                if (defCount > 0)
+                    parts.push(`${defCount} definition(s)`);
+                if (usageCount > 0)
+                    parts.push(`${usageCount} usage(s)`);
+                if (matchCount > 0)
+                    parts.push(`${matchCount} match(es)`);
+                results.summary = `Found ${parts.join(", ")} across ${new Set(results.codeReferences.map((r) => r.filePath)).size} file(s)`;
+            }
+            else {
+                results.summary = "No relevant code found for the query";
+            }
+            return results;
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false,
+                error: err.message,
+                query,
+                codeReferences: [],
+            };
+        }
+    },
+});
+export default getCodeContextTool;

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

@@ -0,0 +1,61 @@
+/**
+ * Get Signature Help Tool
+ * Uses LSP to provide parameter hints when calling functions or methods.
+ */
+type GetSignatureHelpParams = {
+    filePath: string;
+    line: number;
+    character: number;
+};
+type GetSignatureHelpResult = {
+    success: true;
+    filePath: string;
+    position: {
+        line: number;
+        character: number;
+    };
+    activeSignature: number;
+    activeParameter: number;
+    signatures: Array<{
+        label: string;
+        documentation: string;
+        parameters: Array<{
+            label: string;
+            documentation: string;
+        }>;
+    }>;
+    activeSignatureLabel: string;
+} | {
+    success: false;
+    message?: string;
+    error?: string;
+    filePath: string;
+    position: {
+        line: number;
+        character: number;
+    };
+};
+declare const getSignatureHelpTool: {
+    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 }: GetSignatureHelpParams): Promise<GetSignatureHelpResult>;
+};
+export default getSignatureHelpTool;

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

@@ -0,0 +1,85 @@
+/**
+ * Get Signature Help Tool
+ * Uses LSP to provide parameter hints when calling functions or methods.
+ */
+import { coreLsp } from "../../library/lsp/coreLsp.js";
+import fs from "fs/promises";
+const getSignatureHelpTool = {
+    name: "getSignatureHelp",
+    description: `Get function/method signature help and parameter hints at a specific position.
+Shows available overloads, parameter names, types, and documentation while typing a function call.
+
+Use this when you need to:
+- See what parameters a function accepts
+- Understand parameter order and types
+- Get documentation for a specific parameter
+- Check all available overloads for a method`,
+    parameters: {
+        type: "object",
+        properties: {
+            filePath: {
+                type: "string",
+                description: "Absolute path to the file",
+            },
+            line: {
+                type: "number",
+                description: "Line number (1-based) inside a function call",
+            },
+            character: {
+                type: "number",
+                description: "Character position (1-based) inside the argument list",
+            },
+        },
+        required: ["filePath", "line", "character"],
+    },
+    async execute({ filePath, line, character }) {
+        try {
+            await fs.access(filePath);
+            const result = (await coreLsp.getSignatureHelp(filePath, line, character));
+            if (!result || !result.signatures || result.signatures.length === 0) {
+                return {
+                    success: false,
+                    message: `No signature help available at ${filePath}:${line}:${character}`,
+                    filePath,
+                    position: { line, character },
+                };
+            }
+            const extractDoc = (doc) => {
+                if (!doc)
+                    return "";
+                if (typeof doc === "string")
+                    return doc;
+                return doc.value || "";
+            };
+            const signatures = result.signatures.map((sig) => ({
+                label: sig.label,
+                documentation: extractDoc(sig.documentation),
+                parameters: (sig.parameters || []).map((param) => ({
+                    label: typeof param.label === "string" ? param.label : sig.label.slice(param.label[0], param.label[1]),
+                    documentation: extractDoc(param.documentation),
+                })),
+            }));
+            const activeIndex = result.activeSignature ?? 0;
+            const activeSig = signatures[activeIndex] ?? signatures[0];
+            return {
+                success: true,
+                filePath,
+                position: { line, character },
+                activeSignature: activeIndex,
+                activeParameter: result.activeParameter ?? 0,
+                signatures,
+                activeSignatureLabel: activeSig?.label ?? "",
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false,
+                error: err.message,
+                filePath,
+                position: { line, character },
+            };
+        }
+    },
+};
+export default getSignatureHelpTool;

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

@@ -0,0 +1,50 @@
+import { z } from "zod";
+type SupportedLanguage = "javascript" | "typescript" | "python" | "java";
+type SymbolKind = "all" | "function" | "class" | "method" | "variable" | "interface" | "type" | "import" | "export";
+type SymbolMatch = {
+    name: string;
+    line: number;
+    text: string;
+    type: string;
+};
+type GetSymbolsParams = {
+    filePath: string;
+    symbolType?: SymbolKind;
+};
+type GetSymbolsResult = {
+    success: true;
+    filePath: string;
+    language: SupportedLanguage;
+    symbolType: SymbolKind;
+    totalSymbols: number;
+    symbols: Partial<Record<Exclude<SymbolKind, "all">, SymbolMatch[]>>;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Tool for getting symbols (functions, classes, methods, variables) from a file
+ * @param {Object} params - The parameters for getting symbols
+ * @param {string} params.filePath - The path to the file to analyze
+ * @param {string} [params.symbolType] - Type of symbols to find (function, class, method, variable, all)
+ * @returns {Promise<Object>} Object containing symbols found or error
+ */
+export declare function getSymbols({ filePath, symbolType, }: GetSymbolsParams): Promise<GetSymbolsResult>;
+/**
+ * Tool metadata for agent system
+ */
+export declare const getSymbolsTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        filePath: z.ZodString;
+        symbolType: z.ZodDefault<z.ZodEnum<["all", "function", "class", "method", "variable", "interface", "type", "import", "export"]>>;
+    }, "strip", z.ZodTypeAny, {
+        filePath?: string;
+        symbolType?: "function" | "type" | "method" | "class" | "interface" | "variable" | "import" | "export" | "all";
+    }, {
+        filePath?: string;
+        symbolType?: "function" | "type" | "method" | "class" | "interface" | "variable" | "import" | "export" | "all";
+    }>;
+    execute: typeof getSymbols;
+};
+export default getSymbolsTool;

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

@@ -0,0 +1,164 @@
+import fs from "fs/promises";
+import path from "path";
+import { z } from "zod";
+// Simple code parser for common languages
+const LANGUAGE_PATTERNS = {
+    javascript: {
+        function: /(?:async\s+)?function\s+(\w+)\s*\(|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^)]*\)\s*=>/g,
+        class: /class\s+(\w+)/g,
+        method: /(\w+)\s*\([^)]*\)\s*{/g,
+        variable: /(?:const|let|var)\s+(\w+)\s*=/g,
+        import: /import\s+.*\s+from\s+['"]([^'"]+)['"]/g,
+        export: /export\s+(?:default\s+)?(?:class|function|const|let|var)\s+(\w+)/g,
+    },
+    typescript: {
+        function: /(?:async\s+)?function\s+(\w+)\s*\(|(?:const|let|var)\s+(\w+)\s*:\s*\([^)]*\)\s*=>/g,
+        class: /class\s+(\w+)/g,
+        interface: /interface\s+(\w+)/g,
+        type: /type\s+(\w+)\s*=/g,
+        method: /(\w+)\s*\([^)]*\)\s*:\s*\w+\s*{/g,
+        variable: /(?:const|let|var)\s+(\w+)\s*:/g,
+        import: /import\s+.*\s+from\s+['"]([^'"]+)['"]/g,
+        export: /export\s+(?:default\s+)?(?:class|function|const|let|var|interface|type)\s+(\w+)/g,
+    },
+    python: {
+        function: /def\s+(\w+)\s*\(/g,
+        class: /class\s+(\w+)/g,
+        method: /def\s+(\w+)\s*\(self/g,
+        import: /(?:from\s+(\S+)\s+)?import\s+(\w+)/g,
+        variable: /^(\w+)\s*=/gm,
+    },
+    java: {
+        class: /(?:public\s+)?class\s+(\w+)/g,
+        interface: /(?:public\s+)?interface\s+(\w+)/g,
+        method: /(?:public|private|protected)\s+(?:\w+\s+)?(\w+)\s*\([^)]*\)\s*{/g,
+        import: /import\s+([\w.]+);/g,
+    },
+};
+/**
+ * Tool for getting symbols (functions, classes, methods, variables) from a file
+ * @param {Object} params - The parameters for getting symbols
+ * @param {string} params.filePath - The path to the file to analyze
+ * @param {string} [params.symbolType] - Type of symbols to find (function, class, method, variable, all)
+ * @returns {Promise<Object>} Object containing symbols found or error
+ */
+export async function getSymbols({ filePath, symbolType = "all", }) {
+    try {
+        // Validate input
+        if (!filePath) {
+            return {
+                success: false,
+                error: "File path is required",
+            };
+        }
+        // Resolve to absolute path
+        const absolutePath = path.resolve(filePath);
+        // Check if file exists
+        try {
+            await fs.access(absolutePath, fs.constants.R_OK);
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `File not found or not readable: ${filePath}`,
+            };
+        }
+        // Detect language from file extension
+        const ext = path.extname(absolutePath).slice(1).toLowerCase();
+        const languageMap = {
+            js: "javascript",
+            jsx: "javascript",
+            ts: "typescript",
+            tsx: "typescript",
+            py: "python",
+            java: "java",
+            // Add more mappings as needed
+        };
+        const language = languageMap[ext];
+        if (!language) {
+            return {
+                success: false,
+                error: `Unsupported file type: ${ext}. Supported: ${Object.keys(languageMap).join(", ")}`,
+            };
+        }
+        // Read file content
+        const content = await fs.readFile(absolutePath, "utf8");
+        const lines = content.split("\n");
+        // Get patterns for detected language
+        const patterns = LANGUAGE_PATTERNS[language];
+        const symbols = {};
+        // Extract symbols based on type
+        const typesToExtract = symbolType === "all"
+            ? Object.keys(patterns)
+            : [symbolType];
+        for (const type of typesToExtract) {
+            if (!patterns[type])
+                continue;
+            const pattern = patterns[type];
+            if (!pattern)
+                continue;
+            const matches = [];
+            let match;
+            // Reset regex state
+            pattern.lastIndex = 0;
+            while ((match = pattern.exec(content)) !== null) {
+                // Find line number
+                const position = match.index;
+                const lineNumber = content.substring(0, position).split("\n").length;
+                // Get the symbol name (could be in different capture groups)
+                const symbolName = match[1] || match[2] || "unknown";
+                matches.push({
+                    name: symbolName,
+                    line: lineNumber,
+                    text: lines[lineNumber - 1]?.trim() || "",
+                    type,
+                });
+            }
+            if (matches.length > 0) {
+                symbols[type] = matches;
+            }
+        }
+        // Count total symbols
+        const totalSymbols = Object.values(symbols).reduce((sum, arr) => sum + arr.length, 0);
+        return {
+            success: true,
+            filePath: absolutePath,
+            language,
+            symbolType,
+            totalSymbols,
+            symbols,
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            error: err.message,
+        };
+    }
+}
+/**
+ * Tool metadata for agent system
+ */
+export const getSymbolsTool = {
+    description: "Get symbols (functions, classes, methods, variables) from a code file",
+    parameters: z.object({
+        filePath: z.string().describe("The path to the file to analyze"),
+        symbolType: z
+            .enum([
+            "all",
+            "function",
+            "class",
+            "method",
+            "variable",
+            "interface",
+            "type",
+            "import",
+            "export",
+        ])
+            .default("all")
+            .describe("Type of symbols to find"),
+    }),
+    execute: getSymbols,
+};
+export default getSymbolsTool;