@4onstudios/iris-agent 0.1.0

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

@@ -0,0 +1,313 @@
+import { spawn } from "child_process";
+import { z } from "zod";
+const OUTPUT_LIMIT_BYTES = 64 * 1024;
+const TERMINATION_GRACE_MS = 1500;
+const TERMINAL_TASK_TTL_MS = 60 * 60 * 1000;
+const MAX_TERMINAL_TASKS_RETAINED = 200;
+const tasks = new Map();
+let evictedTasksTotal = 0;
+const getRetentionStats = () => ({
+    maxTerminalTasksRetained: MAX_TERMINAL_TASKS_RETAINED,
+    terminalTaskTtlMs: TERMINAL_TASK_TTL_MS,
+    evictedTasksTotal,
+});
+const sweepTerminalTasks = () => {
+    const now = Date.now();
+    const terminalEntries = Array.from(tasks.entries()).filter(([, task]) => ["completed", "failed", "stopped"].includes(task.status));
+    for (const [id, task] of terminalEntries) {
+        const terminalAt = task.endedAt || task.startedAt;
+        if (now - terminalAt > TERMINAL_TASK_TTL_MS) {
+            tasks.delete(id);
+            evictedTasksTotal += 1;
+        }
+    }
+    const remainingTerminal = Array.from(tasks.entries())
+        .filter(([, task]) => ["completed", "failed", "stopped"].includes(task.status))
+        .sort((a, b) => {
+        const aTime = a[1].endedAt || a[1].startedAt;
+        const bTime = b[1].endedAt || b[1].startedAt;
+        return bTime - aTime;
+    });
+    if (remainingTerminal.length > MAX_TERMINAL_TASKS_RETAINED) {
+        const overflow = remainingTerminal.slice(MAX_TERMINAL_TASKS_RETAINED);
+        for (const [id] of overflow) {
+            tasks.delete(id);
+            evictedTasksTotal += 1;
+        }
+    }
+};
+const waitForProcessExit = async (child, timeoutMs) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return true;
+    }
+    return await new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.off("close", finish);
+            child.off("exit", finish);
+            resolve(true);
+        };
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.off("close", finish);
+            child.off("exit", finish);
+            resolve(false);
+        }, timeoutMs);
+        child.once("close", finish);
+        child.once("exit", finish);
+    });
+};
+const taskKillOnWindows = async (pid, force) => {
+    return await new Promise((resolve) => {
+        const args = ["/PID", String(pid), "/T", ...(force ? ["/F"] : [])];
+        const killer = spawn("taskkill", args, {
+            windowsHide: true,
+            stdio: "ignore",
+        });
+        killer.on("error", () => resolve(false));
+        killer.on("close", (code) => resolve(code === 0));
+    });
+};
+const sendTerminationSignal = async (task, force) => {
+    const pid = task.pid;
+    if (!pid)
+        return false;
+    if (process.platform === "win32") {
+        return taskKillOnWindows(pid, force);
+    }
+    try {
+        const signal = force ? "SIGKILL" : "SIGTERM";
+        if (task.usesProcessGroup) {
+            process.kill(-pid, signal);
+            return true;
+        }
+        process.kill(pid, signal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const terminateTaskProcess = async (task) => {
+    const child = task.process;
+    if (!child)
+        return true;
+    await sendTerminationSignal(task, false);
+    let exited = await waitForProcessExit(child, TERMINATION_GRACE_MS);
+    if (exited)
+        return true;
+    await sendTerminationSignal(task, true);
+    exited = await waitForProcessExit(child, TERMINATION_GRACE_MS);
+    return exited;
+};
+export const __resetBackgroundTasksForTests = async () => {
+    const runningTasks = Array.from(tasks.values()).filter((task) => task.status === "running");
+    await Promise.all(runningTasks.map(async (task) => {
+        task.status = "stopped";
+        task.endedAt = Date.now();
+        task.stopReason = "Stopped by test reset";
+        appendTaskOutput(task, "\n[background-task-stop] Stopped by test reset\n");
+        await terminateTaskProcess(task);
+    }));
+    tasks.clear();
+    evictedTasksTotal = 0;
+};
+const trimUtf8TailToByteLimit = (input, maxBytes) => {
+    if (maxBytes <= 0)
+        return "";
+    const buffer = Buffer.from(input, "utf8");
+    if (buffer.length <= maxBytes) {
+        return input;
+    }
+    let start = buffer.length - maxBytes;
+    // Avoid starting in the middle of a UTF-8 continuation sequence.
+    while (start < buffer.length && (buffer[start] & 0b11000000) === 0b10000000) {
+        start += 1;
+    }
+    return buffer.subarray(start).toString("utf8");
+};
+const appendTaskOutput = (task, chunk) => {
+    if (!chunk)
+        return;
+    const nextOutput = task.output + chunk;
+    if (Buffer.byteLength(nextOutput, "utf8") <= OUTPUT_LIMIT_BYTES) {
+        task.output = nextOutput;
+        return;
+    }
+    task.outputTruncated = true;
+    task.output = trimUtf8TailToByteLimit(nextOutput, OUTPUT_LIMIT_BYTES);
+};
+const makeTaskId = () => `task_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+export const startBackgroundTask = ({ command, cwd, env = {}, description, }) => {
+    sweepTerminalTasks();
+    const id = makeTaskId();
+    const usesProcessGroup = process.platform !== "win32";
+    const child = spawn(command, {
+        cwd,
+        env: { ...process.env, ...env },
+        shell: true,
+        detached: usesProcessGroup,
+    });
+    const task = {
+        id,
+        command,
+        cwd,
+        description: description || command,
+        status: "running",
+        startedAt: Date.now(),
+        output: "",
+        outputTruncated: false,
+        pid: child.pid,
+        process: child,
+        usesProcessGroup,
+    };
+    tasks.set(id, task);
+    child.stdout?.on("data", (data) => {
+        appendTaskOutput(task, data.toString());
+    });
+    child.stderr?.on("data", (data) => {
+        appendTaskOutput(task, data.toString());
+    });
+    child.on("error", (error) => {
+        appendTaskOutput(task, `\n[background-task-error] ${error.message}\n`);
+        task.status = "failed";
+        task.endedAt = Date.now();
+        task.exitCode = 1;
+    });
+    child.on("close", (code, signal) => {
+        if (task.status === "stopped") {
+            task.endedAt = task.endedAt || Date.now();
+            task.exitCode = code;
+            task.signal = signal;
+            task.process = undefined;
+            return;
+        }
+        task.status = code === 0 ? "completed" : "failed";
+        task.endedAt = Date.now();
+        task.exitCode = code;
+        task.signal = signal;
+        task.process = undefined;
+    });
+    return {
+        success: true,
+        status: "in_progress",
+        taskId: id,
+        pid: child.pid,
+        command,
+        cwd,
+        description: task.description,
+        startedAt: task.startedAt,
+        message: `Started background task ${id}`,
+    };
+};
+export const listBackgroundTasks = ({ activeOnly = true, limit = 20, }) => {
+    sweepTerminalTasks();
+    const ordered = Array.from(tasks.values())
+        .filter((task) => (activeOnly ? task.status === "running" : true))
+        .sort((a, b) => b.startedAt - a.startedAt)
+        .slice(0, Math.max(1, Math.min(limit, 100)));
+    return ordered.map((task) => ({
+        taskId: task.id,
+        command: task.command,
+        description: task.description,
+        cwd: task.cwd,
+        status: task.status,
+        startedAt: task.startedAt,
+        endedAt: task.endedAt,
+        pid: task.pid,
+        exitCode: task.exitCode,
+        signal: task.signal,
+        retention: getRetentionStats(),
+    }));
+};
+export const getBackgroundTaskOutput = ({ taskId, tailChars = 3000, }) => {
+    sweepTerminalTasks();
+    const task = tasks.get(taskId);
+    if (!task) {
+        return {
+            success: false,
+            error: `Background task '${taskId}' not found`,
+        };
+    }
+    const normalizedTailChars = Math.max(256, Math.min(tailChars, 20000));
+    return {
+        success: true,
+        taskId,
+        status: task.status,
+        command: task.command,
+        description: task.description,
+        startedAt: task.startedAt,
+        endedAt: task.endedAt,
+        exitCode: task.exitCode,
+        signal: task.signal,
+        output: task.output.slice(-normalizedTailChars),
+        outputTruncated: task.outputTruncated || task.output.length > normalizedTailChars,
+        totalOutputChars: task.output.length,
+        retention: getRetentionStats(),
+    };
+};
+export const stopBackgroundTask = ({ taskId, reason = "Stopped by TaskStop", }) => {
+    sweepTerminalTasks();
+    const task = tasks.get(taskId);
+    if (!task) {
+        return {
+            success: false,
+            error: `Background task '${taskId}' not found`,
+        };
+    }
+    if (task.status !== "running") {
+        return {
+            success: true,
+            taskId,
+            status: task.status,
+            message: `Task ${taskId} is already in terminal status '${task.status}'`,
+        };
+    }
+    task.status = "stopped";
+    task.endedAt = Date.now();
+    task.stopReason = reason;
+    appendTaskOutput(task, `\n[background-task-stop] ${reason}\n`);
+    return terminateTaskProcess(task).then((killed) => ({
+        success: true,
+        taskId,
+        status: task.status,
+        killed,
+        reason,
+        retention: getRetentionStats(),
+        message: `Stop signal sent to task ${taskId}`,
+    }));
+};
+export const taskListTool = {
+    description: "List background tasks started with runInBackground. Use activeOnly=true by default.",
+    parameters: z.object({
+        activeOnly: z.boolean().default(true),
+        limit: z.number().min(1).max(100).default(20),
+    }),
+    execute: async ({ activeOnly = true, limit = 20 }) => ({
+        success: true,
+        tasks: listBackgroundTasks({ activeOnly, limit }),
+        retention: getRetentionStats(),
+    }),
+};
+export const taskOutputTool = {
+    description: "Get non-blocking status and output snapshot for a background task.",
+    parameters: z.object({
+        taskId: z.string().describe("Background task ID"),
+        tailChars: z.number().min(256).max(20000).default(3000),
+    }),
+    execute: async ({ taskId, tailChars = 3000 }) => getBackgroundTaskOutput({ taskId, tailChars }),
+};
+export const taskStopTool = {
+    description: "Stop a running background task by task ID.",
+    parameters: z.object({
+        taskId: z.string().describe("Background task ID"),
+        reason: z.string().default("Stopped by TaskStop"),
+    }),
+    execute: async ({ taskId, reason = "Stopped by TaskStop" }) => await stopBackgroundTask({ taskId, reason }),
+};

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

@@ -0,0 +1,43 @@
+import { z } from "zod";
+type CreateDirectoryParams = {
+    dirPath: string;
+    recursive?: boolean;
+};
+type CreateDirectorySuccessResult = {
+    success: true;
+    dirPath: string;
+    created?: Date;
+    alreadyExists: boolean;
+    message: string;
+};
+type CreateDirectoryErrorResult = {
+    success: false;
+    error: string;
+};
+type CreateDirectoryResult = CreateDirectorySuccessResult | CreateDirectoryErrorResult;
+/**
+ * Tool for creating directories
+ * @param {Object} params - The parameters for creating a directory
+ * @param {string} params.dirPath - The path to the directory to create
+ * @param {boolean} [params.recursive=true] - Whether to create parent directories
+ * @returns {Promise<Object>} Object containing success status and directory info or error
+ */
+export declare function createDirectory({ dirPath, recursive, }: CreateDirectoryParams): Promise<CreateDirectoryResult>;
+/**
+ * Tool metadata for agent system
+ */
+export declare const createDirectoryTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        dirPath: z.ZodString;
+        recursive: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        recursive?: boolean;
+        dirPath?: string;
+    }, {
+        recursive?: boolean;
+        dirPath?: string;
+    }>;
+    execute: typeof createDirectory;
+};
+export default createDirectoryTool;

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

@@ -0,0 +1,77 @@
+import fs from "fs/promises";
+import path from "path";
+import { z } from "zod";
+/**
+ * Tool for creating directories
+ * @param {Object} params - The parameters for creating a directory
+ * @param {string} params.dirPath - The path to the directory to create
+ * @param {boolean} [params.recursive=true] - Whether to create parent directories
+ * @returns {Promise<Object>} Object containing success status and directory info or error
+ */
+export async function createDirectory({ dirPath, recursive = true, }) {
+    try {
+        // Validate input
+        if (!dirPath) {
+            return {
+                success: false,
+                error: "Directory path is required",
+            };
+        }
+        // Resolve to absolute path
+        const absolutePath = path.resolve(dirPath);
+        // Check if directory already exists
+        try {
+            const stats = await fs.stat(absolutePath);
+            if (stats.isDirectory()) {
+                return {
+                    success: true,
+                    dirPath: absolutePath,
+                    alreadyExists: true,
+                    message: "Directory already exists",
+                };
+            }
+            else {
+                return {
+                    success: false,
+                    error: "Path exists but is not a directory",
+                };
+            }
+        }
+        catch (err) {
+            // Directory doesn't exist, continue with creation
+        }
+        // Create the directory
+        await fs.mkdir(absolutePath, { recursive });
+        // Get directory stats
+        const stats = await fs.stat(absolutePath);
+        return {
+            success: true,
+            dirPath: absolutePath,
+            created: stats.birthtime,
+            alreadyExists: false,
+            message: "Directory created successfully",
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            error: err.message,
+        };
+    }
+}
+/**
+ * Tool metadata for agent system
+ */
+export const createDirectoryTool = {
+    description: "Create a new directory, optionally creating parent directories",
+    parameters: z.object({
+        dirPath: z.string().describe("The path to the directory to create"),
+        recursive: z
+            .boolean()
+            .default(true)
+            .describe("Whether to create parent directories if they don't exist"),
+    }),
+    execute: createDirectory,
+};
+export default createDirectoryTool;

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

@@ -0,0 +1,37 @@
+import { z } from "zod";
+type DeleteFileParams = {
+    filePath: string;
+};
+type DeleteFileSuccessResult = {
+    success: true;
+    filePath: string;
+    deletedSize: number;
+    message: string;
+};
+type DeleteFileErrorResult = {
+    success: false;
+    error: string;
+};
+type DeleteFileResult = DeleteFileSuccessResult | DeleteFileErrorResult;
+/**
+ * Tool for deleting files
+ * @param {Object} params - The parameters for deleting a file
+ * @param {string} params.filePath - The path to the file to delete
+ * @returns {Promise<Object>} Object containing success status and deletion info or error
+ */
+export declare function deleteFile({ filePath, }: DeleteFileParams): Promise<DeleteFileResult>;
+/**
+ * Tool metadata for agent system
+ */
+export declare const deleteFileTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        filePath: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        filePath?: string;
+    }, {
+        filePath?: string;
+    }>;
+    execute: typeof deleteFile;
+};
+export default deleteFileTool;

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

@@ -0,0 +1,66 @@
+import fs from "fs/promises";
+import path from "path";
+import { z } from "zod";
+/**
+ * Tool for deleting files
+ * @param {Object} params - The parameters for deleting a file
+ * @param {string} params.filePath - The path to the file to delete
+ * @returns {Promise<Object>} Object containing success status and deletion info or error
+ */
+export async function deleteFile({ filePath, }) {
+    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.F_OK);
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `File not found: ${filePath}`,
+            };
+        }
+        // Get file stats before deletion
+        const stats = await fs.stat(absolutePath);
+        if (!stats.isFile()) {
+            return {
+                success: false,
+                error: `Path is not a file: ${filePath}`,
+            };
+        }
+        // Delete the file
+        await fs.unlink(absolutePath);
+        return {
+            success: true,
+            filePath: absolutePath,
+            deletedSize: stats.size,
+            message: "File deleted successfully",
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            error: err.message,
+        };
+    }
+}
+/**
+ * Tool metadata for agent system
+ */
+export const deleteFileTool = {
+    description: "Delete a file from the file system",
+    parameters: z.object({
+        filePath: z.string().describe("The path to the file to delete"),
+    }),
+    execute: deleteFile,
+};
+export default deleteFileTool;

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

@@ -0,0 +1,73 @@
+import { z } from "zod";
+type EditFileParams = {
+    filePath: string;
+    oldContent?: string;
+    newContent?: string;
+    startLine?: number;
+    endLine?: number;
+    lineContent?: string;
+    encoding?: BufferEncoding;
+};
+type EditFileSuccessResult = {
+    success: true;
+    filePath: string;
+    fileExisted: true;
+    size: number;
+    modified: Date;
+    linesAdded: number;
+    linesRemoved: number;
+    diff: string;
+    oldContent: string;
+    newContent: string;
+};
+type EditFileErrorResult = {
+    success: false;
+    error: string;
+};
+type EditFileResult = EditFileSuccessResult | EditFileErrorResult;
+/**
+ * Tool for editing files by replacing content or specific lines
+ * @param {Object} params - The parameters for editing a file
+ * @param {string} params.filePath - The path to the file to edit
+ * @param {string} [params.oldContent] - The old content to replace (must match exactly)
+ * @param {string} [params.newContent] - The new content to replace with
+ * @param {number} [params.startLine] - Starting line number to replace (1-indexed)
+ * @param {number} [params.endLine] - Ending line number to replace (1-indexed)
+ * @param {string} [params.lineContent] - New content for the line range
+ * @param {string} [params.encoding='utf8'] - The encoding to use
+ * @returns {Promise<Object>} Object containing success status and edit info or error
+ */
+export declare function editFile({ filePath, oldContent, newContent, startLine, endLine, lineContent, encoding, }: EditFileParams): Promise<EditFileResult>;
+/**
+ * Tool metadata for agent system
+ */
+export declare const editFileTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        filePath: z.ZodString;
+        oldContent: z.ZodOptional<z.ZodString>;
+        newContent: z.ZodOptional<z.ZodString>;
+        startLine: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+        lineContent: z.ZodOptional<z.ZodString>;
+        encoding: z.ZodDefault<z.ZodEnum<["utf8", "ascii", "base64", "binary", "hex"]>>;
+    }, "strip", z.ZodTypeAny, {
+        encoding?: "ascii" | "utf8" | "base64" | "binary" | "hex";
+        filePath?: string;
+        startLine?: number;
+        endLine?: number;
+        oldContent?: string;
+        newContent?: string;
+        lineContent?: string;
+    }, {
+        encoding?: "ascii" | "utf8" | "base64" | "binary" | "hex";
+        filePath?: string;
+        startLine?: number;
+        endLine?: number;
+        oldContent?: string;
+        newContent?: string;
+        lineContent?: string;
+    }>;
+    execute: typeof editFile;
+};
+export default editFileTool;