@aptove/bridge 0.1.18 → 0.2.0

package/README.md

@@ -12,8 +12,6 @@ A bridge library and application between Agent Client Protocol (ACP) agents and
 - **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.
 
-The [Aptove](https://github.com/aptove/aptove) project is the reference implementation of the embedded library usage — `aptove run` starts both the ACP agent and bridge server in a single process.
-
 ## Transport Modes
 
 | Mode | Use Case | Documentation |
@@ -32,7 +30,7 @@ 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
-- 🦀 **Embeddable**: Use as a library with `BridgeServer` for in-process deployment
+- 🦀 **Embeddable**: Use as a library with `StdioBridge` for in-process deployment
 
 ---
 
@@ -48,58 +46,46 @@ aptove-bridge = "0.1"
 ### Minimal Example
 
 ```rust
-use aptove_bridge::{BridgeServer, BridgeServeConfig};
+use aptove_bridge::{
+    bridge::StdioBridge,
+    common_config::CommonConfig,
+    tls::TlsConfig,
+};
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
-    // Build from defaults — reads transport selection from common.toml
-    // in ~/Library/Application Support/Aptove (macOS) or ~/.config/Aptove (Linux).
-    // Prompts the user to select a transport if multiple are enabled.
-    let mut server = BridgeServer::build(&BridgeServeConfig::default())?;
-
-    // Display a pairing QR code so a client can connect
-    server.show_qr()?;
-
-    // Take the in-process transport — wire it to your agent message loop
-    let mut transport = server.take_transport();
-
-    // Run your agent loop and bridge listener concurrently
-    tokio::select! {
-        _ = my_agent_loop(&mut transport) => {}
-        res = server.start() => { res?; }
-    }
-
-    Ok(())
+    // 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
 }
 ```
 
-`take_transport()` returns an `InProcessTransport` that implements the same `Transport` trait as `StdioTransport` — your agent message loop works identically whether running standalone or embedded.
-
-### `BridgeServeConfig`
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `port` | `8080` | WebSocket listen port (overridden by `common.toml` per-transport config) |
-| `bind_addr` | `"0.0.0.0"` | Bind address |
-| `tls` | `true` | Enable TLS (self-signed cert auto-generated) |
-| `auth_token` | `None` | Bearer token required for connections (auto-loaded from `common.toml`) |
-| `keep_alive` | `false` | Enable keep-alive agent pool |
-| `config_dir` | platform default | Directory for `common.toml`, TLS certs, and credentials |
-
-Load from disk (reads `bridge.toml` and `common.toml`, generates `agent_id` if absent):
-
-```rust
-let config = BridgeServeConfig::load()?;
-```
-
-### Reference Implementation: Aptove
-
-The [Aptove project](https://github.com/aptove/aptove) (`aptove run`) is the full reference implementation. Key patterns it uses:
-
-- `BridgeServer::build_with_trigger_store()` — wires in a `TriggerStore` for webhook support
-- `server.show_qr()` — uses the pairing handshake so clients deduplicate agents by `agentId`
-- `server.take_transport()` + `run_message_loop()` — connects the in-process transport to the ACP dispatch loop
-- `tokio::select!` on `agent_loop` and `server.start()` — clean shutdown when either side exits
+### `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) |
 
 ---
 
@@ -111,13 +97,16 @@ The [Aptove project](https://github.com/aptove/aptove) (`aptove run`) is the ful
 # Build
 cargo build --release
 
-# Start with local transport (default — no config needed)
-./target/release/bridge run \
-  --agent-command "gemini --experimental-acp" \
-  --qr
+# Start the bridge — interactive agent selection menu
+./target/release/bridge
+
+# Or specify the agent directly
+./target/release/bridge run --agent-command "copilot --acp"
 ```
 
-Scan the QR code with the Aptove mobile app to connect.
+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.
+
+Scan the QR code with the mobile app to connect.
 
 ### Configuration — `common.toml`
 
@@ -125,16 +114,14 @@ All transport settings live in `common.toml`. The file is created automatically
 
 **Default location:**
 
-| Runtime | macOS | Linux |
-|---------|-------|-------|
-| `aptove run` (embedded) | `~/Library/Application Support/Aptove/common.toml` | `~/.config/Aptove/common.toml` |
-| `bridge` (standalone) | `~/Library/Application Support/com.aptove.bridge/common.toml` | `~/.config/bridge/common.toml` |
-
-When using `aptove run`, this config is shared across all workspaces.
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/com.aptove.bridge/common.toml` |
+| Linux | `~/.config/bridge/common.toml` |
 
-Override with `--config-dir`:
+Override with `-c` / `--config-dir`:
 ```bash
-bridge --config-dir ./my-config run --agent-command "gemini --experimental-acp"
+bridge -c ./my-config run --agent-command "copilot --acp"
 ```
 
 #### Example `common.toml`
@@ -168,20 +155,50 @@ tls     = true
 
 Enable only the transports you need. `agent_id` and `auth_token` are generated automatically on first run and stay stable across restarts.
 
+#### Config Directory Files
+
+All bridge state lives in the config directory. These files are created automatically on first run:
+
+| File | Purpose |
+|------|---------|
+| `common.toml` | Main config — `agent_id`, `auth_token`, 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. |
+
 ### Commands
 
-#### `run` — Start the bridge
+#### `run` — Start the bridge (default)
+
+`run` is the default subcommand — running `bridge` with no arguments is equivalent to `bridge run`.
 
 ```bash
-bridge run --agent-command "<your-agent-command>"
+# Interactive agent selection
+bridge
+
+# Or specify the agent directly
+bridge run --agent-command "copilot --acp"
 ```
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--agent-command <CMD>` | Command to spawn the ACP agent | Required |
-| `--bind <ADDR>` | Address to bind the listener | `0.0.0.0` |
-| `--qr` | Display QR code for pairing at startup | Off |
-| `--verbose` | Enable info-level logging | Off (warn only) |
+| 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 |
+
+When `--agent-command` is omitted, the bridge presents an interactive menu:
+
+```
+Select an agent to run:
+  [1] Copilot  (copilot --acp)
+  [2] Gemini   (gemini --experimental-acp)
+  [3] Goose    (goose acp)
+  [4] Custom
+Enter number [1]:
+```
+
+The QR code for pairing is always displayed at startup.
 
 Transport selection, port, TLS, and auth token are all read from `common.toml`.
 
@@ -193,12 +210,6 @@ bridge show-qr
 
 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.
 
-To show the QR at initial startup, pass `--qr` to `bridge run` instead:
-
-```bash
-bridge run --agent-command "aptove stdio" --qr
-```
-
 #### `setup` — Provision Cloudflare infrastructure
 
 ```bash
@@ -243,16 +254,13 @@ Prints the active `common.toml` path, `agent_id`, enabled transports, and Tailsc
 ### Embedded (library)
 
 ```
-┌─────────────┐                    ┌──────────────────────────────────────────────┐
-│  Client App │◄──────────────────►│  Your process                                │
-│ (iOS/Android│  WebSocket (TLS)   │  ┌─────────────────┐  ┌────────────────────┐ │
-└─────────────┘                    │  │  BridgeServer   │◄►│  Agent message loop│ │
-                                   │  │  (transport)    │  │ (InProcessTransport│ │
-                                   │  └─────────────────┘  └────────────────────┘ │
-                                   └──────────────────────────────────────────────┘
+┌─────────────┐                    ┌──────────────────────────────────┐        ┌──────────────┐
+│  Client App │◄──────────────────►│  Your process                    │◄──────►│  ACP Agent   │
+│ (iOS/Android│  WebSocket (TLS)   │  StdioBridge (transport listener)│  stdio │  (your cmd)  │
+└─────────────┘                    └──────────────────────────────────┘        └──────────────┘
 ```
 
-No subprocess is spawned. Agent and bridge communicate via in-process channels.
+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.
 
 ---
 
@@ -270,13 +278,24 @@ No subprocess is spawned. Agent and bridge communicate via in-process channels.
 
 ```bash
 # Enable verbose logging
-bridge run --agent-command "gemini --experimental-acp" --verbose
+bridge run --verbose
 
 # Check which transports are configured
 bridge status
 
 # Test agent command independently
-echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | gemini --experimental-acp
+echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | copilot --acp
+```
+
+### Testing with Other ACP-Compatible Agents
+
+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
 ```
 
 ---
@@ -287,19 +306,17 @@ echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | gemini --experimental-ac
 - **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.
 
 To rotate credentials (invalidates all paired devices):
 
 ```bash
-# Using aptove run (embedded bridge):
-rm ~/Library/Application\ Support/Aptove/common.toml   # macOS
-rm ~/.config/Aptove/common.toml                        # Linux
-aptove run --qr
-
-# Using standalone bridge binary:
-rm ~/Library/Application\ Support/com.aptove.bridge/common.toml   # macOS
-rm ~/.config/bridge/common.toml                                    # Linux
-bridge run --agent-command "aptove stdio" --qr
+# macOS
+rm ~/Library/Application\ Support/com.aptove.bridge/common.toml
+# Linux
+rm ~/.config/bridge/common.toml
+
+bridge
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aptove/bridge",
-  "version": "0.1.18",
+  "version": "0.2.0",
   "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.1.18",
-    "@aptove/bridge-darwin-x64": "0.1.18",
-    "@aptove/bridge-linux-arm64": "0.1.18",
-    "@aptove/bridge-linux-x64": "0.1.18",
-    "@aptove/bridge-win32-x64": "0.1.18"
+    "@aptove/bridge-darwin-arm64": "0.2.0",
+    "@aptove/bridge-darwin-x64": "0.2.0",
+    "@aptove/bridge-linux-arm64": "0.2.0",
+    "@aptove/bridge-linux-x64": "0.2.0",
+    "@aptove/bridge-win32-x64": "0.2.0"
   }
 }