bashkit 0.3.2 → 0.5.0

package/AGENTS.md

@@ -92,18 +92,35 @@ This is useful for:
 - Persisting sandbox state between server restarts
 - Reducing sandbox creation overhead
 
+## Internal Architecture
+
+For developers working on bashkit internals, each source folder has its own `AGENTS.md`:
+
+- `src/sandbox/AGENTS.md` -- Execution environment abstractions
+- `src/tools/AGENTS.md` -- Tool implementations
+- `src/cache/AGENTS.md` -- Tool result caching
+- `src/middleware/AGENTS.md` -- AI SDK middleware
+- `src/utils/AGENTS.md` -- Utility functions
+- `src/skills/AGENTS.md` -- Agent Skills support
+- `src/setup/AGENTS.md` -- Environment setup
+- `src/cli/AGENTS.md` -- CLI initialization
+
+See also `CLAUDE.md` for development workflow and conventions.
+
 ## Available Tools
 
 ### Default Tools (always included)
 
 | Tool | Purpose | Key Inputs |
 |------|---------|------------|
-| `Bash` | Execute shell commands | `command`, `timeout?`, `description?` |
-| `Read` | Read files or list directories | `file_path`, `offset?`, `limit?` |
+| `Bash` | Execute shell commands | `command`, `timeout`, `description` |
+| `Read` | Read files or list directories | `file_path`, `offset`, `limit` |
 | `Write` | Create/overwrite files | `file_path`, `content` |
-| `Edit` | Replace strings in files | `file_path`, `old_string`, `new_string`, `replace_all?` |
-| `Glob` | Find files by pattern | `pattern`, `path?` |
-| `Grep` | Search file contents | `pattern`, `path?`, `output_mode?`, `-i?`, `-C?` |
+| `Edit` | Replace strings in files | `file_path`, `old_string`, `new_string`, `replace_all` |
+| `Glob` | Find files by pattern | `pattern`, `path` |
+| `Grep` | Search file contents | `pattern`, `path`, `output_mode`, `-i`, `-C` |
+
+> **Note on nullable types:** Optional parameters use `T | null` (not `T | undefined`) for OpenAI structured outputs compatibility. AI models should send explicit `null` for parameters they don't want to set. This works with both OpenAI and Anthropic models.
 
 ### Optional Tools (via config)
 

package/README.md

@@ -19,6 +19,32 @@ Agentic coding tools for Vercel AI SDK. Give AI agents the ability to execute co
 - Search the web and fetch URLs
 - Load skills on-demand via the [Agent Skills](https://agentskills.io) standard
 
+## Breaking Changes in v0.4.0
+
+### Nullable Types for OpenAI Compatibility
+
+All optional tool parameters now use `.nullable()` instead of `.optional()` in Zod schemas. This change enables compatibility with OpenAI's structured outputs, which require all properties to be in the `required` array.
+
+**What changed:**
+- Tool input types changed from `T | undefined` to `T | null`
+- Exported interfaces (`QuestionOption`, `StructuredQuestion`) use `T | null`
+- AI models will send explicit `null` values instead of omitting properties
+
+**Migration:**
+```typescript
+// Before v0.4.0
+const option: QuestionOption = { label: "test", description: undefined };
+
+// v0.4.0+
+const option: QuestionOption = { label: "test", description: null };
+```
+
+**Why this matters:**
+- Works with both OpenAI and Anthropic models
+- OpenAI structured outputs require nullable (not optional) fields
+- Anthropic/Claude handles nullable fields correctly
+- The `??` operator handles both `null` and `undefined`, so runtime behavior is unchanged
+
 ## Installation
 
 ```bash

package/dist/cli/init.js

@@ -54,7 +54,7 @@ export const config: AgentConfig = {${webTools ? `
 ` : ""}};
 
 // Create tools
-export const { tools } = createAgentTools(sandbox${webTools ? ", config" : ""});
+export const { tools } = await createAgentTools(sandbox${webTools ? ", config" : ""});
 `;
   const configPath = join(process.cwd(), "bashkit.config.ts");
   if (existsSync(configPath)) {

package/dist/index.d.ts

@@ -3,14 +3,14 @@ export { anthropicPromptCacheMiddleware, anthropicPromptCacheMiddlewareV2, } fro
 export type { E2BSandboxConfig, LocalSandboxConfig, VercelSandboxConfig, } 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 type { AgentToolsResult, AskUserError, AskUserOutput, AskUserResponseHandler, QuestionOption, StructuredQuestion, 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, CacheConfig, SkillConfig, ToolConfig, WebFetchConfig, WebSearchConfig, } from "./types";
+export type { AgentConfig, AskUserConfig, BudgetConfig, CacheConfig, PricingProvider, 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, DebugEvent, ModelContextLimit, PruneMessagesConfig, } from "./utils";
-export { clearDebugLogs, compactConversation, contextNeedsAttention, contextNeedsCompaction, createCompactConfig, estimateMessagesTokens, estimateMessageTokens, estimateTokens, getContextStatus, getDebugLogs, isDebugEnabled, MODEL_CONTEXT_LIMITS, pruneMessagesByTokens, reinitDebugMode, } from "./utils";
+export type { BudgetStatus, BudgetTracker, ModelPricing, CompactConversationConfig, CompactConversationResult, CompactConversationState, ContextMetrics, ContextStatus, ContextStatusConfig, ContextStatusLevel, DebugEvent, ModelContextLimit, PruneMessagesConfig, } from "./utils";
+export { createBudgetTracker, clearDebugLogs, compactConversation, contextNeedsAttention, contextNeedsCompaction, createCompactConfig, estimateMessagesTokens, estimateMessageTokens, estimateTokens, getContextStatus, getDebugLogs, isDebugEnabled, MODEL_CONTEXT_LIMITS, pruneMessagesByTokens, reinitDebugMode, } from "./utils";
 export type { DiscoverSkillsOptions, SkillBundle, SkillMetadata, } from "./skills";
 export { discoverSkills, fetchSkill, fetchSkills, loadSkillBundle, loadSkillBundles, parseSkillMetadata, skillsToXml, } from "./skills";
 export type { AgentEnvironmentConfig, SetupResult, SkillContent, } from "./setup";

package/dist/index.js

@@ -612,6 +612,242 @@ var DEFAULT_CONFIG = {
   }
 };
 
+// src/utils/budget-tracking.ts
+var openRouterCache = null;
+var openRouterCacheTimestamp = 0;
+var openRouterFetchPromise = null;
+var OPENROUTER_FETCH_TIMEOUT_MS = 1e4;
+var OPENROUTER_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+async function fetchOpenRouterPricing(apiKey) {
+  if (openRouterCache && Date.now() - openRouterCacheTimestamp < OPENROUTER_CACHE_TTL_MS) {
+    return openRouterCache;
+  }
+  if (openRouterFetchPromise)
+    return openRouterFetchPromise;
+  openRouterFetchPromise = (async () => {
+    const controller = new AbortController;
+    const timeoutId = setTimeout(() => controller.abort(), OPENROUTER_FETCH_TIMEOUT_MS);
+    try {
+      let response;
+      try {
+        const headers = {};
+        if (apiKey) {
+          headers["Authorization"] = `Bearer ${apiKey}`;
+        }
+        response = await fetch("https://openrouter.ai/api/v1/models", {
+          signal: controller.signal,
+          headers
+        });
+      } catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+          throw new Error(`[bashkit] OpenRouter pricing fetch timed out after ${OPENROUTER_FETCH_TIMEOUT_MS / 1000}s. ` + `This usually means OpenRouter is unreachable from your network. ` + `You can bypass this by providing modelPricing overrides in your config.`);
+        }
+        throw new Error(`[bashkit] OpenRouter pricing fetch failed (network error). ` + `Ensure you have internet access or provide modelPricing overrides in your config. ` + `Original error: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      if (!response.ok) {
+        throw new Error(`[bashkit] OpenRouter pricing fetch failed: HTTP ${response.status} ${response.statusText}. ` + `You can bypass this by providing modelPricing overrides in your config.`);
+      }
+      const json = await response.json();
+      const models = json.data;
+      if (!Array.isArray(models)) {
+        throw new Error(`[bashkit] OpenRouter pricing response missing data array. ` + `The API may have changed. Please provide modelPricing overrides in your config.`);
+      }
+      const MAX_MODELS = 1e4;
+      const map = new Map;
+      for (const model of models.slice(0, MAX_MODELS)) {
+        if (!model.id || !model.pricing)
+          continue;
+        const prompt = parseFloat(model.pricing.prompt ?? "");
+        const completion = parseFloat(model.pricing.completion ?? "");
+        if (!Number.isFinite(prompt) || !Number.isFinite(completion))
+          continue;
+        if (prompt < 0 || completion < 0)
+          continue;
+        const pricing = {
+          inputPerToken: prompt,
+          outputPerToken: completion
+        };
+        const cacheRead = parseFloat(model.pricing.input_cache_read ?? "");
+        if (Number.isFinite(cacheRead) && cacheRead >= 0)
+          pricing.cacheReadPerToken = cacheRead;
+        const cacheWrite = parseFloat(model.pricing.input_cache_write ?? "");
+        if (Number.isFinite(cacheWrite) && cacheWrite >= 0)
+          pricing.cacheWritePerToken = cacheWrite;
+        map.set(model.id.toLowerCase(), pricing);
+      }
+      openRouterCache = map;
+      openRouterCacheTimestamp = Date.now();
+      return openRouterCache;
+    } finally {
+      clearTimeout(timeoutId);
+      openRouterFetchPromise = null;
+    }
+  })();
+  return openRouterFetchPromise;
+}
+function getModelMatchVariants(model) {
+  const lower = model.toLowerCase();
+  const kebab = lower.replace(/[^a-z0-9]+/g, "-");
+  const withoutProvider = lower.includes("/") ? lower.slice(lower.lastIndexOf("/") + 1) : lower;
+  const withoutProviderKebab = withoutProvider.replace(/[^a-z0-9]+/g, "-");
+  const seen = new Set;
+  const variants = [];
+  for (const v of [lower, kebab, withoutProvider, withoutProviderKebab]) {
+    if (!seen.has(v)) {
+      seen.add(v);
+      variants.push(v);
+    }
+  }
+  return variants;
+}
+function searchModelInCosts(model, costsMap) {
+  if (costsMap.size === 0)
+    return;
+  const modelVariants = getModelMatchVariants(model);
+  const costVariantsCache = new Map;
+  function getCostVariants(key) {
+    let variants = costVariantsCache.get(key);
+    if (!variants) {
+      variants = getModelMatchVariants(key);
+      costVariantsCache.set(key, variants);
+    }
+    return variants;
+  }
+  for (const variant of modelVariants) {
+    const pricing = costsMap.get(variant);
+    if (pricing)
+      return pricing;
+  }
+  let bestMatch;
+  let bestMatchLength = 0;
+  for (const [costKey, pricing] of costsMap) {
+    const costVariants = getCostVariants(costKey);
+    for (const modelVariant of modelVariants) {
+      for (const costVariant of costVariants) {
+        if (modelVariant.includes(costVariant) && costVariant.length > bestMatchLength) {
+          bestMatch = pricing;
+          bestMatchLength = costVariant.length;
+        }
+      }
+    }
+  }
+  if (bestMatch)
+    return bestMatch;
+  let reverseMatch;
+  let reverseMatchLength = Infinity;
+  for (const [costKey, pricing] of costsMap) {
+    const costVariants = getCostVariants(costKey);
+    for (const modelVariant of modelVariants) {
+      for (const costVariant of costVariants) {
+        if (costVariant.includes(modelVariant) && costVariant.length < reverseMatchLength) {
+          reverseMatch = pricing;
+          reverseMatchLength = costVariant.length;
+        }
+      }
+    }
+  }
+  return reverseMatch;
+}
+function findPricingForModel(model, options) {
+  if (options?.overrides) {
+    const overrideMap = options.overrides instanceof Map ? options.overrides : new Map(Object.entries(options.overrides).map(([k, v]) => [
+      k.toLowerCase(),
+      v
+    ]));
+    const found = searchModelInCosts(model, overrideMap);
+    if (found)
+      return found;
+  }
+  if (options?.openRouterCache) {
+    const found = searchModelInCosts(model, options.openRouterCache);
+    if (found)
+      return found;
+  }
+  if (options?.warnedModels && !options.warnedModels.has(model.toLowerCase())) {
+    options.warnedModels.add(model.toLowerCase());
+    console.warn(`[bashkit] No pricing found for model "${model}". Cost will not be tracked for this step.`);
+  }
+  return;
+}
+function calculateStepCost(usage, pricing) {
+  let inputCost;
+  const cacheRead = usage.inputTokenDetails?.cacheReadTokens;
+  const cacheWrite = usage.inputTokenDetails?.cacheWriteTokens;
+  const noCache = usage.inputTokenDetails?.noCacheTokens;
+  if (cacheRead != null || cacheWrite != null || noCache != null) {
+    const noCacheCost = (noCache ?? 0) * pricing.inputPerToken;
+    const cacheReadCost = (cacheRead ?? 0) * (pricing.cacheReadPerToken ?? pricing.inputPerToken);
+    const cacheWriteCost = (cacheWrite ?? 0) * (pricing.cacheWritePerToken ?? pricing.inputPerToken);
+    inputCost = noCacheCost + cacheReadCost + cacheWriteCost;
+  } else {
+    inputCost = (usage.inputTokens ?? 0) * pricing.inputPerToken;
+  }
+  const outputCost = (usage.outputTokens ?? 0) * pricing.outputPerToken;
+  return inputCost + outputCost;
+}
+function createBudgetTracker(maxUsd, options) {
+  if (maxUsd <= 0) {
+    throw new Error(`[bashkit] maxUsd must be positive, got ${maxUsd}`);
+  }
+  const overrideMap = options?.modelPricing ? new Map(Object.entries(options.modelPricing).map(([k, v]) => [
+    k.toLowerCase(),
+    v
+  ])) : undefined;
+  const openRouterPricing = options?.openRouterPricing;
+  const onUnpricedModel = options?.onUnpricedModel;
+  const warnedModels = new Set;
+  const pricingCache = new Map;
+  let totalCostUsd = 0;
+  let stepsCompleted = 0;
+  let unpricedSteps = 0;
+  const tracker = {
+    onStepFinish(step) {
+      const modelId = step.response?.modelId;
+      if (!modelId) {
+        unpricedSteps++;
+        stepsCompleted++;
+        return;
+      }
+      let pricing;
+      if (pricingCache.has(modelId)) {
+        pricing = pricingCache.get(modelId);
+      } else {
+        pricing = findPricingForModel(modelId, {
+          overrides: overrideMap,
+          openRouterCache: openRouterPricing,
+          warnedModels
+        });
+        pricingCache.set(modelId, pricing);
+      }
+      if (!pricing) {
+        unpricedSteps++;
+        onUnpricedModel?.(modelId);
+        stepsCompleted++;
+        return;
+      }
+      const cost = calculateStepCost(step.usage, pricing);
+      totalCostUsd += cost;
+      stepsCompleted++;
+    },
+    stopWhen(_options) {
+      return totalCostUsd >= maxUsd;
+    },
+    getStatus() {
+      const remaining = Math.max(0, maxUsd - totalCostUsd);
+      return {
+        totalCostUsd,
+        maxUsd,
+        remainingUsd: remaining,
+        usagePercent: totalCostUsd / maxUsd * 100,
+        stepsCompleted,
+        exceeded: totalCostUsd >= maxUsd,
+        unpricedSteps
+      };
+    }
+  };
+  return tracker;
+}
+
 // src/tools/ask-user.ts
 import { tool, zodSchema } from "ai";
 import { z } from "zod";
@@ -795,17 +1031,17 @@ function reinitDebugMode() {
 // src/tools/ask-user.ts
 var questionOptionSchema = z.object({
   label: z.string().describe("The display text for this option. Should be concise (1-5 words). Add '(Recommended)' suffix for suggested options."),
-  description: z.string().optional().describe("Explanation of what this option means or its implications.")
+  description: z.string().nullable().default(null).describe("Explanation of what this option means or its implications.")
 });
 var structuredQuestionSchema = z.object({
-  header: z.string().optional().describe("Very short label displayed as a chip/tag (max 12 chars). Examples: 'Auth method', 'Library', 'Approach'."),
+  header: z.string().nullable().default(null).describe("Very short label displayed as a chip/tag (max 12 chars). Examples: 'Auth method', 'Library', 'Approach'."),
   question: z.string().describe("The complete question to ask the user. Should be clear and specific."),
-  options: z.array(questionOptionSchema).min(2).max(4).optional().describe("Available choices for this question. 2-4 options. An 'Other' option is automatically available to users."),
-  multiSelect: z.boolean().optional().describe("Set to true to allow the user to select multiple options instead of just one.")
+  options: z.array(questionOptionSchema).min(2).max(4).nullable().default(null).describe("Available choices for this question. 2-4 options. An 'Other' option is automatically available to users."),
+  multiSelect: z.boolean().nullable().default(null).describe("Set to true to allow the user to select multiple options instead of just one.")
 });
 var askUserInputSchema = z.object({
-  question: z.string().optional().describe("Simple question string (for backward compatibility). Use 'questions' for structured multi-choice."),
-  questions: z.array(structuredQuestionSchema).min(1).max(4).optional().describe("Structured questions with options (1-4 questions).")
+  question: z.string().nullable().default(null).describe("Simple question string (for backward compatibility). Use 'questions' for structured multi-choice."),
+  questions: z.array(structuredQuestionSchema).min(1).max(4).nullable().default(null).describe("Structured questions with options (1-4 questions).")
 });
 var ASK_USER_DESCRIPTION = `Use this tool when you need to ask the user questions during execution.
 
@@ -930,9 +1166,9 @@ import { tool as tool2, zodSchema as zodSchema2 } from "ai";
 import { z as z2 } from "zod";
 var bashInputSchema = z2.object({
   command: z2.string().describe("The command to execute"),
-  timeout: z2.number().optional().describe("Optional timeout in milliseconds (max 600000)"),
-  description: z2.string().optional().describe("Clear, concise description of what this command does in 5-10 words"),
-  run_in_background: z2.boolean().optional().describe("Set to true to run this command in the background")
+  timeout: z2.number().nullable().default(null).describe("Optional timeout in milliseconds (max 600000)"),
+  description: z2.string().nullable().default(null).describe("Clear, concise description of what this command does in 5-10 words"),
+  run_in_background: z2.boolean().nullable().default(null).describe("Set to true to run this command in the background")
 });
 var BASH_DESCRIPTION = `Executes a bash command in a persistent shell session with optional timeout.
 
@@ -1049,7 +1285,7 @@ var editInputSchema = z3.object({
   file_path: z3.string().describe("The absolute path to the file to modify"),
   old_string: z3.string().describe("The text to replace"),
   new_string: z3.string().describe("The text to replace it with (must be different from old_string)"),
-  replace_all: z3.boolean().optional().describe("Replace all occurrences of old_string (default false)")
+  replace_all: z3.boolean().nullable().default(null).describe("Replace all occurrences of old_string (default false)")
 });
 var EDIT_DESCRIPTION = `Performs exact string replacements in files.
 
@@ -1079,8 +1315,9 @@ function createEditTool(sandbox, config) {
       file_path,
       old_string,
       new_string,
-      replace_all = false
+      replace_all: rawReplaceAll
     }) => {
+      const replace_all = rawReplaceAll ?? false;
       const startTime = performance.now();
       const debugId = isDebugEnabled() ? debugStart("edit", {
         file_path,
@@ -1330,7 +1567,7 @@ import { tool as tool6, zodSchema as zodSchema6 } from "ai";
 import { z as z6 } from "zod";
 var globInputSchema = z6.object({
   pattern: z6.string().describe('Glob pattern to match files (e.g., "**/*.ts", "src/**/*.js", "*.md")'),
-  path: z6.string().optional().describe("Directory to search in (defaults to working directory)")
+  path: z6.string().nullable().default(null).describe("Directory to search in (defaults to working directory)")
 });
 var GLOB_DESCRIPTION = `
 - Fast file pattern matching tool that works with any codebase size
@@ -1351,7 +1588,7 @@ function createGlobTool(sandbox, config) {
       pattern,
       path
     }) => {
-      const searchPath = path || ".";
+      const searchPath = path ?? ".";
       const startTime = performance.now();
       const debugId = isDebugEnabled() ? debugStart("glob", { pattern, path: searchPath }) : "";
       if (config?.allowedPaths) {
@@ -1403,18 +1640,18 @@ import { tool as tool7, zodSchema as zodSchema7 } from "ai";
 import { z as z7 } from "zod";
 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)"),
-  glob: z7.string().optional().describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")'),
-  type: z7.string().optional().describe('File type to search (e.g. "js", "py", "rust")'),
-  output_mode: z7.enum(["content", "files_with_matches", "count"]).optional().describe('Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts'),
-  "-i": z7.boolean().optional().describe("Case insensitive search"),
-  "-n": z7.boolean().optional().describe("Show line numbers in output. Requires output_mode: 'content'. Defaults to true."),
-  "-B": z7.number().optional().describe("Number of lines to show before each match. Requires output_mode: 'content'."),
-  "-A": z7.number().optional().describe("Number of lines to show after each match. Requires output_mode: 'content'."),
-  "-C": z7.number().optional().describe("Number of lines to show before and after each match. Requires output_mode: 'content'."),
-  head_limit: z7.number().optional().describe("Limit output to first N lines/entries. Works across all output modes. Defaults to 0 (unlimited)."),
-  offset: z7.number().optional().describe("Skip first N lines/entries before applying head_limit. Works across all output modes. Defaults to 0."),
-  multiline: z7.boolean().optional().describe("Enable multiline mode where patterns can span lines. Default: false.")
+  path: z7.string().nullable().default(null).describe("File or directory to search in (defaults to cwd)"),
+  glob: z7.string().nullable().default(null).describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")'),
+  type: z7.string().nullable().default(null).describe('File type to search (e.g. "js", "py", "rust")'),
+  output_mode: z7.enum(["content", "files_with_matches", "count"]).nullable().default(null).describe('Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts'),
+  "-i": z7.boolean().nullable().default(null).describe("Case insensitive search"),
+  "-n": z7.boolean().nullable().default(null).describe("Show line numbers in output. Requires output_mode: 'content'. Defaults to true."),
+  "-B": z7.number().nullable().default(null).describe("Number of lines to show before each match. Requires output_mode: 'content'."),
+  "-A": z7.number().nullable().default(null).describe("Number of lines to show after each match. Requires output_mode: 'content'."),
+  "-C": z7.number().nullable().default(null).describe("Number of lines to show before and after each match. Requires output_mode: 'content'."),
+  head_limit: z7.number().nullable().default(null).describe("Limit output to first N lines/entries. Works across all output modes. Defaults to 0 (unlimited)."),
+  offset: z7.number().nullable().default(null).describe("Skip first N lines/entries before applying head_limit. Works across all output modes. Defaults to 0."),
+  multiline: z7.boolean().nullable().default(null).describe("Enable multiline mode where patterns can span lines. Default: false.")
 });
 var GREP_DESCRIPTION = `A powerful content search tool built on ripgrep with regex support.
 
@@ -1449,15 +1686,17 @@ function createGrepTool(sandbox, config) {
         path,
         glob,
         type,
-        output_mode = "files_with_matches",
+        output_mode: rawOutputMode,
         "-i": caseInsensitive,
         "-B": beforeContext,
         "-A": afterContext,
         "-C": context,
         head_limit,
-        offset = 0,
+        offset: rawOffset,
         multiline
       } = input;
+      const output_mode = rawOutputMode ?? "files_with_matches";
+      const offset = rawOffset ?? 0;
       const searchPath = path || ".";
       const startTime = performance.now();
       const debugId = isDebugEnabled() ? debugStart("grep", {
@@ -1607,7 +1846,7 @@ function parseCountOutput(stdout) {
     total
   };
 }
-function parseContentOutput(stdout, head_limit, offset = 0) {
+function parseContentOutput(stdout, head_limit, offset) {
   const fileData = new Map;
   for (const line of stdout.split(`
 `).filter(Boolean)) {
@@ -1704,8 +1943,8 @@ import { tool as tool8, zodSchema as zodSchema8 } from "ai";
 import { z as z8 } from "zod";
 var readInputSchema = z8.object({
   file_path: z8.string().describe("Absolute path to file or directory"),
-  offset: z8.number().optional().describe("Line number to start reading from (1-indexed)"),
-  limit: z8.number().optional().describe("Maximum number of lines to read")
+  offset: z8.number().nullable().default(null).describe("Line number to start reading from (1-indexed)"),
+  limit: z8.number().nullable().default(null).describe("Maximum number of lines to read")
 });
 var READ_DESCRIPTION = `Reads a file from the local filesystem. You can access any file directly by using this tool.
 Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
@@ -2118,8 +2357,8 @@ async function searchContent(apiKey, provider, options) {
 }
 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"),
-  blocked_domains: z11.array(z11.string()).optional().describe("Never include results from these domains")
+  allowed_domains: z11.array(z11.string()).nullable().default(null).describe("Only include results from these domains"),
+  blocked_domains: z11.array(z11.string()).nullable().default(null).describe("Never include results from these domains")
 });
 var WEB_SEARCH_DESCRIPTION = `Searches the web and returns results with links. Use this for accessing up-to-date information beyond your knowledge cutoff.
 
@@ -2283,8 +2522,8 @@ var taskInputSchema = z13.object({
   description: z13.string().describe("A short (3-5 word) description of the task"),
   prompt: z13.string().describe("The task for the agent to perform"),
   subagent_type: z13.string().describe("The type of specialized agent to use for this task"),
-  system_prompt: z13.string().optional().describe("Optional custom system prompt for this agent. If provided, overrides the default system prompt for the subagent type. Use this to create dynamic, specialized agents on the fly."),
-  tools: z13.array(z13.string()).optional().describe("Optional list of tool names this agent can use (e.g., ['Read', 'Grep', 'WebSearch']). If provided, overrides the default tools for the subagent type. Use this to restrict or expand the agent's capabilities.")
+  system_prompt: z13.string().nullable().default(null).describe("Optional custom system prompt for this agent. If provided, overrides the default system prompt for the subagent type. Use this to create dynamic, specialized agents on the fly."),
+  tools: z13.array(z13.string()).nullable().default(null).describe("Optional list of tool names this agent can use (e.g., ['Read', 'Grep', 'WebSearch']). If provided, overrides the default tools for the subagent type. Use this to restrict or expand the agent's capabilities.")
 });
 var TASK_DESCRIPTION = `Launch a new agent to handle complex, multi-step tasks autonomously.
 
@@ -2336,7 +2575,8 @@ function createTaskTool(config) {
     subagentTypes = {},
     defaultStopWhen,
     defaultOnStepFinish,
-    streamWriter
+    streamWriter,
+    budget
   } = config;
   return tool13({
     description: TASK_DESCRIPTION,
@@ -2364,12 +2604,14 @@ function createTaskTool(config) {
         const model = typeConfig.model || defaultModel;
         const tools = filterTools(allTools, customTools ?? typeConfig.tools, typeConfig.additionalTools);
         const systemPrompt = system_prompt ?? typeConfig.systemPrompt;
+        const baseStopWhen = typeConfig.stopWhen ?? defaultStopWhen ?? stepCountIs(15);
+        const effectiveStopWhen = budget ? [baseStopWhen, budget.stopWhen].flat() : baseStopWhen;
         const commonOptions = {
           model,
           tools,
           system: systemPrompt,
           prompt,
-          stopWhen: typeConfig.stopWhen ?? defaultStopWhen ?? stepCountIs(15),
+          stopWhen: effectiveStopWhen,
           prepareStep: typeConfig.prepareStep
         };
         if (streamWriter) {
@@ -2386,6 +2628,7 @@ function createTaskTool(config) {
           const result2 = streamText({
             ...commonOptions,
             onStepFinish: async (step) => {
+              budget?.onStepFinish(step);
               if (step.toolCalls?.length) {
                 for (const tc of step.toolCalls) {
                   const eventId = generateEventId();
@@ -2460,6 +2703,7 @@ function createTaskTool(config) {
         const result = await generateText2({
           ...commonOptions,
           onStepFinish: async (step) => {
+            budget?.onStepFinish(step);
             await typeConfig.onStepFinish?.(step);
             await defaultOnStepFinish?.({
               subagentType: subagent_type,
@@ -2645,7 +2889,7 @@ function resolveCache(config) {
     enabled
   };
 }
-function createAgentTools(sandbox, config) {
+async function createAgentTools(sandbox, config) {
   const toolsConfig = {
     ...DEFAULT_CONFIG.tools,
     ...config?.tools
@@ -2695,7 +2939,28 @@ function createAgentTools(sandbox, config) {
       }
     }
   }
-  return { tools, planModeState };
+  let budget;
+  if (config?.budget) {
+    const { pricingProvider, apiKey, modelPricing, maxUsd } = config.budget;
+    if (!pricingProvider && !modelPricing) {
+      throw new Error("[bashkit] Budget requires either pricingProvider or modelPricing (or both).");
+    }
+    let openRouterPricing;
+    if (pricingProvider === "openRouter") {
+      try {
+        openRouterPricing = await fetchOpenRouterPricing(apiKey);
+      } catch (err) {
+        if (!modelPricing) {
+          throw new Error(`[bashkit] Failed to fetch OpenRouter pricing and no modelPricing overrides provided. ` + `Either provide modelPricing in your budget config or ensure network access to OpenRouter. ` + `Original error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+    }
+    budget = createBudgetTracker(maxUsd, {
+      modelPricing,
+      openRouterPricing
+    });
+  }
+  return { tools, planModeState, budget };
 }
 // src/utils/compact-conversation.ts
 import { generateText as generateText3 } from "ai";
@@ -3415,6 +3680,7 @@ export {
   createEditTool,
   createE2BSandbox,
   createCompactConfig,
+  createBudgetTracker,
   createBashTool,
   createAskUserTool,
   createAgentTools,

package/dist/tools/ask-user.d.ts

@@ -1,12 +1,12 @@
 export interface QuestionOption {
     label: string;
-    description?: string;
+    description: string | null;
 }
 export interface StructuredQuestion {
-    header?: string;
+    header: string | null;
     question: string;
-    options?: QuestionOption[];
-    multiSelect?: boolean;
+    options: QuestionOption[] | null;
+    multiSelect: boolean | null;
 }
 export interface AskUserSimpleOutput {
     question: string;
@@ -40,14 +40,14 @@ export interface AskUserToolConfig {
  * @param config - Configuration with optional handlers for questions
  */
 export declare function createAskUserTool(config?: AskUserToolConfig | AskUserResponseHandler): import("ai").Tool<{
-    question?: string | undefined;
-    questions?: {
+    question: string | null;
+    questions: {
+        header: string | null;
         question: string;
-        header?: string | undefined;
-        options?: {
+        options: {
             label: string;
-            description?: string | undefined;
-        }[] | undefined;
-        multiSelect?: boolean | undefined;
-    }[] | undefined;
+            description: string | null;
+        }[] | null;
+        multiSelect: boolean | null;
+    }[] | null;
 }, AskUserOutput | AskUserError | AskUserAnswerOutput>;

package/dist/tools/bash.d.ts

@@ -12,7 +12,7 @@ export interface BashError {
 }
 export declare function createBashTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
     command: string;
-    timeout?: number | undefined;
-    description?: string | undefined;
-    run_in_background?: boolean | undefined;
+    timeout: number | null;
+    description: string | null;
+    run_in_background: boolean | null;
 }, BashOutput | BashError>;

package/dist/tools/edit.d.ts

@@ -12,5 +12,5 @@ export declare function createEditTool(sandbox: Sandbox, config?: ToolConfig): i
     file_path: string;
     old_string: string;
     new_string: string;
-    replace_all?: boolean | undefined;
+    replace_all: boolean | null;
 }, EditOutput | EditError>;

package/dist/tools/glob.d.ts

@@ -10,5 +10,5 @@ export interface GlobError {
 }
 export declare function createGlobTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
     pattern: string;
-    path?: string | undefined;
+    path: string | null;
 }, GlobOutput | GlobError>;

package/dist/tools/grep.d.ts

@@ -28,16 +28,16 @@ export interface GrepError {
 export type GrepOutput = GrepContentOutput | GrepFilesOutput | GrepCountOutput | GrepError;
 export declare function createGrepTool(sandbox: Sandbox, config?: GrepToolConfig): import("ai").Tool<{
     pattern: string;
-    path?: string | undefined;
-    glob?: string | undefined;
-    type?: string | undefined;
-    output_mode?: "content" | "count" | "files_with_matches" | undefined;
-    "-i"?: boolean | undefined;
-    "-n"?: boolean | undefined;
-    "-B"?: number | undefined;
-    "-A"?: number | undefined;
-    "-C"?: number | undefined;
-    head_limit?: number | undefined;
-    offset?: number | undefined;
-    multiline?: boolean | undefined;
+    path: string | null;
+    glob: string | null;
+    type: string | null;
+    output_mode: "content" | "count" | "files_with_matches" | null;
+    "-i": boolean | null;
+    "-n": boolean | null;
+    "-B": number | null;
+    "-A": number | null;
+    "-C": number | null;
+    head_limit: number | null;
+    offset: number | null;
+    multiline: boolean | null;
 }, GrepOutput>;

package/dist/tools/index.d.ts

@@ -1,6 +1,7 @@
 import type { ToolSet } from "ai";
 import type { Sandbox } from "../sandbox/interface";
 import type { AgentConfig } from "../types";
+import { type BudgetTracker } from "../utils/budget-tracking";
 import { type PlanModeState } from "./enter-plan-mode";
 /**
  * Result from createAgentTools including tools and optional shared state.
@@ -10,6 +11,8 @@ export interface AgentToolsResult {
     tools: ToolSet;
     /** Shared plan mode state (only present when planMode is enabled) */
     planModeState?: PlanModeState;
+    /** Budget tracker (only present when budget config is set) */
+    budget?: BudgetTracker;
 }
 /**
  * Creates agent tools for AI SDK's generateText/streamText.
@@ -30,24 +33,23 @@ export interface AgentToolsResult {
  *
  * @example
  * // Basic usage (lean default for background agents)
- * const { tools } = createAgentTools(sandbox);
+ * const { tools } = await createAgentTools(sandbox);
  *
  * @example
  * // Interactive agent with plan mode
- * const { tools, planModeState } = createAgentTools(sandbox, {
+ * const { tools, planModeState } = await createAgentTools(sandbox, {
  *   planMode: true,
  *   askUser: { onQuestion: async (q) => await promptUser(q) },
  * });
  *
  * @example
- * // With web and skill tools
- * const { tools } = createAgentTools(sandbox, {
- *   webSearch: { apiKey: process.env.PARALLEL_API_KEY },
- *   skill: { skills: discoveredSkills },
+ * // With budget tracking (OpenRouter pricing)
+ * const { tools, budget } = await createAgentTools(sandbox, {
+ *   budget: { maxUsd: 5.00, pricingProvider: "openRouter" },
  * });
  */
-export declare function createAgentTools(sandbox: Sandbox, config?: AgentConfig): AgentToolsResult;
-export type { AskUserError, AskUserOutput, AskUserResponseHandler, } from "./ask-user";
+export declare function createAgentTools(sandbox: Sandbox, config?: AgentConfig): Promise<AgentToolsResult>;
+export type { AskUserError, AskUserOutput, AskUserResponseHandler, QuestionOption, StructuredQuestion, } from "./ask-user";
 export { createAskUserTool } from "./ask-user";
 export type { BashError, BashOutput } from "./bash";
 export { createBashTool } from "./bash";

package/dist/tools/read.d.ts

@@ -20,6 +20,6 @@ export interface ReadError {
 export type ReadOutput = ReadTextOutput | ReadDirectoryOutput | ReadError;
 export declare function createReadTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
     file_path: string;
-    offset?: number | undefined;
-    limit?: number | undefined;
+    offset: number | null;
+    limit: number | null;
 }, ReadOutput>;

package/dist/tools/task.d.ts

@@ -1,4 +1,5 @@
 import { type ModelMessage, type LanguageModel, type PrepareStepFunction, type StepResult, type StopCondition, type UIMessageStreamWriter, type Tool, type ToolSet } from "ai";
+import type { BudgetTracker } from "../utils/budget-tracking";
 import { z } from "zod";
 export interface TaskOutput {
     result: string;
@@ -17,8 +18,8 @@ declare const taskInputSchema: z.ZodObject<{
     description: z.ZodString;
     prompt: z.ZodString;
     subagent_type: z.ZodString;
-    system_prompt: z.ZodOptional<z.ZodString>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    system_prompt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    tools: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>;
 type TaskInput = z.infer<typeof taskInputSchema>;
 /** Event emitted for each step a subagent takes */
@@ -65,6 +66,8 @@ export interface TaskToolConfig {
     defaultOnStepFinish?: (event: SubagentStepEvent) => void | Promise<void>;
     /** Optional stream writer for real-time subagent activity (uses streamText instead of generateText) */
     streamWriter?: UIMessageStreamWriter;
+    /** Budget tracker — auto-wires stopWhen and onStepFinish for sub-agent cost tracking */
+    budget?: BudgetTracker;
 }
 export declare function createTaskTool(config: TaskToolConfig): Tool<TaskInput, TaskOutput | TaskError>;
 export {};

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

@@ -17,6 +17,6 @@ export interface WebSearchError {
 }
 export declare function createWebSearchTool(config: WebSearchConfig): import("ai").Tool<{
     query: string;
-    allowed_domains?: string[] | undefined;
-    blocked_domains?: string[] | undefined;
+    allowed_domains: string[] | null;
+    blocked_domains: string[] | null;
 }, WebSearchOutput | WebSearchError>;

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type { LanguageModel, Tool } from "ai";
 import type { CacheStore } from "./cache/types";
 import type { SkillMetadata } from "./skills/types";
+import type { ModelPricing } from "./utils/budget-tracking";
 /**
  * SDK tool options picked from the Tool type.
  * This automatically adapts to the user's installed AI SDK version.
@@ -89,6 +90,24 @@ export type CacheConfig = boolean | CacheStore | {
     /** Per-tool overrides - any tool name can be enabled/disabled */
     [toolName: string]: boolean | CacheStore | number | ((toolName: string, key: string) => void) | ((toolName: string, params: unknown) => string) | undefined;
 };
+/**
+ * Supported pricing providers for automatic model cost lookup.
+ */
+export type PricingProvider = "openRouter";
+/**
+ * Budget tracking configuration.
+ * At least one of `pricingProvider` or `modelPricing` must be provided.
+ */
+export type BudgetConfig = {
+    /** Maximum budget in USD (must be positive) */
+    maxUsd: number;
+    /** Pricing provider for automatic model cost lookup. Omit to skip fetching. */
+    pricingProvider?: PricingProvider;
+    /** API key for the pricing provider. Passed as bearer token. */
+    apiKey?: string;
+    /** Per-model pricing overrides (always highest priority over provider data) */
+    modelPricing?: Record<string, ModelPricing>;
+};
 export type AgentConfig = {
     tools?: {
         Bash?: ToolConfig;
@@ -110,6 +129,8 @@ export type AgentConfig = {
     webFetch?: WebFetchConfig;
     /** Enable tool result caching */
     cache?: CacheConfig;
+    /** Budget tracking configuration */
+    budget?: BudgetConfig;
     defaultTimeout?: number;
     workingDirectory?: string;
 };

package/dist/utils/budget-tracking.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Budget tracking for AI agent cost management.
+ *
+ * Tracks cumulative cost across agentic loop steps and stops generation
+ * when a budget is exceeded. Pricing is automatic via OpenRouter's free
+ * public API. Model ID matching uses PostHog's proven 3-tier strategy.
+ */
+import type { LanguageModelUsage, StepResult, StopCondition, ToolSet } from "ai";
+export interface ModelPricing {
+    inputPerToken: number;
+    outputPerToken: number;
+    cacheReadPerToken?: number;
+    cacheWritePerToken?: number;
+}
+export interface BudgetStatus {
+    totalCostUsd: number;
+    maxUsd: number;
+    remainingUsd: number;
+    usagePercent: number;
+    stepsCompleted: number;
+    exceeded: boolean;
+    /** Number of steps where pricing was unavailable (cost tracked as $0). */
+    unpricedSteps: number;
+}
+export interface BudgetTracker {
+    /** Track cost for a completed step. Call from onStepFinish. */
+    onStepFinish: (step: StepResult<ToolSet>) => void;
+    /** Stop condition — returns true when budget exceeded. Compose with other stopWhen conditions. */
+    stopWhen: StopCondition<ToolSet>;
+    /** Get current budget status (cost, remaining, etc.) */
+    getStatus: () => BudgetStatus;
+}
+/**
+ * Fetches model pricing from OpenRouter's public API.
+ * Results are cached at module level. Concurrent calls are deduplicated.
+ *
+ * On failure, throws an error (callers decide whether to rethrow or fall back).
+ */
+export declare function fetchOpenRouterPricing(apiKey?: string): Promise<Map<string, ModelPricing>>;
+/**
+ * Reset the OpenRouter cache. Primarily for testing.
+ * @internal
+ */
+export declare function resetOpenRouterCache(): void;
+/**
+ * Generates match variants for a model ID.
+ * Adapted from PostHog/posthog/nodejs/src/ingestion/ai/costs/cost-model-matching.ts
+ */
+export declare function getModelMatchVariants(model: string): string[];
+/**
+ * Searches for a model's pricing in a cost map using 3-tier matching.
+ *
+ * 1. Exact match (case-insensitive key lookup)
+ * 2. Longest contained match: response model variant *contains* a cost entry variant
+ * 3. Reverse containment: cost entry variant *contains* response model variant
+ */
+export declare function searchModelInCosts(model: string, costsMap: Map<string, ModelPricing>): ModelPricing | undefined;
+/**
+ * Finds pricing for a model, checking user overrides first then OpenRouter cache.
+ * Pass a `warnedModels` set to suppress duplicate warnings per tracker instance.
+ */
+export declare function findPricingForModel(model: string, options?: {
+    overrides?: Record<string, ModelPricing> | Map<string, ModelPricing>;
+    openRouterCache?: Map<string, ModelPricing>;
+    warnedModels?: Set<string>;
+}): ModelPricing | undefined;
+/**
+ * Calculates the cost of a single step based on token usage and pricing.
+ */
+export declare function calculateStepCost(usage: LanguageModelUsage, pricing: ModelPricing): number;
+/**
+ * Creates a budget tracker that monitors cumulative cost across agentic loop steps.
+ *
+ * Pricing is looked up synchronously from a pre-fetched OpenRouter pricing map
+ * and/or user-provided overrides. Use `fetchOpenRouterPricing()` to eagerly load
+ * the map before creating the tracker (this is what `createAgentTools` does).
+ *
+ * @param maxUsd - Maximum budget in USD (must be positive)
+ * @param options - Pricing sources: user overrides and/or pre-fetched OpenRouter map
+ * @returns BudgetTracker instance
+ *
+ * @example
+ * ```typescript
+ * const openRouterPricing = await fetchOpenRouterPricing();
+ * const budget = createBudgetTracker(5.00, { openRouterPricing });
+ *
+ * const result = await generateText({
+ *   model,
+ *   tools,
+ *   stopWhen: [stepCountIs(50), budget.stopWhen],
+ *   onStepFinish: (step) => {
+ *     budget.onStepFinish(step);
+ *     console.log(budget.getStatus());
+ *   },
+ * });
+ * ```
+ */
+export declare function createBudgetTracker(maxUsd: number, options?: {
+    modelPricing?: Record<string, ModelPricing>;
+    openRouterPricing?: Map<string, ModelPricing>;
+    onUnpricedModel?: (modelId: string) => void;
+}): BudgetTracker;

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
+export { type BudgetStatus, type BudgetTracker, type ModelPricing, createBudgetTracker, } from "./budget-tracking";
 export { type CompactConversationConfig, type CompactConversationResult, type CompactConversationState, compactConversation, createCompactConfig, MODEL_CONTEXT_LIMITS, type ModelContextLimit, } from "./compact-conversation";
 export { type ContextMetrics, type ContextStatus, type ContextStatusConfig, type ContextStatusLevel, contextNeedsAttention, contextNeedsCompaction, getContextStatus, } from "./context-status";
 export { type DebugEvent, clearDebugLogs, getDebugLogs, isDebugEnabled, reinitDebugMode, } from "./debug";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bashkit",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Agentic coding tools for the Vercel AI SDK",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,12 +26,17 @@
     "build:cli": "bun build src/cli/init.ts --outdir dist/cli --target node --format esm --external @clack/prompts && chmod +x dist/cli/init.js",
     "build:types": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
     "format": "biome format --write .",
     "format:check": "biome format .",
     "lint": "biome lint --write .",
     "lint:check": "biome lint .",
     "check": "biome check --write .",
     "check:ci": "biome check .",
+    "link-agents": "bash scripts/link-agents-md.sh",
+    "check:agents": "bash scripts/check-agents-md.sh",
     "prepublishOnly": "bun run build"
   },
   "keywords": [
@@ -61,9 +66,11 @@
     "@types/bun": "latest",
     "@types/node": "^24.10.0",
     "@vercel/sandbox": "^1.0.4",
+    "@vitest/coverage-v8": "^3.0.0",
     "ai": "^6.0.0",
     "parallel-web": "^0.2.4",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
   },
   "peerDependencies": {
     "ai": ">=5.0.0",