claude-code-telegrammer 0.4.1__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.1 → claude_code_telegrammer-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-telegrammer
-Version: 0.4.1
+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
@@ -140,34 +140,36 @@ Description-Content-Type: text/markdown
 
 ### Important: Bot Token Exclusivity
 
-This MCP server **must be the sole consumer** of its configured Telegram bot token. The Telegram Bot API enforces a single active `getUpdates` long-polling connection per token. If another component (e.g., `scitex-orochi`'s Telegram bridge) also polls the same token, **HTTP 409 Conflict** errors will occur, causing both consumers to miss messages.
+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.
 
-**If you see 409 errors:**
-- Disable the other polling component, **or**
-- Use a separate bot token for each component
+**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
@@ -220,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.1 → claude_code_telegrammer-0.4.2}/README.md

@@ -107,34 +107,36 @@
 
 ### Important: Bot Token Exclusivity
 
-This MCP server **must be the sole consumer** of its configured Telegram bot token. The Telegram Bot API enforces a single active `getUpdates` long-polling connection per token. If another component (e.g., `scitex-orochi`'s Telegram bridge) also polls the same token, **HTTP 409 Conflict** errors will occur, causing both consumers to miss messages.
+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.
 
-**If you see 409 errors:**
-- Disable the other polling component, **or**
-- Use a separate bot token for each component
+**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
@@ -187,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.1 → claude_code_telegrammer-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-code-telegrammer"
-version = "0.4.1"
+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.1 → 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,14 +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",
+        const conflictMsg =
           "409 Conflict — another process is polling this bot token. " +
-            "Only one getUpdates consumer is allowed per token. " +
-            "If scitex-orochi's Telegram bridge is active, disable it or use a separate bot token. " +
-            "Retrying in 5s...",
-        );
-        await new Promise((r) => setTimeout(r, 5000));
+          "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.1/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/"
-    )