From 8d35f7f8c8ad6b15e0ea257e6837075d73f1fd2b Mon Sep 17 00:00:00 2001 From: Miguel Palhas Date: Mon, 7 Sep 2026 21:08:08 +0100 Subject: [PATCH] feat(maestro): async structured session spawn Register a structured session immediately with `activity: Starting` and run the ACP handshake in a background task. The HTTP caller gets an instant response; the user can begin typing a prompt while the adapter boots. - Add `ActivityState::Starting` to the protocol - Open the event log eagerly so the structured WS can connect during boot (empty transcript + idle state) - `queue_acp_prompt` stashes a prompt while `Starting`; the background task drains it on successful handshake - `apply_structured_activity` skips overwriting `Starting` - `subscribe_acp_projection` allows connecting during `Starting` - TUI/CLI map `Starting` to idle colour / "starting" label Co-Authored-By: Claude Opus 4.6 --- crates/maestro-cli/src/sessions.rs | 1 + crates/maestro-daemon/src/local_api.rs | 6 +- crates/maestro-daemon/src/session.rs | 378 ++++++++++++++----------- crates/maestro-protocol/src/lib.rs | 8 +- crates/maestro-tui/src/palette.rs | 2 +- 5 files changed, 231 insertions(+), 164 deletions(-) diff --git a/crates/maestro-cli/src/sessions.rs b/crates/maestro-cli/src/sessions.rs index 73a6787..88e8beb 100644 --- a/crates/maestro-cli/src/sessions.rs +++ b/crates/maestro-cli/src/sessions.rs @@ -216,6 +216,7 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon ActivityState::Idle => "idle", ActivityState::AwaitingInput => "awaiting", ActivityState::Error => "error", + ActivityState::Starting => "starting", }; // Show the live foreground command alongside the spawn command when // the daemon has observed one that differs (NAP-340). diff --git a/crates/maestro-daemon/src/local_api.rs b/crates/maestro-daemon/src/local_api.rs index 7a351ce..e0eb078 100644 --- a/crates/maestro-daemon/src/local_api.rs +++ b/crates/maestro-daemon/src/local_api.rs @@ -180,7 +180,7 @@ fn dir_error_status(code: &str) -> StatusCode { fn session_error_status(code: &str) -> StatusCode { match code { "not_found" => StatusCode::NOT_FOUND, - "invalid_env" => StatusCode::BAD_REQUEST, + "invalid_env" | "bad_request" => StatusCode::BAD_REQUEST, // A guard refusal is the daemon doing its job, not a failure (#79). "kill_guarded" => StatusCode::CONFLICT, // The session outlived its pane: nothing to type into, and nothing @@ -483,7 +483,9 @@ async fn structured_prompt( Json(body): Json, ) -> Response { match s.manager.queue_acp_prompt(id, body.prompt).await { - Ok(QueueAcpPrompt::Queued) => StatusCode::NO_CONTENT.into_response(), + Ok(QueueAcpPrompt::Queued) | Ok(QueueAcpPrompt::Pending) => { + StatusCode::NO_CONTENT.into_response() + } Ok(QueueAcpPrompt::InFlight) => error_response( StatusCode::CONFLICT, "turn_in_flight", diff --git a/crates/maestro-daemon/src/session.rs b/crates/maestro-daemon/src/session.rs index 20eaedb..4f9f0d6 100644 --- a/crates/maestro-daemon/src/session.rs +++ b/crates/maestro-daemon/src/session.rs @@ -6,12 +6,9 @@ //! handler interact with tmux. use std::collections::{HashMap, HashSet}; -use std::future::Future; use std::path::PathBuf; -use std::pin::Pin; use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering}; use std::sync::{Arc, Weak}; -use std::task::{Context, Poll}; use std::time::Duration; use chrono::Utc; @@ -125,6 +122,9 @@ pub struct SessionRecord { /// When `true`, the permission pump auto-responds `AllowAlways` to every /// ACP permission request without surfacing it to clients. pub auto_approve: bool, + /// A prompt submitted while the adapter was still booting (`Starting`). + /// The background handshake task drains this on success. + pub pending_prompt: Option, } impl SessionRecord { @@ -134,6 +134,13 @@ impl SessionRecord { && self.acp.is_some() && self.acp_events.is_some() } + + /// The session is structured and still booting its adapter. + fn is_starting_structured(&self) -> bool { + self.session.view == SessionView::Structured + && self.session.activity == ActivityState::Starting + && self.acp.is_none() + } } #[derive(Debug)] @@ -208,6 +215,8 @@ pub enum SessionError { NotTerminal(Uuid), #[error("daemon is shutting down")] ShuttingDown, + #[error("bad request: {0}")] + BadRequest(String), /// The kill was refused (#79): the session's worktree holds unsaved work. /// Nothing happened — the session keeps running and the tree is untouched, /// so it stays the operator's handle on their own unfinished work. @@ -227,6 +236,8 @@ pub enum BeginAcpTurn { #[derive(Debug)] pub enum QueueAcpPrompt { Queued, + /// The adapter is still booting; the prompt is held until it is ready. + Pending, InFlight, Unavailable, Failed(String), @@ -253,6 +264,7 @@ impl SessionError { SessionError::NotRunning(_) => "not_running", SessionError::NotTerminal(_) => "not_terminal", SessionError::ShuttingDown => "shutting_down", + SessionError::BadRequest(_) => "bad_request", SessionError::KillGuarded(_) => "kill_guarded", }; let unsaved_work = match self { @@ -320,18 +332,6 @@ struct StructuredLifecycle { } impl StructuredLifecycle { - fn admit<'a>( - &'a self, - shutting_down: &AtomicBool, - ) -> Result, SessionError> { - let _gate = self.gate.lock().expect("structured lifecycle gate"); - if shutting_down.load(Ordering::Acquire) { - return Err(SessionError::ShuttingDown); - } - self.in_flight.fetch_add(1, Ordering::AcqRel); - Ok(StructuredCreate { lifecycle: self }) - } - async fn wait_until_settled(&self) { loop { let settled = self.settled.notified(); @@ -343,30 +343,18 @@ impl StructuredLifecycle { } } -struct StructuredCreate<'a> { - lifecycle: &'a StructuredLifecycle, -} - -impl Drop for StructuredCreate<'_> { - fn drop(&mut self) { - if self.lifecycle.in_flight.fetch_sub(1, Ordering::AcqRel) == 1 { - self.lifecycle.settled.notify_one(); - } - } -} - -struct AdmittedStructuredCreate<'a> { - create: Pin> + Send + 'a>>, - /// Field order matters: dropping a cancelled create rolls back its inner - /// future before this permit releases shutdown's in-flight barrier. - _permit: StructuredCreate<'a>, -} - -impl Future for AdmittedStructuredCreate<'_> { - type Output = Result; - - fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - self.create.as_mut().poll(cx) +/// Release the structured-lifecycle in-flight counter that `create` acquires +/// before spawning the background ACP handshake task. Called when the task +/// finishes (success or failure) or when `create_inner` fails before the task +/// is spawned. +fn drop_structured_lifecycle_permit(inner: &Inner) { + if inner + .structured_lifecycle + .in_flight + .fetch_sub(1, Ordering::AcqRel) + == 1 + { + inner.structured_lifecycle.settled.notify_one(); } } @@ -660,7 +648,9 @@ impl SessionManager { let stream = { let sessions = self.inner.sessions.lock().await; let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?; - if !record.is_live_structured() { + // Allow connecting while the adapter is still booting + // (`Starting`) — the event stream exists, it is just empty. + if !record.is_live_structured() && !record.is_starting_structured() { return Ok(None); } let Some(stream) = &record.acp_events else { @@ -745,8 +735,14 @@ impl SessionManager { text: String, ) -> Result { let (acp, stream) = { - let sessions = self.inner.sessions.lock().await; - let record = sessions.get(&id).ok_or(SessionError::NotFound(id))?; + let mut sessions = self.inner.sessions.lock().await; + let record = sessions.get_mut(&id).ok_or(SessionError::NotFound(id))?; + // While the adapter is booting, stash the prompt for the + // background handshake task to drain on success. + if record.is_starting_structured() { + record.pending_prompt = Some(text); + return Ok(QueueAcpPrompt::Pending); + } if !record.is_live_structured() { return Ok(QueueAcpPrompt::Unavailable); } @@ -1217,17 +1213,42 @@ impl SessionManager { } /// Spawn a new session. On success returns the freshly-created `Session`. + /// + /// For structured sessions, the ACP handshake runs in a background task + /// after the session is registered — the HTTP caller gets an instant + /// response with `activity: Starting`. The `StructuredLifecycle` gate is + /// held across the background task so `shutdown()` waits for it. pub async fn create(&self, req: CreateSessionRequest) -> Result { if req.view == SessionView::Structured { - let permit = self + // Acquire the lifecycle gate synchronously (rejects if shutting + // down). The background handshake task calls + // `drop_structured_lifecycle_permit` when it finishes; we must + // not use the RAII `StructuredCreate` because it would drop at + // the end of `create_inner`, before the handshake completes. + let _gate = self .inner .structured_lifecycle - .admit(&self.inner.shutting_down)?; - return AdmittedStructuredCreate { - create: Box::pin(self.create_inner(req)), - _permit: permit, + .gate + .lock() + .expect("structured lifecycle gate"); + if self.inner.shutting_down.load(Ordering::Acquire) { + return Err(SessionError::ShuttingDown); } - .await; + self.inner + .structured_lifecycle + .in_flight + .fetch_add(1, Ordering::AcqRel); + drop(_gate); + + return match self.create_inner(req).await { + Ok(session) => Ok(session), + Err(e) => { + // create_inner failed before spawning the background + // task, so release the permit here. + drop_structured_lifecycle_permit(&self.inner); + Err(e) + } + }; } self.create_inner(req).await } @@ -1289,32 +1310,41 @@ impl SessionManager { { session_env.insert("MAESTRO_URL".into(), url); } - // A structured session (#134) gets no tmux pane: the agent is a - // child of the daemon, driven over ACP. An adapter that cannot come - // up still yields a session — Dead, with the reason on it — so the - // operator sees what to fix instead of a silently missing session. - let (acp, acp_failure) = match req.view { - SessionView::Structured => match structured_adapter(&req.command) { - Err(error) => (None, Some(error)), - Ok(adapter) => match maestro_acp::spawn( - SpawnConfig::new( - &effective_cwd, - session_env - .iter() - .map(|(k, v)| (k.clone(), v.clone())) - .collect(), - ) - .adapter(adapter), - ) - .await - { - Ok(acp) => (Some(Arc::new(acp)), None), - Err(e) => { - tracing::warn!(%id, error = %e, "structured session: adapter failed to start"); - (None, Some(e.to_string())) + // ── Structured path: validate adapter, open event log, register + // the session immediately with `Starting`, then handshake in the + // background so the HTTP caller gets an instant response. + // + // ── Terminal path: unchanged — tmux spawn is fast enough to stay + // synchronous. + // Structured: validate adapter, open event log eagerly. Terminal: + // spawn the tmux pane synchronously (it is fast). + let structured_spawn = match req.view { + SessionView::Structured => { + // Fail fast on an unsupported command before touching disk. + let adapter = structured_adapter(&req.command).map_err(|msg| { + SessionError::BadRequest(msg) + })?; + // Open the event log eagerly so the structured WS can + // connect before the adapter is up. + let acp_events = match self.inner.sidecar.open_events(id) { + Ok(log) => { + let (tx, _) = broadcast::channel(EVENTS_CAPACITY); + let (projected_tx, _) = broadcast::channel(EVENTS_CAPACITY); + Arc::new(Mutex::new(AcpEventStream { + log, + live: tx, + projection: Projection::default(), + projected_live: projected_tx, + pending_approvals: HashMap::new(), + operation: Arc::new(Mutex::new(())), + dispatch: AcpDispatchState::default(), + activity_sequence: 0, + })) } - }, - }, + Err(e) => return Err(SessionError::Sidecar(e)), + }; + Some((adapter, acp_events)) + } SessionView::Terminal => { let spawned = { let tmux = self.inner.tmux.clone(); @@ -1328,53 +1358,10 @@ impl SessionManager { if let Err(e) = spawned { return Err(SessionError::Tmux(e)); } - (None, None) + None } }; - let acp_events = if let Some(acp) = &acp { - let persisted = - match self - .inner - .sidecar - .read_events(id, EventCursor::Since(0), usize::MAX) - { - Ok(events) => events, - Err(error) => { - acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE) - .await; - return Err(SessionError::Sidecar(error)); - } - }; - match self.inner.sidecar.open_events(id) { - Ok(log) => { - let (tx, _) = broadcast::channel(EVENTS_CAPACITY); - let (projected_tx, _) = broadcast::channel(EVENTS_CAPACITY); - let mut projection = Projection::default(); - for event in &persisted { - apply_persisted_event(&mut projection, event); - } - Some(Arc::new(Mutex::new(AcpEventStream { - log, - live: tx, - projection, - projected_live: projected_tx, - pending_approvals: HashMap::new(), - operation: Arc::new(Mutex::new(())), - dispatch: AcpDispatchState::default(), - activity_sequence: 0, - }))) - } - Err(e) => { - acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE) - .await; - return Err(SessionError::Sidecar(e)); - } - } - } else { - None - }; - // Capture spawn-history inputs before `req` is partially moved into // `session`. `history_cwd` is the *chosen* working dir (the request // `cwd`), not a generated worktree checkout path — that's what the @@ -1384,10 +1371,13 @@ impl SessionManager { resolve_name(&mut metadata); let worktree_branch = req.worktree.as_ref().map(|w| w.branch.clone()); + let is_structured = structured_spawn.is_some(); + let events_arc = structured_spawn.as_ref().map(|(_, e)| e.clone()); + let session = Session { id, - cwd: effective_cwd, - command: req.command, + cwd: effective_cwd.clone(), + command: req.command.clone(), env: req.env, metadata, worktree: worktree_path.as_ref().zip(worktree_base_repo.as_ref()).map( @@ -1396,67 +1386,41 @@ impl SessionManager { base_repo: base_repo.clone(), }, ), - status: if acp_failure.is_some() { - SessionStatus::Dead - } else { - SessionStatus::Running - }, + status: SessionStatus::Running, created_at: Utc::now(), - // A terminal spawn begins active until its watcher sees otherwise; - // a structured spawn has no turn yet and begins idle. foreground: None, - activity: match (req.view, acp_failure.is_some()) { - (_, true) => ActivityState::Error, - (SessionView::Structured, false) => ActivityState::Idle, - (SessionView::Terminal, false) => ActivityState::Active, + activity: if is_structured { + ActivityState::Starting + } else { + ActivityState::Active }, - activity_detail: acp_failure, + activity_detail: None, last_activity_at: Utc::now(), activity_since: chrono::Utc::now(), - current_cwd: None, - // The watcher fills this in on its first blocked-work pass; a - // fresh tree has nothing in the way anyway. blocked_work: None, last_focused_at: None, - acp_session_id: acp.as_ref().map(|a| a.session_id().to_string()), + acp_session_id: None, view: req.view, }; if let Err(e) = self.inner.sidecar.write(&session) { - // The process already started; end it so no ghost survives a - // failed sidecar write, then unwind the FIFO + worktree. - match &acp { - Some(acp) => { - acp.terminate(maestro_acp::CANCEL_GRACE, maestro_acp::TERM_GRACE) - .await - } - None => { - let tmux = self.inner.tmux.clone(); - let _ = tmux_blocking(move || tmux.kill_session(id)).await; - } + if !is_structured { + let tmux = self.inner.tmux.clone(); + let _ = tmux_blocking(move || tmux.kill_session(id)).await; } return Err(SessionError::Sidecar(e)); } - let event_pump = acp - .as_ref() - .zip(acp_events.as_ref()) - .map(|(acp, events)| (acp.clone(), events.clone())); { let mut sessions = self.inner.sessions.lock().await; - let event_pump = event_pump.map(|(acp, events)| { - let done = start_acp_event_pump(&self.inner, id, &acp, events.clone()); - start_acp_permission_pump(&self.inner, id, &acp, events, req.auto_approve); - done - }); sessions.insert( id, SessionRecord { session: session.clone(), fifo_path, - worktree_path, - worktree_base_repo, + worktree_path: worktree_path.clone(), + worktree_base_repo: worktree_base_repo.clone(), bridge, reported_activity: None, settled: false, @@ -1464,11 +1428,12 @@ impl SessionManager { naming: false, focused_since: None, awaiting_suppressed: false, - acp, - acp_events, + acp: None, + acp_events: events_arc, structured_activity_watermark: None, - acp_event_pump: event_pump, + acp_event_pump: None, auto_approve: req.auto_approve, + pending_prompt: None, }, ); } @@ -1497,6 +1462,92 @@ impl SessionManager { } pending.commit(); + + // ── Background ACP handshake for structured sessions ── + // + // The session is registered and visible to clients. The adapter + // spawn + handshake runs in a background task; on completion it + // fills in `acp`, starts the event/permission pumps, and + // transitions activity from `Starting` to `Idle` (or to `Error` + // on failure). The `StructuredLifecycle` permit is held until the + // task finishes so `shutdown()` waits for it. + if let Some((adapter, events)) = structured_spawn { + let inner = self.inner.clone(); + let env: HashMap = session_env + .iter() + .map(|(k, v)| (k.clone(), v.clone())) + .collect(); + let cwd = effective_cwd; + let auto_approve = req.auto_approve; + tokio::spawn(async move { + let result = maestro_acp::spawn( + SpawnConfig::new(&cwd, env).adapter(adapter), + ) + .await; + + match result { + Ok(acp_session) => { + let acp = Arc::new(acp_session); + let done = + start_acp_event_pump(&inner, id, &acp, events.clone()); + start_acp_permission_pump( + &inner, + id, + &acp, + events.clone(), + auto_approve, + ); + // Drain any prompt submitted while Starting. + let pending_prompt = { + let mut sessions = inner.sessions.lock().await; + let Some(record) = sessions.get_mut(&id) else { + // Session was killed while we were booting. + acp.terminate( + maestro_acp::CANCEL_GRACE, + maestro_acp::TERM_GRACE, + ) + .await; + drop_structured_lifecycle_permit(&inner); + return; + }; + record.acp = Some(acp.clone()); + record.acp_event_pump = Some(done); + record.session.acp_session_id = + Some(acp.session_id().to_string()); + record.session.activity = ActivityState::Idle; + record.session.activity_since = Utc::now(); + let _ = inner.sidecar.write(&record.session); + let _ = inner.events.send(CatalogEvent::SessionUpdated { + session: record.session.clone(), + }); + record.pending_prompt.take() + }; + if let Some(prompt) = pending_prompt { + let manager = SessionManager { + inner: inner.clone(), + }; + let _ = manager.queue_acp_prompt(id, prompt).await; + } + } + Err(e) => { + tracing::warn!(%id, error = %e, "structured session: adapter failed to start"); + let mut sessions = inner.sessions.lock().await; + if let Some(record) = sessions.get_mut(&id) { + record.session.status = SessionStatus::Dead; + record.session.activity = ActivityState::Error; + record.session.activity_detail = Some(e.to_string()); + record.session.activity_since = Utc::now(); + let _ = inner.sidecar.write(&record.session); + let _ = inner.events.send(CatalogEvent::SessionUpdated { + session: record.session.clone(), + }); + } + } + } + drop_structured_lifecycle_permit(&inner); + }); + } + Ok(session) } @@ -1682,6 +1733,7 @@ impl SessionManager { structured_activity_watermark: None, acp_event_pump: None, auto_approve: false, + pending_prompt: None, }, ); let _ = self @@ -1862,6 +1914,7 @@ impl SessionManager { // Recovery cannot know the original preset's flag; the // operator re-enables it by restarting with the preset. auto_approve: false, + pending_prompt: None, }, ); if let Some((acp, events)) = event_pump { @@ -2321,6 +2374,11 @@ async fn apply_structured_activity( if record.session.view != SessionView::Structured { return; } + // While the adapter is still booting, the background handshake task + // owns the activity state — the activity pass must not overwrite it. + if record.session.activity == ActivityState::Starting { + return; + } let current_events = record.acp_events.as_ref(); match (expected_events, current_events) { (Some((expected, sequence)), Some(current)) if Arc::ptr_eq(expected, current) => { diff --git a/crates/maestro-protocol/src/lib.rs b/crates/maestro-protocol/src/lib.rs index e64dda5..7a87b61 100644 --- a/crates/maestro-protocol/src/lib.rs +++ b/crates/maestro-protocol/src/lib.rs @@ -175,6 +175,10 @@ pub enum ActivityState { AwaitingInput, /// An agent reported a failure, or a structured session/turn failed. Error, + /// The ACP adapter is booting; the session is registered but cannot accept + /// prompts yet. Older clients that do not know this variant degrade it to + /// `Idle` via the lenient deserializer — acceptable. + Starting, } impl<'de> Deserialize<'de> for ActivityState { @@ -187,6 +191,7 @@ impl<'de> Deserialize<'de> for ActivityState { "Active" => Self::Active, "AwaitingInput" => Self::AwaitingInput, "Error" => Self::Error, + "Starting" => Self::Starting, // Known or not, any other spelling degrades to the neutral default _ => Self::Idle, }) @@ -225,9 +230,10 @@ where "Idle" => Ok(ActivityState::Idle), "AwaitingInput" => Ok(ActivityState::AwaitingInput), "Error" => Ok(ActivityState::Error), + "Starting" => Ok(ActivityState::Starting), other => Err(D::Error::unknown_variant( other, - &["Active", "Idle", "AwaitingInput", "Error"], + &["Active", "Idle", "AwaitingInput", "Error", "Starting"], )), } } diff --git a/crates/maestro-tui/src/palette.rs b/crates/maestro-tui/src/palette.rs index 8ecae24..1564153 100644 --- a/crates/maestro-tui/src/palette.rs +++ b/crates/maestro-tui/src/palette.rs @@ -82,7 +82,7 @@ impl Surface { pub fn activity(&self, state: ActivityState) -> Color { match state { ActivityState::Active => self.active, - ActivityState::Idle => self.idle, + ActivityState::Idle | ActivityState::Starting => self.idle, ActivityState::AwaitingInput => self.awaiting, ActivityState::Error => self.error, }