discoclaw 0.2.4 → 0.3.0

package/dist/runtime/openai-tool-exec.test.js

@@ -0,0 +1,267 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { executeToolCall } from './openai-tool-exec.js';
+// ── Helpers ──────────────────────────────────────────────────────────
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-tool-exec-'));
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+// ── read_file ────────────────────────────────────────────────────────
+describe('read_file', () => {
+    it('reads an existing file', async () => {
+        const filePath = path.join(tmpDir, 'hello.txt');
+        await fs.writeFile(filePath, 'hello world\n');
+        const r = await executeToolCall('read_file', { file_path: filePath }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toBe('hello world\n');
+    });
+    it('returns error for nonexistent file', async () => {
+        const filePath = path.join(tmpDir, 'nope.txt');
+        const r = await executeToolCall('read_file', { file_path: filePath }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toMatch(/ENOENT|no such file|not accessible/i);
+    });
+    it('reads with offset and limit', async () => {
+        const filePath = path.join(tmpDir, 'lines.txt');
+        await fs.writeFile(filePath, 'line1\nline2\nline3\nline4\nline5\n');
+        const r = await executeToolCall('read_file', { file_path: filePath, offset: 2, limit: 2 }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toBe('line2\nline3');
+    });
+    it('returns error when file_path is missing', async () => {
+        const r = await executeToolCall('read_file', {}, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('file_path');
+    });
+});
+// ── write_file ───────────────────────────────────────────────────────
+describe('write_file', () => {
+    it('writes a new file and creates parent directories', async () => {
+        const filePath = path.join(tmpDir, 'sub', 'dir', 'output.txt');
+        const r = await executeToolCall('write_file', { file_path: filePath, content: 'created!' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        const contents = await fs.readFile(filePath, 'utf-8');
+        expect(contents).toBe('created!');
+    });
+    it('overwrites an existing file', async () => {
+        const filePath = path.join(tmpDir, 'existing.txt');
+        await fs.writeFile(filePath, 'old content');
+        const r = await executeToolCall('write_file', { file_path: filePath, content: 'new content' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        const contents = await fs.readFile(filePath, 'utf-8');
+        expect(contents).toBe('new content');
+    });
+    it('returns error when content is missing', async () => {
+        const r = await executeToolCall('write_file', { file_path: path.join(tmpDir, 'x.txt') }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('content');
+    });
+});
+// ── edit_file ────────────────────────────────────────────────────────
+describe('edit_file', () => {
+    it('replaces a unique match', async () => {
+        const filePath = path.join(tmpDir, 'code.ts');
+        await fs.writeFile(filePath, 'const x = 1;\nconst y = 2;\n');
+        const r = await executeToolCall('edit_file', { file_path: filePath, old_string: 'const x = 1;', new_string: 'const x = 42;' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        const updated = await fs.readFile(filePath, 'utf-8');
+        expect(updated).toBe('const x = 42;\nconst y = 2;\n');
+    });
+    it('fails when old_string not found', async () => {
+        const filePath = path.join(tmpDir, 'code.ts');
+        await fs.writeFile(filePath, 'const x = 1;\n');
+        const r = await executeToolCall('edit_file', { file_path: filePath, old_string: 'nonexistent', new_string: 'replaced' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('not found');
+    });
+    it('fails when old_string has multiple matches (without replace_all)', async () => {
+        const filePath = path.join(tmpDir, 'code.ts');
+        await fs.writeFile(filePath, 'foo\nfoo\nbar\n');
+        const r = await executeToolCall('edit_file', { file_path: filePath, old_string: 'foo', new_string: 'baz' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('2 times');
+    });
+    it('replace_all replaces all occurrences', async () => {
+        const filePath = path.join(tmpDir, 'code.ts');
+        await fs.writeFile(filePath, 'foo\nfoo\nbar\n');
+        const r = await executeToolCall('edit_file', { file_path: filePath, old_string: 'foo', new_string: 'baz', replace_all: true }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        const updated = await fs.readFile(filePath, 'utf-8');
+        expect(updated).toBe('baz\nbaz\nbar\n');
+    });
+});
+// ── list_files ───────────────────────────────────────────────────────
+describe('list_files', () => {
+    it('finds files matching a glob pattern', async () => {
+        await fs.writeFile(path.join(tmpDir, 'a.ts'), '');
+        await fs.writeFile(path.join(tmpDir, 'b.ts'), '');
+        await fs.writeFile(path.join(tmpDir, 'c.js'), '');
+        const r = await executeToolCall('list_files', { pattern: '*.ts', path: tmpDir }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toContain('a.ts');
+        expect(r.result).toContain('b.ts');
+        expect(r.result).not.toContain('c.js');
+    });
+    it('returns message when no files match', async () => {
+        const r = await executeToolCall('list_files', { pattern: '*.xyz', path: tmpDir }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toContain('No files matched');
+    });
+});
+// ── search_content ───────────────────────────────────────────────────
+describe('search_content', () => {
+    it('finds content matching a pattern', async () => {
+        await fs.writeFile(path.join(tmpDir, 'file.txt'), 'hello world\ngoodbye world\n');
+        const r = await executeToolCall('search_content', { pattern: 'hello', path: tmpDir }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toContain('hello');
+    });
+    it('returns no matches message for missing pattern', async () => {
+        await fs.writeFile(path.join(tmpDir, 'file.txt'), 'hello\n');
+        const r = await executeToolCall('search_content', { pattern: 'zzzznotfound', path: tmpDir }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toContain('No matches');
+    });
+});
+// ── bash ─────────────────────────────────────────────────────────────
+describe('bash', () => {
+    it('executes a simple echo command', async () => {
+        const r = await executeToolCall('bash', { command: 'echo hello' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toContain('hello');
+    });
+    it('returns error on nonzero exit', async () => {
+        const r = await executeToolCall('bash', { command: 'exit 1' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+    });
+    it('uses first allowed root as cwd', async () => {
+        const r = await executeToolCall('bash', { command: 'pwd' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        // The cwd should be the tmpDir (resolve symlinks for comparison)
+        const realTmpDir = await fs.realpath(tmpDir);
+        expect(r.result.trim()).toBe(realTmpDir);
+    });
+    it('times out on long-running commands', async () => {
+        // Use a very short timeout via the handler's internal timeout — we test
+        // the mechanism by running a command that hangs, but we can't easily
+        // override the 30s const. Instead test that a fast-exit command works
+        // and trust the execFile timeout mechanism. A full timeout test would
+        // need 30+ seconds which is too slow for unit tests.
+        const r = await executeToolCall('bash', { command: 'echo fast' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+    });
+});
+// ── web_fetch ────────────────────────────────────────────────────────
+describe('web_fetch', () => {
+    const originalFetch = globalThis.fetch;
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it('fetches HTTPS URL successfully', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(new Response('page content', { status: 200 }));
+        const r = await executeToolCall('web_fetch', { url: 'https://example.com/page' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toBe('page content');
+    });
+    it('rejects HTTP (non-HTTPS) URLs', async () => {
+        const r = await executeToolCall('web_fetch', { url: 'http://example.com/page' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('HTTPS');
+    });
+    it('rejects private IP addresses (10.x)', async () => {
+        const r = await executeToolCall('web_fetch', { url: 'https://10.0.0.1/internal' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('private');
+    });
+    it('rejects private IP addresses (192.168.x)', async () => {
+        const r = await executeToolCall('web_fetch', { url: 'https://192.168.1.1/internal' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('private');
+    });
+    it('rejects localhost', async () => {
+        const r = await executeToolCall('web_fetch', { url: 'https://localhost/internal' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('localhost');
+    });
+    it('rejects loopback IP', async () => {
+        const r = await executeToolCall('web_fetch', { url: 'https://127.0.0.1/internal' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('private');
+    });
+});
+// ── web_search ───────────────────────────────────────────────────────
+describe('web_search', () => {
+    it('returns not available stub', async () => {
+        const r = await executeToolCall('web_search', { query: 'test' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('web_search not available');
+    });
+});
+// ── Security: path traversal ─────────────────────────────────────────
+describe('path security', () => {
+    it('rejects ../ traversal outside allowed roots', async () => {
+        const filePath = path.join(tmpDir, '..', 'etc', 'passwd');
+        const r = await executeToolCall('read_file', { file_path: filePath }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toMatch(/outside allowed roots|not accessible/i);
+    });
+    it('rejects absolute path outside allowed roots', async () => {
+        const r = await executeToolCall('read_file', { file_path: '/etc/hostname' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toMatch(/outside allowed roots|not accessible/i);
+    });
+    it('rejects symlink pointing outside allowed roots', async () => {
+        // Create a temp file outside the allowed root
+        const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-outside-'));
+        const outsideFile = path.join(outsideDir, 'secret.txt');
+        await fs.writeFile(outsideFile, 'secret data');
+        // Create symlink inside allowed root pointing outside
+        const symlinkPath = path.join(tmpDir, 'escape-link');
+        await fs.symlink(outsideFile, symlinkPath);
+        const r = await executeToolCall('read_file', { file_path: symlinkPath }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toMatch(/outside allowed roots|not accessible/i);
+        // Clean up
+        await fs.rm(outsideDir, { recursive: true, force: true });
+    });
+    it('rejects write_file outside allowed roots', async () => {
+        const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-outside-'));
+        const filePath = path.join(outsideDir, 'injected.txt');
+        const r = await executeToolCall('write_file', { file_path: filePath, content: 'injected' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toMatch(/outside allowed roots|not accessible/i);
+        // File should not have been created
+        await expect(fs.access(filePath)).rejects.toThrow();
+        await fs.rm(outsideDir, { recursive: true, force: true });
+    });
+    it('allows access with multiple allowed roots', async () => {
+        const secondRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-root2-'));
+        const filePath = path.join(secondRoot, 'allowed.txt');
+        await fs.writeFile(filePath, 'allowed content');
+        const r = await executeToolCall('read_file', { file_path: filePath }, [tmpDir, secondRoot]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toBe('allowed content');
+        await fs.rm(secondRoot, { recursive: true, force: true });
+    });
+});
+// ── Unknown tool ─────────────────────────────────────────────────────
+describe('unknown tool', () => {
+    it('returns error for unknown tool name', async () => {
+        const r = await executeToolCall('nonexistent_tool', {}, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('Unknown tool');
+    });
+});
+// ── Empty allowed roots ──────────────────────────────────────────────
+describe('empty allowed roots', () => {
+    it('returns error when no roots are configured', async () => {
+        const r = await executeToolCall('read_file', { file_path: '/etc/hostname' }, []);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('No allowed roots');
+    });
+});

package/dist/runtime/openai-tool-schemas.js

@@ -0,0 +1,174 @@
+/**
+ * OpenAI function-calling tool definitions for discoclaw tools.
+ *
+ * Maps internal tool names (Read, Write, …) to OpenAI function names
+ * (read_file, write_file, …) and provides JSON Schema parameter definitions.
+ */
+/** Discoclaw tool name → OpenAI function name */
+const DISCO_TO_OPENAI_NAME = {
+    Read: 'read_file',
+    Write: 'write_file',
+    Edit: 'edit_file',
+    Glob: 'list_files',
+    Grep: 'search_content',
+    Bash: 'bash',
+    WebSearch: 'web_search',
+    WebFetch: 'web_fetch',
+};
+/** OpenAI function name → discoclaw tool name (for dispatching tool results) */
+export const OPENAI_TO_DISCO_NAME = Object.fromEntries(Object.entries(DISCO_TO_OPENAI_NAME).map(([disco, openai]) => [openai, disco]));
+const TOOL_DEFS = {
+    Read: {
+        type: 'function',
+        function: {
+            name: 'read_file',
+            description: 'Read the contents of a file at the given path.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    file_path: { type: 'string', description: 'Absolute path to the file to read.' },
+                    offset: { type: 'number', description: 'Line number to start reading from (1-based).' },
+                    limit: { type: 'number', description: 'Maximum number of lines to read.' },
+                },
+                required: ['file_path'],
+                additionalProperties: false,
+            },
+        },
+    },
+    Write: {
+        type: 'function',
+        function: {
+            name: 'write_file',
+            description: 'Write content to a file, creating or overwriting it.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    file_path: { type: 'string', description: 'Absolute path to the file to write.' },
+                    content: { type: 'string', description: 'The full content to write to the file.' },
+                },
+                required: ['file_path', 'content'],
+                additionalProperties: false,
+            },
+        },
+    },
+    Edit: {
+        type: 'function',
+        function: {
+            name: 'edit_file',
+            description: 'Perform an exact string replacement in a file.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    file_path: { type: 'string', description: 'Absolute path to the file to edit.' },
+                    old_string: { type: 'string', description: 'The exact text to find and replace.' },
+                    new_string: { type: 'string', description: 'The replacement text.' },
+                    replace_all: {
+                        type: 'boolean',
+                        description: 'Replace all occurrences instead of just the first.',
+                    },
+                },
+                required: ['file_path', 'old_string', 'new_string'],
+                additionalProperties: false,
+            },
+        },
+    },
+    Glob: {
+        type: 'function',
+        function: {
+            name: 'list_files',
+            description: 'Find files matching a glob pattern.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    pattern: { type: 'string', description: 'Glob pattern to match (e.g. "**/*.ts").' },
+                    path: { type: 'string', description: 'Directory to search in.' },
+                },
+                required: ['pattern'],
+                additionalProperties: false,
+            },
+        },
+    },
+    Grep: {
+        type: 'function',
+        function: {
+            name: 'search_content',
+            description: 'Search file contents using a regular expression pattern.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    pattern: { type: 'string', description: 'Regex pattern to search for.' },
+                    path: { type: 'string', description: 'File or directory to search in.' },
+                    glob: { type: 'string', description: 'Glob to filter files (e.g. "*.ts").' },
+                    case_insensitive: { type: 'boolean', description: 'Case-insensitive search.' },
+                },
+                required: ['pattern'],
+                additionalProperties: false,
+            },
+        },
+    },
+    Bash: {
+        type: 'function',
+        function: {
+            name: 'bash',
+            description: 'Execute a shell command and return its output.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    command: { type: 'string', description: 'The shell command to execute.' },
+                    timeout: {
+                        type: 'number',
+                        description: 'Timeout in milliseconds (max 600000).',
+                    },
+                },
+                required: ['command'],
+                additionalProperties: false,
+            },
+        },
+    },
+    WebSearch: {
+        type: 'function',
+        function: {
+            name: 'web_search',
+            description: 'Search the web and return results.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'The search query.' },
+                },
+                required: ['query'],
+                additionalProperties: false,
+            },
+        },
+    },
+    WebFetch: {
+        type: 'function',
+        function: {
+            name: 'web_fetch',
+            description: 'Fetch the content of a web page by URL.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    url: { type: 'string', description: 'The URL to fetch.' },
+                },
+                required: ['url'],
+                additionalProperties: false,
+            },
+        },
+    },
+};
+// ── Public API ────────────────────────────────────────────────────────
+/**
+ * Build OpenAI function-calling tool definitions for the given enabled tools.
+ *
+ * Only tools that have a known schema are included; unknown names are silently
+ * skipped so callers don't need to pre-filter.
+ */
+export function buildToolSchemas(enabledTools) {
+    const schemas = [];
+    for (const tool of enabledTools) {
+        const def = TOOL_DEFS[tool];
+        if (def)
+            schemas.push(def);
+    }
+    return schemas;
+}

package/dist/runtime/openai-tool-schemas.test.js

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { buildToolSchemas, OPENAI_TO_DISCO_NAME } from './openai-tool-schemas.js';
+const ALL_DISCO_TOOLS = ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash', 'WebSearch', 'WebFetch'];
+describe('buildToolSchemas', () => {
+    it('returns schemas for all 8 tools when all are enabled', () => {
+        const schemas = buildToolSchemas(ALL_DISCO_TOOLS);
+        expect(schemas).toHaveLength(8);
+    });
+    it('each schema has correct shape', () => {
+        const schemas = buildToolSchemas(ALL_DISCO_TOOLS);
+        for (const schema of schemas) {
+            expect(schema.type).toBe('function');
+            expect(schema.function).toBeDefined();
+            expect(typeof schema.function.name).toBe('string');
+            expect(typeof schema.function.description).toBe('string');
+            expect(schema.function.parameters).toBeDefined();
+            expect(schema.function.parameters).toHaveProperty('type', 'object');
+            expect(schema.function.parameters).toHaveProperty('properties');
+            expect(schema.function.parameters).toHaveProperty('required');
+        }
+    });
+    it('returns correct OpenAI function names', () => {
+        const schemas = buildToolSchemas(ALL_DISCO_TOOLS);
+        const names = schemas.map((s) => s.function.name);
+        expect(names).toEqual([
+            'read_file',
+            'write_file',
+            'edit_file',
+            'list_files',
+            'search_content',
+            'bash',
+            'web_search',
+            'web_fetch',
+        ]);
+    });
+    it('returns subset when only some tools are enabled', () => {
+        const schemas = buildToolSchemas(['Read', 'Bash']);
+        expect(schemas).toHaveLength(2);
+        expect(schemas[0].function.name).toBe('read_file');
+        expect(schemas[1].function.name).toBe('bash');
+    });
+    it('returns empty array for empty input', () => {
+        expect(buildToolSchemas([])).toEqual([]);
+    });
+    it('silently skips unknown tool names', () => {
+        const schemas = buildToolSchemas(['Read', 'UnknownTool', 'Bash']);
+        expect(schemas).toHaveLength(2);
+        expect(schemas.map((s) => s.function.name)).toEqual(['read_file', 'bash']);
+    });
+});
+describe('OPENAI_TO_DISCO_NAME', () => {
+    it('maps every OpenAI function name back to the disco tool name', () => {
+        expect(OPENAI_TO_DISCO_NAME['read_file']).toBe('Read');
+        expect(OPENAI_TO_DISCO_NAME['write_file']).toBe('Write');
+        expect(OPENAI_TO_DISCO_NAME['edit_file']).toBe('Edit');
+        expect(OPENAI_TO_DISCO_NAME['list_files']).toBe('Glob');
+        expect(OPENAI_TO_DISCO_NAME['search_content']).toBe('Grep');
+        expect(OPENAI_TO_DISCO_NAME['bash']).toBe('Bash');
+        expect(OPENAI_TO_DISCO_NAME['web_search']).toBe('WebSearch');
+        expect(OPENAI_TO_DISCO_NAME['web_fetch']).toBe('WebFetch');
+    });
+    it('is consistent with schemas — every schema name has a reverse mapping', () => {
+        const schemas = buildToolSchemas(ALL_DISCO_TOOLS);
+        for (const schema of schemas) {
+            const openaiName = schema.function.name;
+            expect(OPENAI_TO_DISCO_NAME[openaiName]).toBeDefined();
+            // And the reverse mapping should be one of our disco tool names
+            expect(ALL_DISCO_TOOLS).toContain(OPENAI_TO_DISCO_NAME[openaiName]);
+        }
+    });
+    it('has exactly 8 entries', () => {
+        expect(Object.keys(OPENAI_TO_DISCO_NAME)).toHaveLength(8);
+    });
+});

package/dist/runtime/tools/fs-glob.js

@@ -0,0 +1,102 @@
+/**
+ * OpenAI function-calling tool: list_files
+ *
+ * Finds files matching a glob pattern within allowed directories.
+ * Uses Node 22+ fs.glob when available, falling back to recursive
+ * readdir with simple glob matching.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveAndCheck } from './path-security.js';
+export const name = 'list_files';
+const MAX_RESULTS = 1000;
+const MAX_SCAN_FILES = 5000;
+export const schema = {
+    type: 'function',
+    function: {
+        name: 'list_files',
+        description: 'Find files matching a glob pattern.',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Glob pattern to match (e.g. "**/*.ts").' },
+                path: { type: 'string', description: 'Directory to search in.' },
+            },
+            required: ['pattern'],
+            additionalProperties: false,
+        },
+    },
+};
+export async function execute(args, allowedRoots) {
+    const pattern = args.pattern;
+    const searchPath = args.path;
+    if (!pattern)
+        return { result: 'pattern is required', ok: false };
+    try {
+        const baseDir = searchPath
+            ? await resolveAndCheck(searchPath, allowedRoots)
+            : allowedRoots[0];
+        const matches = [];
+        if (typeof fs.glob === 'function') {
+            // Node 22+ fs.glob
+            const globFn = fs.glob;
+            for await (const entry of globFn(pattern, { cwd: baseDir })) {
+                matches.push(entry);
+                if (matches.length >= MAX_RESULTS)
+                    break;
+            }
+        }
+        else {
+            // Fallback: recursive readdir + simple glob matching
+            const allFiles = await collectFiles(baseDir, baseDir, MAX_SCAN_FILES);
+            for (const file of allFiles) {
+                if (simpleGlobMatch(file, pattern)) {
+                    matches.push(file);
+                    if (matches.length >= MAX_RESULTS)
+                        break;
+                }
+            }
+        }
+        if (matches.length === 0) {
+            return { result: 'No files matched', ok: true };
+        }
+        return { result: matches.join('\n'), ok: true };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { result: message, ok: false };
+    }
+}
+/** Recursively collect relative file paths. */
+async function collectFiles(dir, base, limit) {
+    const results = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (results.length >= limit)
+            break;
+        const full = path.join(dir, entry.name);
+        const rel = path.relative(base, full);
+        if (entry.isDirectory()) {
+            // Skip hidden dirs and node_modules
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const sub = await collectFiles(full, base, limit - results.length);
+            results.push(...sub);
+        }
+        else {
+            results.push(rel);
+        }
+    }
+    return results;
+}
+/** Basic glob matching: ** → any path, * → any non-sep, ? → single char. */
+export function simpleGlobMatch(file, pattern) {
+    let re = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape regex specials (except * and ?)
+        .replace(/\*\*/g, '\0DOUBLESTAR\0')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\0DOUBLESTAR\0/g, '.*')
+        .replace(/\?/g, '[^/]');
+    re = '^' + re + '$';
+    return new RegExp(re).test(file);
+}