@townco/agent 0.1.19 → 0.1.21

package/dist/dev-agent/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { makeHttpTransport, makeStdioTransport } from "../acp-server/index";
+// Load agent definition from JSON file
+const configPath = join(import.meta.dir, "agent.json");
+const agent = JSON.parse(readFileSync(configPath, "utf-8"));
+const transport = process.argv[2] || "stdio";
+if (transport === "http") {
+    makeHttpTransport(agent);
+}
+else if (transport === "stdio") {
+    makeStdioTransport(agent);
+}
+else {
+    console.error(`Invalid transport: ${transport}`);
+    process.exit(1);
+}

package/dist/index.js

@@ -1,19 +1,19 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { makeHttpTransport, makeStdioTransport } from "./acp-server";
-
-const exampleAgent = {
-	model: "claude-sonnet-4-5-20250929",
-	systemPrompt: "You are a helpful assistant.",
-	tools: ["todo_write", "get_weather", "web_search"],
-	mcps: [],
-};
+// Load agent definition from shared JSON file at repo root
+const configPath = join(import.meta.dir, "../../agent.json");
+const exampleAgent = JSON.parse(readFileSync(configPath, "utf-8"));
 // Parse transport type from command line argument
 const transport = process.argv[2] || "stdio";
 if (transport === "http") {
-	makeHttpTransport(exampleAgent);
-} else if (transport === "stdio") {
-	makeStdioTransport(exampleAgent);
-} else {
-	console.error(`Invalid transport: ${transport}`);
-	console.error("Usage: bun run index.ts [stdio|http]");
-	process.exit(1);
+    makeHttpTransport(exampleAgent);
+}
+else if (transport === "stdio") {
+    makeStdioTransport(exampleAgent);
+}
+else {
+    console.error(`Invalid transport: ${transport}`);
+    console.error("Usage: bun run index.ts [stdio|http]");
+    process.exit(1);
 }

package/dist/runner/agent-runner.d.ts

@@ -3,9 +3,12 @@ import { z } from "zod";
 export declare const zAgentRunnerParams: z.ZodObject<{
     systemPrompt: z.ZodNullable<z.ZodString>;
     model: z.ZodString;
-    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">]>, z.ZodObject<{
+    tools: z.ZodOptional<z.ZodArray<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>]>>>;
     mcps: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         name: z.ZodString;
@@ -20,9 +23,23 @@ export declare const zAgentRunnerParams: z.ZodObject<{
     }, z.core.$strip>]>>>;
 }, z.core.$strip>;
 export type CreateAgentRunnerParams = z.infer<typeof zAgentRunnerParams>;
-export type InvokeRequest = Omit<PromptRequest, "_meta">;
+export type InvokeRequest = Omit<PromptRequest, "_meta"> & {
+    messageId: string;
+};
+export type ExtendedSessionUpdate = SessionNotification["update"] | {
+    sessionUpdate: "tool_output";
+    toolCallId: string;
+    content?: Array<{
+        type: string;
+        [key: string]: unknown;
+    }>;
+    rawOutput?: Record<string, unknown>;
+    _meta?: {
+        messageId?: string;
+    };
+};
 /** Describes an object that can run an agent definition */
 export interface AgentRunner {
     definition: CreateAgentRunnerParams;
-    invoke(req: InvokeRequest): AsyncGenerator<SessionNotification["update"], PromptResponse, undefined>;
+    invoke(req: InvokeRequest): AsyncGenerator<ExtendedSessionUpdate, PromptResponse, undefined>;
 }

package/dist/runner/agent-runner.js

@@ -2,8 +2,8 @@ import { z } from "zod";
 import { McpConfigSchema } from "../definition";
 import { zToolType } from "./tools";
 export const zAgentRunnerParams = z.object({
-	systemPrompt: z.string().nullable(),
-	model: z.string(),
-	tools: z.array(zToolType).optional(),
-	mcps: z.array(McpConfigSchema).optional(),
+    systemPrompt: z.string().nullable(),
+    model: z.string(),
+    tools: z.array(zToolType).optional(),
+    mcps: z.array(McpConfigSchema).optional(),
 });

package/dist/runner/langchain/index.d.ts

@@ -1,15 +1,16 @@
-import type { PromptResponse, SessionNotification } from "@agentclientprotocol/sdk";
+import type { PromptResponse } from "@agentclientprotocol/sdk";
 import { type DynamicStructuredTool, type Tool } from "langchain";
-import type { AgentRunner, CreateAgentRunnerParams, InvokeRequest } from "../agent-runner";
-import type { BuiltInToolType } from "../tools";
+import type { AgentRunner, CreateAgentRunnerParams, ExtendedSessionUpdate, InvokeRequest } from "../agent-runner";
+import type { BuiltInToolType } from "../tools.js";
 type LangchainTool = DynamicStructuredTool | Tool;
 /** Lazily-loaded langchain tools */
 type LazyLangchainTool = MakeLazy<LangchainTool>;
+type LazyLangchainTools = () => readonly LangchainTool[];
 type MakeLazy<T> = T extends LangchainTool ? () => T : never;
-export declare const TOOL_REGISTRY: Record<BuiltInToolType, LangchainTool | LazyLangchainTool>;
+export declare const TOOL_REGISTRY: Record<BuiltInToolType, LangchainTool | LazyLangchainTool | LazyLangchainTools>;
 export declare class LangchainAgent implements AgentRunner {
     definition: CreateAgentRunnerParams;
     constructor(params: CreateAgentRunnerParams);
-    invoke(req: InvokeRequest): AsyncGenerator<SessionNotification["update"], PromptResponse, undefined>;
+    invoke(req: InvokeRequest): AsyncGenerator<ExtendedSessionUpdate, PromptResponse, undefined>;
 }
 export {};

package/dist/runner/langchain/index.js

@@ -1,9 +1,12 @@
 import { MultiServerMCPClient } from "@langchain/mcp-adapters";
 import { AIMessageChunk, createAgent, ToolMessage, tool, } from "langchain";
 import { z } from "zod";
-import { loadCustomToolModule } from "../tool-loader";
+import { createLogger } from "../../utils/logger.js";
+import { loadCustomToolModule, } from "../tool-loader.js";
+import { makeFilesystemTools } from "./tools/filesystem.js";
 import { todoItemSchema, todoWrite } from "./tools/todo";
 import { makeWebSearchTool } from "./tools/web_search";
+const logger = createLogger("agent-runner");
 const getWeather = tool(({ city }) => `It's always sunny in ${city}!`, {
     name: "get_weather",
     description: "Get the weather for a given city",
@@ -15,6 +18,7 @@ export const TOOL_REGISTRY = {
     todo_write: todoWrite,
     get_weather: getWeather,
     web_search: makeWebSearchTool,
+    filesystem: () => makeFilesystemTools(process.cwd()),
 };
 // ============================================================================
 // Custom tool loading
@@ -47,6 +51,7 @@ export class LangchainAgent {
         const todoWriteToolCallIds = new Set();
         // --------------------------------------------------------------------------
         // Resolve tools: built-ins (string) + custom ({ type: "custom", modulePath })
+        // + filesystem ({ type: "filesystem", working_directory? })
         // --------------------------------------------------------------------------
         const enabledTools = [];
         const toolDefs = this.definition.tools ?? [];
@@ -56,13 +61,18 @@ export class LangchainAgent {
             if (typeof t === "string") {
                 builtInNames.push(t);
             }
-            else if (t &&
-                typeof t === "object" &&
-                "type" in t &&
-                t.type === "custom" &&
-                "modulePath" in t &&
-                typeof t.modulePath === "string") {
-                customToolPaths.push(t.modulePath);
+            else if (t && typeof t === "object" && "type" in t) {
+                const type = t.type;
+                if (type === "custom" &&
+                    "modulePath" in t &&
+                    typeof t.modulePath === "string") {
+                    customToolPaths.push(t.modulePath);
+                }
+                else if (type === "filesystem") {
+                    const wd = t.working_directory ??
+                        process.cwd();
+                    enabledTools.push(...makeFilesystemTools(wd));
+                }
             }
         }
         // Built-in tools from registry
@@ -71,7 +81,18 @@ export class LangchainAgent {
             if (!entry) {
                 throw new Error(`Unknown built-in tool "${name}"`);
             }
-            enabledTools.push(typeof entry === "function" ? entry() : entry);
+            if (typeof entry === "function") {
+                const result = entry();
+                if (Array.isArray(result)) {
+                    enabledTools.push(...result);
+                }
+                else {
+                    enabledTools.push(result);
+                }
+            }
+            else {
+                enabledTools.push(entry);
+            }
         }
         // Custom tools loaded from modulePaths
         if (customToolPaths.length > 0) {
@@ -90,14 +111,13 @@ export class LangchainAgent {
             agentConfig.systemPrompt = this.definition.systemPrompt;
         }
         const agent = createAgent(agentConfig);
-        const stream = agent.stream({
-            messages: req.prompt
-                .filter((promptMsg) => promptMsg.type === "text")
-                .map((promptMsg) => ({
-                type: "human",
-                content: promptMsg.text,
-            })),
-        }, {
+        const messages = req.prompt
+            .filter((promptMsg) => promptMsg.type === "text")
+            .map((promptMsg) => ({
+            type: "human",
+            content: promptMsg.text,
+        }));
+        const stream = agent.stream({ messages }, {
             streamMode: ["updates", "messages"],
         });
         for await (const [streamMode, chunk] of await stream) {
@@ -114,6 +134,15 @@ export class LangchainAgent {
                     throw new Error(`Unhandled updates message chunk types: ${JSON.stringify(updatesMessages)}`);
                 }
                 for (const msg of updatesMessages) {
+                    // Extract token usage metadata if available
+                    const tokenUsage = msg.usage_metadata
+                        ? {
+                            inputTokens: msg.usage_metadata.input_tokens,
+                            outputTokens: msg.usage_metadata.output_tokens,
+                            totalTokens: msg.usage_metadata.total_tokens,
+                        }
+                        : undefined;
+                    logger.debug("Token usage:", tokenUsage);
                     for (const toolCall of msg.tool_calls ?? []) {
                         if (toolCall.id == null) {
                             throw new Error(`Tool call is missing id: ${JSON.stringify(toolCall)}`);
@@ -149,11 +178,15 @@ export class LangchainAgent {
                             kind: "other",
                             status: "pending",
                             rawInput: toolCall.args,
+                            ...(tokenUsage ? { tokenUsage } : {}),
+                            _meta: { messageId: req.messageId },
                         };
                         yield {
                             sessionUpdate: "tool_call_update",
                             toolCallId: toolCall.id,
                             status: "in_progress",
+                            ...(tokenUsage ? { tokenUsage } : {}),
+                            _meta: { messageId: req.messageId },
                         };
                     }
                 }
@@ -202,10 +235,17 @@ export class LangchainAgent {
                             // Skip tool_call_update for todo_write tools
                             continue;
                         }
+                        // Send status update (metadata only, no content)
                         yield {
                             sessionUpdate: "tool_call_update",
                             toolCallId: aiMessage.tool_call_id,
                             status: "completed",
+                            _meta: { messageId: req.messageId },
+                        };
+                        // Send tool output separately (via direct SSE, bypassing PostgreSQL NOTIFY)
+                        yield {
+                            sessionUpdate: "tool_output",
+                            toolCallId: aiMessage.tool_call_id,
                             content: [
                                 {
                                     type: "content",
@@ -216,6 +256,7 @@ export class LangchainAgent {
                                 },
                             ],
                             rawOutput: { content: aiMessage.content },
+                            _meta: { messageId: req.messageId },
                         };
                     }
                     else {

package/dist/runner/langchain/tools/filesystem.d.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+export declare function makeFilesystemTools(workingDirectory: string): readonly [import("langchain").DynamicStructuredTool<z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    glob: z.ZodOptional<z.ZodString>;
+    output_mode: z.ZodOptional<z.ZodEnum<{
+        content: "content";
+        files_with_matches: "files_with_matches";
+        count: "count";
+    }>>;
+    "-B": z.ZodOptional<z.ZodNumber>;
+    "-A": z.ZodOptional<z.ZodNumber>;
+    "-C": z.ZodOptional<z.ZodNumber>;
+    "-n": z.ZodOptional<z.ZodBoolean>;
+    "-i": z.ZodOptional<z.ZodBoolean>;
+    type: z.ZodOptional<z.ZodString>;
+    head_limit: z.ZodOptional<z.ZodNumber>;
+    multiline: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, {
+    pattern: string;
+    path?: string | undefined;
+    glob?: string | undefined;
+    output_mode?: "content" | "files_with_matches" | "count" | undefined;
+    "-B"?: number | undefined;
+    "-A"?: number | undefined;
+    "-C"?: number | undefined;
+    "-n"?: boolean | undefined;
+    "-i"?: boolean | undefined;
+    type?: string | undefined;
+    head_limit?: number | undefined;
+    multiline?: boolean | undefined;
+}, {
+    pattern: string;
+    path?: string | undefined;
+    glob?: string | undefined;
+    output_mode?: "content" | "files_with_matches" | "count" | undefined;
+    "-B"?: number | undefined;
+    "-A"?: number | undefined;
+    "-C"?: number | undefined;
+    "-n"?: boolean | undefined;
+    "-i"?: boolean | undefined;
+    type?: string | undefined;
+    head_limit?: number | undefined;
+    multiline?: boolean | undefined;
+}, unknown>, import("langchain").DynamicStructuredTool<z.ZodObject<{
+    file_path: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, {
+    file_path: string;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}, {
+    file_path: string;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}, unknown>, import("langchain").DynamicStructuredTool<z.ZodObject<{
+    file_path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>, {
+    file_path: string;
+    content: string;
+}, {
+    file_path: string;
+    content: string;
+}, unknown>];

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,
+]);