bashkit 0.2.3 → 0.3.0

package/AGENTS.md

@@ -34,9 +34,12 @@ Runs in isolated Firecracker microVMs on Vercel's infrastructure.
 ```typescript
 import { createAgentTools, createVercelSandbox } from "bashkit";
 
-const sandbox = createVercelSandbox({
+// Async - automatically installs ripgrep for Grep tool
+const sandbox = await createVercelSandbox({
   runtime: "node22",
   resources: { vcpus: 2 },
+  // ensureTools: true (default) - auto-setup ripgrep
+  // ensureTools: false - skip for faster startup if you don't need Grep
 });
 const { tools } = createAgentTools(sandbox);
 
@@ -51,8 +54,11 @@ Runs in E2B's cloud sandboxes. Requires `@e2b/code-interpreter` peer dependency.
 ```typescript
 import { createAgentTools, createE2BSandbox } from "bashkit";
 
-const sandbox = createE2BSandbox({
+// Async - automatically installs ripgrep for Grep tool
+const sandbox = await createE2BSandbox({
   apiKey: process.env.E2B_API_KEY,
+  // ensureTools: true (default) - auto-setup ripgrep
+  // ensureTools: false - skip for faster startup if you don't need Grep
 });
 const { tools } = createAgentTools(sandbox);
 
@@ -65,18 +71,17 @@ Cloud sandboxes (E2B, Vercel) support reconnection via the `id` property and `sa
 
 ```typescript
 // Create a new sandbox
-const sandbox = createE2BSandbox({ apiKey: process.env.E2B_API_KEY });
+const sandbox = await createE2BSandbox({ apiKey: process.env.E2B_API_KEY });
 
-// After first operation, the sandbox ID is available
-await sandbox.exec("echo hello");
+// Sandbox ID is available immediately after creation
 const sandboxId = sandbox.id; // "sbx_abc123..."
 
 // Store sandboxId in your database (e.g., chat metadata)
 await db.chat.update({ where: { id: chatId }, data: { sandboxId } });
 
-// Later: reconnect to the same sandbox
+// Later: reconnect to the same sandbox (fast - ripgrep already installed)
 const savedId = chat.sandboxId;
-const reconnected = createE2BSandbox({
+const reconnected = await createE2BSandbox({
   apiKey: process.env.E2B_API_KEY,
   sandboxId: savedId, // Reconnects instead of creating new
 });
@@ -442,7 +447,7 @@ const config = {
   },
 };
 
-const sandbox = createVercelSandbox({});
+const sandbox = await createVercelSandbox({});
 const { skills } = await setupAgentEnvironment(sandbox, config);
 
 // Use same config in prompt - stays in sync!

package/README.md

@@ -69,7 +69,8 @@ import { anthropic } from '@ai-sdk/anthropic';
 import { streamText, stepCountIs } from 'ai';
 
 // Create a Vercel sandbox (isolated Firecracker microVM)
-const sandbox = createVercelSandbox({
+// Note: async - automatically sets up ripgrep for Grep tool
+const sandbox = await createVercelSandbox({
   runtime: 'node22',
   resources: { vcpus: 2 },
 });
@@ -144,17 +145,19 @@ Runs in isolated Firecracker microVMs on Vercel's infrastructure. **Use when you
 ```typescript
 import { createVercelSandbox } from 'bashkit';
 
-const sandbox = createVercelSandbox({
+// Async - automatically installs ripgrep for Grep tool
+const sandbox = await createVercelSandbox({
   runtime: 'node22',
   resources: { vcpus: 2 },
+  // ensureTools: true (default) - auto-setup ripgrep
+  // ensureTools: false - skip for faster startup if you don't need Grep
 });
 
-// After first operation, get the sandbox ID for persistence
-await sandbox.exec('echo hello');
+// Sandbox ID available immediately after creation
 console.log(sandbox.id); // Sandbox ID for reconnection
 
-// Later: reconnect to the same sandbox
-const reconnected = createVercelSandbox({
+// Later: reconnect to the same sandbox (fast - ripgrep already installed)
+const reconnected = await createVercelSandbox({
   sandboxId: 'existing-sandbox-id',
 });
 ```
@@ -166,16 +169,18 @@ Runs in E2B's cloud sandboxes. Requires `@e2b/code-interpreter` peer dependency.
 ```typescript
 import { createE2BSandbox } from 'bashkit';
 
-const sandbox = createE2BSandbox({
+// Async - automatically installs ripgrep for Grep tool
+const sandbox = await createE2BSandbox({
   apiKey: process.env.E2B_API_KEY,
+  // ensureTools: true (default) - auto-setup ripgrep
+  // ensureTools: false - skip for faster startup if you don't need Grep
 });
 
-// After first operation, get the sandbox ID for persistence
-await sandbox.exec('echo hello');
+// Sandbox ID available immediately after creation
 console.log(sandbox.id); // "sbx_abc123..."
 
-// Later: reconnect to the same sandbox
-const reconnected = createE2BSandbox({
+// Later: reconnect to the same sandbox (fast - ripgrep already installed)
+const reconnected = await createE2BSandbox({
   apiKey: process.env.E2B_API_KEY,
   sandboxId: 'sbx_abc123...', // Reconnect to existing sandbox
 });
@@ -782,14 +787,20 @@ interface Sandbox {
   writeFile(path: string, content: string): Promise<void>;
   readDir(path: string): Promise<string[]>;
   fileExists(path: string): Promise<boolean>;
+  isDirectory(path: string): Promise<boolean>;
   destroy(): Promise<void>;
 
   // Optional: Sandbox ID for reconnection (cloud providers only)
   readonly id?: string;
+
+  // Path to ripgrep binary (set by ensureSandboxTools)
+  rgPath?: string;
 }
 ```
 
-The `id` property is available on cloud sandboxes (E2B, Vercel) after the first operation. Use it to persist the sandbox ID and reconnect later.
+The `id` property is available on cloud sandboxes (E2B, Vercel) after creation. Use it to persist the sandbox ID and reconnect later.
+
+The `rgPath` property is set by `ensureSandboxTools()` (called automatically during sandbox creation). It points to the ripgrep binary for the Grep tool. Supports x86_64 and ARM64 architectures.
 
 ### Custom Sandbox Example
 
@@ -866,9 +877,10 @@ Creates a set of agent tools bound to a sandbox instance.
 
 ### Sandbox Factories
 
-- `createLocalSandbox(config?)` - Local execution sandbox
-- `createVercelSandbox(config?)` - Vercel Firecracker sandbox
-- `createE2BSandbox(config?)` - E2B cloud sandbox
+- `createLocalSandbox(config?)` - Local execution sandbox (sync)
+- `createVercelSandbox(config?)` - Vercel Firecracker sandbox (async, auto-installs ripgrep)
+- `createE2BSandbox(config?)` - E2B cloud sandbox (async, auto-installs ripgrep)
+- `ensureSandboxTools(sandbox)` - Manually setup tools (called automatically by default)
 
 ### Workflow Tools
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type { UIMessageStreamWriter, StreamTextResult, Tool, ToolSet, LanguageModel, LanguageModelMiddleware, Output, } from "ai";
 export { anthropicPromptCacheMiddleware, anthropicPromptCacheMiddlewareV2, } from "./middleware";
 export type { E2BSandboxConfig, LocalSandboxConfig, VercelSandboxConfig, } from "./sandbox";
-export { createE2BSandbox, createLocalSandbox, createVercelSandbox, } from "./sandbox";
+export { createE2BSandbox, createLocalSandbox, createVercelSandbox, ensureSandboxTools, } from "./sandbox";
 export type { ExecOptions, ExecResult, Sandbox } from "./sandbox/interface";
 export type { AgentToolsResult, AskUserError, AskUserOutput, AskUserResponseHandler, BashError, BashOutput, EditError, EditOutput, EnterPlanModeError, EnterPlanModeOutput, ExitPlanModeError, ExitPlanModeOutput, PlanModeState, GlobError, GlobOutput, GrepContentOutput, GrepCountOutput, GrepError, GrepFilesOutput, GrepMatch, GrepOutput, ReadDirectoryOutput, ReadError, ReadOutput, ReadTextOutput, SkillError, SkillOutput, SkillToolConfig, SubagentEventData, SubagentStepEvent, SubagentTypeConfig, TaskError, TaskOutput, TaskToolConfig, TodoItem, TodoState, TodoWriteError, TodoWriteOutput, WebFetchError, WebFetchOutput, WebSearchError, WebSearchOutput, WebSearchResult, WriteError, WriteOutput, } from "./tools";
 export { createAgentTools, createAskUserTool, createBashTool, createEditTool, createEnterPlanModeTool, createExitPlanModeTool, createGlobTool, createGrepTool, createReadTool, createSkillTool, createTaskTool, createTodoWriteTool, createWebFetchTool, createWebSearchTool, createWriteTool, } from "./tools";

package/dist/index.js

@@ -49,15 +49,71 @@ var anthropicPromptCacheMiddleware = {
   specificationVersion: "v3",
   transformParams: async ({ params }) => applyCacheMarkers(params)
 };
+// src/sandbox/lazy-singleton.ts
+function createLazySingleton(factory) {
+  let promise = null;
+  return {
+    get: () => {
+      if (!promise) {
+        promise = factory();
+      }
+      return promise;
+    },
+    reset: () => {
+      promise = null;
+    }
+  };
+}
+
+// src/sandbox/ensure-tools.ts
+import { rgPath as bundledRgPath } from "@vscode/ripgrep";
+var RIPGREP_VERSION = "14.1.0";
+var ARCH_MAP = {
+  x86_64: "x86_64-unknown-linux-musl",
+  aarch64: "aarch64-unknown-linux-gnu",
+  arm64: "aarch64-unknown-linux-gnu"
+};
+async function ensureSandboxTools(sandbox) {
+  const bundledCheck = await sandbox.exec(`test -x "${bundledRgPath}" && echo found`);
+  if (bundledCheck.stdout.includes("found")) {
+    sandbox.rgPath = bundledRgPath;
+    return;
+  }
+  const tmpCheck = await sandbox.exec("test -x /tmp/rg && echo found");
+  if (tmpCheck.stdout.includes("found")) {
+    sandbox.rgPath = "/tmp/rg";
+    return;
+  }
+  const systemCheck = await sandbox.exec("which rg 2>/dev/null");
+  if (systemCheck.exitCode === 0 && systemCheck.stdout.trim()) {
+    sandbox.rgPath = systemCheck.stdout.trim();
+    return;
+  }
+  const archResult = await sandbox.exec("uname -m");
+  const arch = archResult.stdout.trim();
+  const ripgrepArch = ARCH_MAP[arch];
+  if (!ripgrepArch) {
+    throw new Error(`Unsupported architecture: ${arch}. Supported: ${Object.keys(ARCH_MAP).join(", ")}`);
+  }
+  const ripgrepUrl = `https://github.com/BurntSushi/ripgrep/releases/download/${RIPGREP_VERSION}/ripgrep-${RIPGREP_VERSION}-${ripgrepArch}.tar.gz`;
+  const tarPath = `ripgrep-${RIPGREP_VERSION}-${ripgrepArch}/rg`;
+  const installResult = await sandbox.exec(`
+    curl -sL "${ripgrepUrl}" |
+    tar xzf - -C /tmp --strip-components=1 ${tarPath} &&
+    chmod +x /tmp/rg
+  `);
+  if (installResult.exitCode !== 0) {
+    throw new Error(`Failed to install ripgrep: ${installResult.stderr}`);
+  }
+  sandbox.rgPath = "/tmp/rg";
+}
+
 // src/sandbox/e2b.ts
-function createE2BSandbox(config = {}) {
-  let sandbox = null;
+async function createE2BSandbox(config = {}) {
   let sandboxId = config.sandboxId;
   const workingDirectory = config.cwd || "/home/user";
   const timeout = config.timeout ?? 300000;
-  const ensureSandbox = async () => {
-    if (sandbox)
-      return sandbox;
+  const sandbox = createLazySingleton(async () => {
     let E2BSandboxSDK;
     try {
       const module = await import("@e2b/code-interpreter");
@@ -65,20 +121,21 @@ function createE2BSandbox(config = {}) {
     } catch {
       throw new Error("E2BSandbox requires @e2b/code-interpreter. Install with: npm install @e2b/code-interpreter");
     }
+    let sbx;
     if (config.sandboxId) {
-      sandbox = await E2BSandboxSDK.connect(config.sandboxId);
+      sbx = await E2BSandboxSDK.connect(config.sandboxId);
     } else {
-      sandbox = await E2BSandboxSDK.create({
+      sbx = await E2BSandboxSDK.create({
         apiKey: config.apiKey,
         timeoutMs: timeout,
         metadata: config.metadata
       });
-      sandboxId = sandbox.sandboxId;
+      sandboxId = sbx.sandboxId;
     }
-    return sandbox;
-  };
+    return sbx;
+  });
   const exec = async (command, options) => {
-    const sbx = await ensureSandbox();
+    const sbx = await sandbox.get();
     const startTime = performance.now();
     try {
       const result = await sbx.commands.run(command, {
@@ -118,11 +175,18 @@ function createE2BSandbox(config = {}) {
       throw error;
     }
   };
-  return {
+  let rgPath;
+  const sandboxObj = {
     exec,
     get id() {
       return sandboxId;
     },
+    get rgPath() {
+      return rgPath;
+    },
+    set rgPath(path) {
+      rgPath = path;
+    },
     async readFile(path) {
       const result = await exec(`cat "${path}"`);
       if (result.exitCode !== 0) {
@@ -131,7 +195,7 @@ function createE2BSandbox(config = {}) {
       return result.stdout;
     },
     async writeFile(path, content) {
-      const sbx = await ensureSandbox();
+      const sbx = await sandbox.get();
       await sbx.files.write(path, content);
     },
     async readDir(path) {
@@ -151,15 +215,21 @@ function createE2BSandbox(config = {}) {
       return result.exitCode === 0;
     },
     async destroy() {
-      if (sandbox) {
-        await sandbox.kill();
-        sandbox = null;
-      }
+      try {
+        const sbx = await sandbox.get();
+        await sbx.kill();
+      } catch {}
+      sandbox.reset();
     }
   };
+  if (config.ensureTools !== false) {
+    await ensureSandboxTools(sandboxObj);
+  }
+  return sandboxObj;
 }
 // src/sandbox/local.ts
 import { existsSync, mkdirSync } from "node:fs";
+import { rgPath as bundledRgPath2 } from "@vscode/ripgrep";
 function createLocalSandbox(config = {}) {
   const workingDirectory = config.cwd || "/tmp";
   if (!existsSync(workingDirectory)) {
@@ -201,6 +271,7 @@ function createLocalSandbox(config = {}) {
   };
   return {
     exec,
+    rgPath: bundledRgPath2,
     async readFile(path) {
       const fullPath = path.startsWith("/") ? path : `${workingDirectory}/${path}`;
       const file = Bun.file(fullPath);
@@ -239,8 +310,7 @@ function createLocalSandbox(config = {}) {
   };
 }
 // src/sandbox/vercel.ts
-function createVercelSandbox(config = {}) {
-  let sandbox = null;
+async function createVercelSandbox(config = {}) {
   let sandboxId = config.sandboxId;
   const workingDirectory = config.cwd || "/vercel/sandbox";
   const resolvedConfig = {
@@ -248,9 +318,7 @@ function createVercelSandbox(config = {}) {
     resources: config.resources ?? { vcpus: 2 },
     timeout: config.timeout ?? 300000
   };
-  const ensureSandbox = async () => {
-    if (sandbox)
-      return sandbox;
+  const sandbox = createLazySingleton(async () => {
     let VercelSandboxSDK;
     try {
       const module = await import("@vercel/sandbox");
@@ -269,16 +337,17 @@ function createVercelSandbox(config = {}) {
         token: config.token
       });
     }
+    let sbx;
     if (config.sandboxId) {
-      sandbox = await VercelSandboxSDK.get({ sandboxId: config.sandboxId });
+      sbx = await VercelSandboxSDK.get({ sandboxId: config.sandboxId });
     } else {
-      sandbox = await VercelSandboxSDK.create(createOptions);
+      sbx = await VercelSandboxSDK.create(createOptions);
     }
-    sandboxId = sandbox.sandboxId;
-    return sandbox;
-  };
+    sandboxId = sbx.sandboxId;
+    return sbx;
+  });
   const exec = async (command, options) => {
-    const sbx = await ensureSandbox();
+    const sbx = await sandbox.get();
     const startTime = performance.now();
     let interrupted = false;
     const abortController = new AbortController;
@@ -326,13 +395,20 @@ function createVercelSandbox(config = {}) {
       throw error;
     }
   };
-  return {
+  let rgPath;
+  const sandboxObj = {
     exec,
     get id() {
       return sandboxId;
     },
+    get rgPath() {
+      return rgPath;
+    },
+    set rgPath(path) {
+      rgPath = path;
+    },
     async readFile(path) {
-      const sbx = await ensureSandbox();
+      const sbx = await sandbox.get();
       const stream = await sbx.readFile({ path });
       if (!stream) {
         throw new Error(`File not found: ${path}`);
@@ -344,7 +420,7 @@ function createVercelSandbox(config = {}) {
       return Buffer.concat(chunks).toString("utf-8");
     },
     async writeFile(path, content) {
-      const sbx = await ensureSandbox();
+      const sbx = await sandbox.get();
       await sbx.writeFiles([
         {
           path,
@@ -369,12 +445,17 @@ function createVercelSandbox(config = {}) {
       return result.exitCode === 0;
     },
     async destroy() {
-      if (sandbox) {
-        await sandbox.stop();
-        sandbox = null;
-      }
+      try {
+        const sbx = await sandbox.get();
+        await sbx.stop();
+      } catch {}
+      sandbox.reset();
     }
   };
+  if (config.ensureTools !== false) {
+    await ensureSandboxTools(sandboxObj);
+  }
+  return sandboxObj;
 }
 // src/cache/lru.ts
 class LRUCacheStore {
@@ -1004,13 +1085,13 @@ var grepInputSchema = z7.object({
   "-C": z7.number().optional().describe("Number of lines to show before and after each match. Requires output_mode: 'content'."),
   head_limit: z7.number().optional().describe("Limit output to first N lines/entries. Works across all output modes. Defaults to 0 (unlimited)."),
   offset: z7.number().optional().describe("Skip first N lines/entries before applying head_limit. Works across all output modes. Defaults to 0."),
-  multiline: z7.boolean().optional().describe("Enable multiline mode where patterns can span lines (requires ripgrep). Default: false.")
+  multiline: z7.boolean().optional().describe("Enable multiline mode where patterns can span lines. Default: false.")
 });
-var GREP_DESCRIPTION = `A powerful content search tool with regex support. Use this instead of running grep commands directly.
+var GREP_DESCRIPTION = `A powerful content search tool built on ripgrep with regex support.
 
 **Usage:**
 - ALWAYS use Grep for search tasks. NEVER invoke \`grep\` or \`rg\` as a Bash command.
-- Supports regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
 - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
 
 **Output modes:**
@@ -1025,11 +1106,8 @@ var GREP_DESCRIPTION = `A powerful content search tool with regex support. Use t
 
 **Pagination:**
 - Use offset to skip results (useful for pagination)
-- Use head_limit to limit total results returned
-
-**Note:** Set useRipgrep: true in config for better performance and multiline support (requires ripgrep installed).`;
+- Use head_limit to limit total results returned`;
 function createGrepTool(sandbox, config) {
-  const useRipgrep = config?.useRipgrep ?? false;
   return tool7({
     description: GREP_DESCRIPTION,
     inputSchema: zodSchema7(grepInputSchema),
@@ -1044,7 +1122,6 @@ function createGrepTool(sandbox, config) {
         type,
         output_mode = "files_with_matches",
         "-i": caseInsensitive,
-        "-n": showLineNumbers = true,
         "-B": beforeContext,
         "-A": afterContext,
         "-C": context,
@@ -1059,98 +1136,32 @@ function createGrepTool(sandbox, config) {
           return { error: `Path not allowed: ${searchPath}` };
         }
       }
-      if (multiline && !useRipgrep) {
-        return {
-          error: "Multiline mode requires ripgrep. Set useRipgrep: true in config."
-        };
-      }
       try {
-        let paginationSuffix = "";
-        if (offset > 0) {
-          paginationSuffix += ` | tail -n +${offset + 1}`;
-        }
-        if (head_limit && head_limit > 0) {
-          paginationSuffix += ` | head -${head_limit}`;
-        }
-        let cmd;
-        if (useRipgrep) {
-          cmd = buildRipgrepCommand({
-            pattern,
-            searchPath,
-            output_mode,
-            caseInsensitive,
-            showLineNumbers,
-            beforeContext,
-            afterContext,
-            context,
-            glob,
-            type,
-            multiline,
-            paginationSuffix
-          });
-        } else {
-          cmd = buildGrepCommand({
-            pattern,
-            searchPath,
-            output_mode,
-            caseInsensitive,
-            showLineNumbers,
-            beforeContext,
-            afterContext,
-            context,
-            glob,
-            type,
-            paginationSuffix
-          });
+        if (!sandbox.rgPath) {
+          return {
+            error: "Ripgrep not available. Call ensureSandboxTools(sandbox) before using Grep with remote sandboxes."
+          };
         }
+        const cmd = buildRipgrepCommand({
+          rgPath: sandbox.rgPath,
+          pattern,
+          searchPath,
+          output_mode,
+          caseInsensitive,
+          beforeContext,
+          afterContext,
+          context,
+          glob,
+          type,
+          multiline
+        });
         const result = await sandbox.exec(cmd, { timeout: config?.timeout });
         if (output_mode === "files_with_matches") {
-          const files = result.stdout.split(`
-`).filter(Boolean);
-          return {
-            files,
-            count: files.length
-          };
+          return parseFilesOutput(result.stdout);
         } else if (output_mode === "count") {
-          const lines = result.stdout.split(`
-`).filter(Boolean);
-          const counts = lines.map((line) => {
-            const lastColon = line.lastIndexOf(":");
-            return {
-              file: line.slice(0, lastColon),
-              count: parseInt(line.slice(lastColon + 1), 10)
-            };
-          });
-          const total = counts.reduce((sum, c) => sum + c.count, 0);
-          return {
-            counts,
-            total
-          };
+          return parseCountOutput(result.stdout);
         } else {
-          if (!result.stdout.trim()) {
-            return {
-              matches: [],
-              total_matches: 0
-            };
-          }
-          const lines = result.stdout.split(`
-`).filter(Boolean);
-          const matches = [];
-          for (const line of lines) {
-            const colonMatch = line.match(/^(.+?):(\d+)[:|-](.*)$/);
-            if (colonMatch) {
-              const [, file, lineNum, content] = colonMatch;
-              matches.push({
-                file,
-                line_number: parseInt(lineNum, 10),
-                line: content
-              });
-            }
-          }
-          return {
-            matches,
-            total_matches: matches.length
-          };
+          return parseContentOutput(result.stdout, head_limit, offset);
         }
       } catch (error) {
         return {
@@ -1161,14 +1172,12 @@ function createGrepTool(sandbox, config) {
   });
 }
 function buildRipgrepCommand(opts) {
-  const flags = [];
+  const flags = ["--json"];
   if (opts.caseInsensitive)
     flags.push("-i");
   if (opts.multiline)
     flags.push("-U", "--multiline-dotall");
   if (opts.output_mode === "content") {
-    if (opts.showLineNumbers)
-      flags.push("-n");
     if (opts.context) {
       flags.push(`-C ${opts.context}`);
     } else {
@@ -1183,42 +1192,137 @@ function buildRipgrepCommand(opts) {
   if (opts.type)
     flags.push(`-t ${opts.type}`);
   const flagStr = flags.join(" ");
-  if (opts.output_mode === "files_with_matches") {
-    return `rg -l ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null${opts.paginationSuffix}`;
-  } else if (opts.output_mode === "count") {
-    return `rg -c ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null${opts.paginationSuffix}`;
-  } else {
-    return `rg ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null${opts.paginationSuffix}`;
+  return `${opts.rgPath} ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null`;
+}
+function parseFilesOutput(stdout) {
+  const files = new Set;
+  for (const line of stdout.split(`
+`).filter(Boolean)) {
+    try {
+      const msg = JSON.parse(line);
+      if (msg.type === "begin") {
+        const data = msg.data;
+        files.add(data.path.text);
+      }
+    } catch {}
   }
+  return {
+    files: Array.from(files),
+    count: files.size
+  };
 }
-function buildGrepCommand(opts) {
-  const flags = ["-r"];
-  if (opts.caseInsensitive)
-    flags.push("-i");
-  if (opts.output_mode === "content") {
-    if (opts.showLineNumbers)
-      flags.push("-n");
-    if (opts.context) {
-      flags.push(`-C ${opts.context}`);
-    } else {
-      if (opts.beforeContext)
-        flags.push(`-B ${opts.beforeContext}`);
-      if (opts.afterContext)
-        flags.push(`-A ${opts.afterContext}`);
+function parseCountOutput(stdout) {
+  const counts = new Map;
+  for (const line of stdout.split(`
+`).filter(Boolean)) {
+    try {
+      const msg = JSON.parse(line);
+      if (msg.type === "end") {
+        const data = msg.data;
+        counts.set(data.path.text, data.stats.matches);
+      }
+    } catch {}
+  }
+  const countsArray = Array.from(counts.entries()).map(([file, count]) => ({
+    file,
+    count
+  }));
+  const total = countsArray.reduce((sum, c) => sum + c.count, 0);
+  return {
+    counts: countsArray,
+    total
+  };
+}
+function parseContentOutput(stdout, head_limit, offset = 0) {
+  const fileData = new Map;
+  for (const line of stdout.split(`
+`).filter(Boolean)) {
+    try {
+      const msg = JSON.parse(line);
+      if (msg.type === "begin") {
+        const data = msg.data;
+        fileData.set(data.path.text, { matches: [], contexts: [] });
+      } else if (msg.type === "context") {
+        const data = msg.data;
+        const fd = fileData.get(data.path.text);
+        if (fd) {
+          fd.contexts.push({
+            line_number: data.line_number,
+            text: data.lines.text.replace(/\n$/, "")
+          });
+        }
+      } else if (msg.type === "match") {
+        const data = msg.data;
+        const fd = fileData.get(data.path.text);
+        if (fd) {
+          fd.matches.push({
+            line_number: data.line_number,
+            text: data.lines.text.replace(/\n$/, "")
+          });
+        }
+      }
+    } catch {}
+  }
+  const allMatches = [];
+  for (const [file, { matches, contexts }] of fileData) {
+    matches.sort((a, b) => a.line_number - b.line_number);
+    contexts.sort((a, b) => a.line_number - b.line_number);
+    const matchContexts = new Map;
+    for (const match of matches) {
+      matchContexts.set(match.line_number, { before: [], after: [] });
+    }
+    for (const ctx of contexts) {
+      let bestMatch = null;
+      let bestDistance = Infinity;
+      let isBefore = false;
+      for (const match of matches) {
+        const distance = Math.abs(ctx.line_number - match.line_number);
+        if (distance < bestDistance) {
+          bestDistance = distance;
+          bestMatch = match;
+          isBefore = ctx.line_number < match.line_number;
+        }
+      }
+      if (bestMatch) {
+        const mc = matchContexts.get(bestMatch.line_number);
+        if (mc) {
+          if (isBefore) {
+            mc.before.push(ctx.text);
+          } else {
+            mc.after.push(ctx.text);
+          }
+        }
+      }
+    }
+    for (const match of matches) {
+      const mc = matchContexts.get(match.line_number);
+      allMatches.push({
+        file,
+        line_number: match.line_number,
+        line: match.text,
+        before_context: mc?.before ?? [],
+        after_context: mc?.after ?? []
+      });
     }
   }
-  if (opts.glob)
-    flags.push(`--include="${opts.glob}"`);
-  if (opts.type)
-    flags.push(`--include="*.${opts.type}"`);
-  const flagStr = flags.join(" ");
-  if (opts.output_mode === "files_with_matches") {
-    return `grep -l ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null${opts.paginationSuffix}`;
-  } else if (opts.output_mode === "count") {
-    return `grep -c ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null | grep -v ':0$'${opts.paginationSuffix}`;
-  } else {
-    return `grep ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null${opts.paginationSuffix}`;
+  const grepMatches = allMatches.map((m) => ({
+    file: m.file,
+    line_number: m.line_number,
+    line: m.line,
+    before_context: m.before_context.length > 0 ? m.before_context : undefined,
+    after_context: m.after_context.length > 0 ? m.after_context : undefined
+  }));
+  let result = grepMatches;
+  if (offset > 0) {
+    result = result.slice(offset);
   }
+  if (head_limit && head_limit > 0) {
+    result = result.slice(0, head_limit);
+  }
+  return {
+    matches: result,
+    total_matches: result.length
+  };
 }
 
 // src/tools/read.ts
@@ -2760,6 +2864,7 @@ export {
   estimateTokens,
   estimateMessagesTokens,
   estimateMessageTokens,
+  ensureSandboxTools,
   discoverSkills,
   createWriteTool,
   createWebSearchTool,

package/dist/sandbox/e2b.d.ts

@@ -7,5 +7,10 @@ export interface E2BSandboxConfig {
     timeout?: number;
     cwd?: string;
     metadata?: Record<string, string>;
+    /**
+     * Ensure tools like ripgrep are available in the sandbox.
+     * Defaults to true. Set to false for faster startup if you don't need Grep.
+     */
+    ensureTools?: boolean;
 }
-export declare function createE2BSandbox(config?: E2BSandboxConfig): Sandbox;
+export declare function createE2BSandbox(config?: E2BSandboxConfig): Promise<Sandbox>;

package/dist/sandbox/ensure-tools.d.ts

@@ -0,0 +1,22 @@
+import type { Sandbox } from "./interface";
+/**
+ * Ensures required tools (ripgrep) are available in the sandbox.
+ * Call this once during sandbox setup, before using tools like Grep.
+ *
+ * - For local sandboxes: verifies bundled binary exists
+ * - For remote sandboxes: installs ripgrep to /tmp/rg if not present
+ *
+ * Supports x86_64 and ARM64 architectures.
+ *
+ * After calling, `sandbox.rgPath` will be set to the correct path.
+ *
+ * @example
+ * ```typescript
+ * const sandbox = await createVercelSandbox();
+ * await ensureSandboxTools(sandbox);
+ *
+ * const { tools } = createAgentTools(sandbox);
+ * // Grep now works
+ * ```
+ */
+export declare function ensureSandboxTools(sandbox: Sandbox): Promise<void>;

package/dist/sandbox/index.d.ts

@@ -1,4 +1,5 @@
 export { createE2BSandbox, type E2BSandboxConfig } from "./e2b";
+export { ensureSandboxTools } from "./ensure-tools";
 export type { ExecOptions, ExecResult, Sandbox } from "./interface";
 export { createLocalSandbox, type LocalSandboxConfig } from "./local";
 export { createVercelSandbox, type VercelSandboxConfig } from "./vercel";

package/dist/sandbox/interface.d.ts

@@ -25,4 +25,9 @@ export interface Sandbox {
      * - For local sandboxes: always undefined
      */
     readonly id?: string;
+    /**
+     * Path to ripgrep binary for this sandbox.
+     * Set by ensureSandboxTools() or defaults to bundled binary for local sandboxes.
+     */
+    rgPath?: string;
 }

package/dist/sandbox/lazy-singleton.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Creates a lazy singleton that initializes on first access.
+ * Safe for concurrent calls - all callers await the same promise.
+ *
+ * @example
+ * ```typescript
+ * const sandbox = createLazySingleton(async () => {
+ *   const sdk = await import("@vercel/sandbox");
+ *   return sdk.Sandbox.create({ ... });
+ * });
+ *
+ * // Safe for parallel calls:
+ * const [a, b] = await Promise.all([sandbox.get(), sandbox.get()]);
+ * // a === b (same instance)
+ *
+ * // Reset for cleanup:
+ * sandbox.reset();
+ * ```
+ */
+export declare function createLazySingleton<T>(factory: () => Promise<T>): {
+    /** Get the singleton instance, creating it if needed */
+    get: () => Promise<T>;
+    /** Reset the singleton, allowing a new instance to be created */
+    reset: () => void;
+};

package/dist/sandbox/vercel.d.ts

@@ -11,5 +11,10 @@ export interface VercelSandboxConfig {
     teamId?: string;
     projectId?: string;
     token?: string;
+    /**
+     * Ensure tools like ripgrep are available in the sandbox.
+     * Defaults to true. Set to false for faster startup if you don't need Grep.
+     */
+    ensureTools?: boolean;
 }
-export declare function createVercelSandbox(config?: VercelSandboxConfig): Sandbox;
+export declare function createVercelSandbox(config?: VercelSandboxConfig): Promise<Sandbox>;

package/dist/types.d.ts

@@ -21,10 +21,7 @@ export type ToolConfig = {
     allowedPaths?: string[];
     blockedCommands?: string[];
 } & SDKToolOptions;
-export type GrepToolConfig = ToolConfig & {
-    /** Use ripgrep (rg) instead of grep. Requires ripgrep to be installed. Default: false */
-    useRipgrep?: boolean;
-};
+export type GrepToolConfig = ToolConfig;
 /**
  * Supported web search providers.
  * Currently only 'parallel' is implemented.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bashkit",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Agentic coding tools for the Vercel AI SDK",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
   "scripts": {
     "dev": "bun run src/index.ts",
     "build": "bun run build:js && bun run build:cli && bun run build:types",
-    "build:js": "bun build src/index.ts --outdir dist --target node --format esm --external ai --external zod --external @ai-sdk/* --external @vercel/sandbox --external @e2b/code-interpreter --external parallel-web",
+    "build:js": "bun build src/index.ts --outdir dist --target node --format esm --external ai --external zod --external @ai-sdk/* --external @vercel/sandbox --external @e2b/code-interpreter --external parallel-web --external @vscode/ripgrep",
     "build:cli": "bun build src/cli/init.ts --outdir dist/cli --target node --format esm --external @clack/prompts && chmod +x dist/cli/init.js",
     "build:types": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
@@ -51,7 +51,8 @@
     "url": "https://github.com/jbreite/bashkit"
   },
   "dependencies": {
-    "@clack/prompts": "^0.7.0"
+    "@clack/prompts": "^0.7.0",
+    "@vscode/ripgrep": "^1.17.0"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.1",