bashkit 0.4.0 → 0.5.0

package/AGENTS.md

@@ -92,6 +92,21 @@ 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)

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

@@ -5,12 +5,12 @@ export { createE2BSandbox, createLocalSandbox, createVercelSandbox, ensureSandbo
 export type { ExecOptions, ExecResult, Sandbox } from "./sandbox/interface";
 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";
@@ -2339,7 +2575,8 @@ function createTaskTool(config) {
     subagentTypes = {},
     defaultStopWhen,
     defaultOnStepFinish,
-    streamWriter
+    streamWriter,
+    budget
   } = config;
   return tool13({
     description: TASK_DESCRIPTION,
@@ -2367,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) {
@@ -2389,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();
@@ -2463,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,
@@ -2648,7 +2889,7 @@ function resolveCache(config) {
     enabled
   };
 }
-function createAgentTools(sandbox, config) {
+async function createAgentTools(sandbox, config) {
   const toolsConfig = {
     ...DEFAULT_CONFIG.tools,
     ...config?.tools
@@ -2698,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";
@@ -3418,6 +3680,7 @@ export {
   createEditTool,
   createE2BSandbox,
   createCompactConfig,
+  createBudgetTracker,
   createBashTool,
   createAskUserTool,
   createAgentTools,

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,23 +33,22 @@ 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 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";

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;
@@ -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/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.4.0",
+  "version": "0.5.0",
   "description": "Agentic coding tools for the Vercel AI SDK",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,6 +35,8 @@
     "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": [