opencode-tbot 0.1.0

package/INSTALL.md

@@ -0,0 +1,92 @@
+# Install `opencode-tbot`
+
+## Recommended
+
+Run:
+
+```bash
+npx opencode-tbot@latest install
+```
+
+The installer will:
+
+1. update `~/.config/opencode/opencode.json`
+2. ensure the `plugin` array contains `opencode-tbot@latest`
+3. prompt for the Telegram bot token
+4. ask whether voice transcription should be enabled
+5. prompt for the OpenRouter API key when voice transcription is enabled
+6. write plugin defaults to `~/.config/opencode/opencode-tbot/config.json`
+
+Restart OpenCode after installation.
+
+## Non-Interactive
+
+Example:
+
+```bash
+npx opencode-tbot@latest install \
+  --bot-token <telegram-token> \
+  --disable-voice
+```
+
+If voice transcription is enabled:
+
+```bash
+npx opencode-tbot@latest install \
+  --bot-token <telegram-token> \
+  --enable-voice \
+  --openrouter-api-key <openrouter-key>
+```
+
+Useful flags:
+
+- `--telegram-api-root <url>`
+- `--skip-register`
+- `--home-dir <path>`
+
+`--skip-register` only skips the OpenCode global registration step. The plugin config file is still written.
+
+## Project Overrides
+
+The installer writes global defaults to:
+
+- `~/.config/opencode/opencode-tbot/config.json`
+
+You can override them per worktree with:
+
+- `<worktree>/tbot.config.json`
+- legacy fallback: `<worktree>/opencode-tbot.config.json`
+
+The runtime loads global defaults first, then deep-merges the project config on top.
+
+Example project override:
+
+```json
+{
+  "telegram": {
+    "allowedChatIds": [123456789]
+  },
+  "state": {
+    "path": "./data/opencode-tbot.state.json"
+  },
+  "logLevel": "info"
+}
+```
+
+## Agent Prompt
+
+If you want another coding agent to perform the install, give it this:
+
+```text
+Install opencode-tbot for OpenCode by running:
+npx opencode-tbot@latest install
+
+If the environment is non-interactive, use:
+- --bot-token for the Telegram bot token
+- --enable-voice or --disable-voice
+- --openrouter-api-key when voice transcription is enabled
+
+Do not remove unrelated existing configuration.
+Preserve existing plugins in ~/.config/opencode/opencode.json.
+Show me the final changes and tell me to restart OpenCode.
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-tbot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# opencode-tbot
+
+A Telegram plugin for driving [OpenCode](https://opencode.ai) from chat.
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+> This project is not built by the OpenCode team and is not affiliated with them.
+
+## What It Does
+
+`opencode-tbot` lets you operate OpenCode from Telegram.
+
+- Text messages are forwarded to the active OpenCode session.
+- Telegram images are uploaded as OpenCode file parts.
+- Telegram voice messages can be transcribed through OpenRouter before entering the normal prompt flow.
+- Permission requests raised by OpenCode can be approved or rejected directly from Telegram inline buttons.
+- Session completion and error events can be reported back to the bound Telegram chat.
+- Chat state is stored in a JSON state file that works in both Node and Bun runtimes.
+
+This repository runs as an OpenCode plugin. There is no standalone bot service.
+
+## Installation
+
+### Requirements
+
+- OpenCode must be installed and able to load plugins.
+- Node.js 22.12.0 or newer is required for local builds and development.
+- You need a Telegram bot token from BotFather.
+
+### Recommended Install Flow
+
+Run:
+
+```bash
+npx opencode-tbot@latest install
+```
+
+The installer will:
+
+1. register `opencode-tbot@latest` in `~/.config/opencode/opencode.json`
+2. ask for your Telegram bot token
+3. ask whether voice transcription should be enabled
+4. ask for an OpenRouter API key if voice transcription is enabled
+5. write plugin defaults to `~/.config/opencode/opencode-tbot/config.json`
+
+Restart OpenCode after installation, then message the bot with `/start` or `/status`.
+
+### Non-Interactive Install
+
+For CI or scripted setup:
+
+```bash
+npx opencode-tbot@latest install \
+  --bot-token <telegram-token> \
+  --disable-voice
+```
+
+If voice transcription is enabled, `--openrouter-api-key` is required.
+
+Useful flags:
+
+- `--enable-voice`
+- `--disable-voice`
+- `--openrouter-api-key <key>`
+- `--telegram-api-root <url>`
+- `--skip-register`
+- `--home-dir <path>`
+
+`--skip-register` is mainly for tests or local packaging flows where plugin registration is handled separately.
+
+## Configuration
+
+The runtime config is loaded in this order:
+
+1. global defaults from `~/.config/opencode/opencode-tbot/config.json`
+2. project overrides from `<worktree>/tbot.config.json`
+3. legacy project filename `<worktree>/opencode-tbot.config.json` if `tbot.config.json` is absent
+
+Project config is merged on top of the global config. `telegram`, `state`, and `openrouter` are deep-merged by section.
+
+### Example `tbot.config.json`
+
+```json
+{
+  "telegram": {
+    "botToken": "your_telegram_bot_token",
+    "allowedChatIds": [123456789],
+    "apiRoot": "https://api.telegram.org"
+  },
+  "state": {
+    "path": "./data/opencode-tbot.state.json"
+  },
+  "openrouter": {
+    "apiKey": "your_openrouter_api_key",
+    "model": "openai/gpt-audio-mini",
+    "timeoutMs": 30000,
+    "transcriptionPrompt": ""
+  },
+  "logLevel": "info"
+}
+```
+
+### Fields
+
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `telegram.botToken` | Yes | - | Telegram bot token. Normally written by the installer into the global plugin config. |
+| `telegram.allowedChatIds` | No | `[]` | Allowed Telegram chat IDs. If empty, the bot accepts messages from any chat. |
+| `telegram.apiRoot` | No | `https://api.telegram.org` | Telegram Bot API base URL. Useful for tests or self-hosted gateways. |
+| `state.path` | No | `./data/opencode-tbot.state.json` | JSON state file path, resolved relative to the current OpenCode worktree. |
+| `database.path` | Legacy | - | Backward-compatible alias for `state.path`. No sqlite migration is performed. |
+| `openrouter.apiKey` | No | `""` | OpenRouter API key. Required only when voice transcription is enabled. |
+| `openrouter.model` | No | `openai/gpt-audio-mini` | OpenRouter model for voice transcription. |
+| `openrouter.timeoutMs` | No | `30000` | Voice transcription timeout in milliseconds. |
+| `openrouter.transcriptionPrompt` | No | `""` | Optional extra instruction appended to the transcription prompt. |
+| `logLevel` | No | `info` | Plugin log level. Logs are emitted through `client.app.log()`. |
+
+## Features
+
+- Send text prompts to OpenCode from Telegram
+- Send Telegram images to OpenCode with optional caption text
+- Transcribe Telegram voice messages through OpenRouter
+- Create and switch OpenCode sessions in chat
+- View and switch agents
+- View and switch models and reasoning levels
+- Approve or reject OpenCode permission requests from Telegram
+- Receive session error and idle notifications in Telegram
+- Restrict access with an optional Telegram allowlist
+- Persist chat bindings and pending actions in a JSON state file
+
+## Commands
+
+- `/start` show the welcome message and quick-start steps
+- `/help` show the full command reference and examples
+- `/status` show aggregated OpenCode health, path, LSP, and MCP status
+- `/new [title]` create a new OpenCode session
+- `/agents` or `/agent` list available agents and switch the active one
+- `/sessions` list available sessions and switch the active one
+- `/cancel` cancel session rename or abort the running request for the current session
+- `/model` or `/models` list available models and switch the active one
+- `/language` switch the bot display language
+
+Any non-command text message is treated as a prompt and sent to OpenCode. Telegram `voice` messages follow the same prompt flow after transcription when OpenRouter is configured. Telegram images are forwarded as OpenCode file parts.
+
+## Local Development
+
+Build the plugin bundle:
+
+```bash
+pnpm build
+```
+
+Type-check:
+
+```bash
+pnpm typecheck
+```
+
+Run tests:
+
+```bash
+pnpm test
+```
+
+For local source-based loading in this repository, OpenCode can use [.opencode/plugins/opencode-tbot.ts](./.opencode/plugins/opencode-tbot.ts), which re-exports `src/plugin.ts`.
+
+## Deployment
+
+Supported deployment modes:
+
+- Recommended npm installation through `npx opencode-tbot@latest install`
+- Non-interactive install for CI or scripted environments
+- Local development bridge through `.opencode/plugins/opencode-tbot.ts`
+- Unpublished external-project bridge that re-exports `dist/plugin.js`
+
+Deployment details are documented in [docs/deployment.md](./docs/deployment.md).
+
+## FAQ
+
+### Do I need a running OpenCode instance?
+
+Yes. This repository provides a Telegram integration layer and depends on the OpenCode host process that loads the plugin.
+
+### Is this an official OpenCode project?
+
+No. It integrates with OpenCode, but it is not built by the OpenCode team.
+
+### Why is Node.js 22 recommended?
+
+The project uses modern Node APIs for the CLI, tests, and local development. Runtime state storage is file-based and works in both Node and Bun-compatible plugin hosts.

package/README.zh-CN.md

@@ -0,0 +1,190 @@
+# opencode-tbot
+
+一个通过 Telegram 驱动 [OpenCode](https://opencode.ai) 的插件。
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+> 本项目并非由 OpenCode 团队开发，也不隶属于 OpenCode 官方。
+
+## 项目说明
+
+`opencode-tbot` 允许你直接在 Telegram 中操作 OpenCode。
+
+- 文本消息会转发到当前 OpenCode 会话。
+- Telegram 图片会作为 OpenCode 文件片段上传。
+- Telegram 语音消息可先通过 OpenRouter 转写，再进入正常 prompt 流程。
+- OpenCode 触发的权限请求可以直接在 Telegram 中通过内联按钮批准或拒绝。
+- 会话完成和错误事件可以主动回推到绑定的 Telegram chat。
+- 聊天状态通过 JSON 状态文件持久化，可同时兼容 Node 和 Bun 运行环境。
+
+当前仓库以 OpenCode 插件形式运行，不再提供独立 bot 进程。
+
+## 安装
+
+### 环境要求
+
+- 需要已安装并可加载插件的 OpenCode。
+- 本地构建和开发需要 Node.js 22.12.0 或更高版本。
+- 需要一个由 BotFather 创建的 Telegram bot token。
+
+### 推荐安装方式
+
+执行：
+
+```bash
+npx opencode-tbot@latest install
+```
+
+安装器会自动完成以下步骤：
+
+1. 在 `~/.config/opencode/opencode.json` 中注册 `opencode-tbot@latest`
+2. 提示输入 Telegram bot token
+3. 询问是否启用语音转写
+4. 如果启用语音转写，则继续提示输入 OpenRouter API key
+5. 将插件全局默认配置写入 `~/.config/opencode/opencode-tbot/config.json`
+
+安装完成后重启 OpenCode，再向 bot 发送 `/start` 或 `/status` 验证即可。
+
+### 非交互安装
+
+适合 CI 或脚本化环境：
+
+```bash
+npx opencode-tbot@latest install \
+  --bot-token <telegram-token> \
+  --disable-voice
+```
+
+如果启用了语音转写，则必须同时提供 `--openrouter-api-key`。
+
+常用参数：
+
+- `--enable-voice`
+- `--disable-voice`
+- `--openrouter-api-key <key>`
+- `--telegram-api-root <url>`
+- `--skip-register`
+- `--home-dir <path>`
+
+`--skip-register` 主要用于测试或本地打包流程，此时插件注册由外部步骤负责。
+
+## 配置
+
+运行时配置按以下优先级加载：
+
+1. 全局默认配置 `~/.config/opencode/opencode-tbot/config.json`
+2. 项目覆盖配置 `<worktree>/tbot.config.json`
+3. 如果不存在 `tbot.config.json`，则兼容旧文件名 `<worktree>/opencode-tbot.config.json`
+
+项目配置会覆盖全局默认值；`telegram`、`state`、`openrouter` 这些分段配置会进行深合并。
+
+### `tbot.config.json` 示例
+
+```json
+{
+  "telegram": {
+    "botToken": "your_telegram_bot_token",
+    "allowedChatIds": [123456789],
+    "apiRoot": "https://api.telegram.org"
+  },
+  "state": {
+    "path": "./data/opencode-tbot.state.json"
+  },
+  "openrouter": {
+    "apiKey": "your_openrouter_api_key",
+    "model": "openai/gpt-audio-mini",
+    "timeoutMs": 30000,
+    "transcriptionPrompt": ""
+  },
+  "logLevel": "info"
+}
+```
+
+### 配置字段
+
+| 字段 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `telegram.botToken` | 是 | - | Telegram bot token。通常由安装器写入全局插件配置。 |
+| `telegram.allowedChatIds` | 否 | `[]` | 允许访问的 Telegram chat ID 数组。为空时表示接受任意 chat。 |
+| `telegram.apiRoot` | 否 | `https://api.telegram.org` | Telegram Bot API 根地址，适合测试或自托管网关。 |
+| `state.path` | 否 | `./data/opencode-tbot.state.json` | JSON 状态文件路径，相对当前 OpenCode worktree 解析。 |
+| `database.path` | 兼容字段 | - | `state.path` 的旧别名，仅做兼容映射，不迁移 sqlite 数据。 |
+| `openrouter.apiKey` | 否 | `""` | OpenRouter API key。仅在启用语音转写时需要。 |
+| `openrouter.model` | 否 | `openai/gpt-audio-mini` | 语音转写使用的 OpenRouter 模型。 |
+| `openrouter.timeoutMs` | 否 | `30000` | 语音转写超时时间，单位毫秒。 |
+| `openrouter.transcriptionPrompt` | 否 | `""` | 追加到内置转写提示词后的可选说明。 |
+| `logLevel` | 否 | `info` | 插件日志级别。日志统一通过 `client.app.log()` 上报。 |
+
+## 功能
+
+- 在 Telegram 中向 OpenCode 发送文本 prompt
+- 将 Telegram 图片连同可选 caption 一起转发给 OpenCode
+- 通过 OpenRouter 转写 Telegram 语音消息
+- 在聊天中创建和切换 OpenCode 会话
+- 查看和切换 agent
+- 查看和切换模型与推理等级
+- 在 Telegram 中审批或拒绝 OpenCode 权限请求
+- 接收会话错误和空闲通知
+- 通过 Telegram allowlist 限制访问
+- 使用 JSON 状态文件持久化聊天绑定和待处理动作
+
+## 命令
+
+- `/start` 显示欢迎信息和快速开始说明
+- `/help` 显示完整命令说明和示例
+- `/status` 显示 OpenCode 健康状态、路径、LSP 和 MCP 信息
+- `/new [title]` 创建新的 OpenCode 会话
+- `/agents` 或 `/agent` 列出可用 agent 并切换当前 agent
+- `/sessions` 列出会话并切换当前会话
+- `/cancel` 取消会话重命名，或中止当前会话正在运行的请求
+- `/model` 或 `/models` 列出可用模型并切换当前模型
+- `/language` 切换 bot 显示语言
+
+任意非命令文本都会被当作 prompt 发送给 OpenCode。配置了 OpenRouter 后，Telegram `voice` 消息会先转写再走同一条 prompt 流程。图片会作为 OpenCode 文件片段上传。
+
+## 本地开发
+
+构建插件：
+
+```bash
+pnpm build
+```
+
+类型检查：
+
+```bash
+pnpm typecheck
+```
+
+运行测试：
+
+```bash
+pnpm test
+```
+
+在本仓库中做源码调试时，OpenCode 可以通过 [.opencode/plugins/opencode-tbot.ts](./.opencode/plugins/opencode-tbot.ts) 直接加载 `src/plugin.ts`。
+
+## 部署
+
+支持的部署模式：
+
+- 通过 `npx opencode-tbot@latest install` 的推荐安装流
+- 面向 CI 或脚本环境的非交互安装
+- 通过 `.opencode/plugins/opencode-tbot.ts` 的本地开发桥接
+- 在外部项目中通过 re-export `dist/plugin.js` 的构建产物桥接
+
+更完整的部署说明见 [docs/deployment.md](./docs/deployment.md)。
+
+## 常见问题
+
+### 我需要一个正在运行的 OpenCode 实例吗？
+
+需要。这个仓库提供的是 Telegram 集成层，依赖加载它的 OpenCode Host 进程。
+
+### 这是 OpenCode 官方项目吗？
+
+不是。它只是与 OpenCode 集成，并非 OpenCode 官方项目。
+
+### 为什么仍然推荐 Node.js 22？
+
+CLI、测试和本地开发仍然使用现代 Node API。插件运行时的状态存储已经改为文件方案，可兼容 Node 和 Bun 风格的宿主环境。

package/bin/opencode-tbot.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/cli.js").then(({ main }) => main());