aipager 0.2.0__py3-none-any.whl

aipager/OBSERVERS.md

@@ -0,0 +1,44 @@
+# Observer Bots
+
+Read-only Telegram bots that mirror notifications from the primary bot. They receive summaries, warnings, and errors — but can't control sessions.
+
+## Setup
+
+1. Create a bot via [@BotFather](https://t.me/BotFather)
+2. Start a chat with the bot and send `/start`
+3. Get your chat ID (send a message, then check `https://api.telegram.org/bot<TOKEN>/getUpdates`)
+4. Add to `.env`:
+
+```
+OBSERVER_BOTS=<bot_token>:<chat_id>
+```
+
+Multiple observers (comma-separated):
+
+```
+OBSERVER_BOTS=111:AAA_first:12345,222:BBB_second:67890
+```
+
+The format is `token:chat_id` — parsing uses the **last** colon as delimiter (bot tokens contain an internal colon).
+
+5. Restart the daemon
+
+## What observers receive
+
+| Event | Example |
+|-------|---------|
+| Idle summary | "Finished" + response text (+ .txt file for long responses) |
+| API error | "Anthropic servers overloaded" (no retry button) |
+| Context warning | "Context at 82% — auto-compact soon" |
+| Compacting | "Compacting" |
+| Compact done | "Compacted: 82% → 4%" |
+
+## What observers DON'T receive
+
+- Busy animations / spinner
+- Tool call updates
+- Permission prompts (Allow/Deny)
+- AskUserQuestion dialogs
+- Any inline keyboards or buttons
+
+Observers are completely stateless — fire-and-forget sends. A failing observer never affects the primary bot.

aipager/__init__.py

@@ -0,0 +1,8 @@
+"""aipager — Telegram remote control for Claude Code sessions."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("aipager")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

aipager/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m aipager` — delegates to the CLI."""
+
+from aipager.cli import main
+
+if __name__ == "__main__":
+    main()

aipager/_dtach_redraw.py

@@ -0,0 +1,95 @@
+"""Force a TUI redraw in a dtach session by bouncing the PTY window size.
+
+dtach has no screen buffer — reattaching shows a blank screen. TUI apps
+(Ink/React) only redraw on genuine dimension changes due to three
+independent same-size guards (Linux kernel, Node.js, Ink).
+
+`redraw(name)` changes the PTY size to (rows-1, cols), waits 50ms, then
+restores (rows, cols) — forcing two genuine SIGWINCH signals and a full
+redraw.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import struct
+import subprocess
+import sys
+import termios
+import time
+
+
+def find_pty(session_name: str) -> str | None:
+    """Find the PTY slave device for a claude-dtach session's child process."""
+    try:
+        result = subprocess.run(
+            ["pgrep", "-f", f"dtach -n.*/claude-dtach-{session_name}\\.sock"],
+            capture_output=True, text=True, timeout=5,
+        )
+        dtach_pid = result.stdout.strip().split("\n")[0]
+        if not dtach_pid:
+            return None
+    except Exception:
+        return None
+
+    try:
+        result = subprocess.run(
+            ["pgrep", "-P", dtach_pid],
+            capture_output=True, text=True, timeout=5,
+        )
+        child_pid = result.stdout.strip().split("\n")[0]
+        if not child_pid:
+            return None
+    except Exception:
+        return None
+
+    try:
+        pty = os.readlink(f"/proc/{child_pid}/fd/1")
+        if pty.startswith("/dev/pts/"):
+            return pty
+    except Exception:
+        pass
+    return None
+
+
+def bounce_size(pty_path: str) -> bool:
+    """Bounce PTY dimensions: (rows-1) then restore. Triggers two SIGWINCHs."""
+    try:
+        fd = os.open(pty_path, os.O_RDWR | os.O_NOCTTY)
+    except OSError:
+        return False
+    try:
+        buf = fcntl.ioctl(fd, termios.TIOCGWINSZ, b"\x00" * 8)
+        rows, cols, xpix, ypix = struct.unpack("HHHH", buf)
+        if rows <= 1:
+            return False
+        fcntl.ioctl(fd, termios.TIOCSWINSZ,
+                    struct.pack("HHHH", rows - 1, cols, xpix, ypix))
+        time.sleep(0.05)
+        fcntl.ioctl(fd, termios.TIOCSWINSZ,
+                    struct.pack("HHHH", rows, cols, xpix, ypix))
+        return True
+    except Exception:
+        return False
+    finally:
+        os.close(fd)
+
+
+def redraw(session_name: str) -> bool:
+    """Bounce PTY size for the given session — returns True on success."""
+    pty = find_pty(session_name)
+    if not pty:
+        return False
+    return bounce_size(pty)
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print(f"Usage: {sys.argv[0]} <session-name>", file=sys.stderr)
+        return 1
+    return 0 if redraw(sys.argv[1]) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aipager/cli.py

@@ -0,0 +1,114 @@
+"""Top-level CLI for aipager.
+
+Subcommands:
+  start    run the daemon in the foreground
+  config   interactive setup wizard (configures Telegram + Claude Code)
+  version  print version
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import signal
+import sys
+
+from aipager import __version__
+
+log = logging.getLogger("aipager")
+
+
+async def _run_daemon() -> None:
+    """Boot the daemon and run until SIGINT/SIGTERM."""
+    from aipager.config import BOT_TOKEN, OBSERVER_BOTS
+    from aipager.hook_receiver import HookReceiver
+    from aipager.observer import ObserverBroadcaster
+    from aipager.session_monitor import SessionMonitor
+    from aipager.state import SessionRegistry
+    from aipager.telegram_bot import TelegramBot
+
+    if not BOT_TOKEN:
+        log.error("CLAUDE_TG_BOT_TOKEN not set — run `aipager config` first")
+        sys.exit(1)
+
+    registry = SessionRegistry()
+    registry.load()
+    bot = TelegramBot(registry)
+    hook_receiver = HookReceiver(registry, bot.notify)
+    session_monitor = SessionMonitor(registry, bot.notify)
+
+    await bot.start()
+    observers = None
+    if OBSERVER_BOTS:
+        observers = ObserverBroadcaster(OBSERVER_BOTS)
+        await observers.start()
+        bot.observers = observers
+    await hook_receiver.start()
+    await bot.recover_sessions()
+    session_monitor.on_sessions_changed = bot._update_bot_commands
+    await session_monitor.start()
+
+    log.info("AIPager running — all components started")
+
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, stop.set)
+
+    await stop.wait()
+
+    log.info("Shutting down...")
+    registry.save()
+    session_monitor.stop()
+    hook_receiver.stop()
+    if observers:
+        await observers.stop()
+    await bot.stop()
+    log.info("Goodbye")
+
+
+def _cmd_start(args: argparse.Namespace) -> int:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+        datefmt="%H:%M:%S",
+    )
+    asyncio.run(_run_daemon())
+    return 0
+
+
+def _cmd_config(args: argparse.Namespace) -> int:
+    from aipager.setup_wizard import run
+    return run()
+
+
+def _cmd_version(args: argparse.Namespace) -> int:
+    print(__version__)
+    return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="aipager",
+        description="Telegram remote-control daemon for Claude Code sessions",
+    )
+    parser.add_argument("--version", action="version",
+                        version=f"aipager {__version__}")
+    sub = parser.add_subparsers(dest="cmd")
+    sub.add_parser("start", help="run the daemon in the foreground"
+                   ).set_defaults(fn=_cmd_start)
+    sub.add_parser("config", help="interactive setup wizard"
+                   ).set_defaults(fn=_cmd_config)
+    sub.add_parser("version", help="print version"
+                   ).set_defaults(fn=_cmd_version)
+
+    args = parser.parse_args()
+    if not args.cmd:
+        parser.print_help()
+        sys.exit(0)
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()

aipager/config.py

@@ -0,0 +1,131 @@
+"""Configuration for aipager — loads env from XDG path or project root."""
+
+import os
+from pathlib import Path
+
+_XDG_CONFIG = Path.home() / ".config" / "aipager" / "config.env"
+_PROJECT_DOTENV = Path(__file__).parent.parent / ".env"
+
+
+def _load_env_file() -> None:
+    """Load environment variables.
+
+    Source priority (first existing file wins):
+      1. ~/.config/aipager/config.env (XDG, written by `aipager config`)
+      2. <project-root>/.env (legacy / development checkouts)
+    """
+    for candidate in (_XDG_CONFIG, _PROJECT_DOTENV):
+        if candidate.exists():
+            for line in candidate.read_text().splitlines():
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, _, value = line.partition("=")
+                key = key.strip()
+                value = value.strip().strip("\"'")
+                if key and key not in os.environ:
+                    os.environ[key] = value
+            return
+
+
+_load_env_file()
+
+BOT_TOKEN: str = os.environ.get("CLAUDE_TG_BOT_TOKEN", "")
+CHAT_ID: str = os.environ.get("CLAUDE_TG_CHAT_ID", "")
+
+
+def _parse_observer_bots(raw: str) -> list[tuple[str, str]]:
+    """Parse 'token1:chatid1,token2:chatid2' into [(token, chatid), ...].
+
+    Uses rsplit(":", 1) to split at the LAST colon, since bot tokens
+    contain an internal colon (format NNNNN:XXXXXX).
+    """
+    if not raw.strip():
+        return []
+    result = []
+    for entry in raw.split(","):
+        entry = entry.strip()
+        if ":" not in entry:
+            continue
+        parts = entry.rsplit(":", 1)
+        if len(parts) != 2:
+            continue
+        token, chat_id = parts[0].strip(), parts[1].strip()
+        if token and chat_id:
+            result.append((token, chat_id))
+    return result
+
+
+OBSERVER_BOTS: list[tuple[str, str]] = _parse_observer_bots(
+    os.environ.get("OBSERVER_BOTS", "")
+)
+
+# Unix datagram socket for hook → daemon communication
+SOCKET_PATH: str = "/tmp/aipager.sock"
+
+# Pane monitor interval (seconds)
+PANE_POLL_INTERVAL: float = 2.0
+
+# Use transcript JSONL for rich markdown→HTML summaries in Telegram notifications.
+# When False, uses pane-scraped plain text in expandable blockquotes (old behavior).
+RICH_SUMMARIES: bool = os.environ.get("CLAUDE_RICH_SUMMARIES", "1") not in ("0", "false", "no")
+
+# Session state persistence (survives daemon restarts)
+SESSION_STATE_FILE = Path.home() / ".claude" / "aipager-sessions.json"
+
+# Minimum seconds between busy-message edits (rate-limit for Telegram API)
+BUSY_EDIT_INTERVAL: float = 3.0
+
+# Stale busy session threshold (seconds) — alert if BUSY with no hooks for this long
+STALE_BUSY_TIMEOUT: float = float(os.environ.get("STALE_BUSY_TIMEOUT", "1200"))
+
+# Spinner verbs for animated busy messages (curated from Claude Code's terminal spinner)
+SPINNER_VERBS: list[str] = [
+    "Thinking", "Reasoning", "Pondering", "Considering", "Analyzing",
+    "Processing", "Synthesizing", "Deliberating", "Evaluating", "Mulling",
+    "Contemplating", "Inferring", "Cogitating", "Puzzling", "Calculating",
+    "Deciphering", "Formulating", "Examining", "Investigating", "Brewing",
+    "Cooking", "Crafting", "Forging", "Conjuring", "Noodling",
+    "Percolating", "Simmering", "Ruminating", "Musing", "Tinkering",
+]
+
+# Quick template buttons for Telegram persistent keyboard
+TEMPLATES_BUTTON = "Templates"
+BACK_BUTTON = "\u00ab Back"
+QUICK_TEMPLATES: list[tuple[str, str]] = [
+    ("Continue", "Continue"),
+    ("Run tests", "Run the tests"),
+    ("Commit", "Commit the changes with a descriptive message"),
+    ("LGTM ship it", "LGTM, ship it"),
+    ("Show diff", "Show me the git diff of all changes"),
+]
+
+# Claude Code slash commands — instant commands (no BUSY transition)
+# Only commands that CHANGE BEHAVIOR belong here. Commands that just
+# display info in the terminal (cost, context, stats, doctor) are useless
+# remotely since the user can't see the terminal output in Telegram.
+COMMANDS_BUTTON = "Commands"
+QUICK_COMMANDS: list[tuple[str, str]] = [
+    ("Compact", "/compact"),
+    ("Clear", "/clear"),
+    ("Plan mode", "/plan"),
+]
+
+# Model submenu — accessible from Commands → Model
+MODELS_BUTTON = "Model \u203a"
+MODEL_CHOICES: list[tuple[str, str]] = [
+    ("Sonnet", "/model sonnet"),
+    ("Opus", "/model opus"),
+    ("Haiku", "/model haiku"),
+    ("OpusPlan", "/model opusplan"),
+]
+
+# Parent level for each keyboard level (for context-aware Back button)
+KEYBOARD_PARENTS: dict[str, str] = {
+    "templates": "main",
+    "commands": "main",
+    "models": "commands",
+}
+
+# Directory for files downloaded from Telegram (photos, documents)
+FILE_DOWNLOAD_DIR = Path("/tmp/aipager-files")

aipager/dtach_inject.py

@@ -0,0 +1,211 @@
+"""Async dtach wrappers — inject keystrokes and check session liveness.
+
+Uses `dtach -p <socket>` to send raw bytes to the session's PTY via stdin.
+
+Socket naming: session "claude-dev" → /tmp/claude-dtach-dev.sock
+"""
+
+import asyncio
+import logging
+import os
+import re
+import shutil
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+SOCK_PREFIX = "/tmp/claude-dtach-"
+
+# Logical key names → ANSI escape sequences
+KEYS = {
+    "Enter": "\r",
+    "Down": "\x1b[B",
+    "Up": "\x1b[A",
+    "Right": "\x1b[C",
+    "Left": "\x1b[D",
+    "Tab": "\t",
+    "Escape": "\x1b",
+}
+
+
+async def _run(args: list[str], stdin: bytes = b"",
+               timeout: float = 5) -> tuple[bool, str]:
+    """Run subprocess, optionally piping stdin, return (success, stdout)."""
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *args,
+            stdin=asyncio.subprocess.PIPE if stdin else asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await asyncio.wait_for(
+            proc.communicate(stdin or None), timeout=timeout,
+        )
+        if proc.returncode == 0:
+            return True, stdout.decode()
+        log.error("dtach cmd failed: %s — %s", args, stderr.decode().strip())
+        return False, ""
+    except asyncio.TimeoutError:
+        log.error("dtach cmd timed out: %s", args)
+        return False, ""
+    except FileNotFoundError:
+        log.error("dtach not found")
+        return False, ""
+
+
+def _sock_path(session: str) -> str:
+    """Convert session name 'claude-dev' to socket path '/tmp/claude-dtach-dev.sock'."""
+    name = session.removeprefix("claude-")
+    return f"{SOCK_PREFIX}{name}.sock"
+
+
+async def send_keys(session: str, keys: str) -> bool:
+    """Send a key sequence to the dtach session.
+
+    `keys` can be a logical name ("Enter", "Down") or raw text.
+    """
+    seq = KEYS.get(keys, keys)
+    sock = _sock_path(session)
+    ok, _ = await _run(["dtach", "-p", sock], stdin=seq.encode())
+    if ok:
+        log.info("Sent keys %r → %s", keys, session)
+    return ok
+
+
+async def send_text_and_enter(session: str, text: str) -> bool:
+    """Send literal text followed by Enter.
+
+    Text and Enter must be separate dtach -p calls — Claude Code's TUI
+    treats a single chunk (text + CR) as all-text input. A separate CR
+    write is needed to trigger the submit keypress event.
+    """
+    sock = _sock_path(session)
+    ok, _ = await _run(["dtach", "-p", sock], stdin=text.encode())
+    if not ok:
+        return False
+    # Claude Code's Ink TUI needs time to process text input before
+    # Enter is recognized as "submit". Too short → \r is swallowed.
+    # Scale with text length: longer text = more rendering time needed.
+    delay = max(0.15, min(0.5, len(text) * 0.003))
+    await asyncio.sleep(delay)
+    ok, _ = await _run(["dtach", "-p", sock], stdin=b"\r")
+    if ok:
+        log.info("Sent text %r + Enter → %s", text[:50], session)
+    return ok
+
+
+async def kill_session(session: str) -> bool:
+    """Kill a dtach session by finding its host PID and terminating it."""
+    sock = _sock_path(session)
+    sock_path = Path(sock)
+    if not sock_path.is_socket():
+        return False
+
+    # Find the dtach host process (dtach -n <sock> ...)
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "fuser", sock,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=5)
+        pids = stdout.decode().split()
+        for pid_str in pids:
+            pid_str = pid_str.strip()
+            if pid_str.isdigit():
+                import os
+                import signal
+                os.kill(int(pid_str), signal.SIGTERM)
+                log.info("Killed dtach PID %s for %s", pid_str, session)
+    except Exception:
+        log.warning("Failed to find/kill dtach PID for %s", session, exc_info=True)
+
+    # Remove socket as fallback (dtach should clean up, but ensure it)
+    try:
+        sock_path.unlink(missing_ok=True)
+    except OSError:
+        pass
+    return True
+
+
+async def is_alive(session: str) -> bool:
+    """Check if a dtach session socket exists and is connectable."""
+    sock = _sock_path(session)
+    return Path(sock).is_socket()
+
+
+_VALID_NAME = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$")
+_RESERVED = {"status", "stop", "kill", "new", "help", "start", "settings"}
+_PROJECT_DIR = os.environ.get("AIPAGER_WORK_DIR", os.getcwd())
+_CLAUDE_BIN = shutil.which("claude") or "claude"
+
+
+async def launch_session(name: str, skip_perms: bool = True) -> tuple[bool, str]:
+    """Launch a new Claude Code session inside dtach.
+
+    Returns (success, error_message). The session_monitor will auto-discover
+    the new session within 2 seconds.
+    """
+    if not name or not _VALID_NAME.match(name):
+        return False, "Invalid name (use letters, numbers, hyphens)"
+    if name.lower() in _RESERVED:
+        return False, f"'{name}' is a reserved command name"
+    if len(name) > 30:
+        return False, "Name too long (max 30 chars)"
+
+    sock = f"{SOCK_PREFIX}{name}.sock"
+    if Path(sock).is_socket():
+        return False, f"Session '{name}' already exists"
+
+    # Build the bash -c command — wraps claude with env vars and prompt
+    perms = "--dangerously-skip-permissions" if skip_perms else ""
+    sys_prompt = (f'Your session name is "{name}". '
+                  f'When users address you by this name, respond naturally '
+                  f'-- it is your name in this session.')
+    # `unset CLAUDECODE`: Claude Code sets this env var when running, and
+    # the binary refuses to launch a second time if it sees it ("already
+    # inside a Claude Code session"). Strip it so /new sessions can launch
+    # cleanly from inside a parent Claude.
+    bash_cmd = (
+        f"unset CLAUDECODE; "
+        f"export CLAUDE_DTACH_SESSION=claude-{name}; "
+        f"{_CLAUDE_BIN} {perms} "
+        f"--append-system-prompt '{sys_prompt}'"
+    )
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "dtach", "-n", sock, "-Ez", "bash", "-c", bash_cmd,
+            cwd=_PROJECT_DIR,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        _, stderr = await asyncio.wait_for(proc.communicate(), timeout=5)
+        if proc.returncode != 0:
+            return False, f"dtach failed: {stderr.decode().strip()}"
+    except FileNotFoundError:
+        return False, "dtach not installed"
+    except asyncio.TimeoutError:
+        return False, "dtach launch timed out"
+
+    # Wait for socket to appear (dtach creates it asynchronously)
+    for _ in range(10):
+        await asyncio.sleep(0.3)
+        if Path(sock).is_socket():
+            log.info("Launched session claude-%s (socket: %s)", name, sock)
+            return True, ""
+    return False, "Socket never appeared after launch"
+
+
+async def list_sessions() -> list[str]:
+    """Return names of all active claude-dtach sessions.
+
+    Scans /tmp for claude-dtach-*.sock files that are Unix sockets.
+    """
+    results = []
+    for sock_file in Path("/tmp").glob("claude-dtach-*.sock"):
+        if not sock_file.is_socket():
+            continue
+        name = "claude-" + sock_file.stem.removeprefix("claude-dtach-")
+        results.append(name)
+    return results