@ocis/myagent-cli 0.2.0

package/dist/tools/fs.js

@@ -0,0 +1,276 @@
+// ---------------------------------------------------------------------------
+// Filesystem tools: local_read, local_write, local_edit, local_ls.
+// ---------------------------------------------------------------------------
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { defineTool, optionalBoolean, optionalNumber, optionalString, requireString } from "./types.js";
+import { displayPath, resolveToolPath } from "./paths.js";
+import { isBinaryBuffer } from "./binary.js";
+import { matchGlob } from "./glob.js";
+import { generateDiff } from "./diff.js";
+const MAX_READ_BYTES = 10 * 1024 * 1024;
+const DEFAULT_READ_LINES = 2000;
+function splitLines(text) {
+    const lines = text.split("\n");
+    // A trailing newline yields a final empty element; drop it for line counts.
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+const readTool = defineTool({
+    name: "local_read",
+    description: "Read a text file with line numbers. Use offset/limit for large files. Paths are relative to the workspace root.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path (relative to the workspace)." },
+            offset: { type: "number", description: "1-indexed first line to return (default 1)." },
+            limit: { type: "number", description: `Maximum lines to return (default ${DEFAULT_READ_LINES}).` },
+        },
+        required: ["path"],
+    },
+    summarize: (args) => `read ${String(args.path ?? "")}`,
+    run: async (args, ctx) => {
+        const path = requireString(args, "path");
+        const offset = Math.max(1, Math.floor(optionalNumber(args, "offset") ?? 1));
+        const limit = Math.max(1, Math.floor(optionalNumber(args, "limit") ?? DEFAULT_READ_LINES));
+        const absolute = await resolveToolPath(path, ctx);
+        const info = await stat(absolute).catch(() => null);
+        if (!info)
+            throw new Error(`File not found: ${path}`);
+        if (info.isDirectory())
+            throw new Error(`"${path}" is a directory — use local_ls.`);
+        if (info.size > MAX_READ_BYTES) {
+            throw new Error(`File is too large (${info.size} bytes, limit ${MAX_READ_BYTES}). Use local_grep/local_shell to inspect it.`);
+        }
+        const buffer = await readFile(absolute);
+        if (isBinaryBuffer(buffer))
+            throw new Error(`"${path}" appears to be a binary file.`);
+        const lines = splitLines(buffer.toString("utf-8"));
+        const start = Math.min(offset - 1, lines.length);
+        const selected = lines.slice(start, start + limit);
+        const numbered = selected.map((line, i) => `${start + i + 1}: ${line}`).join("\n");
+        const end = start + selected.length;
+        const footer = end < lines.length ? `\n… (file has ${lines.length} lines; showed ${start + 1}–${end}; use offset/limit to see more)` : "";
+        // An out-of-range offset on a non-empty file is not an empty file — the
+        // model would conclude the file has no content.
+        const emptyNote = lines.length === 0 ? "(empty file)" : "(no lines in that range)";
+        return (numbered || emptyNote) + footer;
+    },
+});
+const writeTool = defineTool({
+    name: "local_write",
+    description: "Create or overwrite a file with the given content, creating parent directories as needed. Set append:true to append instead.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path (relative to the workspace)." },
+            content: { type: "string", description: "Full file content to write." },
+            append: { type: "boolean", description: "Append instead of overwriting (default false)." },
+        },
+        required: ["path", "content"],
+    },
+    mutating: true,
+    summarize: (args) => `write ${String(args.path ?? "")}`,
+    run: async (args, ctx) => {
+        const path = requireString(args, "path");
+        if (typeof args.content !== "string") {
+            throw new Error('Invalid arguments: "content" is required and must be a string.');
+        }
+        const content = args.content;
+        const append = optionalBoolean(args, "append") ?? false;
+        const absolute = await resolveToolPath(path, ctx);
+        const existed = await stat(absolute).then((s) => s.isFile()).catch(() => false);
+        if (append && !existed)
+            throw new Error(`Cannot append: ${path} does not exist.`);
+        if (append) {
+            // Same cap as local_read/local_edit: appending to a huge existing file
+            // would otherwise read it all into memory before the write.
+            const size = await stat(absolute).then((s) => s.size).catch(() => 0);
+            if (size > MAX_READ_BYTES) {
+                throw new Error(`Cannot append: ${path} is too large (${size} bytes, limit ${MAX_READ_BYTES}).`);
+            }
+        }
+        await mkdir(dirname(absolute), { recursive: true });
+        if (append) {
+            const previous = await readFile(absolute, "utf-8").catch(() => "");
+            await writeFile(absolute, previous + content, "utf-8");
+        }
+        else {
+            await writeFile(absolute, content, "utf-8");
+        }
+        const bytes = Buffer.byteLength(content, "utf-8");
+        const verb = append ? "Appended" : existed ? "Updated" : "Created";
+        return `${verb} ${displayPath(ctx.workspace, absolute)} (${bytes} bytes).`;
+    },
+});
+function parseEditSpecs(args) {
+    const raw = args.edits;
+    if (Array.isArray(raw)) {
+        if (raw.length === 0)
+            throw new Error("`edits` must not be empty.");
+        return raw.map((entry, index) => {
+            if (typeof entry !== "object" || entry === null)
+                throw new Error(`edits[${index}] must be an object.`);
+            const e = entry;
+            if (typeof e.old_string !== "string" || e.old_string.length === 0) {
+                throw new Error(`edits[${index}].old_string must be a non-empty string.`);
+            }
+            if (typeof e.new_string !== "string")
+                throw new Error(`edits[${index}].new_string must be a string.`);
+            return { old_string: e.old_string, new_string: e.new_string, replace_all: e.replace_all === true };
+        });
+    }
+    const oldString = requireString(args, "old_string");
+    const newString = requireString(args, "new_string");
+    if (oldString.length === 0)
+        throw new Error("`old_string` must not be empty.");
+    return [{ old_string: oldString, new_string: newString, replace_all: optionalBoolean(args, "replace_all") === true }];
+}
+/** Apply one literal edit; returns replacement count or throws a precise error. */
+function applyEdit(content, edit) {
+    const occurrences = content.split(edit.old_string).length - 1;
+    if (occurrences === 0) {
+        throw new Error("old_string not found. Make sure it matches exactly, including whitespace and indentation.");
+    }
+    if (occurrences > 1 && !edit.replace_all) {
+        throw new Error(`old_string appears ${occurrences} times. Add more surrounding context or set replace_all: true.`);
+    }
+    // split/join is a literal replacement — String.replace would interpret $&/$1
+    // sequences in new_string and silently corrupt the file.
+    return { content: content.split(edit.old_string).join(edit.new_string), replacements: edit.replace_all ? occurrences : 1 };
+}
+const editTool = defineTool({
+    name: "local_edit",
+    description: "Edit a file by exact string replacement. old_string must be unique unless replace_all is true. Multiple edits can be sent in `edits`, applied in order. Returns a unified diff.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path (relative to the workspace)." },
+            old_string: { type: "string", description: "Exact text to replace." },
+            new_string: { type: "string", description: "Replacement text." },
+            replace_all: { type: "boolean", description: "Replace every occurrence." },
+            edits: {
+                type: "array",
+                description: "Batch form: [{old_string, new_string, replace_all?}] applied in order.",
+                items: { type: "object" },
+            },
+        },
+        required: ["path"],
+    },
+    mutating: true,
+    summarize: (args) => `edit ${String(args.path ?? "")}`,
+    run: async (args, ctx) => {
+        const path = requireString(args, "path");
+        const specs = parseEditSpecs(args);
+        const absolute = await resolveToolPath(path, ctx);
+        const info = await stat(absolute).catch(() => null);
+        if (!info)
+            throw new Error(`File not found: ${path}`);
+        // Same guard as local_read: without it an edit pointed at a huge file (a
+        // log, a data dump) would read it all into memory and then amplify it
+        // through applyEdit's split/join.
+        if (info.size > MAX_READ_BYTES) {
+            throw new Error(`File is too large (${info.size} bytes, limit ${MAX_READ_BYTES}). Use local_grep/local_shell to edit it.`);
+        }
+        // Same guard as local_read: a string edit against a binary file would
+        // decode it lossily and write the re-encoded (corrupted) bytes back.
+        const buffer = await readFile(absolute).catch(() => {
+            throw new Error(`File not found: ${path}`);
+        });
+        if (isBinaryBuffer(buffer))
+            throw new Error(`"${path}" appears to be a binary file.`);
+        const original = buffer.toString("utf-8");
+        let content = original;
+        let totalReplacements = 0;
+        const errors = [];
+        for (let i = 0; i < specs.length; i++) {
+            try {
+                const result = applyEdit(content, specs[i]);
+                content = result.content;
+                totalReplacements += result.replacements;
+            }
+            catch (err) {
+                errors.push(`edit ${i + 1}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (totalReplacements === 0) {
+            throw new Error(errors.length ? `All ${specs.length} edits failed:\n${errors.join("\n")}` : "No edits applied.");
+        }
+        await writeFile(absolute, content, "utf-8");
+        const diff = generateDiff(displayPath(ctx.workspace, absolute), original, content);
+        const errorBlock = errors.length ? `\nERROR:\n${errors.join("\n")}` : "";
+        return `Applied ${totalReplacements} replacement(s) in ${displayPath(ctx.workspace, absolute)}.${errorBlock}\n${diff}`;
+    },
+});
+const lsTool = defineTool({
+    name: "local_ls",
+    description: "List a directory (non-recursive by default). Directories are suffixed with /.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Directory path (default: workspace root)." },
+            recursive: { type: "boolean", description: "Recurse into subdirectories (max depth 5, 1000 entries)." },
+            pattern: { type: "string", description: "Optional glob filter (e.g. *.ts)." },
+        },
+    },
+    summarize: (args) => `ls ${String(args.path ?? ".")}`,
+    run: async (args, ctx) => {
+        const path = optionalString(args, "path") ?? ".";
+        const recursive = optionalBoolean(args, "recursive") ?? false;
+        const pattern = optionalString(args, "pattern");
+        const absolute = await resolveToolPath(path, ctx);
+        const info = await stat(absolute).catch(() => null);
+        if (!info)
+            throw new Error(`Directory not found: ${path}`);
+        if (!info.isDirectory())
+            throw new Error(`"${path}" is not a directory — use local_read.`);
+        const maxEntries = 1000;
+        const lines = [];
+        let truncated = false;
+        async function walk(dir, depth) {
+            if (truncated)
+                return;
+            // One unreadable subdirectory (permissions, corruption) skips that
+            // subtree — same tolerance as local_find/local_grep — instead of
+            // failing the whole listing.
+            let entries;
+            try {
+                entries = await readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            entries.sort((a, b) => {
+                if (a.isDirectory() !== b.isDirectory())
+                    return a.isDirectory() ? -1 : 1;
+                return a.name.localeCompare(b.name);
+            });
+            for (const entry of entries) {
+                if (lines.length >= maxEntries) {
+                    truncated = true;
+                    return;
+                }
+                const child = join(dir, entry.name);
+                const rel = relative(absolute, child) || entry.name;
+                if (entry.isDirectory()) {
+                    // Directories are structural: always shown and always traversed when
+                    // recursive, regardless of the file pattern.
+                    lines.push(`${rel}/`);
+                    if (recursive && depth < 5)
+                        await walk(child, depth + 1);
+                    continue;
+                }
+                if (pattern && !matchGlob(pattern, rel) && !matchGlob(pattern, entry.name))
+                    continue;
+                const size = await stat(child).then((s) => s.size).catch(() => 0);
+                lines.push(recursive ? `${rel} (${size} bytes)` : `${entry.name} (${size} bytes)`);
+            }
+        }
+        await walk(absolute, 0);
+        if (lines.length === 0)
+            return "(empty directory)";
+        return lines.join("\n") + (truncated ? `\n… (truncated at ${maxEntries} entries)` : "");
+    },
+});
+export const fsTools = [readTool, writeTool, editTool, lsTool];

package/dist/tools/glob.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Match a glob against a path. Patterns without "/" match the basename;
+ * patterns with "/" match the full path (use a double-star segment to match
+ * any depth).
+ */
+export declare function matchGlob(pattern: string, path: string): boolean;

package/dist/tools/glob.js

@@ -0,0 +1,131 @@
+// ---------------------------------------------------------------------------
+// Minimal glob matching (*, ?, **, {a,b}) for find/ls/grep --include.
+// No dependency — pi-tui pulls in `marked` only, and a full glob library is
+// overkill for workspace-relative matching.
+//
+// Matching is a memoized walk over (pattern, path) — NOT a compiled RegExp.
+// The regex translation this replaced was ambiguous by construction: `**/`
+// became `(?:.*/)?`, so a run of them backtracked exponentially and a
+// model-supplied pattern like "**/".repeat(14) + "x" froze the single-threaded
+// CLI for minutes (local_find/local_ls need no approval). The walk is
+// polynomial with no backtracking blowup.
+// ---------------------------------------------------------------------------
+/**
+ * Index of the `}` closing the group opened at `open`, tracking depth — a
+ * plain indexOf would stop at a NESTED close (`{a,{b,c}}`) and leave the outer
+ * brace to be escaped into a literal, silently matching the wrong strings.
+ * Returns -1 when the group is never closed.
+ */
+function matchingBrace(pattern, open) {
+    let depth = 0;
+    for (let i = open; i < pattern.length; i++) {
+        if (pattern[i] === "{")
+            depth++;
+        else if (pattern[i] === "}" && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+/** Split on top-level commas only — a nested group's commas belong to it. */
+function splitAlternatives(body) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (ch === "{")
+            depth++;
+        else if (ch === "}")
+            depth = Math.max(0, depth - 1);
+        else if (ch === "," && depth === 0) {
+            parts.push(body.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(body.slice(start));
+    return parts;
+}
+/**
+ * Match one pattern against one path with a memoized walk. Brace groups are
+ * tried in place (each alternative is matched as `alternative + suffix`), so
+ * nested/combined braces never expand into a pattern list.
+ */
+function matchPattern(pattern, path) {
+    const n = path.length;
+    const memos = new Map();
+    function match(pat, pi, si) {
+        let memo = memos.get(pat);
+        if (!memo) {
+            memo = new Map();
+            memos.set(pat, memo);
+        }
+        const key = pi * (n + 1) + si;
+        const hit = memo.get(key);
+        if (hit !== undefined)
+            return hit;
+        let result;
+        if (pi >= pat.length) {
+            result = si >= n;
+        }
+        else {
+            const ch = pat[pi];
+            if (ch === "*") {
+                if (pat[pi + 1] === "*") {
+                    if (pat[pi + 2] === "/") {
+                        // `**/`: zero or more directories — stop now, or consume one
+                        // segment (up to and including its `/`) and continue. Consuming a
+                        // whole segment at a time is what keeps the token from stopping
+                        // mid-name (`**` + `/a` must not match "ba").
+                        result = match(pat, pi + 3, si);
+                        if (!result) {
+                            let k = si;
+                            while (k < n && path[k] !== "/")
+                                k++;
+                            result = k < n && match(pat, pi, k + 1);
+                        }
+                    }
+                    else {
+                        // `**`: anything, slashes included.
+                        result = match(pat, pi + 2, si) || (si < n && match(pat, pi, si + 1));
+                    }
+                }
+                else {
+                    // `*`: anything but a slash.
+                    result = match(pat, pi + 1, si) || (si < n && path[si] !== "/" && match(pat, pi, si + 1));
+                }
+            }
+            else if (ch === "?") {
+                result = si < n && path[si] !== "/" && match(pat, pi + 1, si + 1);
+            }
+            else if (ch === "{") {
+                const close = matchingBrace(pat, pi);
+                if (close < 0) {
+                    result = si < n && path[si] === "{" && match(pat, pi + 1, si + 1);
+                }
+                else {
+                    const suffix = pat.slice(close + 1);
+                    result = splitAlternatives(pat.slice(pi + 1, close)).some((alt) => match(alt + suffix, 0, si));
+                }
+            }
+            else {
+                result = si < n && path[si] === ch && match(pat, pi + 1, si + 1);
+            }
+        }
+        memo.set(key, result);
+        return result;
+    }
+    return match(pattern, 0, 0);
+}
+/**
+ * Match a glob against a path. Patterns without "/" match the basename;
+ * patterns with "/" match the full path (use a double-star segment to match
+ * any depth).
+ */
+export function matchGlob(pattern, path) {
+    const normalized = path.replace(/\\/g, "/");
+    if (!pattern.includes("/")) {
+        const base = normalized.slice(normalized.lastIndexOf("/") + 1);
+        return matchPattern(pattern, base);
+    }
+    return matchPattern(pattern, normalized);
+}

package/dist/tools/grep.d.ts

@@ -0,0 +1,3 @@
+import type { ToolHandler } from "./types.js";
+export declare const SKIP_DIRS: Set<string>;
+export declare const grepToolInstance: ToolHandler;

package/dist/tools/grep.js

@@ -0,0 +1,228 @@
+// ---------------------------------------------------------------------------
+// local_grep — ripgrep-first with a pure-JS fallback.
+//
+// rg's --json output is parsed; SKIP_DIRS become negative --glob patterns so
+// the same trees are excluded in both modes. Capped at 100 matches either way.
+// ---------------------------------------------------------------------------
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { defineTool, optionalString, requireString } from "./types.js";
+import { resolveToolPath } from "./paths.js";
+import { spawnProcess, which } from "../runtime.js";
+const MAX_MATCHES = 100;
+/**
+ * Wall-clock budget for the JS fallback walk. The pattern is LLM-authored and
+ * compiled with `new RegExp` — a catastrophic-backtracking pattern would
+ * otherwise pin the single-threaded process inside `pattern.test()` with
+ * no abort able to interrupt it. The budget bounds the aggregate; a single
+ * pathological match on one huge line can still overshoot, but the window
+ * shrinks from unbounded to one line.
+ */
+const JS_SEARCH_BUDGET_MS = 10_000;
+export const SKIP_DIRS = new Set([
+    "node_modules", ".git", ".svn", ".hg", "dist", "build", ".next", ".cache",
+    ".turbo", ".vercel", "coverage", "__pycache__", ".venv", "venv", ".bun", ".deno",
+]);
+function formatMatches(matches, workspace) {
+    if (matches.length === 0)
+        return "No matches found.";
+    const lines = matches.map((m) => `${relative(workspace, m.path) || m.path}:${m.line}: ${m.content}`);
+    const truncated = matches.length >= MAX_MATCHES;
+    return lines.join("\n") + (truncated ? `\n… (results capped at ${MAX_MATCHES} matches)` : "");
+}
+/**
+ * Search with ripgrep when available. Returns null when rg is unavailable.
+ *
+ * The cap is enforced HERE, on the parse: rg's `--max-count` is per FILE, so
+ * on a large tree it can still produce a huge JSON stream. The output is read
+ * incrementally and rg is killed as soon as MAX_MATCHES lands, so neither the
+ * buffer nor the child outlives the cap.
+ */
+async function searchWithRipgrep(pattern, searchPath, include, signal) {
+    const rg = which("rg");
+    if (!rg)
+        return null;
+    // --max-count bounds the per-file work rg does; the global cap is ours.
+    const args = ["--json", "--max-count", String(MAX_MATCHES), "--no-ignore", "-e", pattern];
+    if (include)
+        args.push("--glob", include);
+    for (const dir of SKIP_DIRS)
+        args.push("--glob", `!**/${dir}/**`);
+    args.push(searchPath);
+    try {
+        const proc = spawnProcess([rg, ...args], { stdout: "pipe", stderr: "ignore" });
+        const onAbort = () => { try {
+            proc.kill();
+        }
+        catch { /* gone */ } };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            const matches = [];
+            const decoder = new TextDecoder();
+            let buffer = "";
+            let capped = false;
+            const consume = (line) => {
+                if (!line)
+                    return;
+                let frame;
+                try {
+                    frame = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if (frame.type !== "match" || !frame.data?.path?.text)
+                    return;
+                matches.push({
+                    path: frame.data.path.text,
+                    line: frame.data.line_number ?? 0,
+                    content: (frame.data.lines?.text ?? "").replace(/\n$/, ""),
+                });
+                if (matches.length >= MAX_MATCHES)
+                    capped = true;
+            };
+            for await (const chunk of proc.stdout) {
+                buffer += decoder.decode(chunk, { stream: true });
+                let idx;
+                while ((idx = buffer.indexOf("\n")) >= 0) {
+                    consume(buffer.slice(0, idx));
+                    buffer = buffer.slice(idx + 1);
+                    if (capped)
+                        break;
+                }
+                if (capped)
+                    break;
+            }
+            if (capped) {
+                // Enough results: stop rg rather than draining (and buffering) the
+                // rest of a large tree's output.
+                try {
+                    proc.kill();
+                }
+                catch { /* gone */ }
+                await proc.exited;
+                return matches;
+            }
+            if (buffer)
+                consume(buffer);
+            const code = await proc.exited;
+            // rg exits 1 for "no matches" (an answer); any other non-zero exit is a
+            // failure — e.g. a JS-valid pattern (backreference, lookahead) its engine
+            // rejects — and must fall back to the JS walk rather than read as "none".
+            if (code > 1)
+                return null;
+            return matches;
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    catch {
+        return null; // fall back to the JS walk
+    }
+}
+async function searchJs(pattern, root, signal) {
+    const matches = [];
+    const deadline = Date.now() + JS_SEARCH_BUDGET_MS;
+    let timedOut = false;
+    const overBudget = () => {
+        if (Date.now() > deadline)
+            timedOut = true;
+        return timedOut;
+    };
+    async function walk(dir, depth) {
+        if (matches.length >= MAX_MATCHES || depth > 12 || signal?.aborted || overBudget())
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (matches.length >= MAX_MATCHES || signal?.aborted || overBudget())
+                return;
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith("."))
+                    continue;
+                await walk(join(dir, entry.name), depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const full = join(dir, entry.name);
+            const info = await stat(full).catch(() => null);
+            if (!info || info.size > 2 * 1024 * 1024)
+                continue;
+            let text;
+            try {
+                text = await readFile(full, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            if (text.includes("\0"))
+                continue;
+            const lines = text.split("\n");
+            for (let i = 0; i < lines.length && matches.length < MAX_MATCHES; i++) {
+                // Abort and the budget must hold inside the per-line loop too — a
+                // large file must not run to its last line after the user pressed
+                // stop or the budget expired.
+                if ((i & 31) === 0 && (signal?.aborted || overBudget()))
+                    return;
+                if (pattern.test(lines[i])) {
+                    matches.push({ path: full, line: i + 1, content: lines[i] });
+                }
+                pattern.lastIndex = 0;
+            }
+        }
+    }
+    await walk(root, 0);
+    return { matches, timedOut };
+}
+const grepTool = defineTool({
+    name: "local_grep",
+    description: "Search file contents with a regular expression (ripgrep when available). Returns file:line: content, capped at 100 matches. Common build/VCS directories are skipped.",
+    parameters: {
+        type: "object",
+        properties: {
+            pattern: { type: "string", description: "JavaScript regular expression." },
+            path: { type: "string", description: "Directory or file to search (default: workspace root)." },
+            include: { type: "string", description: "Glob filter for file names (e.g. \"*.ts\")." },
+        },
+        required: ["pattern"],
+    },
+    summarize: (args) => `grep ${String(args.pattern ?? "")}`,
+    run: async (args, ctx) => {
+        const patternText = requireString(args, "pattern");
+        let pattern;
+        try {
+            pattern = new RegExp(patternText);
+        }
+        catch (err) {
+            throw new Error(`Invalid regular expression: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const path = optionalString(args, "path") ?? ".";
+        const include = optionalString(args, "include");
+        const absolute = await resolveToolPath(path, ctx);
+        // Already stopped before the search began — no work, and no misleading
+        // "No matches found." for a search that never ran.
+        if (ctx.signal?.aborted)
+            return "[search aborted]";
+        const rgMatches = await searchWithRipgrep(patternText, absolute, include, ctx.signal);
+        if (rgMatches) {
+            // rg honors --glob; the JS fallback does not implement include — acceptable parity trade-off.
+            return formatMatches(rgMatches, ctx.workspace);
+        }
+        // A killed rg (the user pressed stop) also returns null. Falling through
+        // to the JS walk would report "No matches found." for an interrupted
+        // search — say it was aborted instead (same rule as the shell tool).
+        if (ctx.signal?.aborted)
+            return "[search aborted]";
+        const { matches, timedOut } = await searchJs(pattern, absolute, ctx.signal);
+        const body = formatMatches(matches, ctx.workspace);
+        return timedOut ? `${body}\n[search stopped: exceeded ${JS_SEARCH_BUDGET_MS}ms time budget — refine the pattern or narrow the path]` : body;
+    },
+});
+export const grepToolInstance = grepTool;

package/dist/tools/paths.d.ts

@@ -0,0 +1,27 @@
+export declare class PathOutsideWorkspaceError extends Error {
+    constructor(input: string);
+}
+export declare function isInside(root: string, candidate: string): boolean;
+/**
+ * True when the path (or a symlink along it) escapes the workspace. Lexical
+ * containment alone is not enough: a symlink inside the workspace can point
+ * outside it, so every existing prefix is realpath-checked too.
+ */
+export declare function pathEscapesWorkspace(input: string, workspace: string): Promise<boolean>;
+/**
+ * Resolve a tool-supplied path to an absolute path inside `workspace`.
+ * Throws PathOutsideWorkspaceError when the path (or a symlink along it)
+ * escapes the workspace and `allowOutside` is false.
+ */
+export declare function resolveToolPath(input: string, opts: {
+    workspace: string;
+    allowOutside: boolean;
+}): Promise<string>;
+/** Workspace-relative display path (falls back to the absolute path). */
+export declare function displayPath(workspace: string, absolute: string): string;
+/**
+ * Whether a tool request should be treated as reaching outside the workspace
+ * (and therefore asked about even in AUTO mode). Path-less tools like shell
+ * cannot be judged statically and are left to the approval mode.
+ */
+export declare function toolRequestOutsideWorkspace(name: string, args: Record<string, unknown>, workspace: string): Promise<boolean>;