ask-human 0.3.0__py3-none-any.whl

ask_human/__init__.py

@@ -0,0 +1,7 @@
+"""Ask Human MCP server."""
+
+__version__ = "0.3.0"
+
+from .server import main
+
+__all__ = ["main"]

ask_human/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running Ask Human as a module."""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

ask_human/broker_state.py

@@ -0,0 +1,215 @@
+"""Persistent state helpers for the local Telegram broker."""
+
+import contextlib
+import os
+import platform
+import socket
+import sqlite3
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator, Optional
+
+from .telegram_models import TelegramConfig, resolve_telegram_target_key
+
+DEFAULT_BROKER_STATE_DIR_NAME = "ask-human"
+BROKER_STATE_DB_FILENAME = "telegram-broker.sqlite3"
+BROKER_STARTUP_LOCK_FILENAME = "broker-startup.lock"
+BROKER_TARGETS_DIRNAME = "targets"
+
+
+@dataclass(frozen=True)
+class TelegramBrokerIdentity:
+    """Stable identity and human-facing label for one broker installation."""
+
+    broker_id: str
+    broker_label: str
+
+
+@dataclass(frozen=True)
+class TelegramBrokerState:
+    """Persisted state that local clients can use for broker discovery."""
+
+    identity: TelegramBrokerIdentity
+    listen_url: Optional[str]
+
+
+@dataclass(frozen=True)
+class TelegramBrokerHealth:
+    """Health data returned by a running broker."""
+
+    broker_id: str
+    broker_label: str
+    listen_url: str
+    target_key: str
+
+
+def resolve_broker_state_dir(state_dir: Optional[str] = None) -> Path:
+    """Resolve the broker state directory from CLI input or platform defaults."""
+    if state_dir is not None and state_dir.strip():
+        expanded = state_dir.replace("{cwd}", os.getcwd())
+        expanded = os.path.expandvars(expanded)
+        expanded = os.path.expanduser(expanded)
+        return Path(expanded).resolve()
+
+    system_name = platform.system()
+    if system_name == "Windows":
+        root = os.environ.get("LOCALAPPDATA") or os.environ.get("APPDATA")
+        if root:
+            return (Path(root) / DEFAULT_BROKER_STATE_DIR_NAME).resolve()
+        return (Path.home() / "AppData" / "Local" / DEFAULT_BROKER_STATE_DIR_NAME).resolve()
+
+    if system_name == "Darwin":
+        return (
+            Path.home() / "Library" / "Application Support" / DEFAULT_BROKER_STATE_DIR_NAME
+        ).resolve()
+
+    root = os.environ.get("XDG_STATE_HOME")
+    if root:
+        return (Path(root) / DEFAULT_BROKER_STATE_DIR_NAME).resolve()
+    return (Path.home() / ".local" / "state" / DEFAULT_BROKER_STATE_DIR_NAME).resolve()
+
+
+def resolve_default_broker_label() -> str:
+    """Choose a human-friendly default label for the local broker."""
+    hostname = socket.gethostname().strip()
+    return hostname or "local-broker"
+
+
+def resolve_target_broker_state_dir(base_state_dir: Path, target: TelegramConfig) -> Path:
+    """Map one Telegram target to its dedicated local broker state directory."""
+    target_key = resolve_telegram_target_key(target)
+    return (base_state_dir / BROKER_TARGETS_DIRNAME / target_key).resolve()
+
+
+def _ensure_state_db(state_dir: Path) -> sqlite3.Connection:
+    """Open the broker state database and initialize its schema if needed."""
+    state_dir.mkdir(parents=True, exist_ok=True)
+    db_path = state_dir / BROKER_STATE_DB_FILENAME
+    connection = sqlite3.connect(db_path)
+    connection.execute("""
+        CREATE TABLE IF NOT EXISTS broker_state (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+        )
+        """)
+    connection.commit()
+    return connection
+
+
+def _get_state_value(connection: sqlite3.Connection, key: str) -> Optional[str]:
+    """Read a single broker state value by key."""
+    row = connection.execute(
+        "SELECT value FROM broker_state WHERE key = ?",
+        (key,),
+    ).fetchone()
+    if row is None:
+        return None
+    return str(row[0])
+
+
+def _set_state_value(connection: sqlite3.Connection, key: str, value: str) -> None:
+    """Persist a single broker state value."""
+    connection.execute(
+        """
+        INSERT INTO broker_state (key, value)
+        VALUES (?, ?)
+        ON CONFLICT(key) DO UPDATE SET value = excluded.value
+        """,
+        (key, value),
+    )
+    connection.commit()
+
+
+def load_or_create_broker_identity(
+    state_dir: Path,
+    broker_label: Optional[str] = None,
+) -> TelegramBrokerIdentity:
+    """Load a stable broker identity, creating and persisting one if absent."""
+    connection = _ensure_state_db(state_dir)
+    try:
+        broker_id = _get_state_value(connection, "broker_id")
+        stored_label = _get_state_value(connection, "broker_label")
+
+        if broker_id is None:
+            broker_id = uuid.uuid4().hex
+            _set_state_value(connection, "broker_id", broker_id)
+
+        resolved_label = broker_label.strip() if broker_label is not None else None
+        if not resolved_label:
+            resolved_label = stored_label or resolve_default_broker_label()
+
+        if stored_label != resolved_label:
+            _set_state_value(connection, "broker_label", resolved_label)
+
+        return TelegramBrokerIdentity(broker_id=broker_id, broker_label=resolved_label)
+    finally:
+        connection.close()
+
+
+def persist_broker_listen_url(state_dir: Path, listen_url: str) -> None:
+    """Store the broker's current listening URL for local discovery."""
+    connection = _ensure_state_db(state_dir)
+    try:
+        _set_state_value(connection, "listen_url", listen_url)
+    finally:
+        connection.close()
+
+
+def load_broker_state(state_dir: Path) -> Optional[TelegramBrokerState]:
+    """Read the persisted broker identity and listening URL, if available."""
+    connection = _ensure_state_db(state_dir)
+    try:
+        broker_id = _get_state_value(connection, "broker_id")
+        broker_label = _get_state_value(connection, "broker_label")
+        listen_url = _get_state_value(connection, "listen_url")
+    finally:
+        connection.close()
+
+    if broker_id is None or broker_label is None:
+        return None
+
+    identity = TelegramBrokerIdentity(broker_id=broker_id, broker_label=broker_label)
+    return TelegramBrokerState(identity=identity, listen_url=listen_url)
+
+
+@contextlib.contextmanager
+def acquire_startup_lock(
+    state_dir: Path,
+    *,
+    timeout_seconds: float = 15.0,
+    stale_after_seconds: float = 60.0,
+) -> Iterator[None]:
+    """Serialize local broker startup for one target with a simple lock file."""
+    state_dir.mkdir(parents=True, exist_ok=True)
+    lock_path = state_dir / BROKER_STARTUP_LOCK_FILENAME
+    deadline = time.monotonic() + timeout_seconds
+
+    while True:
+        try:
+            fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            break
+        except FileExistsError:
+            try:
+                age_seconds = time.time() - lock_path.stat().st_mtime
+            except FileNotFoundError:
+                continue
+
+            if age_seconds >= stale_after_seconds:
+                with contextlib.suppress(FileNotFoundError):
+                    lock_path.unlink()
+                continue
+
+            if time.monotonic() >= deadline:
+                raise TimeoutError("Timed out waiting for the broker startup lock.")
+
+            time.sleep(0.2)
+
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(str(os.getpid()))
+        yield
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            lock_path.unlink()

ask_human/dialogs.py

@@ -0,0 +1,311 @@
+"""Cross-platform GUI dialog handling for Ask Human prompts."""
+
+import asyncio
+import platform
+from contextlib import suppress
+from pathlib import Path
+from typing import Any, Optional, cast
+
+from .prompt_formatting import resolve_dialog_title
+
+DEFAULT_DIALOG_TIMEOUT_SECONDS = 120
+PACKAGE_ASSETS_DIR = Path(__file__).resolve().parent / "assets"
+
+
+class UserPromptCancelled(Exception):
+    """Raised when user cancels the prompt or interrupts the process."""
+
+    pass
+
+
+class UserPromptError(Exception):
+    """Generic error for user prompt operations."""
+
+    pass
+
+
+class GUIDialogHandler:
+    """Cross-platform GUI dialog handler for asking humans for input.
+
+    Provides native GUI dialogs on macOS (osascript), Linux (zenity), and Windows (tkinter).
+    Falls back to terminal input if GUI is unavailable.
+    """
+
+    def __init__(self, dialog_title: Optional[str] = None) -> None:
+        """Initialize the dialog handler with platform detection."""
+        self.platform = platform.system()
+        self.dialog_title = resolve_dialog_title(dialog_title)
+
+    async def get_user_input(
+        self,
+        question: str,
+        timeout: int = DEFAULT_DIALOG_TIMEOUT_SECONDS,
+        *,
+        cancel_event: Optional[asyncio.Event] = None,
+        run_in_thread: bool = False,
+    ) -> Optional[str]:
+        """Get user input via native GUI dialog with timeout."""
+        try:
+            if self.platform == "Darwin":
+                return await self._macos_dialog(question, timeout, cancel_event=cancel_event)
+            if self.platform == "Linux":
+                return await self._linux_dialog(question, timeout, cancel_event=cancel_event)
+            return await self._windows_dialog(
+                question,
+                timeout,
+                run_in_thread=run_in_thread,
+            )
+        except KeyboardInterrupt:
+            raise UserPromptCancelled("User interrupted the dialog with Ctrl+C")
+        except Exception as exc:
+            raise UserPromptError(
+                f"GUI dialog failed: {exc}. Ensure osascript (macOS), zenity (Linux), or "
+                "tkinter (Windows) is available."
+            ) from exc
+
+    async def _communicate_or_cancel(
+        self,
+        process: asyncio.subprocess.Process,
+        cancel_event: Optional[asyncio.Event],
+    ) -> tuple[bytes, bytes, bool]:
+        """Wait for a dialog subprocess or cancel it if another channel wins."""
+        communicate_task = asyncio.create_task(process.communicate())
+        cancel_task: Optional[asyncio.Task[bool]] = None
+        if cancel_event is not None:
+            cancel_task = asyncio.create_task(cancel_event.wait())
+
+        tasks: set[asyncio.Task[Any]] = {communicate_task}
+        if cancel_task is not None:
+            tasks.add(cancel_task)
+
+        done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+
+        for pending_task in pending:
+            pending_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await pending_task
+
+        if cancel_task is not None and cancel_task in done and cancel_event is not None:
+            if process.returncode is None:
+                process.terminate()
+                try:
+                    await asyncio.wait_for(process.wait(), timeout=2)
+                except asyncio.TimeoutError:
+                    process.kill()
+                    await process.wait()
+
+            communicate_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await communicate_task
+            return b"", b"", True
+
+        stdout, stderr = await communicate_task
+        return stdout, stderr, False
+
+    def _enable_windows_dpi_awareness(self) -> None:
+        """Enable crisp rendering for Windows dialogs on scaled displays."""
+        try:
+            import ctypes
+
+            windll = getattr(ctypes, "windll", None)
+            if windll is None:
+                return
+
+            try:
+                windll.shcore.SetProcessDpiAwareness(2)
+                return
+            except Exception:
+                pass
+
+            try:
+                windll.user32.SetProcessDPIAware()
+            except Exception:
+                pass
+        except Exception:
+            pass
+
+    def _configure_windows_tk_scaling(self, root: Any) -> None:
+        """Match Tk scaling to the current monitor DPI when available."""
+        try:
+            import ctypes
+
+            windll = getattr(ctypes, "windll", None)
+            dpi = 0
+            try:
+                if windll is not None:
+                    dpi = windll.user32.GetDpiForWindow(root.winfo_id())
+            except Exception:
+                try:
+                    dpi = root.winfo_fpixels("1i")
+                except Exception:
+                    dpi = 0
+
+            if dpi:
+                root.tk.call("tk", "scaling", float(dpi) / 72.0)
+        except Exception:
+            pass
+
+    async def _macos_dialog(
+        self, question: str, timeout: int, *, cancel_event: Optional[asyncio.Event] = None
+    ) -> Optional[str]:
+        """macOS dialog using osascript."""
+        icon_path = PACKAGE_ASSETS_DIR / "agent-asks.icns"
+
+        if icon_path.exists():
+            icon_clause = f'with icon file (POSIX file "{icon_path}")'
+        else:
+            icon_clause = "with icon caution"
+
+        script = f"""
+        display dialog "{self._escape_for_applescript(question)}" ¬
+        default answer "" ¬
+        with title "{self._escape_for_applescript(self.dialog_title)}" ¬
+        {icon_clause} ¬
+        giving up after {timeout}
+        """
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                "osascript",
+                "-e",
+                script,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+
+            stdout, _stderr, was_cancelled = await self._communicate_or_cancel(
+                process, cancel_event
+            )
+            if was_cancelled:
+                return None
+
+            if process.returncode == 0:
+                output = stdout.decode().strip()
+                if "text returned:" in output:
+                    text_part = output.split("text returned:")[1]
+                    if ", " in text_part:
+                        return text_part.split(", ")[0].strip()
+                    return text_part.strip()
+                if "gave up:true" in output:
+                    return None
+                if "button returned:" in output and "text returned:" not in output:
+                    return ""
+            return None
+        except Exception:
+            return None
+
+    async def _linux_dialog(
+        self, question: str, timeout: int, *, cancel_event: Optional[asyncio.Event] = None
+    ) -> Optional[str]:
+        """Linux dialog using zenity."""
+        icon_args = self._get_linux_icon_args()
+
+        cmd = [
+            "zenity",
+            "--entry",
+            f"--title={self.dialog_title}",
+            f"--text={question}",
+            f"--timeout={timeout}",
+        ] + icon_args
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+            )
+
+            stdout, _stderr, was_cancelled = await self._communicate_or_cancel(
+                process, cancel_event
+            )
+            if was_cancelled:
+                return None
+
+            if process.returncode == 0:
+                return stdout.decode().strip()
+            return None
+        except Exception:
+            return None
+
+    async def _windows_dialog(
+        self,
+        question: str,
+        timeout: int,
+        *,
+        run_in_thread: bool = False,
+    ) -> Optional[str]:
+        """Windows dialog using tkinter."""
+        if run_in_thread:
+            return await asyncio.to_thread(self._windows_dialog_sync, question, timeout)
+
+        return self._windows_dialog_sync(question, timeout)
+
+    def _windows_dialog_sync(self, question: str, timeout: int) -> Optional[str]:
+        """Blocking Windows dialog implementation for the current Tk/simpledialog UI."""
+        root = None
+        try:
+            import tkinter as tk
+            from tkinter import simpledialog
+
+            self._enable_windows_dpi_awareness()
+            root = tk.Tk()
+            self._configure_windows_tk_scaling(root)
+            root.withdraw()
+            self._set_windows_icon(root)
+
+            return self._ask_windows_string(
+                root,
+                simpledialog,
+                self.dialog_title,
+                question,
+                timeout,
+            )
+        except Exception:
+            return None
+        finally:
+            if root is not None:
+                try:
+                    root.destroy()
+                except Exception:
+                    pass
+
+    def _ask_windows_string(
+        self,
+        root: Any,
+        simpledialog: Any,
+        title: str,
+        question: str,
+        timeout: int,
+    ) -> Optional[str]:
+        """Ask for a Windows string response and close it when timeout expires."""
+        timeout_id = root.after(timeout * 1000, root.destroy)
+        try:
+            return cast(Optional[str], simpledialog.askstring(title, question, parent=root))
+        finally:
+            try:
+                root.after_cancel(timeout_id)
+            except Exception:
+                pass
+
+    def _escape_for_applescript(self, text: str) -> str:
+        """Escape text for AppleScript."""
+        return text.replace('"', '\\"').replace("\\", "\\\\")
+
+    def _get_linux_icon_args(self) -> list[str]:
+        """Get icon arguments for Linux zenity dialog."""
+        icon_path = PACKAGE_ASSETS_DIR / "agent-asks.png"
+        if icon_path.exists():
+            print(f"✅ Using Ask Human icon for Linux: {icon_path}")
+            return [f"--window-icon={icon_path}"]
+
+        return ["--question"]
+
+    def _set_windows_icon(self, root: Any) -> None:
+        """Set icon for Windows tkinter dialog."""
+        icon_path = PACKAGE_ASSETS_DIR / "agent-asks.ico"
+        if not icon_path.exists():
+            return
+
+        try:
+            print(f"✅ Using Ask Human icon for Windows: {icon_path}")
+            root.iconbitmap(icon_path)
+        except Exception:
+            pass