@ridit/milo 0.1.0

package/src/tools/FileEditTool/tool.ts

@@ -0,0 +1,39 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { readFile, writeFile } from "fs/promises";
+import { createPatch } from "diff";
+import { DESCRIPTION, PROMPT } from "./prompt.js";
+import { requestPermission } from "../../permissions";
+
+export const FileEditTool = tool({
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  inputSchema: z.object({
+    path: z.string().describe("The absolute file path to edit"),
+    old_string: z.string().describe("The exact string to replace"),
+    new_string: z.string().describe("The string to replace it with"),
+  }),
+  title: "EditFile",
+  execute: async ({ path, old_string, new_string }) => {
+    try {
+      const content = await readFile(path, "utf-8");
+
+      const matches = content.split(old_string).length - 1;
+      if (matches === 0)
+        return { success: false, error: "old_string not found in file" };
+      if (matches > 1)
+        return { success: false, error: `old_string matches ${matches} times` };
+
+      const newContent = content.replace(old_string, new_string);
+      const patch = createPatch(path, content, newContent);
+
+      const decision = await requestPermission("FileEditTool", { path, patch });
+      if (decision === "deny")
+        return { success: false, error: "User denied permission" };
+
+      await writeFile(path, newContent, "utf-8");
+      return { success: true, path, patch };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+});

package/src/tools/FileReadTool/prompt.ts

@@ -0,0 +1,5 @@
+const MAX_LINES_TO_READ = 2000;
+const MAX_LINE_LENGTH = 2000;
+
+export const DESCRIPTION = "Read a file from the local filesystem.";
+export const PROMPT = `Reads a file from the local filesystem. The file_path parameter must be an absolute path, not a relative path. By default, it reads up to ${MAX_LINES_TO_READ} lines starting from the beginning of the file. You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters. Any lines longer than ${MAX_LINE_LENGTH} characters will be truncated. For image files, the tool will display the image for you.`;

package/src/tools/FileReadTool/tool.ts

@@ -0,0 +1,34 @@
+import { readFile } from "fs/promises";
+import { tool } from "ai";
+import { z } from "zod";
+import { resolve } from "path";
+import { PROMPT, DESCRIPTION } from "./prompt.js";
+import { addLineNumbers, findSimilarFile } from "../../utils/file";
+
+export const FileReadTool = tool({
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  title: "ReadFile",
+  inputSchema: z.object({
+    path: z.string().describe("The file path to read"),
+    offset: z.number().optional().describe("Line offset to start reading from"),
+    limit: z.number().optional().describe("Max number of lines to read"),
+  }),
+  execute: async ({ path, offset, limit }) => {
+    try {
+      const absolutePath = resolve(path);
+      let lines = (await readFile(absolutePath, "utf-8")).split("\n");
+      const totalLines = lines.length;
+      if (offset) lines = lines.slice(offset);
+      if (limit) lines = lines.slice(0, limit);
+      const content = addLineNumbers(lines.join("\n"), offset ? offset + 1 : 1);
+      return { success: true, content, totalLines };
+    } catch (err) {
+      const similar = findSimilarFile(path);
+      return {
+        success: false,
+        error: String(err),
+        suggestion: similar ? `Did you mean: ${similar}?` : undefined,
+      };
+    }
+  },
+});

package/src/tools/FileWriteTool/prompt.ts

@@ -0,0 +1,19 @@
+import { cwd } from "process";
+
+export const DESCRIPTION = "Write a file to the local filesystem.";
+
+export const PROMPT = `Write a file to the local filesystem. Overwrites the existing file if there is one.
+
+The current working directory is: ${cwd()}
+
+Path resolution rules:
+- If an absolute path is provided, use it as-is
+- If a relative path is provided, resolve it against the current working directory above
+
+Before using this tool:
+
+1. If overwriting an existing file, use ReadFile first to understand its contents.
+   If creating a new file, skip this step.
+
+2. Directory Verification (only applicable when creating new files):
+   - Use the LS tool to verify the parent directory exists and is the correct location`;

package/src/tools/FileWriteTool/tool.ts

@@ -0,0 +1,34 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { writeFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+import { DESCRIPTION, PROMPT } from "./prompt.js";
+import {
+  requestPermission,
+  TOOLS_REQUIRING_PERMISSION,
+} from "../../permissions";
+
+export const FileWriteTool = tool({
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  inputSchema: z.object({
+    path: z.string().describe("The absolute file path to write to"),
+    content: z.string().describe("The content to write to the file"),
+  }),
+  title: "WriteFile",
+  execute: async ({ path, content }) => {
+    try {
+      const decision = await requestPermission("FileWriteTool", {
+        path,
+        content,
+      });
+      if (decision === "deny")
+        return { success: false, error: "User denied permission" };
+
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, content, "utf-8");
+      return { success: true, path, content };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+});

package/src/tools/GlobTool/prompt.ts

@@ -0,0 +1,11 @@
+export const DESCRIPTION =
+  "Find files by name or path pattern using glob syntax.";
+export const PROMPT = `Use this to find files by their name or path — not their contents.
+
+Examples:
+- "**/*.ts" — all TypeScript files
+- "src/**/tool.ts" — all tool.ts files under src
+- "**/*.test.js" — all test files
+
+Use GrepTool instead if you need to search file contents.
+Automatically excludes: node_modules, .git, dist, build.`;

package/src/tools/GlobTool/tool.ts

@@ -0,0 +1,34 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { glob } from "glob";
+import { DESCRIPTION, PROMPT } from "./prompt";
+import { cwd } from "process";
+
+export const GlobTool = tool({
+  title: "Glob",
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  inputSchema: z.object({
+    pattern: z.string().describe("Glob pattern e.g. **/*.ts or src/**/tool.ts"),
+    path: z
+      .string()
+      .optional()
+      .describe("Directory to search in. Defaults to cwd."),
+  }),
+  execute: async ({ pattern, path }) => {
+    try {
+      const files = await glob(pattern, {
+        cwd: path ?? cwd(),
+        absolute: true,
+        ignore: [
+          "**/node_modules/**",
+          "**/.git/**",
+          "**/dist/**",
+          "**/build/**",
+        ],
+      });
+      return { success: true, files, numFiles: files.length };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+});

package/src/tools/GrepTool/prompt.ts

@@ -0,0 +1,13 @@
+export const DESCRIPTION = "Search for a pattern across files in a directory.";
+
+export const PROMPT = `
+- Fast content search tool that works with any codebase size
+- Searches file contents using regular expressions
+- Supports full regex syntax (e.g. "log.*Error", "function\\s+\\w+", etc.)
+- Filter files by pattern with the include parameter (e.g. "*.js", "*.{ts,tsx}")
+- Returns matching lines with file path and line number
+- Results capped at 500 matches
+- Automatically excludes: node_modules, .git, dist, build, .next, out, coverage
+- Always use this instead of grep, findstr, or any bash search command
+- Use this when you need to find files containing specific patterns or usages
+`.trim();

package/src/tools/GrepTool/tool.ts

@@ -0,0 +1,41 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { grep } from "../../utils/ripgrep";
+import { DESCRIPTION, PROMPT } from "./prompt";
+import { resolve } from "path";
+import { cwd } from "process";
+
+export const GrepTool = tool({
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  title: "Grep",
+  inputSchema: z.object({
+    pattern: z
+      .string()
+      .describe("Regex or string pattern to search for in file contents"),
+    path: z
+      .string()
+      .optional()
+      .describe(
+        "Absolute path to file or directory to search. Defaults to current working directory if omitted.",
+      ),
+    caseInsensitive: z.boolean().default(false).describe("Ignore case"),
+    include: z
+      .string()
+      .optional()
+      .describe("File glob pattern e.g. *.ts or *.{ts,tsx}"),
+  }),
+  execute: async ({ pattern, path, caseInsensitive, include }) => {
+    try {
+      const resolvedPath = path ? resolve(path) : cwd();
+      const matches = await grep(pattern, resolvedPath, {
+        caseInsensitive,
+        include,
+      });
+      if (matches.length === 0)
+        return { success: true, matches: [], message: "No matches found" };
+      return { success: true, matches };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+});

package/src/tools/MemoryEditTool/prompt.ts

@@ -0,0 +1,10 @@
+export const DESCRIPTION =
+  "Edit a specific section of a persistent memory file.";
+export const PROMPT = `Updates a specific part of a memory file without rewriting the whole thing.
+
+Use this to:
+- Update a preference that changed
+- Fix incorrect information
+- Append or modify a specific section
+
+Prefer this over MemoryWriteTool when only a small part needs to change.`;

package/src/tools/MemoryEditTool/tool.ts

@@ -0,0 +1,38 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { MEMORY_DIR } from "../../utils/env";
+import { DESCRIPTION, PROMPT } from "./prompt";
+
+export const MemoryEditTool = tool({
+  title: "MemoryEdit",
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  inputSchema: z.object({
+    file_path: z
+      .string()
+      .describe("Relative path inside memory dir e.g. MEMORY.md"),
+    old_string: z.string().describe("The string to replace"),
+    new_string: z.string().describe("The replacement string"),
+  }),
+  execute: async ({ file_path, old_string, new_string }) => {
+    try {
+      const fullPath = join(MEMORY_DIR, file_path);
+      if (!fullPath.startsWith(MEMORY_DIR)) {
+        return { success: false, error: "Invalid memory file path" };
+      }
+      if (!existsSync(fullPath)) {
+        return { success: false, error: "Memory file does not exist" };
+      }
+      const content = readFileSync(fullPath, "utf-8");
+      if (!content.includes(old_string)) {
+        return { success: false, error: "old_string not found in memory file" };
+      }
+      const updated = content.replace(old_string, new_string);
+      writeFileSync(fullPath, updated, "utf-8");
+      return { success: true, message: "Memory updated" };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+});

package/src/tools/MemoryReadTool/prompt.ts

@@ -0,0 +1,9 @@
+export const DESCRIPTION = "Read a persistent memory file.";
+export const PROMPT = `Reads from ~/.milo/memory/ to recall information from past sessions.
+
+Use this at the start of a session to load context about:
+- User preferences
+- Project conventions
+- Previously stored information
+
+Always read MEMORY.md unless the user specifies otherwise.`;

package/src/tools/MemoryReadTool/tool.ts

@@ -0,0 +1,47 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { MEMORY_DIR } from "../../utils/env";
+import { DESCRIPTION, PROMPT } from "./prompt";
+
+const memoryCache = new Map<string, string>();
+
+export const MemoryReadTool = tool({
+  title: "MemoryRead",
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  inputSchema: z.object({
+    file_path: z
+      .string()
+      .describe("Relative path inside memory dir e.g. MEMORY.md"),
+  }),
+  execute: async ({ file_path }) => {
+    try {
+      if (memoryCache.has(file_path)) {
+        return {
+          success: true,
+          content: memoryCache.get(file_path)!,
+          cached: true,
+        };
+      }
+
+      const fullPath = join(MEMORY_DIR, file_path);
+      if (!fullPath.startsWith(MEMORY_DIR)) {
+        return { success: false, error: "Invalid memory file path" };
+      }
+      if (!existsSync(fullPath)) {
+        return {
+          success: true,
+          content: "",
+          message: "Memory file does not exist yet",
+        };
+      }
+      const content = readFileSync(fullPath, "utf-8");
+
+      memoryCache.set(file_path, content);
+      return { success: true, content };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+});

package/src/tools/MemoryWriteTool/prompt.ts

@@ -0,0 +1,10 @@
+export const DESCRIPTION = "Write content to a persistent memory file.";
+export const PROMPT = `Saves information to ~/.milo/memory/ for use across sessions.
+
+Use this to remember:
+- User preferences and conventions
+- Project-specific context (stack, patterns, rules)
+- Anything the user explicitly asks you to remember
+
+Always write to MEMORY.md unless the user specifies otherwise.
+Content should be concise markdown.`;

package/src/tools/MemoryWriteTool/tool.ts

@@ -0,0 +1,30 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { MEMORY_DIR } from "../../utils/env";
+import { DESCRIPTION, PROMPT } from "./prompt";
+
+export const MemoryWriteTool = tool({
+  title: "MemoryWrite",
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  inputSchema: z.object({
+    file_path: z
+      .string()
+      .describe("Relative path inside memory dir e.g. MEMORY.md"),
+    content: z.string().describe("Full content to write to the memory file"),
+  }),
+  execute: async ({ file_path, content }) => {
+    try {
+      const fullPath = join(MEMORY_DIR, file_path);
+      if (!fullPath.startsWith(MEMORY_DIR)) {
+        return { success: false, error: "Invalid memory file path" };
+      }
+      mkdirSync(dirname(fullPath), { recursive: true });
+      writeFileSync(fullPath, content, "utf-8");
+      return { success: true, message: "Memory saved" };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+});

package/src/tools/OrchestratorTool/prompt.ts

@@ -0,0 +1,26 @@
+import { cwd } from "process";
+
+export const DESCRIPTION =
+  "Orchestrate complex tasks by breaking them into parallel subtasks and delegating to specialized agents.";
+
+export const PROMPT = `Use this tool when a task is too complex for a single agent — i.e. it requires creating multiple files, systems, or components that can be built independently.
+
+Do not use this tool for simple tasks. Use it only when parallel execution provides a clear benefit.
+
+Current working directory: ${cwd()}
+
+How it works:
+1. A planner model breaks the task into subtasks
+2. Subtasks run in parallel where possible, sequentially where there are dependencies
+3. Each subtask returns a manifest of what it created
+4. A connector agent wires everything together
+
+When to use:
+- Building a full feature (API + types + tests)
+- Scaffolding a project with multiple files
+- Any task where subtasks are clearly independent
+
+When NOT to use:
+- Single file changes
+- Questions or explanations
+- Tasks that are inherently sequential`;

package/src/tools/OrchestratorTool/tool.ts

@@ -0,0 +1,20 @@
+// OrchestratorTool.ts
+import { z } from "zod";
+import { DESCRIPTION, PROMPT } from "./prompt";
+import { tool } from "ai";
+import { Orchestrator } from "../../multi-agent/orchestrator/orchestrator";
+import type { OnOrchestratorEvent } from "../../types";
+
+export function createOrchestratorTool(onEvent?: OnOrchestratorEvent) {
+  return tool({
+    description: DESCRIPTION + "\n\n" + PROMPT,
+    inputSchema: z.object({
+      goal: z.string().describe("The complex task to orchestrate"),
+    }),
+    title: "Orchestrator",
+    execute: async ({ goal }) => {
+      const orchestrator = new Orchestrator(onEvent);
+      return await orchestrator.startTask(goal);
+    },
+  });
+}

package/src/tools/RecallTool/prompt.ts

@@ -0,0 +1,13 @@
+export const DESCRIPTION =
+  "Search through past Milo session history to recall previous conversations, code decisions, or context.";
+
+export const PROMPT = `Use this tool when the user references something from a previous session, asks what was discussed before, or needs context from past conversations.
+
+Triggers:
+- "remember when we...", "last time we...", "what did we discuss about..."
+- User references a past decision, file, or feature without current context
+- You need historical context to answer accurately
+
+Returns snippets from past session messages ranked by keyword relevance.
+
+Do NOT use for current session context — that's already in your message history.`;

package/src/tools/RecallTool/tool.ts

@@ -0,0 +1,47 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { DESCRIPTION, PROMPT } from "./prompt";
+import { SESSIONS_DIR } from "../../utils/env";
+import { grep } from "../../utils/ripgrep";
+
+export const RecallTool = tool({
+  title: "Recall",
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  inputSchema: z.object({
+    query: z
+      .string()
+      .describe("Keywords or phrase to search for in past sessions"),
+    max_results: z
+      .number()
+      .optional()
+      .default(5)
+      .describe("Max snippets to return"),
+    caseInsensitive: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("Ignore case when searching"),
+  }),
+  execute: async ({ query, max_results, caseInsensitive }) => {
+    const matches = await grep(query, SESSIONS_DIR, {
+      caseInsensitive,
+      include: "*.json",
+    });
+
+    if (matches.length === 0) {
+      return { results: [], message: `No matches found for "${query}"` };
+    }
+
+    const top = matches.slice(0, max_results);
+
+    return {
+      query,
+      total_matches: matches.length,
+      results: top.map(({ file, line, match }) => ({
+        sessionFile: file.split(/[\\/]/).pop(),
+        line,
+        snippet: match,
+      })),
+    };
+  },
+});

package/src/tools/ThinkTool/tool.ts

@@ -0,0 +1,16 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+export const ThinkTool = tool({
+  title: "Think",
+  description:
+    "Use this tool to think through a problem before acting. No side effects — just a scratchpad for reasoning.",
+  inputSchema: z.object({
+    thought: z
+      .string()
+      .describe("Your reasoning, plan, or analysis before taking action"),
+  }),
+  execute: async ({ thought }) => {
+    return { success: true, message: "Your thought has been logged." };
+  },
+});

package/src/tools/WebFetchTool/prompt.ts

@@ -0,0 +1,7 @@
+export const DESCRIPTION = "Fetch the content of a URL and return its text.";
+export const PROMPT = `Fetches a webpage and returns its text content with HTML stripped.
+
+Guidelines:
+- Use this to read documentation, articles, or any webpage
+- Content is truncated to 8000 characters
+- Always provide a full URL including https://`;

package/src/tools/WebFetchTool/tool.ts

@@ -0,0 +1,33 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { DESCRIPTION, PROMPT } from "./prompt.js";
+
+export const WebFetchTool = tool({
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  inputSchema: z.object({
+    url: z.string().describe("The URL to fetch"),
+  }),
+  title: "WebFetch",
+  execute: async ({ url }) => {
+    try {
+      const res = await fetch(url, {
+        headers: {
+          "User-Agent": "Mozilla/5.0 (compatible; Milo/1.0)",
+        },
+        signal: AbortSignal.timeout(10000),
+      });
+      const html = await res.text();
+      // strip tags, keep text
+      const text = html
+        .replace(/<script[\s\S]*?<\/script>/gi, "")
+        .replace(/<style[\s\S]*?<\/style>/gi, "")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 8000);
+      return { success: true, url, content: text };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+});

package/src/tools/WebSearchTool/prompt.ts

@@ -0,0 +1,8 @@
+export const DESCRIPTION =
+  "Search the web using DuckDuckGo. No API key required.";
+export const PROMPT = `Searches the web and returns titles, URLs, and snippets.
+
+Guidelines:
+- Use this when the user asks about current events, documentation, or anything that needs live web data
+- Use WebFetchTool to read the full content of a result URL
+- Keep queries short and specific for best results`;

package/src/tools/WebSearchTool/tool.ts

@@ -0,0 +1,49 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { DESCRIPTION, PROMPT } from "./prompt.js";
+
+export const WebSearchTool = tool({
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  inputSchema: z.object({
+    query: z.string().describe("The search query"),
+  }),
+  title: "WebSearch",
+  execute: async ({ query }) => {
+    try {
+      const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+      const res = await fetch(url, {
+        headers: {
+          "User-Agent": "Mozilla/5.0 (compatible; Milo/1.0)",
+        },
+        signal: AbortSignal.timeout(10000),
+      });
+      const html = await res.text();
+
+      const results: { title: string; url: string; snippet: string }[] = [];
+      const resultRegex =
+        /<a class="result__a" href="([^"]+)"[^>]*>([^<]+)<\/a>[\s\S]*?<a class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g;
+      let match;
+      while ((match = resultRegex.exec(html)) !== null && results.length < 8) {
+        results.push({
+          url: match[1] ?? "",
+          title: match[2]?.trim() ?? "",
+          snippet: match[3]?.replace(/<[^>]+>/g, "").trim() ?? "",
+        });
+      }
+
+      if (results.length === 0) {
+        // fallback — just strip html
+        const text = html
+          .replace(/<[^>]+>/g, " ")
+          .replace(/\s+/g, " ")
+          .trim()
+          .slice(0, 4000);
+        return { success: true, query, results: [], raw: text };
+      }
+
+      return { success: true, query, results };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+});