@4onstudios/iris-agent 0.1.0

package/dist/api/core/agent/publicContracts.d.ts

@@ -0,0 +1,35 @@
+import { type WorkspaceToolHooks } from "@mastra/core/workspace";
+export declare const createIrisWorkspaceToolsConfig: (hooks?: WorkspaceToolHooks) => {
+    mastra_workspace_read_file: {
+        name: string;
+    };
+    mastra_workspace_list_files: {
+        name: string;
+    };
+    mastra_workspace_file_stat: {
+        name: string;
+    };
+    mastra_workspace_grep: {
+        name: string;
+    };
+    mastra_workspace_write_file: {
+        enabled: boolean;
+    };
+    mastra_workspace_edit_file: {
+        enabled: boolean;
+    };
+    mastra_workspace_delete: {
+        name: string;
+    };
+    mastra_workspace_mkdir: {
+        name: string;
+    };
+    mastra_workspace_ast_edit: {
+        enabled: boolean;
+    };
+    mastra_workspace_search: {
+        name: string;
+    };
+    hooks?: WorkspaceToolHooks;
+};
+export declare const CODING_AGENT_INSTRUCTIONS: string;

package/dist/api/core/agent/publicContracts.js

@@ -0,0 +1,103 @@
+import { WORKSPACE_TOOLS, } from "@mastra/core/workspace";
+export const createIrisWorkspaceToolsConfig = (hooks) => ({
+    ...(hooks ? { hooks } : {}),
+    [WORKSPACE_TOOLS.FILESYSTEM.READ_FILE]: { name: "readFile" },
+    [WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES]: { name: "listDirectory" },
+    [WORKSPACE_TOOLS.FILESYSTEM.FILE_STAT]: { name: "fileStat" },
+    [WORKSPACE_TOOLS.FILESYSTEM.GREP]: { name: "grepSearch" },
+    // Keep native mutations disabled: their string results omit the rich diff
+    // contract. AIRIS writeFile/editFile are registered on the agent below.
+    [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: { enabled: false },
+    [WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE]: {
+        enabled: false,
+    },
+    [WORKSPACE_TOOLS.FILESYSTEM.DELETE]: { name: "deleteFile" },
+    [WORKSPACE_TOOLS.FILESYSTEM.MKDIR]: { name: "createDirectory" },
+    [WORKSPACE_TOOLS.FILESYSTEM.AST_EDIT]: { enabled: false },
+    [WORKSPACE_TOOLS.SEARCH.SEARCH]: { name: "workspaceSearch" },
+});
+export const CODING_AGENT_INSTRUCTIONS = `
+You are AIRIS, a senior coding agent working in the user's current workspace.
+Follow these rules in order; when rules conflict, the earlier rule wins.
+
+## Priorities
+
+1. Fulfill the user's actual request and preserve explicitly stated constraints.
+2. Protect user data, existing work, credentials, and external systems.
+3. Ground workspace-specific claims in current tool results.
+4. Make the smallest complete change that solves the root problem.
+5. Use the fewest tool calls that still provide enough evidence and validation.
+
+## Decide Whether To Act
+
+- Use tools when the request depends on workspace contents, runtime state, command output,
+  current web information, or an external system. Do not force a tool call for a purely
+  conceptual or conversational answer.
+- When the user clearly requests a change or command, perform it instead of only proposing it.
+- Ask one concise clarification only when missing information materially changes the result,
+  no safe default exists, or an irreversible/external action needs confirmation. Otherwise,
+  infer the most conservative reasonable intent and proceed.
+- Respect tool approval and suspension flows. Waiting for required user input is a valid stop.
+- Never invent paths, file contents, command output, tool capabilities, or successful completion.
+
+## Working Method
+
+1. Start from the most concrete available anchor: an exact file, symbol, error, command, test,
+   or nearby implementation.
+2. Gather only enough current evidence to identify the controlling code path and a check that
+   can disprove the intended fix. Avoid broad project surveys when a local read or search is enough.
+3. Make a focused change using the repository's existing patterns and public contracts.
+4. After an edit, run the narrowest available validation that exercises the changed behavior.
+5. If validation exposes a local defect, fix that same slice and rerun the same check. Do not
+   expand into unrelated cleanup.
+6. Finish with a concise factual response once the request is complete, blocked, awaiting input,
+   or the action budget is exhausted.
+
+## Tool Selection
+
+- Treat the tools and their current schemas as authoritative. Never call aliases that are not
+  exposed in the current run.
+- Known exact path: use readFile directly. Unknown filename: use searchFiles. Known text or code
+  pattern: use grepSearch. Use workspaceSearch, when exposed, for conceptual discovery. Use
+  getWorkspaceInfo only when a broad project overview is genuinely needed.
+- Use getCodeContext or LSP tools when semantic precision matters. Use findReferences before
+  changing a shared symbol or contract, and prefer renameSymbol for semantic renames.
+- Use editFile for exact, localized replacements, writeFile for new files or deliberate full
+  rewrites, and applyDiff for coordinated multi-hunk changes. These AIRIS mutation tools return
+  rich diff metadata for review.
+- Prefer file tools over shell-based file mutation. Use runTerminalCommand for builds, tests,
+  package operations, git inspection, and commands whose behavior belongs in a shell.
+- taskList, taskOutput, and taskStop manage background terminal tasks; they are not planning or
+  todo-list tools.
+- Use MCP and web tools only when the request requires their external capability. Follow each
+  exposed schema exactly and avoid irreversible external actions without clear authorization.
+- Issue independent reads or searches together when supported. Batch dependent shell commands
+  with && only when later commands should run solely after earlier ones succeed.
+
+## Editing And Validation
+
+- Read the relevant current region before modifying an existing file unless its current content
+  is already present in the conversation or a fresh tool result.
+- Preserve repository style, public APIs, and user-authored changes. Do not reformat, revert,
+  delete, or refactor unrelated code.
+- Do not perform destructive git operations, commit, push, deploy, publish, or install global
+  software unless the user explicitly requests or clearly authorizes it.
+- Inspect the mutation result rather than rereading a file solely to confirm that the tool wrote it.
+- Prefer a behavior-scoped test, then a targeted test, typecheck, lint, or build. Broaden validation
+  only when the change's risk or shared surface justifies it.
+- Report pre-existing or unrelated failures without trying to repair them unless they block the task.
+
+## Failure And Completion
+
+- Read the exact error, correct the likely cause, and retry with a bounded alternative. Do not repeat
+  the same failing call or continue investigating after the answer is known.
+- Continue autonomously until the requested outcome is complete. Stop only when complete, genuinely
+  blocked, waiting for required input/approval, or out of the runtime's action budget.
+- The configured Mastra maxSteps value is the sole action budget. When it is nearly exhausted,
+  prioritize the essential implementation and validation. If exhausted, provide a final synthesis
+  of what completed, what remains, and the concrete blocker; do not claim success for partial work.
+- After tools, always provide meaningful final text. State the result first, name changed files or
+  important findings, and include validation status. Keep details proportional to the request.
+- Do not end with a generic offer, ask what to do next, narrate tool mechanics, or continue calling
+  tools after the task is resolved.
+`.trim();

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

@@ -0,0 +1,51 @@
+import { z } from "zod";
+type ApplyDiffParams = {
+    filePath: string;
+    patch: string;
+};
+type ApplyDiffSuccessResult = {
+    success: true;
+    filePath: string;
+    fileExisted: boolean;
+    size: number;
+    modified: Date;
+    linesAdded: number;
+    linesRemoved: number;
+    diff: string;
+    oldContent: string;
+    newContent: string;
+};
+type ApplyDiffErrorResult = {
+    success: false;
+    error: string;
+    patch?: string;
+    filePath?: string;
+    parsedChanges?: number;
+};
+type ApplyDiffResult = ApplyDiffSuccessResult | ApplyDiffErrorResult;
+/**
+ * Tool for applying unified diff patches to files
+ * @param {Object} params - The parameters for applying a diff
+ * @param {string} params.filePath - The path to the file to patch
+ * @param {string} params.patch - The unified diff patch to apply
+ * @returns {Promise<Object>} Object containing success status and patch info or error
+ */
+export declare function applyDiff({ filePath, patch, }: ApplyDiffParams): Promise<ApplyDiffResult>;
+/**
+ * Tool metadata for agent system
+ */
+export declare const applyDiffTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        filePath: z.ZodString;
+        patch: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        filePath?: string;
+        patch?: string;
+    }, {
+        filePath?: string;
+        patch?: string;
+    }>;
+    execute: typeof applyDiff;
+};
+export default applyDiffTool;

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

@@ -0,0 +1,131 @@
+import fs from "fs/promises";
+import path from "path";
+import { applyPatch, parsePatch } from "diff";
+import { z } from "zod";
+import { generateDiff } from "../utils/diffUtils.js";
+const normalizeDiffPath = (input) => {
+    if (!input)
+        return "";
+    const normalized = input.trim().replace(/\\/g, "/");
+    if (normalized.startsWith("a/") || normalized.startsWith("b/")) {
+        return normalized.slice(2);
+    }
+    return normalized;
+};
+const matchesTargetPath = (parsedPath, targetAbsolutePath) => {
+    if (!parsedPath || parsedPath === "/dev/null")
+        return false;
+    const normalizedParsed = parsedPath.replace(/\\/g, "/");
+    const normalizedTarget = targetAbsolutePath.replace(/\\/g, "/");
+    return (normalizedTarget.endsWith(`/${normalizedParsed}`) ||
+        normalizedTarget === normalizedParsed);
+};
+/**
+ * Tool for applying unified diff patches to files
+ * @param {Object} params - The parameters for applying a diff
+ * @param {string} params.filePath - The path to the file to patch
+ * @param {string} params.patch - The unified diff patch to apply
+ * @returns {Promise<Object>} Object containing success status and patch info or error
+ */
+export async function applyDiff({ filePath, patch, }) {
+    try {
+        if (!filePath || !patch) {
+            return {
+                success: false,
+                error: "Both filePath and patch are required",
+            };
+        }
+        const absolutePath = path.resolve(filePath);
+        const parsedPatches = parsePatch(patch);
+        if (parsedPatches.length === 0) {
+            return {
+                success: false,
+                error: "Invalid unified diff: no patch sections found",
+                patch,
+                filePath: absolutePath,
+            };
+        }
+        const targetPatch = parsedPatches.find((candidate) => {
+            const oldName = normalizeDiffPath(candidate.oldFileName);
+            const newName = normalizeDiffPath(candidate.newFileName);
+            return (matchesTargetPath(oldName, absolutePath) ||
+                matchesTargetPath(newName, absolutePath));
+        }) || parsedPatches[0];
+        let oldContent = "";
+        let existedBefore = false;
+        try {
+            oldContent = await fs.readFile(absolutePath, "utf8");
+            existedBefore = true;
+        }
+        catch {
+            oldContent = "";
+            existedBefore = false;
+        }
+        const oldName = normalizeDiffPath(targetPatch.oldFileName);
+        const newName = normalizeDiffPath(targetPatch.newFileName);
+        const isDelete = oldName !== "/dev/null" && newName === "/dev/null";
+        if (isDelete) {
+            if (existedBefore) {
+                await fs.unlink(absolutePath);
+            }
+            const { diff, linesAdded, linesRemoved } = generateDiff(oldContent, "", absolutePath);
+            return {
+                success: true,
+                filePath: absolutePath,
+                fileExisted: existedBefore,
+                size: 0,
+                modified: new Date(),
+                linesAdded,
+                linesRemoved,
+                diff,
+                oldContent,
+                newContent: "",
+            };
+        }
+        const newContent = applyPatch(oldContent, patch);
+        if (newContent === false) {
+            return {
+                success: false,
+                error: "Failed to apply patch because file content no longer matches patch context",
+                patch,
+                filePath: absolutePath,
+                parsedChanges: targetPatch.hunks?.length || 0,
+            };
+        }
+        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+        await fs.writeFile(absolutePath, newContent, "utf8");
+        const stats = await fs.stat(absolutePath);
+        const { diff, linesAdded, linesRemoved } = generateDiff(oldContent, newContent, absolutePath);
+        return {
+            success: true,
+            filePath: absolutePath,
+            fileExisted: existedBefore,
+            size: stats.size,
+            modified: stats.mtime,
+            linesAdded,
+            linesRemoved,
+            diff,
+            oldContent,
+            newContent,
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            error: err.message,
+        };
+    }
+}
+/**
+ * Tool metadata for agent system
+ */
+export const applyDiffTool = {
+    description: "Apply a unified diff patch to a file",
+    parameters: z.object({
+        filePath: z.string().describe("The path to the file to patch"),
+        patch: z.string().describe("The unified diff patch to apply"),
+    }),
+    execute: applyDiff,
+};
+export default applyDiffTool;

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

@@ -0,0 +1,240 @@
+import { z } from "zod";
+export type BackgroundTaskStatus = "running" | "completed" | "failed" | "stopped";
+type StartBackgroundTaskParams = {
+    command: string;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    description?: string;
+};
+export declare const __resetBackgroundTasksForTests: () => Promise<void>;
+export declare const startBackgroundTask: ({ command, cwd, env, description, }: StartBackgroundTaskParams) => {
+    success: boolean;
+    status: string;
+    taskId: string;
+    pid: number;
+    command: string;
+    cwd: string;
+    description: string;
+    startedAt: number;
+    message: string;
+};
+export declare const listBackgroundTasks: ({ activeOnly, limit, }: {
+    activeOnly?: boolean;
+    limit?: number;
+}) => {
+    taskId: string;
+    command: string;
+    description: string;
+    cwd: string;
+    status: BackgroundTaskStatus;
+    startedAt: number;
+    endedAt: number;
+    pid: number;
+    exitCode: number;
+    signal: NodeJS.Signals;
+    retention: {
+        maxTerminalTasksRetained: number;
+        terminalTaskTtlMs: number;
+        evictedTasksTotal: number;
+    };
+}[];
+export declare const getBackgroundTaskOutput: ({ taskId, tailChars, }: {
+    taskId: string;
+    tailChars?: number;
+}) => {
+    success: boolean;
+    error: string;
+    taskId?: undefined;
+    status?: undefined;
+    command?: undefined;
+    description?: undefined;
+    startedAt?: undefined;
+    endedAt?: undefined;
+    exitCode?: undefined;
+    signal?: undefined;
+    output?: undefined;
+    outputTruncated?: undefined;
+    totalOutputChars?: undefined;
+    retention?: undefined;
+} | {
+    success: boolean;
+    taskId: string;
+    status: BackgroundTaskStatus;
+    command: string;
+    description: string;
+    startedAt: number;
+    endedAt: number;
+    exitCode: number;
+    signal: NodeJS.Signals;
+    output: string;
+    outputTruncated: boolean;
+    totalOutputChars: number;
+    retention: {
+        maxTerminalTasksRetained: number;
+        terminalTaskTtlMs: number;
+        evictedTasksTotal: number;
+    };
+    error?: undefined;
+};
+export declare const stopBackgroundTask: ({ taskId, reason, }: {
+    taskId: string;
+    reason?: string;
+}) => Promise<{
+    success: boolean;
+    taskId: string;
+    status: BackgroundTaskStatus;
+    killed: boolean;
+    reason: string;
+    retention: {
+        maxTerminalTasksRetained: number;
+        terminalTaskTtlMs: number;
+        evictedTasksTotal: number;
+    };
+    message: string;
+}> | {
+    success: boolean;
+    error: string;
+    taskId?: undefined;
+    status?: undefined;
+    message?: undefined;
+} | {
+    success: boolean;
+    taskId: string;
+    status: "completed" | "failed" | "stopped";
+    message: string;
+    error?: undefined;
+};
+export declare const taskListTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        activeOnly: z.ZodDefault<z.ZodBoolean>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        activeOnly?: boolean;
+        limit?: number;
+    }, {
+        activeOnly?: boolean;
+        limit?: number;
+    }>;
+    execute: ({ activeOnly, limit }: {
+        activeOnly?: boolean;
+        limit?: number;
+    }) => Promise<{
+        success: boolean;
+        tasks: {
+            taskId: string;
+            command: string;
+            description: string;
+            cwd: string;
+            status: BackgroundTaskStatus;
+            startedAt: number;
+            endedAt: number;
+            pid: number;
+            exitCode: number;
+            signal: NodeJS.Signals;
+            retention: {
+                maxTerminalTasksRetained: number;
+                terminalTaskTtlMs: number;
+                evictedTasksTotal: number;
+            };
+        }[];
+        retention: {
+            maxTerminalTasksRetained: number;
+            terminalTaskTtlMs: number;
+            evictedTasksTotal: number;
+        };
+    }>;
+};
+export declare const taskOutputTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        taskId: z.ZodString;
+        tailChars: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        taskId?: string;
+        tailChars?: number;
+    }, {
+        taskId?: string;
+        tailChars?: number;
+    }>;
+    execute: ({ taskId, tailChars }: {
+        taskId: string;
+        tailChars?: number;
+    }) => Promise<{
+        success: boolean;
+        error: string;
+        taskId?: undefined;
+        status?: undefined;
+        command?: undefined;
+        description?: undefined;
+        startedAt?: undefined;
+        endedAt?: undefined;
+        exitCode?: undefined;
+        signal?: undefined;
+        output?: undefined;
+        outputTruncated?: undefined;
+        totalOutputChars?: undefined;
+        retention?: undefined;
+    } | {
+        success: boolean;
+        taskId: string;
+        status: BackgroundTaskStatus;
+        command: string;
+        description: string;
+        startedAt: number;
+        endedAt: number;
+        exitCode: number;
+        signal: NodeJS.Signals;
+        output: string;
+        outputTruncated: boolean;
+        totalOutputChars: number;
+        retention: {
+            maxTerminalTasksRetained: number;
+            terminalTaskTtlMs: number;
+            evictedTasksTotal: number;
+        };
+        error?: undefined;
+    }>;
+};
+export declare const taskStopTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        taskId: z.ZodString;
+        reason: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        taskId?: string;
+        reason?: string;
+    }, {
+        taskId?: string;
+        reason?: string;
+    }>;
+    execute: ({ taskId, reason }: {
+        taskId: string;
+        reason?: string;
+    }) => Promise<{
+        success: boolean;
+        taskId: string;
+        status: BackgroundTaskStatus;
+        killed: boolean;
+        reason: string;
+        retention: {
+            maxTerminalTasksRetained: number;
+            terminalTaskTtlMs: number;
+            evictedTasksTotal: number;
+        };
+        message: string;
+    } | {
+        success: boolean;
+        error: string;
+        taskId?: undefined;
+        status?: undefined;
+        message?: undefined;
+    } | {
+        success: boolean;
+        taskId: string;
+        status: "completed" | "failed" | "stopped";
+        message: string;
+        error?: undefined;
+    }>;
+};
+export {};