Metadata-Version: 2.4
Name: atlasbridge
Version: 0.4.0
Summary: Universal human-in-the-loop control plane for AI developer agents — forward prompts to your phone, reply from anywhere
Author: AtlasBridge Contributors
License: MIT License
        
        Copyright (c) 2026 Aegis Contributors
        
        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.
        
Project-URL: Homepage, https://github.com/abdulraoufatia/atlasbridge
Project-URL: Repository, https://github.com/abdulraoufatia/atlasbridge
Project-URL: Issues, https://github.com/abdulraoufatia/atlasbridge/issues
Project-URL: Changelog, https://github.com/abdulraoufatia/atlasbridge/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/abdulraoufatia/atlasbridge/blob/main/SECURITY.md
Keywords: ai,cli,telegram,relay,interactive,claude,pty,remote
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: anyio>=4.4
Requires-Dist: pydantic>=2.7
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: tomli-w>=1.0
Requires-Dist: structlog>=24.1
Requires-Dist: rich>=13.7
Requires-Dist: ptyprocess>=0.7
Requires-Dist: psutil>=5.9
Requires-Dist: detect-secrets>=1.5
Provides-Extra: slack
Requires-Dist: slack-sdk>=3.19; extra == "slack"
Requires-Dist: websockets>=11; extra == "slack"
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-psutil; extra == "dev"
Requires-Dist: bandit[toml]>=1.7; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Dynamic: license-file

# AtlasBridge (AtlasBridge)

> **Universal human-in-the-loop control plane for AI developer agents.**

[![CI](https://github.com/abdulraoufatia/atlasbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/abdulraoufatia/atlasbridge/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
[![Version](https://img.shields.io/badge/version-0.2.0--dev-green.svg)](CHANGELOG.md)

---

AtlasBridge sits between you and your AI coding agent. Whenever your agent pauses and requires human input — approval, confirmation, a choice, or clarification — AtlasBridge forwards that prompt to your phone.

You respond from your phone, from a channel such as Telegram or WhatsApp, Slack or others. AtlasBridge relays your decision back to the CLI. Execution resumes.

No walking back to your desk. No missed prompts. You stay in control.

```
┌──────────────┐        ┌───────────────┐        ┌─────────────────┐
│  AI Agent    │──────► │     AtlasBridge     │──────► │   Your Phone    │
│ (Claude CLI) │        │  Prompt Relay │        │   (Telegram)    │
│              │◄────── │               │◄────── │                 │
└──────────────┘        └───────────────┘        └─────────────────┘
   paused waiting           detects &                you reply
   for input                forwards prompt          from anywhere
```

---

## How it works

1. `atlasbridge run claude` — wraps your AI CLI in a PTY supervisor
2. The **tri-signal prompt detector** watches the output stream
3. When a prompt is detected, AtlasBridge sends it to your Telegram (or Slack)
4. You tap a button or send a reply on your phone
5. AtlasBridge injects your answer into the CLI's stdin
6. The agent continues

That's it. AtlasBridge is a relay, not a firewall. It does not interpret commands, score risks, or block actions. It asks you — and only you — at the exact moment the agent needs human input.

---

## Status

| Version | Status | Description |
|---------|--------|-------------|
| **v0.1.0** | Design release | Architecture, docs, and code stubs |
| **v0.2.0** | In progress | macOS MVP — working Telegram relay |
| v0.3.0 | Planned | Linux support |
| v0.4.0 | Planned | Slack channel |
| v0.5.0 | Planned | Windows (ConPTY, experimental) |

---

## Quick start (v0.2.0 target)

```bash
pip install atlasbridge

# First-time setup (creates ~/.atlasbridge/config.toml)
aegis setup

# Wrap Claude Code
aegis run claude

# In another terminal, check status
aegis status
```

When Claude Code asks you a question, your Telegram bot will send you a message with buttons. Tap Yes or No. Claude Code answers and continues.

---

## Design

See the `docs/` directory:

| Document | What it covers |
|----------|---------------|
| [architecture.md](docs/architecture.md) | System diagram, component overview, sequence diagrams |
| [reliability.md](docs/reliability.md) | PTY supervisor, tri-signal detector, Prompt Lab |
| [adapters.md](docs/adapters.md) | BaseAdapter interface, Claude Code adapter |
| [channels.md](docs/channels.md) | BaseChannel interface, Telegram implementation |
| [cli-ux.md](docs/cli-ux.md) | All CLI commands, output formats, exit codes |
| [roadmap-90-days.md](docs/roadmap-90-days.md) | 6-phase roadmap, v0.2.0–v0.5.0 |
| [qa-top-20-failure-scenarios.md](docs/qa-top-20-failure-scenarios.md) | 20 mandatory QA scenarios |
| [dev-workflow-multi-agent.md](docs/dev-workflow-multi-agent.md) | Branch model, agent roles, CI pipeline |

---

## Repository structure

```
src/aegis/
  core/
    prompt/     — detector, state machine, models
    session/    — session manager and lifecycle
    routing/    — prompt router (events → channel, replies → PTY)
    store/      — SQLite database
    audit/      — append-only audit log with hash chaining
    daemon/     — daemon manager (orchestrates all subsystems)
    scheduler/  — TTL sweeper and periodic tasks
  os/tty/       — PTY supervisors (macOS, Linux, Windows stub)
  adapters/     — CLI tool adapters (Claude Code, OpenAI CLI, custom)
  channels/     — notification channels (Telegram, Slack stub)
  cli/          — Click CLI entry point and subcommands
tests/
  unit/         — pure unit tests (no I/O)
  integration/  — SQLite + mocked HTTP
  e2e/          — real PTY + mocked Telegram
  prompt_lab/   — deterministic QA scenario runner
    scenarios/  — QA-001 through QA-020 scenario implementations
docs/           — design documents (see table above)
```

---

## Core invariants

AtlasBridge guarantees the following regardless of channel, adapter, or concurrency:

1. **No duplicate injection** — nonce idempotency via atomic SQL guard
2. **No expired injection** — TTL enforced in the database WHERE clause
3. **No cross-session injection** — prompt_id + session_id binding checked
4. **No unauthorised injection** — allowlisted identities only
5. **No echo loops** — 500ms suppression window after every injection
6. **No lost prompts** — daemon restart reloads pending prompts from SQLite
7. **Bounded memory** — rolling 4096-byte buffer, never unbounded growth

---

## Development

```bash
# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run a Prompt Lab scenario
aegis lab run partial-line-prompt

# Lint and format
ruff check . && ruff format --check .

# Type check
mypy src/aegis/

# Full CI equivalent (local)
ruff check . && ruff format --check . && mypy src/aegis/ && pytest tests/ --cov=aegis
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). All contributions require:
- Existing tests to remain green
- New code to have unit tests
- Prompt Lab scenarios for any PTY/detection changes

---

## License

MIT — see [LICENSE](LICENSE).
