@jackchen_me/open-multi-agent 0.1.0

package/src/tool/built-in/grep.ts

@@ -0,0 +1,362 @@
+/**
+ * Built-in grep tool.
+ *
+ * Searches for a regex pattern in files.  Prefers the `rg` (ripgrep) binary
+ * when available for performance; falls back to a pure Node.js recursive
+ * implementation using the standard `fs` module so the tool works in
+ * environments without ripgrep installed.
+ */
+
+import { spawn } from 'child_process'
+import { readdir, readFile, stat } from 'fs/promises'
+// Note: readdir is used with { encoding: 'utf8' } to return string[] directly.
+import { join, relative } from 'path'
+import { z } from 'zod'
+import type { ToolResult } from '../../types.js'
+import { defineTool } from '../framework.js'
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_RESULTS = 100
+// Directories that are almost never useful to search inside
+const SKIP_DIRS = new Set([
+  '.git',
+  '.svn',
+  '.hg',
+  'node_modules',
+  '.next',
+  'dist',
+  'build',
+])
+
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+
+export const grepTool = defineTool({
+  name: 'grep',
+  description:
+    'Search for a regular-expression pattern in one or more files. ' +
+    'Returns matching lines with their file paths and 1-based line numbers. ' +
+    'Use the `glob` parameter to restrict the search to specific file types ' +
+    '(e.g. "*.ts"). ' +
+    'Results are capped by `maxResults` to keep the response manageable.',
+
+  inputSchema: z.object({
+    pattern: z
+      .string()
+      .describe('Regular expression pattern to search for in file contents.'),
+    path: z
+      .string()
+      .optional()
+      .describe(
+        'Directory or file path to search in. ' +
+          'Defaults to the current working directory.',
+      ),
+    glob: z
+      .string()
+      .optional()
+      .describe(
+        'Glob pattern to filter which files are searched ' +
+          '(e.g. "*.ts", "**/*.json"). ' +
+          'Only used when `path` is a directory.',
+      ),
+    maxResults: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        `Maximum number of matching lines to return. ` +
+          `Defaults to ${DEFAULT_MAX_RESULTS}.`,
+      ),
+  }),
+
+  execute: async (input, context) => {
+    const searchPath = input.path ?? process.cwd()
+    const maxResults = input.maxResults ?? DEFAULT_MAX_RESULTS
+
+    // Compile the regex once and surface bad patterns immediately.
+    let regex: RegExp
+    try {
+      regex = new RegExp(input.pattern)
+    } catch {
+      return {
+        data: `Invalid regular expression: "${input.pattern}"`,
+        isError: true,
+      }
+    }
+
+    // Attempt ripgrep first.
+    const rgAvailable = await isRipgrepAvailable()
+    if (rgAvailable) {
+      return runRipgrep(input.pattern, searchPath, {
+        glob: input.glob,
+        maxResults,
+        signal: context.abortSignal,
+      })
+    }
+
+    // Fallback: pure Node.js recursive search.
+    return runNodeSearch(regex, searchPath, {
+      glob: input.glob,
+      maxResults,
+      signal: context.abortSignal,
+    })
+  },
+})
+
+// ---------------------------------------------------------------------------
+// ripgrep path
+// ---------------------------------------------------------------------------
+
+interface SearchOptions {
+  glob?: string
+  maxResults: number
+  signal: AbortSignal | undefined
+}
+
+async function runRipgrep(
+  pattern: string,
+  searchPath: string,
+  options: SearchOptions,
+): Promise<ToolResult> {
+  const args = [
+    '--line-number',
+    '--no-heading',
+    '--color=never',
+    `--max-count=${options.maxResults}`,
+  ]
+  if (options.glob !== undefined) {
+    args.push('--glob', options.glob)
+  }
+  args.push('--', pattern, searchPath)
+
+  return new Promise<ToolResult>((resolve) => {
+    const chunks: Buffer[] = []
+    const errChunks: Buffer[] = []
+
+    const child = spawn('rg', args, { stdio: ['ignore', 'pipe', 'pipe'] })
+
+    child.stdout.on('data', (d: Buffer) => chunks.push(d))
+    child.stderr.on('data', (d: Buffer) => errChunks.push(d))
+
+    const onAbort = (): void => { child.kill('SIGKILL') }
+    if (options.signal !== undefined) {
+      options.signal.addEventListener('abort', onAbort, { once: true })
+    }
+
+    child.on('close', (code: number | null) => {
+      if (options.signal !== undefined) {
+        options.signal.removeEventListener('abort', onAbort)
+      }
+      const output = Buffer.concat(chunks).toString('utf8').trimEnd()
+
+      // rg exit code 1 = no matches (not an error)
+      if (code !== 0 && code !== 1) {
+        const errMsg = Buffer.concat(errChunks).toString('utf8').trim()
+        resolve({
+          data: `ripgrep failed (exit ${code}): ${errMsg}`,
+          isError: true,
+        })
+        return
+      }
+
+      if (output.length === 0) {
+        resolve({ data: 'No matches found.', isError: false })
+        return
+      }
+
+      const lines = output.split('\n')
+      resolve({
+        data: lines.join('\n'),
+        isError: false,
+      })
+    })
+
+    child.on('error', () => {
+      if (options.signal !== undefined) {
+        options.signal.removeEventListener('abort', onAbort)
+      }
+      // Caller will see an error result — the tool won't retry with Node search
+      // since this branch is only reachable after we confirmed rg is available.
+      resolve({
+        data: 'ripgrep process error — run may be retried with the Node.js fallback.',
+        isError: true,
+      })
+    })
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Node.js fallback search
+// ---------------------------------------------------------------------------
+
+interface MatchLine {
+  file: string
+  lineNumber: number
+  text: string
+}
+
+async function runNodeSearch(
+  regex: RegExp,
+  searchPath: string,
+  options: SearchOptions,
+): Promise<ToolResult> {
+  // Collect files
+  let files: string[]
+  try {
+    const info = await stat(searchPath)
+    if (info.isFile()) {
+      files = [searchPath]
+    } else {
+      files = await collectFiles(searchPath, options.glob, options.signal)
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error'
+    return {
+      data: `Cannot access path "${searchPath}": ${message}`,
+      isError: true,
+    }
+  }
+
+  const matches: MatchLine[] = []
+
+  for (const file of files) {
+    if (options.signal?.aborted === true) break
+    if (matches.length >= options.maxResults) break
+
+    let fileContent: string
+    try {
+      fileContent = (await readFile(file)).toString('utf8')
+    } catch {
+      // Skip unreadable files (binary, permission denied, etc.)
+      continue
+    }
+
+    const lines = fileContent.split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      if (matches.length >= options.maxResults) break
+      // Reset lastIndex for global regexes
+      regex.lastIndex = 0
+      if (regex.test(lines[i])) {
+        matches.push({
+          file: relative(process.cwd(), file) || file,
+          lineNumber: i + 1,
+          text: lines[i],
+        })
+      }
+    }
+  }
+
+  if (matches.length === 0) {
+    return { data: 'No matches found.', isError: false }
+  }
+
+  const formatted = matches
+    .map((m) => `${m.file}:${m.lineNumber}:${m.text}`)
+    .join('\n')
+
+  const truncationNote =
+    matches.length >= options.maxResults
+      ? `\n\n(results capped at ${options.maxResults}; use maxResults to raise the limit)`
+      : ''
+
+  return {
+    data: formatted + truncationNote,
+    isError: false,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// File collection with glob filtering
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively walk `dir` and return file paths, honouring `SKIP_DIRS` and an
+ * optional glob pattern.
+ */
+async function collectFiles(
+  dir: string,
+  glob: string | undefined,
+  signal: AbortSignal | undefined,
+): Promise<string[]> {
+  const results: string[] = []
+  await walk(dir, glob, results, signal)
+  return results
+}
+
+async function walk(
+  dir: string,
+  glob: string | undefined,
+  results: string[],
+  signal: AbortSignal | undefined,
+): Promise<void> {
+  if (signal?.aborted === true) return
+
+  let entryNames: string[]
+  try {
+    // Read as plain strings so we don't have to deal with Buffer Dirent variants.
+    entryNames = await readdir(dir, { encoding: 'utf8' })
+  } catch {
+    return
+  }
+
+  for (const entryName of entryNames) {
+    if (signal !== undefined && signal.aborted) return
+
+    const fullPath = join(dir, entryName)
+
+    let entryInfo: Awaited<ReturnType<typeof stat>>
+    try {
+      entryInfo = await stat(fullPath)
+    } catch {
+      continue
+    }
+
+    if (entryInfo.isDirectory()) {
+      if (!SKIP_DIRS.has(entryName)) {
+        await walk(fullPath, glob, results, signal)
+      }
+    } else if (entryInfo.isFile()) {
+      if (glob === undefined || matchesGlob(entryName, glob)) {
+        results.push(fullPath)
+      }
+    }
+  }
+}
+
+/**
+ * Minimal glob match supporting `*.ext` and `**\/<pattern>` forms.
+ */
+function matchesGlob(filename: string, glob: string): boolean {
+  // Strip leading **/ prefix — we already recurse into all directories
+  const pattern = glob.startsWith('**/') ? glob.slice(3) : glob
+  // Convert shell glob characters to regex equivalents
+  const regexSource = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape special regex chars first
+    .replace(/\*/g, '.*')                  // * -> .*
+    .replace(/\?/g, '.')                   // ? -> .
+  const re = new RegExp(`^${regexSource}$`, 'i')
+  return re.test(filename)
+}
+
+// ---------------------------------------------------------------------------
+// ripgrep availability check (cached per process)
+// ---------------------------------------------------------------------------
+
+let rgAvailableCache: boolean | undefined
+
+async function isRipgrepAvailable(): Promise<boolean> {
+  if (rgAvailableCache !== undefined) return rgAvailableCache
+
+  rgAvailableCache = await new Promise<boolean>((resolve) => {
+    const child = spawn('rg', ['--version'], { stdio: 'ignore' })
+    child.on('close', (code) => resolve(code === 0))
+    child.on('error', () => resolve(false))
+  })
+
+  return rgAvailableCache
+}

package/src/tool/built-in/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Built-in tool collection.
+ *
+ * Re-exports every built-in tool and provides a convenience function to
+ * register them all with a {@link ToolRegistry} in one call.
+ */
+
+import type { ToolDefinition } from '../../types.js'
+import { ToolRegistry } from '../framework.js'
+import { bashTool } from './bash.js'
+import { fileEditTool } from './file-edit.js'
+import { fileReadTool } from './file-read.js'
+import { fileWriteTool } from './file-write.js'
+import { grepTool } from './grep.js'
+
+export { bashTool, fileEditTool, fileReadTool, fileWriteTool, grepTool }
+
+/**
+ * The ordered list of all built-in tools.  Import this when you need to
+ * iterate over them without calling `registerBuiltInTools`.
+ *
+ * The array is typed as `ToolDefinition<unknown>[]` so it can be passed to
+ * APIs that accept any ToolDefinition without requiring a union type.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const BUILT_IN_TOOLS: ToolDefinition<any>[] = [
+  bashTool,
+  fileReadTool,
+  fileWriteTool,
+  fileEditTool,
+  grepTool,
+]
+
+/**
+ * Register all built-in tools with the given registry.
+ *
+ * @example
+ * ```ts
+ * import { ToolRegistry } from '../framework.js'
+ * import { registerBuiltInTools } from './built-in/index.js'
+ *
+ * const registry = new ToolRegistry()
+ * registerBuiltInTools(registry)
+ * ```
+ */
+export function registerBuiltInTools(registry: ToolRegistry): void {
+  for (const tool of BUILT_IN_TOOLS) {
+    registry.register(tool)
+  }
+}

package/src/tool/executor.ts

@@ -0,0 +1,178 @@
+/**
+ * Parallel tool executor with concurrency control and error isolation.
+ *
+ * Validates input via Zod schemas, enforces a maximum concurrency limit using
+ * a lightweight semaphore, tracks execution duration, and surfaces any
+ * execution errors as ToolResult objects rather than thrown exceptions.
+ *
+ * Types are imported from `../types` to ensure consistency with the rest of
+ * the framework.
+ */
+
+import type { ToolResult, ToolUseContext } from '../types.js'
+import type { ToolDefinition } from '../types.js'
+import { ToolRegistry } from './framework.js'
+import { Semaphore } from '../utils/semaphore.js'
+
+// ---------------------------------------------------------------------------
+// ToolExecutor
+// ---------------------------------------------------------------------------
+
+export interface ToolExecutorOptions {
+  /**
+   * Maximum number of tool calls that may run in parallel.
+   * Defaults to 4.
+   */
+  maxConcurrency?: number
+}
+
+/** Describes one call in a batch. */
+export interface BatchToolCall {
+  /** Caller-assigned ID used as the key in the result map. */
+  id: string
+  /** Registered tool name. */
+  name: string
+  /** Raw (unparsed) input object from the LLM. */
+  input: Record<string, unknown>
+}
+
+/**
+ * Executes tools from a {@link ToolRegistry}, validating input against each
+ * tool's Zod schema and enforcing a concurrency limit for batch execution.
+ *
+ * All errors — including unknown tool names, Zod validation failures, and
+ * execution exceptions — are caught and returned as `ToolResult` objects with
+ * `isError: true` so the agent runner can forward them to the LLM.
+ */
+export class ToolExecutor {
+  private readonly registry: ToolRegistry
+  private readonly semaphore: Semaphore
+
+  constructor(registry: ToolRegistry, options: ToolExecutorOptions = {}) {
+    this.registry = registry
+    this.semaphore = new Semaphore(options.maxConcurrency ?? 4)
+  }
+
+  // -------------------------------------------------------------------------
+  // Single execution
+  // -------------------------------------------------------------------------
+
+  /**
+   * Execute a single tool by name.
+   *
+   * Errors are caught and returned as a {@link ToolResult} with
+   * `isError: true` — this method itself never rejects.
+   *
+   * @param toolName  The registered tool name.
+   * @param input     Raw input object (before Zod validation).
+   * @param context   Execution context forwarded to the tool.
+   */
+  async execute(
+    toolName: string,
+    input: Record<string, unknown>,
+    context: ToolUseContext,
+  ): Promise<ToolResult> {
+    const tool = this.registry.get(toolName)
+    if (tool === undefined) {
+      return this.errorResult(
+        `Tool "${toolName}" is not registered in the ToolRegistry.`,
+      )
+    }
+
+    // Check abort before even starting
+    if (context.abortSignal?.aborted === true) {
+      return this.errorResult(
+        `Tool "${toolName}" was aborted before execution began.`,
+      )
+    }
+
+    return this.runTool(tool, input, context)
+  }
+
+  // -------------------------------------------------------------------------
+  // Batch execution
+  // -------------------------------------------------------------------------
+
+  /**
+   * Execute multiple tool calls in parallel, honouring the concurrency limit.
+   *
+   * Returns a `Map` from call ID to result.  Every call in `calls` is
+   * guaranteed to produce an entry — errors are captured as results.
+   *
+   * @param calls    Array of tool calls to execute.
+   * @param context  Shared execution context for all calls in this batch.
+   */
+  async executeBatch(
+    calls: BatchToolCall[],
+    context: ToolUseContext,
+  ): Promise<Map<string, ToolResult>> {
+    const results = new Map<string, ToolResult>()
+
+    await Promise.all(
+      calls.map(async (call) => {
+        const result = await this.semaphore.run(() =>
+          this.execute(call.name, call.input, context),
+        )
+        results.set(call.id, result)
+      }),
+    )
+
+    return results
+  }
+
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Validate input with the tool's Zod schema, then call `execute`.
+   * Any synchronous or asynchronous error is caught and turned into an error
+   * ToolResult.
+   */
+  private async runTool(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tool: ToolDefinition<any>,
+    rawInput: Record<string, unknown>,
+    context: ToolUseContext,
+  ): Promise<ToolResult> {
+    // --- Zod validation ---
+    const parseResult = tool.inputSchema.safeParse(rawInput)
+    if (!parseResult.success) {
+      const issues = parseResult.error.issues
+        .map((issue) => `  • ${issue.path.join('.')}: ${issue.message}`)
+        .join('\n')
+      return this.errorResult(
+        `Invalid input for tool "${tool.name}":\n${issues}`,
+      )
+    }
+
+    // --- Abort check after parse (parse can be expensive for large inputs) ---
+    if (context.abortSignal?.aborted === true) {
+      return this.errorResult(
+        `Tool "${tool.name}" was aborted before execution began.`,
+      )
+    }
+
+    // --- Execute ---
+    try {
+      const result = await tool.execute(parseResult.data, context)
+      return result
+    } catch (err) {
+      const message =
+        err instanceof Error
+          ? err.message
+          : typeof err === 'string'
+            ? err
+            : JSON.stringify(err)
+      return this.errorResult(`Tool "${tool.name}" threw an error: ${message}`)
+    }
+  }
+
+  /** Construct an error ToolResult. */
+  private errorResult(message: string): ToolResult {
+    return {
+      data: message,
+      isError: true,
+    }
+  }
+}