bashkit 0.1.3 → 0.2.1

package/AGENTS.md

@@ -484,3 +484,111 @@ const { tools } = createAgentTools(sandbox, {
 });
 ```
 
+## Tool Result Caching
+
+Cache tool execution results to avoid redundant operations:
+
+```typescript
+import { createAgentTools, LocalSandbox } from "bashkit";
+
+const sandbox = new LocalSandbox("/tmp/workspace");
+
+// Enable caching with defaults (LRU, 5min TTL)
+const { tools } = createAgentTools(sandbox, { cache: true });
+
+// Or customize caching behavior
+const { tools } = createAgentTools(sandbox, {
+  cache: {
+    ttl: 10 * 60 * 1000,  // 10 minutes
+    debug: true,          // Log cache hits/misses
+    Read: true,           // Enable for Read
+    Glob: true,           // Enable for Glob
+    Grep: false,          // Disable for Grep
+  },
+});
+```
+
+**Default cached tools:** Read, Glob, Grep, WebFetch, WebSearch
+
+**Not cached by default:** Bash, Write, Edit (have side effects)
+
+### Cache Callbacks
+
+Track cache performance with callbacks:
+
+```typescript
+const { tools } = createAgentTools(sandbox, {
+  cache: {
+    onHit: (toolName, key) => {
+      metrics.increment(`cache.hit.${toolName}`);
+    },
+    onMiss: (toolName, key) => {
+      metrics.increment(`cache.miss.${toolName}`);
+    },
+  },
+});
+```
+
+### Cache Stats
+
+Cached tools have additional methods:
+
+```typescript
+import type { CachedTool } from "bashkit";
+
+const readTool = tools.Read as CachedTool;
+
+// Check cache performance (async for Redis compatibility)
+console.log(await readTool.getStats());
+// { hits: 5, misses: 2, hitRate: 0.71, size: 2 }
+
+// Clear cache
+await readTool.clearCache();        // Clear all
+await readTool.clearCache("key");   // Clear specific entry
+```
+
+### Redis Cache Store
+
+Use your existing Redis client with the helper:
+
+```typescript
+import { createRedisCacheStore, createAgentTools } from "bashkit";
+
+const store = createRedisCacheStore(myRedisClient);
+const { tools } = createAgentTools(sandbox, { cache: store });
+```
+
+Works with `redis`, `ioredis`, or any client with `get`, `set`, `del`, `keys` methods. TTL is handled by the wrapper for consistent behavior across all cache backends.
+
+### Custom Cache Store
+
+For other backends, implement the `CacheStore` interface:
+
+```typescript
+import type { CacheStore } from "bashkit";
+
+const myStore: CacheStore = {
+  get(key) { /* return CacheEntry or undefined */ },
+  set(key, entry) { /* store entry */ },
+  delete(key) { /* remove entry */ },
+  clear() { /* remove all entries */ },
+  size() { /* optional: return count */ },
+};
+
+const { tools } = createAgentTools(sandbox, { cache: myStore });
+```
+
+### Standalone Caching
+
+Wrap individual tools with caching:
+
+```typescript
+import { cached, LRUCacheStore } from "bashkit";
+
+const cachedTool = cached(myTool, "MyTool", {
+  ttl: 60000,       // 1 minute
+  debug: true,      // Log cache activity
+  store: new LRUCacheStore(500),  // Max 500 entries
+});
+```
+

package/README.md

@@ -217,6 +217,34 @@ const { tools, planModeState } = createAgentTools(sandbox, {
 - `allowedPaths` (string[]): Restrict file operations to specific paths
 - `blockedCommands` (string[]): Block commands containing these strings (Bash)
 
+#### AI SDK Tool Options (v6+)
+
+All tools support AI SDK v6 tool options:
+
+```typescript
+const { tools } = createAgentTools(sandbox, {
+  tools: {
+    Bash: {
+      timeout: 30000,
+      // AI SDK v6 options
+      needsApproval: true, // Require user approval before execution
+      strict: true, // Strict schema validation
+      providerOptions: { /* provider-specific options */ },
+    },
+    Write: {
+      // Dynamic approval based on input
+      needsApproval: async ({ file_path }) => {
+        return file_path.includes('package.json');
+      },
+    },
+  },
+});
+```
+
+- `needsApproval` (boolean | function): Require user approval before tool execution
+- `strict` (boolean): Enable strict schema validation
+- `providerOptions` (object): Provider-specific tool options
+
 ## Sub-agents with Task Tool
 
 The Task tool spawns new agents for complex subtasks:
@@ -254,6 +282,26 @@ The parent agent calls Task like any other tool:
 }}
 ```
 
+### Dynamic Agents
+
+You can create custom agents on the fly by passing `system_prompt` and/or `tools` directly, without predefined subagent types:
+
+```typescript
+// Agent creates a specialized agent dynamically:
+{ tool: "Task", args: {
+  description: "Analyze security vulnerabilities",
+  prompt: "Review the auth code for security issues",
+  subagent_type: "custom",
+  system_prompt: "You are a security expert. Focus on OWASP top 10 vulnerabilities.",
+  tools: ["Read", "Grep", "Glob"]
+}}
+```
+
+This is useful when:
+- The parent agent needs to create specialized agents based on context
+- You want agents to delegate with custom instructions
+- Predefined subagent types don't fit the task
+
 ### Streaming Sub-agent Activity to UI
 
 Pass a `streamWriter` to stream real-time sub-agent activity to the UI:
@@ -336,13 +384,111 @@ if (contextNeedsCompaction(status)) {
 }
 ```
 
+## Tool Result Caching
+
+Cache tool execution results to avoid repeated expensive operations:
+
+```typescript
+const { tools } = createAgentTools(sandbox, {
+  // Enable caching with defaults (LRU, 5min TTL)
+  cache: true,
+});
+```
+
+### Cache Configuration Options
+
+```typescript
+const { tools } = createAgentTools(sandbox, {
+  cache: {
+    // Custom TTL (default: 5 minutes)
+    ttl: 10 * 60 * 1000,
+
+    // Enable debug logging
+    debug: true,
+
+    // Per-tool control (defaults: Read, Glob, Grep, WebFetch, WebSearch)
+    Read: true,
+    Glob: true,
+    Grep: false,  // Disable for this tool
+
+    // Enable caching for tools not cached by default
+    Bash: true,  // Use with caution - has side effects
+  },
+});
+```
+
+### Default Cached Tools
+
+By default, these read-only tools are cached when `cache: true`:
+- `Read` - File reading
+- `Glob` - File pattern matching
+- `Grep` - Content searching
+- `WebFetch` - URL fetching
+- `WebSearch` - Web searches
+
+Tools with side effects (`Bash`, `Write`, `Edit`) are NOT cached by default but can be enabled.
+
+### Custom Cache Store
+
+Implement your own cache backend (e.g., Redis):
+
+```typescript
+import type { CacheStore } from 'bashkit';
+
+const redisStore: CacheStore = {
+  async get(key) {
+    const data = await redis.get(key);
+    return data ? JSON.parse(data) : undefined;
+  },
+  async set(key, entry) {
+    await redis.set(key, JSON.stringify(entry));
+  },
+  async delete(key) {
+    await redis.del(key);
+  },
+  async clear() {
+    await redis.flushdb();
+  },
+  size() {
+    return redis.dbsize();
+  },
+};
+
+const { tools } = createAgentTools(sandbox, {
+  cache: redisStore,
+});
+```
+
+### Standalone Cached Wrapper
+
+Wrap individual tools with caching:
+
+```typescript
+import { cached, LRUCacheStore } from 'bashkit';
+
+const cachedTool = cached(myTool, 'MyTool', {
+  ttl: 5 * 60 * 1000,
+  debug: true,
+});
+
+// Check cache stats
+console.log(await cachedTool.getStats());
+// { hits: 5, misses: 2, hitRate: 0.71, size: 2 }
+
+// Clear cache
+await cachedTool.clearCache();
+```
+
 ## Prompt Caching
 
 Enable Anthropic prompt caching to reduce costs on repeated prefixes:
 
 ```typescript
 import { wrapLanguageModel } from 'ai';
+// AI SDK v6+
 import { anthropicPromptCacheMiddleware } from 'bashkit';
+// AI SDK v5
+// import { anthropicPromptCacheMiddlewareV2 } from 'bashkit';
 
 const model = wrapLanguageModel({
   model: anthropic('claude-sonnet-4-5'),
@@ -731,7 +877,8 @@ Creates a set of agent tools bound to a sandbox instance.
 
 ### Middleware
 
-- `anthropicPromptCacheMiddleware` - Enable prompt caching for Anthropic models
+- `anthropicPromptCacheMiddleware` - Enable prompt caching for Anthropic models (AI SDK v6+)
+- `anthropicPromptCacheMiddlewareV2` - Enable prompt caching for Anthropic models (AI SDK v5)
 
 ## Future Roadmap
 

package/dist/cache/cached.d.ts

@@ -0,0 +1,37 @@
+import type { Tool } from "ai";
+import type { CacheOptions, CacheStats } from "./types";
+/**
+ * Extended tool with cache methods.
+ */
+export type CachedTool<T extends Tool = Tool> = T & {
+    /** Get cache statistics (hits, misses, hitRate, size) */
+    getStats(): Promise<CacheStats>;
+    /** Clear cache. Pass key to clear specific entry, or no args to clear all. */
+    clearCache(key?: string): Promise<void>;
+};
+/**
+ * Wraps an AI SDK tool with caching capabilities.
+ *
+ * Caches successful tool results (results without an 'error' property).
+ * Cache hits return immediately without re-executing the tool.
+ *
+ * @param tool - The AI SDK tool to wrap
+ * @param toolName - Name used in cache keys (e.g., 'Read', 'Glob')
+ * @param options - Cache configuration options
+ * @returns Cached tool with getStats() and clearCache() methods
+ *
+ * @example
+ * ```typescript
+ * import { cached, LRUCacheStore } from 'bashkit';
+ *
+ * const cachedReadTool = cached(readTool, 'Read', {
+ *   ttl: 5 * 60 * 1000,  // 5 minutes
+ *   debug: true,
+ * });
+ *
+ * // Check stats (async for Redis compatibility)
+ * console.log(await cachedReadTool.getStats());
+ * // { hits: 5, misses: 2, hitRate: 0.71, size: 2 }
+ * ```
+ */
+export declare function cached<T extends Tool>(tool: T, toolName: string, options?: CacheOptions): CachedTool<T>;

package/dist/cache/index.d.ts

@@ -0,0 +1,6 @@
+export type { CacheEntry, CacheOptions, CacheStats, CacheStore, } from "./types";
+export { LRUCacheStore } from "./lru";
+export { cached } from "./cached";
+export type { CachedTool } from "./cached";
+export { createRedisCacheStore } from "./redis";
+export type { RedisCacheStoreOptions, RedisClient } from "./redis";

package/dist/cache/lru.d.ts

@@ -0,0 +1,25 @@
+import type { CacheEntry, CacheStore } from "./types";
+/**
+ * LRU (Least Recently Used) cache implementation.
+ *
+ * Uses a Map for O(1) access. When items are retrieved, they're moved to the
+ * end (most recently used). When capacity is reached, the oldest (first) entry
+ * is removed.
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUCacheStore(1000);
+ * cache.set('key', { result: data, timestamp: Date.now() });
+ * const entry = cache.get('key');
+ * ```
+ */
+export declare class LRUCacheStore<T = unknown> implements CacheStore<T> {
+    private cache;
+    private maxSize;
+    constructor(maxSize?: number);
+    get(key: string): CacheEntry<T> | undefined;
+    set(key: string, entry: CacheEntry<T>): void;
+    delete(key: string): void;
+    clear(): void;
+    size(): number;
+}

package/dist/cache/redis.d.ts

@@ -0,0 +1,41 @@
+import type { CacheStore } from "./types";
+/**
+ * Minimal interface for Redis-like clients.
+ * Compatible with `redis`, `ioredis`, and similar libraries.
+ */
+export interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    del(key: string | string[]): Promise<unknown>;
+    keys(pattern: string): Promise<string[]>;
+}
+/**
+ * Options for Redis cache store.
+ */
+export interface RedisCacheStoreOptions {
+    /** Key prefix for namespacing (default: "bashkit:") */
+    prefix?: string;
+}
+/**
+ * Creates a CacheStore from an existing Redis client.
+ *
+ * TTL is handled by the cached() wrapper, not Redis. This ensures
+ * consistent TTL behavior across all cache backends.
+ *
+ * @param client - Your Redis client (redis, ioredis, etc.)
+ * @param options - Configuration options (prefix)
+ * @returns CacheStore compatible with bashkit caching
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "redis";
+ * import { createRedisCacheStore, createAgentTools } from "bashkit";
+ *
+ * const redis = createClient();
+ * await redis.connect();
+ *
+ * const store = createRedisCacheStore(redis);
+ * const { tools } = createAgentTools(sandbox, { cache: store });
+ * ```
+ */
+export declare function createRedisCacheStore(client: RedisClient, options?: RedisCacheStoreOptions): CacheStore;

package/dist/cache/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Cache entry with result and timestamp for TTL checks.
+ */
+export interface CacheEntry<T = unknown> {
+    result: T;
+    timestamp: number;
+}
+/**
+ * Cache store interface for tool result caching.
+ * Supports both sync and async operations for different backends (LRU, Redis, etc.)
+ */
+export interface CacheStore<T = unknown> {
+    /** Get cached entry by key */
+    get(key: string): CacheEntry<T> | undefined | Promise<CacheEntry<T> | undefined>;
+    /** Set cache entry */
+    set(key: string, entry: CacheEntry<T>): void | Promise<void>;
+    /** Delete cache entry */
+    delete(key: string): void | Promise<void>;
+    /** Clear all entries */
+    clear(): void | Promise<void>;
+    /** Get current cache size (optional, for stats) */
+    size?(): number | Promise<number>;
+}
+/**
+ * Options for the cached() tool wrapper.
+ */
+export interface CacheOptions {
+    /** TTL in milliseconds (default: 5 minutes) */
+    ttl?: number;
+    /** Custom cache store (default: LRUCacheStore) */
+    store?: CacheStore;
+    /** Custom key generator */
+    keyGenerator?: (toolName: string, params: unknown) => string;
+    /** Enable debug logging for cache hits/misses */
+    debug?: boolean;
+    /** Callback when cache hit occurs */
+    onHit?: (toolName: string, key: string) => void;
+    /** Callback when cache miss occurs */
+    onMiss?: (toolName: string, key: string) => void;
+}
+/**
+ * Cache statistics returned by getStats().
+ */
+export interface CacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Hit rate (0-1) */
+    hitRate: number;
+    /** Current cache size */
+    size: number;
+}

package/dist/index.d.ts

@@ -1,15 +1,17 @@
-export type { UIMessageStreamWriter } from "ai";
-export { anthropicPromptCacheMiddleware } from "./middleware";
+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 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, WebFetchToolConfig, WebSearchError, WebSearchOutput, WebSearchResult, WebSearchToolConfig, WriteError, WriteOutput, } from "./tools";
+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";
-export type { AgentConfig, AskUserConfig, SkillConfig, ToolConfig, WebFetchConfig, WebSearchConfig, } from "./types";
+export type { AgentConfig, AskUserConfig, CacheConfig, SkillConfig, ToolConfig, WebFetchConfig, WebSearchConfig, } from "./types";
 export { DEFAULT_CONFIG } from "./types";
+export type { CachedTool, CacheEntry, CacheOptions, CacheStats, CacheStore, RedisCacheStoreOptions, RedisClient, } from "./cache";
+export { cached, createRedisCacheStore, LRUCacheStore } from "./cache";
 export type { CompactConversationConfig, CompactConversationResult, CompactConversationState, ContextMetrics, ContextStatus, ContextStatusConfig, ContextStatusLevel, ModelContextLimit, PruneMessagesConfig, } from "./utils";
 export { compactConversation, contextNeedsAttention, contextNeedsCompaction, createCompactConfig, estimateMessagesTokens, estimateMessageTokens, estimateTokens, getContextStatus, MODEL_CONTEXT_LIMITS, pruneMessagesByTokens, } from "./utils";
 export type { DiscoverSkillsOptions, SkillBundle, SkillMetadata, } from "./skills";
-export { discoverSkills, fetchSkill, fetchSkills, parseSkillMetadata, skillsToXml, } from "./skills";
+export { discoverSkills, fetchSkill, fetchSkills, loadSkillBundle, loadSkillBundles, parseSkillMetadata, skillsToXml, } from "./skills";
 export type { AgentEnvironmentConfig, SetupResult, SkillContent, } from "./setup";
 export { setupAgentEnvironment } from "./setup";