bashkit 0.2.1 → 0.2.3

package/AGENTS.md

@@ -21,9 +21,9 @@ bun add bashkit ai @ai-sdk/anthropic
 Runs commands directly on the local machine. Use for development/testing only.
 
 ```typescript
-import { createAgentTools, LocalSandbox } from "bashkit";
+import { createAgentTools, createLocalSandbox } from "bashkit";
 
-const sandbox = new LocalSandbox("/tmp/workspace");
+const sandbox = createLocalSandbox({ cwd: "/tmp/workspace" });
 const { tools } = createAgentTools(sandbox);
 ```
 
@@ -32,9 +32,9 @@ const { tools } = createAgentTools(sandbox);
 Runs in isolated Firecracker microVMs on Vercel's infrastructure.
 
 ```typescript
-import { createAgentTools, VercelSandbox } from "bashkit";
+import { createAgentTools, createVercelSandbox } from "bashkit";
 
-const sandbox = new VercelSandbox({
+const sandbox = createVercelSandbox({
   runtime: "node22",
   resources: { vcpus: 2 },
 });
@@ -44,6 +44,49 @@ const { tools } = createAgentTools(sandbox);
 await sandbox.destroy();
 ```
 
+### E2BSandbox (Production)
+
+Runs in E2B's cloud sandboxes. Requires `@e2b/code-interpreter` peer dependency.
+
+```typescript
+import { createAgentTools, createE2BSandbox } from "bashkit";
+
+const sandbox = createE2BSandbox({
+  apiKey: process.env.E2B_API_KEY,
+});
+const { tools } = createAgentTools(sandbox);
+
+await sandbox.destroy();
+```
+
+### Sandbox Reconnection (Cloud Sandboxes)
+
+Cloud sandboxes (E2B, Vercel) support reconnection via the `id` property and `sandboxId` config:
+
+```typescript
+// Create a new sandbox
+const sandbox = createE2BSandbox({ apiKey: process.env.E2B_API_KEY });
+
+// After first operation, the sandbox ID is available
+await sandbox.exec("echo hello");
+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
+const savedId = chat.sandboxId;
+const reconnected = createE2BSandbox({
+  apiKey: process.env.E2B_API_KEY,
+  sandboxId: savedId, // Reconnects instead of creating new
+});
+```
+
+This is useful for:
+- Reusing sandboxes across multiple requests in the same conversation
+- Persisting sandbox state between server restarts
+- Reducing sandbox creation overhead
+
 ## Available Tools
 
 ### Default Tools (always included)
@@ -89,11 +132,11 @@ import { generateText, wrapLanguageModel, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import {
   createAgentTools,
-  LocalSandbox,
+  createLocalSandbox,
   anthropicPromptCacheMiddleware,
 } from "bashkit";
 
-const sandbox = new LocalSandbox("/tmp/workspace");
+const sandbox = createLocalSandbox({ cwd: "/tmp/workspace" });
 const { tools } = createAgentTools(sandbox);
 
 // Wrap model with prompt caching (recommended)
@@ -311,12 +354,12 @@ const skills = await discoverSkills();
 ### Using Skills with Agents
 
 ```typescript
-import { discoverSkills, skillsToXml, createAgentTools, LocalSandbox } from "bashkit";
+import { discoverSkills, skillsToXml, createAgentTools, createLocalSandbox } from "bashkit";
 import { generateText, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 const skills = await discoverSkills();
-const sandbox = new LocalSandbox("/tmp/workspace");
+const sandbox = createLocalSandbox({ cwd: "/tmp/workspace" });
 const { tools } = createAgentTools(sandbox);
 
 const result = await generateText({
@@ -421,13 +464,13 @@ import {
   createAgentTools,
   createTaskTool,
   createTodoWriteTool,
-  LocalSandbox,
+  createLocalSandbox,
   anthropicPromptCacheMiddleware,
   type TodoState,
 } from "bashkit";
 
 // 1. Create sandbox
-const sandbox = new LocalSandbox("/tmp/workspace");
+const sandbox = createLocalSandbox({ cwd: "/tmp/workspace" });
 
 // 2. Create sandbox tools
 const { tools: sandboxTools } = createAgentTools(sandbox);
@@ -489,9 +532,9 @@ const { tools } = createAgentTools(sandbox, {
 Cache tool execution results to avoid redundant operations:
 
 ```typescript
-import { createAgentTools, LocalSandbox } from "bashkit";
+import { createAgentTools, createLocalSandbox } from "bashkit";
 
-const sandbox = new LocalSandbox("/tmp/workspace");
+const sandbox = createLocalSandbox({ cwd: "/tmp/workspace" });
 
 // Enable caching with defaults (LRU, 5min TTL)
 const { tools } = createAgentTools(sandbox, { cache: true });

package/README.md

@@ -148,6 +148,15 @@ const sandbox = createVercelSandbox({
   runtime: 'node22',
   resources: { vcpus: 2 },
 });
+
+// After first operation, get the sandbox ID for persistence
+await sandbox.exec('echo hello');
+console.log(sandbox.id); // Sandbox ID for reconnection
+
+// Later: reconnect to the same sandbox
+const reconnected = createVercelSandbox({
+  sandboxId: 'existing-sandbox-id',
+});
 ```
 
 ### E2BSandbox
@@ -158,7 +167,17 @@ Runs in E2B's cloud sandboxes. Requires `@e2b/code-interpreter` peer dependency.
 import { createE2BSandbox } from 'bashkit';
 
 const sandbox = createE2BSandbox({
-  // E2B config
+  apiKey: process.env.E2B_API_KEY,
+});
+
+// After first operation, get the sandbox ID for persistence
+await sandbox.exec('echo hello');
+console.log(sandbox.id); // "sbx_abc123..."
+
+// Later: reconnect to the same sandbox
+const reconnected = createE2BSandbox({
+  apiKey: process.env.E2B_API_KEY,
+  sandboxId: 'sbx_abc123...', // Reconnect to existing sandbox
 });
 ```
 
@@ -764,9 +783,14 @@ interface Sandbox {
   readDir(path: string): Promise<string[]>;
   fileExists(path: string): Promise<boolean>;
   destroy(): Promise<void>;
+
+  // Optional: Sandbox ID for reconnection (cloud providers only)
+  readonly id?: 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.
+
 ### Custom Sandbox Example
 
 ```typescript

package/dist/index.js

@@ -50,19 +50,31 @@ var anthropicPromptCacheMiddleware = {
   transformParams: async ({ params }) => applyCacheMarkers(params)
 };
 // src/sandbox/e2b.ts
-import { Sandbox as E2BSandboxSDK } from "@e2b/code-interpreter";
 function createE2BSandbox(config = {}) {
   let sandbox = null;
+  let sandboxId = config.sandboxId;
   const workingDirectory = config.cwd || "/home/user";
   const timeout = config.timeout ?? 300000;
   const ensureSandbox = async () => {
     if (sandbox)
       return sandbox;
-    sandbox = await E2BSandboxSDK.create({
-      apiKey: config.apiKey,
-      timeoutMs: timeout,
-      metadata: config.metadata
-    });
+    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");
+    }
+    if (config.sandboxId) {
+      sandbox = await E2BSandboxSDK.connect(config.sandboxId);
+    } else {
+      sandbox = await E2BSandboxSDK.create({
+        apiKey: config.apiKey,
+        timeoutMs: timeout,
+        metadata: config.metadata
+      });
+      sandboxId = sandbox.sandboxId;
+    }
     return sandbox;
   };
   const exec = async (command, options) => {
@@ -108,6 +120,9 @@ function createE2BSandbox(config = {}) {
   };
   return {
     exec,
+    get id() {
+      return sandboxId;
+    },
     async readFile(path) {
       const result = await exec(`cat "${path}"`);
       if (result.exitCode !== 0) {
@@ -224,9 +239,9 @@ function createLocalSandbox(config = {}) {
   };
 }
 // src/sandbox/vercel.ts
-import { Sandbox as VercelSandboxSDK } from "@vercel/sandbox";
 function createVercelSandbox(config = {}) {
   let sandbox = null;
+  let sandboxId = config.sandboxId;
   const workingDirectory = config.cwd || "/vercel/sandbox";
   const resolvedConfig = {
     runtime: config.runtime ?? "node22",
@@ -236,6 +251,13 @@ function createVercelSandbox(config = {}) {
   const ensureSandbox = async () => {
     if (sandbox)
       return sandbox;
+    let VercelSandboxSDK;
+    try {
+      const module = await import("@vercel/sandbox");
+      VercelSandboxSDK = module.Sandbox;
+    } catch {
+      throw new Error("VercelSandbox requires @vercel/sandbox. Install with: npm install @vercel/sandbox");
+    }
     const createOptions = {
       runtime: resolvedConfig.runtime,
       resources: resolvedConfig.resources,
@@ -247,7 +269,12 @@ function createVercelSandbox(config = {}) {
         token: config.token
       });
     }
-    sandbox = await VercelSandboxSDK.create(createOptions);
+    if (config.sandboxId) {
+      sandbox = await VercelSandboxSDK.get({ sandboxId: config.sandboxId });
+    } else {
+      sandbox = await VercelSandboxSDK.create(createOptions);
+    }
+    sandboxId = sandbox.sandboxId;
     return sandbox;
   };
   const exec = async (command, options) => {
@@ -301,6 +328,9 @@ function createVercelSandbox(config = {}) {
   };
   return {
     exec,
+    get id() {
+      return sandboxId;
+    },
     async readFile(path) {
       const sbx = await ensureSandbox();
       const stream = await sbx.readFile({ path });
@@ -1372,13 +1402,56 @@ function createSkillTool(config) {
 
 // src/tools/web-fetch.ts
 import { generateText, tool as tool10, zodSchema as zodSchema10 } from "ai";
-import Parallel from "parallel-web";
 import { z as z10 } from "zod";
 
 // src/utils/http-constants.ts
 var RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503];
 
 // src/tools/web-fetch.ts
+var parallelModule = null;
+async function getParallelModule() {
+  if (!parallelModule) {
+    try {
+      parallelModule = await import("parallel-web");
+    } catch {
+      throw new Error("WebFetch requires parallel-web. Install with: npm install parallel-web");
+    }
+  }
+  return parallelModule;
+}
+async function fetchWithParallel(url, apiKey) {
+  const { default: Parallel } = await getParallelModule();
+  const client = new Parallel({ apiKey });
+  const extract = await client.beta.extract({
+    urls: [url],
+    excerpts: true,
+    full_content: true
+  });
+  if (!extract.results || extract.results.length === 0) {
+    throw new Error("No content extracted from URL");
+  }
+  const result = extract.results[0];
+  const content = result.full_content || result.excerpts?.join(`
+
+`) || "";
+  if (!content) {
+    throw new Error("No content available from URL");
+  }
+  return {
+    content,
+    finalUrl: result.url
+  };
+}
+async function fetchContent(url, apiKey, provider) {
+  switch (provider) {
+    case "parallel":
+      return fetchWithParallel(url, apiKey);
+    default: {
+      const _exhaustive = provider;
+      throw new Error(`Unknown provider: ${_exhaustive}`);
+    }
+  }
+}
 var webFetchInputSchema = z10.object({
   url: z10.string().describe("The URL to fetch content from"),
   prompt: z10.string().describe("The prompt to run on the fetched content")
@@ -1400,7 +1473,14 @@ Usage notes:
   - When a URL redirects to a different host, the tool will inform you and provide the redirect URL. You should then make a new WebFetch request with the redirect URL to fetch the content.
 `;
 function createWebFetchTool(config) {
-  const { apiKey, model, strict, needsApproval, providerOptions } = config;
+  const {
+    provider = "parallel",
+    apiKey,
+    model,
+    strict,
+    needsApproval,
+    providerOptions
+  } = config;
   return tool10({
     description: WEB_FETCH_DESCRIPTION,
     inputSchema: zodSchema10(webFetchInputSchema),
@@ -1410,30 +1490,7 @@ function createWebFetchTool(config) {
     execute: async (input) => {
       const { url, prompt } = input;
       try {
-        const client = new Parallel({ apiKey });
-        const extract = await client.beta.extract({
-          urls: [url],
-          excerpts: true,
-          full_content: true
-        });
-        if (!extract.results || extract.results.length === 0) {
-          return {
-            error: "No content extracted from URL",
-            status_code: 404,
-            retryable: false
-          };
-        }
-        const extractedResult = extract.results[0];
-        const content = extractedResult.full_content || extractedResult.excerpts?.join(`
-
-`) || "";
-        if (!content) {
-          return {
-            error: "No content available from URL",
-            status_code: 404,
-            retryable: false
-          };
-        }
+        const { content, finalUrl } = await fetchContent(url, apiKey, provider);
         const result = await generateText({
           model,
           prompt: `${prompt}
@@ -1445,7 +1502,7 @@ ${content}`
         return {
           response: result.text,
           url,
-          final_url: extractedResult.url || url
+          final_url: finalUrl || url
         };
       } catch (error) {
         if (error && typeof error === "object" && "status" in error) {
@@ -1467,8 +1524,53 @@ ${content}`
 
 // src/tools/web-search.ts
 import { tool as tool11, zodSchema as zodSchema11 } from "ai";
-import Parallel2 from "parallel-web";
 import { z as z11 } from "zod";
+var parallelModule2 = null;
+async function getParallelModule2() {
+  if (!parallelModule2) {
+    try {
+      parallelModule2 = await import("parallel-web");
+    } catch {
+      throw new Error("WebSearch requires parallel-web. Install with: npm install parallel-web");
+    }
+  }
+  return parallelModule2;
+}
+async function searchWithParallel(apiKey, options) {
+  const { default: Parallel } = await getParallelModule2();
+  const client = new Parallel({ apiKey });
+  const sourcePolicy = options.allowedDomains || options.blockedDomains ? {
+    ...options.allowedDomains && {
+      include_domains: options.allowedDomains
+    },
+    ...options.blockedDomains && {
+      exclude_domains: options.blockedDomains
+    }
+  } : undefined;
+  const search = await client.beta.search({
+    mode: "agentic",
+    objective: options.query,
+    max_results: 10,
+    ...sourcePolicy && { source_policy: sourcePolicy }
+  });
+  return (search.results || []).map((result) => ({
+    title: result.title ?? "",
+    url: result.url ?? "",
+    snippet: result.excerpts?.join(`
+`) ?? "",
+    metadata: result.publish_date ? { publish_date: result.publish_date } : undefined
+  }));
+}
+async function searchContent(apiKey, provider, options) {
+  switch (provider) {
+    case "parallel":
+      return searchWithParallel(apiKey, options);
+    default: {
+      const _exhaustive = provider;
+      throw new Error(`Unknown provider: ${_exhaustive}`);
+    }
+  }
+}
 var webSearchInputSchema = z11.object({
   query: z11.string().describe("The search query to use"),
   allowed_domains: z11.array(z11.string()).optional().describe("Only include results from these domains"),
@@ -1495,7 +1597,13 @@ When searching for recent information, documentation, or current events, use the
 - allowed_domains: Only include results from these domains
 - blocked_domains: Never include results from these domains`;
 function createWebSearchTool(config) {
-  const { apiKey, strict, needsApproval, providerOptions } = config;
+  const {
+    provider = "parallel",
+    apiKey,
+    strict,
+    needsApproval,
+    providerOptions
+  } = config;
   return tool11({
     description: WEB_SEARCH_DESCRIPTION,
     inputSchema: zodSchema11(webSearchInputSchema),
@@ -1505,24 +1613,11 @@ function createWebSearchTool(config) {
     execute: async (input) => {
       const { query, allowed_domains, blocked_domains } = input;
       try {
-        const client = new Parallel2({ apiKey });
-        const sourcePolicy = allowed_domains || blocked_domains ? {
-          ...allowed_domains && { include_domains: allowed_domains },
-          ...blocked_domains && { exclude_domains: blocked_domains }
-        } : undefined;
-        const search = await client.beta.search({
-          mode: "agentic",
-          objective: query,
-          max_results: 10,
-          ...sourcePolicy && { source_policy: sourcePolicy }
+        const results = await searchContent(apiKey, provider, {
+          query,
+          allowedDomains: allowed_domains,
+          blockedDomains: blocked_domains
         });
-        const results = (search.results || []).map((result) => ({
-          title: result.title ?? "",
-          url: result.url ?? "",
-          snippet: result.excerpts?.join(`
-`) ?? "",
-          metadata: result.publish_date ? { publish_date: result.publish_date } : undefined
-        }));
         return {
           results,
           total_results: results.length,

package/dist/sandbox/e2b.d.ts

@@ -1,6 +1,8 @@
 import type { Sandbox } from "./interface";
 export interface E2BSandboxConfig {
     apiKey?: string;
+    /** Existing sandbox ID to reconnect to instead of creating new */
+    sandboxId?: string;
     template?: string;
     timeout?: number;
     cwd?: string;

package/dist/sandbox/interface.d.ts

@@ -18,4 +18,11 @@ export interface Sandbox {
     fileExists(path: string): Promise<boolean>;
     isDirectory(path: string): Promise<boolean>;
     destroy(): Promise<void>;
+    /**
+     * Sandbox ID for reconnection (cloud providers only).
+     * - For new sandboxes: available after first operation
+     * - For reconnected sandboxes: available immediately
+     * - For local sandboxes: always undefined
+     */
+    readonly id?: string;
 }

package/dist/sandbox/vercel.d.ts

@@ -4,6 +4,8 @@ export interface VercelSandboxConfig {
     resources?: {
         vcpus: number;
     };
+    /** Existing sandbox ID to reconnect to instead of creating new */
+    sandboxId?: string;
     timeout?: number;
     cwd?: string;
     teamId?: string;

package/dist/tools/index.d.ts

@@ -69,7 +69,7 @@ export type { SubagentEventData, SubagentStepEvent, SubagentTypeConfig, TaskErro
 export { createTaskTool } from "./task";
 export type { TodoItem, TodoState, TodoWriteError, TodoWriteOutput, } from "./todo-write";
 export { createTodoWriteTool } from "./todo-write";
-export type { WebFetchError, WebFetchOutput } from "./web-fetch";
+export type { ExtractResult, WebFetchError, WebFetchOutput } from "./web-fetch";
 export { createWebFetchTool } from "./web-fetch";
 export type { WebSearchError, WebSearchOutput, WebSearchResult, } from "./web-search";
 export { createWebSearchTool } from "./web-search";

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

@@ -10,6 +10,14 @@ export interface WebFetchError {
     status_code?: number;
     retryable?: boolean;
 }
+/**
+ * Result from a web fetch provider's extract operation.
+ * New providers should return this shape.
+ */
+export interface ExtractResult {
+    content: string;
+    finalUrl?: string;
+}
 export declare function createWebFetchTool(config: WebFetchConfig): import("ai").Tool<{
     url: string;
     prompt: string;

package/dist/types.d.ts

@@ -25,10 +25,26 @@ export type GrepToolConfig = ToolConfig & {
     /** Use ripgrep (rg) instead of grep. Requires ripgrep to be installed. Default: false */
     useRipgrep?: boolean;
 };
+/**
+ * Supported web search providers.
+ * Currently only 'parallel' is implemented.
+ * Add new providers here as union types (e.g., 'parallel' | 'serper' | 'tavily')
+ */
+export type WebSearchProvider = "parallel";
+/**
+ * Supported web fetch providers.
+ * Currently only 'parallel' is implemented.
+ * Add new providers here as union types (e.g., 'parallel' | 'firecrawl' | 'jina')
+ */
+export type WebFetchProvider = "parallel";
 export type WebSearchConfig = {
+    /** Provider to use for web search. Default: 'parallel' */
+    provider?: WebSearchProvider;
     apiKey: string;
 } & SDKToolOptions;
 export type WebFetchConfig = {
+    /** Provider to use for web fetching. Default: 'parallel' */
+    provider?: WebFetchProvider;
     apiKey: string;
     model: LanguageModel;
 } & SDKToolOptions;

package/package.json

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