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

Открытая npm-библиотека budget-guard, опубликованная 19 августа, оборачивает клиент OpenAI, Anthropic или Gemini. Когда дневной лимит проекта исчерпан, она бросает BudgetExceededError ещё до того, как запрос уйдёт к провайдеру и будет оплачен. По умолчанию лимит пропускает один лишний вызов. Эту дыру закрывает встроенный оценщик токенов, и он учитывает новый токенизатор Claude.
Код лежит на GitHub под лицензией MIT, зависимостей в рантайме нет. Запросы идут к провайдеру напрямую, без прокси: библиотека только считает расход и обрывает вызовы. Автор пишет, что делал её для инди-разработчиков, которым уже приходил «счёт на 40 долларов за задачу на 5». В планах хостинговый дашборд со сводкой расходов по проектам и алертами, а сам SDK, по словам автора, бесплатный и таким останется.
Как считаются деньги
Подключение занимает одну строку: guard(openai.chat.completions, { project: 'my-app', dailyCapUSD: 50 }). Дальше обёрнутый клиент вызывают как обычно, а вторым аргументом можно передать метку фичи вроде { feature: 'chat' }. Все обёртки с одним project делят общий лимит. spendReport('my-app') возвращает расход за сегодня по фичам, например { chat: 2.41, summarize: 0.88 } в долларах. После версии 0.1 эта функция стала асинхронной, и при обновлении нужно добавить await. В остальном совместимость сохранена.
Формат поля usage в ответе библиотека определяет сама. Поддерживаются OpenAI (включая Azure, Mistral, DeepSeek и xAI), Anthropic, Gemini с его usageMetadata, AWS Bedrock Converse и Cohere с billed_units. Кэшированные токены и токены рассуждений считаются по своим тарифам. Отдельно учтена особенность xAI и Gemini: они отдают токены рассуждений вне счётчика выходных, и budget-guard прибавляет их обратно, чтобы расход не занижался. Для остальных провайдеров можно передать свою функцию usageOf. Если формат ответа незнаком, библиотека по умолчанию бросает ошибку и не записывает ноль. Автор объясняет это так: инструмент бюджета не должен тихо перестать считать. Отключается это флагом onMissingUsage: 'zero'. Цены зашиты в таблицу PRICES в долларах за тысячу токенов, и поддерживать её актуальной автор предлагает пулл-реквестами.
Стриминг тоже считается. Для OpenAI библиотека сама добавляет stream_options: { include_usage: true }, потому что без этого флага OpenAI не присылает usage в последнем чанке. Для стрима Anthropic нужно указать provider: 'anthropic', тогда расход читается из событий message_start и message_delta. Чтобы не забыть этот параметр, есть обёртки guardAnthropic, guardOpenAI и guardGemini. Адаптеры написаны для Vercel AI SDK (v5 и v7, в виде middleware), LangChain.js (через callback handler), LlamaIndex.TS и Mastra. Агенты Mastra работают на моделях AI SDK, так что им хватает того же middleware. У AI SDK есть ловушка, о которой предупреждает README: если лимит исчерпан, streamText блокирует вызов, но ошибка приходит через onError или await result.text, а textStream по умолчанию ошибки стрима проглатывает.
Когда срабатывает лимит
По умолчанию проверка идёт по уже учтённому расходу. Если за сегодня потрачено больше 50 долларов, следующий вызов упадёт. Но вызов, который этот порог пересёк, успеет пройти и будет оплачен целиком, а запросы, которые ещё выполняются, в сумму пока не попали. Для параллельной нагрузки README прямо советует подключить оценщик. По сути, жёстким лимит делает именно estimateUsage: estimator(), а не сам dailyCapUSD.
Встроенный estimator() считает грубо, но для аварийного выключателя этого, по мнению автора, хватает. Длину входа он оценивает как число символов в prompt, system и messages, делённое на четыре. Для выхода берёт объявленный max_tokens (или maxOutputTokens). Если передаются инструменты, он добавляет накладные расходы на их схемы. Для точных цифр можно подставить любой токенизатор, например countTokens из gpt-tokenizer.
Если хранилище умеет атомарную операцию addIfUnder (её поддерживают все три встроенных), оценённая стоимость резервируется до вызова, а после ответа заменяется фактической. Упавший вызов снимает свой резерв. Автор утверждает, что так 100 параллельных воркеров не смогут вместе проскочить лимит. В примерах есть сценарий с 20 одновременными вызовами.
Поправка на 30%
Оценщик знает, что токенизатор Claude нового поколения на тот же текст выдаёт примерно на 30% больше токенов, и сам поправляет оценку для Opus 4.7 и новее, Sonnet 5 и новее, Fable и Mythos. Как пишет Developers Digest, Opus 4.8 стоит те же 5 долларов за миллион входных и 25 за миллион выходных токенов, что и Opus 4.6, но счёт может выйти выше, потому что в миллион токенов теперь помещается меньше текста.
Заложенные в оценщик 30% ниже верхней границы, которую называла сама Anthropic. По цитате того же издания, в июне 2026 года страница цен Anthropic говорила, что новый токенизатор «может использовать до 35% больше токенов» на тот же текст, а гайд по миграции давал диапазон примерно от 1x до 1,35x в зависимости от содержимого и советовал поднять max_tokens с запасом. Позже, при перепроверке 11 октября, на странице цен осталось «примерно 30%» без верхней границы в 35%. На коротких строках расхождение бывает больше: в августе неофициальный пакет ctok насчитал на «hello, world» 10 токенов на старом словаре и 15 на словаре 4.7. Anthropic в документации по подсчёту токенов советует замерить коэффициент на своих типичных промптах и не полагаться на фиксированный процент.
Где хранить счётчик
По умолчанию счётчик живёт в памяти процесса. Для одного скрипта, воркера или агента этого хватает, а для cron-задач нет: каждый запуск начинается с нуля долларов. Поэтому есть fileStore, который держит учёт в одном JSON-файле, и тогда, по примеру автора, 100 запусков в день делят один лимит. Запись атомарная (временный файл и переименование), а повреждённый файл вызывает ошибку и не обнуляет бюджет. Рассчитан fileStore на последовательные запуски. Одновременно работающим процессам README велит брать Redis.
redisStore реализует резервирование серверным Lua-скриптом, ключи сами истекают примерно через два дня. В документации Redis описана та же проблема: локальные счётчики в каждом процессе ломаются за балансировщиком, потому что клиент обходит лимит, попадая на разные инстансы. Там же объясняется, что Lua через EVAL выполняет чтение, проверку и запись как одну операцию, поэтому параллельные запросы не могут дважды потратить один бюджет. Путь с резервированием в Redis проверяется в CI на настоящем Redis: атомарность, TTL и откат при ошибке NOSCRIPT.
Лимит можно считать на месяц (period: 'monthly') и сбрасывать по календарю своего часового пояса через timezone в формате IANA. Ошибка в названии зоны падает уже при создании обёртки. С Redis для месячного лимита TTL нужно поднять примерно до 40 дней, иначе счётчики истекут раньше времени. Для плавного внедрения есть onCap: 'warn': при превышении пишется предупреждение, а вызов проходит. В budget-guard/testing лежат фабрики usage, фиксированные часы для проверки границ дня и месяца и хранилище, которое записывает каждую операцию.
Циклы повторов
Самой дорогой ошибкой с LLM автор считает не большой промпт, а цикл повторов, который всю ночь тихо жжёт деньги. Библиотека считает подряд идущие ошибки провайдера отдельно для каждой пары фичи и модели. Когда серия доходит до retryStormThreshold, один раз вызывается onRetryStorm. Вызовы, заблокированные лимитом, не считаются, учитываются только дошедшие до провайдера. Колбэк onSpend срабатывает после каждого успешного вызова с проектом, фичей, моделью, стоимостью и суммой за день, причём синхронно, перед возвратом ответа. Поэтому тяжёлую работу автор советует отправлять в очередь.
Успешный вызов обнуляет серию и записывает в событие о расходе поле retryCount. В логах тогда видна строка вида «этот вызов за 0,40 доллара занял 7 попыток».
Дальше
Free Mode в Replit снимает плату за токены
«Без оглядки на стоимость токенов», так OpenAI описывает режим Free Mode в Replit на GPT-5.6 Luna. Цену самой модели OpenAI снизила на 80% в конце июля.
Читайте также
- AI Usage Ball следит за остатком квоты Claude на Mac
- Claude в Linear и Ramp можно оплачивать без API-ключа
- Tokendoctor обещает тот же Claude Code до 38% дешевле
- Плагин Chisle сжимает для Claude Code и вывод команд
- Неделя Ultra в Claude Code: 1 200-3 700 долларов по API
- Память и навыки Claude Code получили git-историю в memsaga
Комментарии
Пока никто не написал. Будьте первым.
Присоединяйтесь к разговору
Войдите, чтобы оставить комментарий. Он появится после модерации.

