feat(acp): browser control via MCP-over-ACP + stdio bridge (Phase 2)

.dockerignore

@@ -0,0 +1,4 @@
+target/
+.git/
+data/
+*.tgz

Cargo.toml

@@ -51,7 +51,7 @@ feishu = ["dep:openab-gateway", "dep:axum", "openab-gateway/feishu"]
 googlechat = ["dep:openab-gateway", "dep:axum", "openab-gateway/googlechat"]
 wecom = ["dep:openab-gateway", "dep:axum", "openab-gateway/wecom"]
 teams = ["dep:openab-gateway", "dep:axum", "openab-gateway/teams"]
-acp = ["dep:openab-gateway", "dep:axum", "openab-gateway/acp"]
+acp = ["dep:openab-gateway", "dep:axum", "openab-gateway/acp", "openab-core/acp-mcp"]
 
 [dev-dependencies]
 tempfile = "3.27.0"

crates/openab-core/Cargo.toml

@@ -49,6 +49,13 @@ aws-credential-types = { version = "1", optional = true }
 urlencoding = { version = "2", optional = true }
 hex = { version = "0.4", optional = true }
 http = { version = "1", optional = true }
+# MCP proxy server (browser-control, feature `acp-mcp`): core hosts an in-process
+# Streamable-HTTP MCP server the colocated agent connects to (D3). rmcp server + a
+# self-owned loopback axum listener; kept optional so non-acp builds don't pull them.
+rmcp = { version = "1.7", default-features = false, features = ["server", "transport-streamable-http-server"], optional = true }
+axum = { version = "0.8", optional = true }
+tokio-util = { version = "0.7", optional = true }
+subtle = { version = "2", optional = true } # constant-time bearer compare for the loopback MCP server
 
 [target.'cfg(unix)'.dependencies]
 libc = "0.2"
@@ -65,3 +72,5 @@ config-s3 = ["dep:aws-sdk-s3", "dep:aws-config"]
 pre-seed = ["dep:aws-sdk-s3", "dep:aws-config", "dep:zip", "dep:hex", "dep:flate2", "dep:tar"]
 filestore = ["dep:aws-sdk-s3", "dep:aws-config"]
 agentcore = ["dep:aws-config", "dep:aws-sigv4", "dep:aws-credential-types", "dep:urlencoding", "dep:hex", "dep:http", "dep:rustls", "dep:tokio-rustls", "dep:webpki-roots"]
+# Core-hosted MCP proxy server for MCP-over-ACP browser control (enabled by the root `acp`).
+acp-mcp = ["dep:rmcp", "dep:axum", "dep:tokio-util", "dep:subtle"]

crates/openab-core/src/acp/connection.rs

@@ -189,6 +189,11 @@ pub struct AcpConnection {
     pub session_reset: bool,
     _reader_handle: JoinHandle<()>,
     _stderr_handle: Option<JoinHandle<()>>,
+    /// Cancels this session's per-session MCP proxy server (D5-a) when the connection is
+    /// dropped. Held only for its `Drop` side effect (never read).
+    #[cfg(feature = "acp-mcp")]
+    #[allow(dead_code)]
+    mcp_server_guard: Option<tokio_util::sync::DropGuard>,
 }
 
 /// Build the final set of env vars for the agent subprocess.
@@ -331,6 +336,7 @@ impl AcpConnection {
         working_dir: &str,
         env: &std::collections::HashMap<String, String>,
         inherit_env: &[String],
+        browser_channel: Option<&str>,
     ) -> Result<Self> {
         info!(cmd = command, ?args, cwd = working_dir, "spawning agent");
 
@@ -397,6 +403,10 @@ impl AcpConnection {
                 cmd.env("SystemDrive", v);
             }
         }
+        // Option C: hand this session's browser channel to the agent so the `openab
+        // browser-bridge` stdio shim it later spawns inherits it and routes tool calls to THIS
+        // session's tunnel. env_clear() above dropped it, so (re)inject explicitly.
+        set_browser_channel(&mut cmd, browser_channel);
         for (k, v) in env {
             cmd.env(k, expand_env(v));
         }
@@ -485,9 +495,17 @@ impl AcpConnection {
             session_reset: false,
             _reader_handle: reader_handle,
             _stderr_handle: stderr_handle,
+            #[cfg(feature = "acp-mcp")]
+            mcp_server_guard: None,
         })
     }
 
+    /// Attach the guard that stops this session's MCP proxy server when the connection drops.
+    #[cfg(feature = "acp-mcp")]
+    pub fn set_mcp_guard(&mut self, guard: Option<tokio_util::sync::DropGuard>) {
+        self.mcp_server_guard = guard;
+    }
+
     fn next_id(&self) -> u64 {
         self.next_id.fetch_add(1, Ordering::Relaxed)
     }
@@ -834,11 +852,39 @@ impl Drop for AcpConnection {
     }
 }
 
+/// Inject the session's browser channel into the agent's env so the `openab browser-bridge`
+/// stdio shim the agent later spawns inherits it (Option C) and routes tool calls to THIS
+/// session's tunnel. No-op for non-browser sessions (`None`).
+fn set_browser_channel(cmd: &mut tokio::process::Command, browser_channel: Option<&str>) {
+    if let Some(channel) = browser_channel {
+        cmd.env("OPENAB_BROWSER_CHANNEL", channel);
+    }
+}
+
 #[cfg(test)]
 mod tests {
-    use super::{build_agent_env, build_permission_response, pick_best_option};
+    use super::{build_agent_env, build_permission_response, pick_best_option, set_browser_channel};
     use serde_json::json;
 
+    #[test]
+    fn set_browser_channel_injects_env_when_present() {
+        let mut cmd = tokio::process::Command::new("true");
+        set_browser_channel(&mut cmd, Some("acp_win1"));
+        assert!(cmd.as_std().get_envs().any(|(k, v)| {
+            k == "OPENAB_BROWSER_CHANNEL" && v == Some(std::ffi::OsStr::new("acp_win1"))
+        }));
+    }
+
+    #[test]
+    fn set_browser_channel_is_noop_when_absent() {
+        let mut cmd = tokio::process::Command::new("true");
+        set_browser_channel(&mut cmd, None);
+        assert!(!cmd
+            .as_std()
+            .get_envs()
+            .any(|(k, _)| k == "OPENAB_BROWSER_CHANNEL"));
+    }
+
     #[test]
     fn picks_allow_always_over_other_options() {
         let options = vec![

crates/openab-core/src/acp/pool.rs

@@ -53,6 +53,14 @@ pub struct SessionPool {
     mapping_path: PathBuf,
     meta_path: PathBuf,
     default_config_options: HashMap<String, String>,
+    /// Bridge from a session's core MCP proxy to its browser tunnel (D5-a/D6-a'); set by the
+    /// root. `None` = no browser wiring (tool calls report not-connected).
+    #[cfg(feature = "acp-mcp")]
+    browser_tunnel: Option<Arc<dyn crate::mcp_proxy::AcpMcpTunnel>>,
+    #[cfg(feature = "acp-mcp")]
+    session_registrar: Option<Arc<dyn crate::mcp_proxy::SessionTokenRegistrar>>,
+    #[cfg(feature = "acp-mcp")]
+    facade_url: Option<String>,
 }
 
 type CancelHandle = (Arc<tokio::sync::Mutex<tokio::process::ChildStdin>>, String);
@@ -197,9 +205,42 @@ impl SessionPool {
             mapping_path,
             meta_path,
             default_config_options,
+            #[cfg(feature = "acp-mcp")]
+            browser_tunnel: None,
+            #[cfg(feature = "acp-mcp")]
+            session_registrar: None,
+            #[cfg(feature = "acp-mcp")]
+            facade_url: None,
         }
     }
 
+    /// Wire the browser tunnel bridge (D6-a', set by the root) so per-session MCP proxies can
+    /// reach the browser. Call before sharing the pool.
+    #[cfg(feature = "acp-mcp")]
+    pub fn with_browser_tunnel(
+        mut self,
+        tunnel: Option<Arc<dyn crate::mcp_proxy::AcpMcpTunnel>>,
+    ) -> Self {
+        self.browser_tunnel = tunnel;
+        self
+    }
+
+    /// Wire the facade session-token registrar + facade URL (Facade mode,
+    /// set by the root when `[mcp]` is running). With both present, browser
+    /// capabilities route through the facade: the pool mints one token per
+    /// session, injects it as `OPENAB_SESSION_TOKEN` in the agent process
+    /// env, and writes the static facade MCP entry once per workdir.
+    #[cfg(feature = "acp-mcp")]
+    pub fn with_facade_sessions(
+        mut self,
+        registrar: Option<Arc<dyn crate::mcp_proxy::SessionTokenRegistrar>>,
+        facade_url: Option<String>,
+    ) -> Self {
+        self.session_registrar = registrar;
+        self.facade_url = facade_url;
+        self
+    }
+
     fn load_mapping(path: &Path) -> HashMap<String, String> {
         match std::fs::read_to_string(path) {
             Ok(data) => serde_json::from_str(&data).unwrap_or_else(|e| {
@@ -347,14 +388,106 @@ impl SessionPool {
             self.config.working_dir.clone()
         };
 
+        // Per-session MCP proxy (D5-a): for a browser (`acp:`) session, start a loopback MCP
+        // server + write `.cursor/mcp.json` BEFORE the agent boots so it connects to it. The
+        // returned guard cancels that server when this connection is dropped (any evict path).
+        // Facade mode: mint the per-session token (returned env var rides the
+        // agent spawn below) and write the static facade entry once. Falls
+        // back to Proxy mode when the root wired no registrar (no [mcp]).
+        #[cfg(feature = "acp-mcp")]
+        let mut session_token: Option<String> = None;
+        #[cfg(feature = "acp-mcp")]
+        let mcp_guard: Option<tokio_util::sync::DropGuard> =
+            if let Some(channel_id) = thread_id.strip_prefix("acp:") {
+                let mode = match crate::mcp_proxy::browser_mode() {
+                    crate::mcp_proxy::BrowserMode::Facade
+                        if self.session_registrar.is_none() || self.facade_url.is_none() =>
+                    {
+                        crate::mcp_proxy::BrowserMode::Proxy
+                    }
+                    m => m,
+                };
+                match mode {
+                    crate::mcp_proxy::BrowserMode::Facade => {
+                        // unwraps guarded by the fallback arm above
+                        let registrar = self.session_registrar.as_ref().unwrap();
+                        let facade_url = self.facade_url.as_ref().unwrap();
+                        if let Err(e) =
+                            crate::mcp_proxy::write_facade_mcp_config(&effective_workdir, facade_url)
+                                .await
+                        {
+                            warn!(thread_id, error = %e, "failed to write facade mcp config");
+                        }
+                        session_token = Some(registrar.mint(channel_id));
+                        info!(thread_id, "session token minted for facade browser capabilities");
+                        // Revoke on evict/replace: piggyback the same DropGuard
+                        // plumbing proxy mode uses for its server teardown.
+                        let ct = tokio_util::sync::CancellationToken::new();
+                        let child = ct.child_token();
+                        let registrar = registrar.clone();
+                        let chan = channel_id.to_string();
+                        tokio::spawn(async move {
+                            child.cancelled().await;
+                            registrar.revoke(&chan);
+                        });
+                        Some(ct.drop_guard())
+                    }
+                    // Bridge mode (Option C): the agent's static mcp.json points at `openab
+                    // browser-bridge`, which dials the pod-wide socket server (started at boot).
+                    // Just ensure the write-once config exists — no per-session server/guard.
+                    crate::mcp_proxy::BrowserMode::Bridge => {
+                        if let Err(e) =
+                            crate::mcp_proxy::write_bridge_mcp_config(&effective_workdir).await
+                        {
+                            warn!(thread_id, error = %e, "failed to write bridge mcp config");
+                        }
+                        None
+                    }
+                    // Proxy mode (default): per-session loopback HTTP MCP server + dynamic config.
+                    crate::mcp_proxy::BrowserMode::Proxy => {
+                        match crate::mcp_proxy::start_session_server(
+                            channel_id,
+                            &effective_workdir,
+                            self.browser_tunnel.clone(),
+                        )
+                        .await
+                        {
+                            Ok((addr, ct)) => {
+                                info!(thread_id, %addr, "started per-session MCP proxy server");
+                                Some(ct.drop_guard())
+                            }
+                            Err(e) => {
+                                warn!(thread_id, error = %e, "failed to start MCP proxy; browser tools unavailable");
+                                None
+                            }
+                        }
+                    }
+                }
+            } else {
+                None
+            };
+
         // Build the replacement connection outside the state lock so one stuck
         // initialization does not block all unrelated sessions.
+        #[cfg(feature = "acp-mcp")]
+        let spawn_env: std::collections::HashMap<String, String> = {
+            let mut env = self.config.env.clone();
+            if let Some(tok) = &session_token {
+                // The static facade MCP entry references ${OPENAB_SESSION_TOKEN};
+                // the value lives only in this agent process's environment.
+                env.insert("OPENAB_SESSION_TOKEN".to_string(), tok.clone());
+            }
+            env
+        };
+        #[cfg(not(feature = "acp-mcp"))]
+        let spawn_env = self.config.env.clone();
         let mut new_conn = AcpConnection::spawn(
             &self.config.command,
             &self.config.args,
             &effective_workdir,
-            &self.config.env,
+            &spawn_env,
             &self.config.inherit_env,
+            thread_id.strip_prefix("acp:"),
         )
         .await?;
 
@@ -423,6 +556,8 @@ impl SessionPool {
         let activity_handle = new_conn.activity_handle();
         let child_pgid = new_conn.child_pgid();
         let cancel_session_id = new_conn.acp_session_id.clone().unwrap_or_default();
+        #[cfg(feature = "acp-mcp")]
+        new_conn.set_mcp_guard(mcp_guard);
         let new_conn = Arc::new(Mutex::new(new_conn));
 
         let mut state = self.state.write().await;

crates/openab-core/src/lib.rs

@@ -1,5 +1,7 @@
 pub mod acp;
 pub mod adapter;
+#[cfg(feature = "acp-mcp")]
+pub mod mcp_proxy;
 pub mod bot_turns;
 pub mod config;
 pub mod cron;