# ─────────────────────────────────────────────────────────────────────────────
# Grok Telegram Bot — configuration
# Copy this file to .env and fill in the values, or run:  npm run setup
# ─────────────────────────────────────────────────────────────────────────────

# REQUIRED — Telegram bot token from @BotFather (https://t.me/BotFather)
TELEGRAM_BOT_TOKEN=

# RECOMMENDED — comma-separated Telegram user IDs allowed to use the bot
# (private chats AND groups / forum topics). Get yours from @userinfobot.
# Example: ALLOWED_USERS=123456789,987654321
# If empty, ANYONE can use the bot (unsafe — especially with TOPIC_GROUP_ID).
# Unauthorized group members are ignored silently (no ⛔ spam in the group).
ALLOWED_USERS=

# ── Grok Build CLI ───────────────────────────────────────────────────────────
# Path to the `grok` binary. Leave blank to use "grok" from PATH.
# The official installer puts it in ~/.grok/bin/grok (install with:
#   curl -fsSL https://x.ai/cli/install.sh | bash   — needs SuperGrok / X Premium+)
GROK_CLI_PATH=

# Auth: sign in with your xAI account by running `grok login` once (or use the
# bot's /reauth). No API key needed. On a headless host with no browser, you can
# instead set an xAI API key here (exported to the agent as XAI_API_KEY):
# XAI_API_KEY=

# Default model that powers Grok Build.
GROK_MODEL=grok-4.5

# Default workspace directory used when you start without picking a project.
GROK_WORKSPACE=

# Pass --always-approve to `grok agent stdio` so tool calls run without inline
# permission prompts. Set false to get Approve/Deny buttons in Telegram before
# Grok runs risky tools (file writes, shell commands) — ACP "ask" mode.
GROK_TRUST_ALL_TOOLS=true

# Auto-approve ACP permission requests, preferring "allow for this session".
# Defaults true. Set false (and GROK_TRUST_ALL_TOOLS=false) for interactive
# Approve/Deny buttons in Telegram.
AUTO_APPROVE_PERMISSIONS=true

# Auto-approve Grok plan-mode exit (no Approve / Request changes / Abandon).
# Default true so 24/7 unattended bots never wait. Set false for Telegram review.
# AUTO_APPROVE_PLAN=true

# Optional Grok agent env (applied on process start / after /restart).
# GROK_SANDBOX=workspace-safe
# GROK_MEMORY=
# GROK_AGENT_PROFILE=
# GROK_PLUGIN_DIR=

# Named instance slug (same as grok-tg --name). Optional.
# GROK_TG_NAME=

# Comma-separated roots the /projects browser is allowed to list.
# Supports ~ for home directory. Defaults to GROK_WORKSPACE's parent + home.
# Example: H:\Lucru\Domains,C:\Lucru\Domains
PROJECT_ROOTS=

# Where the bot stores the sessions it drives (<id>.json/.jsonl/.lock). Defaults
# to <data>/sessions. Grok itself keeps sessions in its own SQLite store.
# SESSIONS_DIR=

# ── Rendering / streaming ────────────────────────────────────────────────────
# How often (ms) to edit the streaming message while the agent is typing.
STREAM_THROTTLE_MS=1500

# Coalesce rapid consecutive text messages (a long message Telegram split at
# 4096 chars) into one prompt. 0 = disable.
MESSAGE_BATCH_MS=800

# Show tool-call status messages (file reads/writes, commands). true/false
SHOW_TOOL_CALLS=true

# Show unified diffs for file edits. true/false
SHOW_EDIT_DIFFS=true

# Max lines of a diff to show inline before truncating.
DIFF_MAX_LINES=120

# Send images the agent produces this turn back to Telegram automatically, and
# a per-turn cap.
SEND_AGENT_IMAGES=true
AGENT_IMAGES_MAX=8

# Max characters of a text file attachment inlined into the prompt (0 = unlimited).
DOC_MAX_CHARS=100000

# Show sub-agent activity while the main agent waits on its sub-agents (Grok
# delegates larger tasks to parallel sub-agents). true/false
SHOW_SUBAGENTS=true

# Task-progress bar. SHOW_PROGRESS asks the agent to end each message with a
# {progress: N%} marker (hidden and rendered as a green 0–100% bar). PROGRESS_FALLBACK
# shows a bot-computed bar from real activity when the model emits no marker.
SHOW_PROGRESS=true
PROGRESS_FALLBACK=true

# Deliver a background session's "Done" summary even while you're viewing another
# session (marked "From other session"). true/false
NOTIFY_OTHER_SESSIONS=true

# ── Post-turn suggestions ────────────────────────────────────────────────────
# After a successful Done, quietly ask Grok for 1–3 follow-up steps (JSON with
# a need score 0–100). Shown as inline buttons on the Done message.
# SUGGESTIONS_ENABLED=true
# Auto-queue any suggestion with need ≥ this percent (0 = buttons only, no auto).
# Default 95. Unrelated suggestions are instructed to score ≤ 60.
# When several suggestions qualify, they are merged into ONE multi-step prompt:
#   1) first
#   2) second
# SUGGESTIONS_AUTO_APPROVE_PCT=95

# ── Forum topics (optional project workspace) ────────────────────────────────
# Telegram forum supergroup id (negative for supergroups). When set, the bot
# probes the group at startup / /forum_setup:
#   • not admin (or no Manage Topics) → ignore group for topic features
#   • Topics off → best-effort try to enable (Bot API has no official method;
#     if it fails, enable Topics manually in group settings and re-run setup)
#   • Topics on + admin → creates "AI Chat" + optional per-project topics
#     (TOPIC_AUTO_CREATE), paced + 429-retried for large catalogs
#   • pins favicon / MSIX logo when found; user topics auto-bind on exact
#     catalog name match only (else absolute path / exact name)
# Messages in a topic run Grok sessions in that topic's project path.
# TOPIC_GROUP_ID=
# TOPIC_AUTO_CREATE=true
# TOPIC_AI_CHAT_NAME=AI Chat

# ── Sibling Telegram bots (agent "MCP-like" tools via JSON actions) ──────────
# Comma-separated usernames (with or without @) the agent may call with
# bot_command / list_bots after the first-prompt Telegram bridge directive.
# Example: ALLOWED_TELEGRAM_BOTS=helperbot,other_bot
# ALLOWED_TELEGRAM_BOTS=
# Optional command catalogs (shown by list_bots / first-prompt teaching).
# Compact:  TELEGRAM_BOT_COMMANDS=helperbot:status,help,ping;otherbot:start|Start,info
# JSON:     TELEGRAM_BOT_COMMANDS={"helperbot":["status","help"],"otherbot":[{"command":"start","description":"Start"}]}
# TELEGRAM_BOT_COMMANDS=
# Hard timeout waiting for a sibling bot after /cmd@bot (ms). Default 45000.
# TELEGRAM_BOT_REPLY_TIMEOUT_MS=45000
# Quiet settle after last message/edit from that bot (ms) — "typing done" for
# streaming bots that edit one message. Default 2000.
# TELEGRAM_BOT_SETTLE_MS=2000

# ── Self-recheck (once per user prompt, gated) ───────────────────────────────
# After a successful user turn (queue empty), the bot may run one quality pass.
# Flow:
#   1) Skip automatically if no files were modified this turn.
#   2) Quiet meta ask: should we recheck? AI may refuse (simple tasks, pure
#      build/install, nothing worth re-verifying).
#   3) If needed, AI writes a focused recheck prompt; that prompt is submitted
#      as the one-shot self-recheck turn (may use tools to fix real issues).
#   4) Only then: Done + suggestions (Done splits first-turn vs recheck files).
# Default true. Alias: SLEF_RECHECK (typo-tolerant).
# SELF_RECHECK=true
# Optional: when set AND the AI decides recheck is needed, use this template
# instead of the AI-written recheck body ({{USER}} / {{DONE}} placeholders).
# SELF_RECHECK_PROMPT=
# Max wait (ms) for quiet meta prompts (recheck decision + suggestions JSON).
# On timeout the session prompt is cancelled so ✅ Done is not blocked forever.
# QUIET_PROMPT_TIMEOUT_MS=90000

# ── MCP servers (/mcp) ───────────────────────────────────────────────────────
# /mcp lists MCP servers the bot can discover and health-checks them. Grok Build
# manages its own MCP servers via `grok`'s /mcps modal and ~/.grok/config.toml,
# so configure them there; the bot's /mcp view is best-effort.
# MCP_PROBE_TIMEOUT_MS=8000
# MCP_PROBE_CONCURRENCY=6

# Auto-update (default on): hourly npm check; when a newer version exists AND the
# bot is idle, it updates + restarts and posts the release notes. Global npm only.
AUTO_UPDATE=true
# UPDATE_CHECK_MS=3600000

# Log level: debug | info | warn | error
LOG_LEVEL=info

# ── Daemon / background service ──────────────────────────────────────────────
# Emit a re-bind signal after /reauth / account switch (there is no persistent
# daemon with Grok; each turn spawns `grok`). true/false
GROK_AUTO_RESTART=true

# Quiet mode: send messages silently except turn completions, task results, and
# permission prompts. true/false
QUIET_NOTIFICATIONS=true

# Give up on a turn only after this many ms with NO streaming activity.
# PROMPT_IDLE_TIMEOUT_MS=900000

# Auto-retry a turn up to N times on a transient error before any output streamed
# (6s, 12s, 24s, 48s, capped 60s). 0 = off.
# PROMPT_RETRY_ATTEMPTS=5

# When retries are exhausted on a transient error (nothing streamed), fork the
# session into a fresh primed continuation and retry once. true/false
# AUTO_FORK_ON_ERROR=true

# Fork immediately (skip backoff) when a turn fails transiently AND context usage
# is at/above this %. Requires AUTO_FORK_ON_ERROR. 0 disables. Default 85.
# AUTO_FORK_CONTEXT_PCT=85

# When a transient error hits AFTER streaming started, ask the SAME session to
# continue instead of re-running tools. true/false
# RESUME_ON_STREAM_ERROR=true

# Where to write the log file. Defaults to <project>/logs/grok-telegram-bot.log
# LOG_DIR=
# LOG_FILE=

# ── Voice messages (optional) ────────────────────────────────────────────────
# Voice is ONLY available when STT is configured. Grok Build CLI over ACP does
# not accept audio content blocks, so without STT the bot replies that voice
# isn't configured. Use any OpenAI/Whisper-compatible transcription endpoint
# (including xAI STT if your gateway exposes /audio/transcriptions):
# STT_API_URL=https://api.openai.com/v1
# STT_API_KEY=
# STT_MODEL=whisper-1
# STT_LANGUAGE=                # blank = auto-detect