@aptove/bridge 0.2.4 → 0.2.5

package/README.md

@@ -5,12 +5,9 @@
 [![npm](https://img.shields.io/npm/v/%40aptove%2Fbridge?logo=npm&label=npm)](https://www.npmjs.com/package/@aptove/bridge)
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/gD7AMxBy9y)
 
-A bridge library and application between Agent Client Protocol (ACP) agents and clients.
+Aptove Bridge is a stand-alone app to connect any AI Agents that support Agent Client Protocol (ACP) with the Aptove Mobile App to seamlessly manage the AI agents running in a server or computer.
 
-`aptove-bridge` can be used in two ways:
-
-- **Standalone binary** — run `bridge` as a separate process that spawns your ACP agent over stdio and exposes it over WebSocket to mobile or desktop clients.
-- **Embedded library** — add `aptove-bridge` as a Rust dependency and run the bridge server in-process alongside your agent, with no subprocess or stdio pipe required.
+Bridge is actively developed and we are still experimenting. Until the first stable version, expect breaking changes in the configuration files and how it works.
 
 ## Transport Modes
 
@@ -20,8 +17,6 @@ A bridge library and application between Agent Client Protocol (ACP) agents and
 | **Cloudflare** | Remote access via Cloudflare Zero Trust (internet-accessible) | [docs/transport/cloudflare.md](docs/transport/cloudflare.md) |
 | **Tailscale** | Private overlay network via MagicDNS + HTTPS (Recommended) | [docs/transport/tailscale.md](docs/transport/tailscale.md) |
 
-One transport is active at a time. When multiple are enabled in `common.toml`, the bridge prompts you to select one at startup.
-
 ## Features
 
 - 📱 **QR Code Pairing**: Secure one-time code pairing via QR scan
@@ -29,98 +24,38 @@ One transport is active at a time. When multiple are enabled in `common.toml`, t
 - ⚡ **WebSocket Streaming**: Real-time bidirectional communication
 - 🌐 **Multi-Transport**: Local, Cloudflare, Tailscale — configure and switch between them
 - 🔑 **Stable Agent Identity**: `agent_id` UUID persisted in `common.toml` for multi-transport dedup on mobile
+- 🔔 **Push Notifications**: Wake the mobile app when the agent responds while backgrounded
+- 🖥️ **Terminal UI**: Interactive TUI for setup and day-to-day management
 - 🦀 **Embeddable**: Use as a library with `StdioBridge` for in-process deployment
 
 ---
 
-## Using as a Library
-
-Add to your `Cargo.toml`:
-
-```toml
-[dependencies]
-aptove-bridge = "0.2"
-```
-
-### Minimal Example
-
-```rust
-use aptove_bridge::{
-    bridge::StdioBridge,
-    common_config::CommonConfig,
-    tls::TlsConfig,
-};
-
-#[tokio::main]
-async fn main() -> anyhow::Result<()> {
-    // Load (or initialise) shared config — generates agent_id and auth_token on first run
-    let mut config = CommonConfig::load()?;
-    config.ensure_agent_id();
-    config.ensure_auth_token();
-    config.save()?;
-
-    // Generate (or load) a self-signed TLS cert
-    let tls = TlsConfig::load_or_generate(&CommonConfig::config_dir(), &[])?;
-
-    StdioBridge::new("copilot --acp".to_string(), 8765)
-        .with_auth_token(Some(config.auth_token.clone()))
-        .with_tls(tls)
-        .start()
-        .await
-}
-```
-
-### `StdioBridge` Builder Methods
-
-| Method | Description |
-|--------|-------------|
-| `new(agent_command, port)` | Create a bridge that spawns the given command; listen on `port` |
-| `.with_bind_addr(addr)` | Override bind address (default: `"0.0.0.0"`) |
-| `.with_auth_token(token)` | Require a bearer token for connections |
-| `.with_tls(tls_config)` | Enable TLS with a `TlsConfig` (self-signed cert) |
-| `.with_external_tls()` | Signal that TLS is handled upstream (Tailscale Serve, Cloudflare) |
-| `.with_pairing(manager)` | Enable QR pairing via a `PairingManager` |
-| `.with_agent_pool(pool)` | Enable keep-alive sessions via an `AgentPool` |
-| `.with_working_dir(dir)` | Set the working directory for the spawned agent process |
-| `.with_push_relay(client)` | Enable push notifications via a relay |
-| `.with_webhook_resolver(fn)` | Handle `POST /webhook/<token>` trigger requests |
-| `.start()` | Start the WebSocket listener (runs until shutdown) |
-
----
-
-## Standalone Binary
-
 ### Quick Start
 
 ```bash
 # Build
 cargo build --release
 
-# Start the bridge — interactive agent selection menu
+# Start the bridge — opens the interactive TUI (setup wizard on first run)
 ./target/release/bridge
 
-# Or specify the agent directly
-./target/release/bridge run --agent-command "copilot --acp"
+# Use a custom config directory
+./target/release/bridge -c ./my-config
 ```
 
-Running `bridge` with no subcommand defaults to `run`. When `--agent-command` is omitted, an interactive menu lets you pick from known agents (Copilot, Gemini, Goose) or enter a custom command.
+On first launch the setup wizard runs automatically: it asks you to choose an agent command and a transport, then starts the bridge and shows a QR code for pairing.
 
 Scan the QR code with the mobile app to connect.
 
 ### Configuration — `common.toml`
 
-All transport settings live in `common.toml`. The file is created automatically with local transport enabled on first run.
+All settings live in `common.toml`, created automatically by the setup wizard on first run.
 
-**Default location:**
-
-| Platform | Path |
-|----------|------|
-| macOS | `~/Library/Application Support/com.aptove.bridge/common.toml` |
-| Linux | `~/.config/bridge/common.toml` |
+**Default location:** `.aptove-bridge/` directory inside the working directory where the bridge is launched.
 
 Override with `-c` / `--config-dir`:
 ```bash
-bridge -c ./my-config run --agent-command "copilot --acp"
+bridge -c ./my-config
 ```
 
 #### Example `common.toml`
@@ -128,6 +63,10 @@ bridge -c ./my-config run --agent-command "copilot --acp"
 ```toml
 agent_id   = "550e8400-e29b-41d4-a716-446655440000"  # auto-generated UUID
 auth_token = "base64urltoken"                         # auto-generated
+agent_command = "copilot --acp"                       # set by setup wizard
+
+keep_alive = true    # prevent system sleep while bridge is running
+log_level  = "WARN"  # ERROR / WARN / INFO / DEBUG / TRACE
 
 [transports.local]
 enabled = true
@@ -135,7 +74,7 @@ port    = 8765
 tls     = true
 
 [transports.cloudflare]
-enabled       = true
+enabled       = false
 hostname      = "https://agent.example.com"
 tunnel_id     = "abc123"
 tunnel_secret = "..."
@@ -144,10 +83,19 @@ client_id     = "client.access"
 client_secret = "xxxxx"
 
 [transports.tailscale-serve]
-enabled = true
+enabled = false
+
+# Optional — enables push notifications (see Push Notifications section below)
+[push_relay]
+url           = "https://push.aptove.com"
+token_url     = "https://token.aptove.com"
+client_id     = "your-client-id"
+client_secret = "your-client-secret"
 ```
 
-Enable only the transports you need. `agent_id` and `auth_token` are generated automatically on first run and stay stable across restarts.
+No transports are pre-enabled. The setup wizard asks you to choose one on first run.
+
+`agent_id` and `auth_token` are generated automatically on first run and stay stable across restarts.
 
 #### Config Directory Files
 
@@ -155,33 +103,30 @@ All bridge state lives in the config directory. These files are created automati
 
 | File | Purpose |
 |------|---------|
-| `common.toml` | Main config — `agent_id`, `auth_token`, and transport settings. Permissions `0600`. |
+| `common.toml` | Main config — `agent_id`, `auth_token`, `agent_command`, and transport settings. Permissions `0600`. |
 | `cert.pem` | Self-signed TLS certificate for the local transport WebSocket server. Its fingerprint is embedded in the QR pairing payload for certificate pinning. |
 | `key.pem` | Private key for the TLS certificate. |
-| `cert-extra-sans.json` | Tracks extra Subject Alternative Names (IPs/hostnames) baked into the TLS cert (e.g. `--advertise-addr` or Tailscale IP). When these change, the cert is automatically regenerated. |
+| `cert-extra-sans.json` | Tracks extra Subject Alternative Names (IPs/hostnames) baked into the TLS cert. When these change, the cert is automatically regenerated. |
 
-### Commands
+### CLI
 
-#### `run` — Start the bridge (default)
+```
+bridge [OPTIONS] [COMMAND]
+```
 
-`run` is the default subcommand — running `bridge` with no arguments is equivalent to `bridge run`.
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--config-dir <PATH>` | `-c` | Use a custom config directory instead of `.aptove-bridge/` |
+| `--version` | `-v` | Print version |
 
-```bash
-# Interactive agent selection
-bridge
+| Subcommand | Description |
+|------------|-------------|
+| *(none)* | Start the TUI (setup wizard if needed, then running screen) |
+| `setup` | Re-run the Cloudflare Zero Trust setup wizard |
 
-# Or specify the agent directly
-bridge run --agent-command "copilot --acp"
-```
-
-| Flag | Short | Description | Default |
-|------|-------|-------------|---------|
-| `--agent-command <CMD>` | `-a` | Command to spawn the ACP agent | Interactive menu |
-| `--bind <ADDR>` | `-b` | Address to bind the listener | `0.0.0.0` |
-| `--verbose` | | Enable info-level logging | Off (warn only) |
-| `--advertise-addr <ADDR>` | | Override LAN address in QR pairing URL | Auto-detected |
+#### `bridge` (default — TUI)
 
-When `--agent-command` is omitted, the bridge presents an interactive menu:
+Running `bridge` with no arguments opens the interactive TUI. On first launch it runs the setup wizard:
 
 ```
 Select an agent to run:
@@ -192,52 +137,123 @@ Select an agent to run:
 Enter number [1]:
 ```
 
-The QR code for pairing is always displayed at startup.
+Select **Custom** to enter any ACP-compatible agent command, for example:
 
-Transport selection, port, TLS, and auth token are all read from `common.toml`.
+```
+npx @agentclientprotocol/claude-agent-acp
+```
 
-#### `show-qr` — Show QR code for a second device
+After the wizard completes the bridge starts and displays a QR code for pairing.
+
+#### `bridge setup`
+
+Re-runs the Cloudflare Zero Trust setup wizard as a TUI flow. Use this to reconfigure your Cloudflare tunnel credentials without restarting the running bridge.
 
 ```bash
-bridge show-qr
+bridge setup
 ```
 
-Displays the connection QR code for the currently active transport. The bridge must already be running. Use this to pair an additional device without restarting.
+No flags are needed — the wizard guides you through everything interactively.
 
-#### `setup` — Provision Cloudflare infrastructure
+### TUI slash commands
 
-```bash
-bridge setup \
-  --api-token  "your-api-token" \
-  --account-id "your-account-id" \
-  --domain     "example.com" \
-  --subdomain  "agent"
+Type these in the input bar while the bridge is running:
+
+| Command | Description |
+|---------|-------------|
+| `/qr` | Show QR pairing code |
+| `/agent` | Change the AI agent command |
+| `/push` | Configure push notifications |
+| `/test-push` | Send a test push notification |
+| `/reconnect` | Restart the transport |
+| `/keep-alive` | Toggle prevent-sleep (on by default) |
+| `/log-level` | Change log verbosity (default: WARN) |
+| `/clear-logs` | Clear the log view |
+| `/copy-logs` | Copy all logs to clipboard |
+| `/help` | List all commands |
+| `/quit` | Exit the bridge |
+
+---
+
+## Push Notifications
+
+The bridge can alert the mobile app when the agent produces output while the app is backgrounded (WebSocket disconnected). The bridge never holds APNs/FCM credentials — it authenticates to a push relay service using a short-lived RS256 JWT and the relay handles APNs/FCM delivery.
+
+### How it works
+
+```
+Mobile app (backgrounded)          Bridge                      Push relay
+                                                               (push.aptove.com)
+        │                             │                              │
+        │  [app backgrounds]          │                              │
+        │                             │                              │
+        │                             │  agent produces output       │
+        │                             │◄─────────────────────       │
+        │                             │                              │
+        │                             │  no WebSocket receiver       │
+        │                             │  (broadcast send fails)      │
+        │                             │                              │
+        │                             │  POST /push (JWT Bearer) ───►│
+        │                             │                              │
+        │◄────────────────────────── APNs/FCM notification          │
+        │                             │                              │
+        │  [app foregrounds]          │                              │
+        │  reconnects WebSocket ─────►│                              │
+        │◄── buffered messages ───────│                              │
 ```
 
-Creates the Cloudflare tunnel, DNS record, Access Application, and Service Token. Saves credentials to `common.toml` under `[transports.cloudflare]`. Only needed once.
+### Trigger logic
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--api-token <TOKEN>` | Cloudflare API token | Required |
-| `--account-id <ID>` | Cloudflare account ID | Required |
-| `--domain <DOMAIN>` | Domain managed by Cloudflare | Required |
-| `--subdomain <SUB>` | Subdomain for the bridge endpoint | `agent` |
-| `--tunnel-name <NAME>` | Name for the Cloudflare tunnel | `aptove-tunnel` |
+Push is triggered by **passive failure detection** — the bridge never polls for connectivity:
 
-#### `status` — Check configuration
+| Site | Trigger | Source |
+|------|---------|--------|
+| Agent pool (main path) | Agent stdout arrives; `broadcast::Sender::send()` returns `Err` (zero receivers — no WebSocket client connected) | `src/agent_pool.rs` |
+| Active connection drop | `ws_sender.send()` returns `Err` (client disconnected mid-stream); message is buffered before notify | `src/bridge.rs` |
 
-```bash
-bridge status
+A 30-second per-client debounce prevents notification storms when the agent is verbose.
+
+### Setup
+
+Configure push via the `/push` TUI command or add the `[push_relay]` section directly to `common.toml`:
+
+```toml
+[push_relay]
+url           = "https://push.aptove.com"   # Push relay base URL
+token_url     = "https://token.aptove.com"  # JWT token service URL
+client_id     = "your-client-id"            # M2M client ID (JWT sub)
+client_secret = "your-client-secret"        # M2M client secret
 ```
 
-Prints the active `common.toml` path, `agent_id`, enabled transports, and Tailscale availability.
+All four fields are required. If the section is absent or any field is empty, push is silently disabled. The push relay URL is included in the QR pairing payload so the mobile app knows where to register its device token.
+
+### Security
+
+- Device tokens travel over the bridge's authenticated WebSocket (bearer `authToken` + TLS) — the same channel that carries the full LLM conversation.
+- JWT credentials (`client_id`, `client_secret`) never leave the bridge process.
+- The relay isolates registered devices per JWT `sub` (`client_id`) — one bridge cannot trigger pushes for another bridge's devices.
+- Notification content is fixed (`"Your agent has new activity"`) to prevent leaking agent response text.
+
+### Library usage
+
+```rust
+use aptove_bridge::push::PushRelayClient;
+
+let push_client = PushRelayClient::new("https://push.aptove.com".into(), String::new())
+    .with_jwt_credentials(
+        "https://token.aptove.com".into(),
+        "your-client-id".into(),
+        "your-client-secret".into(),
+    );
+
+let bridge = StdioBridge::new("copilot --acp".into(), 8765)
+    .with_push_relay(push_client);
+```
 
 ---
 
 ## Architecture
 
-### Standalone
-
 ```
 ┌─────────────┐                    ┌───────────────────────┐        ┌──────────────┐
 │  Client App │◄──────────────────►│  bridge binary        │◄──────►│  ACP Agent   │
@@ -245,16 +261,7 @@ Prints the active `common.toml` path, `agent_id`, enabled transports, and Tailsc
 └─────────────┘                    └───────────────────────┘        └──────────────┘
 ```
 
-### Embedded (library)
-
-```
-┌─────────────┐                    ┌──────────────────────────────────┐        ┌──────────────┐
-│  Client App │◄──────────────────►│  Your process                    │◄──────►│  ACP Agent   │
-│ (iOS/Android│  WebSocket (TLS)   │  StdioBridge (transport listener)│  stdio │  (your cmd)  │
-└─────────────┘                    └──────────────────────────────────┘        └──────────────┘
-```
-
-The agent process is still spawned as a subprocess via stdio — `StdioBridge` handles the WebSocket server, TLS, auth, and pairing in-process alongside your application.
+The agent process is spawned as a subprocess via stdio — `StdioBridge` handles the WebSocket server, TLS, auth, and pairing in-process alongside your application.
 
 ---
 
@@ -266,16 +273,16 @@ The agent process is still spawned as a subprocess via stdio — `StdioBridge` h
 | "Unauthorized" on connect | Wrong or missing auth token | Re-scan QR code |
 | TLS handshake failure | Certificate mismatch | Delete the config dir and restart to regenerate certs; re-pair the device |
 | App cannot reach bridge | Firewall blocking the port | Check OS firewall; ensure the port in `common.toml` is open |
-| Transport fails to start | `common.toml` has no `enabled = true` transport | Run `bridge status` to see configured transports |
+| Transport fails to start | No transport has `enabled = true` | Run the bridge and check the setup wizard |
 
 ### Debugging
 
 ```bash
-# Enable verbose logging
-bridge run --verbose
+# Change log verbosity via TUI
+# Type /log-level and select DEBUG or TRACE
 
-# Check which transports are configured
-bridge status
+# Or set it permanently in common.toml
+log_level = "DEBUG"
 
 # Test agent command independently
 echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | copilot --acp
@@ -285,12 +292,7 @@ echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | copilot --acp
 
 Please note that the project is extensively tested only with Copilot CLI. Open a bug report if you notice any issues with other ACP-Compatible Agents.
 
-The easiest way to test any supported agent is to run `bridge` and pick it from the interactive menu. Alternatively, pass the command directly:
-
-```bash
-bridge run -a "gemini --experimental-acp" --verbose
-bridge run -a "goose acp" --verbose
-```
+Run `bridge` and pick an agent from the setup wizard, or edit `agent_command` directly in `common.toml`.
 
 ---
 
@@ -300,16 +302,12 @@ bridge run -a "goose acp" --verbose
 - **TLS**: self-signed certificate generated on first run. Certificate fingerprint is included in the QR pairing payload and pinned by the mobile app to prevent MITM attacks.
 - **Pairing codes**: 6-digit, single-use, expire after 60 seconds. Rate-limited to 5 attempts per code.
 - **`common.toml`**: contains all secrets. Permissions are set to `0600` automatically. Keep it secure.
-- **Agent command**: the `--agent-command` value (or interactive menu selection) is validated at startup — the binary must exist and be executable before the server accepts connections. The command is never persisted to `common.toml`; it must be supplied each time the bridge is started. The bridge is an operator tool: whoever can invoke it already has local shell access, so the agent command is implicitly trusted to the same degree as any other command that user could run.
+- **Agent command**: saved to `agent_command` in `common.toml` by the setup wizard. It can be changed at any time via the `/agent` TUI command. The bridge is an operator tool: whoever can invoke it already has local shell access, so the agent command is implicitly trusted to the same degree as any other command that user could run.
 
 To rotate credentials (invalidates all paired devices):
 
 ```bash
-# macOS
-rm ~/Library/Application\ Support/com.aptove.bridge/common.toml
-# Linux
-rm ~/.config/bridge/common.toml
-
+rm .aptove-bridge/common.toml
 bridge
 ```
 
@@ -324,4 +322,4 @@ cargo test               # Run tests
 
 ## License
 
-Apache 2.0 — see [LICENSE](LICENSE)
+MIT — see [LICENSE](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aptove/bridge",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "ACP bridge — connects ACP agents to mobile and desktop clients over WebSocket",
   "license": "MIT",
   "repository": {
@@ -33,10 +33,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@aptove/bridge-darwin-arm64": "0.2.4",
-    "@aptove/bridge-darwin-x64": "0.2.4",
-    "@aptove/bridge-linux-arm64": "0.2.4",
-    "@aptove/bridge-linux-x64": "0.2.4",
-    "@aptove/bridge-win32-x64": "0.2.4"
+    "@aptove/bridge-darwin-arm64": "0.2.5",
+    "@aptove/bridge-darwin-x64": "0.2.5",
+    "@aptove/bridge-linux-arm64": "0.2.5",
+    "@aptove/bridge-linux-x64": "0.2.5",
+    "@aptove/bridge-win32-x64": "0.2.5"
   }
 }