agentpal 0.1.0 → 0.1.1

package/Cargo.toml

@@ -9,7 +9,7 @@ members = [
 [workspace.package]
 edition = "2024"
 license = "MIT"
-version = "0.1.0"
+version = "0.1.1"
 
 [workspace.dependencies]
 agentpal-protocol = { path = "crates/protocol" }
@@ -21,9 +21,10 @@ local-ip-address = "0.6.13"
 qrcode = { version = "0.14.1", default-features = false }
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.145"
+rustls = { version = "0.23.37", default-features = false, features = ["ring", "std", "tls12"] }
 time = { version = "0.3.44", features = ["serde", "formatting", "macros", "parsing"] }
 tokio = { version = "1.48.0", features = ["macros", "net", "process", "rt-multi-thread", "signal", "sync", "time"] }
-tokio-tungstenite = "0.29.0"
+tokio-tungstenite = { version = "0.29.0", features = ["rustls-tls-webpki-roots"] }
 tracing = "0.1.41"
 tracing-subscriber = { version = "0.3.22", features = ["env-filter"] }
 url = "2.5.7"

package/README.md

@@ -1,43 +1,147 @@
 # AgentPal
 
-AgentPal connects a local coding-agent host to the AgentPal mobile app through a Cloud Relay pairing flow.
+**Your coding agents keep working. You keep control.**
 
-This first npm release is a source-based CLI package: it runs the packaged Rust host and relay through `cargo run`.
+AgentPal is a pocket control surface for coding agents running on your own machine. Pair your phone with a local Codex host, step away from the desk, and stay close enough to review progress, catch blockers, and send the next instruction.
 
-## Install
+```bash
+npx agentpal@latest pair
+```
+
+AgentPal is not a remote desktop, not a phone terminal, and not another AI chat box. Your computer remains the place where code is read, edited, tested, and committed. Your phone becomes the place where you keep the work visible and steer it when attention is needed.
+
+## Why
+
+Long-running coding agents are useful because they can keep moving while you are not staring at the terminal. They are also useful only if you can stay in the loop:
+
+- a command needs approval;
+- a diff needs a quick review;
+- a task gets blocked and needs a nudge;
+- a session finishes while you are away;
+- you want to send one short follow-up without reopening your laptop.
 
-Run without installing:
+AgentPal is built for that gap between "the agent is running" and "I still need to be responsible for what it does."
+
+## Start Here
+
+Run this from the project directory on the computer where Codex is available:
 
 ```bash
 npx agentpal@latest pair
 ```
 
-Or install globally:
+The command starts the AgentPal host, creates a Cloud Relay pairing, and prints a pairing URL plus QR code for the mobile app.
+
+You can also install the CLI globally:
 
 ```bash
 npm install -g agentpal
 agentpal pair
 ```
 
+To pair a different workspace:
+
+```bash
+agentpal pair --workspace /path/to/project
+```
+
+## What Works Today
+
+AgentPal `0.1.x` is the first public release line of the desktop/CLI side:
+
+- public npm package: `agentpal`;
+- one-command pairing entry: `npx agentpal@latest pair`;
+- Cloud Relay pairing flow;
+- local Codex host bridge;
+- QR/link pairing payloads;
+- workspace-aware host startup;
+- local relay command for development and advanced setups.
+
+The mobile app and broader agent adapters are still evolving. This release is intended to make the public pairing path installable and testable.
+
+## How It Works
+
+```text
+Phone app  <->  Cloud Relay  <->  AgentPal Host  <->  Codex CLI
+                                      |
+                                      v
+                                your workspace
+```
+
+The host runs on your computer and talks to the local coding-agent process. The relay helps your phone and host find each other when they are not on the same network. Your repository stays on your machine; the phone is a control and review surface, not the execution environment.
+
 ## Commands
 
 ```bash
 agentpal pair
 agentpal pair --workspace .
+agentpal pair --workspace . --relay-url ws://127.0.0.1:8790/ws
+
 agentpal relay --host 0.0.0.0 --port 8790
 agentpal host codex connect --workspace .
 ```
 
-`agentpal pair` uses the current directory as the default workspace and the public Cloud Relay by default. For local development, pass a local Relay URL:
+`agentpal pair` uses the current directory as the default workspace and the public Cloud Relay unless you pass `--relay-url` or set `AGENTPAL_RELAY_URL`.
+
+## Requirements
+
+The current npm package is source-based. It installs a Node.js wrapper and runs the packaged Rust host/relay through `cargo run`.
+
+You need:
+
+- Node.js 18 or newer;
+- Rust toolchain with `cargo`;
+- Codex CLI available as `codex` for live host sessions.
+
+Prebuilt binaries are planned, but they are not part of the `0.1.x` release line.
+
+## Security Model
+
+AgentPal is designed around local execution:
+
+- your code stays in your workspace on your computer;
+- the host launches and supervises the local coding agent;
+- the relay forwards pairing and realtime messages;
+- the phone sends control intent and receives structured session state.
+
+Do not treat the current public relay as a private enterprise deployment boundary. For sensitive work, run your own relay or wait for hardened deployment guidance.
+
+## Development
+
+Run the CLI from source:
 
 ```bash
-agentpal pair --workspace . --relay-url ws://127.0.0.1:8790/ws
+npm run agentpal -- --help
+npm run agentpal -- pair --workspace .
 ```
 
-## Requirements
+Run a local relay:
+
+```bash
+cargo run -p agentpal-relay -- --host 0.0.0.0 --port 8790
+```
+
+Check the Rust workspace:
+
+```bash
+cargo fmt --check
+cargo check --workspace
+cargo test -p agentpal-relay
+```
+
+Mobile app code lives under `apps/mobile`. Host, relay, and protocol crates live under `crates/`.
+
+## Roadmap
+
+Near-term work:
+
+- mobile pairing and session UX hardening;
+- prebuilt CLI binaries so users do not need Rust;
+- more complete Codex session controls;
+- Claude Code and other adapter paths;
+- self-hosted relay deployment guide;
+- stronger auth, device trust, and production relay hardening.
 
-- Node.js
-- Rust toolchain with `cargo`
-- Codex CLI available as `codex` for live host sessions
+## Status
 
-The npm package currently builds and runs the Rust host/relay from source through `cargo run`.
+AgentPal is early. The public npm package is live, but the product surface is still being shaped. Expect sharp edges, fast iteration, and honest limits.

package/crates/host/Cargo.toml

@@ -11,6 +11,7 @@ clap.workspace = true
 futures-util.workspace = true
 local-ip-address.workspace = true
 qrcode.workspace = true
+rustls.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 time.workspace = true

package/crates/host/src/codex.rs

@@ -1,9 +1,10 @@
 use std::{
-    collections::{HashMap, HashSet},
-    env,
-    path::{Path, PathBuf},
-    process::Stdio,
-    sync::Arc,
+    collections::{HashMap, HashSet},
+    env,
+    io::{self, Write},
+    path::{Path, PathBuf},
+    process::Stdio,
+    sync::Arc,
     time::{Duration, Instant},
 };
 
@@ -15,7 +16,10 @@ use agentpal_protocol::{
     RiskLevel, SessionEvent, SessionState, SessionSummary, WorkspaceSnapshot, WorktreeSummary,
 };
 use clap::Args;
-use futures_util::{SinkExt, StreamExt, stream::SplitSink};
+use futures_util::{
+    SinkExt, StreamExt,
+    stream::{SplitSink, SplitStream},
+};
 use local_ip_address::local_ip;
 use qrcode::{QrCode, render::unicode};
 use serde::{Deserialize, Serialize};
@@ -396,26 +400,17 @@ async fn run_connect_loop(
     codex_version: Option<String>,
     codex_websocket_url: &str,
 ) -> anyhow::Result<()> {
-    tokio::time::sleep(Duration::from_millis(600)).await;
-    let relay_url = normalize_ws_url(&args.relay_url);
-    let (relay_socket, _) = connect_async(relay_url.as_str()).await?;
-    let (codex_socket, _) = connect_async(codex_websocket_url).await?;
-    let (relay_write, mut relay_read) = relay_socket.split();
-    let (codex_write, codex_read) = codex_socket.split();
-    let relay_write = Arc::new(Mutex::new(relay_write));
-    let codex_write = Arc::new(Mutex::new(codex_write));
-    let (codex_tx, mut codex_rx) = mpsc::unbounded_channel::<Value>();
-    let host_id = args.host_id.clone().unwrap_or_else(default_host_id);
-    let session_id = args.session_id.clone();
-    let workspace_owned = workspace.to_owned();
-    let thread_ids = Arc::new(Mutex::new(HashMap::<String, String>::new()));
-    let pending_thread_starts = Arc::new(Mutex::new(HashMap::<u64, String>::new()));
-    let pending_thread_loads = Arc::new(Mutex::new(HashMap::<u64, String>::new()));
-    let picker_items = Arc::new(Mutex::new(default_picker_items()));
-    let seq = Arc::new(Mutex::new(0_u64));
-
-    relay_send(
-        &relay_write,
+    tokio::time::sleep(Duration::from_millis(600)).await;
+    let relay_url = normalize_ws_url(&args.relay_url);
+    let (relay_socket, _) = connect_async(relay_url.as_str()).await?;
+    let (relay_write, mut relay_read) = relay_socket.split();
+    let relay_write = Arc::new(Mutex::new(relay_write));
+    let host_id = args.host_id.clone().unwrap_or_else(default_host_id);
+    let session_id = args.session_id.clone();
+    let workspace_owned = workspace.to_owned();
+
+    relay_send(
+        &relay_write,
         &RelayClientMessage::Register {
             role: RelayClientRole::Host,
             client_id: format!("{host_id}-host"),
@@ -442,11 +437,23 @@ async fn run_connect_loop(
                     pair_token: None,
                     expires_in_seconds,
                 },
-            },
-        )
-        .await?;
-    }
-    publish_host_status(&relay_write, &host_id, host_name, workspace, 1).await?;
+            },
+        )
+        .await?;
+        print_pairing_response(&mut relay_read, &host_id, args.no_qr).await?;
+    }
+
+    let (codex_socket, _) = connect_async(codex_websocket_url).await?;
+    let (codex_write, codex_read) = codex_socket.split();
+    let codex_write = Arc::new(Mutex::new(codex_write));
+    let (codex_tx, mut codex_rx) = mpsc::unbounded_channel::<Value>();
+    let thread_ids = Arc::new(Mutex::new(HashMap::<String, String>::new()));
+    let pending_thread_starts = Arc::new(Mutex::new(HashMap::<u64, String>::new()));
+    let pending_thread_loads = Arc::new(Mutex::new(HashMap::<u64, String>::new()));
+    let picker_items = Arc::new(Mutex::new(default_picker_items()));
+    let seq = Arc::new(Mutex::new(0_u64));
+
+    publish_host_status(&relay_write, &host_id, host_name, workspace, 1).await?;
 
     send_codex_initialize(&codex_write).await?;
     request_codex_picker_sources(&codex_write, &seq, workspace).await?;
@@ -726,12 +733,45 @@ async fn run_connect_loop(
     if let Some(version) = codex_version {
         eprintln!("Codex connected through AgentPal Host ({version})");
     }
-    Ok(())
-}
-
-fn relay_task_result(
-    result: Result<anyhow::Result<()>, tokio::task::JoinError>,
-) -> anyhow::Result<()> {
+    Ok(())
+}
+
+async fn print_pairing_response(
+    relay_read: &mut SplitStream<WebSocketStream<MaybeTlsStream<TcpStream>>>,
+    host_id: &str,
+    no_qr: bool,
+) -> anyhow::Result<()> {
+    while let Some(message) = relay_read.next().await {
+        let message = message?;
+        match message {
+            Message::Text(text) => {
+                let server_message: RelayServerMessage = serde_json::from_str(&text)?;
+                match server_message {
+                    RelayServerMessage::PairCreated { pairing } => {
+                        if pairing.host_id == host_id {
+                            print_pairing_payload(&pairing, no_qr)?;
+                            return Ok(());
+                        }
+                    }
+                    RelayServerMessage::Error { message } => {
+                        anyhow::bail!("AgentPal Relay error: {message}");
+                    }
+                    _ => {}
+                }
+            }
+            Message::Close(frame) => {
+                anyhow::bail!("relay websocket closed before pair response: {frame:?}");
+            }
+            Message::Binary(_) | Message::Ping(_) | Message::Pong(_) | Message::Frame(_) => {}
+        }
+    }
+
+    anyhow::bail!("relay websocket ended before pair response");
+}
+
+fn relay_task_result(
+    result: Result<anyhow::Result<()>, tokio::task::JoinError>,
+) -> anyhow::Result<()> {
     match result {
         Ok(Ok(())) => Ok(()),
         Ok(Err(error)) => Err(error),
@@ -2327,12 +2367,14 @@ fn print_pairing_payload(payload: &PairingPayload, no_qr: bool) -> anyhow::Resul
             .quiet_zone(true)
             .module_dimensions(2, 1)
             .build();
-        println!();
-        println!("{qr}");
-    }
-
-    Ok(())
-}
+        println!();
+        println!("{qr}");
+    }
+
+    io::stdout().flush()?;
+
+    Ok(())
+}
 
 fn pair_url(payload: &PairingPayload) -> String {
     let mut url = url::Url::parse("agentpal://pair").expect("static pair url parses");

package/crates/host/src/main.rs

@@ -32,6 +32,8 @@ enum CodexSubcommand {
 
 #[tokio::main]
 async fn main() -> Result<()> {
+    let _ = rustls::crypto::ring::default_provider().install_default();
+
     let cli = Cli::parse();
 
     match cli.command {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentpal",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AgentPal CLI for pairing local coding agents with the AgentPal mobile app.",
   "license": "MIT",
   "keywords": [