agent-sh 0.4.0 → 0.6.0

package/dist/agent/tools/bash.js

@@ -0,0 +1,71 @@
+import { executeCommand } from "../../executor.js";
+export function createBashTool(opts) {
+    return {
+        name: "bash",
+        description: "Execute a bash command in an isolated subprocess. Output is captured and returned. " +
+            "Does not affect the user's shell state (use user_shell for cd, export, source). " +
+            "Do NOT use bash for file searching — use grep/glob instead. " +
+            "Do NOT use bash for reading files — use read_file instead. " +
+            "Provide a description parameter to explain what the command does.",
+        input_schema: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "The bash command to execute",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Timeout in seconds (default: 60)",
+                },
+                description: {
+                    type: "string",
+                    description: "Short description of what this command does (e.g., 'Install dependencies', 'Run test suite')",
+                },
+            },
+            required: ["command"],
+        },
+        showOutput: true,
+        modifiesFiles: true,
+        requiresPermission: true,
+        getDisplayInfo: (args) => ({
+            kind: "execute",
+            icon: "▶",
+            locations: [],
+        }),
+        async execute(args, onChunk) {
+            const command = args.command;
+            const timeout = (args.timeout ?? 60) * 1000;
+            // Let extensions intercept before execution
+            const intercepted = opts.bus.emitPipe("agent:terminal-intercept", {
+                command,
+                cwd: opts.getCwd(),
+                intercepted: false,
+                output: "",
+            });
+            if (intercepted.intercepted) {
+                return {
+                    content: intercepted.output,
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            const { session, done } = executeCommand({
+                command,
+                cwd: opts.getCwd(),
+                env: opts.getEnv(),
+                timeout,
+                onOutput: onChunk,
+            });
+            await done;
+            const content = session.truncated
+                ? `[output truncated, showing last portion]\n${session.output}`
+                : session.output;
+            return {
+                content: content || "(no output)",
+                exitCode: session.exitCode,
+                isError: session.exitCode !== 0,
+            };
+        },
+    };
+}

package/dist/agent/tools/display.d.ts

@@ -0,0 +1,13 @@
+import type { EventBus } from "../../event-bus.js";
+import type { ToolDefinition } from "../types.js";
+/**
+ * display — shows command output to the user in their live terminal.
+ *
+ * Unlike bash (scratchpad), the user sees the output directly in their shell.
+ * Unlike user_shell, this is for read-only display — no lasting side effects.
+ * The agent does NOT receive the output back.
+ */
+export declare function createDisplayTool(opts: {
+    getCwd: () => string;
+    bus: EventBus;
+}): ToolDefinition;

package/dist/agent/tools/display.js

@@ -0,0 +1,70 @@
+/**
+ * display — shows command output to the user in their live terminal.
+ *
+ * Unlike bash (scratchpad), the user sees the output directly in their shell.
+ * Unlike user_shell, this is for read-only display — no lasting side effects.
+ * The agent does NOT receive the output back.
+ */
+export function createDisplayTool(opts) {
+    return {
+        name: "display",
+        description: "Show command output to the user in their terminal. Use when the user asks to see something (cat, git log, diff, man, etc.) and you don't need to process the output yourself. Output is NOT returned to you.",
+        input_schema: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "Command to run and display output to the user",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Timeout in seconds (default: 30)",
+                },
+            },
+            required: ["command"],
+        },
+        showOutput: false,
+        modifiesFiles: false,
+        getDisplayInfo: () => ({
+            kind: "display",
+            icon: "◇",
+            locations: [],
+        }),
+        async execute(args) {
+            const command = args.command;
+            const timeoutSec = args.timeout ?? 30;
+            let result;
+            try {
+                const execPromise = opts.bus.emitPipeAsync("shell:exec-request", {
+                    command,
+                    output: "",
+                    cwd: opts.getCwd(),
+                    exitCode: null,
+                    done: false,
+                });
+                const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), timeoutSec * 1000));
+                result = await Promise.race([execPromise, timeoutPromise]);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg === "timeout") {
+                    return {
+                        content: `Command timed out after ${timeoutSec}s.`,
+                        exitCode: -1,
+                        isError: true,
+                    };
+                }
+                return { content: `Error: ${msg}`, exitCode: -1, isError: true };
+            }
+            const exitCode = result.exitCode ?? 0;
+            const isError = exitCode !== 0 && exitCode !== null;
+            return {
+                content: isError
+                    ? `Command failed with exit code ${exitCode}.`
+                    : "Output displayed to user.",
+                exitCode,
+                isError,
+            };
+        },
+    };
+}

package/dist/agent/tools/edit-file.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare function createEditFileTool(getCwd: () => string): ToolDefinition;

package/dist/agent/tools/edit-file.js

@@ -0,0 +1,148 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { computeDiff } from "../../utils/diff.js";
+/**
+ * Find the closest matching region in the file content to help diagnose
+ * why an exact match failed. Returns a hint string.
+ */
+function findClosestMatch(content, needle) {
+    const hints = [];
+    // Check if trimming whitespace would match
+    const trimmedNeedle = needle.replace(/[ \t]+$/gm, "").replace(/^[ \t]+/gm, "");
+    const trimmedContent = content.replace(/[ \t]+$/gm, "").replace(/^[ \t]+/gm, "");
+    if (trimmedContent.includes(trimmedNeedle)) {
+        hints.push(" Whitespace (indentation or trailing spaces) differs — check leading/trailing spaces on each line.");
+        return hints.join("");
+    }
+    // Check if the first line exists to narrow down the region
+    const needleLines = needle.split("\n");
+    const firstLine = needleLines[0].trim();
+    if (firstLine.length > 10) {
+        const contentLines = content.split("\n");
+        const matches = contentLines
+            .map((l, i) => ({ line: i + 1, text: l }))
+            .filter((l) => l.text.includes(firstLine));
+        if (matches.length > 0 && needleLines.length > 1) {
+            const loc = matches.map((m) => `line ${m.line}`).join(", ");
+            hints.push(` First line found at ${loc}, but subsequent lines differ. The file may have changed — use read_file to see current content around that region.`);
+            return hints.join("");
+        }
+    }
+    hints.push(" Use read_file to verify the current file contents before retrying.");
+    return hints.join("");
+}
+export function createEditFileTool(getCwd) {
+    return {
+        name: "edit_file",
+        description: "Edit a file by replacing an exact text match with new text. " +
+            "The old_text must appear exactly once unless replace_all=true. " +
+            "Include enough context to make the match unique. " +
+            "Use replace_all for variable renames or bulk string replacements.",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Absolute or relative file path",
+                },
+                old_text: {
+                    type: "string",
+                    description: "Exact text to find (must appear exactly once)",
+                },
+                new_text: {
+                    type: "string",
+                    description: "Replacement text",
+                },
+                replace_all: {
+                    type: "boolean",
+                    description: "Replace ALL occurrences instead of requiring a unique match. Useful for variable renames.",
+                },
+            },
+            required: ["path", "old_text", "new_text"],
+        },
+        showOutput: true,
+        modifiesFiles: true,
+        requiresPermission: true,
+        getDisplayInfo: (args) => ({
+            kind: "write",
+            icon: "✎",
+            locations: [{ path: args.path }],
+        }),
+        formatResult: (_args, result) => {
+            if (result.isError)
+                return {};
+            const m = result.content.match(/\((\+\d+(?:\s-\d+)?)\)/);
+            return m ? { summary: m[1] } : {};
+        },
+        async execute(args, onChunk) {
+            const filePath = args.path;
+            const oldText = args.old_text;
+            const newText = args.new_text;
+            const replaceAll = args.replace_all ?? false;
+            const absPath = path.resolve(getCwd(), filePath);
+            try {
+                const content = await fs.readFile(absPath, "utf-8");
+                // Normalize line endings for matching
+                const normalized = content.replace(/\r\n/g, "\n");
+                const normalizedOld = oldText.replace(/\r\n/g, "\n");
+                const occurrences = normalized.split(normalizedOld).length - 1;
+                if (occurrences === 0) {
+                    // Try to find the closest match to help the agent self-correct
+                    const hint = findClosestMatch(normalized, normalizedOld);
+                    return {
+                        content: `Error: old_text not found in ${filePath}.${hint}`,
+                        exitCode: 1,
+                        isError: true,
+                    };
+                }
+                if (occurrences > 1 && !replaceAll) {
+                    return {
+                        content: `Error: old_text found ${occurrences} times, must be unique. Add more surrounding context or use replace_all=true.`,
+                        exitCode: 1,
+                        isError: true,
+                    };
+                }
+                const normalizedNew = newText.replace(/\r\n/g, "\n");
+                const newContent = replaceAll
+                    ? normalized.split(normalizedOld).join(normalizedNew)
+                    : normalized.replace(normalizedOld, normalizedNew);
+                // Restore original line endings — only convert if the file was
+                // predominantly CRLF (>50% of line endings), to avoid corrupting
+                // mixed-ending files.
+                const crlfCount = (content.match(/\r\n/g) || []).length;
+                const lfCount = (content.match(/(?<!\r)\n/g) || []).length;
+                const useCRLF = crlfCount > 0 && crlfCount >= lfCount;
+                const finalContent = useCRLF
+                    ? newContent.replace(/\n/g, "\r\n")
+                    : newContent;
+                await fs.writeFile(absPath, finalContent);
+                // Compute and stream diff for display
+                const diff = computeDiff(normalized, newContent);
+                if (onChunk && diff.hunks.length > 0) {
+                    for (const hunk of diff.hunks) {
+                        for (const line of hunk.lines) {
+                            if (line.type === "added")
+                                onChunk(`+${line.text}\n`);
+                            else if (line.type === "removed")
+                                onChunk(`-${line.text}\n`);
+                            else
+                                onChunk(` ${line.text}\n`);
+                        }
+                    }
+                }
+                const stats = diff.isNewFile
+                    ? `+${diff.added}`
+                    : `+${diff.added} -${diff.removed}`;
+                return {
+                    content: `Edited ${absPath} (${stats})`,
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { content: `Error: ${msg}`, exitCode: 1, isError: true };
+            }
+        },
+    };
+}

package/dist/agent/tools/glob.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare function createGlobTool(getCwd: () => string): ToolDefinition;

package/dist/agent/tools/glob.js

@@ -0,0 +1,87 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { executeCommand } from "../../executor.js";
+export function createGlobTool(getCwd) {
+    return {
+        name: "glob",
+        description: "Find files by name pattern. Returns paths sorted by modification time (newest first). " +
+            "ALWAYS use this instead of find/ls via bash. " +
+            "Use glob to locate files, then read_file or grep to inspect contents.",
+        input_schema: {
+            type: "object",
+            properties: {
+                pattern: {
+                    type: "string",
+                    description: "Glob pattern (e.g., 'src/**/*.ts', '*.json')",
+                },
+                path: {
+                    type: "string",
+                    description: "Base directory to search (default: cwd)",
+                },
+            },
+            required: ["pattern"],
+        },
+        showOutput: false,
+        formatResult: (_args, result) => {
+            if (result.isError || result.content === "No files matched.")
+                return { summary: "0 files" };
+            const lines = result.content.split("\n").filter(l => l && !l.startsWith("["));
+            return { summary: `${lines.length} files` };
+        },
+        getDisplayInfo: (args) => ({
+            kind: "search",
+            icon: "⌕",
+            locations: args.path
+                ? [{ path: args.path }]
+                : [],
+        }),
+        async execute(args) {
+            const pattern = args.pattern;
+            const searchPath = args.path ?? ".";
+            // Use ripgrep for correct glob matching + .gitignore awareness
+            const shellEsc = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+            const parts = [
+                "rg", "--files",
+                "--glob", shellEsc(pattern),
+                shellEsc(searchPath),
+            ];
+            const { session, done } = executeCommand({
+                command: parts.join(" "),
+                cwd: getCwd(),
+                timeout: 10_000,
+            });
+            await done;
+            if (!session.output.trim()) {
+                return {
+                    content: "No files matched.",
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            const cwd = getCwd();
+            const files = session.output.trim().split("\n");
+            // Sort by modification time (newest first)
+            const withMtime = await Promise.all(files.map(async (f) => {
+                try {
+                    const abs = path.resolve(cwd, f);
+                    const stat = await fs.stat(abs);
+                    return { file: f, mtime: stat.mtimeMs };
+                }
+                catch {
+                    return { file: f, mtime: 0 };
+                }
+            }));
+            withMtime.sort((a, b) => b.mtime - a.mtime);
+            const sorted = withMtime.slice(0, 200).map((e) => e.file);
+            const truncated = files.length > 200;
+            const suffix = truncated
+                ? `\n[Results capped at 200 files, ${files.length - 200} more matched]`
+                : "";
+            return {
+                content: sorted.join("\n") + suffix,
+                exitCode: 0,
+                isError: false,
+            };
+        },
+    };
+}

package/dist/agent/tools/grep.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare function createGrepTool(getCwd: () => string): ToolDefinition;

package/dist/agent/tools/grep.js

@@ -0,0 +1,168 @@
+import { executeCommand } from "../../executor.js";
+export function createGrepTool(getCwd) {
+    return {
+        name: "grep",
+        description: "Search file contents using ripgrep. ALWAYS use this instead of running grep/rg via bash. " +
+            "Supports three output modes: " +
+            "'files_with_matches' (default, returns file paths only — use this to find which files contain a pattern), " +
+            "'content' (matching lines with optional context_before/context_after), and " +
+            "'count' (match counts per file). " +
+            "Use head_limit and offset for pagination.",
+        input_schema: {
+            type: "object",
+            properties: {
+                pattern: {
+                    type: "string",
+                    description: "Regex pattern to search for",
+                },
+                path: {
+                    type: "string",
+                    description: "Directory or file to search (default: cwd)",
+                },
+                include: {
+                    type: "string",
+                    description: "Glob pattern for files to include (e.g., '*.ts')",
+                },
+                output_mode: {
+                    type: "string",
+                    enum: ["files_with_matches", "content", "count"],
+                    description: "Output mode: 'files_with_matches' (default, file paths only), " +
+                        "'content' (matching lines), 'count' (match counts per file)",
+                },
+                case_insensitive: {
+                    type: "boolean",
+                    description: "Case insensitive search (default: false)",
+                },
+                context_before: {
+                    type: "number",
+                    description: "Lines to show before each match (content mode only)",
+                },
+                context_after: {
+                    type: "number",
+                    description: "Lines to show after each match (content mode only)",
+                },
+                head_limit: {
+                    type: "number",
+                    description: "Max lines/entries to return (default: 200 for files_with_matches, 150 for content/count). Pass 0 for unlimited.",
+                },
+                offset: {
+                    type: "number",
+                    description: "Skip first N lines/entries before applying head_limit. Use with head_limit for pagination.",
+                },
+            },
+            required: ["pattern"],
+        },
+        showOutput: false,
+        formatResult: (args, result) => {
+            if (result.isError || result.content === "No matches found.")
+                return { summary: "0 matches" };
+            const lines = result.content.split("\n").filter(Boolean);
+            // Strip pagination info line from count
+            const resultLines = lines.filter(l => !l.startsWith("[Showing "));
+            const mode = args.output_mode ?? "files_with_matches";
+            if (mode === "files_with_matches") {
+                return { summary: `${resultLines.length} files` };
+            }
+            if (mode === "count") {
+                const total = resultLines.reduce((sum, l) => sum + (parseInt(l.split(":").pop() ?? "0", 10) || 0), 0);
+                return { summary: `${total} matches` };
+            }
+            return { summary: `${resultLines.length} lines` };
+        },
+        getDisplayInfo: (args) => ({
+            kind: "search",
+            icon: "⌕",
+            locations: args.path
+                ? [{ path: args.path }]
+                : [],
+        }),
+        async execute(args) {
+            const pattern = args.pattern;
+            const searchPath = args.path ?? ".";
+            const include = args.include;
+            const mode = args.output_mode ?? "files_with_matches";
+            const caseInsensitive = args.case_insensitive;
+            const contextBefore = args.context_before;
+            const contextAfter = args.context_after;
+            const headLimit = args.head_limit;
+            const offset = args.offset ?? 0;
+            const shellEsc = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+            const parts = ["rg", "--color=never"];
+            // Mode-specific flags
+            if (mode === "files_with_matches") {
+                parts.push("--files-with-matches");
+            }
+            else if (mode === "count") {
+                parts.push("--count");
+            }
+            else {
+                // content mode
+                parts.push("--line-number", "--no-heading");
+                if (contextBefore != null && contextBefore > 0) {
+                    parts.push(`-B${contextBefore}`);
+                }
+                if (contextAfter != null && contextAfter > 0) {
+                    parts.push(`-A${contextAfter}`);
+                }
+                // If neither -A nor -B specified, use --max-count to limit per-file
+                if (contextBefore == null && contextAfter == null) {
+                    parts.push("--max-count=50");
+                }
+            }
+            if (caseInsensitive) {
+                parts.push("-i");
+            }
+            if (include) {
+                parts.push("--glob", shellEsc(include));
+            }
+            parts.push("-e", shellEsc(pattern), shellEsc(searchPath));
+            const { session, done } = executeCommand({
+                command: parts.join(" "),
+                cwd: getCwd(),
+                timeout: 10_000,
+                maxOutputBytes: 64 * 1024,
+            });
+            await done;
+            if (session.exitCode === 1 && !session.output.trim()) {
+                return {
+                    content: "No matches found.",
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            let output = session.output;
+            // Cap individual line lengths to 500 chars to prevent minified/base64 flood
+            if (mode === "content") {
+                const MAX_LINE_LEN = 500;
+                output = output
+                    .split("\n")
+                    .map((line) => line.length > MAX_LINE_LEN
+                    ? line.slice(0, MAX_LINE_LEN) + "… [truncated]"
+                    : line)
+                    .join("\n");
+            }
+            // Apply pagination (offset + head_limit)
+            const defaultLimit = mode === "files_with_matches" ? 200 : 150;
+            const limit = headLimit === 0 ? Infinity : (headLimit ?? defaultLimit);
+            const lines = output.split("\n");
+            const total = lines.length;
+            // Apply offset then limit
+            const sliced = lines.slice(offset, offset + limit);
+            const paginated = sliced.join("\n");
+            const parts2 = [];
+            if (paginated)
+                parts2.push(paginated);
+            // Show pagination info when offset is used or results were truncated
+            if (offset > 0 || offset + limit < total) {
+                const shown = sliced.length;
+                const remaining = Math.max(0, total - offset - shown);
+                parts2.push(`\n[Showing ${shown} results (offset=${offset}, limit=${limit === Infinity ? "unlimited" : limit})${remaining > 0 ? `, ${remaining} more available` : ""}]`);
+            }
+            return {
+                content: parts2.join("\n") || "No matches found.",
+                exitCode: 0,
+                isError: false,
+            };
+        },
+    };
+}

package/dist/agent/tools/list-skills.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare function createListSkillsTool(getCwd: () => string): ToolDefinition;

package/dist/agent/tools/list-skills.js

@@ -0,0 +1,28 @@
+import { discoverSkills } from "../skills.js";
+export function createListSkillsTool(getCwd) {
+    return {
+        name: "list_skills",
+        description: "List available skills. Use read_file on a skill's path to load its full instructions.",
+        input_schema: {
+            type: "object",
+            properties: {},
+        },
+        showOutput: false,
+        async execute() {
+            const skills = discoverSkills(getCwd());
+            if (skills.length === 0) {
+                return {
+                    content: "No skills found.",
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            const lines = skills.map((s) => `${s.name}  ${s.filePath}\n  ${s.description}`);
+            return {
+                content: lines.join("\n\n"),
+                exitCode: 0,
+                isError: false,
+            };
+        },
+    };
+}

package/dist/agent/tools/ls.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare function createLsTool(getCwd: () => string): ToolDefinition;