bot/setup.md

# Setup

## Requirements

- Node.js 20+ or newer
- npm
- A Telegram bot token from `@BotFather`

## Project Setup

1. Install dependencies:

```bash
npm install
```

2. Create `.env` from `.env.example` and fill in your bot token:

```env
BOT_TOKEN=your_telegram_bot_token_here
BOT_API_ROOT=
BOT_CONNECTOR=local-codex
LOCAL_CODEX_COMMAND=codex
LOCAL_CODEX_WORKDIR=
LOCAL_CODEX_SANDBOX=workspace-write
LOCAL_CODEX_MODEL=
LOCAL_CODEX_PROFILE=
LOCAL_CODEX_SKIP_GIT_REPO_CHECK=
LOCAL_CODEX_ADD_DIRS=
```

3. Start the bot:

```bash
npm start
```

## What The Bot Does

- Saves text messages to `assets/request.txt` by appending new lines
- Saves photos, videos, voice messages, and documents to `assets/`
- Immediately replies with `Сообщение доставлено ИИ агенту, оно обрабатывается`
- Sends the saved request to the configured connector strategy
- Returns the connector result back to Telegram as a follow-up reply

## Connector Strategy

The bot uses a connector strategy selected by `BOT_CONNECTOR`.

### `local-codex`

Runs the local `codex` CLI with `codex exec` for every supported Telegram message.
The connector expects structured JSON output with:

- `message`: text reply for Telegram
- `attachments`: files to upload back to the user
- attachment fields: `path`, `kind`, `caption`

Supported attachment `kind` values:

- `photo`
- `video`
- `animation`
- `document`

If Codex generates an image, video, or any other file for the user, it should include that file path in `attachments`. Relative paths are resolved from `LOCAL_CODEX_WORKDIR`.

Relevant variables:

- `BOT_CONNECTOR=local-codex`
- `LOCAL_CODEX_COMMAND=codex`
- `LOCAL_CODEX_WORKDIR=`: working directory for Codex. Empty means this project root.
- `LOCAL_CODEX_SANDBOX=workspace-write`: sandbox mode passed to `codex exec`
- `LOCAL_CODEX_MODEL=`: optional model override
- `LOCAL_CODEX_PROFILE=`: optional Codex profile
- `LOCAL_CODEX_SKIP_GIT_REPO_CHECK=`: set to `true` if the Codex workdir is not a git repo
- `LOCAL_CODEX_ADD_DIRS=`: comma-separated extra directories for Codex access

The connector queue is sequential, so messages are processed one by one in arrival order.

## Optional: Local Bot API Server For Files Larger Than 20 MB

Telegram's hosted Bot API cannot download files larger than `20 MB`. To support larger files, run a local `telegram-bot-api` server and point the bot to it with `BOT_API_ROOT`.

Official references:

- https://github.com/tdlib/telegram-bot-api
- https://core.telegram.org/bots/api#using-a-local-bot-api-server
- https://grammy.dev/guide/api.html

### 1. Get `api_id` and `api_hash`

Create them here:

- https://core.telegram.org/api/obtaining_api_id

### 2. Build The Local Bot API Server In `~/dev/lamda/bot_api`

The commands below match the local layout already prepared on this machine.

```bash
mkdir -p ~/dev/lamda/bot_api

~/miniconda3/bin/conda create -y \
  -p ~/dev/lamda/bot_api/.buildenv \
  --override-channels \
  -c conda-forge \
  gperf openssl zlib cmake

git clone --recursive https://github.com/tdlib/telegram-bot-api.git ~/dev/lamda/bot_api/telegram-bot-api

git -C ~/dev/lamda/bot_api/telegram-bot-api submodule update --init --depth 1 td

mkdir -p ~/dev/lamda/bot_api/telegram-bot-api/build
mkdir -p ~/dev/lamda/bot_api/install

export PATH=~/dev/lamda/bot_api/.buildenv/bin:$PATH
export CMAKE_PREFIX_PATH=~/dev/lamda/bot_api/.buildenv

cmake -S ~/dev/lamda/bot_api/telegram-bot-api \
  -B ~/dev/lamda/bot_api/telegram-bot-api/build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=~/dev/lamda/bot_api/install \
  -DOPENSSL_ROOT_DIR=~/dev/lamda/bot_api/.buildenv \
  -DZLIB_ROOT=~/dev/lamda/bot_api/.buildenv

cmake --build ~/dev/lamda/bot_api/telegram-bot-api/build -j"$(nproc)"
cmake --install ~/dev/lamda/bot_api/telegram-bot-api/build
```

### 3. Start The Local Bot API Server

```bash
mkdir -p ~/dev/lamda/bot_api/data
mkdir -p ~/dev/lamda/bot_api/tmp

~/dev/lamda/bot_api/install/bin/telegram-bot-api \
  --api-id <API_ID> \
  --api-hash <API_HASH> \
  --local \
  --http-port 8081 \
  --dir ~/dev/lamda/bot_api/data \
  --temp-dir ~/dev/lamda/bot_api/tmp
```

### 4. Switch The Bot To The Local Server

Before switching away from Telegram's hosted Bot API, log the bot out there once:

```text
https://api.telegram.org/bot<BOT_TOKEN>/logOut
```

Then set this in `.env`:

```env
BOT_TOKEN=your_telegram_bot_token_here
BOT_API_ROOT=http://127.0.0.1:8081
BOT_CONNECTOR=local-codex
```

Restart the bot after that:

```bash
npm start
```

## Notes

- `BOT_API_ROOT` is optional. Leave it empty to use the default Telegram hosted Bot API.
- The local Bot API server listens over HTTP by default.
- If both the bot and the local Bot API server run on the same machine, `127.0.0.1:8081` is enough.
- `BOT_CONNECTOR` defaults to `local-codex` in the current setup.