Usage Limits Skill

КРИТИЧЕСКИ ВАЖНО: Этот skill ДОЛЖЕН выполняться ПЕРВЫМ при получении любого сообщения из Telegram!

Когда использовать

Автоматически срабатывает при каждом входящем Telegram сообщении ДО начала обработки.

Алгоритм

1. Извлечь Telegram Chat ID из контекста сообщения
2. Проверить лимит через HTTP запрос к agent-brain
3. Если лимит превышен - отправить сообщение пользователю и прервать обработку
4. Если лимит в порядке - продолжить обработку сообщения

Проверка лимита

Endpoint: GET http://agent-brain:7080/api/limits/check

Headers:

• X-Telegram-Id: <TELEGRAM_CHAT_ID>

Пример запроса:

curl -s -X GET http://agent-brain:7080/api/limits/check \
  -H "X-Telegram-Id: 313145981"

Успешный ответ (лимит в порядке):

{
  "allowed": true,
  "remaining": 0.73,
  "limit": 1.00,
  "spent": 0.27,
  "nearLimit": false
}

Ответ при превышении лимита:

{
  "allowed": false,
  "remaining": 0,
  "limit": 1.00,
  "spent": 1.05
}

Обработка результата

✅ Лимит в порядке (allowed: true)

Продолжить обработку сообщения как обычно.

Если nearLimit: true (использовано >=80%), показать предупреждение:

⚠️ Внимание: Использовано 85% дневного лимита AI.

Осталось: 15%

❌ Лимит превышен (allowed: false)

НЕМЕДЛЕННО отправить пользователю сообщение и ПРЕРВАТЬ обработку:

⚠️ Превышен дневной лимит использования AI

Использовано: 105% дневного лимита

Попробуйте завтра или обратитесь в поддержку для увеличения лимита.

НЕ продолжать обработку запроса!

Извлечение Telegram Chat ID

Telegram Chat ID доступен в метаданных сообщения:

• Формат: [Telegram Анатолий Степанов (@username) id:313145981 ...]
• Или через префикс сообщения: [Telegram Chat ID: 313145981]

Извлечь числовой ID из этих метаданных.

Обработка ошибок

Если запрос к agent-brain не удался (timeout, 500, network error):

1. Логировать ошибку
2. Разрешить запрос (fail-open стратегия)
3. НЕ блокировать пользователя при сбое системы лимитов

# Пример с обработкой ошибок
RESPONSE=$(curl -s -w "\n%{http_code}" -X GET http://agent-brain:7080/api/limits/check \
  -H "X-Telegram-Id: 313145981" \
  --connect-timeout 5 \
  --max-time 10)

HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | head -n-1)

if [ "$HTTP_CODE" != "200" ]; then
  echo "⚠️ Не удалось проверить лимит (код: $HTTP_CODE). Разрешаю запрос (fail-open)."
  # Продолжить обработку
fi

Запись использования

ОБЯЗАТЕЛЬНО после каждого успешного ответа отправить данные об использовании:

Endpoint: POST http://agent-brain:7080/api/limits/track

Headers:

• Content-Type: application/json
• X-Telegram-Id: <TELEGRAM_CHAT_ID>

Body:

{
  "model": "gpt-5.2",
  "usage": {
    "prompt_tokens": 1234,
    "completion_tokens": 567
  }
}

Пример запроса:

curl -s -X POST http://agent-brain:7080/api/limits/track \
  -H "Content-Type: application/json" \
  -H "X-Telegram-Id: 313145981" \
  -d '{
    "model": "gpt-5.2",
    "usage": {
      "prompt_tokens": 1234,
      "completion_tokens": 567
    }
  }'

Ответ:

{
  "success": true,
  "cost_usd": 0.010098,
  "total_spent_today": 0.273456
}

Откуда взять данные usage?

После завершения запроса к AI модели, в ответе будут доступны:

• prompt_tokens - количество токенов в промпте
• completion_tokens - количество токенов в ответе
• model - использованная модель (gpt-5.2, claude-sonnet-4-20250514, gpt-4o)

Эти данные ДОЛЖНЫ быть отправлены в agent-brain для отслеживания затрат.

Примеры использования

Пример 1: Нормальный запрос

User: Покажи статистику кампаний
↓
[Skill: usage-limits]
  → curl GET /api/limits/check -H "X-Telegram-Id: 313145981"
  ← {"allowed": true, "remaining": 0.85, ...}
  → Лимит ОК, продолжаю
↓
[Обработка запроса через getCampaigns]

Пример 2: Близко к лимиту

User: Создай новую кампанию
↓
[Skill: usage-limits]
  → curl GET /api/limits/check
  ← {"allowed": true, "remaining": 0.12, "nearLimit": true, ...}
  → Отправляю предупреждение
  ⚠️ Внимание: Вы использовали 88% дневного лимита...
↓
[Продолжаю обработку запроса]

Пример 3: Лимит превышен

User: Покажи отчёт
↓
[Skill: usage-limits]
  → curl GET /api/limits/check
  ← {"allowed": false, "spent": 1.05, ...}
  → ❌ ПРЕРЫВАЮ обработку

⚠️ Превышен дневной лимит затрат...

[НЕ продолжаю обработку]

Технические детали

• Приоритет: 1000 (выполняется первым)
• Trigger: on_message (каждое сообщение)
• Timeout: 5 секунд на проверку
• Fallback: fail-open при ошибке
• Логирование: Все проверки логируются в agent-brain

---

⚠️ ВАЖНО: Без этого skill пользователи Telegram могут генерировать неограниченные затраты на AI API!