@agentscope-ai/agentscope 0.0.2

package/src/tool/grep.ts

@@ -0,0 +1,256 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { z } from 'zod';
+
+type OutputMode = 'content' | 'files_with_matches' | 'count';
+
+const TYPE_EXTENSIONS: Record<string, string[]> = {
+    js: ['.js', '.mjs', '.cjs'],
+    ts: ['.ts', '.mts', '.cts'],
+    tsx: ['.tsx'],
+    jsx: ['.jsx'],
+    py: ['.py'],
+    rust: ['.rs'],
+    go: ['.go'],
+    java: ['.java'],
+    cpp: ['.cpp', '.cc', '.cxx', '.h', '.hpp'],
+    c: ['.c', '.h'],
+    css: ['.css'],
+    html: ['.html', '.htm'],
+    json: ['.json'],
+    md: ['.md', '.markdown'],
+    yaml: ['.yaml', '.yml'],
+    toml: ['.toml'],
+    sh: ['.sh', '.bash'],
+};
+
+/**
+ * Tool for searching file contents using regular expressions.
+ * Supports multiple output modes, file type filtering, and multiline matching.
+ *
+ * @returns A Tool object for performing regex searches across files, with a call method that executes the search and returns results based on the specified output mode.
+ */
+export function Grep() {
+    /**
+     * Collects all files under a base directory, optionally filtered by glob or type.
+     * @param baseDir - The base directory to search from.
+     * @param glob - Optional glob pattern to filter files by name.
+     * @param type - Optional file type key to filter by extension.
+     * @returns An array of matching file paths.
+     */
+    const collectFiles = (baseDir: string, glob?: string, type?: string): string[] => {
+        const results: string[] = [];
+        const extensions = type ? TYPE_EXTENSIONS[type] : undefined;
+
+        const walk = (dir: string): void => {
+            let entries: fs.Dirent[];
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            } catch {
+                return;
+            }
+
+            for (const entry of entries) {
+                if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(fullPath);
+                } else if (entry.isFile()) {
+                    if (extensions) {
+                        const ext = path.extname(entry.name);
+                        if (extensions.includes(ext)) results.push(fullPath);
+                    } else if (glob) {
+                        if (matchGlob(glob, entry.name)) results.push(fullPath);
+                    } else {
+                        results.push(fullPath);
+                    }
+                }
+            }
+        };
+
+        if (fs.existsSync(baseDir) && fs.statSync(baseDir).isFile()) {
+            results.push(baseDir);
+        } else {
+            walk(baseDir);
+        }
+
+        return results;
+    };
+
+    /**
+     * Tests whether a filename matches a glob pattern.
+     * @param pattern - The glob pattern to match against.
+     * @param filename - The filename to test.
+     * @returns True if the filename matches the pattern, false otherwise.
+     */
+    const matchGlob = (pattern: string, filename: string): boolean => {
+        const braceMatch = pattern.match(/\*\.\\{(.+)\\}/);
+        if (braceMatch) {
+            const exts = braceMatch[1].split(',').map(e => `.${e.trim()}`);
+            return exts.includes(path.extname(filename));
+        }
+        const escaped = pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*/g, '.*')
+            .replace(/\?/g, '.');
+        return new RegExp(`^${escaped}$`).test(filename);
+    };
+
+    return {
+        name: 'Grep',
+        description: `A powerful search tool built on regular expressions.
+
+Usage:
+- ALWAYS use Grep for search tasks. NEVER invoke \`grep\` or \`rg\` as a Bash command. The Grep tool has been optimized for correct permissions and access.
+- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
+- Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
+- Use Task tool for open-ended searches requiring multiple rounds
+- Pattern syntax: Uses ripgrep-style regex - literal braces need escaping (use \`interface\\{\\}\` to find \`interface{}\` in Go code)
+- Multiline matching: By default patterns match within single lines only. For cross-line patterns, use \`multiline: true\``,
+        inputSchema: z.object({
+            pattern: z
+                .string()
+                .describe('The regular expression pattern to search for in file contents'),
+            path: z
+                .string()
+                .optional()
+                .describe('File or directory to search in. Defaults to current working directory.'),
+            glob: z
+                .string()
+                .optional()
+                .describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")'),
+            type: z
+                .string()
+                .optional()
+                .describe(
+                    'File type to search (e.g., "js", "ts", "py"). More efficient than glob for standard file types.'
+                ),
+            output_mode: z
+                .enum(['content', 'files_with_matches', 'count'])
+                .optional()
+                .describe(
+                    'Output mode: "content" | "files_with_matches" | "count". Defaults to "files_with_matches".'
+                ),
+            multiline: z
+                .boolean()
+                .optional()
+                .describe(
+                    'Enable multiline mode where . matches newlines and patterns can span lines. Default: false.'
+                ),
+            case_insensitive: z
+                .boolean()
+                .optional()
+                .describe('Case insensitive search. Default: false.'),
+            context: z
+                .number()
+                .int()
+                .optional()
+                .describe(
+                    'Number of lines to show before and after each match. Requires output_mode: "content".'
+                ),
+            head_limit: z
+                .number()
+                .int()
+                .optional()
+                .describe('Limit output to first N lines/entries.'),
+        }),
+        requireUserConfirm: true,
+
+        /**
+         * Searches files for a regex pattern and returns results in the specified output mode.
+         *
+         * @param root0 - The parameters object
+         * @param root0.pattern - The regular expression pattern to search for
+         * @param root0.path - File or directory to search in; defaults to cwd
+         * @param root0.glob - Glob pattern to filter which files are searched
+         * @param root0.type - File type shorthand (e.g. "ts", "py") to filter files
+         * @param root0.output_mode - How to format results: "content", "files_with_matches", or "count"
+         * @param root0.multiline - Whether the pattern can span multiple lines
+         * @param root0.case_insensitive - Whether the search is case-insensitive
+         * @param root0.context - Number of surrounding lines to include with each match
+         * @param root0.head_limit - Maximum number of result entries to return
+         * @returns A newline-separated string of results, or a no-matches message
+         */
+        call({
+            pattern,
+            path: searchPath,
+            glob,
+            type,
+            output_mode = 'files_with_matches',
+            multiline = false,
+            case_insensitive = false,
+            context,
+            head_limit,
+        }: {
+            pattern: string;
+            path?: string;
+            glob?: string;
+            type?: string;
+            output_mode?: OutputMode;
+            multiline?: boolean;
+            case_insensitive?: boolean;
+            context?: number;
+            head_limit?: number;
+        }): string {
+            const baseDir = searchPath ? searchPath : process.cwd();
+
+            let flags = multiline ? 'gms' : 'gm';
+            if (case_insensitive) flags += 'i';
+
+            const regex = new RegExp(pattern, flags);
+            const files = collectFiles(baseDir, glob, type);
+
+            if (files.length === 0) {
+                return 'No files found to search.';
+            }
+
+            const results: string[] = [];
+
+            for (const file of files) {
+                try {
+                    const content = fs.readFileSync(file, 'utf-8');
+
+                    if (output_mode === 'files_with_matches') {
+                        if (regex.test(content)) {
+                            results.push(file);
+                        }
+                        regex.lastIndex = 0;
+                    } else if (output_mode === 'count') {
+                        const matches = content.match(regex);
+                        if (matches) {
+                            results.push(`${file}: ${matches.length}`);
+                        }
+                        regex.lastIndex = 0;
+                    } else if (output_mode === 'content') {
+                        const lines = content.split('\n');
+                        for (let i = 0; i < lines.length; i++) {
+                            const lineRegex = new RegExp(pattern, case_insensitive ? 'i' : '');
+                            if (lineRegex.test(lines[i])) {
+                                const start = context !== undefined ? Math.max(0, i - context) : i;
+                                const end =
+                                    context !== undefined
+                                        ? Math.min(lines.length - 1, i + context)
+                                        : i;
+                                for (let j = start; j <= end; j++) {
+                                    results.push(`${file}:${j + 1}:${lines[j]}`);
+                                }
+                            }
+                        }
+                    }
+                } catch {
+                    // skip unreadable files
+                }
+            }
+
+            if (results.length === 0) {
+                return `No matches found for pattern: ${pattern}`;
+            }
+
+            const output = head_limit !== undefined ? results.slice(0, head_limit) : results;
+            return output.join('\n');
+        },
+    };
+}

package/src/tool/index.ts

@@ -0,0 +1,10 @@
+export { ToolResponse } from './response';
+export { Tool } from './base';
+export { Toolkit } from './toolkit';
+export { Bash } from './bash';
+export { Read } from './read';
+export { Write } from './write';
+export { Edit } from './edit';
+export { Glob } from './glob';
+export { Grep } from './grep';
+export { TaskCreate, TaskUpdate, TaskGet, TaskList } from './task';

package/src/tool/read.test.ts

@@ -0,0 +1,77 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { Tool } from './base';
+import { Read } from './read';
+import { ToolResponse } from './response';
+
+describe('Read', () => {
+    let tmpDir: string;
+    let read: Tool;
+
+    beforeEach(() => {
+        read = Read();
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'read-test-'));
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    const getTextFromResponse = (response: ToolResponse): string => {
+        const textBlock = response.content.find(block => block.type === 'text');
+        return textBlock && 'text' in textBlock ? textBlock.text : '';
+    };
+
+    it('reads a file with line numbers', () => {
+        const filePath = path.join(tmpDir, 'test.txt');
+        fs.writeFileSync(filePath, 'line1\nline2\nline3');
+        const response = read.call!({ file_path: filePath }) as ToolResponse;
+        const result = getTextFromResponse(response);
+        expect(result).toContain('1\tline1');
+        expect(result).toContain('2\tline2');
+        expect(result).toContain('3\tline3');
+    });
+
+    it('respects offset and limit', () => {
+        const filePath = path.join(tmpDir, 'test.txt');
+        fs.writeFileSync(filePath, 'a\nb\nc\nd\ne');
+        const response = read.call!({ file_path: filePath, offset: 2, limit: 2 }) as ToolResponse;
+        const result = getTextFromResponse(response);
+        expect(result).toContain('2\tb');
+        expect(result).toContain('3\tc');
+        expect(result).not.toContain('1\ta');
+        expect(result).not.toContain('4\td');
+    });
+
+    it('throws on relative path', () => {
+        expect(() => read.call!({ file_path: 'relative.txt' })).toThrow('absolute path');
+    });
+
+    it('throws on non-existent file', () => {
+        expect(() => read.call!({ file_path: path.join(tmpDir, 'nope.txt') })).toThrow(
+            'File not found'
+        );
+    });
+
+    it('throws on directory', () => {
+        expect(() => read.call!({ file_path: tmpDir })).toThrow('directory');
+    });
+
+    it('returns warning for empty file', () => {
+        const filePath = path.join(tmpDir, 'empty.txt');
+        fs.writeFileSync(filePath, '');
+        const response = read.call!({ file_path: filePath }) as ToolResponse;
+        const result = getTextFromResponse(response);
+        expect(result).toBe('');
+    });
+
+    it('truncates lines longer than 2000 characters', () => {
+        const filePath = path.join(tmpDir, 'long.txt');
+        fs.writeFileSync(filePath, 'x'.repeat(2100));
+        const response = read.call!({ file_path: filePath }) as ToolResponse;
+        const result = getTextFromResponse(response);
+        expect(result).toContain('[truncated]');
+    });
+});

package/src/tool/read.ts

@@ -0,0 +1,117 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { z } from 'zod';
+
+import { createToolResponse, ToolResponse } from './response';
+
+/**
+ * Tool for reading files from the local filesystem.
+ * Returns file contents with line numbers in cat -n format.
+ *
+ * @returns A Tool object for reading files, with a call method that performs the read operation and returns the formatted contents or a warning if the file is empty.
+ */
+export function Read() {
+    return {
+        name: 'Read',
+        description: `Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to 2000 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 2000 characters will be truncated
+- Results are returned using cat -n format, with line numbers starting at 1
+- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
+- You can call multiple tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.
+- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.`,
+        inputSchema: z.object({
+            file_path: z.string().describe('The absolute path to the file to read'),
+            offset: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe(
+                    'The line number to start reading from. Only provide if the file is too large to read at once'
+                ),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe(
+                    'The number of lines to read. Only provide if the file is too large to read at once'
+                ),
+        }),
+        requireUserConfirm: true,
+
+        /**
+         * Reads a file and returns its contents with line numbers.
+         *
+         * @param root0 - The parameters object
+         * @param root0.file_path - Absolute path to the file to read
+         * @param root0.offset - Line number to start reading from (1-based)
+         * @param root0.limit - Maximum number of lines to read (capped at 2000)
+         * @returns The file contents formatted with line numbers, or a warning if the file is empty
+         * @throws If the path is not absolute, the file does not exist, or the path is a directory
+         */
+        call({
+            file_path,
+            offset,
+            limit,
+        }: {
+            file_path: string;
+            offset?: number;
+            limit?: number;
+        }): ToolResponse {
+            if (!path.isAbsolute(file_path)) {
+                throw new Error(`file_path must be an absolute path, got: ${file_path}`);
+            }
+
+            if (!fs.existsSync(file_path)) {
+                throw new Error(`File not found: ${file_path}`);
+            }
+
+            const stat = fs.statSync(file_path);
+            if (stat.isDirectory()) {
+                throw new Error(
+                    `${file_path} is a directory, not a file. Use Bash with ls to read directories.`
+                );
+            }
+
+            const rawContent = fs.readFileSync(file_path, 'utf-8');
+
+            if (rawContent.length === 0) {
+                return createToolResponse({
+                    content: [{ id: crypto.randomUUID(), type: 'text', text: rawContent }],
+                    state: 'success',
+                });
+            }
+
+            const allLines = rawContent.split('\n');
+            const startLine = offset !== undefined ? offset - 1 : 0;
+            const maxLines = 2000;
+            const effectiveLimit = limit !== undefined ? Math.min(limit, maxLines) : maxLines;
+            const selectedLines = allLines.slice(startLine, startLine + effectiveLimit);
+
+            const maxLineLength = 2000;
+            const formatted = selectedLines
+                .map((line, i) => {
+                    const lineNum = startLine + i + 1;
+                    const truncated =
+                        line.length > maxLineLength
+                            ? line.substring(0, maxLineLength) + '[truncated]'
+                            : line;
+                    return `${String(lineNum).padStart(6)}\t${truncated}`;
+                })
+                .join('\n');
+
+            return createToolResponse({
+                content: [{ id: crypto.randomUUID(), type: 'text', text: formatted }],
+                state: 'success',
+            });
+        },
+    };
+}

package/src/tool/response.ts

@@ -0,0 +1,82 @@
+import { DataBlock, TextBlock } from '../message';
+import { JSONSerializableObject } from '../type';
+
+/**
+ * The tool response structure.
+ */
+export interface ToolResponse {
+    content: Array<TextBlock | DataBlock>;
+    id: string;
+    createdAt: string;
+    metadata: Record<string, JSONSerializableObject>;
+    state: 'success' | 'error' | 'interrupted' | 'running';
+    isLast: boolean;
+    isInterrupted: boolean;
+}
+
+/**
+ * Create a tool response object with the given parameters.
+ *
+ * @param root0
+ * @param root0.content
+ * @param root0.state
+ * @param root0.id
+ * @param root0.createdAt
+ * @param root0.metadata
+ * @param root0.stream
+ * @param root0.isLast
+ * @param root0.isInterrupted
+ * @returns A ToolResponse object
+ */
+export function createToolResponse({
+    content,
+    state,
+    id = crypto.randomUUID(),
+    createdAt = new Date().toISOString(),
+    metadata = {},
+    stream = false,
+    isLast = true,
+    isInterrupted = false,
+}: {
+    content: Array<TextBlock | DataBlock>;
+    state: 'success' | 'error' | 'interrupted' | 'running';
+    id?: string;
+    createdAt?: string;
+    metadata?: Record<string, JSONSerializableObject>;
+    stream?: boolean;
+    isLast?: boolean;
+    isInterrupted?: boolean;
+}) {
+    return {
+        content,
+        id,
+        createdAt,
+        metadata,
+        state,
+        stream,
+        isLast,
+        isInterrupted,
+    } as ToolResponse;
+}
+
+/**
+ * If the given object conforms to the ToolResponse structure.
+ *
+ * @param obj
+ * @returns True if the object is a ToolResponse, false otherwise
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function isToolResponse(obj: any): boolean {
+    return (
+        obj &&
+        typeof obj === 'object' &&
+        typeof obj.id === 'string' &&
+        typeof obj.createdAt === 'string' &&
+        Array.isArray(obj.content) &&
+        typeof obj.metadata === 'object' &&
+        typeof obj.stream === 'boolean' &&
+        typeof obj.isLast === 'boolean' &&
+        typeof obj.isInterrupted === 'boolean' &&
+        ['success', 'error', 'interrupted', 'running'].includes(obj.state)
+    );
+}