claude-code-telegrammer 0.4.0__tar.gz → 0.4.2__tar.gz

claude_code_telegrammer-0.4.2/.env.example

@@ -0,0 +1,20 @@
+# Claude Code Telegrammer — Environment Variables
+# Copy to .env and fill in your values
+
+# Required: Telegram bot token from @BotFather
+CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN=123456789:AAH...
+
+# Required: Comma-separated Telegram user IDs allowed to send messages
+CLAUDE_CODE_TELEGRAMMER_TELEGRAM_ALLOWED_USERS=YOUR_TELEGRAM_USER_ID
+
+# Optional: State directory (default: ~/.claude-code-telegrammer)
+CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR=~/.claude-code-telegrammer
+
+# Optional: Hostname for message metadata (default: os.hostname())
+CLAUDE_CODE_TELEGRAMMER_TELEGRAM_HOST_NAME=
+
+# Optional: Project identifier for message metadata (default: cwd)
+CLAUDE_CODE_TELEGRAMMER_TELEGRAM_PROJECT=
+
+# Optional: Agent ID for message metadata (default: 'telegram')
+CLAUDE_CODE_TELEGRAMMER_TELEGRAM_AGENT_ID=

claude_code_telegrammer-0.4.2/.mcp.json.example

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "claude-code-telegrammer": {
+      "type": "stdio",
+      "command": "bun",
+      "args": ["run", "/path/to/claude-code-telegrammer/ts/telegram-server.ts"],
+      "env": {
+        "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN": "123456789:AAH...",
+        "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_ALLOWED_USERS": "YOUR_TELEGRAM_USER_ID",
+        "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR": "~/.claude-code-telegrammer"
+      }
+    }
+  }
+}

{claude_code_telegrammer-0.4.0 → claude_code_telegrammer-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-telegrammer
-Version: 0.4.0
+Version: 0.4.2
 Summary: Custom Telegram MCP server + TUI auto-responder for running Claude Code as an autonomous Telegram agent
 Project-URL: Homepage, https://github.com/ywatanabe1989/claude-code-telegrammer
 Project-URL: Repository, https://github.com/ywatanabe1989/claude-code-telegrammer.git
@@ -62,23 +62,63 @@ Description-Content-Type: text/markdown
 
 ---
 
-## Problem
-
-The official `plugin:telegram@claude-plugins-official` has several unresolved issues that make it unusable for production autonomous agents:
-
-- **[#851](https://github.com/anthropics/claude-code/issues/851)** -- `STATE_DIR` not respected; access.json path hardcoded
-- **[#1075](https://github.com/anthropics/claude-code/issues/1075)** -- 409 Conflict errors when multiple instances poll the same bot
-- **[#1146](https://github.com/anthropics/claude-code/issues/1146)** -- Zombie CPU consumption after session ends
-
-Additionally, Claude Code sessions running unattended will stall at permission prompts or idle states with no way to recover.
-
-## Solution
-
-Two subsystems that replace and extend the official plugin:
-
-1. **Custom Telegram MCP Server** (`ts/`) -- A self-contained MCP server that fixes all three official plugin issues: configurable state directory via `CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR`, PID-based single-instance lock, and clean shutdown on stdin close/SIGTERM. Provides 10 MCP tools (vs 3 in the official plugin), SQLite message persistence, allowlist-based access control, and inbound reaction (`message_reaction`) delivery. Incoming messages are acknowledged with a 📩 reaction.
-
-2. **TUI Watchdog** (`lib/`) -- Polls a GNU Screen session, detects Claude Code's TUI state via pattern matching, and sends keystrokes to keep the agent running unattended (auto-accepts permission prompts, re-engages on idle). Throttled with burst limits to prevent runaway responses. Orchestration and lifecycle management is handled by [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container).
+## Problem and Solution
+
+<table>
+<tr>
+  <th align="center">#</th>
+  <th>Problem</th>
+  <th>Solution</th>
+</tr>
+<tr valign="top">
+  <td align="center">1</td>
+  <td><h4>Hardcoded paths</h4>The official plugin hardcodes <code>~/.claude/</code> as its state directory (<a href="https://github.com/anthropics/claude-code/issues/851">#851</a>), making it impossible to run multiple bots or customize where access.json lives.</td>
+  <td><h4>Configurable state directory</h4>All state (DB, lock, access config) lives under <code>CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR</code>. Run as many bots as you want, each with its own isolated state.</td>
+</tr>
+<tr valign="top">
+  <td align="center">2</td>
+  <td><h4>409 Conflict crashes</h4>No single-instance guard — multiple sessions polling the same bot get 409 errors and crash each other (<a href="https://github.com/anthropics/claude-code/issues/1075">#1075</a>).</td>
+  <td><h4>PID-based lock</h4>Automatic single-instance enforcement via PID lock file. Second instance detects the conflict and waits instead of crashing.</td>
+</tr>
+<tr valign="top">
+  <td align="center">3</td>
+  <td><h4>Zombie CPU consumption</h4>After session ends, the plugin process lingers at 100% CPU — requires manual kill (<a href="https://github.com/anthropics/claude-code/issues/1146">#1146</a>).</td>
+  <td><h4>Clean shutdown</h4>Exits gracefully on stdin close, SIGTERM, or SIGINT. No zombies, no manual cleanup.</td>
+</tr>
+<tr valign="top">
+  <td align="center">4</td>
+  <td><h4>Only 3 basic tools</h4>The official plugin provides just send, get_updates, and set_reaction — no history, no search, no file handling, no message editing.</td>
+  <td><h4>10 MCP tools</h4>reply, react, edit_message, get_history, get_unread, mark_read, download_attachment, send_document, search_messages, get_context — everything an autonomous agent needs.</td>
+</tr>
+<tr valign="top">
+  <td align="center">5</td>
+  <td><h4>No message persistence</h4>Messages vanish after delivery. No way to search past conversations, track read status, or build context from history.</td>
+  <td><h4>SQLite message store</h4>All messages persisted in WAL-mode SQLite with full-text search, reply threading (reply_to_message_id), read/replied tracking, and attachment metadata.</td>
+</tr>
+<tr valign="top">
+  <td align="center">6</td>
+  <td><h4>No access control for groups</h4>Basic allowlist only — no per-group policies, no hot-reload when config changes.</td>
+  <td><h4>DM + group policies</h4>Allowlist-based access control with separate DM and group chat policies via <code>access.json</code>, hot-reloaded on file change (mtime-based).</td>
+</tr>
+<tr valign="top">
+  <td align="center">7</td>
+  <td><h4>No attachment support</h4>Cannot download inbound files or upload documents to chats.</td>
+  <td><h4>Full attachment handling</h4>Inbound photos, documents, voice, audio, and video are auto-downloaded. Upload local files via <code>send_document</code> tool.</td>
+</tr>
+<tr valign="top">
+  <td align="center">8</td>
+  <td><h4>Sessions stall unattended</h4>Claude Code halts at permission prompts or idle states with no way to recover — the agent just stops working.</td>
+  <td><h4>TUI Watchdog</h4>Polls GNU Screen buffer, detects TUI state via pattern matching, sends keystrokes to auto-accept prompts and re-engage on idle. Throttled with burst limits.</td>
+</tr>
+</table>
+
+<p align="center"><sub><b>Table 1.</b> Eight issues with the official Telegram plugin (as of April 2026) and how claude-code-telegrammer addresses each. These problems make the official plugin unusable for production autonomous agents.</sub></p>
+
+### Architecture
+
+1. **Custom Telegram MCP Server** (`ts/`) -- Self-contained Bun + MCP server. 10 tools, SQLite persistence, allowlist access control, attachment handling, reaction support. Incoming messages acknowledged with 📩. Built-in responsiveness policy directs the agent to reply immediately and delegate heavy work to background subagents.
+
+2. **TUI Watchdog** (`lib/`) -- Polls a GNU Screen session, detects Claude Code's TUI state via pattern matching, and sends keystrokes to keep the agent running unattended (auto-accepts permission prompts, re-engages on idle). Throttled with burst limits to prevent runaway responses. Orchestration handled by [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container).
 
 <details>
 <summary><strong>MCP Tools (10)</strong></summary>
@@ -98,28 +138,38 @@ Two subsystems that replace and extend the official plugin:
 
 </details>
 
+### Important: Bot Token Exclusivity
+
+This MCP server **must be the sole consumer** of its configured Telegram bot token. The Telegram Bot API allows only one `getUpdates` long-polling connection per token.
+
+**What happens with duplicate consumers:**
+
+| Scenario | Symptom | Detection |
+|----------|---------|-----------|
+| Two pollers start simultaneously | One gets 409, the other wins silently | The loser sees `409 Conflict` in logs |
+| Two pollers start sequentially | Both appear to work, but only one receives messages | **No error** — the other poller gets empty responses forever |
+| Webhook active + poller | Poller gets nothing | **No error** — Telegram ignores `getUpdates` when webhook is set |
+
+**Why 409 detection alone is insufficient:** The Telegram API does not reliably return 409 for all conflict cases. When two consumers poll sequentially (not overlapping), both connections succeed — one simply receives all messages while the other gets none, with no error. The server performs a `timeout=3` preflight check at startup to catch overlapping polls, but this cannot detect the sequential case.
+
+**If messages aren't arriving:**
+1. Check if another process is polling the same token: `ps aux | grep telegram-server`
+2. Check if a webhook is set: `curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo`
+3. Use a separate bot token per component (recommended)
+4. Or disable the other consumer
+
 ## Installation
 
 ### Prerequisites
 
-- Python >= 3.10 and GNU Screen (for watchdog/CLI)
 - [Bun](https://bun.sh/) >= 1.0 (for the MCP server)
+- GNU Screen (for watchdog, optional)
 
 ### Install
 
-```bash
-pip install claude-code-telegrammer
-```
-
-Or from source:
-
 ```bash
 git clone https://github.com/ywatanabe1989/claude-code-telegrammer.git
-cd claude-code-telegrammer
-pip install -e .
-
-# Install TypeScript dependencies for the MCP server
-cd ts && bun install
+cd claude-code-telegrammer/ts && bun install
 ```
 
 ## Quickstart
@@ -172,7 +222,7 @@ claude \
     --dangerously-load-development-channels server:claude-code-telegrammer
 ```
 
-For full agent orchestration (screen sessions, watchdog, YAML configs), see [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container).
+You should see `Listening for channel messages from: server:claude-code-telegrammer` in the Claude Code TUI. Send a message from Telegram to your bot — Claude Code will receive it as a channel notification.
 
 ## Interfaces
 

{claude_code_telegrammer-0.4.0 → claude_code_telegrammer-0.4.2}/README.md

@@ -29,23 +29,63 @@
 
 ---
 
-## Problem
-
-The official `plugin:telegram@claude-plugins-official` has several unresolved issues that make it unusable for production autonomous agents:
-
-- **[#851](https://github.com/anthropics/claude-code/issues/851)** -- `STATE_DIR` not respected; access.json path hardcoded
-- **[#1075](https://github.com/anthropics/claude-code/issues/1075)** -- 409 Conflict errors when multiple instances poll the same bot
-- **[#1146](https://github.com/anthropics/claude-code/issues/1146)** -- Zombie CPU consumption after session ends
-
-Additionally, Claude Code sessions running unattended will stall at permission prompts or idle states with no way to recover.
-
-## Solution
-
-Two subsystems that replace and extend the official plugin:
-
-1. **Custom Telegram MCP Server** (`ts/`) -- A self-contained MCP server that fixes all three official plugin issues: configurable state directory via `CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR`, PID-based single-instance lock, and clean shutdown on stdin close/SIGTERM. Provides 10 MCP tools (vs 3 in the official plugin), SQLite message persistence, allowlist-based access control, and inbound reaction (`message_reaction`) delivery. Incoming messages are acknowledged with a 📩 reaction.
-
-2. **TUI Watchdog** (`lib/`) -- Polls a GNU Screen session, detects Claude Code's TUI state via pattern matching, and sends keystrokes to keep the agent running unattended (auto-accepts permission prompts, re-engages on idle). Throttled with burst limits to prevent runaway responses. Orchestration and lifecycle management is handled by [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container).
+## Problem and Solution
+
+<table>
+<tr>
+  <th align="center">#</th>
+  <th>Problem</th>
+  <th>Solution</th>
+</tr>
+<tr valign="top">
+  <td align="center">1</td>
+  <td><h4>Hardcoded paths</h4>The official plugin hardcodes <code>~/.claude/</code> as its state directory (<a href="https://github.com/anthropics/claude-code/issues/851">#851</a>), making it impossible to run multiple bots or customize where access.json lives.</td>
+  <td><h4>Configurable state directory</h4>All state (DB, lock, access config) lives under <code>CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR</code>. Run as many bots as you want, each with its own isolated state.</td>
+</tr>
+<tr valign="top">
+  <td align="center">2</td>
+  <td><h4>409 Conflict crashes</h4>No single-instance guard — multiple sessions polling the same bot get 409 errors and crash each other (<a href="https://github.com/anthropics/claude-code/issues/1075">#1075</a>).</td>
+  <td><h4>PID-based lock</h4>Automatic single-instance enforcement via PID lock file. Second instance detects the conflict and waits instead of crashing.</td>
+</tr>
+<tr valign="top">
+  <td align="center">3</td>
+  <td><h4>Zombie CPU consumption</h4>After session ends, the plugin process lingers at 100% CPU — requires manual kill (<a href="https://github.com/anthropics/claude-code/issues/1146">#1146</a>).</td>
+  <td><h4>Clean shutdown</h4>Exits gracefully on stdin close, SIGTERM, or SIGINT. No zombies, no manual cleanup.</td>
+</tr>
+<tr valign="top">
+  <td align="center">4</td>
+  <td><h4>Only 3 basic tools</h4>The official plugin provides just send, get_updates, and set_reaction — no history, no search, no file handling, no message editing.</td>
+  <td><h4>10 MCP tools</h4>reply, react, edit_message, get_history, get_unread, mark_read, download_attachment, send_document, search_messages, get_context — everything an autonomous agent needs.</td>
+</tr>
+<tr valign="top">
+  <td align="center">5</td>
+  <td><h4>No message persistence</h4>Messages vanish after delivery. No way to search past conversations, track read status, or build context from history.</td>
+  <td><h4>SQLite message store</h4>All messages persisted in WAL-mode SQLite with full-text search, reply threading (reply_to_message_id), read/replied tracking, and attachment metadata.</td>
+</tr>
+<tr valign="top">
+  <td align="center">6</td>
+  <td><h4>No access control for groups</h4>Basic allowlist only — no per-group policies, no hot-reload when config changes.</td>
+  <td><h4>DM + group policies</h4>Allowlist-based access control with separate DM and group chat policies via <code>access.json</code>, hot-reloaded on file change (mtime-based).</td>
+</tr>
+<tr valign="top">
+  <td align="center">7</td>
+  <td><h4>No attachment support</h4>Cannot download inbound files or upload documents to chats.</td>
+  <td><h4>Full attachment handling</h4>Inbound photos, documents, voice, audio, and video are auto-downloaded. Upload local files via <code>send_document</code> tool.</td>
+</tr>
+<tr valign="top">
+  <td align="center">8</td>
+  <td><h4>Sessions stall unattended</h4>Claude Code halts at permission prompts or idle states with no way to recover — the agent just stops working.</td>
+  <td><h4>TUI Watchdog</h4>Polls GNU Screen buffer, detects TUI state via pattern matching, sends keystrokes to auto-accept prompts and re-engage on idle. Throttled with burst limits.</td>
+</tr>
+</table>
+
+<p align="center"><sub><b>Table 1.</b> Eight issues with the official Telegram plugin (as of April 2026) and how claude-code-telegrammer addresses each. These problems make the official plugin unusable for production autonomous agents.</sub></p>
+
+### Architecture
+
+1. **Custom Telegram MCP Server** (`ts/`) -- Self-contained Bun + MCP server. 10 tools, SQLite persistence, allowlist access control, attachment handling, reaction support. Incoming messages acknowledged with 📩. Built-in responsiveness policy directs the agent to reply immediately and delegate heavy work to background subagents.
+
+2. **TUI Watchdog** (`lib/`) -- Polls a GNU Screen session, detects Claude Code's TUI state via pattern matching, and sends keystrokes to keep the agent running unattended (auto-accepts permission prompts, re-engages on idle). Throttled with burst limits to prevent runaway responses. Orchestration handled by [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container).
 
 <details>
 <summary><strong>MCP Tools (10)</strong></summary>
@@ -65,28 +105,38 @@ Two subsystems that replace and extend the official plugin:
 
 </details>
 
+### Important: Bot Token Exclusivity
+
+This MCP server **must be the sole consumer** of its configured Telegram bot token. The Telegram Bot API allows only one `getUpdates` long-polling connection per token.
+
+**What happens with duplicate consumers:**
+
+| Scenario | Symptom | Detection |
+|----------|---------|-----------|
+| Two pollers start simultaneously | One gets 409, the other wins silently | The loser sees `409 Conflict` in logs |
+| Two pollers start sequentially | Both appear to work, but only one receives messages | **No error** — the other poller gets empty responses forever |
+| Webhook active + poller | Poller gets nothing | **No error** — Telegram ignores `getUpdates` when webhook is set |
+
+**Why 409 detection alone is insufficient:** The Telegram API does not reliably return 409 for all conflict cases. When two consumers poll sequentially (not overlapping), both connections succeed — one simply receives all messages while the other gets none, with no error. The server performs a `timeout=3` preflight check at startup to catch overlapping polls, but this cannot detect the sequential case.
+
+**If messages aren't arriving:**
+1. Check if another process is polling the same token: `ps aux | grep telegram-server`
+2. Check if a webhook is set: `curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo`
+3. Use a separate bot token per component (recommended)
+4. Or disable the other consumer
+
 ## Installation
 
 ### Prerequisites
 
-- Python >= 3.10 and GNU Screen (for watchdog/CLI)
 - [Bun](https://bun.sh/) >= 1.0 (for the MCP server)
+- GNU Screen (for watchdog, optional)
 
 ### Install
 
-```bash
-pip install claude-code-telegrammer
-```
-
-Or from source:
-
 ```bash
 git clone https://github.com/ywatanabe1989/claude-code-telegrammer.git
-cd claude-code-telegrammer
-pip install -e .
-
-# Install TypeScript dependencies for the MCP server
-cd ts && bun install
+cd claude-code-telegrammer/ts && bun install
 ```
 
 ## Quickstart
@@ -139,7 +189,7 @@ claude \
     --dangerously-load-development-channels server:claude-code-telegrammer
 ```
 
-For full agent orchestration (screen sessions, watchdog, YAML configs), see [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container).
+You should see `Listening for channel messages from: server:claude-code-telegrammer` in the Claude Code TUI. Send a message from Telegram to your bot — Claude Code will receive it as a channel notification.
 
 ## Interfaces
 

claude_code_telegrammer-0.4.2/bin/claude-code-telegrammer-hook

@@ -0,0 +1,187 @@
+#!/bin/bash
+# claude-code-telegrammer-hook — Entry point for scitex-agent-container hooks
+# Called by agent-container's post_start/pre_stop hooks.
+#
+# Usage:
+#   claude-code-telegrammer-hook pre-start     # Write access.json (before Claude Code)
+#   claude-code-telegrammer-hook post-start    # Start watchdog + send startup commands
+#   claude-code-telegrammer-hook pre-stop      # Stop watchdog
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source "$SCRIPT_DIR/lib/common.sh"
+
+# Expect these env vars from agent-container:
+#   AGENT_CONFIG_PATH  — full path to agent YAML
+#   AGENT_SCREEN_NAME  — screen session name
+#   AGENT_NAME         — agent name
+
+cmd="${1:-}"
+
+case "$cmd" in
+  pre-start)
+    if [[ -z "${AGENT_CONFIG_PATH:-}" ]]; then
+      log_warn "AGENT_CONFIG_PATH not set, skipping pre-start"
+      exit 0
+    fi
+
+    # 1. Map bot_token_env → CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN
+    BOT_TOKEN_ENV=$(yaml_get "$AGENT_CONFIG_PATH" "spec.telegram.bot_token_env" "")
+    if [[ -n "$BOT_TOKEN_ENV" && "$BOT_TOKEN_ENV" != "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN" ]]; then
+      TOKEN_VAL="${!BOT_TOKEN_ENV:-}"
+      if [[ -n "$TOKEN_VAL" ]]; then
+        export CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN="$TOKEN_VAL"
+      fi
+    fi
+
+    # 2. Write access.json
+    AUTO_CONNECT=$(yaml_get "$AGENT_CONFIG_PATH" "spec.telegram.auto_connect" "true")
+    STATE_DIR="${CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR:-$HOME/.scitex/agent-container/telegram}"
+
+    # Resolve bot_id from token for state dir
+    if [[ -n "${CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN:-}" ]]; then
+      BOT_ID="${CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN%%:*}"
+      STATE_DIR="$HOME/.scitex/agent-container/telegram/$BOT_ID"
+    fi
+    mkdir -p "$STATE_DIR"
+
+    # Parse allowed_users via Python (yaml_get returns flat values, not JSON)
+    if [[ "$AUTO_CONNECT" == "true" || "$AUTO_CONNECT" == "True" ]]; then
+      python3 -c "
+import yaml, json
+with open('$AGENT_CONFIG_PATH') as f:
+    raw = yaml.safe_load(f)
+users = raw.get('spec',{}).get('telegram',{}).get('allowed_users',[]) or []
+users = [str(u) for u in users]
+data = {'dmPolicy': 'allowlist', 'allowFrom': users}
+with open('$STATE_DIR/access.json', 'w') as f:
+    json.dump(data, f, indent=2)
+    f.write('\n')
+print('Wrote access.json with', len(users), 'allowed users to $STATE_DIR')
+"
+    fi
+
+    # 3. Write .env for the MCP server
+    echo "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN=${CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN:-}" > "$STATE_DIR/.env"
+    chmod 600 "$STATE_DIR/.env"
+    log_info "Wrote .env to $STATE_DIR"
+
+    # 4. Write MCP config JSON for --mcp-config
+    AGENT_NAME="${AGENT_NAME:-telegrammer}"
+    MCP_DIR="$HOME/.scitex/agent-container/cache/mcp-configs"
+    mkdir -p "$MCP_DIR"
+    # Find telegram-server.ts: check project root first, then relative to SCRIPT_DIR
+    TS_SERVER=""
+    for candidate in \
+      "$SCRIPT_DIR/../ts/telegram-server.ts" \
+      "$SCRIPT_DIR/ts/telegram-server.ts" \
+      "$(python3 -c 'import claude_code_telegrammer; import os; print(os.path.join(os.path.dirname(claude_code_telegrammer.__file__), "..", "..", "ts", "telegram-server.ts"))' 2>/dev/null)" \
+    ; do
+      if [[ -f "$candidate" ]]; then
+        TS_SERVER="$(cd "$(dirname "$candidate")" && pwd)/$(basename "$candidate")"
+        break
+      fi
+    done
+    if [[ -z "$TS_SERVER" ]]; then
+      log_warn "telegram-server.ts not found"
+      exit 1
+    fi
+
+    python3 -c "
+import yaml, json, os
+with open('$AGENT_CONFIG_PATH') as f:
+    raw = yaml.safe_load(f)
+users = raw.get('spec',{}).get('telegram',{}).get('allowed_users',[]) or []
+users_str = ','.join(str(u) for u in users)
+config = {
+    'mcpServers': {
+        'claude-code-telegrammer': {
+            'type': 'stdio',
+            'command': 'bun',
+            'args': ['run', '$TS_SERVER'],
+            'env': {
+                'CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN': os.environ.get('CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN', ''),
+                'CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR': '$STATE_DIR',
+                'CLAUDE_CODE_TELEGRAMMER_TELEGRAM_ALLOWED_USERS': users_str
+            }
+        }
+    }
+}
+# Write to both /tmp (for --mcp-config) and workdir .mcp.json (for --dangerously-load-development-channels)
+path = '$MCP_DIR/mcp-$AGENT_NAME.json'
+with open(path, 'w') as f:
+    json.dump(config, f, indent=2)
+    f.write('\n')
+print('Wrote MCP config to', path)
+
+# Also write to workdir .mcp.json so --dangerously-load-development-channels can find it
+import yaml as _yaml
+with open('$AGENT_CONFIG_PATH') as f:
+    agent_cfg = _yaml.safe_load(f)
+workdir = os.path.expanduser(agent_cfg.get('spec', {}).get('workdir', '~/proj'))
+mcp_json_path = os.path.join(workdir, '.mcp.json')
+# Merge with existing .mcp.json if present
+existing = {}
+try:
+    with open(mcp_json_path) as f:
+        existing = json.load(f)
+except (FileNotFoundError, json.JSONDecodeError):
+    pass
+existing.setdefault('mcpServers', {})
+existing['mcpServers']['claude-code-telegrammer'] = config['mcpServers']['claude-code-telegrammer']
+with open(mcp_json_path, 'w') as f:
+    json.dump(existing, f, indent=2)
+    f.write('\n')
+print('Wrote .mcp.json to', mcp_json_path)
+"
+    ;;
+
+  post-start)
+    # Send startup commands (screen must exist)
+    SESSION="${AGENT_SCREEN_NAME:-cld-telegram}"
+    if [[ -n "${AGENT_CONFIG_PATH:-}" ]]; then
+      claude-code-telegrammer-init --session "$SESSION" --config "$AGENT_CONFIG_PATH"
+    fi
+
+    # Start watchdog if enabled
+    if [[ -n "${AGENT_CONFIG_PATH:-}" ]]; then
+      WATCHDOG_ENABLED=$(yaml_get "$AGENT_CONFIG_PATH" "spec.watchdog.enabled" "false")
+      if [[ "$WATCHDOG_ENABLED" == "true" || "$WATCHDOG_ENABLED" == "True" ]]; then
+        INTERVAL=$(yaml_get "$AGENT_CONFIG_PATH" "spec.watchdog.interval" "1.5")
+        RESP_YN=$(yaml_get "$AGENT_CONFIG_PATH" "spec.watchdog.responses.y_n" "1")
+        RESP_YYN=$(yaml_get "$AGENT_CONFIG_PATH" "spec.watchdog.responses.y_y_n" "2")
+        RESP_WAIT=$(yaml_get "$AGENT_CONFIG_PATH" "spec.watchdog.responses.waiting" "/speak-and-call")
+
+        WATCHDOG_SESSION="${SESSION}-watchdog"
+
+        export CLAUDE_CODE_TELEGRAMMER_SESSION="$SESSION"
+        export CLAUDE_CODE_TELEGRAMMER_WATCHDOG_INTERVAL="$INTERVAL"
+        export CLAUDE_CODE_TELEGRAMMER_RESP_Y_N="$RESP_YN"
+        export CLAUDE_CODE_TELEGRAMMER_RESP_Y_Y_N="$RESP_YYN"
+        export CLAUDE_CODE_TELEGRAMMER_RESP_WAITING="$RESP_WAIT"
+
+        WATCHDOG_BIN=$(which claude-code-telegrammer-watchdog 2>/dev/null || echo "")
+        if [[ -n "$WATCHDOG_BIN" ]]; then
+          screen -dmS "$WATCHDOG_SESSION" bash -c "$WATCHDOG_BIN --session $SESSION --interval $INTERVAL"
+          log_info "Watchdog started: $WATCHDOG_SESSION"
+        else
+          log_warn "claude-code-telegrammer-watchdog not found in PATH"
+        fi
+      fi
+    fi
+    ;;
+
+  pre-stop)
+    SESSION="${AGENT_SCREEN_NAME:-cld-telegram}"
+    WATCHDOG_SESSION="${SESSION}-watchdog"
+    if screen -ls 2>/dev/null | grep -q "$WATCHDOG_SESSION"; then
+      screen -S "$WATCHDOG_SESSION" -X quit 2>/dev/null || true
+      log_info "Watchdog stopped: $WATCHDOG_SESSION"
+    fi
+    ;;
+
+  *)
+    echo "Usage: claude-code-telegrammer-hook {post-start|pre-stop}"
+    exit 1
+    ;;
+esac

claude_code_telegrammer-0.4.2/bin/claude-code-telegrammer-init

@@ -0,0 +1,104 @@
+#!/bin/bash
+# claude-code-telegrammer-init — Send startup commands to a Claude Code screen session
+# and optionally configure Telegram access.json.
+#
+# Usage: claude-code-telegrammer-init --session cld-telegram --config telegram-master.yaml
+#
+# Requires: yq (or python3 with PyYAML as fallback)
+
+set -euo pipefail
+
+SESSION=""
+CONFIG=""
+
+usage() {
+    echo "Usage: claude-code-telegrammer-init --session <screen-session> --config <yaml-config>"
+    echo ""
+    echo "Options:"
+    echo "  --session  Screen session name to send commands to"
+    echo "  --config   YAML config file with startup_commands and telegram sections"
+    echo "  --help     Show this help message"
+    exit "${1:-0}"
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --session) SESSION="$2"; shift 2 ;;
+        --config)  CONFIG="$2";  shift 2 ;;
+        --help)    usage 0 ;;
+        *)         echo "Unknown option: $1"; usage 1 ;;
+    esac
+done
+
+if [[ -z "$SESSION" || -z "$CONFIG" ]]; then
+    echo "Error: --session and --config are required."
+    usage 1
+fi
+
+if [[ ! -f "$CONFIG" ]]; then
+    echo "Error: Config file not found: $CONFIG"
+    exit 1
+fi
+
+# Use python3 to parse YAML (always available in our environment)
+parse_yaml() {
+    python3 -c "
+import sys, yaml, json
+
+with open('$CONFIG') as f:
+    raw = yaml.safe_load(f)
+
+spec = raw.get('spec', {})
+result = {
+    'startup_commands': spec.get('startup_commands', []) or [],
+    'telegram': spec.get('telegram', {}) or {},
+}
+print(json.dumps(result))
+"
+}
+
+PARSED=$(parse_yaml)
+
+# Setup Telegram access.json if configured
+AUTO_CONNECT=$(echo "$PARSED" | python3 -c "import sys,json; d=json.load(sys.stdin); print(str(d.get('telegram',{}).get('auto_connect',True)).lower())")
+ALLOWED_USERS=$(echo "$PARSED" | python3 -c "import sys,json; d=json.load(sys.stdin); users=d.get('telegram',{}).get('allowed_users',[]); print(json.dumps(users))")
+
+if [[ "$AUTO_CONNECT" == "true" && "$ALLOWED_USERS" != "[]" ]]; then
+    ACCESS_DIR="${CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR:-$HOME/.scitex/agent-container/telegram}"
+    mkdir -p "$ACCESS_DIR"
+    python3 -c "
+import json
+users = json.loads('$ALLOWED_USERS')
+data = {'dmPolicy': 'allowlist', 'allowFrom': [str(u) for u in users]}
+with open('$ACCESS_DIR/access.json', 'w') as f:
+    json.dump(data, f, indent=2)
+    f.write('\n')
+print('Wrote access.json with', len(users), 'allowed users')
+"
+fi
+
+# Send startup commands with delays
+NUM_COMMANDS=$(echo "$PARSED" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d.get('startup_commands',[])))")
+
+if [[ "$NUM_COMMANDS" -gt 0 ]]; then
+    echo "Sending $NUM_COMMANDS startup command(s) to session: $SESSION"
+
+    echo "$PARSED" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+for cmd in d.get('startup_commands', []):
+    delay = cmd.get('delay', 0)
+    command = cmd.get('command', '')
+    if command:
+        print(f'{delay}\t{command}')
+" | while IFS=$'\t' read -r delay command; do
+        if [[ "$delay" -gt 0 ]]; then
+            echo "  Waiting ${delay}s before sending: $command"
+            sleep "$delay"
+        fi
+        screen -S "$SESSION" -X stuff "${command}\r"
+        echo "  Sent: $command"
+    done
+fi
+
+echo "claude-code-telegrammer-init complete."

{claude_code_telegrammer-0.4.0 → claude_code_telegrammer-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-code-telegrammer"
-version = "0.4.0"
+version = "0.4.2"
 description = "Custom Telegram MCP server + TUI auto-responder for running Claude Code as an autonomous Telegram agent"
 readme = "README.md"
 license = "AGPL-3.0"

claude_code_telegrammer-0.4.2/src/claude_code_telegrammer/__init__.py

@@ -0,0 +1,7 @@
+"""Claude Code Telegrammer -- custom Telegram MCP server + TUI auto-responder for Claude Code."""
+
+from __future__ import annotations
+
+from importlib.metadata import version as _get_version
+
+__version__ = _get_version(__name__)

{claude_code_telegrammer-0.4.0 → claude_code_telegrammer-0.4.2}/ts/lib/poller.ts

@@ -56,6 +56,39 @@ export async function startPolling(mcp: Server): Promise<void> {
     log("poller", `getMe failed: ${err}`);
   }
 
+  // Preflight: try a short long-poll to detect competing consumers.
+  // timeout=0 is instant and won't collide — we need timeout>0 to trigger
+  // the 409 if another consumer is already in a long-poll.
+  log("poller", "preflight: testing for competing consumers (3s)...");
+  try {
+    await tgApi("getUpdates", { offset: updateOffset, timeout: 3, limit: 1 });
+    log("poller", "preflight OK — no competing consumers detected");
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    if (errMsg.includes("409")) {
+      const fatalMsg =
+        "FATAL: 409 Conflict on startup — another process is already polling this bot token. " +
+        "Only one getUpdates consumer is allowed per token. " +
+        "Stop the other consumer first, or use a different bot token. " +
+        "Refusing to start.";
+      log("poller", fatalMsg);
+      // Notify the agent so it knows Telegram is NOT connected
+      mcp
+        .notification({
+          method: "notifications/claude/channel",
+          params: {
+            content: fatalMsg,
+            meta: { source: "telegram", type: "error" },
+          },
+        })
+        .catch(() => {});
+      polling = false;
+      return;
+    }
+    // Non-409 errors are OK to proceed (e.g., network hiccup)
+    log("poller", `preflight warning: ${errMsg} (proceeding anyway)`);
+  }
+
   while (polling) {
     try {
       const updates = await tgApi("getUpdates", {
@@ -85,8 +118,23 @@ export async function startPolling(mcp: Server): Promise<void> {
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
       if (errMsg.includes("409")) {
-        log("poller", "409 Conflict — another instance polling. Waiting 5s...");
-        await new Promise((r) => setTimeout(r, 5000));
+        const conflictMsg =
+          "409 Conflict — another process is polling this bot token. " +
+          "Only one getUpdates consumer is allowed per token. " +
+          "Telegram connection is DOWN. Stop the other consumer or use a different bot token.";
+        log("poller", conflictMsg);
+        mcp
+          .notification({
+            method: "notifications/claude/channel",
+            params: {
+              content: conflictMsg,
+              meta: { source: "telegram", type: "error" },
+            },
+          })
+          .catch(() => {});
+        // Stop polling — don't retry, the agent needs to fix this
+        polling = false;
+        return;
       } else {
         log("poller", `getUpdates error: ${errMsg}. Retrying in 3s...`);
         await new Promise((r) => setTimeout(r, 3000));

claude_code_telegrammer-0.4.0/src/claude_code_telegrammer/__init__.py

@@ -1,35 +0,0 @@
-"""Claude Code Telegrammer -- screen-based auto-responder for Claude Code TUI."""
-
-from __future__ import annotations
-
-import pathlib
-
-from importlib.metadata import version as _get_version
-
-__version__ = _get_version(__name__)
-
-# Package directory (works for both editable and regular installs)
-_PKG_DIR = pathlib.Path(__file__).resolve().parent
-
-
-def get_bin_path(script_name: str) -> str:
-    """Return absolute path to an installed bash script in bin/.
-
-    Searches two locations:
-    1. <package>/bin/<script>  (symlinked or copied during install)
-    2. <repo_root>/bin/<script>  (editable install fallback)
-    """
-    # Primary: inside package (symlink or copied)
-    path = _PKG_DIR / "bin" / script_name
-    if path.exists():
-        return str(path)
-
-    # Fallback: repo root (editable install, src layout)
-    repo_root = _PKG_DIR.parent.parent
-    path = repo_root / "bin" / script_name
-    if path.exists():
-        return str(path)
-
-    raise FileNotFoundError(
-        f"Script '{script_name}' not found in package bin/ or repo root bin/"
-    )