min-agent 0.1.0

package/src/tool-output.ts

@@ -0,0 +1,146 @@
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from "fs"
+import path from "path"
+import { randomBytes } from "crypto"
+import { getConfigDir } from "./config.js"
+
+/** Default limits (aligned with common agent tooling practice). */
+export const TOOL_OUTPUT_MAX_LINES = 2000
+export const TOOL_OUTPUT_MAX_BYTES = 50 * 1024
+
+export type TruncateDirection = "head" | "tail"
+
+export interface TruncateToolOutputOptions {
+  maxLines?: number
+  maxBytes?: number
+  direction?: TruncateDirection
+}
+
+export interface TruncateToolOutputResult {
+  content: string
+  truncated: boolean
+  outputPath?: string
+}
+
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000
+
+function toolOutputDir(): string {
+  return path.join(getConfigDir(), "tool-output")
+}
+
+function cleanupOldToolOutputs(dir: string): void {
+  if (!existsSync(dir)) return
+  const now = Date.now()
+  try {
+    for (const f of readdirSync(dir)) {
+      if (!f.startsWith("tool-") || !f.endsWith(".txt")) continue
+      const p = path.join(dir, f)
+      try {
+        if (now - statSync(p).mtimeMs > RETENTION_MS) unlinkSync(p)
+      } catch {
+        /* ignore */
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Write full text to ~/.min-agent/tool-output/ and return absolute path. */
+export function writeFullToolOutput(fullText: string): string {
+  const dir = toolOutputDir()
+  mkdirSync(dir, { recursive: true })
+  cleanupOldToolOutputs(dir)
+  const name = `tool-${Date.now()}-${randomBytes(4).toString("hex")}.txt`
+  const filePath = path.join(dir, name)
+  writeFileSync(filePath, fullText, "utf-8")
+  return filePath
+}
+
+const hint = (filePath: string) =>
+  `The tool output was truncated. Full output saved to: ${filePath}\nUse the read tool with startLine/endLine, or grep, to inspect further.`
+
+/** Keep end of text within line/byte limits (good for shell logs). */
+export function tailPreview(text: string, maxLines: number, maxBytes: number): { text: string; cut: boolean } {
+  const lines = text.split("\n")
+  const totalBytes = Buffer.byteLength(text, "utf-8")
+  if (lines.length <= maxLines && totalBytes <= maxBytes) {
+    return { text, cut: false }
+  }
+
+  const out: string[] = []
+  let bytes = 0
+  for (let i = lines.length - 1; i >= 0 && out.length < maxLines; i--) {
+    const size = Buffer.byteLength(lines[i], "utf-8") + (out.length > 0 ? 1 : 0)
+    if (bytes + size > maxBytes) {
+      if (out.length === 0) {
+        const buf = Buffer.from(lines[i], "utf-8")
+        let start = buf.length - maxBytes
+        if (start < 0) start = 0
+        while (start < buf.length && (buf[start] & 0xc0) === 0x80) start++
+        out.unshift(buf.subarray(start).toString("utf-8"))
+      }
+      break
+    }
+    out.unshift(lines[i])
+    bytes += size
+  }
+  return { text: out.join("\n"), cut: true }
+}
+
+/** Keep start of text within line/byte limits (good for files / HTTP bodies). */
+export function headPreview(text: string, maxLines: number, maxBytes: number): { text: string; cut: boolean } {
+  const lines = text.split("\n")
+  const totalBytes = Buffer.byteLength(text, "utf-8")
+  if (lines.length <= maxLines && totalBytes <= maxBytes) {
+    return { text, cut: false }
+  }
+
+  const out: string[] = []
+  let bytes = 0
+  for (let i = 0; i < lines.length && out.length < maxLines; i++) {
+    const size = Buffer.byteLength(lines[i], "utf-8") + (i > 0 ? 1 : 0)
+    if (bytes + size > maxBytes) {
+      if (out.length === 0) {
+        const buf = Buffer.from(lines[i], "utf-8")
+        let end = Math.min(maxBytes, buf.length)
+        while (end > 0 && (buf[end - 1] & 0xc0) === 0x80) end--
+        out.push(buf.subarray(0, end).toString("utf-8"))
+      }
+      break
+    }
+    out.push(lines[i])
+    bytes += size
+  }
+  return { text: out.join("\n"), cut: true }
+}
+
+/**
+ * If text exceeds limits, write full text to disk and return a preview + path hint.
+ * Otherwise returns the original string.
+ */
+export function truncateToolOutput(
+  text: string,
+  options: TruncateToolOutputOptions = {},
+): TruncateToolOutputResult {
+  const maxLines = options.maxLines ?? TOOL_OUTPUT_MAX_LINES
+  const maxBytes = options.maxBytes ?? TOOL_OUTPUT_MAX_BYTES
+  const direction = options.direction ?? "head"
+
+  const lines = text.split("\n")
+  const totalBytes = Buffer.byteLength(text, "utf-8")
+  if (lines.length <= maxLines && totalBytes <= maxBytes) {
+    return { content: text, truncated: false }
+  }
+
+  const filePath = writeFullToolOutput(text)
+  const preview =
+    direction === "tail" ? tailPreview(text, maxLines, maxBytes).text : headPreview(text, maxLines, maxBytes).text
+
+  const header = "...output truncated...\n\n"
+  const content =
+    direction === "tail"
+      ? `${header}${hint(filePath)}\n\n${preview}`
+      : `${preview}\n\n${header}${hint(filePath)}`
+
+  return { content, truncated: true, outputPath: filePath }
+}

package/src/tools/bash.ts

@@ -0,0 +1,108 @@
+import { spawn } from "child_process"
+import { tool, jsonSchema } from "ai"
+import { confirm, isDangerousCommand, isAutoApprove } from "../confirm.js"
+import { truncateToolOutput } from "../tool-output.js"
+
+type BashInput = { command: string; timeout?: number }
+
+/** Hard cap for in-memory collection before killing the process (avoid OOM on huge stdout). */
+const COLLECT_HARD_CAP_BYTES = 16 * 1024 * 1024
+
+function runCommand(command: string, cwd: string, timeoutMs: number): Promise<{
+  code: number | null
+  output: string
+  killedByTimeout: boolean
+  killedByCap: boolean
+}> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      shell: true,
+      cwd,
+      env: process.env as NodeJS.ProcessEnv,
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+    const outChunks: Buffer[] = []
+    const errChunks: Buffer[] = []
+    let total = 0
+    let killedCap = false
+    let killedTimeout = false
+
+    const timer = setTimeout(() => {
+      killedTimeout = true
+      child.kill("SIGTERM")
+      setTimeout(() => child.kill("SIGKILL"), 2000).unref()
+    }, timeoutMs)
+
+    const push = (buf: Buffer, arr: Buffer[]) => {
+      total += buf.length
+      if (total > COLLECT_HARD_CAP_BYTES && !killedCap) {
+        killedCap = true
+        child.kill("SIGKILL")
+        return
+      }
+      arr.push(buf)
+    }
+
+    child.stdout?.on("data", (b: Buffer) => push(b, outChunks))
+    child.stderr?.on("data", (b: Buffer) => push(b, errChunks))
+
+    child.on("error", (err) => {
+      clearTimeout(timer)
+      reject(err)
+    })
+
+    child.on("close", (code) => {
+      clearTimeout(timer)
+      const stdout = Buffer.concat(outChunks).toString("utf-8")
+      const stderr = Buffer.concat(errChunks).toString("utf-8")
+      let combined = stdout.replace(/\s+$/, "")
+      if (stderr) combined += (combined ? "\n" : "") + stderr.replace(/\s+$/, "")
+
+      if (killedCap) {
+        combined +=
+          `\n\n[bash] Output collection stopped: exceeded ${COLLECT_HARD_CAP_BYTES} bytes in-memory cap (process was killed). Prefer redirecting to a file (e.g. > out.txt) then read with startLine/endLine.`
+      } else if (killedTimeout) {
+        combined += `\n\n[bash] Command exceeded timeout ${timeoutMs} ms (process terminated).`
+      }
+
+      resolve({
+        code,
+        output: combined || "(no output)",
+        killedByTimeout: killedTimeout,
+        killedByCap: killedCap,
+      })
+    })
+  })
+}
+
+export const bashTool = tool<BashInput, string>({
+  description:
+    "Run a shell command. Use this for system operations, running builds, tests, git commands, etc. The command runs in the current working directory. Very long stdout/stderr is truncated: full output may be saved under ~/.min-agent/tool-output/ with a preview returned.",
+  inputSchema: jsonSchema<BashInput>({
+    type: "object",
+    properties: {
+      command: { type: "string", description: "The shell command to execute" },
+      timeout: { type: "number", description: "Timeout in milliseconds (default: 30000)" },
+    },
+    required: ["command"],
+  }),
+  execute: async ({ command, timeout }) => {
+    if (!isAutoApprove() && isDangerousCommand(command)) {
+      const approved = await confirm(`Execute dangerous command: ${command}`)
+      if (!approved) return "Command rejected by user."
+    }
+
+    const timeoutMs = timeout ?? 30000
+    try {
+      const { code, output, killedByTimeout, killedByCap } = await runCommand(command, process.cwd(), timeoutMs)
+      let body = output
+      if (code !== 0 && code !== null && !killedByTimeout && !killedByCap) {
+        body = `Exit code ${code}\n${body}`
+      }
+      const { content } = truncateToolOutput(body, { direction: "tail" })
+      return content.trim() || "(no output)"
+    } catch (err: any) {
+      return `Error: ${err.message ?? String(err)}`
+    }
+  },
+})

package/src/tools/edit.ts

@@ -0,0 +1,65 @@
+import { tool, jsonSchema } from "ai"
+import { readFileSync, writeFileSync, existsSync } from "fs"
+import path from "path"
+import { confirm, isAutoApprove } from "../confirm.js"
+
+type EditInput = {
+  filePath: string
+  oldText: string
+  newText: string
+}
+
+export const editTool = tool<EditInput, string>({
+  description:
+    "Edit a file by replacing a specific text block with new content. The oldText must match exactly (including whitespace and indentation). Use this for precise edits instead of rewriting entire files.",
+  inputSchema: jsonSchema<EditInput>({
+    type: "object",
+    properties: {
+      filePath: { type: "string", description: "Path to the file to edit (relative to cwd or absolute)" },
+      oldText: { type: "string", description: "The exact text to find and replace (must match exactly)" },
+      newText: { type: "string", description: "The new text to replace it with" },
+    },
+    required: ["filePath", "oldText", "newText"],
+  }),
+  execute: async ({ filePath, oldText, newText }) => {
+    const resolved = path.resolve(process.cwd(), filePath)
+
+    if (!existsSync(resolved)) {
+      return `Error: File not found: ${filePath}`
+    }
+
+    const content = readFileSync(resolved, "utf-8")
+    const occurrences = content.split(oldText).length - 1
+
+    if (occurrences === 0) {
+      // Try to help: show nearby content
+      const lines = content.split("\n")
+      const searchLines = oldText.split("\n")
+      const firstLine = searchLines[0].trim()
+      const nearbyIdx = lines.findIndex((l) => l.includes(firstLine))
+      if (nearbyIdx >= 0) {
+        const context = lines.slice(Math.max(0, nearbyIdx - 1), nearbyIdx + 3).join("\n")
+        return `Error: oldText not found exactly. Found similar content near line ${nearbyIdx + 1}:\n${context}\n\nMake sure whitespace and indentation match exactly.`
+      }
+      return `Error: oldText not found in ${filePath}. Make sure the text matches exactly including whitespace.`
+    }
+
+    if (occurrences > 1) {
+      return `Error: oldText found ${occurrences} times in ${filePath}. Please provide more context to make the match unique.`
+    }
+
+    // Confirm edit
+    if (!isAutoApprove()) {
+      const preview = oldText.length > 80 ? oldText.slice(0, 80) + "..." : oldText
+      const approved = await confirm(`Edit ${filePath}: replace "${preview}"`)
+      if (!approved) return "Edit rejected by user."
+    }
+
+    const updated = content.replace(oldText, newText)
+    writeFileSync(resolved, updated, "utf-8")
+
+    const oldLines = oldText.split("\n").length
+    const newLines = newText.split("\n").length
+    return `Edited ${filePath}: replaced ${oldLines} line(s) with ${newLines} line(s)`
+  },
+})

package/src/tools/glob.ts

@@ -0,0 +1,37 @@
+import { tool, jsonSchema } from "ai"
+import { globSync } from "glob"
+import { truncateToolOutput } from "../tool-output.js"
+
+type GlobInput = { pattern: string; cwd?: string }
+
+export const globTool = tool<GlobInput, string>({
+  description:
+    "Find files matching a glob pattern. Returns a list of file paths. Use this to discover project structure and find files.",
+  inputSchema: jsonSchema<GlobInput>({
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "Glob pattern to match (e.g. 'src/**/*.ts', '*.json')" },
+      cwd: { type: "string", description: "Directory to search in (defaults to working directory)" },
+    },
+    required: ["pattern"],
+  }),
+  execute: async ({ pattern, cwd }) => {
+    try {
+      const matches = globSync(pattern, {
+        cwd: cwd ?? process.cwd(),
+        ignore: ["**/node_modules/**", "**/.git/**"],
+        nodir: true,
+      })
+      if (matches.length === 0) return "No files found matching pattern"
+      let text: string
+      if (matches.length > 100) {
+        text = matches.slice(0, 100).join("\n") + `\n\n... (${matches.length - 100} more files)`
+      } else {
+        text = matches.join("\n")
+      }
+      return truncateToolOutput(text, { direction: "head" }).content
+    } catch (err: any) {
+      return `Error: ${err.message}`
+    }
+  },
+})

package/src/tools/grep.ts

@@ -0,0 +1,37 @@
+import { tool, jsonSchema } from "ai"
+import { execSync } from "child_process"
+import { truncateToolOutput } from "../tool-output.js"
+
+type GrepInput = { pattern: string; path?: string; include?: string }
+
+export const grepTool = tool<GrepInput, string>({
+  description:
+    "Search for a pattern in files using grep. Returns matching lines with file paths and line numbers. Use this to find code references, usages, and definitions.",
+  inputSchema: jsonSchema<GrepInput>({
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "The regex pattern to search for" },
+      path: { type: "string", description: "File or directory path to search in (defaults to current directory)" },
+      include: { type: "string", description: "File pattern to include (e.g. '*.ts')" },
+    },
+    required: ["pattern"],
+  }),
+  execute: async ({ pattern, path: searchPath, include }) => {
+    const target = searchPath ?? "."
+    const includeFlag = include ? `--include='${include}'` : ""
+    const cmd = `grep -rn ${includeFlag} --color=never -E '${pattern.replace(/'/g, "'\\''")}' '${target}' 2>/dev/null | head -50`
+    try {
+      const output = execSync(cmd, {
+        encoding: "utf-8",
+        cwd: process.cwd(),
+        timeout: 10000,
+        maxBuffer: 512 * 1024,
+      })
+      const text = output.trim() || "No matches found"
+      return truncateToolOutput(text, { direction: "head" }).content
+    } catch (err: any) {
+      if (err.status === 1) return "No matches found"
+      return `Error: ${err.message}`
+    }
+  },
+})

package/src/tools/index.ts

@@ -0,0 +1,21 @@
+import { bashTool } from "./bash.js"
+import { readTool } from "./read.js"
+import { writeTool } from "./write.js"
+import { editTool } from "./edit.js"
+import { globTool } from "./glob.js"
+import { grepTool } from "./grep.js"
+import { webSearchTool } from "./web_search.js"
+import { webFetchTool } from "./web_fetch.js"
+
+export function createTools() {
+  return {
+    bash: bashTool,
+    read: readTool,
+    write: writeTool,
+    edit: editTool,
+    glob: globTool,
+    grep: grepTool,
+    web_search: webSearchTool,
+    web_fetch: webFetchTool,
+  }
+}

package/src/tools/read.ts

@@ -0,0 +1,38 @@
+import { tool, jsonSchema } from "ai"
+import { readFileSync, statSync } from "fs"
+import path from "path"
+import { truncateToolOutput } from "../tool-output.js"
+
+type ReadInput = { filePath: string; startLine?: number; endLine?: number }
+
+export const readTool = tool<ReadInput, string>({
+  description:
+    "Read the contents of a file. Returns the file content as text. Use this to understand code, check configurations, etc.",
+  inputSchema: jsonSchema<ReadInput>({
+    type: "object",
+    properties: {
+      filePath: { type: "string", description: "Path to the file to read (relative to cwd or absolute)" },
+      startLine: { type: "number", description: "Start line number (1-indexed)" },
+      endLine: { type: "number", description: "End line number (1-indexed, inclusive)" },
+    },
+    required: ["filePath"],
+  }),
+  execute: async ({ filePath, startLine, endLine }) => {
+    const resolved = path.resolve(process.cwd(), filePath)
+    try {
+      const stat = statSync(resolved)
+      if (stat.isDirectory()) return `Error: ${filePath} is a directory, not a file`
+      const content = readFileSync(resolved, "utf-8")
+      if (startLine || endLine) {
+        const lines = content.split("\n")
+        const start = (startLine ?? 1) - 1
+        const end = endLine ?? lines.length
+        const slice = lines.slice(start, end).join("\n")
+        return truncateToolOutput(slice, { direction: "head" }).content
+      }
+      return truncateToolOutput(content, { direction: "head" }).content
+    } catch (err: any) {
+      return `Error reading file: ${err.message}`
+    }
+  },
+})

package/src/tools/web_fetch.ts

@@ -0,0 +1,87 @@
+import { tool, jsonSchema } from "ai"
+import { truncateToolOutput } from "../tool-output.js"
+
+type WebFetchInput = { url: string; method?: string }
+
+const FIRECRAWL_BASE = "https://fireclawl.xc.lonae.com"
+
+export const webFetchTool = tool<WebFetchInput, string>({
+  description:
+    "Fetch content from a URL. Use this to access web pages, APIs, or any HTTP resource. Returns the response body as text (or markdown for HTML pages). Supports JavaScript-rendered SPA pages via fallback.",
+  inputSchema: jsonSchema<WebFetchInput>({
+    type: "object",
+    properties: {
+      url: { type: "string", description: "The URL to fetch" },
+      method: { type: "string", description: "HTTP method (default: GET)" },
+    },
+    required: ["url"],
+  }),
+  execute: async ({ url, method }) => {
+    // First try: direct fetch
+    const directResult = await directFetch(url, method)
+
+    // If we got meaningful content, return it
+    if (directResult && hasContent(directResult)) {
+      return directResult
+    }
+
+    // Fallback: use Firecrawl for SPA/dynamic pages
+    const firecrawlResult = await firecrawlFetch(url)
+    if (firecrawlResult) return firecrawlResult
+
+    // Return whatever we got from direct fetch
+    return directResult || "Failed to fetch content from URL"
+  },
+})
+
+async function directFetch(url: string, method?: string): Promise<string | null> {
+  try {
+    const response = await fetch(url, {
+      method: method ?? "GET",
+      headers: {
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+      },
+      signal: AbortSignal.timeout(15000),
+    })
+    if (!response.ok) return `HTTP ${response.status}`
+    const text = await response.text()
+    return truncateToolOutput(text, { direction: "head" }).content
+  } catch (err: any) {
+    return null
+  }
+}
+
+async function firecrawlFetch(url: string): Promise<string | null> {
+  try {
+    const response = await fetch(`${FIRECRAWL_BASE}/v1/scrape`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        url,
+        formats: ["markdown"],
+        onlyMainContent: true,
+        waitFor: 3000,
+        timeout: 30000,
+      }),
+      signal: AbortSignal.timeout(35000),
+    })
+    if (!response.ok) return null
+    const data = await response.json() as any
+    const markdown = data?.data?.markdown || data?.data?.content
+    if (!markdown) return null
+    return truncateToolOutput(markdown, { direction: "head" }).content
+  } catch {
+    return null
+  }
+}
+
+function hasContent(html: string): boolean {
+  // Check if the response has meaningful content (not just an empty SPA shell)
+  if (html.length < 200) return false
+  // SPA shells typically have very little text content outside of script tags
+  const withoutScripts = html.replace(/<script[\s\S]*?<\/script>/gi, "")
+  const textContent = withoutScripts.replace(/<[^>]*>/g, "").trim()
+  // If after removing scripts and tags there's less than 100 chars, it's likely an empty shell
+  return textContent.length > 100
+}

package/src/tools/web_search.ts

@@ -0,0 +1,42 @@
+import { tool, jsonSchema } from "ai"
+import { truncateToolOutput } from "../tool-output.js"
+
+type WebSearchInput = { query: string; categories?: string }
+
+const SEARXNG_BASE = "https://searxng.xc.lonae.com"
+
+export const webSearchTool = tool<WebSearchInput, string>({
+  description:
+    "Search the web for information. Returns search results with titles, URLs, and snippets. Use this when you need current information, news, documentation, or answers that require up-to-date knowledge.",
+  inputSchema: jsonSchema<WebSearchInput>({
+    type: "object",
+    properties: {
+      query: { type: "string", description: "The search query" },
+      categories: { type: "string", description: "Search categories: general, news, images, science, it (default: general)" },
+    },
+    required: ["query"],
+  }),
+  execute: async ({ query, categories }) => {
+    try {
+      const params = new URLSearchParams({
+        q: query,
+        format: "json",
+        categories: categories ?? "general",
+      })
+      const response = await fetch(`${SEARXNG_BASE}/search?${params}`, {
+        headers: { "Accept": "application/json" },
+        signal: AbortSignal.timeout(15000),
+      })
+      if (!response.ok) return `Search error: HTTP ${response.status}`
+      const data = await response.json() as any
+      const results = (data.results ?? []).slice(0, 10)
+      if (results.length === 0) return "No search results found. Try a different query."
+      const text = results
+        .map((r: any, i: number) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.content ?? ""}`)
+        .join("\n\n")
+      return truncateToolOutput(text, { direction: "head" }).content
+    } catch (err: any) {
+      return `Search error: ${err.message}`
+    }
+  },
+})

package/src/tools/write.ts

@@ -0,0 +1,36 @@
+import { tool, jsonSchema } from "ai"
+import { writeFileSync, mkdirSync, existsSync } from "fs"
+import path from "path"
+import { confirm, isAutoApprove } from "../confirm.js"
+
+type WriteInput = { filePath: string; content: string }
+
+export const writeTool = tool<WriteInput, string>({
+  description:
+    "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Creates parent directories as needed.",
+  inputSchema: jsonSchema<WriteInput>({
+    type: "object",
+    properties: {
+      filePath: { type: "string", description: "Path to the file to write (relative to cwd or absolute)" },
+      content: { type: "string", description: "The content to write to the file" },
+    },
+    required: ["filePath", "content"],
+  }),
+  execute: async ({ filePath, content }) => {
+    const resolved = path.resolve(process.cwd(), filePath)
+
+    // Confirm overwriting existing files
+    if (!isAutoApprove() && existsSync(resolved)) {
+      const approved = await confirm(`Overwrite existing file: ${filePath}`)
+      if (!approved) return "Write rejected by user."
+    }
+
+    try {
+      mkdirSync(path.dirname(resolved), { recursive: true })
+      writeFileSync(resolved, content, "utf-8")
+      return `Written ${content.length} bytes to ${filePath}`
+    } catch (err: any) {
+      return `Error writing file: ${err.message}`
+    }
+  },
+})

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"]
+}