@travisennis/acai 0.0.1

package/source/tools/memory-write.ts

@@ -0,0 +1,105 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, resolve, sep } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { config } from "../config.ts";
+import type { SendData } from "./types.ts";
+
+export const MemoryWriteTool = {
+  name: "memoryWrite" as const,
+};
+
+const MEMORY_DIR = config.app.ensurePathSync("memory");
+
+export const createMemoryWriteTool = (
+  options: { sendData?: SendData | undefined } = {},
+) => {
+  const { sendData } = options;
+
+  const memoryWriteTool = tool({
+    description: "Write content to a memory file.",
+    inputSchema: z.object({
+      filePath: z
+        .string()
+        .describe(
+          'Path to the memory file, relative to the memory directory. Cannot use ".." or absolute paths.',
+        ),
+      content: z.string().describe("Content to write to the file."),
+    }),
+    execute: async (
+      { filePath, content }: { filePath: string; content: string },
+      { toolCallId },
+    ) => {
+      sendData?.({
+        event: "tool-init",
+        id: toolCallId,
+        data: "Initializing memory write...",
+      });
+
+      const resolvedMemoryDir = resolve(MEMORY_DIR);
+      const normalizedRelativePath = normalize(filePath);
+
+      if (
+        normalizedRelativePath.startsWith("..") ||
+        normalizedRelativePath.includes("..") ||
+        isAbsolute(normalizedRelativePath)
+      ) {
+        const errorMsg = `Error: Invalid filePath "${filePath}". Must be a relative path within the memory directory and cannot use '..'.`;
+        sendData?.({
+          event: "tool-error",
+          id: toolCallId,
+          data: errorMsg,
+        });
+        return errorMsg;
+      }
+
+      const fullPath = join(resolvedMemoryDir, normalizedRelativePath);
+
+      if (
+        !fullPath.startsWith(resolvedMemoryDir + sep) &&
+        fullPath !== resolvedMemoryDir
+      ) {
+        const errorMsg = `Error: Path "${filePath}" resolves outside the allowed memory directory.`;
+        sendData?.({
+          event: "tool-error",
+          id: toolCallId,
+          data: errorMsg,
+        });
+        return errorMsg;
+      }
+
+      sendData?.({
+        event: "tool-update",
+        id: toolCallId,
+        data: { primary: "Writing to file:", secondary: [filePath] },
+      });
+
+      try {
+        await mkdir(dirname(fullPath), { recursive: true });
+        await writeFile(fullPath, content, "utf-8");
+        const successMsg = `Memory file '${filePath}' written successfully.`;
+        sendData?.({
+          event: "tool-completion",
+          id: toolCallId,
+          data: successMsg,
+        });
+        return successMsg;
+      } catch (error: unknown) {
+        let errorMsg = `Error writing memory file '${filePath}': An unknown error occurred`;
+        if (error instanceof Error) {
+          errorMsg = `Error writing memory file '${filePath}': ${error.message}`;
+        }
+        sendData?.({
+          event: "tool-error",
+          id: toolCallId,
+          data: errorMsg,
+        });
+        return errorMsg;
+      }
+    },
+  });
+
+  return {
+    [MemoryWriteTool.name]: memoryWriteTool,
+  };
+};

package/source/tools/move-file.ts

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import { tool } from "ai";
+import chalk from "chalk";
+import { z } from "zod";
+import { joinWorkingDir, validatePath } from "./filesystem-utils.ts";
+import type { SendData } from "./types.ts";
+
+export const MoveFileTool = {
+  name: "moveFile" as const,
+};
+
+export const createMoveFileTool = async ({
+  workingDir,
+  sendData,
+}: {
+  workingDir: string;
+  sendData?: SendData;
+}) => {
+  const allowedDirectory = workingDir;
+  return {
+    [MoveFileTool.name]: tool({
+      description:
+        "Move or rename files and directories. Can move files between directories " +
+        "and rename them in a single operation. If the destination exists, the " +
+        "operation will fail. Works across different directories and can be used " +
+        "for simple renaming within the same directory. Both source and destination must be within allowed directories.",
+      inputSchema: z.object({
+        source: z.string(),
+        destination: z.string(),
+      }),
+      execute: async ({ source, destination }, { toolCallId }) => {
+        try {
+          sendData?.({
+            id: toolCallId,
+            event: "tool-init",
+            data: `Moving file from ${chalk.cyan(source)} to ${chalk.cyan(destination)}`,
+          });
+          const validSourcePath = await validatePath(
+            joinWorkingDir(source, workingDir),
+            allowedDirectory,
+          );
+          const validDestPath = await validatePath(
+            joinWorkingDir(destination, workingDir),
+            allowedDirectory,
+          );
+          await fs.rename(validSourcePath, validDestPath);
+          sendData?.({
+            id: toolCallId,
+            event: "tool-completion",
+            data: "Done",
+          });
+          return `Successfully moved ${source} to ${destination}`;
+        } catch (error) {
+          return `Failed to move file: ${(error as Error).message}`;
+        }
+      },
+    }),
+  };
+};

package/source/tools/read-file.ts

@@ -0,0 +1,129 @@
+import fs from "node:fs/promises";
+import { isNumber } from "@travisennis/stdlib/typeguards";
+import { tool } from "ai";
+import chalk from "chalk";
+import { z } from "zod";
+import { config } from "../config.ts";
+import type { TokenCounter } from "../token-utils.ts";
+import { joinWorkingDir, validatePath } from "./filesystem-utils.ts";
+import type { SendData } from "./types.ts";
+import { fileEncodingSchema } from "./types.ts";
+
+export const ReadFileTool = {
+  name: "readFile" as const,
+};
+
+export const createReadFileTool = async ({
+  workingDir,
+  sendData,
+  tokenCounter,
+}: {
+  workingDir: string;
+  sendData?: SendData;
+  tokenCounter: TokenCounter;
+}) => {
+  const allowedDirectory = workingDir;
+  return {
+    [ReadFileTool.name]: tool({
+      description:
+        "Read the complete contents of a file from the file system unless startLine and lineCount are given to read a file selection. " +
+        "Handles various text encodings and provides detailed error messages " +
+        "if the file cannot be read. Use this tool when you need to examine " +
+        "the contents of a single file. Only works within allowed directories.",
+      inputSchema: z.object({
+        path: z.string().describe("Absolute path to file to read"),
+        encoding: fileEncodingSchema.describe(
+          'Encoding format for reading the file. Use "utf-8" as default for text files',
+        ),
+        startLine: z
+          .number()
+          .nullable()
+          .describe(
+            "1-based line number to start reading from. Pass null to start at beginning of file",
+          ),
+        lineCount: z
+          .number()
+          .nullable()
+          .describe(
+            "Maximum number of lines to read. Pass null to get all lines.",
+          ),
+      }),
+      execute: async (
+        {
+          path: providedPath,
+          encoding,
+          startLine,
+          lineCount,
+        }: {
+          path: string;
+          encoding: z.infer<typeof fileEncodingSchema>;
+          startLine: number | null;
+          lineCount: number | null;
+        },
+        { toolCallId },
+      ) => {
+        sendData?.({
+          id: toolCallId,
+          event: "tool-init",
+          data: `Reading file: ${chalk.cyan(providedPath)}${startLine ? chalk.cyan(`:${startLine}`) : ""}${lineCount ? chalk.cyan(`:${lineCount}`) : ""}`,
+        });
+        try {
+          const filePath = await validatePath(
+            joinWorkingDir(providedPath, workingDir),
+            allowedDirectory,
+          );
+
+          let file = await fs.readFile(filePath, { encoding });
+
+          // Apply line-based selection if requested
+          if (isNumber(startLine) || isNumber(lineCount)) {
+            const lines = file.split("\n");
+            const totalLines = lines.length;
+
+            const startIndex = (startLine ?? 1) - 1; // Default to start of file if only lineCount is given
+            const count = lineCount ?? totalLines - startIndex; // Default to read all lines from start if only startLine is given
+
+            if (startIndex < 0 || startIndex >= totalLines) {
+              return `startLine ${startLine} is out of bounds for file with ${totalLines} lines.`;
+            }
+
+            const endIndex = Math.min(startIndex + count, totalLines);
+            file = lines.slice(startIndex, endIndex).join("\n");
+          }
+          let tokenCount = 0;
+          try {
+            // Only calculate tokens for non-image files and if encoding is text-based
+            if (encoding.startsWith("utf")) {
+              tokenCount = tokenCounter.count(file);
+            }
+          } catch (tokenError) {
+            console.error("Error calculating token count:", tokenError);
+            // Log or handle error, but don't block file return
+          }
+
+          const maxTokens = (await config.readProjectConfig()).tools.maxTokens;
+          // Adjust max token check message if line selection was used
+          const maxTokenMessage =
+            isNumber(startLine) || isNumber(lineCount)
+              ? `Selected file content (${tokenCount} tokens) exceeds maximum allowed tokens (${maxTokens}). Consider adjusting startLine/lineCount or using grepFiles.`
+              : `File content (${tokenCount} tokens) exceeds maximum allowed tokens (${maxTokens}). Please use startLine and lineCount parameters to read specific portions of the file, or using grepFiles to search for specific content.`;
+
+          const result = tokenCount <= maxTokens ? file : maxTokenMessage;
+
+          sendData?.({
+            id: toolCallId,
+            event: "tool-completion",
+            // Include token count only if calculated (i.e., for text files)
+            data:
+              tokenCount <= maxTokens
+                ? `File read successfully ${tokenCount > 0 ? ` (${tokenCount} tokens)` : ""}`
+                : result,
+          });
+          return result;
+        } catch (error) {
+          return `Failed to read file: ${(error as Error).message}`;
+        }
+      },
+    }),
+  };
+};

package/source/tools/read-multiple-files.ts

@@ -0,0 +1,80 @@
+import { tool } from "ai";
+import chalk from "chalk";
+import { z } from "zod";
+import { config } from "../config.ts";
+import type { TokenCounter } from "../token-utils.ts";
+import { readFileAndCountTokens } from "./filesystem-utils.ts";
+import type { SendData } from "./types.ts";
+
+export const ReadMultipleFilesTool = {
+  name: "readMultipleFiles" as const,
+};
+
+export const createReadMultipleFilesTool = async ({
+  workingDir,
+  sendData,
+  tokenCounter,
+}: {
+  workingDir: string;
+  sendData?: SendData;
+  tokenCounter: TokenCounter;
+}) => {
+  const allowedDirectory = workingDir;
+  return {
+    [ReadMultipleFilesTool.name]: tool({
+      description:
+        "Read the contents of multiple files simultaneously. This is more " +
+        "efficient than reading files one by one when you need to analyze " +
+        "or compare multiple files. Each file's content is returned with its " +
+        "path as a reference. Failed reads for individual files won't stop " +
+        "the entire operation. Only works within allowed directories.",
+      inputSchema: z.object({
+        paths: z.array(z.string()),
+      }),
+      execute: async ({ paths }, { toolCallId }) => {
+        sendData?.({
+          id: toolCallId,
+          event: "tool-init",
+          data: `Reading files: ${paths.map((p) => chalk.cyan(p)).join(", ")}`,
+        });
+        const maxTokens = (await config.readProjectConfig()).tools.maxTokens;
+        const results = await Promise.all(
+          paths.map((filePath) =>
+            readFileAndCountTokens(
+              filePath,
+              workingDir,
+              allowedDirectory,
+              tokenCounter,
+              maxTokens,
+            ),
+          ),
+        );
+        let totalTokens = 0;
+        let filesReadCount = 0;
+        const formattedResults = results.map((result) => {
+          if (result.error) {
+            return `${result.path}: Error - ${result.error}`;
+          }
+          // Check if tokenCount is > 0, meaning it wasn't skipped
+          if (result.tokenCount > 0) {
+            filesReadCount++;
+          }
+          totalTokens += result.tokenCount; // Add the token count (will be 0 for skipped files)
+          // Return content (or max token message)
+          return `${result.path}:\n${result.content}\n`;
+        });
+        const completionMessage =
+          filesReadCount === paths.length
+            ? `Read ${paths.length} files successfully (${totalTokens} total tokens).`
+            : `Read ${filesReadCount} of ${paths.length} files successfully (${totalTokens} total tokens). Files exceeding token limit were skipped.`;
+
+        sendData?.({
+          id: toolCallId,
+          event: "tool-completion",
+          data: completionMessage,
+        });
+        return formattedResults.join("\n---\n");
+      },
+    }),
+  };
+};

package/source/tools/save-file.ts

@@ -0,0 +1,147 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { input, select } from "@inquirer/prompts";
+import { tool } from "ai";
+import chalk from "chalk";
+import { z } from "zod";
+import type { Terminal } from "../terminal/index.ts";
+import { joinWorkingDir, validatePath } from "./filesystem-utils.ts";
+import { fileEncodingSchema, type SendData } from "./types.ts";
+
+export const SaveFileTool = {
+  name: "saveFile" as const,
+};
+
+export const createSaveFileTool = async ({
+  workingDir,
+  sendData,
+  terminal,
+  autoAcceptAll,
+}: {
+  workingDir: string;
+  sendData?: SendData;
+  terminal?: Terminal;
+  autoAcceptAll?: boolean;
+}) => {
+  const allowedDirectory = workingDir;
+  let autoAcceptSaves = autoAcceptAll ?? false;
+
+  return {
+    [SaveFileTool.name]: tool({
+      description:
+        "Create a new file or completely overwrite an existing file with new content. " +
+        "Use with caution as it will overwrite existing files without warning. " +
+        "Handles text content with proper encoding. Only works within allowed directories.",
+      inputSchema: z.object({
+        path: z.string().describe("Absolute path to file to save to"),
+        content: z.string().describe("Content to save in the file"),
+        encoding: fileEncodingSchema.describe(
+          'Encoding format for saving the file. Use "utf-8" as default for text files',
+        ),
+      }),
+      execute: async (
+        {
+          path: userPath,
+          content,
+          encoding,
+        }: {
+          path: string;
+          content: string;
+          encoding: z.infer<typeof fileEncodingSchema>;
+        },
+        { toolCallId },
+      ) => {
+        sendData?.({
+          id: toolCallId,
+          event: "tool-init",
+          data: `Saving file: ${chalk.cyan(userPath)}`,
+        });
+        try {
+          const filePath = await validatePath(
+            joinWorkingDir(userPath, workingDir),
+            allowedDirectory,
+          );
+
+          if (terminal) {
+            terminal.writeln(
+              `\n${chalk.blue.bold("●")} Proposing file save: ${chalk.cyan(userPath)}`,
+            );
+
+            terminal.lineBreak();
+            terminal.writeln("Proposed file content:");
+            terminal.lineBreak();
+            terminal.display(content);
+            terminal.lineBreak();
+
+            let userChoice: string;
+            if (autoAcceptSaves) {
+              terminal.writeln(
+                chalk.green(
+                  "✓ Auto-accepting saves (all future saves will be accepted)",
+                ),
+              );
+              userChoice = "accept";
+            } else {
+              userChoice = await select({
+                message: "What would you like to do with this file?",
+                choices: [
+                  { name: "Accept and save this file", value: "accept" },
+                  {
+                    name: "Accept all future saves (including this)",
+                    value: "accept-all",
+                  },
+                  { name: "Reject this save", value: "reject" },
+                ],
+                default: "accept",
+              });
+            }
+
+            terminal.lineBreak();
+
+            if (userChoice === "accept-all") {
+              autoAcceptSaves = true;
+              terminal.writeln(
+                chalk.yellow("✓ Auto-accept mode enabled for all future saves"),
+              );
+              terminal.lineBreak();
+            }
+
+            if (userChoice === "reject") {
+              const reason = await input({ message: "Feedback: " });
+
+              terminal.lineBreak();
+
+              sendData?.({
+                id: toolCallId,
+                event: "tool-completion",
+                data: `Save rejected by user. Reason: ${reason}`,
+              });
+
+              return `The user rejected this save. Reason: ${reason}`;
+            }
+
+            // If accepted, proceed to write file
+          }
+
+          // Ensure parent directory exists
+          await fs.mkdir(path.dirname(filePath), { recursive: true });
+          await fs.writeFile(filePath, content, { encoding });
+
+          sendData?.({
+            id: toolCallId,
+            event: "tool-completion",
+            data: `File saved successfully: ${userPath}`,
+          });
+          return `File saved successfully: ${filePath}`;
+        } catch (error) {
+          sendData?.({
+            id: toolCallId,
+            event: "tool-error",
+            data: `Failed to save file: ${(error as Error).message}`,
+          });
+          return `Failed to save file: ${(error as Error).message}`;
+        }
+      },
+    }),
+  };
+};

package/source/tools/think.ts

@@ -0,0 +1,51 @@
+import { tool } from "ai";
+import { z } from "zod";
+import type { SendData } from "./types.ts";
+
+export const ThinkTool = {
+  name: "think" as const,
+};
+
+const toolDescription = `Use the tool to think about something. It will not obtain new information or make any changes to the repository, but just log the thought. Use it when complex reasoning or brainstorming is needed.
+Common use cases:
+1. When exploring a repository and discovering the source of a bug, call this tool to brainstorm several unique ways of fixing the bug, and assess which change(s) are likely to be simplest and most effective
+2. After receiving test results, use this tool to brainstorm ways to fix failing tests
+3. When planning a complex refactoring, use this tool to outline different approaches and their tradeoffs
+4. When designing a new feature, use this tool to think through architecture decisions and implementation details
+5. When debugging a complex issue, use this tool to organize your thoughts and hypotheses
+The tool simply logs your thought process for better transparency and does not execute any code or make changes.`;
+
+// This is a no-op tool that logs a thought. It is inspired by the tau-bench think tool.
+export const createThinkTool = (
+  options: { sendData?: SendData | undefined } = {},
+) => {
+  const { sendData } = options;
+  return {
+    [ThinkTool.name]: tool({
+      description: toolDescription,
+      inputSchema: z.object({
+        thought: z.string().describe("Your thought"),
+      }),
+      execute: ({ thought }, { toolCallId }) => {
+        // Replace literal '\\n' with actual newline characters
+        const formattedThought = thought.replace(/\\n/g, "\n");
+        sendData?.({
+          event: "tool-init",
+          id: toolCallId,
+          data: "Logging Thought",
+        });
+        sendData?.({
+          event: "tool-update",
+          id: toolCallId,
+          data: { primary: "Thought:", secondary: [formattedThought] },
+        });
+        sendData?.({
+          event: "tool-completion",
+          id: toolCallId,
+          data: "Done",
+        });
+        return Promise.resolve("Your thought has been logged.");
+      },
+    }),
+  };
+};

package/source/tools/types.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+export const fileEncodingSchema = z.enum([
+  "ascii",
+  "utf8",
+  "utf-8",
+  "utf16le",
+  "ucs2",
+  "ucs-2",
+  "base64",
+  "base64url",
+  "latin1",
+  "binary",
+  "hex",
+]);
+
+interface MessageData {
+  primary: string;
+  secondary?: string[] | undefined;
+}
+
+interface BaseMessage {
+  id: string;
+  retry?: number;
+}
+
+interface ToolInitMessage extends BaseMessage {
+  event: "tool-init";
+  data: string;
+}
+
+interface ToolErrorMessage extends BaseMessage {
+  event: "tool-error";
+  data: string;
+}
+
+interface ToolCompletionMessage extends BaseMessage {
+  event: "tool-completion";
+  data: string;
+}
+
+interface ToolUpdateMessage extends BaseMessage {
+  event: "tool-update";
+  data: MessageData;
+}
+
+export type Message =
+  | ToolInitMessage
+  | ToolErrorMessage
+  | ToolCompletionMessage
+  | ToolUpdateMessage;
+
+export type SendData = ({
+  data,
+  event,
+  id,
+  retry,
+}: Message) => void | Promise<void>;