Add agentic file/shell tools with approval gating, loop safety, and tool-aware model recommendations

Author: voidstackloop

app/src/agent-tools.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { readFile, writeFile, listDir, searchFiles, executeTool, runCommand } from "./agent-tools";
+
+describe("agent-tools", () => {
+    let workspace: string;
+
+    beforeEach(() => {
+        workspace = fs.mkdtempSync(path.join(os.tmpdir(), "agent-tools-test-"));
+    });
+
+    describe("path traversal protection", () => {
+        it("rejects a relative path that escapes the workspace via ..", () => {
+            expect(() => readFile(workspace, "../../etc/passwd")).toThrow(/outside the workspace/);
+        });
+
+        it("rejects an absolute path outside the workspace", () => {
+            const outsideFile = path.join(os.tmpdir(), "not-in-workspace.txt");
+            fs.writeFileSync(outsideFile, "secret");
+            expect(() => readFile(workspace, outsideFile)).toThrow(/outside the workspace/);
+        });
+
+        it("allows a path that resolves to exactly the workspace root", () => {
+            expect(() => listDir(workspace, ".")).not.toThrow();
+        });
+
+        it("allows a nested path within the workspace", () => {
+            fs.mkdirSync(path.join(workspace, "sub"));
+            fs.writeFileSync(path.join(workspace, "sub", "file.txt"), "hi");
+            expect(readFile(workspace, "sub/file.txt")).toBe("hi");
+        });
+    });
+
+    describe("readFile", () => {
+        it("reads a file's contents", () => {
+            fs.writeFileSync(path.join(workspace, "a.txt"), "hello world");
+            expect(readFile(workspace, "a.txt")).toBe("hello world");
+        });
+
+        it("refuses to read a directory as a file", () => {
+            fs.mkdirSync(path.join(workspace, "adir"));
+            expect(() => readFile(workspace, "adir")).toThrow(/directory, not a file/);
+        });
+
+        it("truncates very large files instead of returning them whole", () => {
+            fs.writeFileSync(path.join(workspace, "big.txt"), "x".repeat(200_000));
+            const result = readFile(workspace, "big.txt");
+            expect(result.length).toBeLessThan(200_000);
+            expect(result).toContain("truncated");
+        });
+    });
+
+    describe("writeFile", () => {
+        it("creates a new file with the given content", () => {
+            const result = writeFile(workspace, "new.txt", "content here");
+            expect(result.bytesWritten).toBe(12);
+            expect(fs.readFileSync(path.join(workspace, "new.txt"), "utf-8")).toBe("content here");
+        });
+
+        it("creates parent directories as needed", () => {
+            writeFile(workspace, "a/b/c.txt", "nested");
+            expect(fs.readFileSync(path.join(workspace, "a", "b", "c.txt"), "utf-8")).toBe("nested");
+        });
+
+        it("overwrites an existing file", () => {
+            writeFile(workspace, "x.txt", "first");
+            writeFile(workspace, "x.txt", "second");
+            expect(fs.readFileSync(path.join(workspace, "x.txt"), "utf-8")).toBe("second");
+        });
+    });
+
+    describe("listDir", () => {
+        it("lists files and marks directories with a trailing slash", () => {
+            fs.writeFileSync(path.join(workspace, "file.txt"), "");
+            fs.mkdirSync(path.join(workspace, "subdir"));
+            const entries = listDir(workspace, ".");
+            expect(entries).toContain("file.txt");
+            expect(entries).toContain("subdir/");
+        });
+    });
+
+    describe("searchFiles", () => {
+        it("finds matching lines with file and line number", () => {
+            fs.writeFileSync(path.join(workspace, "code.txt"), "line one\nfindme here\nline three");
+            const results = searchFiles(workspace, "findme");
+            expect(results).toEqual([{ file: "code.txt", line: 2, text: "findme here" }]);
+        });
+
+        it("skips ignored directories like node_modules", () => {
+            fs.mkdirSync(path.join(workspace, "node_modules"));
+            fs.writeFileSync(path.join(workspace, "node_modules", "lib.js"), "findme");
+            const results = searchFiles(workspace, "findme");
+            expect(results).toEqual([]);
+        });
+    });
+
+    describe("executeTool", () => {
+        it("dispatches to the right tool by name", async () => {
+            writeFile(workspace, "y.txt", "z");
+            expect(await executeTool(workspace, "read_file", { path: "y.txt" })).toBe("z");
+        });
+
+        it("throws for an unknown tool name", async () => {
+            await expect(executeTool(workspace, "delete_everything", {})).rejects.toThrow(/Unknown tool/);
+        });
+    });
+
+    describe("run_command", () => {
+        it("captures stdout and a zero exit code from a successful command", async () => {
+            const output = await executeTool(workspace, "run_command", { command: "echo hello" });
+            expect(output).toContain("Exit code: 0");
+            expect(output).toContain("hello");
+        });
+
+        it("captures a non-zero exit code", async () => {
+            const output = await executeTool(workspace, "run_command", { command: "exit 3" });
+            expect(output).toContain("Exit code: 3");
+        });
+
+        it("runs in the specified cwd within the workspace", async () => {
+            fs.mkdirSync(path.join(workspace, "sub"));
+            fs.writeFileSync(path.join(workspace, "sub", "marker.txt"), "");
+            const output = await executeTool(workspace, "run_command", { command: "ls", cwd: "sub" });
+            expect(output).toContain("marker.txt");
+        });
+
+        it("rejects a cwd that escapes the workspace", async () => {
+            await expect(runCommand(workspace, "echo hi", "../../etc")).rejects.toThrow(/outside the workspace/);
+        });
+    });
+});

app/src/agent-tools.ts

@@ -0,0 +1,210 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type { ToolDefinition } from "./providers/types";
+
+const execAsync = promisify(exec);
+
+export const AGENT_TOOLS: ToolDefinition[] = [
+    {
+        name: "read_file",
+        description: "Read the contents of a text file within the workspace.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path, relative to the workspace root." },
+            },
+            required: ["path"],
+        },
+    },
+    {
+        name: "write_file",
+        description: "Create a file or overwrite it with the given content. Creates parent directories as needed.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path, relative to the workspace root." },
+                content: { type: "string", description: "The full content to write to the file." },
+            },
+            required: ["path", "content"],
+        },
+    },
+    {
+        name: "list_dir",
+        description: "List files and subdirectories at a path within the workspace.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: 'Directory path, relative to the workspace root. Use "." for the root.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "search_files",
+        description: "Search for a text string across files in the workspace and return matching lines.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "The text to search for (plain substring match, case-sensitive)." },
+                path: { type: "string", description: 'Subdirectory to scope the search to, relative to the workspace root. Defaults to "."' },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "run_command",
+        description:
+            "Execute a shell command in the workspace (or a subdirectory of it) and return its stdout/stderr/exit code. Use for builds, tests, git, npm, etc.",
+        parameters: {
+            type: "object",
+            properties: {
+                command: { type: "string", description: "The shell command to run." },
+                cwd: { type: "string", description: 'Working directory for the command, relative to the workspace root. Defaults to "."' },
+            },
+            required: ["command"],
+        },
+    },
+];
+
+const MAX_READ_CHARS = 100_000;
+const MAX_SEARCH_RESULTS = 50;
+const MAX_LIST_ENTRIES = 500;
+const MAX_COMMAND_OUTPUT_CHARS = 50_000;
+const COMMAND_TIMEOUT_MS = 60_000;
+const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", "out", "release", "__pycache__"]);
+
+// Every tool call is confined to the chosen workspace directory — this
+// resolves the (possibly relative, possibly attacker-crafted via a prompt
+// injection in file content the model read) path and throws if it would
+// escape that directory via ../ or an absolute path elsewhere on disk.
+function resolveSafePath(workspaceRoot: string, relativePath: string): string {
+    const root = path.resolve(workspaceRoot);
+    const resolved = path.resolve(root, relativePath || ".");
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new Error(`Path "${relativePath}" is outside the workspace directory.`);
+    }
+    return resolved;
+}
+
+export function readFile(workspaceRoot: string, relativePath: string): string {
+    const target = resolveSafePath(workspaceRoot, relativePath);
+    const stat = fs.statSync(target);
+    if (stat.isDirectory()) throw new Error(`"${relativePath}" is a directory, not a file.`);
+    const content = fs.readFileSync(target, "utf-8");
+    return content.length > MAX_READ_CHARS
+        ? `${content.slice(0, MAX_READ_CHARS)}\n\n[truncated — file is ${content.length} characters]`
+        : content;
+}
+
+export function writeFile(workspaceRoot: string, relativePath: string, content: string): { bytesWritten: number } {
+    const target = resolveSafePath(workspaceRoot, relativePath);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content);
+    return { bytesWritten: Buffer.byteLength(content) };
+}
+
+export function listDir(workspaceRoot: string, relativePath: string): string[] {
+    const target = resolveSafePath(workspaceRoot, relativePath || ".");
+    const entries = fs.readdirSync(target, { withFileTypes: true });
+    return entries.slice(0, MAX_LIST_ENTRIES).map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+}
+
+export interface SearchMatch {
+    file: string;
+    line: number;
+    text: string;
+}
+
+export function searchFiles(workspaceRoot: string, query: string, relativePath = "."): SearchMatch[] {
+    const startDir = resolveSafePath(workspaceRoot, relativePath);
+    const results: SearchMatch[] = [];
+
+    function walk(dir: string): void {
+        if (results.length >= MAX_SEARCH_RESULTS) return;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (results.length >= MAX_SEARCH_RESULTS) return;
+            if (entry.name.startsWith(".") || IGNORED_DIRS.has(entry.name)) continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!entry.isFile()) continue;
+            let text: string;
+            try {
+                text = fs.readFileSync(full, "utf-8");
+            } catch {
+                continue; // binary or unreadable — skip
+            }
+            const lines = text.split("\n");
+            for (let i = 0; i < lines.length && results.length < MAX_SEARCH_RESULTS; i++) {
+                if (lines[i].includes(query)) {
+                    results.push({
+                        file: path.relative(workspaceRoot, full).split(path.sep).join("/"),
+                        line: i + 1,
+                        text: lines[i].trim().slice(0, 200),
+                    });
+                }
+            }
+        }
+    }
+
+    walk(startDir);
+    return results;
+}
+
+function truncateOutput(text: string): string {
+    return text.length > MAX_COMMAND_OUTPUT_CHARS
+        ? `${text.slice(0, MAX_COMMAND_OUTPUT_CHARS)}\n[truncated]`
+        : text;
+}
+
+function formatCommandResult(stdout: string, stderr: string, exitCode: number | null): string {
+    const parts = [`Exit code: ${exitCode}`];
+    if (stdout) parts.push(`--- stdout ---\n${truncateOutput(stdout)}`);
+    if (stderr) parts.push(`--- stderr ---\n${truncateOutput(stderr)}`);
+    return parts.join("\n\n");
+}
+
+export async function runCommand(workspaceRoot: string, command: string, relativeCwd = "."): Promise<string> {
+    const cwd = resolveSafePath(workspaceRoot, relativeCwd);
+    try {
+        const { stdout, stderr } = await execAsync(command, {
+            cwd,
+            timeout: COMMAND_TIMEOUT_MS,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        return formatCommandResult(stdout, stderr, 0);
+    } catch (err) {
+        const e = err as { stdout?: string; stderr?: string; code?: number; killed?: boolean; message: string };
+        if (e.killed) {
+            return `Command timed out after ${COMMAND_TIMEOUT_MS / 1000}s.\n\n${formatCommandResult(e.stdout ?? "", e.stderr ?? "", e.code ?? null)}`;
+        }
+        return formatCommandResult(e.stdout ?? "", e.stderr ?? e.message, e.code ?? null);
+    }
+}
+
+export async function executeTool(workspaceRoot: string, name: string, args: Record<string, unknown>): Promise<unknown> {
+    switch (name) {
+        case "read_file":
+            return readFile(workspaceRoot, String(args.path ?? ""));
+        case "write_file":
+            return writeFile(workspaceRoot, String(args.path ?? ""), String(args.content ?? ""));
+        case "list_dir":
+            return listDir(workspaceRoot, String(args.path ?? "."));
+        case "search_files":
+            return searchFiles(workspaceRoot, String(args.query ?? ""), args.path ? String(args.path) : ".");
+        case "run_command":
+            return runCommand(workspaceRoot, String(args.command ?? ""), args.cwd ? String(args.cwd) : ".");
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}