@jackchen_me/open-multi-agent 0.1.0

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

@@ -0,0 +1,187 @@
+/**
+ * Built-in bash tool.
+ *
+ * Executes a shell command and returns its stdout + stderr.  Supports an
+ * optional timeout and a custom working directory.
+ */
+
+import { spawn } from 'child_process'
+import { z } from 'zod'
+import { defineTool } from '../framework.js'
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TIMEOUT_MS = 30_000
+
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+
+export const bashTool = defineTool({
+  name: 'bash',
+  description:
+    'Execute a bash command and return its stdout and stderr. ' +
+    'Use this for file system operations, running scripts, installing packages, ' +
+    'and any task that requires shell access. ' +
+    'The command runs in a non-interactive shell (bash -c). ' +
+    'Long-running commands should use the timeout parameter.',
+
+  inputSchema: z.object({
+    command: z.string().describe('The bash command to execute.'),
+    timeout: z
+      .number()
+      .optional()
+      .describe(
+        `Timeout in milliseconds before the command is forcibly killed. ` +
+          `Defaults to ${DEFAULT_TIMEOUT_MS} ms.`,
+      ),
+    cwd: z
+      .string()
+      .optional()
+      .describe('Working directory in which to run the command.'),
+  }),
+
+  execute: async (input, context) => {
+    const timeoutMs = input.timeout ?? DEFAULT_TIMEOUT_MS
+
+    const { stdout, stderr, exitCode } = await runCommand(
+      input.command,
+      { cwd: input.cwd, timeoutMs },
+      context.abortSignal,
+    )
+
+    const combined = buildOutput(stdout, stderr, exitCode)
+    const isError = exitCode !== 0
+
+    return {
+      data: combined,
+      isError,
+    }
+  },
+})
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+interface RunResult {
+  stdout: string
+  stderr: string
+  exitCode: number
+}
+
+interface RunOptions {
+  cwd: string | undefined
+  timeoutMs: number
+}
+
+/**
+ * Spawn a bash subprocess, capture its output, and resolve when it exits or
+ * the abort signal fires.
+ */
+function runCommand(
+  command: string,
+  options: RunOptions,
+  signal: AbortSignal | undefined,
+): Promise<RunResult> {
+  return new Promise<RunResult>((resolve) => {
+    const stdoutChunks: Buffer[] = []
+    const stderrChunks: Buffer[] = []
+
+    const child = spawn('bash', ['-c', command], {
+      cwd: options.cwd,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    child.stdout.on('data', (chunk: Buffer) => stdoutChunks.push(chunk))
+    child.stderr.on('data', (chunk: Buffer) => stderrChunks.push(chunk))
+
+    let timedOut = false
+    let settled = false
+
+    const done = (exitCode: number): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      if (signal !== undefined) {
+        signal.removeEventListener('abort', onAbort)
+      }
+
+      const stdout = Buffer.concat(stdoutChunks).toString('utf8')
+      const stderr = Buffer.concat(stderrChunks).toString('utf8')
+
+      resolve({ stdout, stderr, exitCode })
+    }
+
+    // Timeout handler
+    const timer = setTimeout(() => {
+      timedOut = true
+      child.kill('SIGKILL')
+    }, options.timeoutMs)
+
+    // Abort-signal handler
+    const onAbort = (): void => {
+      child.kill('SIGKILL')
+    }
+
+    if (signal !== undefined) {
+      signal.addEventListener('abort', onAbort, { once: true })
+    }
+
+    child.on('close', (code: number | null) => {
+      const exitCode = code ?? (timedOut ? 124 : 1)
+      done(exitCode)
+    })
+
+    child.on('error', (err: Error) => {
+      if (!settled) {
+        settled = true
+        clearTimeout(timer)
+        if (signal !== undefined) {
+          signal.removeEventListener('abort', onAbort)
+        }
+        resolve({
+          stdout: '',
+          stderr: err.message,
+          exitCode: 127,
+        })
+      }
+    })
+  })
+}
+
+/**
+ * Format captured output into a single readable string.
+ * When only stdout is present its content is returned as-is.
+ * When stderr is also present both sections are labelled.
+ */
+function buildOutput(stdout: string, stderr: string, exitCode: number): string {
+  const parts: string[] = []
+
+  if (stdout.length > 0) {
+    parts.push(stdout)
+  }
+
+  if (stderr.length > 0) {
+    parts.push(
+      stdout.length > 0
+        ? `--- stderr ---\n${stderr}`
+        : stderr,
+    )
+  }
+
+  if (parts.length === 0) {
+    return exitCode === 0
+      ? '(command completed with no output)'
+      : `(command exited with code ${exitCode}, no output)`
+  }
+
+  if (exitCode !== 0 && parts.length > 0) {
+    parts.push(`\n(exit code: ${exitCode})`)
+  }
+
+  return parts.join('\n')
+}

package/src/tool/built-in/file-edit.ts

@@ -0,0 +1,154 @@
+/**
+ * Built-in file-edit tool.
+ *
+ * Performs a targeted string replacement inside an existing file.
+ * The uniqueness invariant (one match unless replace_all is set) prevents the
+ * common class of bugs where a generic pattern matches the wrong occurrence.
+ */
+
+import { readFile, writeFile } from 'fs/promises'
+import { z } from 'zod'
+import { defineTool } from '../framework.js'
+
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+
+export const fileEditTool = defineTool({
+  name: 'file_edit',
+  description:
+    'Edit a file by replacing a specific string with new content. ' +
+    'The `old_string` must appear verbatim in the file. ' +
+    'By default the tool errors if `old_string` appears more than once — ' +
+    'use `replace_all: true` to replace every occurrence. ' +
+    'Use file_write when you need to create a new file or rewrite it entirely.',
+
+  inputSchema: z.object({
+    path: z
+      .string()
+      .describe('Absolute path to the file to edit.'),
+    old_string: z
+      .string()
+      .describe(
+        'The exact string to find and replace. ' +
+          'Must match character-for-character including whitespace and newlines.',
+      ),
+    new_string: z
+      .string()
+      .describe('The replacement string that will be inserted in place of `old_string`.'),
+    replace_all: z
+      .boolean()
+      .optional()
+      .describe(
+        'When true, replace every occurrence of `old_string` instead of requiring it ' +
+          'to be unique. Defaults to false.',
+      ),
+  }),
+
+  execute: async (input) => {
+    // Read the existing file.
+    let original: string
+    try {
+      const buffer = await readFile(input.path)
+      original = buffer.toString('utf8')
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : 'Unknown error reading file.'
+      return {
+        data: `Could not read "${input.path}": ${message}`,
+        isError: true,
+      }
+    }
+
+    const occurrences = countOccurrences(original, input.old_string)
+
+    if (occurrences === 0) {
+      return {
+        data:
+          `The string to replace was not found in "${input.path}".\n` +
+          'Make sure `old_string` matches the file contents exactly, ' +
+          'including indentation and line endings.',
+        isError: true,
+      }
+    }
+
+    const replaceAll = input.replace_all ?? false
+
+    if (occurrences > 1 && !replaceAll) {
+      return {
+        data:
+          `\`old_string\` appears ${occurrences} times in "${input.path}". ` +
+          'Provide a more specific string to uniquely identify the section you want ' +
+          'to replace, or set `replace_all: true` to replace every occurrence.',
+        isError: true,
+      }
+    }
+
+    // Perform the replacement.
+    const updated = replaceAll
+      ? replaceAllOccurrences(original, input.old_string, input.new_string)
+      : original.replace(input.old_string, input.new_string)
+
+    // Persist the result.
+    try {
+      await writeFile(input.path, updated, 'utf8')
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : 'Unknown error writing file.'
+      return {
+        data: `Failed to write "${input.path}": ${message}`,
+        isError: true,
+      }
+    }
+
+    const replacedCount = replaceAll ? occurrences : 1
+    return {
+      data:
+        `Replaced ${replacedCount} occurrence${replacedCount === 1 ? '' : 's'} ` +
+        `in "${input.path}".`,
+      isError: false,
+    }
+  },
+})
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Count how many times `needle` appears in `haystack`.
+ * Uses a plain loop to avoid constructing a potentially large regex from
+ * untrusted input.
+ */
+function countOccurrences(haystack: string, needle: string): number {
+  if (needle.length === 0) return 0
+  let count = 0
+  let pos = 0
+  while ((pos = haystack.indexOf(needle, pos)) !== -1) {
+    count++
+    pos += needle.length
+  }
+  return count
+}
+
+/**
+ * Replace all occurrences of `needle` in `haystack` with `replacement`
+ * without using a regex (avoids regex-special-character escaping issues).
+ */
+function replaceAllOccurrences(
+  haystack: string,
+  needle: string,
+  replacement: string,
+): string {
+  if (needle.length === 0) return haystack
+  const parts: string[] = []
+  let pos = 0
+  let next: number
+  while ((next = haystack.indexOf(needle, pos)) !== -1) {
+    parts.push(haystack.slice(pos, next))
+    parts.push(replacement)
+    pos = next + needle.length
+  }
+  parts.push(haystack.slice(pos))
+  return parts.join('')
+}

package/src/tool/built-in/file-read.ts

@@ -0,0 +1,105 @@
+/**
+ * Built-in file-read tool.
+ *
+ * Reads a file from disk and returns its contents with 1-based line numbers.
+ * Supports reading a slice of lines via `offset` and `limit` for large files.
+ */
+
+import { readFile } from 'fs/promises'
+import { z } from 'zod'
+import { defineTool } from '../framework.js'
+
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+
+export const fileReadTool = defineTool({
+  name: 'file_read',
+  description:
+    'Read the contents of a file from disk. ' +
+    'Returns the file contents with line numbers prefixed in the format "N\\t<line>". ' +
+    'Use `offset` and `limit` to read large files in chunks without loading the ' +
+    'entire file into the context window.',
+
+  inputSchema: z.object({
+    path: z.string().describe('Absolute path to the file to read.'),
+    offset: z
+      .number()
+      .int()
+      .nonnegative()
+      .optional()
+      .describe(
+        '1-based line number to start reading from. ' +
+          'When omitted the file is read from the beginning.',
+      ),
+    limit: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        'Maximum number of lines to return. ' +
+          'When omitted all lines from `offset` to the end of the file are returned.',
+      ),
+  }),
+
+  execute: async (input) => {
+    let raw: string
+    try {
+      const buffer = await readFile(input.path)
+      raw = buffer.toString('utf8')
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : 'Unknown error reading file.'
+      return {
+        data: `Could not read file "${input.path}": ${message}`,
+        isError: true,
+      }
+    }
+
+    // Split preserving trailing newlines correctly
+    const lines = raw.split('\n')
+
+    // Remove the last empty string produced by a trailing newline
+    if (lines.length > 0 && lines[lines.length - 1] === '') {
+      lines.pop()
+    }
+
+    const totalLines = lines.length
+
+    // Apply offset (convert from 1-based to 0-based)
+    const startIndex =
+      input.offset !== undefined ? Math.max(0, input.offset - 1) : 0
+
+    if (startIndex >= totalLines && totalLines > 0) {
+      return {
+        data:
+          `File "${input.path}" has ${totalLines} line${totalLines === 1 ? '' : 's'} ` +
+          `but offset ${input.offset} is beyond the end.`,
+        isError: true,
+      }
+    }
+
+    const endIndex =
+      input.limit !== undefined
+        ? Math.min(startIndex + input.limit, totalLines)
+        : totalLines
+
+    const slice = lines.slice(startIndex, endIndex)
+
+    // Build line-numbered output (1-based line numbers matching file positions)
+    const numbered = slice
+      .map((line, i) => `${startIndex + i + 1}\t${line}`)
+      .join('\n')
+
+    const meta =
+      endIndex < totalLines
+        ? `\n\n(showing lines ${startIndex + 1}–${endIndex} of ${totalLines})`
+        : ''
+
+    return {
+      data: numbered + meta,
+      isError: false,
+    }
+  },
+})

package/src/tool/built-in/file-write.ts

@@ -0,0 +1,81 @@
+/**
+ * Built-in file-write tool.
+ *
+ * Creates or overwrites a file with the supplied content.  Parent directories
+ * are created automatically (equivalent to `mkdir -p`).
+ */
+
+import { mkdir, stat, writeFile } from 'fs/promises'
+import { dirname } from 'path'
+import { z } from 'zod'
+import { defineTool } from '../framework.js'
+
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+
+export const fileWriteTool = defineTool({
+  name: 'file_write',
+  description:
+    'Write content to a file, creating it (and any missing parent directories) if it ' +
+    'does not already exist, or overwriting it if it does. ' +
+    'Prefer this tool for creating new files; use file_edit for targeted in-place edits ' +
+    'of existing files.',
+
+  inputSchema: z.object({
+    path: z
+      .string()
+      .describe(
+        'Absolute path to the file to write. ' +
+          'The path must be absolute (starting with /).',
+      ),
+    content: z.string().describe('The full content to write to the file.'),
+  }),
+
+  execute: async (input) => {
+    // Determine whether the file already exists so we can report create vs update.
+    let existed = false
+    try {
+      await stat(input.path)
+      existed = true
+    } catch {
+      // File does not exist — will be created.
+    }
+
+    // Ensure parent directory hierarchy exists.
+    const parentDir = dirname(input.path)
+    try {
+      await mkdir(parentDir, { recursive: true })
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : 'Unknown error creating directories.'
+      return {
+        data: `Failed to create parent directory "${parentDir}": ${message}`,
+        isError: true,
+      }
+    }
+
+    // Write the file.
+    try {
+      await writeFile(input.path, input.content, 'utf8')
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : 'Unknown error writing file.'
+      return {
+        data: `Failed to write file "${input.path}": ${message}`,
+        isError: true,
+      }
+    }
+
+    const lineCount = input.content.split('\n').length
+    const byteCount = Buffer.byteLength(input.content, 'utf8')
+    const action = existed ? 'Updated' : 'Created'
+
+    return {
+      data:
+        `${action} "${input.path}" ` +
+        `(${lineCount} line${lineCount === 1 ? '' : 's'}, ${byteCount} bytes).`,
+      isError: false,
+    }
+  },
+})