# AGENTS

## Назначение
- `codex-agent-VPS` — переносимая версия Telegram-бота для запуска `codex` CLI на VPS.
- Папку можно ставить в любое место на Linux-сервере, если там есть `python3`, `systemd`, `codex` и доступ в интернет.
- Конфигурация делается через `.env`.

## Состав папки
- `py_bot_service.py` — основная реализация сервиса.
- `AGENT.md` — инструкции, которые бот передаёт в промпт Codex.
- `.env.example` — пример конфигурации.
- `scripts/systemd/shine-agent-bot-coder.service` — шаблон systemd unit.

## Требования к VPS
- Linux-сервер с `systemd`.
- Установленные `python3`, `curl`, `ffmpeg`.
- Установленный `codex` CLI.
- Выполненный `codex login` под тем пользователем, от которого будет работать сервис.
- Telegram bot token.
- Telegram usernames разрешённых пользователей.

## Установка через Codex
1. Скопировать папку `codex-agent-VPS` на сервер в нужное место, например:
   - `/home/your_user/codex-agent`
2. Установить `codex` CLI под рабочим пользователем.
3. Выполнить под этим же пользователем:
   - `codex login`
4. Установить системные зависимости:
   - `python3`
   - `ffmpeg`
5. Скопировать `.env.example` в `.env`.
6. В `.env` заполнить:
   - `TELEGRAM_BOT_TOKEN`
   - `ALLOWED_TELEGRAM_USERNAME`
   - `ALLOWED_TELEGRAM_PLAYERS`
   - `BOT_USERNAME`
   - `CODEX_BIN`
   - `CODEX_WORKDIR`
7. Если нужны voice/audio и голосовые ответы, дополнительно задать:
   - `OPENAI_API_KEY`
8. В `scripts/systemd/shine-agent-bot-coder.service` заменить:
   - `your_user`
   - `/home/your_user/codex-agent`
   на реальные значения.
9. Скопировать unit в:
   - `/etc/systemd/system/shine-agent-bot-coder.service`
10. Выполнить:
   - `sudo systemctl daemon-reload`
   - `sudo systemctl enable --now shine-agent-bot-coder`
11. Проверить:
   - `sudo systemctl status shine-agent-bot-coder --no-pager`
   - `sudo journalctl -u shine-agent-bot-coder -f`

## Настройка доступа
- `ALLOWED_TELEGRAM_USERNAME` — основной разрешённый пользователь.
- `ALLOWED_TELEGRAM_PLAYERS` — дополнительные разрешённые пользователи:
  - `username1:Имя 1,username2:Имя 2`
- Все пользователи из whitelist в этой версии считаются полноправными.
- Все входящие задачи попадают в одну общую очередь и выполняются строго последовательно.

## Поведение агента
- Бот принимает текст, voice и audio.
- Для каждого пользователя ведётся отдельная история.
- Все задачи запускаются через `codex exec`.
- Рабочая директория задаётся через `CODEX_WORKDIR`.
- Вызов идёт без sandbox/approval ограничений: `--dangerously-bypass-approvals-and-sandbox`.

## Что обычно меняют при переносе
- `.env`
- `scripts/systemd/shine-agent-bot-coder.service`
- при необходимости `AGENT.md`

## Полезные команды
- Проверка установки Codex:
  - `codex --version`
  - `codex doctor`
- Self-test без Telegram:
  - `python3 py_bot_service.py --selftest-codex "Ответь одной строкой: Codex работает"`
- Проверка сервиса:
  - `sudo systemctl status shine-agent-bot-coder --no-pager`
  - `sudo journalctl -u shine-agent-bot-coder -f`

## Примечания
- Если `codex doctor` пишет, что credentials не найдены, нужно выполнить `codex login`.
- Если `OPENAI_API_KEY` пустой, текстовые задачи через `codex` будут работать, а voice/audio и TTS-функции — нет.
- Если у пользователя в Telegram нет username, whitelist по username его не пропустит.