Merge pull request #13 from grinev/release/0.7.0

Release/0.7.0

Author: grinev

.env.example

@@ -36,6 +36,10 @@ OPENCODE_MODEL_ID=big-pickle
 # Bot Configuration (optional)
 # Maximum number of sessions shown in /sessions (default: 10)
 # SESSIONS_LIST_LIMIT=10
+
+# Maximum number of projects shown in /projects (default: 10)
+# PROJECTS_LIST_LIMIT=10
+
 # Bot locale: en or ru (default: en)
 # BOT_LOCALE=en
 
@@ -53,3 +57,12 @@ OPENCODE_MODEL_ID=big-pickle
 # Code File Settings (optional)
 # Maximum file size in KB to send as document (default: 100)
 # CODE_FILE_MAX_SIZE_KB=100
+
+# Speech-to-Text / Voice Recognition (optional)
+# Enable voice message transcription by setting a Whisper-compatible API URL.
+# Works with OpenAI, Groq, or any Whisper-compatible endpoint.
+# If STT_API_URL is not set, voice messages will get a "not configured" reply.
+# STT_API_URL=
+# STT_API_KEY=
+# STT_MODEL=
+# STT_LANGUAGE=

AGENTS.md

@@ -255,6 +255,7 @@ OPENCODE_MODEL_ID=big-pickle
 
 # Bot options (optional)
 # SESSIONS_LIST_LIMIT=10
+# PROJECTS_LIST_LIMIT=10
 # BOT_LOCALE=en    # en or ru
 
 # File output options (optional)
@@ -275,6 +276,7 @@ OPENCODE_MODEL_ID=big-pickle
 | `OPENCODE_SERVER_PASSWORD` | OpenCode auth password            | No       | empty                   |
 | `LOG_LEVEL`                | Logging level                     | No       | `info`                  |
 | `SESSIONS_LIST_LIMIT`      | Max sessions shown in `/sessions` | No       | `10`                    |
+| `PROJECTS_LIST_LIMIT`      | Max projects shown in `/projects` | No       | `10`                    |
 | `BOT_LOCALE`               | Bot locale (`en` or `ru`)         | No       | `en`                    |
 | `CODE_FILE_MAX_SIZE_KB`    | Max code file size to send        | No       | `100`                   |
 

PRODUCT.md

@@ -46,6 +46,7 @@ No public inbound ports are required for normal usage.
 ### Task handling
 
 - Send text prompts to OpenCode
+- Accept voice/audio messages, transcribe via Whisper-compatible STT API, and forward recognized text as prompts
 - Interrupt current task (ESC equivalent)
 - Handle OpenCode questions with inline options and custom text answers
 - Send selected/custom answers back to OpenCode (`question.reply`)
@@ -80,6 +81,7 @@ No public inbound ports are required for normal usage.
 - Configurable bot locale
 - Configurable visibility for service messages (thinking/tool calls)
 - Configurable max code file size in KB (default: 100)
+- Optional STT settings for voice transcription (`STT_API_URL`, `STT_API_KEY`, `STT_MODEL`, `STT_LANGUAGE`)
 
 ## Current Product Scope
 
@@ -99,7 +101,7 @@ Current command set:
 - [x] `/opencode_stop` - stop local OpenCode server
 - [x] `/help` - show command help
 
-Text messages (non-commands) are treated as prompts for OpenCode only when no blocking interaction is active.
+Text messages (non-commands) are treated as prompts for OpenCode only when no blocking interaction is active. Voice/audio messages are transcribed and then sent as prompts when STT is configured.
 
 Interaction routing rules:
 
@@ -123,6 +125,7 @@ Interaction routing rules:
 - [x] Sending code blocks as files when needed
 - [x] Configurable batching of service messages (thinking + tool updates): recommended `>=2` sec for Telegram rate limits; `0` = immediate
 - [x] Configurable service message visibility via env flags (`HIDE_THINKING_MESSAGES`, `HIDE_TOOL_CALL_MESSAGES`)
+- [x] Voice/audio transcription via Whisper-compatible APIs (OpenAI/Groq/Together and compatible providers)
 - [x] Single-user security model (allowed Telegram user ID)
 - [x] Persistent bot settings (`settings.json`) between restarts
 - [x] EN/RU localization structure via dedicated i18n files
@@ -138,7 +141,7 @@ Open tasks for upcoming iterations:
 - [ ] Improve Telegram-compatible message formatting for richer outputs
 - [ ] Support sending files from Telegram to OpenCode (screenshots, documents)
 - [ ] Provide a Docker image and basic container deployment guide
-- [ ] Add voice transcription
+- [x] Add voice transcription
 
 ## Possible Improvements
 

README.md

@@ -25,7 +25,9 @@ Quick start: `npx @grinev/opencode-telegram-bot`
 - **Model switching** — pick any model from your OpenCode favorites directly in the chat
 - **Agent modes** — switch between Plan and Build modes on the fly
 - **Interactive Q&A** — answer agent questions and approve permissions via inline buttons
+- **Voice prompts** — send voice/audio messages, transcribe them via a Whisper-compatible API, then forward recognized text to OpenCode
 - **Context control** — compact context when it gets too large, right from the chat
+- **Input flow control** — when an interactive flow is active, the bot accepts only relevant input to keep context consistent and avoid accidental actions
 - **Security** — strict user ID whitelist; no one else can access your bot, even if they find it
 - **Localization** — English and Russian UI (`BOT_LOCALE=en|ru`)
 
@@ -102,15 +104,7 @@ opencode-telegram config
 | `/opencode_stop`  | Stop the OpenCode server remotely                       |
 | `/help`           | Show available commands                                 |
 
-Any regular text message is sent as a prompt to the coding agent only when no blocking interaction is active.
-
-### Interaction Rules
-
-- Only one interactive flow can be active at a time (inline menus, permission request, question flow, rename)
-- While an interaction is active, the bot accepts only relevant input for that flow and blocks unrelated actions
-- Allowed utility commands remain available during active interactions: `/help`, `/status`, `/stop`
-- Unknown slash commands return an explicit fallback message instead of being silently ignored
-- Interaction flows do not expire automatically and wait until explicit completion (`answer`, `cancel`, `/stop`, or reset/cleanup)
+Any regular text message is sent as a prompt to the coding agent only when no blocking interaction is active. Voice/audio messages are transcribed and then sent as prompts when STT is configured.
 
 > `/opencode_start` and `/opencode_stop` are intended as emergency commands — for example, if you need to restart a stuck server while away from your computer. Under normal usage, start `opencode serve` yourself before launching the bot.
 
@@ -124,26 +118,54 @@ When installed via npm, the configuration wizard handles the initial setup. The
 - **Windows:** `%APPDATA%\opencode-telegram-bot\.env`
 - **Linux:** `~/.config/opencode-telegram-bot/.env`
 
-| Variable                        | Description                                                                                                  | Required | Default                 |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------ | :------: | ----------------------- |
-| `TELEGRAM_BOT_TOKEN`            | Bot token from @BotFather                                                                                    |   Yes    | —                       |
-| `TELEGRAM_ALLOWED_USER_ID`      | Your numeric Telegram user ID                                                                                |   Yes    | —                       |
-| `TELEGRAM_PROXY_URL`            | Proxy URL for Telegram API (SOCKS5/HTTP)                                                                     |    No    | —                       |
-| `OPENCODE_API_URL`              | OpenCode server URL                                                                                          |    No    | `http://localhost:4096` |
-| `OPENCODE_SERVER_USERNAME`      | Server auth username                                                                                         |    No    | `opencode`              |
-| `OPENCODE_SERVER_PASSWORD`      | Server auth password                                                                                         |    No    | —                       |
-| `OPENCODE_MODEL_PROVIDER`       | Default model provider                                                                                       |   Yes    | `opencode`              |
-| `OPENCODE_MODEL_ID`             | Default model ID                                                                                             |   Yes    | `big-pickle`            |
-| `BOT_LOCALE`                    | Bot UI language (`en` or `ru`)                                                                               |    No    | `en`                    |
-| `SESSIONS_LIST_LIMIT`           | Max sessions shown in `/sessions`                                                                            |    No    | `10`                    |
-| `SERVICE_MESSAGES_INTERVAL_SEC` | Service messages interval (thinking + tool calls); keep `>=2` to avoid Telegram rate limits, `0` = immediate |    No    | `5`                     |
-| `HIDE_THINKING_MESSAGES`        | Hide `💭 Thinking...` service messages                                                                       |    No    | `false`                 |
-| `HIDE_TOOL_CALL_MESSAGES`       | Hide tool-call service messages (`💻 bash ...`, `📖 read ...`, etc.)                                         |    No    | `false`                 |
-| `CODE_FILE_MAX_SIZE_KB`         | Max file size (KB) to send as document                                                                       |    No    | `100`                   |
-| `LOG_LEVEL`                     | Log level (`debug`, `info`, `warn`, `error`)                                                                 |    No    | `info`                  |
+| Variable                        | Description                                                                                                  | Required | Default                  |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------ | :------: | ------------------------ |
+| `TELEGRAM_BOT_TOKEN`            | Bot token from @BotFather                                                                                    |   Yes    | —                        |
+| `TELEGRAM_ALLOWED_USER_ID`      | Your numeric Telegram user ID                                                                                |   Yes    | —                        |
+| `TELEGRAM_PROXY_URL`            | Proxy URL for Telegram API (SOCKS5/HTTP)                                                                     |    No    | —                        |
+| `OPENCODE_API_URL`              | OpenCode server URL                                                                                          |    No    | `http://localhost:4096`  |
+| `OPENCODE_SERVER_USERNAME`      | Server auth username                                                                                         |    No    | `opencode`               |
+| `OPENCODE_SERVER_PASSWORD`      | Server auth password                                                                                         |    No    | —                        |
+| `OPENCODE_MODEL_PROVIDER`       | Default model provider                                                                                       |   Yes    | `opencode`               |
+| `OPENCODE_MODEL_ID`             | Default model ID                                                                                             |   Yes    | `big-pickle`             |
+| `BOT_LOCALE`                    | Bot UI language (`en` or `ru`)                                                                               |    No    | `en`                     |
+| `SESSIONS_LIST_LIMIT`           | Max sessions shown in `/sessions`                                                                            |    No    | `10`                     |
+| `PROJECTS_LIST_LIMIT`           | Max projects shown in `/projects`                                                                            |    No    | `10`                     |
+| `SERVICE_MESSAGES_INTERVAL_SEC` | Service messages interval (thinking + tool calls); keep `>=2` to avoid Telegram rate limits, `0` = immediate |    No    | `5`                      |
+| `HIDE_THINKING_MESSAGES`        | Hide `💭 Thinking...` service messages                                                                       |    No    | `false`                  |
+| `HIDE_TOOL_CALL_MESSAGES`       | Hide tool-call service messages (`💻 bash ...`, `📖 read ...`, etc.)                                         |    No    | `false`                  |
+| `CODE_FILE_MAX_SIZE_KB`         | Max file size (KB) to send as document                                                                       |    No    | `100`                    |
+| `STT_API_URL`                   | Whisper-compatible API base URL (enables voice/audio transcription)                                          |    No    | —                        |
+| `STT_API_KEY`                   | API key for your STT provider                                                                                |    No    | —                        |
+| `STT_MODEL`                     | STT model name passed to `/audio/transcriptions`                                                             |    No    | `whisper-large-v3-turbo` |
+| `STT_LANGUAGE`                  | Optional language hint (empty = provider auto-detect)                                                        |    No    | —                        |
+| `LOG_LEVEL`                     | Log level (`debug`, `info`, `warn`, `error`)                                                                 |    No    | `info`                   |
 
 > **Keep your `.env` file private.** It contains your bot token. Never commit it to version control.
 
+### Voice and Audio Transcription (Optional)
+
+If `STT_API_URL` and `STT_API_KEY` are set, the bot will:
+
+1. Accept `voice` and `audio` Telegram messages
+2. Transcribe them via `POST {STT_API_URL}/audio/transcriptions`
+3. Show recognized text in chat
+4. Send the recognized text to OpenCode as a normal prompt
+
+Supported provider examples (Whisper-compatible):
+
+- **OpenAI**
+  - `STT_API_URL=https://api.openai.com/v1`
+  - `STT_MODEL=whisper-1`
+- **Groq**
+  - `STT_API_URL=https://api.groq.com/openai/v1`
+  - `STT_MODEL=whisper-large-v3-turbo`
+- **Together**
+  - `STT_API_URL=https://api.together.xyz/v1`
+  - `STT_MODEL=openai/whisper-large-v3`
+
+If STT variables are not set, voice/audio transcription is disabled and the bot will ask you to configure STT.
+
 ### Model Configuration
 
 The bot picks up your **favorite models** from OpenCode. To add a model to favorites:

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@grinev/opencode-telegram-bot",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Telegram bot client for OpenCode to run and monitor coding tasks from chat.",
   "type": "module",
   "main": "./dist/index.js",

package.json

@@ -15,9 +15,9 @@ import { createMainKeyboard } from "../utils/keyboard.js";
 import { ensureActiveInlineMenu, replyWithInlineMenu } from "../handlers/inline-menu.js";
 import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
+import { config } from "../../config.js";
 
 const MAX_INLINE_BUTTON_LABEL_LENGTH = 64;
-const MAX_PROJECTS_TO_SHOW = 10;
 
 function formatProjectButtonLabel(label: string, isActive: boolean): string {
   const prefix = isActive ? "✅ " : "";
@@ -34,7 +34,7 @@ export async function projectsCommand(ctx: CommandContext<Context>) {
   try {
     await syncSessionDirectoryCache();
     const projects = await getProjects();
-    const projectsToShow = projects.slice(0, MAX_PROJECTS_TO_SHOW);
+    const projectsToShow = projects.slice(0, config.bot.projectsListLimit);
 
     if (projectsToShow.length === 0) {
       await ctx.reply(t("projects.empty"));