Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
8f5d96a95b | ||
|
|
3e98b3ab24 | ||
|
|
24ed1ac002 | ||
|
|
64741a027e | ||
|
|
cdd4213ff5 | ||
|
|
f8973b3802 | ||
|
|
1e2c0f0a38 |
@@ -92,6 +92,12 @@ clients — how it opens, the sigils, the key model, the match-and-rank algorith
|
|||||||
the two matchers must agree on, and the fixture table they are tested against.
|
the two matchers must agree on, and the fixture table they are tested against.
|
||||||
Read it before changing either bar or either matcher.
|
Read it before changing either bar or either matcher.
|
||||||
|
|
||||||
|
`docs/STRUCTURED-VIEW.md` is the contract for a structured session (an agent
|
||||||
|
run as a daemon child over ACP instead of in a tmux pane) — the eight
|
||||||
|
transcript row kinds, the two projections and their cursor/replay semantics,
|
||||||
|
the handshake and declined capabilities, and the approval nonce rules. Read
|
||||||
|
it before changing anything that renders a structured session.
|
||||||
|
|
||||||
`nix run .#dev` (or `just dev`) brings up the whole local stack under
|
`nix run .#dev` (or `just dev`) brings up the whole local stack under
|
||||||
process-compose: a debug daemon on 127.0.0.1:7071, then Vite on :5173 once the
|
process-compose: a debug daemon on 127.0.0.1:7071, then Vite on :5173 once the
|
||||||
daemon answers `/api/info`. The SPA proxies `/api/*` back to the daemon, so only
|
daemon answers `/api/info`. The SPA proxies `/api/*` back to the daemon, so only
|
||||||
|
|||||||
@@ -66,6 +66,23 @@ pub fn decide(idle_for: Duration, awaiting_input: bool) -> ActivityState {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Derive a structured session's sidebar state from its ACP projection.
|
||||||
|
pub fn decide_structured(
|
||||||
|
turn_active: bool,
|
||||||
|
pending_approval: bool,
|
||||||
|
turn_failed: bool,
|
||||||
|
) -> ActivityState {
|
||||||
|
if turn_failed {
|
||||||
|
ActivityState::Error
|
||||||
|
} else if pending_approval {
|
||||||
|
ActivityState::AwaitingInput
|
||||||
|
} else if turn_active {
|
||||||
|
ActivityState::Active
|
||||||
|
} else {
|
||||||
|
ActivityState::Idle
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
/// How long a session's pane must be continuously focused (a client's pane,
|
/// How long a session's pane must be continuously focused (a client's pane,
|
||||||
/// not a sidebar highlight) before an `AwaitingInput` glow clears: the
|
/// not a sidebar highlight) before an `AwaitingInput` glow clears: the
|
||||||
/// operator has looked, so the rail stops asking for attention.
|
/// operator has looked, so the rail stops asking for attention.
|
||||||
@@ -136,6 +153,17 @@ mod tests {
|
|||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn structured_activity_follows_lifecycle_with_approval_precedence() {
|
||||||
|
assert_eq!(decide_structured(false, false, false), ActivityState::Idle);
|
||||||
|
assert_eq!(decide_structured(true, false, false), ActivityState::Active);
|
||||||
|
assert_eq!(
|
||||||
|
decide_structured(true, true, false),
|
||||||
|
ActivityState::AwaitingInput
|
||||||
|
);
|
||||||
|
assert_eq!(decide_structured(false, false, true), ActivityState::Error);
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn report_is_in_force_until_exactly_its_expiry() {
|
fn report_is_in_force_until_exactly_its_expiry() {
|
||||||
let ttl = Duration::from_secs(300);
|
let ttl = Duration::from_secs(300);
|
||||||
|
|||||||
@@ -307,11 +307,10 @@ async fn rename_session(
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// `POST /api/sessions/:id/activity` (#105): an agent reports its own state.
|
/// `POST /api/sessions/:id/activity` (#105): an agent reports a terminal
|
||||||
/// The report holds above the daemon's inference for a TTL, then inference
|
/// session's state. Structured sessions acknowledge and ignore these reports
|
||||||
/// resumes — an agent that dies mid-run cannot pin its session at `Error`
|
/// because their activity comes from ACP. Unknown session is 404; an unknown
|
||||||
/// forever. Unknown session is 404; an unknown state value is rejected by the
|
/// state value is rejected by the JSON decoder (422). Answers `204 No Content`.
|
||||||
/// JSON decoder (422) rather than coerced. Answers `204 No Content`.
|
|
||||||
async fn report_activity(
|
async fn report_activity(
|
||||||
State(s): State<LocalApiState>,
|
State(s): State<LocalApiState>,
|
||||||
Path(id): Path<Uuid>,
|
Path(id): Path<Uuid>,
|
||||||
|
|||||||
@@ -4,7 +4,8 @@ use std::collections::{HashMap, HashSet};
|
|||||||
|
|
||||||
use maestro_acp::schema::{ContentChunk, SessionNotification, SessionUpdate, ToolCall};
|
use maestro_acp::schema::{ContentChunk, SessionNotification, SessionUpdate, ToolCall};
|
||||||
use maestro_protocol::{
|
use maestro_protocol::{
|
||||||
ReducedState, TranscriptDelta, TranscriptRow, TranscriptRowKind, TranscriptSnapshot,
|
ActivityState, ReducedState, TranscriptDelta, TranscriptRow, TranscriptRowKind,
|
||||||
|
TranscriptSnapshot,
|
||||||
};
|
};
|
||||||
use serde_json::Value;
|
use serde_json::Value;
|
||||||
|
|
||||||
@@ -36,6 +37,7 @@ pub struct Projection {
|
|||||||
pending_tool_updates: HashMap<String, Vec<maestro_acp::schema::ToolCallUpdateFields>>,
|
pending_tool_updates: HashMap<String, Vec<maestro_acp::schema::ToolCallUpdateFields>>,
|
||||||
state: ReducedState,
|
state: ReducedState,
|
||||||
active_turn: Option<u64>,
|
active_turn: Option<u64>,
|
||||||
|
turn_failed: bool,
|
||||||
next_turn: u64,
|
next_turn: u64,
|
||||||
turn_tool_calls: HashSet<String>,
|
turn_tool_calls: HashSet<String>,
|
||||||
}
|
}
|
||||||
@@ -109,11 +111,21 @@ impl Projection {
|
|||||||
self.active_turn.is_some()
|
self.active_turn.is_some()
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Sidebar activity derived from the live turn projection.
|
||||||
|
pub fn activity(&self) -> ActivityState {
|
||||||
|
crate::activity::decide_structured(
|
||||||
|
self.active_turn.is_some(),
|
||||||
|
self.state.pending_approval.is_some(),
|
||||||
|
self.turn_failed,
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
/// Start a prompt turn and return its monotonically increasing token.
|
/// Start a prompt turn and return its monotonically increasing token.
|
||||||
pub fn begin_turn(&mut self) -> (u64, ProjectionUpdate) {
|
pub fn begin_turn(&mut self) -> (u64, ProjectionUpdate) {
|
||||||
self.next_turn += 1;
|
self.next_turn += 1;
|
||||||
let turn = self.next_turn;
|
let turn = self.next_turn;
|
||||||
self.active_turn = Some(turn);
|
self.active_turn = Some(turn);
|
||||||
|
self.turn_failed = false;
|
||||||
self.state.turn.responding = true;
|
self.state.turn.responding = true;
|
||||||
self.state.turn.thinking = true;
|
self.state.turn.thinking = true;
|
||||||
self.turn_tool_calls.clear();
|
self.turn_tool_calls.clear();
|
||||||
@@ -141,6 +153,7 @@ impl Projection {
|
|||||||
return None;
|
return None;
|
||||||
}
|
}
|
||||||
self.active_turn = None;
|
self.active_turn = None;
|
||||||
|
self.turn_failed = lifecycle == TurnLifecycle::Failure;
|
||||||
self.state.turn.responding = false;
|
self.state.turn.responding = false;
|
||||||
self.state.turn.thinking = false;
|
self.state.turn.thinking = false;
|
||||||
self.turn_tool_calls.clear();
|
self.turn_tool_calls.clear();
|
||||||
|
|||||||
@@ -535,6 +535,8 @@ impl SessionManager {
|
|||||||
return Ok(false);
|
return Ok(false);
|
||||||
};
|
};
|
||||||
let _ = stream.projected_live.send(projected);
|
let _ = stream.projected_live.send(projected);
|
||||||
|
drop(stream);
|
||||||
|
sync_structured_activity(&self.inner, id).await;
|
||||||
Ok(true)
|
Ok(true)
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -558,6 +560,8 @@ impl SessionManager {
|
|||||||
}
|
}
|
||||||
let (turn, update) = stream.projection.begin_turn();
|
let (turn, update) = stream.projection.begin_turn();
|
||||||
let _ = stream.projected_live.send(update);
|
let _ = stream.projected_live.send(update);
|
||||||
|
drop(stream);
|
||||||
|
sync_structured_activity(&self.inner, id).await;
|
||||||
Ok(BeginAcpTurn::Started(acp, turn))
|
Ok(BeginAcpTurn::Started(acp, turn))
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -614,6 +618,8 @@ impl SessionManager {
|
|||||||
};
|
};
|
||||||
manager.finish_queued_acp_turn(id, turn, lifecycle).await;
|
manager.finish_queued_acp_turn(id, turn, lifecycle).await;
|
||||||
});
|
});
|
||||||
|
drop(stream);
|
||||||
|
sync_structured_activity(&self.inner, id).await;
|
||||||
return Ok(QueueAcpPrompt::Queued);
|
return Ok(QueueAcpPrompt::Queued);
|
||||||
}
|
}
|
||||||
Err(message) => {
|
Err(message) => {
|
||||||
@@ -625,6 +631,8 @@ impl SessionManager {
|
|||||||
"newly claimed turn remains current while stream is locked",
|
"newly claimed turn remains current while stream is locked",
|
||||||
);
|
);
|
||||||
let _ = stream.projected_live.send(projected);
|
let _ = stream.projected_live.send(projected);
|
||||||
|
drop(stream);
|
||||||
|
sync_structured_activity(&self.inner, id).await;
|
||||||
return Ok(QueueAcpPrompt::Failed(message));
|
return Ok(QueueAcpPrompt::Failed(message));
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -669,6 +677,8 @@ impl SessionManager {
|
|||||||
if let Some(projected) = stream.projection.turn_lifecycle(lifecycle, turn) {
|
if let Some(projected) = stream.projection.turn_lifecycle(lifecycle, turn) {
|
||||||
let _ = stream.projected_live.send(projected);
|
let _ = stream.projected_live.send(projected);
|
||||||
}
|
}
|
||||||
|
drop(stream);
|
||||||
|
sync_structured_activity(&self.inner, id).await;
|
||||||
}
|
}
|
||||||
|
|
||||||
async fn fail_cancelled_acp_turn(
|
async fn fail_cancelled_acp_turn(
|
||||||
@@ -741,6 +751,7 @@ impl SessionManager {
|
|||||||
.expect("active turn remains current while stream is locked");
|
.expect("active turn remains current while stream is locked");
|
||||||
let _ = stream.projected_live.send(projected);
|
let _ = stream.projected_live.send(projected);
|
||||||
drop(stream);
|
drop(stream);
|
||||||
|
sync_structured_activity(&self.inner, id).await;
|
||||||
if let Some(turn) = cancelled_queued_turn {
|
if let Some(turn) = cancelled_queued_turn {
|
||||||
self.schedule_cancelled_acp_turn_failure(id, event_stream, turn);
|
self.schedule_cancelled_acp_turn_failure(id, event_stream, turn);
|
||||||
}
|
}
|
||||||
@@ -789,6 +800,8 @@ impl SessionManager {
|
|||||||
if let Some(update) = stream.projection.resolve_approval(nonce) {
|
if let Some(update) = stream.projection.resolve_approval(nonce) {
|
||||||
let _ = stream.projected_live.send(update);
|
let _ = stream.projected_live.send(update);
|
||||||
}
|
}
|
||||||
|
drop(stream);
|
||||||
|
sync_structured_activity(&self.inner, id).await;
|
||||||
Ok(Some(()))
|
Ok(Some(()))
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -1133,13 +1146,13 @@ impl SessionManager {
|
|||||||
SessionStatus::Running
|
SessionStatus::Running
|
||||||
},
|
},
|
||||||
created_at: Utc::now(),
|
created_at: Utc::now(),
|
||||||
// A freshly-spawned session is producing its initial output; the
|
// A terminal spawn begins active until its watcher sees otherwise;
|
||||||
// activity watcher refines `foreground`/`activity` on its next tick.
|
// a structured spawn has no turn yet and begins idle.
|
||||||
foreground: None,
|
foreground: None,
|
||||||
activity: if acp_failure.is_some() {
|
activity: match (req.view, acp_failure.is_some()) {
|
||||||
ActivityState::Error
|
(_, true) => ActivityState::Error,
|
||||||
} else {
|
(SessionView::Structured, false) => ActivityState::Idle,
|
||||||
ActivityState::Active
|
(SessionView::Terminal, false) => ActivityState::Active,
|
||||||
},
|
},
|
||||||
activity_detail: acp_failure,
|
activity_detail: acp_failure,
|
||||||
last_activity_at: Utc::now(),
|
last_activity_at: Utc::now(),
|
||||||
@@ -1201,7 +1214,7 @@ impl SessionManager {
|
|||||||
}
|
}
|
||||||
if let Some((acp, events)) = event_pump {
|
if let Some((acp, events)) = event_pump {
|
||||||
let done = start_acp_event_pump(&self.inner, id, &acp, events.clone());
|
let done = start_acp_event_pump(&self.inner, id, &acp, events.clone());
|
||||||
start_acp_permission_pump(&acp, events);
|
start_acp_permission_pump(&self.inner, id, &acp, events);
|
||||||
if let Some(record) = self.inner.sessions.lock().await.get_mut(&id) {
|
if let Some(record) = self.inner.sessions.lock().await.get_mut(&id) {
|
||||||
record.acp_event_pump = Some(done);
|
record.acp_event_pump = Some(done);
|
||||||
}
|
}
|
||||||
@@ -1331,6 +1344,7 @@ impl SessionManager {
|
|||||||
return;
|
return;
|
||||||
};
|
};
|
||||||
run_liveness_pass(&inner).await;
|
run_liveness_pass(&inner).await;
|
||||||
|
run_structured_activity_pass(&inner).await;
|
||||||
// Same tick, no new timer (NAP-340): refresh activity for the
|
// Same tick, no new timer (NAP-340): refresh activity for the
|
||||||
// survivors and emit SessionUpdated on any transition.
|
// survivors and emit SessionUpdated on any transition.
|
||||||
run_activity_pass(&inner).await;
|
run_activity_pass(&inner).await;
|
||||||
@@ -1499,11 +1513,15 @@ impl SessionManager {
|
|||||||
SessionStatus::Dead
|
SessionStatus::Dead
|
||||||
};
|
};
|
||||||
if recoverable {
|
if recoverable {
|
||||||
session.activity = if failure.is_some() {
|
let activity = if failure.is_some() {
|
||||||
ActivityState::Error
|
ActivityState::Error
|
||||||
} else {
|
} else {
|
||||||
ActivityState::Active
|
ActivityState::Idle
|
||||||
};
|
};
|
||||||
|
if session.activity != activity {
|
||||||
|
session.activity_since = Utc::now();
|
||||||
|
}
|
||||||
|
session.activity = activity;
|
||||||
session.activity_detail = failure;
|
session.activity_detail = failure;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -1590,7 +1608,7 @@ impl SessionManager {
|
|||||||
);
|
);
|
||||||
if let Some((acp, events)) = event_pump {
|
if let Some((acp, events)) = event_pump {
|
||||||
let done = start_acp_event_pump(&self.inner, id, &acp, events.clone());
|
let done = start_acp_event_pump(&self.inner, id, &acp, events.clone());
|
||||||
start_acp_permission_pump(&acp, events);
|
start_acp_permission_pump(&self.inner, id, &acp, events);
|
||||||
if let Some(record) = self.inner.sessions.lock().await.get_mut(&id) {
|
if let Some(record) = self.inner.sessions.lock().await.get_mut(&id) {
|
||||||
record.acp_event_pump = Some(done);
|
record.acp_event_pump = Some(done);
|
||||||
}
|
}
|
||||||
@@ -1750,12 +1768,10 @@ impl SessionManager {
|
|||||||
Ok(session)
|
Ok(session)
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Accept an agent-reported activity state (#105), the only path that can
|
/// Accept an agent-reported activity state (#105) for a terminal session.
|
||||||
/// produce `ActivityState::Error`. The report outranks the activity pass's
|
/// Structured sessions derive their state from ACP instead, so their
|
||||||
/// own inference until its TTL lapses — so an agent that dies mid-run
|
/// inherited hooks are acknowledged but ignored. An unknown session is
|
||||||
/// cannot pin its session at `Error` forever. An unknown session is
|
/// [`SessionError::NotFound`]; the reported `detail` is capped server-side.
|
||||||
/// [`SessionError::NotFound`]; the reported `detail` is capped
|
|
||||||
/// server-side.
|
|
||||||
///
|
///
|
||||||
/// A report that changes the effective state restarts `activity_since`
|
/// A report that changes the effective state restarts `activity_since`
|
||||||
/// (#104's clock); re-reporting an unchanged state only extends the TTL
|
/// (#104's clock); re-reporting an unchanged state only extends the TTL
|
||||||
@@ -1769,6 +1785,9 @@ impl SessionManager {
|
|||||||
let updated = {
|
let updated = {
|
||||||
let mut sessions = self.inner.sessions.lock().await;
|
let mut sessions = self.inner.sessions.lock().await;
|
||||||
let rec = sessions.get_mut(&id).ok_or(SessionError::NotFound(id))?;
|
let rec = sessions.get_mut(&id).ok_or(SessionError::NotFound(id))?;
|
||||||
|
if rec.session.view == SessionView::Structured {
|
||||||
|
return Ok(());
|
||||||
|
}
|
||||||
let detail = crate::activity::truncate_detail(detail);
|
let detail = crate::activity::truncate_detail(detail);
|
||||||
let changed = rec.session.activity != state || rec.session.activity_detail != detail;
|
let changed = rec.session.activity != state || rec.session.activity_detail != detail;
|
||||||
if rec.session.activity != state {
|
if rec.session.activity != state {
|
||||||
@@ -1983,10 +2002,51 @@ fn apply_persisted_event(projection: &mut Projection, event: &LoggedEvent) -> Pr
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
fn start_acp_permission_pump(acp: &Arc<AcpSession>, events: Arc<Mutex<AcpEventStream>>) {
|
async fn sync_structured_activity(inner: &Arc<Inner>, id: Uuid) {
|
||||||
|
let updated = {
|
||||||
|
let mut sessions = inner.sessions.lock().await;
|
||||||
|
let Some(record) = sessions.get_mut(&id) else {
|
||||||
|
return;
|
||||||
|
};
|
||||||
|
if record.session.view != SessionView::Structured {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
let raw = if record.session.status == SessionStatus::Dead {
|
||||||
|
ActivityState::Error
|
||||||
|
} else if let Some(events) = &record.acp_events {
|
||||||
|
events.lock().await.projection.activity()
|
||||||
|
} else {
|
||||||
|
ActivityState::Error
|
||||||
|
};
|
||||||
|
let activity = crate::activity::apply_focus_suppression(
|
||||||
|
raw,
|
||||||
|
record.focused_since,
|
||||||
|
std::time::Instant::now(),
|
||||||
|
&mut record.awaiting_suppressed,
|
||||||
|
);
|
||||||
|
if record.session.activity == activity {
|
||||||
|
None
|
||||||
|
} else {
|
||||||
|
record.session.activity = activity;
|
||||||
|
record.session.activity_since = Utc::now();
|
||||||
|
Some(record.session.clone())
|
||||||
|
}
|
||||||
|
};
|
||||||
|
if let Some(session) = updated {
|
||||||
|
let _ = inner.events.send(CatalogEvent::SessionUpdated { session });
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
fn start_acp_permission_pump(
|
||||||
|
inner: &Arc<Inner>,
|
||||||
|
id: Uuid,
|
||||||
|
acp: &Arc<AcpSession>,
|
||||||
|
events: Arc<Mutex<AcpEventStream>>,
|
||||||
|
) {
|
||||||
let Some(mut requests) = acp.take_permission_requests() else {
|
let Some(mut requests) = acp.take_permission_requests() else {
|
||||||
return;
|
return;
|
||||||
};
|
};
|
||||||
|
let weak_inner = Arc::downgrade(inner);
|
||||||
tokio::spawn(async move {
|
tokio::spawn(async move {
|
||||||
while let Some(PermissionRequest {
|
while let Some(PermissionRequest {
|
||||||
turn,
|
turn,
|
||||||
@@ -2023,12 +2083,20 @@ fn start_acp_permission_pump(acp: &Arc<AcpSession>, events: Arc<Mutex<AcpEventSt
|
|||||||
if let Err(error) = events.log.append(&event) {
|
if let Err(error) = events.log.append(&event) {
|
||||||
tracing::error!(%error, "approval history append failed");
|
tracing::error!(%error, "approval history append failed");
|
||||||
cancel_pending_approvals(&mut events);
|
cancel_pending_approvals(&mut events);
|
||||||
|
drop(events);
|
||||||
|
if let Some(inner) = weak_inner.upgrade() {
|
||||||
|
sync_structured_activity(&inner, id).await;
|
||||||
|
}
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
let seq = events.log.last_seq();
|
let seq = events.log.last_seq();
|
||||||
let _ = events.live.send(LoggedEvent { seq, event });
|
let _ = events.live.send(LoggedEvent { seq, event });
|
||||||
}
|
}
|
||||||
let _ = events.projected_live.send(update);
|
let _ = events.projected_live.send(update);
|
||||||
|
drop(events);
|
||||||
|
if let Some(inner) = weak_inner.upgrade() {
|
||||||
|
sync_structured_activity(&inner, id).await;
|
||||||
|
}
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
}
|
}
|
||||||
@@ -2176,7 +2244,7 @@ async fn run_liveness_pass(inner: &Arc<Inner>) {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Refresh each live session's inferred activity (NAP-340) and emit
|
/// Refresh each live terminal session's inferred activity (NAP-340) and emit
|
||||||
/// `SessionUpdated` only when `activity` or `foreground` actually changes — so a
|
/// `SessionUpdated` only when `activity` or `foreground` actually changes — so a
|
||||||
/// steady state produces no diffs. Runs on the existing liveness tick.
|
/// steady state produces no diffs. Runs on the existing liveness tick.
|
||||||
async fn run_activity_pass(inner: &Arc<Inner>) {
|
async fn run_activity_pass(inner: &Arc<Inner>) {
|
||||||
@@ -2192,7 +2260,10 @@ async fn run_activity_pass(inner: &Arc<Inner>) {
|
|||||||
// kept as-is so the UI can still show what it was doing when it died.
|
// kept as-is so the UI can still show what it was doing when it died.
|
||||||
sessions
|
sessions
|
||||||
.iter()
|
.iter()
|
||||||
.filter(|(_, r)| r.session.status == SessionStatus::Running)
|
.filter(|(_, r)| {
|
||||||
|
r.session.status == SessionStatus::Running
|
||||||
|
&& r.session.view == SessionView::Terminal
|
||||||
|
})
|
||||||
.map(|(id, _)| *id)
|
.map(|(id, _)| *id)
|
||||||
.collect()
|
.collect()
|
||||||
};
|
};
|
||||||
@@ -2290,6 +2361,21 @@ async fn run_activity_pass(inner: &Arc<Inner>) {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Reapply focus suppression to structured activity on the liveness cadence.
|
||||||
|
async fn run_structured_activity_pass(inner: &Arc<Inner>) {
|
||||||
|
let ids: Vec<Uuid> = inner
|
||||||
|
.sessions
|
||||||
|
.lock()
|
||||||
|
.await
|
||||||
|
.iter()
|
||||||
|
.filter(|(_, record)| record.session.view == SessionView::Structured)
|
||||||
|
.map(|(id, _)| *id)
|
||||||
|
.collect();
|
||||||
|
for id in ids {
|
||||||
|
sync_structured_activity(inner, id).await;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
/// Refresh each running session's blocked-work indicator (#83): what its
|
/// Refresh each running session's blocked-work indicator (#83): what its
|
||||||
/// worktree holds right now that would block an unforced kill. Rides the
|
/// worktree holds right now that would block an unforced kill. Rides the
|
||||||
/// liveness tick on its own (slower) cadence — see
|
/// liveness tick on its own (slower) cadence — see
|
||||||
@@ -2391,6 +2477,12 @@ async fn mark_session_dead_with_worktree_settlement(
|
|||||||
match sessions.get_mut(&id) {
|
match sessions.get_mut(&id) {
|
||||||
Some(record) if record.session.status == SessionStatus::Running => {
|
Some(record) if record.session.status == SessionStatus::Running => {
|
||||||
record.session.status = SessionStatus::Dead;
|
record.session.status = SessionStatus::Dead;
|
||||||
|
if record.session.view == SessionView::Structured
|
||||||
|
&& record.session.activity != ActivityState::Error
|
||||||
|
{
|
||||||
|
record.session.activity = ActivityState::Error;
|
||||||
|
record.session.activity_since = Utc::now();
|
||||||
|
}
|
||||||
// Release anyone attached; the scrollback survives for a later
|
// Release anyone attached; the scrollback survives for a later
|
||||||
// attach.
|
// attach.
|
||||||
record.bridge.seal();
|
record.bridge.seal();
|
||||||
|
|||||||
@@ -136,6 +136,7 @@ async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
|
|||||||
|
|
||||||
assert_eq!(session.view, SessionView::Structured);
|
assert_eq!(session.view, SessionView::Structured);
|
||||||
assert_eq!(session.status, SessionStatus::Running);
|
assert_eq!(session.status, SessionStatus::Running);
|
||||||
|
assert_eq!(session.activity, ActivityState::Idle);
|
||||||
let acp_id = session.acp_session_id.clone().expect("acp session id");
|
let acp_id = session.acp_session_id.clone().expect("acp session id");
|
||||||
assert!(acp_id.starts_with("fake-"), "{acp_id}");
|
assert!(acp_id.starts_with("fake-"), "{acp_id}");
|
||||||
|
|
||||||
@@ -204,6 +205,77 @@ async fn structured_spawn_starts_the_adapter_in_cwd_with_session_env() {
|
|||||||
.exists());
|
.exists());
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn structured_activity_tracks_turn_completion_and_failure() {
|
||||||
|
let fx = DaemonFixture::new();
|
||||||
|
let fake = Fake::new();
|
||||||
|
let cwd = TempDir::new().unwrap();
|
||||||
|
let mut env = fake.env();
|
||||||
|
env.insert("FAKE_ACP_DELAY_PROMPT_MS".into(), "100".into());
|
||||||
|
env.insert("FAKE_ACP_PROMPT_FAIL_ONCE".into(), "1".into());
|
||||||
|
let session = fx
|
||||||
|
.manager
|
||||||
|
.create(structured(cwd.path(), env))
|
||||||
|
.await
|
||||||
|
.unwrap();
|
||||||
|
|
||||||
|
assert!(matches!(
|
||||||
|
fx.manager
|
||||||
|
.queue_acp_prompt(session.id, "fail".into())
|
||||||
|
.await
|
||||||
|
.unwrap(),
|
||||||
|
maestro_daemon::session::QueueAcpPrompt::Queued
|
||||||
|
));
|
||||||
|
assert_eq!(
|
||||||
|
fx.manager
|
||||||
|
.snapshot()
|
||||||
|
.await
|
||||||
|
.into_iter()
|
||||||
|
.find(|candidate| candidate.id == session.id)
|
||||||
|
.unwrap()
|
||||||
|
.activity,
|
||||||
|
ActivityState::Active
|
||||||
|
);
|
||||||
|
wait_for_async(Duration::from_secs(2), || async {
|
||||||
|
fx.manager
|
||||||
|
.snapshot()
|
||||||
|
.await
|
||||||
|
.into_iter()
|
||||||
|
.find(|candidate| candidate.id == session.id)
|
||||||
|
.is_some_and(|candidate| candidate.activity == ActivityState::Error)
|
||||||
|
})
|
||||||
|
.await;
|
||||||
|
|
||||||
|
assert!(matches!(
|
||||||
|
fx.manager
|
||||||
|
.queue_acp_prompt(session.id, "succeed".into())
|
||||||
|
.await
|
||||||
|
.unwrap(),
|
||||||
|
maestro_daemon::session::QueueAcpPrompt::Queued
|
||||||
|
));
|
||||||
|
assert_eq!(
|
||||||
|
fx.manager
|
||||||
|
.snapshot()
|
||||||
|
.await
|
||||||
|
.into_iter()
|
||||||
|
.find(|candidate| candidate.id == session.id)
|
||||||
|
.unwrap()
|
||||||
|
.activity,
|
||||||
|
ActivityState::Active
|
||||||
|
);
|
||||||
|
wait_for_async(Duration::from_secs(2), || async {
|
||||||
|
fx.manager
|
||||||
|
.snapshot()
|
||||||
|
.await
|
||||||
|
.into_iter()
|
||||||
|
.find(|candidate| candidate.id == session.id)
|
||||||
|
.is_some_and(|candidate| candidate.activity == ActivityState::Idle)
|
||||||
|
})
|
||||||
|
.await;
|
||||||
|
|
||||||
|
fx.manager.kill(session.id, false).await.unwrap();
|
||||||
|
}
|
||||||
|
|
||||||
#[tokio::test]
|
#[tokio::test]
|
||||||
async fn projection_snapshot_and_live_stream_share_one_fold() {
|
async fn projection_snapshot_and_live_stream_share_one_fold() {
|
||||||
let fx = DaemonFixture::new();
|
let fx = DaemonFixture::new();
|
||||||
@@ -476,6 +548,16 @@ async fn recovery_loads_the_acp_session_without_duplicating_history() {
|
|||||||
revived.status(session.id).await,
|
revived.status(session.id).await,
|
||||||
Some(SessionStatus::Running)
|
Some(SessionStatus::Running)
|
||||||
);
|
);
|
||||||
|
assert_eq!(
|
||||||
|
revived
|
||||||
|
.snapshot()
|
||||||
|
.await
|
||||||
|
.into_iter()
|
||||||
|
.find(|candidate| candidate.id == session.id)
|
||||||
|
.unwrap()
|
||||||
|
.activity,
|
||||||
|
ActivityState::Idle
|
||||||
|
);
|
||||||
let log = fake.log();
|
let log = fake.log();
|
||||||
assert!(
|
assert!(
|
||||||
log.contains(&format!("recv session/load sessionId={acp_id}")),
|
log.contains(&format!("recv session/load sessionId={acp_id}")),
|
||||||
@@ -925,6 +1007,16 @@ async fn adapter_exit_marks_the_session_dead_and_keeps_it_listed() {
|
|||||||
fx.manager.status(session.id).await == Some(SessionStatus::Dead)
|
fx.manager.status(session.id).await == Some(SessionStatus::Dead)
|
||||||
})
|
})
|
||||||
.await;
|
.await;
|
||||||
|
assert_eq!(
|
||||||
|
fx.manager
|
||||||
|
.snapshot()
|
||||||
|
.await
|
||||||
|
.into_iter()
|
||||||
|
.find(|candidate| candidate.id == session.id)
|
||||||
|
.unwrap()
|
||||||
|
.activity,
|
||||||
|
ActivityState::Error
|
||||||
|
);
|
||||||
assert!(fx.manager.has(session.id).await);
|
assert!(fx.manager.has(session.id).await);
|
||||||
assert!(
|
assert!(
|
||||||
!fx.sidecar_dir()
|
!fx.sidecar_dir()
|
||||||
|
|||||||
@@ -11,7 +11,8 @@ use common::DaemonFixture;
|
|||||||
use futures_util::{SinkExt, StreamExt};
|
use futures_util::{SinkExt, StreamExt};
|
||||||
use maestro_daemon::local_api;
|
use maestro_daemon::local_api;
|
||||||
use maestro_protocol::{
|
use maestro_protocol::{
|
||||||
ApiError, CreateSessionRequest, Session, SessionStatus, SessionView, WorktreeSpec,
|
ActivityState, ApiError, CreateSessionRequest, Session, SessionStatus, SessionView,
|
||||||
|
WorktreeSpec,
|
||||||
};
|
};
|
||||||
use tempfile::TempDir;
|
use tempfile::TempDir;
|
||||||
use tokio::net::TcpListener;
|
use tokio::net::TcpListener;
|
||||||
@@ -167,6 +168,29 @@ async fn structured_session_with_env(h: &Harness, env: HashMap<String, String>)
|
|||||||
.id
|
.id
|
||||||
}
|
}
|
||||||
|
|
||||||
|
async fn wait_for_session_activity(h: &Harness, id: Uuid, expected: ActivityState) {
|
||||||
|
tokio::time::timeout(Duration::from_secs(2), async {
|
||||||
|
loop {
|
||||||
|
let sessions: Vec<Session> = reqwest::get(url(h.addr, "/api/sessions"))
|
||||||
|
.await
|
||||||
|
.unwrap()
|
||||||
|
.json()
|
||||||
|
.await
|
||||||
|
.unwrap();
|
||||||
|
if sessions
|
||||||
|
.iter()
|
||||||
|
.find(|session| session.id == id)
|
||||||
|
.is_some_and(|session| session.activity == expected)
|
||||||
|
{
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
tokio::time::sleep(Duration::from_millis(10)).await;
|
||||||
|
}
|
||||||
|
})
|
||||||
|
.await
|
||||||
|
.unwrap_or_else(|_| panic!("session {id} did not reach {expected:?}"));
|
||||||
|
}
|
||||||
|
|
||||||
#[tokio::test]
|
#[tokio::test]
|
||||||
async fn structured_ws_sends_snapshot_then_live_projection() {
|
async fn structured_ws_sends_snapshot_then_live_projection() {
|
||||||
let h = spawn("naps-laptop").await;
|
let h = spawn("naps-laptop").await;
|
||||||
@@ -318,6 +342,7 @@ async fn structured_approval_is_secret_single_use_and_race_safe() {
|
|||||||
})
|
})
|
||||||
.await
|
.await
|
||||||
.unwrap();
|
.unwrap();
|
||||||
|
wait_for_session_activity(&h, id, ActivityState::AwaitingInput).await;
|
||||||
assert!(
|
assert!(
|
||||||
!fake.log().contains(&nonce),
|
!fake.log().contains(&nonce),
|
||||||
"daemon nonce leaked to ACP agent"
|
"daemon nonce leaked to ACP agent"
|
||||||
@@ -373,6 +398,7 @@ async fn structured_approval_is_secret_single_use_and_race_safe() {
|
|||||||
})
|
})
|
||||||
.await
|
.await
|
||||||
.expect("resolved approval clears the reduced state");
|
.expect("resolved approval clears the reduced state");
|
||||||
|
wait_for_session_activity(&h, id, ActivityState::Idle).await;
|
||||||
assert_eq!(
|
assert_eq!(
|
||||||
client
|
client
|
||||||
.post(url(
|
.post(url(
|
||||||
@@ -429,6 +455,7 @@ async fn structured_prompt_failure_clears_the_turn() {
|
|||||||
})
|
})
|
||||||
.await
|
.await
|
||||||
.expect("failed turn clears promptly");
|
.expect("failed turn clears promptly");
|
||||||
|
wait_for_session_activity(&h, id, ActivityState::Error).await;
|
||||||
let second = client
|
let second = client
|
||||||
.post(url(h.addr, &path))
|
.post(url(h.addr, &path))
|
||||||
.json(&serde_json::json!({"prompt":"available"}))
|
.json(&serde_json::json!({"prompt":"available"}))
|
||||||
@@ -1350,6 +1377,73 @@ async fn events_ws_sends_a_snapshot_then_streams_deltas() {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn events_ws_streams_structured_activity_without_hook_overrides() {
|
||||||
|
let h = spawn("konishi").await;
|
||||||
|
let fake = FakeAcp::new();
|
||||||
|
let mut env = fake.env();
|
||||||
|
env.insert("FAKE_ACP_DELAY_PROMPT_MS".into(), "500".into());
|
||||||
|
let (mut ws, _) = connect_async(ws_url(h.addr, "/api/events"))
|
||||||
|
.await
|
||||||
|
.expect("events ws");
|
||||||
|
assert!(matches!(
|
||||||
|
next_event(&mut ws).await,
|
||||||
|
maestro_protocol::CatalogEvent::Snapshot { .. }
|
||||||
|
));
|
||||||
|
|
||||||
|
let id = structured_session_with_env(&h, env).await;
|
||||||
|
let maestro_protocol::CatalogEvent::SessionAdded { session } = next_event(&mut ws).await else {
|
||||||
|
panic!("expected structured SessionAdded")
|
||||||
|
};
|
||||||
|
assert_eq!(session.activity, ActivityState::Idle);
|
||||||
|
|
||||||
|
let client = reqwest::Client::new();
|
||||||
|
let prompt = client
|
||||||
|
.post(url(
|
||||||
|
h.addr,
|
||||||
|
&format!("/api/sessions/{id}/structured/prompt"),
|
||||||
|
))
|
||||||
|
.json(&serde_json::json!({"prompt": "hello"}))
|
||||||
|
.send()
|
||||||
|
.await
|
||||||
|
.unwrap();
|
||||||
|
assert_eq!(prompt.status(), reqwest::StatusCode::NO_CONTENT);
|
||||||
|
let report = client
|
||||||
|
.post(url(h.addr, &format!("/api/sessions/{id}/activity")))
|
||||||
|
.json(&serde_json::json!({"state": "Error"}))
|
||||||
|
.send()
|
||||||
|
.await
|
||||||
|
.unwrap();
|
||||||
|
assert_eq!(report.status(), reqwest::StatusCode::NO_CONTENT);
|
||||||
|
wait_for_session_activity(&h, id, ActivityState::Active).await;
|
||||||
|
|
||||||
|
let mut activities = Vec::new();
|
||||||
|
tokio::time::timeout(Duration::from_secs(2), async {
|
||||||
|
loop {
|
||||||
|
if let maestro_protocol::CatalogEvent::SessionUpdated { session } =
|
||||||
|
next_event(&mut ws).await
|
||||||
|
{
|
||||||
|
activities.push(session.activity);
|
||||||
|
if session.activity == ActivityState::Idle {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
.await
|
||||||
|
.expect("structured turn returns to idle");
|
||||||
|
assert!(
|
||||||
|
activities.contains(&ActivityState::Active),
|
||||||
|
"{activities:?}"
|
||||||
|
);
|
||||||
|
assert!(
|
||||||
|
!activities.contains(&ActivityState::Error),
|
||||||
|
"{activities:?}"
|
||||||
|
);
|
||||||
|
|
||||||
|
h.manager.kill(id, false).await.unwrap();
|
||||||
|
}
|
||||||
|
|
||||||
/// Each subscriber has its own lag domain now that the publisher task is gone:
|
/// Each subscriber has its own lag domain now that the publisher task is gone:
|
||||||
/// two clients connected at different times both get their own Snapshot.
|
/// two clients connected at different times both get their own Snapshot.
|
||||||
#[tokio::test]
|
#[tokio::test]
|
||||||
|
|||||||
@@ -156,9 +156,9 @@ pub enum SessionStatus {
|
|||||||
Dead,
|
Dead,
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Inferred session activity, orthogonal to [`SessionStatus`] (NAP-340). The
|
/// Session activity, orthogonal to [`SessionStatus`] (NAP-340). Terminal
|
||||||
/// daemon derives this from tmux pane state, PTY quiescence, and `/proc`
|
/// sessions use pane/process inference and agent reports; structured sessions
|
||||||
/// inspection — never by parsing the terminal byte stream.
|
/// use their ACP turn lifecycle (docs/SIDEBAR.md).
|
||||||
///
|
///
|
||||||
/// Deserializes leniently (#110, SIDEBAR.md Precedence): an unknown variant
|
/// Deserializes leniently (#110, SIDEBAR.md Precedence): an unknown variant
|
||||||
/// from a newer daemon becomes [`ActivityState::Idle`] instead of failing the
|
/// from a newer daemon becomes [`ActivityState::Idle`] instead of failing the
|
||||||
@@ -166,15 +166,14 @@ pub enum SessionStatus {
|
|||||||
/// forgiven.
|
/// forgiven.
|
||||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Default)]
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Default)]
|
||||||
pub enum ActivityState {
|
pub enum ActivityState {
|
||||||
/// Producing output, or the foreground process is busy.
|
/// Producing output, the foreground process is busy, or an ACP turn is active.
|
||||||
Active,
|
Active,
|
||||||
/// Foreground process alive but quiescent. The forward-compatible default.
|
/// Foreground process alive but quiescent. The forward-compatible default.
|
||||||
#[default]
|
#[default]
|
||||||
Idle,
|
Idle,
|
||||||
/// Blocked on a `read()` from the pty — waiting on the user.
|
/// Blocked on terminal input or waiting for an ACP approval.
|
||||||
AwaitingInput,
|
AwaitingInput,
|
||||||
/// The agent running in the session reported a failure (#102). Never
|
/// An agent reported a failure, or a structured session/turn failed.
|
||||||
/// inferred by the daemon; only set when an agent reports it (#105).
|
|
||||||
Error,
|
Error,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
+15
-5
@@ -18,10 +18,14 @@ wizard, and cleans up — only the unified `maestro` binary ends up persisted in
|
|||||||
|
|
||||||
**Updating is the same command.** Re-running `./install.sh` detects an existing
|
**Updating is the same command.** Re-running `./install.sh` detects an existing
|
||||||
systemd unit, refreshes it, and runs `systemctl --user restart maestro` instead
|
systemd unit, refreshes it, and runs `systemctl --user restart maestro` instead
|
||||||
of `start`. No `--update` flag needed. **The restart keeps your sessions:** the unit sets
|
of `start`. No `--update` flag needed. **The restart keeps your terminal sessions:** the unit sets
|
||||||
`KillMode=process`, so systemd signals only the daemon — the tmux server (and
|
`KillMode=process`, so systemd signals only the daemon — the tmux server (and
|
||||||
every session) survives, and the new daemon re-adopts them on start. A unit
|
every tmux-backed session) survives, and the new daemon re-adopts them on
|
||||||
written before this default lacks the line; re-run `./install.sh` to refresh it.
|
start. Structured sessions (an agent run as a daemon child over ACP) are not
|
||||||
|
tmux panes, so shutdown ends their active turn; the transcript survives and
|
||||||
|
the next daemon attempts one resume (`docs/RESTART.md#structured-sessions`). A
|
||||||
|
unit written before this default lacks the line; re-run `./install.sh` to
|
||||||
|
refresh it.
|
||||||
|
|
||||||
Inside the script, `cargo install --git https://git.naps.pt/naps62/maestro …`
|
Inside the script, `cargo install --git https://git.naps.pt/naps62/maestro …`
|
||||||
uses your already-configured git credentials for this host (HTTPS helper or
|
uses your already-configured git credentials for this host (HTTPS helper or
|
||||||
@@ -94,7 +98,10 @@ running a local daemon, for a host that only talks to another machine's.
|
|||||||
|
|
||||||
The daemon unit carries the same `KillMode=process` as the wizard-written one,
|
The daemon unit carries the same `KillMode=process` as the wizard-written one,
|
||||||
so `systemctl --user restart maestro-daemon` leaves the tmux server and every
|
so `systemctl --user restart maestro-daemon` leaves the tmux server and every
|
||||||
session alive.
|
terminal session alive. Structured sessions end their active turn on
|
||||||
|
shutdown and resume once on the next daemon: ACP state comes back via
|
||||||
|
`session/load`, while the event log only replays Maestro's own transcript
|
||||||
|
projection (`docs/RESTART.md#structured-sessions`).
|
||||||
|
|
||||||
## Thin builds for single-role hosts
|
## Thin builds for single-role hosts
|
||||||
|
|
||||||
@@ -211,7 +218,10 @@ what to run. The adapter is a child of the daemon: it ends with a `DELETE
|
|||||||
itself. A daemon restart ends an in-flight structured turn, but preserves its
|
itself. A daemon restart ends an in-flight structured turn, but preserves its
|
||||||
worktree, session record, and event-log transcript. The replacement daemon
|
worktree, session record, and event-log transcript. The replacement daemon
|
||||||
starts a new adapter, resumes it with `session/load`, and replays the
|
starts a new adapter, resumes it with `session/load`, and replays the
|
||||||
transcript. Terminal sessions keep surviving restarts through tmux.
|
transcript. Terminal sessions keep surviving restarts through tmux. See
|
||||||
|
`docs/STRUCTURED-VIEW.md` for the full contract — row kinds, projections, the
|
||||||
|
handshake, and the approval and recovery rules — and `docs/RESTART.md` for
|
||||||
|
what a client observes across the restart.
|
||||||
|
|
||||||
## The browser UI
|
## The browser UI
|
||||||
|
|
||||||
|
|||||||
+39
-4
@@ -2,10 +2,16 @@
|
|||||||
|
|
||||||
Maestro is upgraded in place: the operator reinstalls the binary and systemd
|
Maestro is upgraded in place: the operator reinstalls the binary and systemd
|
||||||
restarts the daemon under every browser tab and TUI that is attached to it.
|
restarts the daemon under every browser tab and TUI that is attached to it.
|
||||||
tmux keeps the sessions alive across that (see `docs/INSTALL.md`), but clients
|
tmux keeps **terminal** sessions alive across that (see `docs/INSTALL.md`),
|
||||||
lose their sockets. This document is the contract for what a client does about
|
but clients lose their sockets either way. This document is the contract for
|
||||||
it — what the daemon publishes, how a client tells a restart from a blip, and
|
what a client does about it — what the daemon publishes, how a client tells a
|
||||||
what the user sees while it happens.
|
restart from a blip, and what the user sees while it happens.
|
||||||
|
|
||||||
|
A **structured** session (`docs/STRUCTURED-VIEW.md`) has no tmux pane behind
|
||||||
|
it to survive on: its agent is a child of the daemon process itself, so a
|
||||||
|
restart takes it down with the daemon. See
|
||||||
|
[Structured sessions](#structured-sessions) below for exactly what that
|
||||||
|
costs and what it doesn't.
|
||||||
|
|
||||||
## What the daemon publishes
|
## What the daemon publishes
|
||||||
|
|
||||||
@@ -68,6 +74,35 @@ resolves, so a blocked client is never a trapped one. It clears itself the
|
|||||||
moment a probe succeeds — there is no "retry" button, because the client is
|
moment a probe succeeds — there is no "retry" button, because the client is
|
||||||
already retrying.
|
already retrying.
|
||||||
|
|
||||||
|
## Structured sessions
|
||||||
|
|
||||||
|
Everything above describes a **client's** view of a restart, and it holds for
|
||||||
|
a structured session exactly as written — the same three verdicts, the same
|
||||||
|
status indicator, the same overlay. What differs is what survives on the
|
||||||
|
**daemon** side, because a structured session's agent is a daemon child, not
|
||||||
|
a tmux pane:
|
||||||
|
|
||||||
|
- A restart **ends the active turn**. There is no adapter process left to
|
||||||
|
finish it, and no tmux pane keeping it alive underneath.
|
||||||
|
- The **transcript survives**, in the per-session event log
|
||||||
|
(`docs/STRUCTURED-VIEW.md#persistence-recovery-and-dead-sessions`) — a
|
||||||
|
graceful shutdown marks the session for one resume attempt. Recovery is
|
||||||
|
two separate operations, not one: the next daemon calls `session/load` so
|
||||||
|
the adapter restores its own ACP session, but whatever history the
|
||||||
|
adapter emits during that call is discarded, not replayed into anything —
|
||||||
|
the daemon already has that history on disk. Separately, the daemon
|
||||||
|
rebuilds its own projection by folding the persisted event log back
|
||||||
|
through it. An ungraceful death (a crash, `kill -9`) leaves no resume
|
||||||
|
marker, and the session stays dead permanently.
|
||||||
|
- **Pending approvals and their nonces do not survive.** Both live only in
|
||||||
|
the old daemon's memory; any ACP permission request still mid-flight when
|
||||||
|
the daemon exits is answered `Cancelled` on the way down, and a resumed
|
||||||
|
session starts with no pending approval at all.
|
||||||
|
|
||||||
|
`docs/STRUCTURED-VIEW.md` is the full contract for all of this — the event
|
||||||
|
log's shape, the recovery marker, and exactly which kind of session death is
|
||||||
|
resumable.
|
||||||
|
|
||||||
## Timing
|
## Timing
|
||||||
|
|
||||||
- **Grace window** — 1200 ms between the socket dropping and the overlay
|
- **Grace window** — 1200 ms between the socket dropping and the overlay
|
||||||
|
|||||||
+22
-5
@@ -231,7 +231,24 @@ cutover points land within one tick.
|
|||||||
|
|
||||||
## Precedence
|
## Precedence
|
||||||
|
|
||||||
An agent-reported `ActivityState` (#105) overrides the daemon's inference for
|
### Activity source by session kind
|
||||||
|
|
||||||
|
The daemon supplies one `activity` field to both clients, but its source depends
|
||||||
|
on the session kind:
|
||||||
|
|
||||||
|
| Session kind | Source |
|
||||||
|
|---|---|
|
||||||
|
| Terminal | The existing agent-report override and five-minute TTL, falling back to PTY quiescence, foreground process and `/proc` input-block inference. |
|
||||||
|
| Structured | ACP state directly: a pending approval is `AwaitingInput`; otherwise an in-flight turn is `Active`; no turn is `Idle`. A failed turn or dead structured session is `Error`, and the next turn clears a failed-turn error. |
|
||||||
|
|
||||||
|
Structured sessions never enter the terminal inference path and ignore activity
|
||||||
|
reports inherited through agent hooks. They have no PTY whose output or blocked
|
||||||
|
read could describe their state. This is a second source, not a replacement for
|
||||||
|
the terminal source.
|
||||||
|
|
||||||
|
### Terminal report override
|
||||||
|
|
||||||
|
For terminal sessions, an agent-reported `ActivityState` (#105) overrides the daemon's inference for
|
||||||
**five minutes** (the TTL is fixed by the daemon; re-reporting extends it).
|
**five minutes** (the TTL is fixed by the daemon; re-reporting extends it).
|
||||||
When the TTL expires, inference resumes and the session's reported detail —
|
When the TTL expires, inference resumes and the session's reported detail —
|
||||||
if any — clears with the report. Clients never blend the two: whichever source
|
if any — clears with the report. Clients never blend the two: whichever source
|
||||||
@@ -281,10 +298,10 @@ session is genuinely `Active` again — new work, not merely a refocus. Only
|
|||||||
after that fresh `Active` cycle does the *next* `AwaitingInput` glow again.
|
after that fresh `Active` cycle does the *next* `AwaitingInput` glow again.
|
||||||
Unfocusing and refocusing alone never re-arms it.
|
Unfocusing and refocusing alone never re-arms it.
|
||||||
|
|
||||||
This applies uniformly to `AwaitingInput` from either source — the daemon's
|
This applies uniformly to `AwaitingInput` from terminal inference, an agent
|
||||||
own inference or an agent's report (#105) — since the rail draws them
|
report (#105), or a structured session's pending approval, since the rail draws
|
||||||
identically. It does not touch `Error`; that state's own TTL (below) is
|
them identically. It does not touch `Error`; terminal reports keep their TTL,
|
||||||
unrelated and unaffected by focus.
|
while a structured failed-turn error clears when the next turn starts.
|
||||||
|
|
||||||
Each client reports its own pane's focus with `POST /api/sessions/:id/focus`
|
Each client reports its own pane's focus with `POST /api/sessions/:id/focus`
|
||||||
(`{"focused": bool}`) whenever the pane it is showing changes — on attach, on
|
(`{"focused": bool}`) whenever the pane it is showing changes — on attach, on
|
||||||
|
|||||||
@@ -0,0 +1,359 @@
|
|||||||
|
# STRUCTURED-VIEW.md — the structured session contract
|
||||||
|
|
||||||
|
The contract for a structured session (`view: Structured`, #133): an agent run
|
||||||
|
as a daemon child over the Agent Client Protocol (ACP) instead of in a tmux
|
||||||
|
pane. Alongside `docs/WORKTREES.md`, `docs/SIDEBAR.md` and `docs/RESTART.md`,
|
||||||
|
read this before changing anything that renders a structured session — both
|
||||||
|
the web and TUI renderers are written against it.
|
||||||
|
|
||||||
|
It covers the eight transcript row kinds, what the daemon decides versus what
|
||||||
|
a client decides, the two projections and their delta/cursor semantics, the
|
||||||
|
ACP handshake and the capabilities it declines, the adapter's install
|
||||||
|
command, and the approval nonce rules. **Non-goal: the detached runner.** It
|
||||||
|
does not exist yet, and nothing here describes it.
|
||||||
|
|
||||||
|
## What a structured session is
|
||||||
|
|
||||||
|
A terminal session's agent runs inside a tmux pane; a structured session's
|
||||||
|
agent runs as a subprocess of the daemon itself, speaking ACP over stdio. The
|
||||||
|
daemon is the ACP **client**; the adapter process, `claude-code-acp`, is the
|
||||||
|
ACP **agent** — it wraps Claude Code's own SDK and translates the model's
|
||||||
|
tool calls into ACP `session/update` notifications instead of drawing them to
|
||||||
|
a pane. `crates/maestro-acp` owns the daemon's side of that connection;
|
||||||
|
`crates/maestro-daemon/src/projection.rs` folds what it receives into the two
|
||||||
|
projections below.
|
||||||
|
|
||||||
|
The child is a real child of the daemon process: same process group, and on
|
||||||
|
Linux marked with `PR_SET_PDEATHSIG` so it dies with the daemon even if the
|
||||||
|
daemon exits without cleaning up; other platforms have no such signal and
|
||||||
|
depend on an orderly shutdown/drop to terminate it. The ordinary path on
|
||||||
|
every platform is `AcpSession::terminate` (`session/cancel`, a short grace,
|
||||||
|
`SIGTERM`, then `SIGKILL`), called from both `DELETE /api/sessions/:id` and
|
||||||
|
daemon shutdown.
|
||||||
|
`docs/WORKTREES.md`'s kill-guard rule — an unforced kill refused while the
|
||||||
|
session's worktree holds unsaved work — applies to a structured session
|
||||||
|
exactly as it does to a terminal one; only what gets terminated differs (an
|
||||||
|
ACP handle instead of a tmux pane).
|
||||||
|
|
||||||
|
## The adapter
|
||||||
|
|
||||||
|
`ADAPTER_BIN` (`claude-code-acp`) is resolved by walking `PATH` — the
|
||||||
|
session's own `PATH` env var if the spawn request set one, the daemon's
|
||||||
|
otherwise — and taking the first executable file named `claude-code-acp` on
|
||||||
|
it. Install it once per host:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm install -g --prefix ~/.local @zed-industries/claude-code-acp
|
||||||
|
```
|
||||||
|
|
||||||
|
That is `maestro_acp::INSTALL_COMMAND`, and it is not just documentation: it
|
||||||
|
is baked into `AcpError::AdapterMissing`'s message. When the adapter cannot
|
||||||
|
be found, spawn still creates the session — **Dead**, with that install
|
||||||
|
command as its `activity_detail` — so the sidebar names the fix instead of
|
||||||
|
the session silently never appearing (see `docs/INSTALL.md` for the full
|
||||||
|
install writeup, including the systemd `PATH` caveat). The adapter also needs
|
||||||
|
a logged-in Claude Code (`claude /login`); a missing login surfaces the same
|
||||||
|
way, via the adapter's own stderr tail in the failure message.
|
||||||
|
|
||||||
|
The handshake is bounded by `HANDSHAKE_TIMEOUT` (60s) — long enough for a
|
||||||
|
slow machine to boot a node process and the Claude Code SDK behind it, never
|
||||||
|
long enough to hang a spawn indefinitely. Any handshake failure — missing
|
||||||
|
adapter, early exit, a protocol error, or the timeout — leaves no orphaned
|
||||||
|
process: `spawn` closes and reaps the child itself before returning the
|
||||||
|
error.
|
||||||
|
|
||||||
|
## The ACP handshake
|
||||||
|
|
||||||
|
`initialize` is where the daemon states what kind of client it is. It
|
||||||
|
declares, deliberately, almost nothing:
|
||||||
|
|
||||||
|
| Capability | Declared | Why |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `fs.readTextFile` | `false` | The adapter uses Claude Code's own Read tool instead of asking the daemon to read a file on its behalf — the same tool a terminal-view Claude Code session uses. |
|
||||||
|
| `fs.writeTextFile` | `false` | Same reasoning, for Write. |
|
||||||
|
| `terminal` | `false` | The adapter runs Claude Code's own Bash tool rather than asking the daemon to open a terminal for it. |
|
||||||
|
|
||||||
|
Declining all three keeps the daemon out of the file/terminal surface
|
||||||
|
entirely — the adapter already has direct access to the session's `cwd`, and
|
||||||
|
routing every read, write, and shell command through the daemon would only
|
||||||
|
add a hop with no new capability. Every other capability namespace ACP
|
||||||
|
defines (session extensions, auth, elicitation) is simply left at its
|
||||||
|
default; the daemon does not advertise support because `claude-code-acp` has
|
||||||
|
never asked for it, not because it was weighed and refused.
|
||||||
|
|
||||||
|
The one client method that *is* implemented for real is
|
||||||
|
`session/request_permission` (#139) — see [Approvals](#approvals) below.
|
||||||
|
Before #139 it was a stub that declined every request; that stub is gone now
|
||||||
|
that a live implementation exists.
|
||||||
|
|
||||||
|
`session/new` opens a fresh ACP session on every ordinary spawn. A respawn
|
||||||
|
after a daemon restart instead sets `SpawnConfig::load_session(id)` and runs
|
||||||
|
`session/load` with the ACP session id the original handshake returned
|
||||||
|
(`Session::acp_session_id` on the wire) — the adapter must advertise
|
||||||
|
`agent_capabilities.load_session`, or the handshake fails outright naming
|
||||||
|
that. Whatever history the adapter streams back while `session/load` is in
|
||||||
|
flight is dropped on arrival, deliberately: the daemon's own event log
|
||||||
|
already holds that history, and forwarding it too would duplicate every row
|
||||||
|
in the projections below.
|
||||||
|
|
||||||
|
## The eight transcript row kinds
|
||||||
|
|
||||||
|
`TranscriptRowKind` (`maestro-protocol`) is the alphabet a structured
|
||||||
|
transcript is written in. Every row has a stable `id` (so later deltas can
|
||||||
|
address it), a `kind`, and a `data: Value` that preserves the underlying ACP
|
||||||
|
payload — clients depend on ACP's *shape* without depending on ACP as a
|
||||||
|
crate.
|
||||||
|
|
||||||
|
| Kind | Carries | Row identity |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `User` | An echoed `user_message_chunk` — the prompt text as ACP saw it. | `user:<message_id>`, or `user:<seq>` when the chunk carries no id. |
|
||||||
|
| `AgentText` | An `agent_message_chunk` — the agent's visible reply, streamed. | `agent:<message_id>` / `agent:<seq>`. Later chunks for the same id are appended into `data.content.text` in place, not appended as new rows. |
|
||||||
|
| `AgentThought` | An `agent_thought_chunk` — the model's reasoning stream. | `thought:<message_id>` / `thought:<seq>`, coalesced the same way as `AgentText`. |
|
||||||
|
| `ToolCall` | A `tool_call` / `tool_call_update` pair whose content carries no diff. | `tool:<tool_call_id>` — one row for the call's whole life; updates patch it in place, they never create a second row. |
|
||||||
|
| `ToolDiff` | The same tool-call machinery, when the tool's content includes a `Diff` block. | Same `tool:<tool_call_id>` identity as `ToolCall`; the *kind* flips between the two as the tool's own content changes, not the row. |
|
||||||
|
| `Approval` | A daemon-originated permission request (`RequestPermissionRequest`), serialized without its nonce. | `approval:<uuid>` — minted fresh per request, unrelated to the ACP request's own id. |
|
||||||
|
| `Plan` | A `plan` update — the agent's current step list. | The fixed id `"plan"`. Each new plan **replaces** the row wholesale; entries are not diffed against the previous plan. |
|
||||||
|
| `Notice` | The raw JSON of any `session/update` variant the projection does not special-case. | `notice:<seq>`. |
|
||||||
|
|
||||||
|
`Notice` is the projection's forward-compatibility seam: ACP adds
|
||||||
|
notification variants over time, and an unrecognised one becomes a generic
|
||||||
|
row instead of being silently dropped or making the daemon reject the whole
|
||||||
|
stream. A client that does not know what to do with a `Notice` can render it
|
||||||
|
as an opaque, collapsed line — that is a reasonable floor, not a client bug.
|
||||||
|
|
||||||
|
Rendering is entirely a client concern. The projection's job stops at
|
||||||
|
folding ACP into these eight shapes; markdown formatting, diff rendering,
|
||||||
|
tool-card treatment, and how a `Notice` is presented are all renderer
|
||||||
|
choices, not daemon ones.
|
||||||
|
|
||||||
|
## Daemon decisions vs. client decisions
|
||||||
|
|
||||||
|
**The daemon decides:**
|
||||||
|
|
||||||
|
- Which ACP `session/update` becomes which row kind, and under what id — the
|
||||||
|
fold in `projection.rs` is the one place this logic lives, so the web and
|
||||||
|
TUI renderers can never disagree about it.
|
||||||
|
- Turn lifecycle: when a turn begins, and whether an ACP response, a cancel,
|
||||||
|
or a failure ends it (`TurnState.responding` / `.thinking` /
|
||||||
|
`.active_tool_calls` are derived, not renderer-computed).
|
||||||
|
- Approval nonce minting, secrecy, and the single-active-approval rule (see
|
||||||
|
below) — a client never sees an ACP permission request before the daemon
|
||||||
|
has already turned it into an `Approval` row and a nonce.
|
||||||
|
- What happens to an ACP update variant nobody has taught the daemon about
|
||||||
|
yet (falls back to `Notice` rather than erroring).
|
||||||
|
- Persistence and replay: what is written to the event log, in what order,
|
||||||
|
and how a restart resumes it.
|
||||||
|
|
||||||
|
**A client decides:**
|
||||||
|
|
||||||
|
- How each row kind is drawn — markdown for `AgentText`/`AgentThought`, a
|
||||||
|
diff view for `ToolDiff`, a tool card for `ToolCall`, a checklist for
|
||||||
|
`Plan`, and a floor presentation for `Notice`.
|
||||||
|
- How `responding` vs. `thinking` are distinguished visually, if at all.
|
||||||
|
- How the operator is asked to resolve an `Approval` row — the daemon only
|
||||||
|
exposes the three-way decision (`AllowOnce` / `AllowForSession` / `Deny`),
|
||||||
|
never the UI that solicits it.
|
||||||
|
- Scrolling, collapsing, and every other presentation-only behaviour.
|
||||||
|
|
||||||
|
## The two projections
|
||||||
|
|
||||||
|
`Projection` (daemon-only) is folded once from the durable ACP stream and
|
||||||
|
exposes two independent views, both defined in `maestro-protocol`:
|
||||||
|
|
||||||
|
- **`TranscriptSnapshot { cursor, rows }`** — the complete ordered list of
|
||||||
|
transcript rows built so far, plus the log position (`cursor`) it reflects.
|
||||||
|
It is intentionally always the *whole* transcript, not a windowed one: a
|
||||||
|
tool row patched much later must still find its original entry.
|
||||||
|
- **`ReducedState`** — one whole-session snapshot folded over every event
|
||||||
|
seen: `turn` (the per-turn indicators above), `pending_approval`, `plan`,
|
||||||
|
`usage`/`context`, `model`, and `mode`. Like `TranscriptSnapshot`, it is
|
||||||
|
always full-history, never a delta — a client that only wants "is a turn
|
||||||
|
active right now" never has to replay anything to answer that.
|
||||||
|
|
||||||
|
Changes to the transcript travel as `TranscriptDelta`, tagged `type`:
|
||||||
|
`Append { row }` (a new row), `Patch { row }` (an existing row, addressed by
|
||||||
|
`id`, replaced wholesale), and `Remove { id }`. `Remove` is defined on the
|
||||||
|
wire for forward compatibility; nothing in the current projection emits it —
|
||||||
|
every row, once appended, is only ever patched or left alone.
|
||||||
|
|
||||||
|
### Cursor and replay semantics
|
||||||
|
|
||||||
|
The event log's own line position is the cursor: 1-based, shared by ACP
|
||||||
|
notifications and daemon-generated rows alike (`sidecar.rs`'s
|
||||||
|
`PersistedEvent` envelope is what lets an `Approval` row share a cursor
|
||||||
|
sequence with raw ACP JSON without pretending to be ACP traffic). Two ways to
|
||||||
|
read it:
|
||||||
|
|
||||||
|
- **`WS /api/structured/:id`** — on connect, sends a `TranscriptSnapshot` and
|
||||||
|
a `ReducedState` covering the whole log as it stands, then streams
|
||||||
|
`ProjectionUpdate { transcript, state }` for everything that happens next.
|
||||||
|
There is no client-supplied resume cursor on this socket: every connection
|
||||||
|
gets the full snapshot, not a gap-filled continuation, so a client never
|
||||||
|
needs the replay endpoint just to obtain the current transcript. Use
|
||||||
|
replay instead for cursor-bounded pagination through the durable log —
|
||||||
|
history from before this connection, fetched a page at a time.
|
||||||
|
- **`GET /api/sessions/:id/structured/replay`** — cursor-bounded pagination
|
||||||
|
over the durable log, returning one `StructuredReplayEvent` (`cursor`,
|
||||||
|
`transcript`, `state`) per matching line. `?since=<n>` returns the first
|
||||||
|
page after `n` (`since=0` selects from the beginning, i.e. the first
|
||||||
|
page); a client pages forward from there using the cursor of the last
|
||||||
|
event returned. `?before=<n>` returns the page immediately before `n`,
|
||||||
|
still in ascending order — passing both is a `400`. `?limit` defaults to
|
||||||
|
100 and is clamped to 500. Each call re-folds
|
||||||
|
the entire log from scratch to compute the state at every returned cursor,
|
||||||
|
so a page reflects exactly the *durable* state at its cursor, not an
|
||||||
|
approximation of it — at the cost of redoing the whole fold per request.
|
||||||
|
That durable state is not always identical to what a live client saw at
|
||||||
|
that moment, though: turn lifecycle transitions are broadcast live without
|
||||||
|
a durable event backing them (see [Prompt and cancel](#prompt-and-cancel-bounded-liveness)),
|
||||||
|
and a restored `Approval` row carries no pending nonce, because the nonce
|
||||||
|
never reached disk (see [Approvals](#approvals)) — replay is exact and
|
||||||
|
reconstructible, not a perfect record of everything the live view showed.
|
||||||
|
A session that is not a live structured session (terminal, or a dead
|
||||||
|
adapter) answers `409 not_structured` from either route rather than a
|
||||||
|
coherent-looking but stale reply.
|
||||||
|
|
||||||
|
## Approvals
|
||||||
|
|
||||||
|
An ACP `session/request_permission` callback becomes an `Approval` row plus a
|
||||||
|
pending decision, entirely on the daemon side:
|
||||||
|
|
||||||
|
- **Generation.** The daemon mints the nonce itself — a fresh
|
||||||
|
`Uuid::new_v4()` string per request — rather than using anything ACP's own
|
||||||
|
request carries. ACP permission callbacks have no request id of their own
|
||||||
|
that would double as one.
|
||||||
|
- **Live-only placement.** The nonce lives in exactly one place: the
|
||||||
|
in-memory `pending_approvals` map keyed by nonce, and its mirror in
|
||||||
|
`ReducedState.pending_approval.nonce` on the live wire. It is never part of
|
||||||
|
the `Approval` row's `data` — the row is `RequestPermissionRequest`
|
||||||
|
serialized *without* the nonce.
|
||||||
|
- **Secrecy from the agent and from durable history.** The adapter itself
|
||||||
|
never learns the nonce — it is a daemon-to-client secret, never sent back
|
||||||
|
over the ACP connection. It is likewise never written to the event log:
|
||||||
|
restoring an `Approval` row from disk (`Projection::restore_approval`)
|
||||||
|
produces a historical row with no `pending_approval` in state, because the
|
||||||
|
nonce that would make it "pending" never made it to disk in the first
|
||||||
|
place. A restart therefore cannot resume a pending approval — see
|
||||||
|
[Persistence](#persistence-recovery-and-dead-sessions).
|
||||||
|
- **One live approval at a time.** A new permission request mints its own
|
||||||
|
nonce, then cancels whatever was already pending (`cancel_pending_approvals`)
|
||||||
|
before installing itself as the new pending approval — ACP serializes
|
||||||
|
requests through one connection, so this only ever fires if an adapter
|
||||||
|
nonetheless overlaps two. Either way, the prior pending request is
|
||||||
|
cancelled/cleared before the new one is installed, so the newest request
|
||||||
|
wins.
|
||||||
|
- **Single-use and duplicate resolution.**
|
||||||
|
`POST /api/sessions/:id/structured/approvals/:nonce` **always answers
|
||||||
|
`204`** for a known, live structured session — whether the nonce is the
|
||||||
|
one currently pending, one already consumed by an earlier answer, or one
|
||||||
|
that never existed. Only an unknown or non-structured *session* answers
|
||||||
|
otherwise (`404` / `409`). This is deliberate: two clients racing to answer the same
|
||||||
|
approval must not turn a harmless duplicate click into a client-visible
|
||||||
|
error. Whichever `POST` reaches the daemon first removes the nonce from
|
||||||
|
`pending_approvals` and is the one whose decision actually reaches the
|
||||||
|
adapter; every later `POST` for that nonce is a no-op `204`.
|
||||||
|
- **Cancellation vs. denial.** A turn cancel or a session shutdown resolves
|
||||||
|
any pending approval with ACP's `Cancelled` outcome, not a `Deny` decision
|
||||||
|
— the adapter should read those as "the operation was withdrawn," not "the
|
||||||
|
operator refused it."
|
||||||
|
- **Decision mapping.** `AllowOnce` and `AllowForSession` select the ACP
|
||||||
|
option of kind `AllowOnce` / `AllowAlways` from the request's own option
|
||||||
|
list. `Deny` prefers a one-shot refusal (`RejectOnce`) and falls back to a
|
||||||
|
permanent one (`RejectAlways`) only when that is the sole rejection option
|
||||||
|
offered; if neither is present, it answers `Cancelled`.
|
||||||
|
|
||||||
|
## Prompt and cancel: bounded liveness
|
||||||
|
|
||||||
|
`POST /api/sessions/:id/structured/prompt` and `.../cancel` are serialized
|
||||||
|
against each other through one per-session `operation` lock
|
||||||
|
(`AcpEventStream::operation`), because ACP permission callbacks carry no
|
||||||
|
per-request id — the daemon's own notion of "the active turn" is the only
|
||||||
|
thing a callback can be attributed to, so at most one turn may ever be
|
||||||
|
in flight, and a cancelled turn must fully settle before the next prompt is
|
||||||
|
allowed to claim the daemon's idea of "the active turn."
|
||||||
|
|
||||||
|
- A prompt claims the turn and dispatches it to ACP as one operation. While a
|
||||||
|
turn is active, a second prompt gets `409 turn_in_flight` rather than
|
||||||
|
queuing — one active turn per session, never a hidden queue of prompts.
|
||||||
|
- Cancel sends `session/cancel`, clears any pending approval as `Cancelled`,
|
||||||
|
and ends the turn's client-visible lifecycle immediately. If the cancelled
|
||||||
|
turn was still *dispatched* to ACP (waiting on its response), the daemon
|
||||||
|
cannot simply forget it: ACP has not confirmed the cancel yet, and a new
|
||||||
|
prompt claiming "the active turn" while the old one is still outstanding
|
||||||
|
would make the next permission callback ambiguous between the two.
|
||||||
|
- So a cancelled-but-still-dispatched turn must **settle within
|
||||||
|
`CANCEL_GRACE` (500ms)** — either ACP acknowledges the prompt (however it
|
||||||
|
resolves) or that grace period runs out. If it settles in time, the next
|
||||||
|
prompt proceeds normally. If it does not, the daemon does not guess: it
|
||||||
|
marks the whole structured session dead (`fail_cancelled_acp_turn`) rather
|
||||||
|
than risk a callback resolving against the wrong turn. This is the bounded
|
||||||
|
half of "bounded liveness" — a structured session's prompt/cancel dance
|
||||||
|
either resolves promptly or the session is declared unusable, never left
|
||||||
|
in an indefinite ambiguous state.
|
||||||
|
|
||||||
|
## Persistence, recovery, and dead sessions
|
||||||
|
|
||||||
|
A structured session's durable state is three files in the sidecar
|
||||||
|
directory: the sidecar itself (`<id>.json`), plus two next to it:
|
||||||
|
|
||||||
|
- **`<id>.events.jsonl`** — the unified event log. Each line is either a raw
|
||||||
|
ACP `SessionNotification` (kept in its original JSON so old logs stay
|
||||||
|
readable) or a `{"maestroEvent": "approval", "row": …}` envelope for a
|
||||||
|
daemon-generated row. Both share the same 1-based line-position cursor. A
|
||||||
|
line a hard kill left half-written is terminated before the next append, so
|
||||||
|
it keeps its position and is skipped as malformed rather than corrupting
|
||||||
|
what follows.
|
||||||
|
- **`<id>.recover`** — an empty marker file. Its only meaning is "the daemon
|
||||||
|
that wrote this shut down gracefully while this session was running, and
|
||||||
|
the next daemon may attempt to resume it." It is consumed (deleted) the
|
||||||
|
moment a recovery attempt reads it — one recovery attempt per graceful
|
||||||
|
shutdown, never a standing flag.
|
||||||
|
|
||||||
|
Three ways a structured session ends up `Dead`, each with different
|
||||||
|
persistence consequences:
|
||||||
|
|
||||||
|
1. **The adapter exits, or a notification append to the event log fails,
|
||||||
|
while the daemon keeps running.** (An approval-row append failure is
|
||||||
|
narrower: it cancels the pending approval and lets the session continue,
|
||||||
|
without marking it dead.) `mark_session_dead` applies the same
|
||||||
|
natural-exit worktree rule
|
||||||
|
as a terminal session's own pane exiting (`docs/WORKTREES.md`): a pristine
|
||||||
|
worktree is removed, one holding unsaved work is left on disk. No recovery
|
||||||
|
marker is written. This death is permanent — a later daemon restart's
|
||||||
|
`recover()` finds the sidecar, sees no marker, and leaves the session
|
||||||
|
`Dead` without attempting to resume it.
|
||||||
|
2. **A cancelled turn fails to settle within `CANCEL_GRACE`.** Same
|
||||||
|
consequence as (1): the session is marked dead through the same path, no
|
||||||
|
marker, no future resumption.
|
||||||
|
3. **Graceful daemon shutdown**, while the session was still `Running`.
|
||||||
|
`mark_session_dead_after_shutdown` marks the session dead **without**
|
||||||
|
applying the worktree exit rule — the tree is kept exactly as it is,
|
||||||
|
pristine or not, because there is nothing "natural" about this exit — and
|
||||||
|
writes the `.recover` marker. The sidecar on disk therefore says `Dead`,
|
||||||
|
but is eligible for resumption.
|
||||||
|
|
||||||
|
Recovery, on the next daemon's `recover()`: for every `Structured` sidecar
|
||||||
|
not already adopted, the marker is consumed. When one was present and the
|
||||||
|
sidecar carries a stored `acp_session_id`, the daemon spawns a fresh adapter
|
||||||
|
with `SpawnConfig::load_session(acp_session_id)`, replays the
|
||||||
|
entire durable event log into a new `Projection` (rebuilding the transcript
|
||||||
|
and reduced state exactly as they were, with any restored `Approval` row
|
||||||
|
landing as history — never as a re-armed pending approval, since its nonce
|
||||||
|
never reached disk), and only then reopens the log for further appends. What
|
||||||
|
the adapter streams back while its own `session/load` is in flight is
|
||||||
|
discarded rather than appended, so the replayed history is not duplicated
|
||||||
|
(see [The ACP handshake](#the-acp-handshake)). Success flips the session back
|
||||||
|
to `Running`/`Idle`; failure (no stored `acp_session_id`, or the handshake
|
||||||
|
itself failing) leaves it `Dead` with the failure reason as
|
||||||
|
`activity_detail` — the same "tell the operator what to fix" pattern as a
|
||||||
|
missing adapter binary.
|
||||||
|
|
||||||
|
Pending approvals and their nonces never survive any of this. They live only
|
||||||
|
in the in-memory `pending_approvals` map and the live `ReducedState`, both
|
||||||
|
gone the instant the daemon that held them exits. Whatever ACP permission
|
||||||
|
request was mid-flight when the old daemon died was already answered
|
||||||
|
`Cancelled` on that daemon's own shutdown path, so a resumed session always
|
||||||
|
starts with no pending approval.
|
||||||
|
|
||||||
|
See `docs/RESTART.md` for what a *client* observes across a daemon restart,
|
||||||
|
now that structured sessions exist alongside terminal ones.
|
||||||
Reference in New Issue
Block a user