budget-guard обрывает вызовы Claude на дневном лимите

Библиотека budget-guard оборачивает клиент OpenAI, Anthropic или Gemini и обрывает следующий вызов ошибкой BudgetExceededError, как только расход проекта за день перешагнул заданный dailyCapUSD, например 50 долларов. Исходный код опубликован на Github под лицензией MIT, установка идёт через npm i budget-guard, зависимостей в рантайме нет.

Коротко

• По умолчанию лимит срабатывает на следующем вызове после превышения, поэтому один запрос успевает выйти за рамки; с оценщиком estimator() блокируется сам вызов, который превысил бы порог.
• Счётчик живёт в памяти процесса, в JSON-файле или в Redis, где резервирование выполняет серверный Lua-скрипт, ключи истекают примерно через двое суток, а один лимит делят сразу несколько экземпляров.
• Счётчик подряд идущих ошибок провайдера с порогом retryStormThreshold вызывает onRetryStorm, а успешный вызов сбрасывает серию и проставляет retryCount в событии расхода, поэтому в логах видно, сколько попыток потребовал конкретный оплаченный вызов.

Библиотека закрывает разрыв между дашбордом провайдера, который показывает счёт постфактум, и кодом, который тратит деньги прямо сейчас. Автор ориентируется на независимых разработчиков, видевших «счёт на 40 долларов за задачу на 5», и главный сценарий здесь не большой промпт, а цикл повторов, который всю ночь заново жжёт деньги. Разбивка расхода по фичам, судя по всему, закрывает вторую половину проблемы: понять, какая функция продукта столько стоит.

Оценщик estimator() поднимает счёт токенов новых моделей Claude примерно на 30%

По умолчанию лимит проверяется перед вызовом по уже потраченному, поэтому один запрос может выйти за порог. Если передать estimateUsage: estimator(), библиотека оценивает вход по эвристике «символы делить на четыре», читает prompt, system и messages, берёт объявленный max_tokens или maxOutputTokens и добавляет накладные расходы на схемы инструментов.

Оценщик знает, что новое поколение токенизатора Claude считает примерно на 30% больше токенов (Opus 4.7 и новее, Sonnet 5 и новее, Fable, Mythos), и правит цифру автоматически. Для точного счёта в estimator() подставляется любой сторонний токенизатор, например countTokens из пакета gpt-tokenizer.

Оценённая стоимость резервируется атомарно до вызова и пересчитывается по фактическому расходу после него, поэтому сотня параллельных воркеров не проскакивает лимит наперегонки, а неудачные вызовы откатывают резерв. Файловое хранилище пишет через временный файл с переименованием, а повреждённый файл бросает ошибку вместо тихого обнуления бюджета.

budget-guard распознаёт формат usage у OpenAI, Anthropic, Gemini, Bedrock и Cohere

Форматы полей usage определяются автоматически: OpenAI и совместимые с ним Azure, Mistral, DeepSeek и xAI, Anthropic, usageMetadata у Google Gemini, AWS Bedrock Converse и billed_units у Cohere. Для всего остального в guard передаётся собственный экстрактор usageOf, возвращающий число входных и выходных токенов. Каждому вызову можно проставить тег feature, и тогда spendReport возвращает расход за текущий день с разбивкой по фичам.

Кэшированные и рассуждающие токены считаются по своим тарифам, включая расхождения провайдеров: xAI и Gemini сообщают рассуждающие токены вне выходного счётчика, и библиотека добавляет их обратно. Цены лежат в таблице PRICES в долларах за тысячу токенов. Неизвестный формат ответа по умолчанию бросает ошибку, а опция onMissingUsage: 'zero' отключает это для конкретного guard.

Лимит можно считать не только за сутки: period: 'monthly' и IANA-зона в timezone сбрасывают счётчик по календарю нужного часового пояса, а неверная зона роняет конструктор. Режим onCap: 'warn' оставляет вызовы проходить и только пишет предупреждение, а обработчик onSpend отдаёт стоимость каждого успешного вызова.

Адаптеры закрывают Vercel AI SDK v5 и v7, LangChain.js, LlamaIndex.TS и Mastra

Для Vercel AI SDK предусмотрен budgetGuardMiddleware: модель оборачивается через wrapLanguageModel, форма usage определяется на каждом вызове, поэтому v5 и v7 работают через одну точку входа. Учитываются и generateText, и streamText; при превышении лимита streamText падает до обращения к модели, а ошибка приходит в штатный канал onError.

Агенты Mastra работают на моделях того же SDK, поэтому отдельного кода не требуют. В LangChain.js подключается обработчик BudgetGuardHandler, читающий usage_metadata с откатом к llmOutput.tokenUsage и требующий @langchain/core как необязательную зависимость. Обёртка guardLlamaIndex снимает расход из response.raw, включая потоковый chat(), а при отсутствии usage в потоке выдаёт предупреждение.

В потоковом режиме стоимость списывается один раз после завершения потока. Для OpenAI библиотека сама подставляет stream_options: { include_usage: true }, для Anthropic при provider: 'anthropic' читает события message_start и message_delta, для Gemini берёт usageMetadata из чанков. Типизированные обёртки guardOpenAI, guardAnthropic и guardGemini проставляют provider сами.

Панель с расходами пока в планах. Хостинговая панель со сводным расходом по проектам и оповещениями значится в ROADMAP.md как единственный крупный нерешённый пункт; сроков автор не называет, а SDK, по его словам, останется бесплатным. При переходе с версии 0.1 нужно добавить await к spendReport, остальное совместимо: без указания store поведение счётчика остаётся прежним, в пределах одного процесса.