@townco/agent 0.1.19 → 0.1.20

package/dist/runner/langchain/tools/filesystem.js

@@ -0,0 +1,261 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { SandboxManager, } from "@anthropic-ai/sandbox-runtime";
+import { tool } from "langchain";
+import { z } from "zod";
+/**
+ * Lazily initialize Sandbox Runtime with write access limited to workingDirectory.
+ * Read access defaults to Sandbox Runtime's defaults (read allowed everywhere),
+ * but commands run with cwd=workingDirectory, so rg/reads are scoped naturally.
+ */
+let initialized = false;
+async function ensureSandbox(workingDirectory) {
+    if (initialized)
+        return;
+    const cfg = {
+        network: {
+            // No outbound network needed for Grep/Read/Write; block by default.
+            allowedDomains: [],
+            deniedDomains: [],
+        },
+        filesystem: {
+            // Allow writes only within the configured sandbox directory.
+            allowWrite: [workingDirectory],
+            denyWrite: [],
+            // Optional: harden reads a bit (deny common sensitive dirs)
+            denyRead: ["~/.ssh", "~/.gnupg", "/etc/ssh"],
+        },
+    };
+    await SandboxManager.initialize(cfg);
+    initialized = true;
+}
+/** Small shell-escape for args that we pass via `shell: true`. */
+function shEscape(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/** Run a command string inside the sandbox, returning { stdout, stderr, code }. */
+async function runSandboxed(cmd, cwd) {
+    const wrapped = await SandboxManager.wrapWithSandbox(cmd);
+    const child = spawn(wrapped, { shell: true, cwd });
+    const stdout = [];
+    const stderr = [];
+    child.stdout?.on("data", (d) => stdout.push(Buffer.from(d)));
+    child.stderr?.on("data", (d) => stderr.push(Buffer.from(d)));
+    const [code] = (await once(child, "exit"));
+    return {
+        stdout: Buffer.concat(stdout),
+        stderr: Buffer.concat(stderr),
+        code: code ?? 1,
+    };
+}
+/** Check that ripgrep is available inside the sandbox. Throw with a helpful note if not. */
+async function assertRipgrep(workingDirectory) {
+    const { code } = await runSandboxed("rg --version", workingDirectory);
+    if (code !== 0) {
+        throw new Error("ripgrep (rg) is required for the Grep tool. Please install it (e.g., `brew install ripgrep` on macOS or your distro package on Linux).");
+    }
+}
+/** Validate that a path is absolute */
+function assertAbsolutePath(filePath, paramName) {
+    if (!path.isAbsolute(filePath)) {
+        throw new Error(`${paramName} must be an absolute path, got: ${filePath}`);
+    }
+}
+/** Validate that a path is within the working directory bounds */
+function assertWithinWorkingDirectory(filePath, workingDirectory) {
+    const resolved = path.resolve(filePath);
+    const normalizedWd = path.resolve(workingDirectory);
+    if (!resolved.startsWith(normalizedWd + path.sep) &&
+        resolved !== normalizedWd) {
+        throw new Error(`Path ${filePath} is outside the allowed working directory ${workingDirectory}`);
+    }
+}
+export function makeFilesystemTools(workingDirectory) {
+    const resolvedWd = path.resolve(workingDirectory);
+    const grep = tool(async ({ pattern, path: searchPath, glob, output_mode, "-B": before, "-A": after, "-C": context, "-n": lineNumbers, "-i": ignoreCase, type: fileType, head_limit, multiline, }) => {
+        await ensureSandbox(resolvedWd);
+        await assertRipgrep(resolvedWd);
+        let target = resolvedWd;
+        if (searchPath) {
+            assertAbsolutePath(searchPath, "path");
+            assertWithinWorkingDirectory(searchPath, resolvedWd);
+            target = path.resolve(searchPath);
+        }
+        // Build rg command
+        const parts = ["rg"];
+        // Output format
+        const mode = output_mode ?? "files_with_matches";
+        if (mode === "files_with_matches") {
+            parts.push("--files-with-matches");
+        }
+        else if (mode === "count") {
+            parts.push("--count");
+        }
+        else if (mode === "content") {
+            // Default content mode
+            if (lineNumbers !== false) {
+                parts.push("--line-number");
+            }
+            if (context !== undefined) {
+                parts.push(`-C${context}`);
+            }
+            else {
+                if (before !== undefined)
+                    parts.push(`-B${before}`);
+                if (after !== undefined)
+                    parts.push(`-A${after}`);
+            }
+        }
+        // Search options
+        if (ignoreCase)
+            parts.push("-i");
+        if (multiline)
+            parts.push("-U", "--multiline-dotall");
+        if (fileType)
+            parts.push("--type", fileType);
+        if (glob)
+            parts.push("-g", shEscape(glob));
+        // Pattern and target
+        parts.push(shEscape(pattern), shEscape(target));
+        // Head limit (done via pipe)
+        let cmd = parts.join(" ");
+        if (head_limit !== undefined) {
+            cmd = `${cmd} | head -n ${head_limit}`;
+        }
+        const { stdout, stderr, code } = await runSandboxed(cmd, resolvedWd);
+        // rg returns non-zero on "no matches" — treat as empty results
+        if (code !== 0 && stdout.length === 0) {
+            const err = stderr.toString("utf8");
+            // If stderr looks like a real error (not just "no matches"), surface it
+            if (err && !/no such file or directory|nothing matched/i.test(err)) {
+                throw new Error(`ripgrep failed:\n${err}`);
+            }
+            return mode === "count" ? "0" : "";
+        }
+        return stdout.toString("utf8");
+    }, {
+        name: "Grep",
+        description: 'A powerful search tool built on ripgrep\n\n  Usage:\n  - ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.\n  - Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")\n  - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")\n  - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts\n  - Use Task tool for open-ended searches requiring multiple rounds\n  - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\\{\\}` to find `interface{}` in Go code)\n  - Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \\{[\\s\\S]*?field`, use `multiline: true`\n',
+        schema: z.object({
+            pattern: z
+                .string()
+                .describe("The regular expression pattern to search for in file contents"),
+            path: z
+                .string()
+                .optional()
+                .describe("File or directory to search in (rg PATH). Defaults to current working directory."),
+            glob: z
+                .string()
+                .optional()
+                .describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}") - maps to rg --glob'),
+            output_mode: z
+                .enum(["content", "files_with_matches", "count"])
+                .optional()
+                .describe('Output mode: "content" shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), "files_with_matches" shows file paths (supports head_limit), "count" shows match counts (supports head_limit). Defaults to "files_with_matches".'),
+            "-B": z
+                .number()
+                .optional()
+                .describe('Number of lines to show before each match (rg -B). Requires output_mode: "content", ignored otherwise.'),
+            "-A": z
+                .number()
+                .optional()
+                .describe('Number of lines to show after each match (rg -A). Requires output_mode: "content", ignored otherwise.'),
+            "-C": z
+                .number()
+                .optional()
+                .describe('Number of lines to show before and after each match (rg -C). Requires output_mode: "content", ignored otherwise.'),
+            "-n": z
+                .boolean()
+                .optional()
+                .describe('Show line numbers in output (rg -n). Requires output_mode: "content", ignored otherwise.'),
+            "-i": z
+                .boolean()
+                .optional()
+                .describe("Case insensitive search (rg -i)"),
+            type: z
+                .string()
+                .optional()
+                .describe("File type to search (rg --type). Common types: js, py, rust, go, java, etc. More efficient than include for standard file types."),
+            head_limit: z
+                .number()
+                .optional()
+                .describe('Limit output to first N lines/entries, equivalent to "| head -N". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). When unspecified, shows all results from ripgrep.'),
+            multiline: z
+                .boolean()
+                .optional()
+                .describe("Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall). Default: false."),
+        }),
+    });
+    const read = tool(async ({ file_path, offset, limit }) => {
+        await ensureSandbox(resolvedWd);
+        assertAbsolutePath(file_path, "file_path");
+        assertWithinWorkingDirectory(file_path, resolvedWd);
+        const target = path.resolve(file_path);
+        // Read the file using sandboxed cat
+        const cmd = `cat ${shEscape(target)}`;
+        const { stdout, stderr, code } = await runSandboxed(cmd, resolvedWd);
+        if (code !== 0) {
+            throw new Error(`Read failed for ${file_path}:\n${stderr.toString("utf8") || "Unknown error"}`);
+        }
+        // Handle offset and limit
+        let lines = stdout.toString("utf8").split(/\r?\n/);
+        if (offset !== undefined) {
+            lines = lines.slice(offset);
+        }
+        if (limit !== undefined) {
+            lines = lines.slice(0, limit);
+        }
+        // Truncate long lines
+        const truncatedLines = lines.map((line) => line.length > 2000 ? `${line.slice(0, 2000)}...` : line);
+        // Format with line numbers (cat -n style)
+        const startLine = (offset ?? 0) + 1;
+        const formatted = truncatedLines
+            .map((line, idx) => `${startLine + idx}→${line}`)
+            .join("\n");
+        return formatted;
+    }, {
+        name: "Read",
+        description: "Reads a file from the local filesystem. You can access any file directly by using this tool.\nAssume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.\n\nUsage:\n- The file_path parameter must be an absolute path, not a relative path\n- By default, it reads up to 2000 lines starting from the beginning of the file\n- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n- Any lines longer than 2000 characters will be truncated\n- Results are returned using cat -n format, with line numbers starting at 1\n- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.\n- This tool can read PDF files (.pdf). PDFs are processed page by page, extracting both text and visual content for analysis.\n- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.\n- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.\n- You can call multiple tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.\n- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.\n- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.",
+        schema: z.object({
+            file_path: z.string().describe("The absolute path to the file to read"),
+            offset: z
+                .number()
+                .optional()
+                .describe("The line number to start reading from. Only provide if the file is too large to read at once"),
+            limit: z
+                .number()
+                .optional()
+                .describe("The number of lines to read. Only provide if the file is too large to read at once."),
+        }),
+    });
+    const write = tool(async ({ file_path, content }) => {
+        await ensureSandbox(resolvedWd);
+        assertAbsolutePath(file_path, "file_path");
+        assertWithinWorkingDirectory(file_path, resolvedWd);
+        const target = path.resolve(file_path);
+        const dir = path.dirname(target);
+        // Make sure parent exists (in *parent* process, just for convenience of here-doc).
+        // This does not write file contents; the write itself happens inside the sandbox.
+        await fs.mkdir(dir, { recursive: true });
+        // Safe here-doc to avoid shell interpolation
+        const cmd = `bash -c 'mkdir -p ${shEscape(dir)} && cat > ${shEscape(target)} <<'EOF'\n` +
+            `${content}\nEOF\n'`;
+        const { stderr, code } = await runSandboxed(cmd, resolvedWd);
+        if (code !== 0) {
+            throw new Error(`Write failed for ${file_path}:\n${stderr.toString("utf8") || "Unknown error"}`);
+        }
+        return `Successfully wrote ${Buffer.byteLength(content, "utf8")} bytes to ${file_path}`;
+    }, {
+        name: "Write",
+        description: "Writes a file to the local filesystem.\n\nUsage:\n- This tool will overwrite the existing file if there is one at the provided path.\n- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.",
+        schema: z.object({
+            file_path: z
+                .string()
+                .describe("The absolute path to the file to write (must be absolute, not relative)"),
+            content: z.string().describe("The content to write to the file"),
+        }),
+    });
+    return [grep, read, write];
+}

package/dist/runner/tools.d.ts

@@ -1,10 +1,13 @@
 import { z } from "zod";
 /** Built-in tool types. */
-export declare const zBuiltInToolType: z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">]>;
+export declare const zBuiltInToolType: z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">]>;
 /** Tool type - can be a built-in tool string or custom tool object. */
-export declare const zToolType: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">]>, z.ZodObject<{
+export declare const zToolType: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">]>, z.ZodObject<{
     type: z.ZodLiteral<"custom">;
     modulePath: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"filesystem">;
+    working_directory: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>]>;
 export type ToolType = z.infer<typeof zToolType>;
 export type BuiltInToolType = z.infer<typeof zBuiltInToolType>;

package/dist/runner/tools.js

@@ -4,11 +4,21 @@ export const zBuiltInToolType = z.union([
     z.literal("todo_write"),
     z.literal("get_weather"),
     z.literal("web_search"),
+    z.literal("filesystem"),
 ]);
 /** Custom tool schema. */
 const zCustomTool = z.object({
     type: z.literal("custom"),
     modulePath: z.string(),
 });
+/** Filesystem tool schema. */
+const zFilesystemTool = z.object({
+    type: z.literal("filesystem"),
+    working_directory: z.string().optional(),
+});
 /** Tool type - can be a built-in tool string or custom tool object. */
-export const zToolType = z.union([zBuiltInToolType, zCustomTool]);
+export const zToolType = z.union([
+    zBuiltInToolType,
+    zCustomTool,
+    zFilesystemTool,
+]);

package/dist/templates/index.d.ts

@@ -5,6 +5,9 @@ export interface TemplateVars {
     tools: Array<string | {
         type: "custom";
         modulePath: string;
+    } | {
+        type: "filesystem";
+        working_directory?: string | undefined;
     }>;
     systemPrompt: string | null;
     hasWebSearch: boolean;

package/dist/templates/index.js

@@ -1,5 +1,5 @@
 export function getTemplateVars(name, definition) {
-    const tools = definition.tools || [];
+    const tools = definition.tools ?? [];
     return {
         name,
         model: definition.model,
@@ -13,6 +13,7 @@ export function generatePackageJson(vars) {
     const dependencies = {
         "@townco/agent": "^0.1.14",
         "@agentclientprotocol/sdk": "^0.5.1",
+        "@anthropic-ai/sandbox-runtime": "^0.0.2",
         "@langchain/anthropic": "^1.0.0",
         "@langchain/core": "^1.0.3",
         "@langchain/exa": "^0.1.0",
@@ -105,7 +106,15 @@ export function generateTsConfig() {
 export function generateReadme(vars) {
     const toolsList = vars.tools.length > 0
         ? vars.tools
-            .map((tool) => (typeof tool === "string" ? tool : tool.modulePath))
+            .map((tool) => {
+            if (typeof tool === "string")
+                return tool;
+            if (tool.type === "custom")
+                return tool.modulePath;
+            if (tool.type === "filesystem")
+                return `filesystem${tool.working_directory ? ` (${tool.working_directory})` : ""}`;
+            return "";
+        })
             .join(", ")
         : "None";
     const envVars = vars.hasWebSearch