agent-tether 0.2.0__py3-none-any.whl

agent_tether/__init__.py

@@ -0,0 +1,64 @@
+"""agent-tether: Tether your AI agents to human oversight through chat platforms."""
+
+from agent_tether.formatting import format_tool_input, humanize_key, humanize_enum_value
+from agent_tether.models import ApprovalRequest, CommandDef, Handlers
+from agent_tether.router import BridgeRouter
+from agent_tether.subscriber import EventSubscriber
+
+__all__ = [
+    # Core bridge components
+    "ApprovalRequest",
+    "CommandDef",
+    "EventSubscriber",
+    "Handlers",
+    "BridgeRouter",
+    # Platform bridges (lazy loaded)
+    "TelegramBridge",
+    "SlackBridge",
+    "DiscordBridge",
+    # Formatting utilities
+    "format_tool_input",
+    "humanize_key",
+    "humanize_enum_value",
+    # Runner module (lazy loaded)
+    "runner",
+]
+
+
+def __getattr__(name: str):
+    """Lazy imports for platform bridges and session module — avoids requiring optional deps at import time."""
+    if name == "TelegramBridge":
+        try:
+            from agent_tether.platforms.telegram.bridge import TelegramBridge
+
+            return TelegramBridge
+        except ImportError:
+            raise ImportError(
+                "TelegramBridge requires python-telegram-bot. "
+                "Install with: pip install agent-tether[telegram]"
+            ) from None
+    if name == "SlackBridge":
+        try:
+            from agent_tether.platforms.slack.bridge import SlackBridge
+
+            return SlackBridge
+        except ImportError:
+            raise ImportError(
+                "SlackBridge requires slack-sdk and slack-bolt. "
+                "Install with: pip install agent-tether[slack]"
+            ) from None
+    if name == "DiscordBridge":
+        try:
+            from agent_tether.platforms.discord.bridge import DiscordBridge
+
+            return DiscordBridge
+        except ImportError:
+            raise ImportError(
+                "DiscordBridge requires discord.py. "
+                "Install with: pip install agent-tether[discord]"
+            ) from None
+    if name == "runner":
+        from agent_tether import runner as runner_module
+
+        return runner_module
+    raise AttributeError(f"module 'agent_tether' has no attribute {name!r}")

agent_tether/approval.py

@@ -0,0 +1,142 @@
+"""Auto-approve engine with timed permissions.
+
+Manages per-thread, per-tool, and per-directory auto-approve timers.
+When a human grants a timed permission (e.g., "Allow All for 30m"),
+subsequent approval requests are resolved automatically until the
+timer expires.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+_DEFAULT_DURATION_S = 30 * 60  # 30 minutes
+_DEFAULT_NEVER_AUTO_APPROVE = frozenset({"task", "enterplanmode", "exitplanmode"})
+
+
+class AutoApproveEngine:
+    """Timed auto-approve engine.
+
+    Args:
+        duration_s: How long timers last in seconds (default 30 minutes).
+        never_auto_approve: Tool name prefixes that are never auto-approved.
+    """
+
+    def __init__(
+        self,
+        *,
+        duration_s: int = _DEFAULT_DURATION_S,
+        never_auto_approve: set[str] | frozenset[str] | None = None,
+    ) -> None:
+        self._duration_s = duration_s
+        self._never: frozenset[str] = (
+            frozenset(never_auto_approve)
+            if never_auto_approve is not None
+            else _DEFAULT_NEVER_AUTO_APPROVE
+        )
+        # Per-thread allow-all: thread_id → expiry timestamp
+        self._allow_all_until: dict[str, float] = {}
+        # Per-thread per-tool: thread_id → {tool_name → expiry}
+        self._allow_tool_until: dict[str, dict[str, float]] = {}
+        # Per-directory: normalised_dir → expiry timestamp
+        self._allow_dir_until: dict[str, float] = {}
+        # Thread → directory association
+        self._thread_directory: dict[str, str] = {}
+
+    # ------------------------------------------------------------------
+    # Configuration
+    # ------------------------------------------------------------------
+
+    def associate_directory(self, thread_id: str, directory: str) -> None:
+        """Associate a thread with a directory path (for directory-scoped timers)."""
+        self._thread_directory[thread_id] = os.path.normpath(directory)
+
+    # ------------------------------------------------------------------
+    # Check
+    # ------------------------------------------------------------------
+
+    def check(self, thread_id: str, tool_name: str) -> str | None:
+        """Check if a tool request should be auto-approved.
+
+        Returns a reason string if auto-approved, or None if human review
+        is required.
+        """
+        norm = (tool_name or "").strip().lower()
+        if any(norm.startswith(prefix) for prefix in self._never):
+            return None
+
+        now = time.time()
+
+        # Per-thread allow-all
+        if now < self._allow_all_until.get(thread_id, 0):
+            return "Allow All"
+
+        # Per-thread per-tool
+        tool_expiry = self._allow_tool_until.get(thread_id, {}).get(tool_name, 0)
+        if now < tool_expiry:
+            return f"Allow {tool_name}"
+
+        # Per-directory
+        return self._check_directory(thread_id, now)
+
+    def _check_directory(self, thread_id: str, now: float) -> str | None:
+        """Check directory-scoped auto-approve timers."""
+        if not self._allow_dir_until:
+            return None
+        thread_dir = self._thread_directory.get(thread_id)
+        if not thread_dir:
+            return None
+        for allowed_dir, expiry in self._allow_dir_until.items():
+            if now >= expiry:
+                continue
+            if thread_dir == allowed_dir or thread_dir.startswith(allowed_dir + os.sep):
+                short = os.path.basename(allowed_dir) or allowed_dir
+                return f"Allow dir {short}"
+        return None
+
+    # ------------------------------------------------------------------
+    # Set timers
+    # ------------------------------------------------------------------
+
+    def set_allow_all(self, thread_id: str) -> None:
+        """Enable auto-approve for all tools on this thread."""
+        self._allow_all_until[thread_id] = time.time() + self._duration_s
+
+    def set_allow_tool(self, thread_id: str, tool_name: str) -> None:
+        """Enable auto-approve for a specific tool on this thread."""
+        self._allow_tool_until.setdefault(thread_id, {})[tool_name] = (
+            time.time() + self._duration_s
+        )
+
+    def set_allow_directory(self, directory: str) -> None:
+        """Enable auto-approve for all threads in a directory."""
+        norm = os.path.normpath(directory)
+        self._allow_dir_until[norm] = time.time() + self._duration_s
+
+    # ------------------------------------------------------------------
+    # Cleanup
+    # ------------------------------------------------------------------
+
+    # ------------------------------------------------------------------
+    # Accessors
+    # ------------------------------------------------------------------
+
+    def get_directory(self, thread_id: str) -> str | None:
+        """Get the directory associated with a thread, or None."""
+        return self._thread_directory.get(thread_id)
+
+    def is_never_approved(self, tool_name: str) -> bool:
+        """Check if a tool name matches the never-auto-approve set."""
+        norm = (tool_name or "").strip().lower()
+        return any(norm.startswith(prefix) for prefix in self._never)
+
+    # ------------------------------------------------------------------
+    # Cleanup
+    # ------------------------------------------------------------------
+
+    def remove_thread(self, thread_id: str) -> None:
+        """Clean up all state for a thread."""
+        self._allow_all_until.pop(thread_id, None)
+        self._allow_tool_until.pop(thread_id, None)
+        self._thread_directory.pop(thread_id, None)

agent_tether/batching.py

@@ -0,0 +1,62 @@
+"""Notification batcher for auto-approve events.
+
+Collects auto-approve notifications per thread and flushes them
+as a single batched message after a short delay, so rapid-fire
+approvals don't flood the chat.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+
+
+class NotificationBatcher:
+    """Batches notifications per thread and flushes after a delay.
+
+    Args:
+        flush_callback: Async function called with ``(thread_id, items)``
+            when the batch is ready. ``items`` is a list of
+            ``(tool_name, reason)`` tuples.
+        flush_delay: Seconds to wait before flushing (default 1.5).
+    """
+
+    def __init__(
+        self,
+        flush_callback: Callable[[str, list[tuple[str, str]]], Awaitable[None]],
+        *,
+        flush_delay: float = 1.5,
+    ) -> None:
+        self._flush_callback = flush_callback
+        self._flush_delay = flush_delay
+        self._buffer: dict[str, list[tuple[str, str]]] = {}
+        self._tasks: dict[str, asyncio.Task] = {}
+
+    def add(self, thread_id: str, tool_name: str, reason: str) -> None:
+        """Buffer a notification. Resets the flush timer."""
+        self._buffer.setdefault(thread_id, []).append((tool_name, reason))
+
+        # Cancel existing timer and start a new one
+        existing = self._tasks.pop(thread_id, None)
+        if existing:
+            existing.cancel()
+
+        self._tasks[thread_id] = asyncio.create_task(self._flush_after_delay(thread_id))
+
+    async def _flush_after_delay(self, thread_id: str) -> None:
+        """Wait then flush buffered notifications."""
+        try:
+            await asyncio.sleep(self._flush_delay)
+        except asyncio.CancelledError:
+            return
+        self._tasks.pop(thread_id, None)
+        items = self._buffer.pop(thread_id, [])
+        if items:
+            await self._flush_callback(thread_id, items)
+
+    def remove_thread(self, thread_id: str) -> None:
+        """Cancel pending flush and discard buffer for a thread."""
+        task = self._tasks.pop(thread_id, None)
+        if task:
+            task.cancel()
+        self._buffer.pop(thread_id, None)

agent_tether/debounce.py

@@ -0,0 +1,40 @@
+"""Error notification debouncing.
+
+Prevents flooding chat threads with repeated error messages
+by enforcing a minimum interval between error notifications
+per thread.
+"""
+
+from __future__ import annotations
+
+import time
+
+
+class ErrorDebouncer:
+    """Debounces error notifications per thread.
+
+    Args:
+        debounce_seconds: Minimum seconds between error notifications
+            for the same thread. 0 means no debouncing.
+    """
+
+    def __init__(self, *, debounce_seconds: int = 0) -> None:
+        self._debounce_s = debounce_seconds
+        self._last_sent: dict[str, float] = {}
+
+    def should_send(self, thread_id: str) -> bool:
+        """Return True if an error notification should be sent now."""
+        if self._debounce_s <= 0:
+            return True
+
+        now = time.time()
+        last = self._last_sent.get(thread_id)
+        if last is not None and (now - last) < self._debounce_s:
+            return False
+
+        self._last_sent[thread_id] = now
+        return True
+
+    def remove_thread(self, thread_id: str) -> None:
+        """Clean up state for a thread."""
+        self._last_sent.pop(thread_id, None)

agent_tether/formatting.py

@@ -0,0 +1,176 @@
+"""Formatting utilities for tool input and human-readable output.
+
+Provides functions to convert JSON tool input dicts into readable
+text suitable for chat platforms, with smart truncation and key
+humanization.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+# ---------------------------------------------------------------------------
+# Key / value humanization
+# ---------------------------------------------------------------------------
+
+_ACRONYMS = frozenset(
+    {
+        "id",
+        "url",
+        "api",
+        "sdk",
+        "http",
+        "https",
+        "cli",
+        "ui",
+        "sse",
+        "mcp",
+        "json",
+    }
+)
+
+
+def humanize_key(key: str) -> str:
+    """Convert a snake_case key into a human-friendly label.
+
+    Examples:
+        >>> humanize_key("output_mode")
+        'Output mode'
+        >>> humanize_key("session_id")
+        'Session ID'
+    """
+    if not key or "_" not in key:
+        return key
+
+    parts = [p for p in key.strip().split("_") if p]
+    if not parts:
+        return key
+
+    out: list[str] = []
+    for i, p in enumerate(parts):
+        low = p.lower()
+        if low in _ACRONYMS:
+            out.append(low.upper())
+        elif i == 0:
+            out.append(low[:1].upper() + low[1:])
+        else:
+            out.append(low)
+    return " ".join(out)
+
+
+def humanize_enum_value(value: object) -> str:
+    """Humanize enum-ish snake_case values like ``files_with_matches``.
+
+    Only touches values that look like enums; paths and commands are
+    left alone.
+    """
+    s = str(value)
+    if "_" not in s:
+        return s
+    if not re.fullmatch(r"[a-z0-9_]+", s):
+        return s
+    parts = [p for p in s.split("_") if p]
+    if not parts:
+        return s
+    out: list[str] = []
+    for i, p in enumerate(parts):
+        low = p.lower()
+        if low == "id":
+            out.append("ID")
+        elif i == 0:
+            out.append(low[:1].upper() + low[1:])
+        else:
+            out.append(low)
+    return " ".join(out)
+
+
+# ---------------------------------------------------------------------------
+# Tool input formatting
+# ---------------------------------------------------------------------------
+
+_PATH_KEYS = frozenset({"file_path", "path", "notebook_path"})
+_CODE_BLOCK_KEYS = frozenset(
+    {
+        "command",
+        "old_string",
+        "new_string",
+        "content",
+        "new_source",
+    }
+)
+
+
+def format_tool_input(
+    raw: str,
+    *,
+    truncate: int = 400,
+    truncate_code: int = 1400,
+    max_chars: int = 2000,
+) -> str:
+    """Format a tool_input JSON string as readable markdown for chat platforms.
+
+    Args:
+        raw: JSON string (or plain text) of the tool input.
+        truncate: Max chars per value (non-code fields).
+        truncate_code: Max chars for code-block fields.
+        max_chars: Total output character budget.
+
+    Returns:
+        Formatted markdown string.
+    """
+    try:
+        obj = json.loads(raw) if isinstance(raw, str) else raw
+    except Exception:
+        return str(raw)
+
+    if not isinstance(obj, dict):
+        return str(raw)
+
+    lines: list[str] = []
+    total = 0
+    for key, value in obj.items():
+        key_s = str(key)
+        label = humanize_key(key_s)
+
+        if isinstance(value, (dict, list)):
+            v = json.dumps(value, ensure_ascii=True)
+        else:
+            v = humanize_enum_value(value)
+
+        limit = truncate_code if key_s in _CODE_BLOCK_KEYS else truncate
+        if len(v) > limit:
+            v = v[:limit] + "..."
+
+        # Prevent closing a code block early.
+        v = v.replace("```", "``\\`")
+
+        if key_s in _PATH_KEYS:
+            part = f"{label}: `{v}`"
+        elif key_s in _CODE_BLOCK_KEYS:
+            part = f"{label}:\n```\n{v}\n```"
+        else:
+            part = f"{label}: {v}"
+
+        if total + len(part) > max_chars and lines:
+            lines.append("...(truncated)")
+            break
+        lines.append(part)
+        total += len(part) + 1
+
+    return "\n".join(lines).strip()
+
+
+def chunk_message(text: str, limit: int = 4096) -> list[str]:
+    """Split a message into chunks at a character limit.
+
+    Args:
+        text: Text to chunk.
+        limit: Maximum characters per chunk.
+
+    Returns:
+        List of text chunks.
+    """
+    if len(text) <= limit:
+        return [text]
+    return [text[i : i + limit] for i in range(0, len(text), limit)]

agent_tether/models.py

@@ -0,0 +1,108 @@
+"""Core data models for agent-tether."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Literal
+
+from pydantic import BaseModel
+
+# ---------------------------------------------------------------------------
+# Handler type aliases
+# ---------------------------------------------------------------------------
+
+InputHandler = Callable[[str, str, str | None], Awaitable[None]]
+"""(thread_id, text, username) → None"""
+
+ApprovalHandler = Callable[..., Awaitable[None]]
+"""(thread_id, request_id, approved, reason=None, timer=None) → None
+
+timer: None | "all" | "dir" | tool_name
+"""
+
+CommandHandler = Callable[[str, str, str], Awaitable[str | None]]
+"""(thread_id, command, args) → optional response text"""
+
+StatusHandler = Callable[[], Awaitable[str]]
+"""() → status text to display"""
+
+StopHandler = Callable[[str], Awaitable[str | None]]
+"""(thread_id) → optional confirmation text"""
+
+UsageHandler = Callable[[str], Awaitable[str | None]]
+"""(thread_id) → optional usage text"""
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Handlers:
+    """Callbacks the consumer provides to handle platform events.
+
+    All handlers are optional. If a handler is not set, the corresponding
+    event is silently ignored.
+    """
+
+    on_input: InputHandler | None = None
+    """Human sent a text message in a thread."""
+
+    on_approval_response: ApprovalHandler | None = None
+    """Human responded to an approval/permission request."""
+
+    on_command: CommandHandler | None = None
+    """Catch-all for unrecognized commands. Return text to reply, or None."""
+
+    on_status_request: StatusHandler | None = None
+    """Handle /status or !status. Return text to display."""
+
+    on_stop_request: StopHandler | None = None
+    """Handle /stop or !stop. Return text to confirm, or None."""
+
+    on_usage_request: UsageHandler | None = None
+    """Handle /usage or !usage. Return text to display, or None."""
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CommandDef:
+    """Definition of a custom command.
+
+    Attributes:
+        description: Short help text shown in /help output.
+        handler: Async function ``(thread_id, args) → str | None``.
+            Return text to reply, or None for no reply.
+    """
+
+    description: str
+    handler: Callable[[str, str], Awaitable[str | None]]
+
+
+# ---------------------------------------------------------------------------
+# Approval / Choice requests
+# ---------------------------------------------------------------------------
+
+
+class ApprovalRequest(BaseModel):
+    """An approval or choice request sent to a human via a chat thread.
+
+    For permission requests (kind="permission"), the human is asked to
+    Allow or Deny a tool invocation.
+
+    For choice requests (kind="choice"), the human picks from a list of
+    options (e.g., selecting an environment, confirming a plan).
+    """
+
+    kind: Literal["permission", "choice"] = "permission"
+    request_id: str
+    title: str
+    description: str
+    options: list[str] = field(default_factory=lambda: ["Allow", "Deny"])
+    timeout_s: int = 300