izackp/takopi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update readme and developer guide

Browse Source
This commit is contained in:
banteg
2025-12-29 14:17:40 +04:00
parent a67cc010bb
commit 752a3752ad
2 changed files with 10 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
codex_telegram_bridge/developing.md
+6 -3
View File
@@ -13,7 +13,8 @@ The orchestrator module containing:
| `main()` / `run()` | CLI entry point via Typer | | `main()` / `run()` | CLI entry point via Typer |
| `BridgeConfig` | Frozen dataclass holding runtime config | | `BridgeConfig` | Frozen dataclass holding runtime config |
| `CodexExecRunner` | Spawns `codex exec`, streams JSONL, handles cancellation | | `CodexExecRunner` | Spawns `codex exec`, streams JSONL, handles cancellation |
| `_run_main_loop()` | Long-poll loop for Telegram updates | | `poll_updates()` | Async generator that drains backlog, long-polls updates, filters messages |
| `_run_main_loop()` | TaskGroup-based main loop that spawns per-message handlers |
| `_handle_message()` | Per-message handler with progress updates | | `_handle_message()` | Per-message handler with progress updates |
| `extract_session_id()` | Parses `resume: <uuid>` from message text | | `extract_session_id()` | Parses `resume: <uuid>` from message text |
| `truncate_for_telegram()` | Smart truncation preserving resume lines | | `truncate_for_telegram()` | Smart truncation preserving resume lines |
@@ -21,6 +22,7 @@ The orchestrator module containing:
**Key patterns:** **Key patterns:**
- Per-session locks prevent concurrent resumes to the same `session_id` - Per-session locks prevent concurrent resumes to the same `session_id`
- `asyncio.Semaphore` limits overall concurrency (default: 16) - `asyncio.Semaphore` limits overall concurrency (default: 16)
- `asyncio.TaskGroup` manages per-message tasks
- Progress edits are throttled to ~2s intervals - Progress edits are throttled to ~2s intervals
- Subprocess stderr is drained to a bounded deque for error reporting - Subprocess stderr is drained to a bounded deque for error reporting
@@ -96,7 +98,9 @@ def setup_logging(*, debug: bool):
``` ```
Telegram Update Telegram Update
↓ ↓
_run_main_loop() validates chat_id, extracts text poll_updates() drains backlog, long-polls, filters chat_id == from_id == cfg.chat_id
↓
_run_main_loop() spawns tasks in TaskGroup
↓ ↓
_handle_message() spawned as task _handle_message() spawned as task
↓ ↓
@@ -132,4 +136,3 @@ Same as above, but:
| Telegram API error | Logged, edit skipped (progress continues) | | Telegram API error | Logged, edit skipped (progress continues) |
| Cancellation | Subprocess terminated, CancelledError re-raised | | Cancellation | Subprocess terminated, CancelledError re-raised |
| No agent_message | Final shows "error" status | | No agent_message | Final shows "error" status |
codex_telegram_bridge/readme.md
+4 -1
View File
@@ -42,6 +42,8 @@ chat_id = 123456789
| `bot_token` | Telegram Bot API token from [@BotFather](https://t.me/BotFather) | | `bot_token` | Telegram Bot API token from [@BotFather](https://t.me/BotFather) |
| `chat_id` | Allowed chat ID (also used for startup notifications) | | `chat_id` | Allowed chat ID (also used for startup notifications) |
The bridge only accepts messages where the chat ID equals the sender ID and both match `chat_id` (i.e., private chat with that user).
### Running ### Running
```bash ```bash
@@ -81,10 +83,11 @@ resume: `019b66fc-64c2-7a71-81cd-081c504cfeb2`
- **Startup**: Pending updates are drained (ignored) on startup - **Startup**: Pending updates are drained (ignored) on startup
- **Progress**: Updates are throttled to ~2s intervals, sent silently - **Progress**: Updates are throttled to ~2s intervals, sent silently
- **Notifications**: Codex's built-in notify is disabled (bridge handles it) - **Notifications**: Codex's built-in notify is disabled (bridge handles it)
- **Filtering**: Only accepts messages where chat ID equals sender ID and matches `chat_id`
## Development ## Development
See [`src/codex_telegram_bridge/developing.md`](src/codex_telegram_bridge/developing.md) for architecture details. See [`developing.md`](developing.md) for architecture details.
```bash ```bash
# Run tests # Run tests