opencode-telegram-mirror 0.3.0

package/AGENTS.md

@@ -0,0 +1,196 @@
+# AGENTS.md
+
+Guidance for agentic coding assistants working in this repo.
+Scope: repository root (applies to all files).
+
+## Overview
+- Project: Telegram mirror for OpenCode sessions.
+- Primary runtime: Bun (root) 
+- Language: TypeScript with ESM modules and strict type checking.
+- Keep changes small and aligned with existing style.
+
+## Repo Layout
+- `src/`: Bun-based Telegram mirror bot.
+- `tsconfig.json`: root TS config (strict, ESM).
+
+## Commands (Root - Telegram Mirror)
+Install dependencies:
+  - `bun install`
+Run the bot:
+  - `bun run start`
+Run from source (explicit):
+  - `bun run src/main.ts`
+Typecheck:
+  - `bun run typecheck`
+
+## Tests
+
+The test harness enables **autonomous testing feedback loops** by mocking external dependencies. Instead of hitting real Telegram servers, the bot talks to a local mock server that:
+1. Serves pre-recorded updates from fixture files
+2. Captures all outgoing Telegram API calls for inspection
+
+This allows fully automated test runs without any external dependencies.
+
+### Test Files
+- `test/fixtures/sample-updates.json` - Mock Telegram updates
+- `test/mock-server.ts` - Mock server (serves updates + captures API calls)
+- `test/run-test.ts` - Test runner (starts mock server + bot together)
+
+### Running Tests
+
+**Quick test run** (30 seconds, uses mock OpenCode if no OPENCODE_URL):
+```bash
+bun run test:run
+```
+
+**With custom timeout**:
+```bash
+bun run test/run-test.ts test/fixtures/sample-updates.json 60
+```
+
+**Manual testing** (two terminals):
+```bash
+# Terminal 1: Start mock server
+bun run test:mock-server
+
+# Terminal 2: Start bot with mock endpoints
+TELEGRAM_UPDATES_URL=http://localhost:3456/updates \
+TELEGRAM_SEND_URL=http://localhost:3456 \
+TELEGRAM_BOT_TOKEN=test:token \
+TELEGRAM_CHAT_ID=-1003546563617 \
+bun run start
+```
+
+### Mock Server Control Endpoints
+
+The mock server at `http://localhost:3456` provides:
+- `GET /_control?action=status` - Server stats (updates served, requests captured)
+- `GET /_control?action=captured` - All captured Telegram API requests
+- `POST /_control?action=inject` - Inject new updates dynamically
+- `GET /_control?action=reset` - Reset update pointer and clear captured requests
+
+### Adding Test Fixtures
+
+Add new fixture files to `test/fixtures/` as JSON arrays of updates in the DO format:
+```json
+[
+  {
+    "update_id": 123,
+    "chat_id": "-1003546563617",
+    "payload": { "update_id": 123, "message": { ... } }
+  }
+]
+```
+
+## Single-File Checks
+- Root: `bun run typecheck` validates `src/**/*`.
+- Lint single file: `npx next lint --file app/page.tsx`.
+- Use `npm run lint -- --file <path>` if you prefer npm.
+
+## TypeScript & Module Conventions
+- TypeScript `strict` is enabled in both packages.
+- ESM modules are used; prefer `import`/`export` syntax.
+- Use `import type` for type-only imports (see `src/telegram.ts`).
+- Prefer explicit return types for exported/public functions.
+- Avoid `any`; use `unknown` + narrowing when needed.
+- Prefer `interface` for object shapes and `type` for unions.
+- Keep JSON parsing typed (cast to known interfaces).
+- Prefer `const` over `let`; keep functions small and focused.
+
+## Formatting
+- Indentation: 2 spaces.
+- Semicolons are omitted in existing files.
+- Root `src/` uses double quotes.
+- Keep line length readable (roughly 100–120 chars).
+- Use trailing commas in multi-line objects/arrays.
+- Separate logical blocks with blank lines.
+
+## Imports
+- Order: Node built-ins (`node:`), external deps, internal modules.
+- Keep internal imports relative (no absolute paths in root).
+- Avoid unused imports; remove when refactoring.
+
+## Naming
+- Files: kebab-case or lower-case with hyphens (existing pattern).
+- Functions: `camelCase`.
+- Classes: `PascalCase`.
+- Types/interfaces: `PascalCase`.
+- Constants: `UPPER_SNAKE_CASE` when truly constant.
+- Prefer descriptive names (e.g., `sessionId`, `updatesUrl`).
+
+## Error Handling
+- Use `try/catch` around network and IO calls.
+- Log errors with context and return safe defaults.
+- Throw `Error` for fatal conditions (e.g., invalid bot token).
+- Use `String(error)` when logging unknown errors.
+- Prefer early returns for invalid state.
+- Use `console.error` + `process.exit(1)` only for fatal startup errors.
+
+## Logging
+- Root uses `createLogger()` and `log(level, message, extra)`.
+- Use `log("info" | "warn" | "error" | "debug", ...)` in bot code.
+- Avoid `console.log` except for fatal startup errors.
+
+## Async & Concurrency
+- Use `async/await` for clarity.
+- Avoid blocking loops; use `await Bun.sleep(...)` for backoff.
+- If retrying, log retry context and keep delays reasonable.
+
+## Data & API Handling
+- Validate request payloads before use.
+- When reading env vars, allow file config to be overridden.
+- Normalize ids to strings for comparisons.
+- Keep Telegram API interactions resilient (retry without Markdown).
+
+## Config & Environment
+- Root config loads from:
+  - `~/.config/opencode/telegram.json`
+  - `<repo>/.opencode/telegram.json`
+- Environment variables override config:
+  - `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `TELEGRAM_UPDATES_URL`, `TELEGRAM_SEND_URL`
+- Diff viewer base URL uses `VERCEL_URL` or `NEXT_PUBLIC_BASE_URL`.
+
+## Dependency Management
+- Root uses Bun; avoid adding npm scripts unless required.
+- Keep dependency upgrades minimal and justified.
+
+## Generated Files
+- Do not commit `dist/` or `node_modules/`.
+- Root build output goes to `dist/` (see `tsconfig.json`).
+
+## Code Organization
+- Prefer small helpers over large monolithic functions.
+- Keep side effects near the edges (IO, network).
+- Keep types co-located with their usage when small.
+
+## Updating This File
+- Update commands if scripts change.
+- Add new tool or lint rules as they are introduced.
+- Keep this file around ~150 lines.
+
+## Cursor/Copilot Rules
+- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` found.
+- If added later, summarize them here.
+
+<!-- opensrc:start -->
+
+## Source Code Reference
+
+Source code for dependencies is available in `opensrc/` for deeper understanding of implementation details.
+
+See `opensrc/sources.json` for the list of available packages and their versions.
+
+Use this source code when you need to understand how a package works internally, not just its types/interface.
+
+### Fetching Additional Source Code
+
+To fetch source code for a package or repository you need to understand, run:
+
+```bash
+npx opensrc <package>           # npm package (e.g., npx opensrc zod)
+npx opensrc pypi:<package>      # Python package (e.g., npx opensrc pypi:requests)
+npx opensrc crates:<package>    # Rust crate (e.g., npx opensrc crates:serde)
+npx opensrc <owner>/<repo>      # GitHub repo (e.g., npx opensrc vercel/ai)
+```
+
+<!-- opensrc:end -->

package/README.md

@@ -0,0 +1,230 @@
+# OpenCode Telegram Mirror
+
+A standalone bot that mirrors OpenCode sessions to Telegram topics, enabling collaborative AI-assisted coding conversations in Telegram.
+
+## Installation
+
+```bash
+npm install -g opencode-telegram-mirror
+```
+
+## Quick Start
+
+1. **Create a Telegram Bot**:
+   - Message [@BotFather](https://t.me/BotFather) on Telegram
+   - Send `/newbot` and follow instructions
+   - Copy your bot token
+
+2. **Get your Chat ID**:
+   - Message [@userinfobot](https://t.me/userinfobot)
+   - Copy your chat ID
+
+3. **Run the mirror**:
+   ```bash
+   opencode-telegram-mirror
+   ```
+
+4. **Configure environment variables**:
+   ```bash
+   export TELEGRAM_BOT_TOKEN="your-bot-token"
+   export TELEGRAM_CHAT_ID="your-chat-id"
+   # Optional: export TELEGRAM_THREAD_ID="your-thread-id"
+   ```
+
+That's it! Your OpenCode sessions will now be mirrored to Telegram.
+
+## How it works
+
+The Telegram mirror streams OpenCode session interactions (questions, answers, tool usage, and file edits) to Telegram topics. This enables:
+
+- **Collaborative coding**: Share your coding sessions with team members
+- **Remote pair programming**: Get real-time feedback on your code
+- **Session persistence**: Keep conversations going across devices
+- **Rich formatting**: Code blocks, diffs, and interactive buttons
+
+### Architecture
+
+Each instance of the `opencode-telegram-mirror` binary mirrors **one OpenCode session** to **one Telegram channel/thread**. This 1:1 mapping ensures clean separation between different coding conversations.
+
+**OpenCode Server Connection**:
+- **Without `OPENCODE_URL`**: The mirror spawns its own OpenCode server instance locally
+- **With `OPENCODE_URL`**: The mirror connects to an existing OpenCode server at the specified URL
+
+This flexibility allows you to either run self-contained mirrors (each with their own server) or connect to a shared/managed OpenCode server.
+
+### Threading & Topics
+
+Telegram supports threaded conversations in forum-style channels:
+
+- **No thread ID**: Messages go to the main channel
+- **With thread ID**: Messages go to a specific topic thread within a forum channel
+
+Each mirror instance should be configured with a unique `TELEGRAM_THREAD_ID` to prevent cross-contamination between different coding sessions.
+
+### Orchestration
+
+While you can run a single mirror instance, production deployments typically require orchestration to support multiple concurrent sessions:
+
+- **Multiple sessions**: Run separate mirror processes for different coding projects
+- **Thread isolation**: Use unique thread IDs per session
+- **Server sharing**: Point multiple mirrors to the same `OPENCODE_URL` for resource efficiency
+- **Load balancing**: Distribute mirrors across multiple servers
+
+Example orchestration might involve:
+- Docker containers for each mirror instance
+- Kubernetes deployments with unique environment configs
+- Process managers like PM2 for local deployment
+
+### Updates URL & Multi-Instance Deployments
+
+**Single Instance (Simple Case)**:
+If you're running one `opencode-telegram-mirror` instance with one Telegram bot and one channel, you don't need `TELEGRAM_UPDATES_URL`. The mirror will poll Telegram's API directly using `getUpdates`.
+
+**Multi-Instance Deployments**:
+When running multiple mirror instances (e.g., one per coding session or per team), Telegram only allows one webhook or one `getUpdates` poller per bot. To support multiple mirrors:
+
+1. **Central Updates Collector**: Deploy a central service that polls `getUpdates` once and distributes updates to multiple mirrors
+2. **Set `TELEGRAM_UPDATES_URL`**: Point each mirror to this central endpoint
+3. **Thread Isolation**: Each mirror should have a unique `TELEGRAM_THREAD_ID`
+
+**Updates URL API Contract**:
+The central updates endpoint must accept GET requests with query parameters:
+- `since`: Last processed `update_id` (for pagination)
+- `chat_id`: Filter updates to specific chat
+- `thread_id`: Filter to specific thread (optional)
+
+Response format (JSON):
+```json
+{
+  "updates": [
+    {
+      "payload": {
+        "update_id": 123,
+        "message": {
+          "message_id": 456,
+          "message_thread_id": 789,
+          "date": 1640995200,
+          "text": "Hello world",
+          "from": { "id": 123456, "username": "user" },
+          "chat": { "id": -1001234567890 }
+        }
+      },
+      "update_id": 123
+    }
+  ]
+}
+```
+
+The `payload` contains the standard [Telegram Update object](https://core.telegram.org/bots/api#update). Basic authentication is supported via URL credentials (`https://user:pass@example.com/updates`).
+
+## Usage
+
+### Basic Usage
+
+```bash
+opencode-telegram-mirror [directory] [session-id]
+```
+
+- `directory`: Working directory (defaults to current directory)
+- `session-id`: Existing OpenCode session ID to resume
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `TELEGRAM_BOT_TOKEN` | Bot token from [@BotFather](https://t.me/BotFather) | Yes |
+| `TELEGRAM_CHAT_ID` | Chat ID from [@userinfobot](https://t.me/userinfobot) | Yes |
+| `TELEGRAM_THREAD_ID` | Thread/topic ID for forum channels | No |
+| `TELEGRAM_UPDATES_URL` | Central updates endpoint for multi-instance deployments | No |
+| `TELEGRAM_SEND_URL` | Custom Telegram API endpoint (defaults to api.telegram.org) | No |
+| `OPENCODE_URL` | External OpenCode server URL (if not set, spawns local server) | No |
+
+### Configuration Files
+
+The bot loads configuration from (in order of priority):
+
+1. Environment variables (highest priority)
+2. `~/.config/opencode/telegram.json`
+3. `<repo>/.opencode/telegram.json`
+
+Example config file:
+```json
+{
+  "botToken": "your-bot-token",
+  "chatId": "your-chat-id",
+  "threadId": 123,
+  "sendUrl": "https://api.telegram.org/bot",
+  "updatesUrl": "https://your-durable-object-endpoint"
+}
+```
+
+## Advanced Features
+
+### Session Control
+
+Send messages in Telegram to interact with OpenCode:
+- **Text messages**: Sent as prompts to OpenCode
+- **Photos**: Attached as image files to prompts
+- **"x"**: Interrupt the current session
+- **"/connect"**: Get the OpenCode server URL
+
+### Interactive Controls
+
+The bot provides inline keyboard controls for:
+- **Interrupt**: Stop the current session
+- **Mode switching**: Toggle between "plan" and "build" modes
+- **Questions**: Answer multiple-choice questions from OpenCode
+- **Permissions**: Grant/deny file access permissions
+
+### Diff Viewer
+
+When OpenCode makes file edits, the bot:
+1. Generates a visual diff
+2. Uploads it to a diff viewer
+3. Shares a link to view the changes
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm or bun
+
+### Local Development
+
+```bash
+# Clone the repo
+git clone <repository-url>
+cd opencode-telegram-mirror
+
+# Install dependencies
+bun install
+
+# Run in development
+bun run start
+
+# Run tests
+bun run test:run
+```
+
+### Building
+
+```bash
+# Type check
+bun run typecheck
+
+# Run mock server for testing
+bun run test:mock-server
+```
+
+## Why Telegram?
+
+- **Cross-platform**: Works on any device with Telegram
+- **Instant sync**: Real-time message delivery
+- **Rich formatting**: Markdown, code blocks, and media support
+- **Free**: No rate limits or costs
+- **Persistent**: Message history is always available
+
+## License
+
+[Add your license here]

package/bun.lock

@@ -0,0 +1,67 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "name": "opencode-telegram-mirror",
+      "dependencies": {
+        "@opencode-ai/sdk": "latest",
+        "better-result": "^2.0.0",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "typescript": "^5.9.3",
+      },
+      "peerDependencies": {
+        "bun": ">=1.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@clack/core": ["@clack/core@0.5.0", "", { "dependencies": { "picocolors": "^1.0.0", "sisteransi": "^1.0.5" } }, "sha512-p3y0FIOwaYRUPRcMO7+dlmLh8PSRcrjuTndsiA0WAFbWES0mLZlrjVoBRZ9DzkPFJZG6KGkJmoEAY0ZcVWTkow=="],
+
+    "@clack/prompts": ["@clack/prompts@0.11.0", "", { "dependencies": { "@clack/core": "0.5.0", "picocolors": "^1.0.0", "sisteransi": "^1.0.5" } }, "sha512-pMN5FcrEw9hUkZA4f+zLlzivQSeQf5dRGJjSUbvVYDLvpKCdQx5OaknvKzgbtXOizhP+SJJJjqEbOe55uKKfAw=="],
+
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.1.15", "", {}, "sha512-9G0FTWELgyMKWKSAihiyNu/h352L5smrMOSexS05EG+knU+aBTGil3pytbgo69OgJGUWpY0onfCg2QwYaFGUug=="],
+
+    "@oven/bun-darwin-aarch64": ["@oven/bun-darwin-aarch64@1.3.5", "", { "os": "darwin", "cpu": "arm64" }, "sha512-8GvNtMo0NINM7Emk9cNAviCG3teEgr3BUX9be0+GD029zIagx2Sf54jMui1Eu1IpFm7nWHODuLEefGOQNaJ0gQ=="],
+
+    "@oven/bun-darwin-x64": ["@oven/bun-darwin-x64@1.3.5", "", { "os": "darwin", "cpu": "x64" }, "sha512-r33eHQOHAwkuiBJIwmkXIyqONQOQMnd1GMTpDzaxx9vf9+svby80LZO9Hcm1ns6KT/TBRFyODC/0loA7FAaffg=="],
+
+    "@oven/bun-darwin-x64-baseline": ["@oven/bun-darwin-x64-baseline@1.3.5", "", { "os": "darwin", "cpu": "x64" }, "sha512-p5q3rJk48qhLuLBOFehVc+kqCE03YrswTc6NCxbwsxiwfySXwcAvpF2KWKF/ZZObvvR8hCCvqe1F81b2p5r2dg=="],
+
+    "@oven/bun-linux-aarch64": ["@oven/bun-linux-aarch64@1.3.5", "", { "os": "linux", "cpu": "arm64" }, "sha512-zkcHPI23QxJ1TdqafhgkXt1NOEN8o5C460sVeNnrhfJ43LwZgtfcvcQE39x/pBedu67fatY8CU0iY00nOh46ZQ=="],
+
+    "@oven/bun-linux-aarch64-musl": ["@oven/bun-linux-aarch64-musl@1.3.5", "", { "os": "linux", "cpu": "arm64" }, "sha512-HKBeUlJdNduRkzJKZ5DXM+pPqntfC50/Hu2X65jVX0Y7hu/6IC8RaUTqpr8FtCZqqmc9wDK0OTL+Mbi9UQIKYQ=="],
+
+    "@oven/bun-linux-x64": ["@oven/bun-linux-x64@1.3.5", "", { "os": "linux", "cpu": "x64" }, "sha512-n7zhKTSDZS0yOYg5Rq8easZu5Y/o47sv0c7yGr2ciFdcie9uYV55fZ7QMqhWMGK33ezCSikh5EDkUMCIvfWpjA=="],
+
+    "@oven/bun-linux-x64-baseline": ["@oven/bun-linux-x64-baseline@1.3.5", "", { "os": "linux", "cpu": "x64" }, "sha512-FeCQyBU62DMuB0nn01vPnf3McXrKOsrK9p7sHaBFYycw0mmoU8kCq/WkBkGMnLuvQljJSyen8QBTx+fXdNupWg=="],
+
+    "@oven/bun-linux-x64-musl": ["@oven/bun-linux-x64-musl@1.3.5", "", { "os": "linux", "cpu": "x64" }, "sha512-XkCCHkByYn8BIDvoxnny898znju4xnW2kvFE8FT5+0Y62cWdcBGMZ9RdsEUTeRz16k8hHtJpaSfLcEmNTFIwRQ=="],
+
+    "@oven/bun-linux-x64-musl-baseline": ["@oven/bun-linux-x64-musl-baseline@1.3.5", "", { "os": "linux", "cpu": "x64" }, "sha512-TJiYC7KCr0XxFTsxgwQOeE7dncrEL/RSyL0EzSL3xRkrxJMWBCvCSjQn7LV1i6T7hFst0+3KoN3VWvD5BinqHA=="],
+
+    "@oven/bun-windows-x64": ["@oven/bun-windows-x64@1.3.5", "", { "os": "win32", "cpu": "x64" }, "sha512-T3xkODItb/0ftQPFsZDc7EAX2D6A4TEazQ2YZyofZToO8Q7y8YT8ooWdhd0BQiTCd66uEvgE1DCZetynwg2IoA=="],
+
+    "@oven/bun-windows-x64-baseline": ["@oven/bun-windows-x64-baseline@1.3.5", "", { "os": "win32", "cpu": "x64" }, "sha512-rtVQB9/1XK8FWJgFtsOthbPifRMYypgJwxu+pK3NHx8WvFKmq7HcPDqNr8xLzGULjQEO7eAo2aOZfONOwYz+5g=="],
+
+    "@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
+
+    "@types/node": ["@types/node@25.0.6", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-NNu0sjyNxpoiW3YuVFfNz7mxSQ+S4X2G28uqg2s+CzoqoQjLPsWSbsFFyztIAqt2vb8kfEAsJNepMGPTxFDx3Q=="],
+
+    "better-result": ["better-result@2.0.0", "", { "dependencies": { "@clack/prompts": "^0.11.0" }, "bin": { "better-result": "bin/cli.mjs" } }, "sha512-72GfHw5FQp2GylNeoQPAmXDQj2e0HBeMuyGwVd1eM5HahvC2pysdBjCOuRASfQ2ZLeykiFaVOs3455a78+Dh3Q=="],
+
+    "bun": ["bun@1.3.5", "", { "optionalDependencies": { "@oven/bun-darwin-aarch64": "1.3.5", "@oven/bun-darwin-x64": "1.3.5", "@oven/bun-darwin-x64-baseline": "1.3.5", "@oven/bun-linux-aarch64": "1.3.5", "@oven/bun-linux-aarch64-musl": "1.3.5", "@oven/bun-linux-x64": "1.3.5", "@oven/bun-linux-x64-baseline": "1.3.5", "@oven/bun-linux-x64-musl": "1.3.5", "@oven/bun-linux-x64-musl-baseline": "1.3.5", "@oven/bun-windows-x64": "1.3.5", "@oven/bun-windows-x64-baseline": "1.3.5" }, "os": [ "linux", "win32", "darwin", ], "cpu": [ "x64", "arm64", ], "bin": { "bun": "bin/bun.exe", "bunx": "bin/bunx.exe" } }, "sha512-c1YHIGUfgvYPJmLug5QiLzNWlX2Dg7X/67JWu1Va+AmMXNXzC/KQn2lgQ7rD+n1u1UqDpJMowVGGxTNpbPydNw=="],
+
+    "bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
+
+    "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
+
+    "sisteransi": ["sisteransi@1.0.5", "", {}, "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "opencode-telegram-mirror",
+	"version": "0.3.0",
+	"description": "Standalone bot that mirrors OpenCode sessions to Telegram topics",
+	"type": "module",
+	"main": "src/main.ts",
+	"bin": {
+		"opencode-telegram-mirror": "./src/main.ts"
+	},
+	"scripts": {
+		"start": "bun run src/main.ts",
+		"typecheck": "tsc --noEmit",
+		"test:mock-server": "bun run test/mock-server.ts",
+		"test:run": "bun run test/run-test.ts"
+	},
+	"dependencies": {
+		"@opencode-ai/sdk": "latest",
+		"better-result": "^2.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"typescript": "^5.9.3"
+	},
+	"peerDependencies": {
+		"bun": ">=1.0.0"
+	}
+}

package/src/config.ts

@@ -0,0 +1,99 @@
+/**
+ * Bot configuration loading
+ */
+
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+import { Result, TaggedError } from "better-result"
+import type { LogFn } from "./log"
+
+export interface BotConfig {
+  botToken?: string
+  chatId?: string
+  threadId?: number
+  // URL to poll for updates (Cloudflare DO endpoint)
+  updatesUrl?: string
+  // URL to send messages (defaults to Telegram API if not set)
+  sendUrl?: string
+}
+
+export class ConfigLoadError extends TaggedError("ConfigLoadError")<{
+  path: string
+  message: string
+  cause: unknown
+}>() {
+  constructor(args: { path: string; cause: unknown }) {
+    const message = `Failed to load config at ${args.path}`
+    super({ ...args, message })
+  }
+}
+
+export type ConfigLoadResult = Result<BotConfig, ConfigLoadError>
+
+export async function loadConfig(directory: string, log?: LogFn): Promise<ConfigLoadResult> {
+  const config: BotConfig = {}
+  const homeDir = process.env.HOME || process.env.USERPROFILE || ""
+
+  const configPaths = [
+    join(homeDir, ".config", "opencode", "telegram.json"),
+    join(directory, ".opencode", "telegram.json"),
+  ]
+
+  log?.("debug", "Checking config file paths", { paths: configPaths })
+
+  for (const configPath of configPaths) {
+    const fileResult = await Result.tryPromise({
+      try: async () => {
+        const content = await readFile(configPath, "utf-8")
+        return JSON.parse(content) as BotConfig
+      },
+      catch: (error) => new ConfigLoadError({ path: configPath, cause: error }),
+    })
+
+    if (fileResult.status === "ok") {
+      Object.assign(config, fileResult.value)
+      log?.("info", "Loaded config file", {
+        path: configPath,
+        keys: Object.keys(fileResult.value),
+      })
+    } else {
+      log?.("debug", "Config file not found or invalid", {
+        path: configPath,
+        error: String(fileResult.error).slice(0, 100),
+      })
+    }
+  }
+
+  // Environment variables override file config
+  const envOverrides: string[] = []
+
+  if (process.env.TELEGRAM_BOT_TOKEN) {
+    config.botToken = process.env.TELEGRAM_BOT_TOKEN
+    envOverrides.push("TELEGRAM_BOT_TOKEN")
+  }
+  if (process.env.TELEGRAM_CHAT_ID) {
+    config.chatId = process.env.TELEGRAM_CHAT_ID
+    envOverrides.push("TELEGRAM_CHAT_ID")
+  }
+  if (process.env.TELEGRAM_THREAD_ID) {
+    const parsed = Number(process.env.TELEGRAM_THREAD_ID)
+    if (!Number.isNaN(parsed)) {
+      config.threadId = parsed
+      envOverrides.push("TELEGRAM_THREAD_ID")
+    }
+  }
+  if (process.env.TELEGRAM_UPDATES_URL) {
+    config.updatesUrl = process.env.TELEGRAM_UPDATES_URL
+    envOverrides.push("TELEGRAM_UPDATES_URL")
+  }
+  if (process.env.TELEGRAM_SEND_URL) {
+    config.sendUrl = process.env.TELEGRAM_SEND_URL
+    envOverrides.push("TELEGRAM_SEND_URL")
+  }
+
+  if (envOverrides.length > 0) {
+    log?.("info", "Environment variable overrides applied", { variables: envOverrides })
+  }
+
+  return Result.ok(config)
+}