Nova/AGENTS.md

Repository Guidelines

Project Structure

NOVA is a TypeScript Telegram AI bot. Two source files hold everything:

• index.ts — entry point, calls startNova() from src/bot.ts
• src/bot.ts — ~7000 lines, single file containing all bot logic (Telegram polling, Gemini tool calling, session management, admin commands, image gen, voice, reminders, PDF, web apps, scheduler)
• src/kv.ts — SqliteKV class implementing a Cloudflare-KV-style interface over better-sqlite3 (kv_store table with optional TTL)
• nova.db — runtime SQLite database (gitignored; /data/nova.db inside Docker)

There is no build step. tsx runs TypeScript directly.

Commands

npm install            # install deps
npm run dev            # tsx watch index.ts — auto-restart on change
npm start              # tsx index.ts — production long-polling
npm run type-check     # tsc --noEmit — required validation before submitting
docker compose up -d   # container with restart policy, healthcheck, persistent nova-data volume

There is no test framework. npm run type-check is the only automated check.

Architecture Notes

• Update mode: Telegram Bot API long polling via getUpdates. No webhooks.
• Express server on PORT (default 3000): serves /health endpoint and hosted web apps at /app/:name.
• Scheduler: setInterval calls runScheduled() every 5 minutes for reminders, broadcasts, and cleanup.
• Session model: ChatSession stored in KV under session:<chatId>. In-memory CacheLayer<ChatSession> (200 entries, 3 min TTL) wraps hot reads.
• Tool calling: Gemini function-calling drives bot features (image gen, web search, voice, PDF, reminders, admin actions). Tool results fed back as functionResponse parts.
• Key rotation: Gemini keys (GEMINI_KEY_1..5), ElevenLabs keys (ELEVENLABS_KEY_1..5), Cloudflare pairs (CF_ID_1..3/CF_TOKEN_1..3). Disabled keys tracked in KV, auto-rotated on failure.
• Rate limiting: TokenBucket per user, daily limits per session type, in-memory dedup via activeProgressMessages.
• Bot config: persisted in KV under bot_config key with runtime defaults. Editable via owner Telegram commands.
• Bot version: BOT_VERSION constant at top of src/bot.ts.

Coding Conventions

• TypeScript strict mode. Two-space indent, semicolons, single quotes.
• camelCase for functions/variables, PascalCase for interfaces/classes.
• Sections in bot.ts are separated by // SECTION: comment banners — keep new logic in labeled sections.
• Prefer typed interfaces; avoid any unless local and unavoidable.
• State goes through SqliteKV (async API matching Cloudflare KV). Never read/write nova.db directly.

Configuration

Loaded from .env via dotenv/config (imported as first line in bot.ts). Required:

• TOKEN — Telegram bot token (app exits if missing)
• BOT_OWNER_ID — primary owner user ID (number)
• ADDITIONAL_OWNER_IDS — comma-separated extra owner IDs

Optional provider keys: GEMINI_KEY_*, ELEVENLABS_KEY_*, CF_ID_*/CF_TOKEN_*, GOOGLE_SEARCH_API_KEY, GOOGLE_SEARCH_ENGINE_ID.

DB_PATH defaults to ./nova.db, overridden to /data/nova.db in Docker.

Security Constraints

• /eval is permanently disabled. Never reintroduce shell access, child_process, runtime JS eval, or AI-triggered command execution.
• Owner access is strictly via BOT_OWNER_ID + ADDITIONAL_OWNER_IDS env vars. No username-based or hidden escalation.
• .env, API keys, bot tokens, and Cloudflare tokens are sensitive. Never log or commit them.