@4onstudios/iris-agent 0.1.0

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

@@ -0,0 +1,90 @@
+/**
+ * Format Document Tool
+ * Uses LSP to format an entire file according to language server formatting rules.
+ */
+import { coreLsp } from "../../library/lsp/coreLsp.js";
+import fs from "fs/promises";
+const formatDocumentTool = {
+    name: "formatDocument",
+    description: `Format an entire file using the language server's formatting provider.
+Applies consistent formatting rules such as indentation, spacing, and line endings.
+
+Use this when you need to:
+- Clean up code formatting after edits
+- Ensure a file follows project style conventions
+- Normalise whitespace, indentation, or brace placement`,
+    parameters: {
+        type: "object",
+        properties: {
+            filePath: {
+                type: "string",
+                description: "Absolute path to the file to format",
+            },
+            tabSize: {
+                type: "number",
+                description: "Number of spaces per indentation level (default: 2)",
+            },
+            insertSpaces: {
+                type: "boolean",
+                description: "Use spaces instead of tabs (default: true)",
+            },
+            trimTrailingWhitespace: {
+                type: "boolean",
+                description: "Remove trailing whitespace from each line (default: true)",
+            },
+            insertFinalNewline: {
+                type: "boolean",
+                description: "Ensure file ends with a newline (default: true)",
+            },
+            trimFinalNewlines: {
+                type: "boolean",
+                description: "Remove extra blank lines at end of file (default: true)",
+            },
+        },
+        required: ["filePath"],
+    },
+    async execute({ filePath, tabSize = 2, insertSpaces = true, trimTrailingWhitespace = true, insertFinalNewline = true, trimFinalNewlines = true, }) {
+        try {
+            await fs.access(filePath);
+            const result = (await coreLsp.formatDocument(filePath, {
+                tabSize,
+                insertSpaces,
+                trimTrailingWhitespace,
+                insertFinalNewline,
+                trimFinalNewlines,
+            }));
+            if (!result || result.length === 0) {
+                return {
+                    success: true,
+                    filePath,
+                    editCount: 0,
+                    edits: [],
+                    summary: "No formatting changes required",
+                };
+            }
+            const edits = result.map((edit) => ({
+                startLine: (edit.range?.start?.line ?? 0) + 1,
+                startCharacter: (edit.range?.start?.character ?? 0) + 1,
+                endLine: (edit.range?.end?.line ?? 0) + 1,
+                endCharacter: (edit.range?.end?.character ?? 0) + 1,
+                newText: edit.newText ?? "",
+            }));
+            return {
+                success: true,
+                filePath,
+                editCount: edits.length,
+                edits,
+                summary: `${edits.length} formatting edit${edits.length === 1 ? "" : "s"} produced`,
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false,
+                error: err.message,
+                filePath,
+            };
+        }
+    },
+};
+export default formatDocumentTool;

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

@@ -0,0 +1,77 @@
+/**
+ * Get Code Actions Tool
+ * Uses LSP to retrieve available code actions (quick fixes, refactors) for a range.
+ */
+type GetCodeActionsParams = {
+    filePath: string;
+    startLine: number;
+    startCharacter: number;
+    endLine?: number;
+    endCharacter?: number;
+    only?: string[];
+};
+type ParsedCodeAction = {
+    title: string;
+    kind: string;
+    isPreferred: boolean;
+    hasEdit: boolean;
+    hasCommand: boolean;
+};
+type GetCodeActionsResult = {
+    success: true;
+    filePath: string;
+    range: {
+        startLine: number;
+        startCharacter: number;
+        endLine: number;
+        endCharacter: number;
+    };
+    count: number;
+    actions: ParsedCodeAction[];
+    quickFixes: ParsedCodeAction[];
+    refactors: ParsedCodeAction[];
+} | {
+    success: false;
+    message?: string;
+    error?: string;
+    filePath: string;
+};
+declare const getCodeActionsTool: {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            filePath: {
+                type: string;
+                description: string;
+            };
+            startLine: {
+                type: string;
+                description: string;
+            };
+            startCharacter: {
+                type: string;
+                description: string;
+            };
+            endLine: {
+                type: string;
+                description: string;
+            };
+            endCharacter: {
+                type: string;
+                description: string;
+            };
+            only: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    execute({ filePath, startLine, startCharacter, endLine, endCharacter, only, }: GetCodeActionsParams): Promise<GetCodeActionsResult>;
+};
+export default getCodeActionsTool;

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

@@ -0,0 +1,97 @@
+/**
+ * Get Code Actions Tool
+ * Uses LSP to retrieve available code actions (quick fixes, refactors) for a range.
+ */
+import { coreLsp } from "../../library/lsp/coreLsp.js";
+import fs from "fs/promises";
+const getCodeActionsTool = {
+    name: "getCodeActions",
+    description: `Get available code actions (quick fixes, refactors, source actions) for a range in a file.
+Returns actionable suggestions provided by the language server such as:
+- Quick fixes for errors and warnings
+- Refactoring options (extract function, rename, etc.)
+- Import organization
+- Code generation
+
+Use this when you need to:
+- See what quick fixes are available for a diagnostic
+- Find refactoring opportunities
+- Organise imports
+- Apply suggested code improvements`,
+    parameters: {
+        type: "object",
+        properties: {
+            filePath: {
+                type: "string",
+                description: "Absolute path to the file",
+            },
+            startLine: {
+                type: "number",
+                description: "Start line number (1-based) of the selection or cursor",
+            },
+            startCharacter: {
+                type: "number",
+                description: "Start character (1-based) of the selection",
+            },
+            endLine: {
+                type: "number",
+                description: "End line number (1-based, defaults to startLine)",
+            },
+            endCharacter: {
+                type: "number",
+                description: "End character (1-based, defaults to startCharacter)",
+            },
+            only: {
+                type: "array",
+                items: { type: "string" },
+                description: "Optional list of code action kinds to request e.g. [\"quickfix\", \"refactor\"]",
+            },
+        },
+        required: ["filePath", "startLine", "startCharacter"],
+    },
+    async execute({ filePath, startLine, startCharacter, endLine, endCharacter, only, }) {
+        try {
+            await fs.access(filePath);
+            const resolvedEndLine = endLine ?? startLine;
+            const resolvedEndCharacter = endCharacter ?? startCharacter;
+            const result = (await coreLsp.getCodeActions(filePath, startLine, startCharacter, resolvedEndLine, resolvedEndCharacter, only ? { only } : {}));
+            if (!result || result.length === 0) {
+                return {
+                    success: false,
+                    message: `No code actions available at ${filePath}:${startLine}:${startCharacter}`,
+                    filePath,
+                };
+            }
+            const parsed = result.map((action) => ({
+                title: action.title ?? "Unnamed action",
+                kind: action.kind ?? "unknown",
+                isPreferred: action.isPreferred ?? false,
+                hasEdit: !!(action.edit?.changes || action.edit?.documentChanges),
+                hasCommand: !!action.command,
+            }));
+            return {
+                success: true,
+                filePath,
+                range: {
+                    startLine,
+                    startCharacter,
+                    endLine: resolvedEndLine,
+                    endCharacter: resolvedEndCharacter,
+                },
+                count: parsed.length,
+                actions: parsed,
+                quickFixes: parsed.filter((a) => a.kind.startsWith("quickfix")),
+                refactors: parsed.filter((a) => a.kind.startsWith("refactor")),
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false,
+                error: err.message,
+                filePath,
+            };
+        }
+    },
+};
+export default getCodeActionsTool;

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

@@ -0,0 +1,77 @@
+/**
+ * Get Code Completion Tool
+ * Uses LSP to provide intelligent code completion suggestions
+ */
+type ParsedCompletionItem = {
+    label: string;
+    kind: string;
+    detail?: string;
+    documentation?: string;
+    insertText: string;
+    sortText: string;
+    filterText: string;
+    deprecated: boolean;
+    preselect: boolean;
+};
+type GetCodeCompletionParams = {
+    filePath: string;
+    line: number;
+    character: number;
+    triggerCharacter?: string;
+};
+type GetCodeCompletionResult = {
+    success: true;
+    filePath: string;
+    position: {
+        line: number;
+        character: number;
+    };
+    triggerCharacter?: string;
+    totalItems: number;
+    itemsReturned: number;
+    isIncomplete: boolean;
+    topSuggestions: ParsedCompletionItem[];
+    allSuggestions: ParsedCompletionItem[];
+    byKind: Record<string, ParsedCompletionItem[]>;
+    summary: Array<{
+        kind: string;
+        count: number;
+    }>;
+} | {
+    success: false;
+    message?: string;
+    error?: string;
+    filePath: string;
+    position: {
+        line: number;
+        character: number;
+    };
+};
+declare const getCodeCompletionTool: {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            filePath: {
+                type: string;
+                description: string;
+            };
+            line: {
+                type: string;
+                description: string;
+            };
+            character: {
+                type: string;
+                description: string;
+            };
+            triggerCharacter: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    execute({ filePath, line, character, triggerCharacter, }: GetCodeCompletionParams): Promise<GetCodeCompletionResult>;
+};
+export default getCodeCompletionTool;

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

@@ -0,0 +1,174 @@
+/**
+ * Get Code Completion Tool
+ * Uses LSP to provide intelligent code completion suggestions
+ */
+import { coreLsp } from "../../library/lsp/coreLsp.js";
+import fs from "fs/promises";
+const getCodeCompletionTool = {
+    name: "getCodeCompletion",
+    description: `Get intelligent code completion suggestions at a specific position in a file.
+Provides context-aware suggestions including:
+- Variable names and properties
+- Function names and parameters
+- Type suggestions
+- Import suggestions
+- Snippet completions
+
+Use this when you need to:
+- Autocomplete code while writing
+- Discover available methods/properties
+- Find correct function signatures
+- Get import suggestions`,
+    parameters: {
+        type: "object",
+        properties: {
+            filePath: {
+                type: "string",
+                description: "Absolute path to the file",
+            },
+            line: {
+                type: "number",
+                description: "Line number (1-based) where completion is needed",
+            },
+            character: {
+                type: "number",
+                description: "Character position (1-based) within the line",
+            },
+            triggerCharacter: {
+                type: "string",
+                description: "Optional trigger character like '.', '(' that initiated completion",
+            },
+        },
+        required: ["filePath", "line", "character"],
+    },
+    async execute({ filePath, line, character, triggerCharacter, }) {
+        try {
+            // Verify file exists
+            await fs.access(filePath);
+            // Get completion from LSP
+            const completionResult = (await coreLsp.getCompletion(filePath, line, character));
+            if (!completionResult) {
+                return {
+                    success: false,
+                    message: `No completions available at ${filePath}:${line}:${character}`,
+                    filePath,
+                    position: { line, character },
+                };
+            }
+            // Handle both CompletionList and CompletionItem[] formats
+            let items = [];
+            let isIncomplete = false;
+            if (Array.isArray(completionResult)) {
+                items = completionResult;
+            }
+            else if (completionResult.items) {
+                items = completionResult.items;
+                isIncomplete = completionResult.isIncomplete || false;
+            }
+            if (items.length === 0) {
+                return {
+                    success: false,
+                    message: `No completion suggestions at ${filePath}:${line}:${character}`,
+                    filePath,
+                    position: { line, character },
+                };
+            }
+            // Parse completion items
+            const completionKindNames = {
+                1: "Text",
+                2: "Method",
+                3: "Function",
+                4: "Constructor",
+                5: "Field",
+                6: "Variable",
+                7: "Class",
+                8: "Interface",
+                9: "Module",
+                10: "Property",
+                11: "Unit",
+                12: "Value",
+                13: "Enum",
+                14: "Keyword",
+                15: "Snippet",
+                16: "Color",
+                17: "File",
+                18: "Reference",
+                19: "Folder",
+                20: "EnumMember",
+                21: "Constant",
+                22: "Struct",
+                23: "Event",
+                24: "Operator",
+                25: "TypeParameter",
+            };
+            const parsedItems = items.slice(0, 50).map((item) => {
+                // Extract text to insert
+                let insertText = item.insertText || item.label;
+                let textEdit = null;
+                if (item.textEdit) {
+                    textEdit = {
+                        newText: item.textEdit.newText || item.textEdit.insert?.newText,
+                        range: item.textEdit.range || item.textEdit.insert?.range,
+                    };
+                    insertText = textEdit.newText ?? insertText;
+                }
+                return {
+                    label: item.label,
+                    kind: item.kind !== undefined
+                        ? completionKindNames[item.kind] || "Unknown"
+                        : "Unknown",
+                    detail: item.detail || undefined,
+                    documentation: typeof item.documentation === "string"
+                        ? item.documentation
+                        : item.documentation?.value || undefined,
+                    insertText,
+                    sortText: item.sortText || item.label,
+                    filterText: item.filterText || item.label,
+                    deprecated: item.deprecated || false,
+                    preselect: item.preselect || false,
+                };
+            });
+            // Group by kind for easier consumption
+            const byKind = {};
+            parsedItems.forEach((item) => {
+                if (!byKind[item.kind]) {
+                    byKind[item.kind] = [];
+                }
+                byKind[item.kind].push(item);
+            });
+            // Top suggestions (preselected or first 10)
+            const topSuggestions = parsedItems
+                .filter((item) => item.preselect)
+                .slice(0, 5);
+            if (topSuggestions.length === 0) {
+                topSuggestions.push(...parsedItems.slice(0, 10));
+            }
+            return {
+                success: true,
+                filePath,
+                position: { line, character },
+                triggerCharacter,
+                totalItems: items.length,
+                itemsReturned: parsedItems.length,
+                isIncomplete,
+                topSuggestions,
+                allSuggestions: parsedItems,
+                byKind,
+                summary: Object.keys(byKind).map((kind) => ({
+                    kind,
+                    count: byKind[kind].length,
+                })),
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false,
+                error: err.message,
+                filePath,
+                position: { line, character },
+            };
+        }
+    },
+};
+export default getCodeCompletionTool;

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

@@ -0,0 +1,14 @@
+/**
+ * getCodeContext tool - Fetches relevant code snippets for answering questions
+ * Similar to how VS Code Copilot finds and references code
+ */
+declare const getCodeContextTool: import("@mastra/core/tools").Tool<{
+    cwd?: string;
+    query?: string;
+    maxResults?: number;
+    symbols?: string[];
+    targetFiles?: string[];
+    includeDefinitions?: boolean;
+    includeUsages?: boolean;
+}, unknown, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "getCodeContext", unknown>;
+export default getCodeContextTool;