bashkit 0.2.4 → 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 {
@@ -991,7 +1072,6 @@ function createGlobTool(sandbox, config) {
 // src/tools/grep.ts
 import { tool as tool7, zodSchema as zodSchema7 } from "ai";
 import { z as z7 } from "zod";
-import { rgPath } from "@vscode/ripgrep";
 var grepInputSchema = z7.object({
   pattern: z7.string().describe("The regular expression pattern to search for in file contents"),
   path: z7.string().optional().describe("File or directory to search in (defaults to cwd)"),
@@ -1057,7 +1137,13 @@ function createGrepTool(sandbox, config) {
         }
       }
       try {
+        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,
@@ -1106,7 +1192,7 @@ function buildRipgrepCommand(opts) {
   if (opts.type)
     flags.push(`-t ${opts.type}`);
   const flagStr = flags.join(" ");
-  return `${rgPath} ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null`;
+  return `${opts.rgPath} ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null`;
 }
 function parseFilesOutput(stdout) {
   const files = new Set;
@@ -2778,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bashkit",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Agentic coding tools for the Vercel AI SDK",
   "type": "module",
   "main": "./dist/index.js",