agent-tether 0.2.0__tar.gz

agent_tether-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # REQUIRED for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+      
+      - name: Build package
+        run: python -m build
+      
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_tether-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,all]"
+      
+      - name: Run tests
+        run: pytest tests/ -v
+      
+      - name: Check code formatting
+        run: black --check src/ tests/

agent_tether-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.mypy_cache/
+.pytest_cache/
+.venv/
+venv/
+*.so
+.coverage
+htmlcov/

agent_tether-0.2.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to agent-tether will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-02-12
+
+### Added
+- Runner protocol and registry framework
+  - `Runner` protocol for agent backends
+  - `RunnerEvents` protocol with 10 event callbacks
+  - `RunnerRegistry` for factory-based runner creation
+  - `RunnerUnavailableError` exception
+- Comprehensive test suite (41 tests)
+- Full documentation in README.md
+
+### Changed
+- Simplified package scope to bridges + runner protocol only
+- Updated documentation to reflect focused scope
+- Improved example code in README
+
+## [0.1.0] - 2026-02-11
+
+### Added
+- Initial release with chat platform bridges
+- Telegram bridge with forum topics and inline keyboards
+- Slack bridge with socket mode and threaded conversations
+- Discord bridge with pairing system and thread management
+- Auto-approve engine with per-thread, per-tool, and per-directory timers
+- Command handling with built-in commands and custom registry
+- Message formatting utilities (markdown, chunking, tool inputs)
+- Thread state management with JSON persistence
+- Notification batching and error debouncing
+- Event subscriber system for bridge events
+- Comprehensive test coverage
+- MIT License
+- Full documentation
+
+[0.2.0]: https://github.com/xithing/agent-tether/releases/tag/v0.2.0
+[0.1.0]: https://github.com/xithing/agent-tether/releases/tag/v0.1.0

agent_tether-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xithing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_tether-0.2.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: agent-tether
+Version: 0.2.0
+Summary: Tether your AI agents to human oversight through Telegram, Slack, and Discord
+Project-URL: Homepage, https://github.com/xithing/agent-tether
+Project-URL: Repository, https://github.com/xithing/agent-tether
+Project-URL: Issues, https://github.com/xithing/agent-tether/issues
+Author: xithing
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,approval,discord,human-in-the-loop,slack,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: discord-py>=2.0; extra == 'all'
+Requires-Dist: python-telegram-bot>=21.0; extra == 'all'
+Requires-Dist: slack-bolt>=1.0; extra == 'all'
+Requires-Dist: slack-sdk>=3.0; extra == 'all'
+Provides-Extra: bridges
+Requires-Dist: discord-py>=2.0; extra == 'bridges'
+Requires-Dist: python-telegram-bot>=21.0; extra == 'bridges'
+Requires-Dist: slack-bolt>=1.0; extra == 'bridges'
+Requires-Dist: slack-sdk>=3.0; extra == 'bridges'
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: discord
+Requires-Dist: discord-py>=2.0; extra == 'discord'
+Provides-Extra: slack
+Requires-Dist: slack-bolt>=1.0; extra == 'slack'
+Requires-Dist: slack-sdk>=3.0; extra == 'slack'
+Provides-Extra: telegram
+Requires-Dist: python-telegram-bot>=21.0; extra == 'telegram'
+Description-Content-Type: text/markdown
+
+# agent-tether
+
+Connect to your AI coding agents through Telegram, Slack, and Discord. Control them from your phone while they work on your laptop.
+
+A Python library that handles the chat-platform integration for AI agent supervision: thread management, approval flows with inline buttons, auto-approve timers, message formatting, and command handling. You provide callbacks for your application logic.
+
+**Use Cases:**
+- Monitor Claude/Codex/Aider from your phone while agents run locally
+- Get approval requests as Telegram notifications with one-tap approve/deny
+- Set auto-approve timers for trusted operations
+- Send additional input or stop agents remotely
+
+## Install
+
+```bash
+pip install agent-tether[telegram]   # Telegram support
+pip install agent-tether[slack]      # Slack support
+pip install agent-tether[discord]    # Discord support
+pip install agent-tether[all]        # All platforms
+```
+
+## Quick Start
+
+```python
+import asyncio
+from agent_tether import TelegramBridge, Handlers
+
+async def on_input(thread_id: str, text: str, username: str | None):
+    print(f"[{thread_id}] {username}: {text}")
+
+async def on_approval_response(thread_id: str, request_id: str, approved: bool, **kwargs):
+    print(f"[{thread_id}] {'Approved' if approved else 'Denied'} {request_id}")
+
+bridge = TelegramBridge(
+    token="BOT_TOKEN",
+    forum_group_id=123456,
+    handlers=Handlers(
+        on_input=on_input,
+        on_approval_response=on_approval_response,
+    ),
+)
+
+async def main():
+    await bridge.start()
+
+    thread_id = await bridge.create_thread("My Agent Task")
+    await bridge.send_output(thread_id, "Starting work on your request...")
+
+    await bridge.send_approval_request(
+        thread_id,
+        request_id="req_123",
+        tool_name="Bash",
+        description='{"command": "rm -rf /tmp/cache"}',
+    )
+
+    await bridge.wait_until_stopped()
+
+asyncio.run(main())
+```
+
+### Runner Protocol Example
+
+```python
+from agent_tether.runner import Runner, RunnerEvents, RunnerRegistry
+
+# Implement event callbacks
+class MyEventHandler:
+    async def on_output(self, session_id, stream, text, **kwargs):
+        print(f"[{session_id}] {text}", end="")
+    
+    async def on_error(self, session_id, code, message):
+        print(f"ERROR: {message}")
+    
+    async def on_exit(self, session_id, exit_code):
+        print(f"Session {session_id} exited with code {exit_code}")
+    
+    async def on_permission_request(self, session_id, request_id, tool_name, tool_input, **kwargs):
+        print(f"Permission requested for {tool_name}")
+    
+    # ... other event callbacks
+
+# Register runners
+registry = RunnerRegistry()
+
+def my_runner_factory(events, config):
+    # Return a Runner implementation
+    return MyCustomRunner(events, **config)
+
+registry.register("my-runner", my_runner_factory)
+
+# Create and use runner
+events = MyEventHandler()
+runner = registry.create("my-runner", events, api_key="...", model="...")
+
+await runner.start("sess_1", "Build a web app", approval_choice=1)
+await runner.send_input("sess_1", "Add a login page")
+await runner.stop("sess_1")
+```
+
+## Features
+
+### Chat Platform Bridges
+- **Telegram** — Forum topics, inline keyboard approval buttons, typing indicators, HTML formatting
+- **Slack** — Socket mode, threaded conversations, text-based approval commands
+- **Discord** — Channel threads, pairing/authorization system, text-based approvals
+- **Approval engine** — Auto-approve timers (per-thread, per-tool, per-directory), batched notifications
+- **Commands** — Built-in `/help`, `/stop`, `/status`, `/usage` + custom command registry
+- **Formatting** — Tool input JSON → readable text, markdown conversion, message chunking
+
+### Runner Protocol
+- **Protocol definitions** — `Runner` and `RunnerEvents` interfaces for agent backends
+- **RunnerRegistry** — Factory pattern for discovering and creating runners
+- **Pluggable adapters** — Clean protocol for implementing custom agent backends
+- **Event-driven** — Runners report progress via callbacks (output, errors, permissions, etc.)
+
+## Documentation
+
+- **[CHANGELOG.md](CHANGELOG.md)** — Version history and changes
+
+## Contributing
+
+Contributions welcome! Please feel free to submit a Pull Request.
+
+## Related Projects
+
+This library is extracted from [Tether](https://github.com/xithing/tether), a full-featured control plane for supervising AI coding agents.
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details
+

agent_tether-0.2.0/README.md

@@ -0,0 +1,131 @@
+# agent-tether
+
+Connect to your AI coding agents through Telegram, Slack, and Discord. Control them from your phone while they work on your laptop.
+
+A Python library that handles the chat-platform integration for AI agent supervision: thread management, approval flows with inline buttons, auto-approve timers, message formatting, and command handling. You provide callbacks for your application logic.
+
+**Use Cases:**
+- Monitor Claude/Codex/Aider from your phone while agents run locally
+- Get approval requests as Telegram notifications with one-tap approve/deny
+- Set auto-approve timers for trusted operations
+- Send additional input or stop agents remotely
+
+## Install
+
+```bash
+pip install agent-tether[telegram]   # Telegram support
+pip install agent-tether[slack]      # Slack support
+pip install agent-tether[discord]    # Discord support
+pip install agent-tether[all]        # All platforms
+```
+
+## Quick Start
+
+```python
+import asyncio
+from agent_tether import TelegramBridge, Handlers
+
+async def on_input(thread_id: str, text: str, username: str | None):
+    print(f"[{thread_id}] {username}: {text}")
+
+async def on_approval_response(thread_id: str, request_id: str, approved: bool, **kwargs):
+    print(f"[{thread_id}] {'Approved' if approved else 'Denied'} {request_id}")
+
+bridge = TelegramBridge(
+    token="BOT_TOKEN",
+    forum_group_id=123456,
+    handlers=Handlers(
+        on_input=on_input,
+        on_approval_response=on_approval_response,
+    ),
+)
+
+async def main():
+    await bridge.start()
+
+    thread_id = await bridge.create_thread("My Agent Task")
+    await bridge.send_output(thread_id, "Starting work on your request...")
+
+    await bridge.send_approval_request(
+        thread_id,
+        request_id="req_123",
+        tool_name="Bash",
+        description='{"command": "rm -rf /tmp/cache"}',
+    )
+
+    await bridge.wait_until_stopped()
+
+asyncio.run(main())
+```
+
+### Runner Protocol Example
+
+```python
+from agent_tether.runner import Runner, RunnerEvents, RunnerRegistry
+
+# Implement event callbacks
+class MyEventHandler:
+    async def on_output(self, session_id, stream, text, **kwargs):
+        print(f"[{session_id}] {text}", end="")
+    
+    async def on_error(self, session_id, code, message):
+        print(f"ERROR: {message}")
+    
+    async def on_exit(self, session_id, exit_code):
+        print(f"Session {session_id} exited with code {exit_code}")
+    
+    async def on_permission_request(self, session_id, request_id, tool_name, tool_input, **kwargs):
+        print(f"Permission requested for {tool_name}")
+    
+    # ... other event callbacks
+
+# Register runners
+registry = RunnerRegistry()
+
+def my_runner_factory(events, config):
+    # Return a Runner implementation
+    return MyCustomRunner(events, **config)
+
+registry.register("my-runner", my_runner_factory)
+
+# Create and use runner
+events = MyEventHandler()
+runner = registry.create("my-runner", events, api_key="...", model="...")
+
+await runner.start("sess_1", "Build a web app", approval_choice=1)
+await runner.send_input("sess_1", "Add a login page")
+await runner.stop("sess_1")
+```
+
+## Features
+
+### Chat Platform Bridges
+- **Telegram** — Forum topics, inline keyboard approval buttons, typing indicators, HTML formatting
+- **Slack** — Socket mode, threaded conversations, text-based approval commands
+- **Discord** — Channel threads, pairing/authorization system, text-based approvals
+- **Approval engine** — Auto-approve timers (per-thread, per-tool, per-directory), batched notifications
+- **Commands** — Built-in `/help`, `/stop`, `/status`, `/usage` + custom command registry
+- **Formatting** — Tool input JSON → readable text, markdown conversion, message chunking
+
+### Runner Protocol
+- **Protocol definitions** — `Runner` and `RunnerEvents` interfaces for agent backends
+- **RunnerRegistry** — Factory pattern for discovering and creating runners
+- **Pluggable adapters** — Clean protocol for implementing custom agent backends
+- **Event-driven** — Runners report progress via callbacks (output, errors, permissions, etc.)
+
+## Documentation
+
+- **[CHANGELOG.md](CHANGELOG.md)** — Version history and changes
+
+## Contributing
+
+Contributions welcome! Please feel free to submit a Pull Request.
+
+## Related Projects
+
+This library is extracted from [Tether](https://github.com/xithing/tether), a full-featured control plane for supervising AI coding agents.
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details
+

agent_tether-0.2.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-tether"
+version = "0.2.0"
+description = "Tether your AI agents to human oversight through Telegram, Slack, and Discord"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "xithing" },
+]
+keywords = ["ai", "agent", "telegram", "slack", "discord", "approval", "human-in-the-loop"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+# Bridges
+telegram = ["python-telegram-bot>=21.0"]
+slack = ["slack-sdk>=3.0", "slack-bolt>=1.0"]
+discord = ["discord.py>=2.0"]
+bridges = [
+    "python-telegram-bot>=21.0",
+    "slack-sdk>=3.0",
+    "slack-bolt>=1.0",
+    "discord.py>=2.0",
+]
+# All features (currently just bridges)
+all = [
+    "python-telegram-bot>=21.0",
+    "slack-sdk>=3.0",
+    "slack-bolt>=1.0",
+    "discord.py>=2.0",
+]
+# Development
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "black",
+    "mypy",
+]
+
+[project.urls]
+Homepage = "https://github.com/xithing/agent-tether"
+Repository = "https://github.com/xithing/agent-tether"
+Issues = "https://github.com/xithing/agent-tether/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_tether"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.black]
+line-length = 99
+target-version = ["py311"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

agent_tether-0.2.0/src/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}")