@4onstudios/iris-agent 0.1.0

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

@@ -0,0 +1,60 @@
+/**
+ * Tree Traversal Utilities for Directory Operations
+ * Based on standard tree traversal algorithms
+ */
+export type TraversableNode<T extends TraversableNode<T> = TraversableNode<any>> = {
+    children?: T[];
+};
+export type TraversalType = "bfs" | "pre" | "post";
+/**
+ * Generator-based Pre-Order traversal (DFS)
+ * Useful for processing directories before their contents
+ * Order: current -> left -> right (parent -> children)
+ */
+export declare function walkPreOrder<T extends TraversableNode<T>>(node: T | null | undefined): Generator<T, void, undefined>;
+/**
+ * Generator-based Post-Order traversal (DFS)
+ * Useful for processing directory contents before the directory itself
+ * Order: left -> right -> current (children -> parent)
+ * Good for operations like delete (delete files before directory)
+ */
+export declare function walkPostOrder<T extends TraversableNode<T>>(node: T | null | undefined): Generator<T, void, undefined>;
+/**
+ * Generator-based Breadth-First Search (BFS)
+ * Processes directories level by level
+ * Good for finding files at specific depth or displaying hierarchy
+ */
+export declare function walkBFS<T extends TraversableNode<T>>(node: T | null | undefined): Generator<T, void, undefined>;
+/**
+ * BFS with level information
+ * Returns [node, level] tuples
+ */
+export declare function walkBFSWithLevel<T extends TraversableNode<T>>(node: T | null | undefined): Generator<[T, number], void, undefined>;
+/**
+ * Get all nodes at a specific level
+ */
+export declare function getNodesAtLevel<T extends TraversableNode<T>>(root: T | null | undefined, targetLevel: number): T[];
+/**
+ * Find node by predicate using BFS (finds closest match)
+ */
+export declare function findNode<T extends TraversableNode<T>>(root: T | null | undefined, predicate: (node: T) => boolean): T | null;
+/**
+ * Find all nodes matching predicate
+ */
+export declare function findAllNodes<T extends TraversableNode<T>>(root: T | null | undefined, predicate: (node: T) => boolean): T[];
+/**
+ * Count total nodes in tree
+ */
+export declare function countNodes<T extends TraversableNode<T>>(root: T | null | undefined): number;
+/**
+ * Get maximum depth of tree
+ */
+export declare function getMaxDepth<T extends TraversableNode<T>>(root: T | null | undefined): number;
+/**
+ * Flatten tree to array using specified traversal
+ */
+export declare function flattenTree<T extends TraversableNode<T>>(root: T | null | undefined, traversalType?: TraversalType): T[];
+/**
+ * Example usage for directory trees
+ */
+export declare function exampleUsage(): void;

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

@@ -0,0 +1,217 @@
+/**
+ * Tree Traversal Utilities for Directory Operations
+ * Based on standard tree traversal algorithms
+ */
+/**
+ * Generator-based Pre-Order traversal (DFS)
+ * Useful for processing directories before their contents
+ * Order: current -> left -> right (parent -> children)
+ */
+export function* walkPreOrder(node) {
+    if (!node)
+        return;
+    const stack = [node];
+    while (stack.length) {
+        const item = stack.pop();
+        if (!item) {
+            continue;
+        }
+        yield item;
+        // Push children in reverse order (right first) so left is processed first
+        if (item.children) {
+            for (let i = item.children.length - 1; i >= 0; i--) {
+                stack.push(item.children[i]);
+            }
+        }
+    }
+}
+/**
+ * Generator-based Post-Order traversal (DFS)
+ * Useful for processing directory contents before the directory itself
+ * Order: left -> right -> current (children -> parent)
+ * Good for operations like delete (delete files before directory)
+ */
+export function* walkPostOrder(node) {
+    if (!node)
+        return;
+    const tempStack = [node];
+    const resultStack = [];
+    while (tempStack.length) {
+        const item = tempStack.pop();
+        if (!item) {
+            continue;
+        }
+        resultStack.push(item);
+        // Push children in normal order
+        if (item.children) {
+            for (const child of item.children) {
+                tempStack.push(child);
+            }
+        }
+    }
+    // Yield in reverse order
+    while (resultStack.length) {
+        const item = resultStack.pop();
+        if (item) {
+            yield item;
+        }
+    }
+}
+/**
+ * Generator-based Breadth-First Search (BFS)
+ * Processes directories level by level
+ * Good for finding files at specific depth or displaying hierarchy
+ */
+export function* walkBFS(node) {
+    if (!node)
+        return;
+    const queue = [node];
+    while (queue.length) {
+        const item = queue.shift();
+        if (!item) {
+            continue;
+        }
+        yield item;
+        if (item.children) {
+            for (const child of item.children) {
+                queue.push(child);
+            }
+        }
+    }
+}
+/**
+ * BFS with level information
+ * Returns [node, level] tuples
+ */
+export function* walkBFSWithLevel(node) {
+    if (!node)
+        return;
+    const queue = [[node, 0]];
+    while (queue.length) {
+        const [item, level] = queue.shift();
+        if (!item) {
+            continue;
+        }
+        yield [item, level];
+        if (item.children) {
+            for (const child of item.children) {
+                queue.push([child, level + 1]);
+            }
+        }
+    }
+}
+/**
+ * Get all nodes at a specific level
+ */
+export function getNodesAtLevel(root, targetLevel) {
+    const nodes = [];
+    for (const [node, level] of walkBFSWithLevel(root)) {
+        if (level === targetLevel) {
+            nodes.push(node);
+        }
+        else if (level > targetLevel) {
+            break; // BFS guarantees we won't find more at target level
+        }
+    }
+    return nodes;
+}
+/**
+ * Find node by predicate using BFS (finds closest match)
+ */
+export function findNode(root, 
+// eslint-disable-next-line no-unused-vars
+predicate) {
+    for (const node of walkBFS(root)) {
+        if (predicate(node)) {
+            return node;
+        }
+    }
+    return null;
+}
+/**
+ * Find all nodes matching predicate
+ */
+export function findAllNodes(root, 
+// eslint-disable-next-line no-unused-vars
+predicate) {
+    const results = [];
+    for (const node of walkBFS(root)) {
+        if (predicate(node)) {
+            results.push(node);
+        }
+    }
+    return results;
+}
+/**
+ * Count total nodes in tree
+ */
+export function countNodes(root) {
+    let count = 0;
+    for (const node of walkBFS(root)) {
+        void node;
+        count++;
+    }
+    return count;
+}
+/**
+ * Get maximum depth of tree
+ */
+export function getMaxDepth(root) {
+    let maxDepth = 0;
+    for (const [, level] of walkBFSWithLevel(root)) {
+        maxDepth = Math.max(maxDepth, level);
+    }
+    return maxDepth;
+}
+/**
+ * Flatten tree to array using specified traversal
+ */
+export function flattenTree(root, traversalType = "bfs") {
+    const walker = traversalType === "pre"
+        ? walkPreOrder
+        : traversalType === "post"
+            ? walkPostOrder
+            : walkBFS;
+    return Array.from(walker(root));
+}
+/**
+ * Example usage for directory trees
+ */
+export function exampleUsage() {
+    // Example tree structure (like directory tree from getWorkspaceInfo)
+    const tree = {
+        name: "project",
+        type: "directory",
+        children: [
+            {
+                name: "src",
+                type: "directory",
+                children: [
+                    { name: "index.js", type: "file" },
+                    { name: "utils.js", type: "file" },
+                ],
+            },
+            {
+                name: "package.json",
+                type: "file",
+            },
+        ],
+    };
+    console.log("=== BFS Traversal (Level by Level) ===");
+    for (const node of walkBFS(tree)) {
+        console.log(node.name);
+    }
+    console.log("\n=== Pre-Order Traversal (Parent First) ===");
+    for (const node of walkPreOrder(tree)) {
+        console.log(node.name);
+    }
+    console.log("\n=== Post-Order Traversal (Children First) ===");
+    for (const node of walkPostOrder(tree)) {
+        console.log(node.name);
+    }
+    console.log("\n=== Find all files ===");
+    const files = findAllNodes(tree, (node) => node.type === "file");
+    console.log(files.map((f) => f.name));
+    console.log("\n=== Get depth ===");
+    console.log("Max depth:", getMaxDepth(tree));
+}

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

@@ -0,0 +1,37 @@
+import { z } from "zod";
+type SearchEngine = "duckduckgo" | "bing";
+type SearchResult = {
+    title: string;
+    url: string;
+};
+type SearchWebParams = {
+    query: string;
+    engine?: SearchEngine;
+    maxResults?: number;
+};
+type SearchWebResult = {
+    success: true;
+    results: SearchResult[];
+} | {
+    success: false;
+    error: string;
+};
+export declare function searchWeb({ query, engine, maxResults, }: SearchWebParams): Promise<SearchWebResult>;
+export declare const webSearchTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        query: z.ZodString;
+        engine: z.ZodDefault<z.ZodEnum<["duckduckgo", "bing"]>>;
+        maxResults: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        query?: string;
+        maxResults?: number;
+        engine?: "duckduckgo" | "bing";
+    }, {
+        query?: string;
+        maxResults?: number;
+        engine?: "duckduckgo" | "bing";
+    }>;
+    execute: typeof searchWeb;
+};
+export default webSearchTool;

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

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import BrowserManager from "../../library/BrowserManager.js";
+/**
+ * Web search tool using a search API
+ * @param {Object} params
+ * @param {string} params.query - Search query
+ * @param {number} [params.maxResults=5] - Max results to return
+ * @returns {Promise<Object>} Search results
+ */
+// Engine-specific selectors that target actual search result links,
+// avoiding nav/footer/ad anchors returned by a broad querySelectorAll("a").
+const RESULT_SELECTORS = {
+    duckduckgo: "[data-testid='result-title-a']",
+    bing: ".b_algo h2 a",
+};
+async function webSearch(query, engine = "duckduckgo", maxResults = 5) {
+    if (!query) {
+        throw new Error("Search query is required");
+    }
+    const browserManager = await BrowserManager.getInstance();
+    const page = await browserManager.newPage();
+    try {
+        const url = engine === "duckduckgo"
+            ? `https://duckduckgo.com/?q=${encodeURIComponent(query)}`
+            : `https://bing.com/search?q=${encodeURIComponent(query)}`;
+        // "domcontentloaded" is sufficient for scraping rendered HTML and is
+        // significantly faster than "networkidle2".
+        await page.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 });
+        const selector = RESULT_SELECTORS[engine] ?? RESULT_SELECTORS.duckduckgo;
+        const results = await page.evaluate((resultSelector, limit) => {
+            return Array.from(document.querySelectorAll(resultSelector))
+                .slice(0, limit)
+                .map((a) => ({
+                title: a.textContent?.trim() ?? "",
+                url: a.href,
+            }));
+        }, selector, maxResults);
+        return results;
+    }
+    finally {
+        await page.close();
+    }
+}
+//this is the function that out webSearchTool will be calling
+export async function searchWeb({ query, engine, maxResults = 5, }) {
+    try {
+        //performs web search and returns results, if failed it returns error
+        const results = await webSearch(query, engine, maxResults);
+        return {
+            success: true,
+            results,
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            error: err.message,
+        };
+    }
+}
+export const webSearchTool = {
+    description: "Search the web for real-time information",
+    parameters: z.object({
+        query: z.string().describe("The search query to look up on the web"),
+        engine: z
+            .enum(["duckduckgo", "bing"])
+            .default("duckduckgo")
+            .describe("Search engine to use"),
+        maxResults: z
+            .number()
+            .int()
+            .min(1)
+            .max(20)
+            .default(5)
+            .describe("Maximum number of results to return"),
+    }),
+    execute: searchWeb,
+};
+export default webSearchTool;

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

@@ -0,0 +1,59 @@
+import { z } from "zod";
+type WriteFileParams = {
+    filePath: string;
+    content: string;
+    encoding?: BufferEncoding;
+    createDirectories?: boolean;
+};
+type WriteFileSuccessResult = {
+    success: true;
+    filePath: string;
+    fileExisted: boolean;
+    size: number;
+    created: Date;
+    modified: Date;
+    linesAdded: number;
+    linesRemoved: number;
+    diff: string;
+    oldContent: string;
+    newContent: string;
+};
+type WriteFileErrorResult = {
+    success: false;
+    error: string;
+};
+type WriteFileResult = WriteFileSuccessResult | WriteFileErrorResult;
+/**
+ * Tool for writing content to files
+ * @param {Object} params - The parameters for writing a file
+ * @param {string} params.filePath - The path to the file to write
+ * @param {string} params.content - The content to write to the file
+ * @param {string} [params.encoding='utf8'] - The encoding to use when writing the file
+ * @param {boolean} [params.createDirectories=true] - Whether to create parent directories if they don't exist
+ * @returns {Promise<Object>} Object containing success status and file info or error
+ */
+export declare function writeFile({ filePath, content, encoding, createDirectories, }: WriteFileParams): Promise<WriteFileResult>;
+/**
+ * Tool metadata for agent system
+ */
+export declare const writeFileTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        filePath: z.ZodString;
+        content: z.ZodString;
+        encoding: z.ZodDefault<z.ZodEnum<["utf8", "ascii", "base64", "binary", "hex"]>>;
+        createDirectories: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        content?: string;
+        encoding?: "ascii" | "utf8" | "base64" | "binary" | "hex";
+        filePath?: string;
+        createDirectories?: boolean;
+    }, {
+        content?: string;
+        encoding?: "ascii" | "utf8" | "base64" | "binary" | "hex";
+        filePath?: string;
+        createDirectories?: boolean;
+    }>;
+    execute: typeof writeFile;
+};
+export default writeFileTool;

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

@@ -0,0 +1,97 @@
+import fs from "fs/promises";
+import path from "path";
+import { z } from "zod";
+import { generateDiff } from "../utils/diffUtils.js";
+/**
+ * Tool for writing content to files
+ * @param {Object} params - The parameters for writing a file
+ * @param {string} params.filePath - The path to the file to write
+ * @param {string} params.content - The content to write to the file
+ * @param {string} [params.encoding='utf8'] - The encoding to use when writing the file
+ * @param {boolean} [params.createDirectories=true] - Whether to create parent directories if they don't exist
+ * @returns {Promise<Object>} Object containing success status and file info or error
+ */
+export async function writeFile({ filePath, content, encoding = "utf8", createDirectories = true, }) {
+    try {
+        // Validate input
+        if (!filePath) {
+            return {
+                success: false,
+                error: "File path is required",
+            };
+        }
+        if (content === undefined || content === null) {
+            return {
+                success: false,
+                error: "Content is required",
+            };
+        }
+        // Resolve to absolute path
+        const absolutePath = path.resolve(filePath);
+        // Track whether the file existed before this write so undo can decide
+        // between restoring content vs deleting a newly created file.
+        let fileExisted = false;
+        // Try to read existing content for diff (may not exist for new files)
+        let oldContent = "";
+        try {
+            fileExisted = true;
+            oldContent = await fs.readFile(absolutePath, encoding);
+        }
+        catch {
+            // File doesn't exist yet - that's fine
+        }
+        // Create parent directories if needed
+        if (createDirectories) {
+            const dir = path.dirname(absolutePath);
+            await fs.mkdir(dir, { recursive: true });
+        }
+        // Write file content
+        await fs.writeFile(absolutePath, content, encoding);
+        // Get file stats
+        const stats = await fs.stat(absolutePath);
+        // Generate diff for UI display (includes accurate line counts)
+        const { diff, linesAdded, linesRemoved } = generateDiff(oldContent, content, absolutePath);
+        return {
+            success: true,
+            filePath: absolutePath,
+            fileExisted,
+            size: stats.size,
+            created: stats.birthtime,
+            modified: stats.mtime,
+            linesAdded,
+            linesRemoved,
+            diff,
+            oldContent,
+            newContent: content,
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            error: err.message,
+        };
+    }
+}
+/**
+ * Tool metadata for agent system
+ */
+export const writeFileTool = {
+    description: "Write content to a file, creating it if it doesn't exist",
+    parameters: z.object({
+        filePath: z
+            .string()
+            .describe("The path to the file to write (can be relative or absolute)"),
+        content: z.string().describe("The content to write to the file"),
+        encoding: z
+            .enum(["utf8", "ascii", "base64", "binary", "hex"])
+            .default("utf8")
+            .describe("The encoding to use when writing the file"),
+        createDirectories: z
+            .boolean()
+            .default(true)
+            .describe("Whether to create parent directories if they don't exist"),
+    }),
+    execute: writeFile,
+};
+export default writeFileTool;

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

@@ -0,0 +1,12 @@
+import { WorkspaceMutationBridge } from "./workspaceMutationBridge.js";
+type CapturedResult = {
+    toolCallId: string;
+    result: Record<string, unknown>;
+};
+export declare class CapturedWorkspaceMutationBridge extends WorkspaceMutationBridge {
+    private readonly processedResults;
+    takeProcessedResults(generationId: string, toolCallIds: string[]): CapturedResult[];
+    clearProcessedResults(generationId: string): void;
+    processToolResult(args: Parameters<WorkspaceMutationBridge["processToolResult"]>[0]): Promise<import("@mastra/core/agent").MessageList>;
+}
+export {};

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

@@ -0,0 +1,67 @@
+import { WorkspaceMutationBridge } from "./workspaceMutationBridge.js";
+import { redactToolResult } from "./toolResultSafetyProcessor.js";
+const getGenerationId = (requestContext) => {
+    if (!requestContext || typeof requestContext !== "object")
+        return undefined;
+    const get = requestContext.get;
+    if (typeof get !== "function")
+        return undefined;
+    const value = get.call(requestContext, "workspaceMutationGenerationId");
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+};
+export class CapturedWorkspaceMutationBridge extends WorkspaceMutationBridge {
+    processedResults = new Map();
+    takeProcessedResults(generationId, toolCallIds) {
+        const results = [];
+        const generationResults = this.processedResults.get(generationId);
+        if (!generationResults)
+            return results;
+        for (const toolCallId of toolCallIds) {
+            const result = generationResults.get(toolCallId);
+            if (!result)
+                continue;
+            generationResults.delete(toolCallId);
+            results.push({ toolCallId, result });
+        }
+        if (generationResults.size === 0) {
+            this.processedResults.delete(generationId);
+        }
+        return results;
+    }
+    clearProcessedResults(generationId) {
+        this.processedResults.delete(generationId);
+    }
+    async processToolResult(args) {
+        const messageList = args.messageList;
+        const generationId = getGenerationId(args.requestContext);
+        const originalUpdateToolInvocation = messageList.updateToolInvocation;
+        messageList.updateToolInvocation = (update) => {
+            const invocation = update.toolInvocation;
+            const sanitizedResult = redactToolResult(invocation?.result).result;
+            if (invocation?.state === "result" &&
+                typeof invocation.toolCallId === "string" &&
+                sanitizedResult &&
+                typeof sanitizedResult === "object" &&
+                generationId) {
+                let generationResults = this.processedResults.get(generationId);
+                if (!generationResults) {
+                    generationResults = new Map();
+                    this.processedResults.set(generationId, generationResults);
+                }
+                generationResults.set(invocation.toolCallId, sanitizedResult);
+            }
+            return originalUpdateToolInvocation.call(messageList, {
+                ...update,
+                toolInvocation: invocation
+                    ? { ...invocation, result: sanitizedResult }
+                    : invocation,
+            });
+        };
+        try {
+            return await super.processToolResult(args);
+        }
+        finally {
+            messageList.updateToolInvocation = originalUpdateToolInvocation;
+        }
+    }
+}

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

@@ -0,0 +1,14 @@
+type DiffResult = {
+    diff: string;
+    linesAdded: number;
+    linesRemoved: number;
+};
+/**
+ * Generate a unified diff string from old and new content
+ * @param {string} oldContent - The original content
+ * @param {string} newContent - The modified content
+ * @param {string} filePath - The file path (used for diff header)
+ * @returns {{diff: string, linesAdded: number, linesRemoved: number}} Diff result with accurate line counts
+ */
+export declare function generateDiff(oldContent: string, newContent: string, filePath: string): DiffResult;
+export {};

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

@@ -0,0 +1,39 @@
+import path from "path";
+import { diffLines } from "diff";
+/**
+ * Generate a unified diff string from old and new content
+ * @param {string} oldContent - The original content
+ * @param {string} newContent - The modified content
+ * @param {string} filePath - The file path (used for diff header)
+ * @returns {{diff: string, linesAdded: number, linesRemoved: number}} Diff result with accurate line counts
+ */
+export function generateDiff(oldContent, newContent, filePath) {
+    const changes = diffLines(oldContent, newContent);
+    let diff = `--- a/${path.basename(filePath)}\n+++ b/${path.basename(filePath)}\n`;
+    let linesAdded = 0;
+    let linesRemoved = 0;
+    changes.forEach((part) => {
+        const lines = part.value
+            .split("\n")
+            .filter((line, idx, arr) => idx < arr.length - 1 || line !== "");
+        if (part.added) {
+            linesAdded += lines.length;
+            lines.forEach((line) => {
+                diff += `+${line}\n`;
+            });
+        }
+        else if (part.removed) {
+            linesRemoved += lines.length;
+            lines.forEach((line) => {
+                diff += `-${line}\n`;
+            });
+        }
+        else {
+            // Context lines (unchanged)
+            lines.forEach((line) => {
+                diff += ` ${line}\n`;
+            });
+        }
+    });
+    return { diff, linesAdded, linesRemoved };
+}