@4onstudios/iris-agent 0.1.0

package/dist/api/core/agent/utils/environmentSnapshot.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Environment Snapshot Generator
+ * Pre-gathers environment information at conversation start
+ * Reduces exploratory turns and provides immediate context
+ */
+type SnapshotPackageInfo = {
+    name?: string;
+    version?: string;
+    description?: string;
+    scripts: string[];
+    dependencies: string[];
+    devDependencies: string[];
+};
+type EnvironmentSnapshot = {
+    cwd: string;
+    fileTree: string;
+    readme: string | null;
+    packageInfo: SnapshotPackageInfo | null;
+    git: {
+        branch: string;
+        status: string;
+    };
+    environment: {
+        python: string;
+        node: string;
+        npm: string;
+    };
+    generatedAt: string;
+};
+/**
+ * Generate comprehensive environment snapshot
+ * @param {string} workspacePath - Workspace root path
+ * @returns {Promise<object>} Environment snapshot data
+ */
+export declare const getEnvironmentSnapshot: (workspacePath: string) => Promise<EnvironmentSnapshot>;
+/**
+ * Format snapshot as markdown for agent consumption
+ * @param {object} snapshot - Environment snapshot from getEnvironmentSnapshot
+ * @returns {string} Formatted markdown
+ */
+export declare const formatSnapshotAsMarkdown: (snapshot: EnvironmentSnapshot) => string;
+export {};

package/dist/api/core/agent/utils/environmentSnapshot.js

@@ -0,0 +1,213 @@
+/**
+ * Environment Snapshot Generator
+ * Pre-gathers environment information at conversation start
+ * Reduces exploratory turns and provides immediate context
+ */
+import fs from "fs/promises";
+import path from "path";
+import { exec } from "child_process";
+import { promisify } from "util";
+const execAsync = promisify(exec);
+/**
+ * Read file if it exists, return null otherwise
+ * @param {string} filePath - Path to file
+ * @returns {Promise<string|null>} File content or null
+ */
+const readFileIfExists = async (filePath) => {
+    try {
+        const content = await fs.readFile(filePath, "utf8");
+        return content;
+    }
+    catch (error) {
+        return null;
+    }
+};
+/**
+ * Generate file tree with depth limit
+ * @param {string} dirPath - Directory path
+ * @param {object} options - Options {maxDepth, currentDepth}
+ * @returns {Promise<string>} File tree string
+ */
+const generateFileTree = async (dirPath, options = {}) => {
+    const { maxDepth = 3, currentDepth = 0, ignorePatterns = ["node_modules", ".git", "dist", "build", "coverage"], } = options;
+    if (currentDepth >= maxDepth) {
+        return "";
+    }
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        let tree = "";
+        for (const entry of entries) {
+            // Skip ignored patterns
+            if (ignorePatterns.includes(entry.name)) {
+                continue;
+            }
+            const indent = "  ".repeat(currentDepth);
+            const prefix = entry.isDirectory() ? "📁 " : "📄 ";
+            tree += `${indent}${prefix}${entry.name}\n`;
+            if (entry.isDirectory()) {
+                const subPath = path.join(dirPath, entry.name);
+                const subTree = await generateFileTree(subPath, {
+                    maxDepth,
+                    currentDepth: currentDepth + 1,
+                    ignorePatterns,
+                });
+                tree += subTree;
+            }
+        }
+        return tree;
+    }
+    catch (error) {
+        return "";
+    }
+};
+/**
+ * Run command safely, return output or empty string on error
+ * @param {string} command - Command to run
+ * @param {object} options - Exec options
+ * @returns {Promise<string>} Command output
+ */
+const runCommandSafe = async (command, options = {}) => {
+    try {
+        const { stdout } = await execAsync(command, {
+            timeout: 5000,
+            maxBuffer: 1024 * 1024, // 1MB
+            ...options,
+        });
+        return String(stdout).trim();
+    }
+    catch (error) {
+        return "";
+    }
+};
+/**
+ * Generate comprehensive environment snapshot
+ * @param {string} workspacePath - Workspace root path
+ * @returns {Promise<object>} Environment snapshot data
+ */
+export const getEnvironmentSnapshot = async (workspacePath) => {
+    console.log("📸 Generating environment snapshot...");
+    const startTime = Date.now();
+    // Run operations in parallel where possible
+    const [cwd, fileTree, readme, packageJson, gitBranch, gitStatus, pythonVersion, nodeVersion, npmVersion,] = await Promise.all([
+        // Current working directory
+        Promise.resolve(workspacePath),
+        // File tree (limited depth)
+        generateFileTree(workspacePath, { maxDepth: 3 }),
+        // README
+        readFileIfExists(path.join(workspacePath, "README.md")),
+        // package.json
+        readFileIfExists(path.join(workspacePath, "package.json")),
+        // Git info
+        runCommandSafe("git branch --show-current", { cwd: workspacePath }),
+        runCommandSafe("git status --short", { cwd: workspacePath }),
+        // Environment versions
+        runCommandSafe("python --version || python3 --version"),
+        runCommandSafe("node --version"),
+        runCommandSafe("npm --version"),
+    ]);
+    // Parse package.json if available
+    let packageInfo = null;
+    if (packageJson) {
+        try {
+            const pkg = JSON.parse(packageJson);
+            packageInfo = {
+                name: typeof pkg.name === "string" ? pkg.name : undefined,
+                version: typeof pkg.version === "string" ? pkg.version : undefined,
+                description: typeof pkg.description === "string" ? pkg.description : undefined,
+                scripts: Object.keys(pkg.scripts || {}),
+                dependencies: Object.keys(pkg.dependencies || {}),
+                devDependencies: Object.keys(pkg.devDependencies || {}),
+            };
+        }
+        catch (error) {
+            packageInfo = null;
+        }
+    }
+    const elapsed = Date.now() - startTime;
+    console.log(`✅ Environment snapshot generated in ${elapsed}ms`);
+    return {
+        cwd,
+        fileTree,
+        readme: readme ? readme.substring(0, 2000) : null, // Limit README size
+        packageInfo,
+        git: {
+            branch: gitBranch || "unknown",
+            status: gitStatus || "",
+        },
+        environment: {
+            python: pythonVersion || "not installed",
+            node: nodeVersion || "not installed",
+            npm: npmVersion || "not installed",
+        },
+        generatedAt: new Date().toISOString(),
+    };
+};
+/**
+ * Format snapshot as markdown for agent consumption
+ * @param {object} snapshot - Environment snapshot from getEnvironmentSnapshot
+ * @returns {string} Formatted markdown
+ */
+export const formatSnapshotAsMarkdown = (snapshot) => {
+    let markdown = `## Initial Environment State
+
+Generated at: ${snapshot.generatedAt}
+
+### Working Directory
+\`\`\`
+${snapshot.cwd}
+\`\`\`
+
+`;
+    // File tree
+    if (snapshot.fileTree) {
+        markdown += `### File Structure (depth 3)
+\`\`\`
+${snapshot.fileTree}
+\`\`\`
+
+`;
+    }
+    // Package info
+    if (snapshot.packageInfo) {
+        markdown += `### Project: ${snapshot.packageInfo.name}
+- **Version:** ${snapshot.packageInfo.version}
+${snapshot.packageInfo.description
+            ? `- **Description:** ${snapshot.packageInfo.description}`
+            : ""}
+
+**Available Scripts:**
+${snapshot.packageInfo.scripts.map((s) => `- \`npm run ${s}\``).join("\n")}
+
+**Dependencies:** ${snapshot.packageInfo.dependencies.length} packages
+**Dev Dependencies:** ${snapshot.packageInfo.devDependencies.length} packages
+
+`;
+    }
+    // Git info
+    if (snapshot.git.branch !== "unknown") {
+        markdown += `### Git
+- **Branch:** ${snapshot.git.branch}
+${snapshot.git.status
+            ? `- **Status:**\n\`\`\`\n${snapshot.git.status}\n\`\`\`\n`
+            : ""}
+`;
+    }
+    // Environment
+    markdown += `### Environment
+- **Node:** ${snapshot.environment.node}
+- **NPM:** ${snapshot.environment.npm}
+- **Python:** ${snapshot.environment.python}
+
+`;
+    // README excerpt
+    if (snapshot.readme) {
+        markdown += `### README.md (excerpt)
+\`\`\`
+${snapshot.readme}
+${snapshot.readme.length >= 2000 ? "\n... (truncated)" : ""}
+\`\`\`
+
+`;
+    }
+    return markdown;
+};

package/dist/api/core/agent/utils/errorRecovery.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Error Recovery Utilities
+ * Automatic retry logic and error-specific recovery strategies
+ */
+type ToolParams = Record<string, unknown>;
+type ToolResult = Record<string, unknown> & {
+    success?: boolean;
+    error?: string;
+};
+type ToolLike = {
+    name?: string;
+    execute: (params: ToolParams) => Promise<ToolResult>;
+};
+type ToolLikeGeneric<TParams extends ToolParams, TResult extends ToolResult> = {
+    name?: string;
+    execute: (params: TParams) => Promise<TResult>;
+};
+type RecoveryOptions = {
+    maxRetries?: number;
+    searchFiles?: ((pattern: string) => Promise<string[]>) | null;
+    workspacePath?: string;
+    timeout?: number;
+};
+type RecoveryMiddlewareOptions = {
+    maxRetries?: number;
+    onError?: ((error: Error, attempt: number, params: ToolParams) => Promise<boolean> | boolean) | null;
+};
+/**
+ * Execute tool with automatic retry and error recovery
+ * @param {object} tool - Tool object with execute method
+ * @param {object} params - Tool parameters
+ * @param {object} options - Options {maxRetries, searchFiles}
+ * @returns {Promise<any>} Tool result
+ */
+export declare const executeToolWithRecovery: <TParams extends ToolParams, TResult extends ToolResult>(tool: ToolLikeGeneric<TParams, TResult>, params: TParams, options?: RecoveryOptions) => Promise<TResult | ToolResult>;
+/**
+ * Wrap multiple tools with recovery
+ * @param {object[]} tools - Array of tool objects
+ * @returns {object[]} Tools with recovery wrappers
+ */
+export declare const wrapToolsWithRecovery: (tools: ToolLike[]) => ToolLike[];
+/**
+ * Create error recovery middleware for tool execution
+ * @param {Function} executeFunc - Original execute function
+ * @param {object} options - Recovery options
+ * @returns {Function} Wrapped execute function
+ */
+export declare const createRecoveryMiddleware: (executeFunc: (params: ToolParams) => Promise<ToolResult>, options?: RecoveryMiddlewareOptions) => (params: ToolParams) => Promise<ToolResult>;
+export {};

package/dist/api/core/agent/utils/errorRecovery.js

@@ -0,0 +1,229 @@
+/**
+ * Error Recovery Utilities
+ * Automatic retry logic and error-specific recovery strategies
+ */
+import path from "path";
+const isNonRetryableSecurityError = (message) => {
+    const normalized = message.toLowerCase();
+    return (normalized.includes("security error")
+        || normalized.includes("outside workspace root")
+        || normalized.includes("outside workspace boundary")
+        || normalized.includes("access denied"));
+};
+/**
+ * Execute tool with automatic retry and error recovery
+ * @param {object} tool - Tool object with execute method
+ * @param {object} params - Tool parameters
+ * @param {object} options - Options {maxRetries, searchFiles}
+ * @returns {Promise<any>} Tool result
+ */
+export const executeToolWithRecovery = async (tool, params, options = {}) => {
+    const { maxRetries = 2, searchFiles = null } = options;
+    let lastError = null;
+    const toolLabel = tool.name || "unnamed_tool";
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            // Execute the tool
+            const result = await tool.execute(params);
+            // If successful and this was a retry, log the recovery
+            if (attempt > 0 && result && !result.error) {
+                console.log(`✅ Tool ${toolLabel} succeeded after ${attempt} ${attempt === 1 ? "retry" : "retries"}`);
+            }
+            // If successful, reset error tracking
+            if (result && !result.error) {
+                return result;
+            }
+            // If result has error but not an exception, treat as soft error
+            if (result && result.error) {
+                lastError = new Error(String(result.error));
+                throw lastError;
+            }
+            return result;
+        }
+        catch (error) {
+            const err = error;
+            lastError = err;
+            console.warn(`⚠️ Tool ${toolLabel} failed (attempt ${attempt + 1}/${maxRetries + 1}):`, err.message);
+            if (isNonRetryableSecurityError(err.message)) {
+                break;
+            }
+            // Don't retry on last attempt
+            if (attempt === maxRetries) {
+                break;
+            }
+            // Attempt to fix common issues
+            const recoveryResult = await attemptRecovery(tool, params, err, {
+                searchFiles,
+            });
+            if (recoveryResult.recovered) {
+                console.log(`✅ Recovered from error: ${recoveryResult.strategy}`);
+                // Update params with recovered values
+                Object.assign(params, recoveryResult.params);
+                continue; // Retry with updated params
+            }
+            // If recovery failed, wait before retry
+            await new Promise((resolve) => setTimeout(resolve, 1000 * (attempt + 1)));
+        }
+    }
+    // All retries failed, return error response
+    return {
+        success: false,
+        error: lastError?.message || "Unknown error",
+        suggestion: getErrorSuggestion(lastError || new Error("Unknown error"), tool.name || "unknown"),
+    };
+};
+/**
+ * Attempt to recover from common errors
+ * @param {object} tool - Tool object
+ * @param {object} params - Original params
+ * @param {Error} error - Error that occurred
+ * @param {object} context - Additional context {searchFiles}
+ * @returns {Promise<object>} {recovered, strategy, params}
+ */
+const attemptRecovery = async (tool, params, error, context = {}) => {
+    const { searchFiles } = context;
+    void tool;
+    // File not found - try searching for it
+    if (error.code === "ENOENT" || error.message.includes("no such file")) {
+        console.log("🔍 File not found, attempting search...");
+        if (searchFiles && typeof params.filePath === "string") {
+            try {
+                const fileName = path.basename(params.filePath);
+                const searchResult = await searchFiles(`**/*${fileName}*`);
+                if (searchResult && searchResult.length > 0) {
+                    console.log(`✅ Found file at: ${searchResult[0]}`);
+                    return {
+                        recovered: true,
+                        strategy: "file_search",
+                        params: { ...params, filePath: searchResult[0] },
+                    };
+                }
+            }
+            catch (searchError) {
+                const err = searchError;
+                console.warn("Search failed:", err.message);
+            }
+        }
+    }
+    // Permission denied
+    if (error.message.includes("permission denied") || error.code === "EACCES") {
+        return {
+            recovered: false,
+            strategy: "permission_error",
+            suggestion: "This operation requires elevated permissions. Please check file permissions or run with appropriate access.",
+        };
+    }
+    // Path traversal / invalid path
+    if (error.message.includes("path") && error.message.includes("invalid")) {
+        console.log("🔍 Invalid path, attempting normalization...");
+        if (typeof params.filePath === "string") {
+            const normalized = path.normalize(params.filePath);
+            if (normalized !== params.filePath) {
+                return {
+                    recovered: true,
+                    strategy: "path_normalization",
+                    params: { ...params, filePath: normalized },
+                };
+            }
+        }
+    }
+    // Timeout error
+    if (error.message.includes("timeout") || error.code === "ETIMEDOUT") {
+        console.log("⏱️ Timeout detected, will retry with longer timeout...");
+        return {
+            recovered: true,
+            strategy: "increase_timeout",
+            params: {
+                ...params,
+                timeout: (typeof params.timeout === "number" ? params.timeout : 5000) * 2,
+            },
+        };
+    }
+    // No recovery strategy found
+    return { recovered: false };
+};
+/**
+ * Get helpful error suggestion based on error and tool
+ * @param {Error} error - The error
+ * @param {string} toolName - Tool name
+ * @returns {string} Suggestion text
+ */
+const getErrorSuggestion = (error, toolName) => {
+    const message = error.message.toLowerCase();
+    void toolName;
+    if (message.includes("not found") || message.includes("enoent")) {
+        return "File or directory not found. Try using searchFiles to locate the correct path, or verify the path exists in the workspace.";
+    }
+    if (message.includes("permission")) {
+        return "Permission denied. Check file permissions or try a different approach that doesn't require elevated access.";
+    }
+    if (message.includes("timeout")) {
+        return "Operation timed out. The file or operation may be too large. Try processing smaller chunks or using a different approach.";
+    }
+    if (message.includes("syntax") || message.includes("parse")) {
+        return "Syntax or parsing error. Verify the content format and try again with corrected syntax.";
+    }
+    if (message.includes("network") || message.includes("connection")) {
+        return "Network or connection error. Check internet connectivity and try again.";
+    }
+    // Generic suggestion
+    return "Operation failed. Review the error message and try an alternative approach or break the task into smaller steps.";
+};
+/**
+ * Wrap multiple tools with recovery
+ * @param {object[]} tools - Array of tool objects
+ * @returns {object[]} Tools with recovery wrappers
+ */
+export const wrapToolsWithRecovery = (tools) => {
+    return tools.map((tool) => ({
+        ...tool,
+        execute: async (params) => {
+            const searchTool = tools.find((t) => t.name === "searchFiles");
+            return executeToolWithRecovery(tool, params, {
+                // Pass searchFiles tool if available for file recovery
+                searchFiles: searchTool
+                    ? async (pattern) => {
+                        const result = await searchTool.execute({ pattern });
+                        const files = result.files;
+                        return Array.isArray(files)
+                            ? files.filter((file) => typeof file === "string")
+                            : [];
+                    }
+                    : null,
+            });
+        },
+    }));
+};
+/**
+ * Create error recovery middleware for tool execution
+ * @param {Function} executeFunc - Original execute function
+ * @param {object} options - Recovery options
+ * @returns {Function} Wrapped execute function
+ */
+export const createRecoveryMiddleware = (
+// eslint-disable-next-line no-unused-vars
+executeFunc, options = {}) => {
+    return async (params) => {
+        const { maxRetries = 2, onError = null } = options;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await executeFunc(params);
+            }
+            catch (error) {
+                const err = error;
+                if (onError) {
+                    const shouldRetry = await onError(err, attempt, params);
+                    if (!shouldRetry || attempt === maxRetries) {
+                        throw err;
+                    }
+                }
+                else if (attempt === maxRetries) {
+                    throw err;
+                }
+                // Wait before retry
+                await new Promise((resolve) => setTimeout(resolve, 1000 * (attempt + 1)));
+            }
+        }
+        throw new Error("Recovery middleware exhausted retries without result");
+    };
+};

package/dist/api/core/agent/utils/multimodalTokenLimiter.d.ts

@@ -0,0 +1,8 @@
+import { TokenLimiterProcessor } from "@mastra/core/processors";
+import type { ProcessInputStepArgs } from "@mastra/core/processors";
+export declare const redactMultimodalPayloads: (messages: unknown[]) => (() => void);
+export declare class MultimodalTokenLimiterProcessor extends TokenLimiterProcessor {
+    private readonly supportsVision;
+    constructor(limit: number, supportsVision?: boolean);
+    processInputStep(args: ProcessInputStepArgs): Promise<void>;
+}