mirror of
https://github.com/wu736139669/hapi.git
synced 2026-11-07 01:21:37 +00:00
229 lines
11 KiB
Markdown
229 lines
11 KiB
Markdown
# How it Works
|
|
|
|
HAPI consists of three interconnected components that work together to provide remote AI agent control.
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ Your Machine (Local or Hub Host) │
|
|
│ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ HAPI CLI │◄───────►│ HAPI Hub │◄───────►│ Web App │ │
|
|
│ │ │ Socket │ │ SSE │ (embedded) │ │
|
|
│ │ + AI Agent │ .IO │ + SQLite │ │ │ │
|
|
│ │ │ │ + REST API │ │ │ │
|
|
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │
|
|
│ │ │
|
|
│ │ localhost:3006 │
|
|
└───────────────────────────────────┼────────────────────────────────────────┘
|
|
│
|
|
┌─────────▼─────────┐
|
|
│ Tunnel (Optional)│
|
|
│ Cloudflare/ngrok │
|
|
└─────────┬─────────┘
|
|
│
|
|
┌───────────────────────────────────┼────────────────────────────────────────┐
|
|
│ Public Internet │
|
|
│ │ │
|
|
│ ┌─────────────────────────┼─────────────────────────┐ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌──────────────┐ ┌──────────────┐ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ │ Telegram │ │ PWA / │ │ │
|
|
│ │ │ Mini App │ │ Browser │ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ └──────────────┘ └──────────────┘ │ │
|
|
│ │ │ │
|
|
│ └───────────────────────────────────────────────────┘ │
|
|
│ Your Phone │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
> **Note:** The hub can run on your local desktop or a remote host (VPS, cloud, etc.). If deployed on a host with a public IP, tunneling is not required.
|
|
|
|
## Components
|
|
|
|
### HAPI CLI
|
|
|
|
The CLI is a wrapper around AI coding agents. It supports multiple agent flavors out of the box — see [Supported agents](./agents.md) for the full list. It:
|
|
|
|
- Starts and manages coding sessions
|
|
- Registers sessions with the HAPI hub
|
|
- Relays messages and permission requests
|
|
- Provides MCP (Model Context Protocol) tools
|
|
|
|
**Key Commands:**
|
|
```bash
|
|
hapi # Choose an agent interactively and start a session
|
|
hapi <agent> # Start a supported agent directly (required in scripts)
|
|
hapi runner start # Run background service for remote session spawning
|
|
hapi ping-peer --list # Shell peer shortlist (prefer MCP list_peers in-session)
|
|
```
|
|
|
|
MCP peer tools (same hub/namespace as the session): `list_peers` (discover), `inspect_peer` (read), `ping_peer` (message). These work from runner-spawned sessions even when the hub is on another host - see [Installation → Split hub + remote runner](./installation.md#split-hub-remote-runner-peer-discovery).
|
|
|
|
### HAPI Hub
|
|
|
|
The hub is the central service that connects everything:
|
|
|
|
- **HTTP API** - RESTful endpoints for sessions, messages, permissions
|
|
- **Socket.IO** - Real-time bidirectional communication with CLI
|
|
- **SSE (Server-Sent Events)** - Live updates pushed to web clients
|
|
- **SQLite Database** - Persistent storage for sessions and messages
|
|
- **Telegram Bot** - Notifications and Mini App integration
|
|
|
|
### Web App
|
|
|
|
A React-based PWA that provides the mobile interface:
|
|
|
|
- **Session List** - View all active and past sessions
|
|
- **Chat Interface** - Send messages and view agent responses
|
|
- **Permission Management** - Approve or deny tool access
|
|
- **File Browser** - Browse project files and view git diffs
|
|
- **Terminal View** - Run commands on the working machine from your browser
|
|
- **Voice Assistant** - Talk to your agent and approve permissions by voice (see [Voice input and assistant](./voice-assistant.md))
|
|
- **Session References** - Copy a session reference or mention another conversation for context
|
|
- **Remote Spawn** - Start new sessions on any connected machine
|
|
|
|
## Data Flow
|
|
|
|
### Starting a Session
|
|
|
|
```
|
|
1. User runs `hapi` and chooses an agent
|
|
│
|
|
▼
|
|
2. CLI starts the selected agent
|
|
│
|
|
▼
|
|
3. CLI connects to hub via Socket.IO
|
|
│
|
|
▼
|
|
4. Hub creates session in database
|
|
│
|
|
▼
|
|
5. Web clients receive SSE update
|
|
│
|
|
▼
|
|
6. Session appears in mobile app
|
|
```
|
|
|
|
### Permission Request Flow
|
|
|
|
```
|
|
1. AI agent requests tool permission (e.g., file edit)
|
|
│
|
|
▼
|
|
2. CLI sends permission request to hub
|
|
│
|
|
▼
|
|
3. Hub stores request and notifies via SSE + Telegram
|
|
│
|
|
▼
|
|
4. User receives notification on phone
|
|
│
|
|
▼
|
|
5. User approves/denies in web app or Telegram
|
|
│
|
|
▼
|
|
6. Hub relays decision to CLI via Socket.IO
|
|
│
|
|
▼
|
|
7. CLI informs AI agent, execution continues
|
|
```
|
|
|
|
### Message Flow
|
|
|
|
```
|
|
User (Phone) Hub CLI
|
|
│ │ │
|
|
│──── Send message ──────►│ │
|
|
│ │─── Socket.IO emit ───►│
|
|
│ │ │
|
|
│ │ ├── AI processes
|
|
│ │ │
|
|
│ │◄── Stream response ───│
|
|
│◄─────── SSE ────────────│ │
|
|
│ │ │
|
|
```
|
|
|
|
## Communication Protocols
|
|
|
|
### CLI ↔ Hub: Socket.IO
|
|
|
|
Real-time bidirectional communication for:
|
|
- Session registration and heartbeat
|
|
- Message relay (user input → agent)
|
|
- Permission requests and responses
|
|
- Metadata and state updates
|
|
- RPC method invocation
|
|
|
|
### Hub ↔ Web: REST + SSE
|
|
|
|
- **REST API** for actions (send message, approve permission)
|
|
- **SSE stream** for real-time updates (new messages, status changes)
|
|
|
|
### External Access: Tunnel
|
|
|
|
For remote access outside your local network:
|
|
- **Built-in relay** (`hapi hub --relay`) - Managed tunwg tunnel (WireGuard + TLS), no third-party account required
|
|
- **Cloudflare Tunnel** (recommended) - Free, secure, reliable
|
|
- **Tailscale** - Mesh VPN for private networks
|
|
- **ngrok** - Quick setup for testing
|
|
|
|
## Seamless Handoff
|
|
|
|
HAPI's defining feature is the ability to seamlessly hand off control between local terminal and remote devices without losing session state.
|
|
|
|
### Local Mode
|
|
|
|
When working in local mode, you have the full terminal experience — it is the native agent CLI (Claude Code, Codex, OpenCode, and more):
|
|
|
|
- Direct keyboard input with instant response
|
|
- Full terminal UI with syntax highlighting
|
|
- Best for focused, uninterrupted coding sessions
|
|
- Agent tools run on your machine; model requests use the provider configured in the agent
|
|
|
|
### Remote Mode
|
|
|
|
Switch to remote mode when you need to step away:
|
|
|
|
- Control via Web/PWA/Telegram from any device
|
|
- Approve permissions on the go
|
|
- Monitor progress while away from your desk
|
|
- Session continues running on your local machine
|
|
|
|
### How Switching Works
|
|
|
|
```
|
|
┌─────────────────┐ ┌─────────────────┐
|
|
│ Local Mode │◄──────────────────►│ Remote Mode │
|
|
│ (Terminal) │ │ (Phone/Web) │
|
|
└─────────────────┘ └─────────────────┘
|
|
│ │
|
|
│ ┌────────────────────────────┐ │
|
|
└─►│ Same Session, Same State │◄─────┘
|
|
└────────────────────────────┘
|
|
```
|
|
|
|
**Local → Remote:**
|
|
- Open the session on your phone/web and send a message
|
|
- HAPI keeps the conversation going on the same working machine
|
|
|
|
**Remote → Local:**
|
|
- Continue typing in the terminal
|
|
- If the terminal shows the remote-control screen, press double-space to return to local input
|
|
|
|
Some agents keep both interfaces available at once, so no switch is needed.
|
|
For Codex terminal-exit and resume behavior, see [Usage and limits](./codex-shared-sessions.md).
|
|
|
|
### Use Cases
|
|
|
|
1. **Remote Control While Away** - Start a session at your desk, continue from your phone during commute or coffee break
|
|
|
|
2. **Permission Approval** - AI requests file access, you get notified on phone, approve with one tap, session continues
|
|
|
|
3. **Multi-Device Collaboration** - View session progress on your phone while your desktop does the heavy lifting
|