bashkit 0.2.4 → 0.3.1

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

@@ -1,5 +1,7 @@
 # bashkit
 
+[![npm](https://img.shields.io/npm/v/bashkit)](https://www.npmjs.com/package/bashkit)
+
 Agentic coding tools for Vercel AI SDK. Give AI agents the ability to execute code, read/write files, and perform coding tasks in a sandboxed environment.
 
 ## Overview
@@ -69,7 +71,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 +147,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 +171,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 +789,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 +879,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,91 @@ 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/ripgrep.ts
+async function getBundledRgPath() {
+  try {
+    const { rgPath } = await import("@vscode/ripgrep");
+    return rgPath;
+  } catch {
+    return;
+  }
+}
+function getBundledRgPathSync() {
+  try {
+    const { rgPath } = __require("@vscode/ripgrep");
+    return rgPath;
+  } catch {
+    return;
+  }
+}
+
+// src/sandbox/ensure-tools.ts
+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 bundledRgPath = await getBundledRgPath();
+  if (bundledRgPath) {
+    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 +141,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 +195,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 +215,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,17 +235,23 @@ 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";
 function createLocalSandbox(config = {}) {
   const workingDirectory = config.cwd || "/tmp";
+  const rgPath = getBundledRgPathSync();
   if (!existsSync(workingDirectory)) {
     mkdirSync(workingDirectory, { recursive: true });
   }
@@ -201,6 +291,7 @@ function createLocalSandbox(config = {}) {
   };
   return {
     exec,
+    rgPath,
     async readFile(path) {
       const fullPath = path.startsWith("/") ? path : `${workingDirectory}/${path}`;
       const file = Bun.file(fullPath);
@@ -239,8 +330,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 +338,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 +357,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 +415,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 +440,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 +465,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 +1092,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 +1157,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 +1212,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 +2884,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/ripgrep.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Dynamically imports @vscode/ripgrep to get the bundled binary path.
+ * Returns undefined if the package is not installed.
+ */
+export declare function getBundledRgPath(): Promise<string | undefined>;
+/**
+ * Synchronously gets the bundled ripgrep path using require.
+ * For use in synchronous contexts (e.g., LocalSandbox).
+ * Returns undefined if the package is not installed.
+ */
+export declare function getBundledRgPathSync(): string | undefined;

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/workflow.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Bashkit Workflow Integration
+ *
+ * Durable agent tools for Vercel's Workflow DevKit.
+ * Each tool execution is wrapped with "use step" for automatic
+ * durability, retries, and checkpointing.
+ *
+ * @example
+ * ```typescript
+ * import { createDurableAgentTools } from 'bashkit/workflow';
+ * import { DurableAgent } from '@workflow/ai/agent';
+ *
+ * export async function generateReport(sandboxId: string) {
+ *   "use workflow";
+ *
+ *   const { tools } = createDurableAgentTools(sandboxId);
+ *
+ *   const agent = new DurableAgent({
+ *     model: "anthropic/claude-sonnet-4-20250514",
+ *     tools,
+ *   });
+ *
+ *   await agent.run({ prompt: "Generate the report" });
+ * }
+ * ```
+ */
+import { type ToolSet } from "ai";
+import type { AgentConfig } from "./types";
+export interface DurableAgentConfig extends Omit<AgentConfig, "cache"> {
+    /**
+     * E2B API key (optional, uses ANTHROPIC_API_KEY env var by default)
+     */
+    apiKey?: string;
+}
+export interface DurableAgentToolsResult {
+    tools: ToolSet;
+}
+/**
+ * Creates durable agent tools for Workflow DevKit.
+ *
+ * Each tool execution:
+ * 1. Is wrapped with "use step" for durability
+ * 2. Reconnects to the E2B sandbox via sandboxId
+ * 3. Can retry independently on failure
+ * 4. Works with parallel tool calls (each gets own correlationId)
+ *
+ * @param sandboxId - E2B sandbox ID to reconnect to
+ * @param config - Optional tool configuration
+ */
+export declare function createDurableAgentTools(sandboxId: string, config?: DurableAgentConfig): DurableAgentToolsResult;
+export type { Sandbox } from "./sandbox/interface";
+export type { ToolConfig, AgentConfig } from "./types";

package/dist/workflow.js

@@ -0,0 +1,458 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/workflow.ts
+import { tool, zodSchema } from "ai";
+import { z } from "zod";
+
+// 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
+async function createE2BSandbox(config = {}) {
+  let sandboxId = config.sandboxId;
+  const workingDirectory = config.cwd || "/home/user";
+  const timeout = config.timeout ?? 300000;
+  const sandbox = createLazySingleton(async () => {
+    let E2BSandboxSDK;
+    try {
+      const module = await import("@e2b/code-interpreter");
+      E2BSandboxSDK = module.Sandbox;
+    } catch {
+      throw new Error("E2BSandbox requires @e2b/code-interpreter. Install with: npm install @e2b/code-interpreter");
+    }
+    let sbx;
+    if (config.sandboxId) {
+      sbx = await E2BSandboxSDK.connect(config.sandboxId);
+    } else {
+      sbx = await E2BSandboxSDK.create({
+        apiKey: config.apiKey,
+        timeoutMs: timeout,
+        metadata: config.metadata
+      });
+      sandboxId = sbx.sandboxId;
+    }
+    return sbx;
+  });
+  const exec = async (command, options) => {
+    const sbx = await sandbox.get();
+    const startTime = performance.now();
+    try {
+      const result = await sbx.commands.run(command, {
+        cwd: options?.cwd || workingDirectory,
+        timeoutMs: options?.timeout
+      });
+      const durationMs = Math.round(performance.now() - startTime);
+      return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+        durationMs,
+        interrupted: false
+      };
+    } catch (error) {
+      const durationMs = Math.round(performance.now() - startTime);
+      if (error instanceof Error && error.message.toLowerCase().includes("timeout")) {
+        return {
+          stdout: "",
+          stderr: "Command timed out",
+          exitCode: 124,
+          durationMs,
+          interrupted: true
+        };
+      }
+      if (error instanceof Error) {
+        const exitMatch = error.message.match(/exit status (\d+)/i);
+        const exitCode = exitMatch ? parseInt(exitMatch[1], 10) : 1;
+        return {
+          stdout: "",
+          stderr: error.message,
+          exitCode,
+          durationMs,
+          interrupted: false
+        };
+      }
+      throw error;
+    }
+  };
+  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) {
+        throw new Error(`Failed to read file: ${result.stderr}`);
+      }
+      return result.stdout;
+    },
+    async writeFile(path, content) {
+      const sbx = await sandbox.get();
+      await sbx.files.write(path, content);
+    },
+    async readDir(path) {
+      const result = await exec(`ls -1 "${path}"`);
+      if (result.exitCode !== 0) {
+        throw new Error(`Failed to read directory: ${result.stderr}`);
+      }
+      return result.stdout.split(`
+`).filter(Boolean);
+    },
+    async fileExists(path) {
+      const result = await exec(`test -e "${path}"`);
+      return result.exitCode === 0;
+    },
+    async isDirectory(path) {
+      const result = await exec(`test -d "${path}"`);
+      return result.exitCode === 0;
+    },
+    async destroy() {
+      try {
+        const sbx = await sandbox.get();
+        await sbx.kill();
+      } catch {}
+      sandbox.reset();
+    }
+  };
+  if (config.ensureTools !== false) {
+    await ensureSandboxTools(sandboxObj);
+  }
+  return sandboxObj;
+}
+
+// src/workflow.ts
+async function reconnectSandbox(sandboxId, apiKey) {
+  return createE2BSandbox({
+    sandboxId,
+    apiKey,
+    ensureTools: false
+  });
+}
+var readInputSchema = z.object({
+  file_path: z.string().describe("Absolute path to file or directory"),
+  offset: z.number().optional().describe("Line number to start reading from (1-indexed)"),
+  limit: z.number().optional().describe("Maximum number of lines to read")
+});
+var READ_DESCRIPTION = `Reads a file from the sandbox filesystem.
+
+Usage:
+- The file_path parameter must be an absolute path
+- By default, reads up to 500 lines from the beginning
+- Use offset and limit for large files
+- Returns line numbers starting at 1`;
+var writeInputSchema = z.object({
+  file_path: z.string().describe("Absolute path to the file to write"),
+  content: z.string().describe("Content to write to the file")
+});
+var WRITE_DESCRIPTION = `Writes content to a file in the sandbox filesystem.
+Creates parent directories if they don't exist.`;
+var editInputSchema = z.object({
+  file_path: z.string().describe("Absolute path to the file to edit"),
+  old_string: z.string().describe("The exact string to find and replace"),
+  new_string: z.string().describe("The string to replace it with")
+});
+var EDIT_DESCRIPTION = `Makes a targeted edit to a file by replacing old_string with new_string.
+The old_string must match exactly (including whitespace and indentation).`;
+var bashInputSchema = z.object({
+  command: z.string().describe("The bash command to execute"),
+  description: z.string().optional().describe("Brief description of what this command does"),
+  timeout: z.number().optional().describe("Timeout in milliseconds (default: 120000)")
+});
+var BASH_DESCRIPTION = `Executes a bash command in the sandbox.
+Use for git, npm, system commands, etc.`;
+var globInputSchema = z.object({
+  pattern: z.string().describe('Glob pattern (e.g., "**/*.ts", "src/**/*.json")'),
+  path: z.string().optional().describe("Directory to search in")
+});
+var GLOB_DESCRIPTION = `Finds files matching a glob pattern.
+Returns list of matching file paths.`;
+var grepInputSchema = z.object({
+  pattern: z.string().describe("Regex pattern to search for"),
+  path: z.string().optional().describe("File or directory to search in"),
+  glob: z.string().optional().describe('Glob pattern to filter files (e.g., "*.ts")'),
+  output_mode: z.enum(["content", "files_with_matches", "count"]).optional().describe("Output mode (default: files_with_matches)")
+});
+var GREP_DESCRIPTION = `Searches for a regex pattern in files.
+Returns matching lines with file paths and line numbers.`;
+async function executeRead(sandbox, params, config) {
+  const { file_path, offset, limit } = params;
+  if (config?.allowedPaths) {
+    const isAllowed = config.allowedPaths.some((allowed) => file_path.startsWith(allowed));
+    if (!isAllowed) {
+      return { error: `Path not allowed: ${file_path}` };
+    }
+  }
+  try {
+    const exists = await sandbox.fileExists(file_path);
+    if (!exists) {
+      return { error: `Path not found: ${file_path}` };
+    }
+    const isDir = await sandbox.isDirectory(file_path);
+    if (isDir) {
+      const entries = await sandbox.readDir(file_path);
+      return { type: "directory", entries, count: entries.length };
+    }
+    const content = await sandbox.readFile(file_path);
+    const allLines = content.split(`
+`);
+    const totalLines = allLines.length;
+    const maxLinesWithoutLimit = config?.maxFileSize || 500;
+    if (!limit && totalLines > maxLinesWithoutLimit) {
+      return {
+        error: `File is large (${totalLines} lines). Use 'offset' and 'limit' to read in chunks.`
+      };
+    }
+    const startLine = offset ? offset - 1 : 0;
+    const endLine = limit ? startLine + limit : allLines.length;
+    const selectedLines = allLines.slice(startLine, endLine);
+    const lines = selectedLines.map((line, i) => ({
+      line_number: startLine + i + 1,
+      content: line
+    }));
+    return {
+      type: "text",
+      content: selectedLines.join(`
+`),
+      lines,
+      total_lines: totalLines
+    };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : "Unknown error" };
+  }
+}
+async function executeWrite(sandbox, params) {
+  const { file_path, content } = params;
+  try {
+    const dir = file_path.split("/").slice(0, -1).join("/");
+    if (dir) {
+      await sandbox.exec(`mkdir -p "${dir}"`);
+    }
+    await sandbox.writeFile(file_path, content);
+    return { success: true, path: file_path, bytes_written: content.length };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : "Unknown error" };
+  }
+}
+async function executeEdit(sandbox, params) {
+  const { file_path, old_string, new_string } = params;
+  try {
+    const content = await sandbox.readFile(file_path);
+    if (!content.includes(old_string)) {
+      return { error: `old_string not found in file: ${file_path}` };
+    }
+    const newContent = content.replace(old_string, new_string);
+    await sandbox.writeFile(file_path, newContent);
+    return { success: true, path: file_path };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : "Unknown error" };
+  }
+}
+async function executeBash(sandbox, params, config) {
+  const { command, timeout } = params;
+  if (config?.blockedCommands) {
+    const isBlocked = config.blockedCommands.some((blocked) => command.includes(blocked));
+    if (isBlocked) {
+      return { error: `Command blocked by security policy` };
+    }
+  }
+  try {
+    const result = await sandbox.exec(command, {
+      timeout: timeout || config?.timeout || 120000
+    });
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exit_code: result.exitCode,
+      duration_ms: result.durationMs
+    };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : "Unknown error" };
+  }
+}
+async function executeGlob(sandbox, params) {
+  const { pattern, path } = params;
+  const searchPath = path || ".";
+  try {
+    const result = await sandbox.exec(`find ${searchPath} -type f -name "${pattern.replace(/\*\*/g, "*")}" 2>/dev/null | head -200`);
+    const files = result.stdout.split(`
+`).filter(Boolean);
+    return { files, count: files.length };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : "Unknown error" };
+  }
+}
+async function executeGrep(sandbox, params) {
+  const { pattern, path, glob, output_mode } = params;
+  const searchPath = path || ".";
+  const mode = output_mode || "files_with_matches";
+  try {
+    let cmd;
+    const rgPath = sandbox.rgPath || "rg";
+    if (mode === "files_with_matches") {
+      cmd = `${rgPath} -l "${pattern}" ${searchPath}`;
+    } else if (mode === "count") {
+      cmd = `${rgPath} -c "${pattern}" ${searchPath}`;
+    } else {
+      cmd = `${rgPath} -n "${pattern}" ${searchPath}`;
+    }
+    if (glob) {
+      cmd += ` --glob "${glob}"`;
+    }
+    cmd += " 2>/dev/null | head -100";
+    const result = await sandbox.exec(cmd);
+    const lines = result.stdout.split(`
+`).filter(Boolean);
+    if (mode === "files_with_matches") {
+      return { files: lines, count: lines.length };
+    } else if (mode === "count") {
+      return { matches: lines };
+    } else {
+      return { content: result.stdout, match_count: lines.length };
+    }
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : "Unknown error" };
+  }
+}
+function createDurableAgentTools(sandboxId, config) {
+  const toolsConfig = config?.tools || {};
+  const tools = {
+    Read: tool({
+      description: READ_DESCRIPTION,
+      inputSchema: zodSchema(readInputSchema),
+      execute: async (params) => {
+        "use step";
+        const sandbox = await reconnectSandbox(sandboxId, config?.apiKey);
+        return executeRead(sandbox, params, toolsConfig.Read);
+      }
+    }),
+    Write: tool({
+      description: WRITE_DESCRIPTION,
+      inputSchema: zodSchema(writeInputSchema),
+      execute: async (params) => {
+        "use step";
+        const sandbox = await reconnectSandbox(sandboxId, config?.apiKey);
+        return executeWrite(sandbox, params);
+      }
+    }),
+    Edit: tool({
+      description: EDIT_DESCRIPTION,
+      inputSchema: zodSchema(editInputSchema),
+      execute: async (params) => {
+        "use step";
+        const sandbox = await reconnectSandbox(sandboxId, config?.apiKey);
+        return executeEdit(sandbox, params);
+      }
+    }),
+    Bash: tool({
+      description: BASH_DESCRIPTION,
+      inputSchema: zodSchema(bashInputSchema),
+      execute: async (params) => {
+        "use step";
+        const sandbox = await reconnectSandbox(sandboxId, config?.apiKey);
+        return executeBash(sandbox, params, toolsConfig.Bash);
+      }
+    }),
+    Glob: tool({
+      description: GLOB_DESCRIPTION,
+      inputSchema: zodSchema(globInputSchema),
+      execute: async (params) => {
+        "use step";
+        const sandbox = await reconnectSandbox(sandboxId, config?.apiKey);
+        return executeGlob(sandbox, params);
+      }
+    }),
+    Grep: tool({
+      description: GREP_DESCRIPTION,
+      inputSchema: zodSchema(grepInputSchema),
+      execute: async (params) => {
+        "use step";
+        const sandbox = await reconnectSandbox(sandboxId, config?.apiKey);
+        return executeGrep(sandbox, params);
+      }
+    })
+  };
+  return { tools };
+}
+export {
+  createDurableAgentTools
+};

package/package.json

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

package/dist/tools/web-constants.d.ts

@@ -1,5 +0,0 @@
-/**
- * HTTP status codes that indicate a retryable error.
- * Shared between web-search and web-fetch tools.
- */
-export declare const RETRYABLE_STATUS_CODES: number[];