@corbet-labs/ccht 0.2.2 → 0.2.3

package/source/src/native/mod.rs

@@ -0,0 +1,257 @@
+//! Native ACP sessions driven by the upstream Apache-2.0 Rust SDK.
+//!
+//! The SDK owns process spawning, protocol dispatch, session routing, and process
+//! cleanup. Applications own agent installation, subscription login, workspace
+//! isolation, and authorization policy. Denying permission requests is not a
+//! sandbox: an agent can have tools that do not ask the client for permission.
+
+mod client;
+pub mod drivers;
+mod env;
+pub mod pool;
+mod session;
+
+#[cfg(test)]
+mod tests;
+
+pub use client::NativeClient;
+pub use env::EnvProfile;
+pub use pool::{PoolEvent, SessionKey, SessionPool};
+pub use session::{NativeSession, SessionHandle};
+
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+use std::time::Duration;
+
+use crate::acp::{McpServer, RequestPermissionOutcome};
+
+/// An explicitly installed ACP executable; no implicit shell or installer is used.
+#[derive(Clone)]
+pub struct AgentCommand {
+    /// Executable path or name resolved by the operating system.
+    pub program: PathBuf,
+    /// Arguments passed directly to the executable.
+    pub args: Vec<String>,
+    /// Additional child environment. Values are excluded from debug output.
+    pub env: BTreeMap<String, String>,
+}
+
+impl AgentCommand {
+    /// Select an existing executable without arguments or environment overrides.
+    pub fn new(program: impl Into<PathBuf>) -> Self {
+        Self {
+            program: program.into(),
+            args: Vec::new(),
+            env: BTreeMap::new(),
+        }
+    }
+
+    /// Set arguments without shell parsing.
+    pub fn args(mut self, args: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.args = args.into_iter().map(Into::into).collect();
+        self
+    }
+
+    /// Start in a directory through an installed Linux or macOS `env` launcher.
+    ///
+    /// This changes the process startup directory, independently of ACP session
+    /// `cwd`. The SDK still owns the process and its cleanup. Linux resolves
+    /// `env` through the caller's PATH and requires GNU `--chdir`; macOS uses
+    /// `/usr/bin/env -C`. An unsupported launcher fails before executing the
+    /// agent. No shell parsing is involved. Windows has no implementation here.
+    pub fn with_working_directory(self, cwd: impl AsRef<std::path::Path>) -> Result<Self> {
+        if !cfg!(any(target_os = "linux", target_os = "macos")) {
+            return Err(NativeError::Unsupported(
+                "a startup-directory launcher on this platform",
+            ));
+        }
+        let cwd = cwd.as_ref();
+        if !cwd.is_absolute() || !cwd.is_dir() {
+            return Err(NativeError::InvalidOptions(
+                "startup cwd must be an existing absolute directory",
+            ));
+        }
+        let directory = cwd
+            .to_str()
+            .ok_or(NativeError::InvalidOptions("startup cwd must be UTF-8"))?;
+        let program = self
+            .program
+            .to_str()
+            .ok_or(NativeError::InvalidOptions("executable must be UTF-8"))?;
+        let (launcher, mut args) = if cfg!(target_os = "macos") {
+            (
+                "/usr/bin/env",
+                vec!["-C".into(), directory.into(), "--".into(), program.into()],
+            )
+        } else {
+            (
+                "env",
+                vec![format!("--chdir={directory}"), "--".into(), program.into()],
+            )
+        };
+        args.extend(self.args);
+        Ok(Self {
+            program: launcher.into(),
+            args,
+            env: self.env,
+        })
+    }
+}
+
+impl std::fmt::Debug for AgentCommand {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("AgentCommand")
+            .field("program", &self.program)
+            .field("argument_count", &self.args.len())
+            .field("environment_keys", &self.env.keys().collect::<Vec<_>>())
+            .finish()
+    }
+}
+
+/// How requests that reach the client are handled; this does not sandbox an agent.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum PermissionPolicy {
+    /// Cancel every permission request without granting authority.
+    #[default]
+    Deny,
+    /// Emit a permission event and await an explicit, valid response.
+    Ask,
+}
+
+/// A permission response uses ACP's exact selected-option or cancellation type.
+pub type PermissionDecision = RequestPermissionOutcome;
+
+/// Resource limits and permission policy for a native connection.
+#[derive(Debug, Clone)]
+pub struct NativeOptions {
+    /// Limit for initialization, session creation/restoration, and configuration.
+    pub operation_timeout: Duration,
+    /// Maximum duration of a prompt, including permission waits.
+    pub prompt_timeout: Duration,
+    /// Maximum time an unanswered permission request may remain pending.
+    pub permission_timeout: Duration,
+    /// Grace period for cancellation and SDK connection shutdown.
+    pub shutdown_timeout: Duration,
+    /// Maximum queued application events per session.
+    pub event_capacity: usize,
+    /// Policy applied to every incoming permission request.
+    pub permissions: PermissionPolicy,
+}
+
+impl Default for NativeOptions {
+    fn default() -> Self {
+        Self {
+            operation_timeout: Duration::from_secs(30),
+            prompt_timeout: Duration::from_secs(600),
+            permission_timeout: Duration::from_secs(120),
+            shutdown_timeout: Duration::from_secs(5),
+            event_capacity: 256,
+            permissions: PermissionPolicy::Deny,
+        }
+    }
+}
+
+/// Application-owned workspace and optional agent session configuration.
+#[derive(Debug, Clone)]
+pub struct SessionOptions {
+    /// Absolute existing directory supplied to the agent; not an isolation boundary.
+    pub cwd: PathBuf,
+    /// Exact advertised model option value, or the agent's default when absent.
+    pub model: Option<String>,
+    /// Agent-advertised configuration values, applied in order after model selection.
+    pub configuration: Vec<(String, crate::acp::SessionConfigOptionValue)>,
+    /// Application-owned MCP server descriptors passed to the agent.
+    pub mcp_servers: Vec<McpServer>,
+}
+
+impl SessionOptions {
+    /// Use an explicit workspace and the agent's default model without MCP servers.
+    pub fn new(cwd: impl Into<PathBuf>) -> Self {
+        Self {
+            cwd: cwd.into(),
+            model: None,
+            configuration: Vec::new(),
+            mcp_servers: Vec::new(),
+        }
+    }
+}
+
+/// Native errors deliberately exclude raw agent messages, stderr, and error data.
+#[derive(Debug, Clone, thiserror::Error, PartialEq, Eq)]
+pub enum NativeError {
+    /// A Tokio runtime is required to drive the connection.
+    #[error("a Tokio runtime is required for native ACP sessions")]
+    RuntimeUnavailable,
+    /// Configuration is incomplete or inconsistent.
+    #[error("invalid native configuration: {0}")]
+    InvalidOptions(&'static str),
+    /// The operation exceeded its configured deadline.
+    #[error("native ACP operation timed out")]
+    Timeout,
+    /// The connection or session has closed.
+    #[error("native ACP connection or session is closed")]
+    Closed,
+    /// A session already has an active prompt.
+    #[error("this session already has an active prompt")]
+    Busy,
+    /// The agent did not advertise the requested operation or content type.
+    #[error("the agent does not support {0}")]
+    Unsupported(&'static str),
+    /// Agent-owned authentication is required; no alternate billing path is tried.
+    #[error("authenticate using the selected agent's native login, then reconnect")]
+    AuthenticationRequired,
+    /// A protocol error code, without possibly sensitive server text or data.
+    #[error("the agent returned ACP error {0}")]
+    Protocol(i32),
+    /// An application failed to keep up with the bounded event stream.
+    #[error("session event buffer is full; the connection was closed")]
+    EventBufferFull,
+    /// The session's sole event receiver has already been taken.
+    #[error("the session event stream has already been taken")]
+    EventsTaken,
+    /// No pending permission request has the supplied identifier.
+    #[error("permission request is absent, expired, or already answered")]
+    UnknownPermission,
+    /// A selected permission option was not offered by the agent.
+    #[error("the selected permission option was not offered")]
+    InvalidPermissionOption,
+}
+
+impl NativeError {
+    /// Stable category suitable for a product's structured error event.
+    pub fn code(&self) -> &'static str {
+        match self {
+            Self::RuntimeUnavailable => "runtime_unavailable",
+            Self::InvalidOptions(_) => "invalid_options",
+            Self::Timeout => "timeout",
+            Self::Closed => "closed",
+            Self::Busy => "busy",
+            Self::Unsupported(_) => "unsupported",
+            Self::AuthenticationRequired => "authentication_required",
+            Self::Protocol(_) => "protocol",
+            Self::EventBufferFull => "event_buffer_full",
+            Self::EventsTaken => "events_taken",
+            Self::UnknownPermission => "unknown_permission",
+            Self::InvalidPermissionOption => "invalid_permission_option",
+        }
+    }
+}
+
+impl From<agent_client_protocol::Error> for NativeError {
+    fn from(error: agent_client_protocol::Error) -> Self {
+        if error.code == crate::acp::ErrorCode::AuthRequired {
+            Self::AuthenticationRequired
+        } else {
+            Self::Protocol(error.code.into())
+        }
+    }
+}
+
+/// Result returned by native ACP operations.
+pub type Result<T> = std::result::Result<T, NativeError>;
+
+fn lock<T>(mutex: &std::sync::Mutex<T>) -> std::sync::MutexGuard<'_, T> {
+    mutex
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}

package/source/src/native/pool.rs

@@ -0,0 +1,440 @@
+//! Keyed pool of native agent sessions sharing one client.
+//!
+//! Workspaces, projects or roles map to pool keys; each key owns exactly one
+//! session, created lazily on first use. Turns in different keys run in
+//! parallel automatically, while each key serializes its own turns. Events
+//! arrive tagged so late answers still land where they were asked.
+//!
+//! The pool owns session mechanics only: applications own prompts, permission
+//! decisions, display and storage, and read conversation snapshots back for
+//! replay or persistence.
+
+use std::collections::HashMap;
+
+use tokio::sync::mpsc;
+
+use super::{
+    AgentCommand, NativeClient, NativeError, NativeOptions, SessionHandle, SessionOptions,
+};
+use crate::{Conversation, SessionEvent, WireEvent};
+
+/// Application-chosen session key: a workspace, project or role name.
+pub type SessionKey = String;
+
+/// Streamed pool activity. Raw session events keep their full detail; the
+/// application maps them to display, storage and permission decisions.
+#[derive(Debug)]
+pub enum PoolEvent {
+    /// A session event, tagged with its key.
+    Session {
+        /// Application-chosen session key.
+        key: SessionKey,
+        /// Raw session event with full detail (boxed: the common case
+        /// dwarfs the terminal variant).
+        event: Box<SessionEvent>,
+    },
+    /// The forwarder for a removed session drained. No further events follow.
+    Ended {
+        /// Application-chosen session key.
+        key: SessionKey,
+    },
+}
+
+struct Session {
+    handle: SessionHandle,
+    conv: Conversation,
+    busy: bool,
+    seq: u64,
+}
+
+struct Inner {
+    client: Option<NativeClient>,
+    sessions: HashMap<SessionKey, Session>,
+    app_events: mpsc::UnboundedSender<PoolEvent>,
+    fwd: Option<mpsc::UnboundedSender<(SessionKey, Option<SessionEvent>)>>,
+}
+
+/// Keyed native sessions over one shared client connection.
+#[derive(Clone)]
+pub struct SessionPool {
+    inner: std::sync::Arc<tokio::sync::Mutex<Inner>>,
+}
+
+impl SessionPool {
+    /// Connect the shared client and return the pool plus its event stream.
+    /// A failed connection still returns a pool: every operation then
+    /// reports the outage instead of panicking, so applications degrade
+    /// gracefully (e.g. keep local tools working while the agent is down).
+    pub async fn connect(
+        command: AgentCommand,
+        options: NativeOptions,
+    ) -> (Self, mpsc::UnboundedReceiver<PoolEvent>) {
+        let (app_tx, app_rx) = mpsc::unbounded_channel();
+        let (fwd_tx, fwd_rx) = mpsc::unbounded_channel::<(SessionKey, Option<SessionEvent>)>();
+        let client = NativeClient::connect(command, options).await.ok();
+        let pool = Self {
+            inner: std::sync::Arc::new(tokio::sync::Mutex::new(Inner {
+                client,
+                sessions: HashMap::new(),
+                app_events: app_tx,
+                fwd: Some(fwd_tx),
+            })),
+        };
+        let router = pool.clone();
+        tokio::spawn(async move {
+            Self::route(router, fwd_rx).await;
+        });
+        (pool, app_rx)
+    }
+
+    /// Send a prompt to a key's session, creating it from `new` on first
+    /// use. Resolves when the turn ends; stream events (including the
+    /// terminal `Completed`) arrive separately, tagged with the key.
+    /// A second prompt while the key is busy fails with [`NativeError::Busy`].
+    pub async fn prompt(
+        &self,
+        key: &str,
+        new: SessionOptions,
+        text: String,
+    ) -> Result<(), NativeError> {
+        let handle = {
+            let mut inner = self.inner.lock().await;
+            Self::ensure(&mut inner, key, new).await?;
+            let session = inner.sessions.get_mut(key).expect("just ensured");
+            if session.busy {
+                return Err(NativeError::Busy);
+            }
+            session.busy = true;
+            session.handle.clone()
+        };
+        let request_id = format!("ccht-pool-{key}");
+        let result = handle.prompt(crate::Prompt::text(request_id, text)).await;
+        // Busy clears on the terminal stream event; a failed call has none,
+        // so release the slot here to avoid wedging the key.
+        if result.is_err()
+            && let Some(session) = self.inner.lock().await.sessions.get_mut(key)
+        {
+            session.busy = false;
+        }
+        result.map(|_| ())
+    }
+
+    /// Cancel the active turn of one key. Missing keys are a no-op success.
+    pub async fn cancel(&self, key: &str) -> Result<(), NativeError> {
+        let handle = {
+            let inner = self.inner.lock().await;
+            match inner.sessions.get(key) {
+                Some(session) => session.handle.clone(),
+                None => return Ok(()),
+            }
+        };
+        handle.cancel().await
+    }
+
+    /// Switch the model of an existing session, reporting the agent's
+    /// resulting configuration. Unknown keys fail without creating sessions:
+    /// model selection needs no session of its own.
+    pub async fn set_model(
+        &self,
+        key: &str,
+        model: &str,
+    ) -> Result<crate::SessionConfiguration, NativeError> {
+        let handle = {
+            let inner = self.inner.lock().await;
+            match inner.sessions.get(key) {
+                Some(session) => session.handle.clone(),
+                None => return Err(NativeError::Closed),
+            }
+        };
+        handle.set_model(model).await
+    }
+
+    /// Answer a pending permission request of one key's session.
+    pub async fn respond_permission(
+        &self,
+        key: &str,
+        request_id: &str,
+        decision: crate::acp::RequestPermissionOutcome,
+    ) -> Result<(), NativeError> {
+        let handle = {
+            let inner = self.inner.lock().await;
+            match inner.sessions.get(key) {
+                Some(session) => session.handle.clone(),
+                None => return Err(NativeError::Closed),
+            }
+        };
+        handle.respond_permission(request_id, decision).await
+    }
+
+    /// Drop one key's session and end it agent-side. Unknown keys are a no-op.
+    pub async fn close(&self, key: &str) {
+        let handle = {
+            let mut inner = self.inner.lock().await;
+            inner.sessions.remove(key).map(|s| s.handle)
+        };
+        if let Some(handle) = handle {
+            let _ = handle.close().await;
+        }
+    }
+
+    /// Whether the key holds a live session with a turn in flight.
+    pub async fn is_busy(&self, key: &str) -> bool {
+        self.inner
+            .lock()
+            .await
+            .sessions
+            .get(key)
+            .is_some_and(|s| s.busy)
+    }
+
+    /// Whether the key holds a live session at all.
+    pub async fn has_session(&self, key: &str) -> bool {
+        self.inner.lock().await.sessions.contains_key(key)
+    }
+
+    /// A snapshot of one key's conversation for replay or persistence.
+    /// Applications own storage; the pool only lends the state.
+    pub async fn conversation(&self, key: &str) -> Option<Conversation> {
+        self.inner
+            .lock()
+            .await
+            .sessions
+            .get(key)
+            .map(|s| s.conv.clone())
+    }
+
+    /// Shut every session down and close the shared client.
+    pub async fn shutdown(&self) {
+        let mut inner = self.inner.lock().await;
+        let keys: Vec<String> = inner.sessions.keys().cloned().collect();
+        for key in keys {
+            if let Some(session) = inner.sessions.remove(&key) {
+                let _ = session.handle.close().await;
+            }
+        }
+        if let Some(client) = inner.client.take() {
+            let _ = client.close().await;
+        }
+    }
+
+    async fn ensure(inner: &mut Inner, key: &str, new: SessionOptions) -> Result<(), NativeError> {
+        if inner.sessions.contains_key(key) {
+            return Ok(());
+        }
+        let Some(client) = &inner.client else {
+            return Err(NativeError::Closed);
+        };
+        let mut session = client.new_session(new).await?;
+        let handle = session.handle();
+        let mut events = session.take_events().map_err(|_| NativeError::Closed)?;
+        drop(session);
+        let key_owned = key.to_string();
+        let fwd = inner
+            .fwd
+            .clone()
+            .expect("forwarder channel installed at connect");
+        tokio::spawn(async move {
+            while let Some(ev) = events.recv().await {
+                if fwd.send((key_owned.clone(), Some(ev))).is_err() {
+                    break;
+                }
+            }
+            let _ = fwd.send((key_owned, None));
+        });
+        inner.sessions.insert(
+            key.to_string(),
+            Session {
+                handle,
+                conv: Conversation::new(format!("pool-{key}")),
+                busy: false,
+                seq: 0,
+            },
+        );
+        Ok(())
+    }
+
+    /// Single router: applies every streamed event to its key's conversation
+    /// (clearing finished turns) and re-emits it tagged for the application.
+    async fn route(
+        pool: Self,
+        mut fwd: mpsc::UnboundedReceiver<(SessionKey, Option<SessionEvent>)>,
+    ) {
+        while let Some((key, ev)) = fwd.recv().await {
+            let mut inner = pool.inner.lock().await;
+            let Some(session) = inner.sessions.get_mut(&key) else {
+                continue;
+            };
+            let Some(se) = ev else {
+                session.busy = false;
+                let _ = inner.app_events.send(PoolEvent::Ended { key });
+                continue;
+            };
+            session.seq += 1;
+            let rid = se.request_id.clone().unwrap_or_default();
+            let SessionEvent { event, .. } = &se;
+            let conv_id = session.conv.id().to_string();
+            let _ = session
+                .conv
+                .apply(WireEvent::new(conv_id, rid, session.seq, event.clone()));
+            match &event {
+                crate::Event::Completed { .. } | crate::Event::Error { .. } => {
+                    session.busy = false;
+                }
+                _ => {}
+            }
+            let _ = inner.app_events.send(PoolEvent::Session {
+                key,
+                event: Box::new(se),
+            });
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::Event;
+    use crate::acp::{ContentBlock, SessionUpdate};
+    use std::time::Duration;
+    use tokio::time::timeout;
+
+    fn options() -> NativeOptions {
+        NativeOptions {
+            operation_timeout: Duration::from_secs(5),
+            prompt_timeout: Duration::from_secs(5),
+            permission_timeout: Duration::from_secs(2),
+            shutdown_timeout: Duration::from_secs(2),
+            ..NativeOptions::default()
+        }
+    }
+
+    fn command(mode: &str) -> AgentCommand {
+        AgentCommand::new("python3").args(["-u", "-c", include_str!("fixture.py"), mode])
+    }
+
+    fn session_options() -> SessionOptions {
+        SessionOptions::new(std::env::temp_dir())
+    }
+
+    fn text(event: &SessionEvent) -> Option<&str> {
+        match &event.event {
+            Event::Update {
+                update: SessionUpdate::AgentMessageChunk(chunk),
+            } => {
+                if let ContentBlock::Text(content) = &chunk.content {
+                    Some(&content.text)
+                } else {
+                    None
+                }
+            }
+            _ => None,
+        }
+    }
+
+    /// Collect streamed text for one key until its turn terminates.
+    /// Other keys' events are parked and replayed to the caller in order.
+    /// Collect streamed text for both keys until each turn terminates,
+    /// demultiplexing the single shared event stream.
+    async fn collect_two(rx: &mut mpsc::UnboundedReceiver<PoolEvent>) -> (String, String) {
+        let (mut a, mut b) = (String::new(), String::new());
+        let (mut done_a, mut done_b) = (false, false);
+        while !done_a || !done_b {
+            let ev = timeout(Duration::from_secs(15), rx.recv())
+                .await
+                .expect("event in time")
+                .expect("stream open");
+            if let PoolEvent::Session { key, event } = ev {
+                let terminal = matches!(event.event, Event::Completed { .. } | Event::Error { .. });
+                if let Some(t) = text(&event) {
+                    match key.as_str() {
+                        "a" => a.push_str(t),
+                        "b" => b.push_str(t),
+                        _ => {}
+                    }
+                }
+                if terminal {
+                    match key.as_str() {
+                        "a" => done_a = true,
+                        "b" => done_b = true,
+                        _ => {}
+                    }
+                }
+            }
+        }
+        (a, b)
+    }
+
+    #[tokio::test]
+    async fn parallel_keys_complete_independently() {
+        let (pool, mut rx) = SessionPool::connect(command("normal"), options()).await;
+        // Both turns run concurrently; a single shared session could not do this.
+        let p1 = pool.clone();
+        let t1 =
+            tokio::spawn(
+                async move { p1.prompt("a", session_options(), "first".to_string()).await },
+            );
+        let p2 = pool.clone();
+        let t2 = tokio::spawn(async move {
+            p2.prompt("b", session_options(), "second".to_string())
+                .await
+        });
+        let (r1, r2, texts) = tokio::join!(t1, t2, collect_two(&mut rx));
+        r1.expect("task a").expect("turn a");
+        r2.expect("task b").expect("turn b");
+        // Fixture answers every turn with the same stream.
+        assert_eq!(
+            texts,
+            ("hello world".to_string(), "hello world".to_string())
+        );
+        assert!(!pool.is_busy("a").await);
+        assert!(!pool.is_busy("b").await);
+        // Conversations accumulated per key for replay.
+        assert!(pool.conversation("a").await.is_some());
+        assert!(pool.conversation("b").await.is_some());
+        assert!(pool.conversation("ghost").await.is_none());
+        pool.shutdown().await;
+    }
+
+    #[tokio::test]
+    async fn second_prompt_on_busy_key_fails_cleanly() {
+        use crate::native::NativeError;
+
+        let (pool, _rx) = SessionPool::connect(command("hang"), options()).await;
+        // The hang fixture holds the turn open without answering, so the
+        // overlapping prompt deterministically hits the busy guard.
+        let p = pool.clone();
+        let held = tokio::spawn(async move {
+            // The hang fixture never answers, so the held turn stays open
+            // until the prompt timeout fires; the busy transition in between
+            // is what this test observes, not the outcome.
+            let _ = p.prompt("k", session_options(), "one".to_string()).await;
+        });
+        let mut busy_seen = false;
+        for _ in 0..100 {
+            if pool.is_busy("k").await {
+                busy_seen = true;
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(50)).await;
+        }
+        assert!(busy_seen, "turn never went busy");
+        let second = pool.prompt("k", session_options(), "two".to_string()).await;
+        assert!(
+            matches!(second, Err(NativeError::Busy)),
+            "expected Busy, got {second:?}"
+        );
+        let _ = held.await;
+        assert!(!pool.is_busy("k").await);
+        pool.shutdown().await;
+    }
+
+    #[tokio::test]
+    async fn missing_keys_fail_without_creating_sessions() {
+        let (pool, _rx) = SessionPool::connect(command("normal"), options()).await;
+        assert!(pool.set_model("ghost", "m").await.is_err());
+        assert!(pool.cancel("ghost").await.is_ok());
+        assert!(!pool.has_session("ghost").await);
+        pool.close("ghost").await;
+        pool.shutdown().await;
+    }
+}