agent-sh 0.15.0 → 0.15.2

package/src/agent/tool-registry.ts

@@ -0,0 +1,66 @@
+import type { ToolDefinition, ToolResult, ToolSchemaView } from "./types.js";
+import type { ChatCompletionTool } from "./llm-client.js";
+import type { HandlerFunctions } from "../utils/handler-registry.js";
+import { registerReadOnlyTool, unregisterReadOnlyTool } from "./nuclear-form.js";
+
+/**
+ * Registry for agent tools. Execution is routed through the named-handler
+ * registry under `tool:<name>` so extensions can `advise` a tool without
+ * owning it; duplicate `register` calls throw rather than silently evict.
+ */
+export class ToolRegistry {
+  private tools = new Map<string, ToolDefinition>();
+
+  constructor(private handlers: HandlerFunctions) {}
+
+  register(tool: ToolDefinition): void {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool "${tool.name}" already registered. Use ctx.agent.adviseTool() to wrap it.`);
+    }
+    this.tools.set(tool.name, tool);
+    this.handlers.define(`tool:${tool.name}`, tool.execute.bind(tool));
+    this.handlers.define(`tool:${tool.name}:schema`, (): ToolSchemaView => ({
+      description: tool.description,
+      parameters: tool.input_schema,
+    }));
+    if (tool.readOnly) registerReadOnlyTool(tool.name);
+    else unregisterReadOnlyTool(tool.name);
+  }
+
+  unregister(name: string): void {
+    this.tools.delete(name);
+    unregisterReadOnlyTool(name);
+    // Handler entry intentionally retained so external advisors survive a
+    // reload of the tool's owner and reattach when the name re-registers.
+  }
+
+  get(name: string): ToolDefinition | undefined {
+    return this.tools.get(name);
+  }
+
+  all(): ToolDefinition[] {
+    return Array.from(this.tools.values());
+  }
+
+  allView(): ToolDefinition[] {
+    return this.all().map((t) => {
+      const view = this.handlers.call(`tool:${t.name}:schema`) as ToolSchemaView;
+      return { ...t, description: view.description, input_schema: view.parameters };
+    });
+  }
+
+  call(name: string, ...args: Parameters<ToolDefinition["execute"]>): Promise<ToolResult> {
+    return this.handlers.call(`tool:${name}`, ...args) as Promise<ToolResult>;
+  }
+
+  toAPITools(): ChatCompletionTool[] {
+    return this.allView().map((t) => ({
+      type: "function" as const,
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.input_schema,
+      },
+    }));
+  }
+}

package/src/agent/tools/bash.ts

@@ -0,0 +1,95 @@
+import { executeCommand, killSession } from "../../utils/executor.js";
+import type { EventBus } from "../../core/event-bus.js";
+import type { ToolDefinition } from "../types.js";
+
+export function createBashTool(opts: {
+  getCwd: () => string;
+  getEnv: () => Record<string, string>;
+  bus: EventBus;
+}): ToolDefinition {
+  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. " +
+      "cwd is set to the working directory from the shell context. " +
+      "Keep commands focused; avoid long-running or blocking processes. " +
+      "Always check the returned exit code before treating output as success. " +
+      "Do NOT use bash for file searching — use grep/glob instead. " +
+      "Do NOT use bash for reading files — use read_file instead.",
+    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,
+
+    getDisplayInfo: (args) => ({
+      kind: "execute",
+      icon: "▶",
+      locations: [],
+    }),
+
+    async execute(args, onChunk, ctx) {
+      const command = args.command as string;
+      const timeout = ((args.timeout as number) ?? 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,
+      });
+
+      const onAbort = () => killSession(session);
+      ctx?.signal?.addEventListener("abort", onAbort, { once: true });
+      try {
+        await done;
+      } finally {
+        ctx?.signal?.removeEventListener("abort", onAbort);
+      }
+
+      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/src/agent/tools/edit-file.ts

@@ -0,0 +1,154 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ToolDefinition } from "../types.js";
+import { computeEditDiff } from "../../utils/diff.js";
+import { expandHome } from "./expand-home.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: string, needle: string): string {
+  const hints: string[] = [];
+
+  // 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: () => string): ToolDefinition {
+  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,
+
+    getDisplayInfo: (args) => ({
+      kind: "write",
+      icon: "✎",
+      locations: [{ path: args.path as string }],
+    }),
+
+    async execute(args) {
+      const filePath = expandHome(args.path as string);
+      const oldText = args.old_text as string;
+      const newText = args.new_text as string;
+      const replaceAll = (args.replace_all as boolean) ?? 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");
+        // Use split/join for literal replacement everywhere. String.replace()
+        // treats dollar-sign patterns in the replacement as special substitution
+        // variables, which corrupts file content containing regex escape sequences.
+        const newContent = normalized.split(normalizedOld).join(normalizedNew);
+        // Note: when !replaceAll, we rely on the occurrence check above to ensure
+        // normalizedOld appears exactly once, so split/join replaces only that one.
+
+        // 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);
+
+        const diff = computeEditDiff(normalized, normalizedOld, normalizedNew, replaceAll);
+        const stats = diff.isNewFile ? `+${diff.added}` : `+${diff.added} -${diff.removed}`;
+        return {
+          content: `Edited ${absPath} (${stats})`,
+          exitCode: 0,
+          isError: false,
+          display: {
+            summary: stats,
+            body: { kind: "diff", diff, filePath: absPath },
+          },
+        };
+      } catch (err) {
+        const msg =
+          err instanceof Error ? err.message : String(err);
+        return { content: `Error: ${msg}`, exitCode: 1, isError: true };
+      }
+    },
+  };
+}

package/src/agent/tools/expand-home.ts

@@ -0,0 +1,7 @@
+import * as os from "node:os";
+
+export function expandHome(p: string): string {
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/")) return os.homedir() + p.slice(1);
+  return p;
+}

package/src/agent/tools/glob.ts

@@ -0,0 +1,108 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { executeArgv } from "../../utils/executor.js";
+import { resolveRgPath } from "../../utils/ripgrep-path.js";
+import { contentText, type ToolDefinition } from "../types.js";
+import { expandHome } from "./expand-home.js";
+
+export function createGlobTool(getCwd: () => string): ToolDefinition {
+  return {
+    name: "glob",
+    description:
+      "Use this when you know a FILENAME or PATH SHAPE (e.g. `**/*.ts`, `src/**/*.md`, `package.json`). " +
+      "Returns matching file paths sorted by modification time (newest first). " +
+      "This does NOT search file contents — use `grep` for that. " +
+      "ALWAYS use this instead of find/ls via bash. " +
+      "Typical flow: `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'). Do NOT put `~` or absolute prefixes here — pass the directory in `path` instead.",
+        },
+        path: {
+          type: "string",
+          description: "Base directory to search (default: cwd). Supports `~` and `~/...` for the home directory.",
+        },
+      },
+      required: ["pattern"],
+    },
+
+    showOutput: false,
+
+    formatResult: (_args, result) => {
+      const text = contentText(result.content);
+      if (result.isError || text === "No files matched.") return { summary: "0 files" };
+      const lines = text.split("\n").filter(l => l && !l.startsWith("["));
+      return { summary: `${lines.length} files` };
+    },
+
+    getDisplayInfo: (args) => ({
+      kind: "search",
+      icon: "⌕",
+      locations: args.path
+        ? [{ path: args.path as string }]
+        : [],
+    }),
+
+    async execute(args) {
+      const pattern = args.pattern as string;
+      const searchPath = expandHome((args.path as string) ?? ".");
+
+      // Use ripgrep for correct glob matching + .gitignore awareness
+      const { session, done } = executeArgv({
+        file: resolveRgPath(),
+        args: ["--files", "--glob", pattern, searchPath],
+        cwd: getCwd(),
+        timeout: 10_000,
+      });
+      await done;
+
+      if (session.spawnFailed) {
+        return {
+          content: "ripgrep not available — the bundled binary failed to load and `rg` is not on PATH. Reinstall agent-sh, or install ripgrep manually (https://github.com/BurntSushi/ripgrep#installation).",
+          exitCode: 1,
+          isError: true,
+        };
+      }
+
+      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/src/agent/tools/grep.ts

@@ -0,0 +1,228 @@
+import { executeArgv } from "../../utils/executor.js";
+import { resolveRgPath } from "../../utils/ripgrep-path.js";
+import { contentText, type ToolDefinition } from "../types.js";
+import { expandHome } from "./expand-home.js";
+
+export function createGrepTool(getCwd: () => string): ToolDefinition {
+  return {
+    name: "grep",
+    description:
+      "Use this when you know something INSIDE the file (text, identifier, regex). " +
+      "To find files by filename alone, use `glob` instead. " +
+      "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 (NOT a glob — `*.md` is invalid here; use `.*\\.md` for regex, or use the glob tool to find files by name). For filename filtering while searching content, use the `include` parameter.",
+        },
+        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) => {
+      const text = contentText(result.content);
+      if (result.isError || text === "No matches found.") return { summary: "0 matches" };
+      const lines = text.split("\n").filter(Boolean);
+      // Strip pagination info line from count
+      const resultLines = lines.filter(l => !l.startsWith("[Showing "));
+      const mode = (args.output_mode as string) ?? "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 as string }]
+        : [],
+    }),
+
+    async execute(args) {
+      const pattern = args.pattern as string;
+      const searchPath = expandHome((args.path as string) ?? ".");
+      const include = args.include as string | undefined;
+      const mode = (args.output_mode as string) ?? "files_with_matches";
+      const caseInsensitive = args.case_insensitive as boolean | undefined;
+      const contextBefore = args.context_before as number | undefined;
+      const contextAfter = args.context_after as number | undefined;
+      const headLimit = args.head_limit as number | undefined;
+      const offset = (args.offset as number) ?? 0;
+
+      const rgArgs: string[] = ["--color=never"];
+
+      // Mode-specific flags
+      if (mode === "files_with_matches") {
+        rgArgs.push("--files-with-matches");
+      } else if (mode === "count") {
+        rgArgs.push("--count");
+      } else {
+        // content mode
+        rgArgs.push("--line-number", "--no-heading");
+        if (contextBefore != null && contextBefore > 0) {
+          rgArgs.push(`-B${contextBefore}`);
+        }
+        if (contextAfter != null && contextAfter > 0) {
+          rgArgs.push(`-A${contextAfter}`);
+        }
+        // If neither -A nor -B specified, use --max-count to limit per-file
+        if (contextBefore == null && contextAfter == null) {
+          rgArgs.push("--max-count=50");
+        }
+      }
+
+      if (caseInsensitive) {
+        rgArgs.push("-i");
+      }
+      if (include) {
+        rgArgs.push("--glob", include);
+      }
+      rgArgs.push("-e", pattern, searchPath);
+
+      const { session, done } = executeArgv({
+        file: resolveRgPath(),
+        args: rgArgs,
+        cwd: getCwd(),
+        timeout: 10_000,
+        maxOutputBytes: 64 * 1024,
+      });
+      await done;
+
+      if (session.spawnFailed) {
+        return {
+          content: "ripgrep not available — the bundled binary failed to load and `rg` is not on PATH. Reinstall agent-sh, or install ripgrep manually (https://github.com/BurntSushi/ripgrep#installation).",
+          exitCode: 1,
+          isError: true,
+        };
+      }
+
+      if (session.exitCode === 1 && !session.output.trim()) {
+        // If the pattern looks like a filename (e.g. "SKILL.md", "package.json"),
+        // the agent probably meant to find files by name, not search inside them.
+        // Surface a redirect hint instead of a silent zero.
+        const looksLikeFilename =
+          /^[A-Za-z0-9_.\-*/]+\.[A-Za-z0-9]{1,6}$/.test(pattern) &&
+          !/[\\()\[\]|^$+{}]/.test(pattern);
+        const hint = looksLikeFilename
+          ? ` Hint: "${pattern}" looks like a filename. grep searches file *contents* — to find files by name, use the \`glob\` tool instead.`
+          : "";
+        return {
+          content: `No matches found.${hint}`,
+          exitCode: 0,
+          isError: false,
+        };
+      }
+
+      // exit code >= 2 is a ripgrep error (invalid regex, unreadable path, etc).
+      // Surface it as an error so the model retries with a correct pattern
+      // rather than treating "no useful output" as a successful no-match.
+      if (session.exitCode != null && session.exitCode >= 2) {
+        const looksLikeGlob = /^[*?]|\*\./.test(pattern) && !/[\\()\[\]|^$]/.test(pattern);
+        const hint = looksLikeGlob
+          ? " Hint: `*.md` is a glob, not a regex — use the glob tool to find files by name, or pass `include: \"*.md\"` here to filter files while searching content for a regex pattern."
+          : "";
+        return {
+          content: `grep failed (rg exit ${session.exitCode}): ${session.output.trim() || "no output"}${hint}`,
+          exitCode: session.exitCode,
+          isError: true,
+        };
+      }
+
+      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: string[] = [];
+      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,
+      };
+    },
+  };
+}