Compare commits

...
Author SHA1 Message Date
Miguel Palhas 202b5008b8 fix(maestro): drop an unused instant from report_activity 2026-08-24 21:40:34 +01:00
Miguel Palhas 015f2be5fb docs(maestro): record the activity-detail meta-line slot and report TTL 2026-08-24 21:39:15 +01:00
Miguel Palhas 5a594b2b7f feat(maestro): serve POST /api/sessions/:id/activity 2026-08-24 21:38:42 +01:00
Miguel Palhas 8370ddf066 feat(maestro): hold agent-reported activity above inference for a TTL 2026-08-24 21:36:56 +01:00
Miguel Palhas 5c4e083c2d feat(maestro): add activity_detail to Session and the activity-report wire types 2026-08-24 21:32:27 +01:00
Miguel Palhas 766d256970 fix(maestro): suppress epoch durations on TUI cards 2026-08-24 19:57:58 +01:00
Miguel Palhas 78cddec730 merge: sidebar-cards/108-tui-cards 2026-08-24 19:56:51 +01:00
Miguel Palhas 4ff31a4f79 merge: sidebar-cards/107-web-cards 2026-08-24 19:56:51 +01:00
Miguel Palhas abab7dcb63 merge: sidebar-cards/104-activity-clock 2026-08-24 19:56:51 +01:00
Miguel Palhas f6a97c4695 docs(maestro): settle line-2 rulings — command fragment, pre-#102 payloads, unconditional dot 2026-08-24 19:51:06 +01:00
Miguel Palhas 5be3e33c94 feat(maestro): render sidebar sessions as two-line cards per docs/SIDEBAR.md 2026-08-24 19:50:24 +01:00
Miguel Palhas 002c128ac8 feat(maestro): stamp activity_since only on state transitions (#104)
The activity pass now sets activity_since only when the decided
ActivityState differs from the stored one; foreground/cwd-only diffs and
steady-state ticks leave the clock alone, so the sidebar duration counts
time in the current state instead of reading zero.

Daemon restarts still reset the clock to the restart time (stated in
recover()); the daemon cannot know how long a recovered session had
already been idle.
2026-08-24 19:49:55 +01:00
Miguel Palhas d7b15a131f feat(maestro): activity duration + colour helpers per the sidebar card contract 2026-08-24 19:42:33 +01:00
24 changed files with 1165 additions and 90 deletions
+1
View File
@@ -176,6 +176,7 @@ mod tests {
created_at: Utc.with_ymd_and_hms(2026, 5, 25, 12, 0, 0).unwrap(),
foreground: None,
activity: Default::default(),
activity_detail: None,
last_activity_at: chrono::Utc::now(),
activity_since: chrono::Utc::now(),
current_cwd: None,
+59
View File
@@ -15,6 +15,44 @@ use maestro_protocol::ActivityState;
/// Active↔Idle. This window *is* the debounce the issue calls for.
pub const ACTIVE_WINDOW: Duration = Duration::from_secs(3);
/// How long an agent-reported state (#105) stays in force before inference
/// resumes. Long enough for a working agent's heartbeat to hold between
/// reports, short enough that an agent dying mid-run cannot pin its session
/// at `Error` forever.
pub const REPORT_TTL: Duration = Duration::from_secs(300);
/// Server-side cap (#105) on a reported `detail`, in characters. The meta
/// line renders it inline, so an unbounded string would own the whole card.
pub const MAX_REPORT_DETAIL_CHARS: usize = 256;
/// An agent-reported activity state (#105) still within its TTL. While one
/// is [`Self::in_force`], it outranks [`decide`]'s inference; when it
/// lapses, inference resumes and any reported detail is cleared with it.
#[derive(Debug, Clone)]
pub struct ReportedActivity {
pub state: ActivityState,
pub expires_at: std::time::Instant,
}
impl ReportedActivity {
pub fn new(state: ActivityState, ttl: Duration) -> Self {
Self {
state,
expires_at: std::time::Instant::now() + ttl,
}
}
pub fn in_force(&self, now: std::time::Instant) -> bool {
now < self.expires_at
}
}
/// Cap a reported detail to [`MAX_REPORT_DETAIL_CHARS`] characters,
/// char-boundary safe.
pub fn truncate_detail(detail: Option<String>) -> Option<String> {
detail.map(|d| d.chars().take(MAX_REPORT_DETAIL_CHARS).collect())
}
/// Combine the observed signals into an [`ActivityState`]:
/// recent output ⇒ `Active`; else blocked on a terminal read ⇒ `AwaitingInput`;
/// else `Idle`.
@@ -59,4 +97,25 @@ mod tests {
ActivityState::Idle
);
}
#[test]
fn report_is_in_force_until_exactly_its_expiry() {
let ttl = Duration::from_secs(300);
let report = ReportedActivity::new(ActivityState::Error, ttl);
assert!(report.in_force(report.expires_at - Duration::from_millis(1)));
assert!(!report.in_force(report.expires_at));
}
#[test]
fn detail_truncates_to_the_cap_without_panic_on_multibyte_input() {
let long = "é".repeat(MAX_REPORT_DETAIL_CHARS + 10);
let capped = truncate_detail(Some(long)).unwrap();
assert_eq!(capped.chars().count(), MAX_REPORT_DETAIL_CHARS);
assert_eq!(truncate_detail(None), None);
assert_eq!(
truncate_detail(Some("short".into())).as_deref(),
Some("short")
);
}
}
+1
View File
@@ -27,5 +27,6 @@ pub mod tmux;
pub mod worktree;
pub mod worktree_probe;
pub use activity::MAX_REPORT_DETAIL_CHARS;
pub use config::{default_config_path, default_state_dir, load_config, DaemonConfig, EnvOverrides};
pub use session::{SessionError, SessionManager};
+27 -3
View File
@@ -15,12 +15,12 @@ use std::sync::Arc;
use axum::extract::{Path, Query, State};
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use axum::routing::{any, delete, get};
use axum::routing::{any, delete, get, post};
use axum::{Json, Router};
use maestro_config::SpawnPreset;
use maestro_protocol::{
routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonInfo, GitRoot, NameBatch, Session,
PROTOCOL_VERSION,
routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonInfo, GitRoot, NameBatch,
ReportActivityRequest, Session, PROTOCOL_VERSION,
};
use serde::Deserialize;
use uuid::Uuid;
@@ -46,6 +46,7 @@ pub struct LocalApiState {
pub fn router(state: LocalApiState) -> Router {
Router::new()
.route(routes::SESSIONS, get(list_sessions).post(create_session))
.route(routes::patterns::SESSION_ACTIVITY, post(report_activity))
.route(routes::patterns::SESSION, delete(kill_session))
.route(routes::DIRS, get(list_dir))
.route(routes::RECENT_DIRS, get(recent_dirs))
@@ -318,6 +319,29 @@ async fn reclaim_worktree(State(s): State<LocalApiState>, Path(id): Path<Uuid>)
}
}
/// `POST /api/sessions/:id/activity` (#105): an agent reports its own state.
/// The report holds above the daemon's inference for a TTL, then inference
/// resumes — an agent that dies mid-run cannot pin its session at `Error`
/// forever. Unknown session is 404; an unknown state value is rejected by the
/// JSON decoder (422) rather than coerced. Answers `204 No Content`.
async fn report_activity(
State(s): State<LocalApiState>,
Path(id): Path<Uuid>,
Json(body): Json<ReportActivityRequest>,
) -> Response {
match s.manager.report_activity(id, body.state, body.detail).await {
Ok(()) => StatusCode::NO_CONTENT.into_response(),
Err(e) => {
let info = e.to_error_info();
error_response(
session_error_status(&info.code),
info.code.as_str(),
info.message.as_str(),
)
}
}
}
fn error_response(status: StatusCode, code: &str, message: &str) -> Response {
(status, Json(ApiError::new(code, message))).into_response()
}
+87 -1
View File
@@ -57,6 +57,11 @@ pub struct SessionRecord {
/// fall back to a probe.
pub worktree_branch: Option<String>,
pub bridge: PtyBridge,
/// Agent-reported activity (#105) still within its TTL. While in force it
/// outranks the activity pass's own inference; when it lapses, inference
/// resumes and [`Session::activity_detail`] is cleared with it. This
/// field is daemon-local bookkeeping only — it never rides the wire.
pub reported_activity: Option<crate::activity::ReportedActivity>,
}
#[derive(Debug, thiserror::Error)]
@@ -136,6 +141,9 @@ struct Inner {
/// the variable. A mutex because the runner sets it after construction,
/// possibly while clones are already serving.
daemon_url: std::sync::Mutex<Option<String>>,
/// TTL an agent-reported activity state (#105) stays in force. A const in
/// production; overridable for tests that watch the lapse happen.
report_ttl: Duration,
sessions: Mutex<HashMap<Uuid, SessionRecord>>,
events: broadcast::Sender<CatalogEvent>,
}
@@ -176,6 +184,7 @@ impl SessionManager {
spawn_history: None,
retained: None,
daemon_url: std::sync::Mutex::new(None),
report_ttl: crate::activity::REPORT_TTL,
sessions: Mutex::new(HashMap::new()),
events,
}),
@@ -208,6 +217,15 @@ impl SessionManager {
self
}
/// Override the agent-report TTL (#105). Tests pass a short one to watch
/// inference resume without waiting out [`crate::activity::REPORT_TTL`].
pub fn with_activity_report_ttl(mut self, ttl: Duration) -> Self {
let inner = Arc::get_mut(&mut self.inner)
.expect("with_activity_report_ttl must be called before the SessionManager is cloned");
inner.report_ttl = ttl;
self
}
/// Set the daemon's own HTTP base URL (#103), exported to every session
/// spawned afterwards as `MAESTRO_URL`. Unlike the `with_*` builders this
/// is a plain setter: the daemon runner learns its bound address after
@@ -379,6 +397,7 @@ impl SessionManager {
// activity watcher refines `foreground`/`activity` on its next tick.
foreground: None,
activity: ActivityState::Active,
activity_detail: None,
last_activity_at: Utc::now(),
activity_since: chrono::Utc::now(),
@@ -409,6 +428,7 @@ impl SessionManager {
worktree_base_repo,
worktree_branch: req.worktree.as_ref().map(|w| w.branch.clone()),
bridge,
reported_activity: None,
},
);
}
@@ -597,8 +617,12 @@ impl SessionManager {
status: SessionStatus::Running,
created_at: Utc::now(),
// Activity is unknown on adoption; the watcher fills it in.
// #104: the restart also resets the activity clock to now —
// accepted, since the daemon cannot know how long a
// recovered session had already been sitting idle.
foreground: None,
activity: ActivityState::Idle,
activity_detail: None,
last_activity_at: Utc::now(),
activity_since: chrono::Utc::now(),
@@ -632,6 +656,7 @@ impl SessionManager {
// recovered session probes git for it at retain time.
worktree_branch: None,
bridge,
reported_activity: None,
},
);
let _ = self
@@ -672,6 +697,47 @@ impl SessionManager {
.await
.map_err(SessionError::Tmux)
}
/// Accept an agent-reported activity state (#105), the only path that can
/// produce `ActivityState::Error`. The report outranks the activity pass's
/// own inference until its TTL lapses — so an agent that dies mid-run
/// cannot pin its session at `Error` forever. An unknown session is
/// [`SessionError::NotFound`]; the reported `detail` is capped
/// server-side.
///
/// A report that changes the effective state restarts `activity_since`
/// (#104's clock); re-reporting an unchanged state only extends the TTL
/// and stays silent on the event stream at steady state.
pub async fn report_activity(
&self,
id: Uuid,
state: ActivityState,
detail: Option<String>,
) -> Result<(), SessionError> {
let updated = {
let mut sessions = self.inner.sessions.lock().await;
let rec = sessions.get_mut(&id).ok_or(SessionError::NotFound(id))?;
let detail = crate::activity::truncate_detail(detail);
let changed = rec.session.activity != state || rec.session.activity_detail != detail;
if rec.session.activity != state {
rec.session.activity_since = Utc::now();
}
rec.session.activity = state;
rec.session.activity_detail = detail;
rec.reported_activity = Some(crate::activity::ReportedActivity::new(
state,
self.inner.report_ttl,
));
changed.then(|| rec.session.clone())
};
if let Some(session) = updated {
let _ = self
.inner
.events
.send(CatalogEvent::SessionUpdated { session });
}
Ok(())
}
}
/// Run a blocking `tmux` subprocess call on the blocking thread pool so it
@@ -842,8 +908,22 @@ async fn run_activity_pass(inner: &Arc<Inner>) {
let Some(rec) = sessions.get_mut(&id) else {
continue;
};
// #105: an agent report lapses at its TTL — drop it and its
// detail so this tick's inference takes over again.
if let Some(report) = &rec.reported_activity {
if !report.in_force(std::time::Instant::now()) {
rec.reported_activity = None;
rec.session.activity_detail = None;
}
}
let idle = rec.bridge.idle_for();
let activity = crate::activity::decide(idle, awaiting);
// #105: while a report is in force it supplies the state and
// nothing here may overwrite it; only an unreported session is
// decided by inference.
let activity = match &rec.reported_activity {
Some(report) => report.state,
None => crate::activity::decide(idle, awaiting),
};
let foreground = Some(pane.command.clone());
// The pane's live cwd, drives the dir-based session tree; empty means
// tmux reported none.
@@ -857,6 +937,12 @@ async fn run_activity_pass(inner: &Arc<Inner>) {
{
None
} else {
// #104: stamp only when the state itself changed — never on
// foreground/cwd-only diffs, and never every tick, or the
// sidebar's duration would reset continuously and read zero.
if rec.session.activity != activity {
rec.session.activity_since = Utc::now();
}
rec.session.activity = activity;
rec.session.foreground = foreground;
rec.session.current_cwd = current_cwd;
@@ -0,0 +1,164 @@
//! Agent-reported activity (#105): `POST /api/sessions/:id/activity`
//! semantics at the SessionManager level — precedence over the daemon's own
//! inference, detail handling, and lapse back to inference at the TTL.
mod common;
use std::sync::Arc;
use std::time::Duration;
use common::TmuxFixture;
use maestro_daemon::sidecar::SidecarStore;
use maestro_daemon::worktree::WorktreeManager;
use maestro_daemon::SessionManager;
use maestro_protocol::{ActivityState, CreateSessionRequest};
use tempfile::TempDir;
use tokio::time::sleep;
use uuid::Uuid;
struct Fixture {
manager: SessionManager,
_tmux: TmuxFixture,
_state_dir: TempDir,
}
async fn fixture(ttl: Duration) -> Fixture {
let tmux = TmuxFixture::new();
let state_dir = TempDir::new().unwrap();
let manager = SessionManager::new(
Arc::new(tmux.tmux.clone()),
SidecarStore::new(state_dir.path().join("sessions")),
WorktreeManager::new(None),
state_dir.path().join("fifos"),
)
.with_activity_report_ttl(ttl);
Fixture {
manager,
_tmux: tmux,
_state_dir: state_dir,
}
}
async fn spawn_sleeping(manager: &SessionManager) -> Uuid {
manager
.create(CreateSessionRequest {
cwd: "/tmp".into(),
command: "sleep 60".into(),
env: Default::default(),
metadata: Default::default(),
worktree: None,
})
.await
.unwrap()
.id
}
async fn observed(manager: &SessionManager, id: Uuid) -> maestro_protocol::Session {
manager
.snapshot()
.await
.into_iter()
.find(|s| s.id == id)
.expect("session still tracked")
}
#[tokio::test]
async fn report_on_unknown_session_is_not_found() {
let fx = fixture(Duration::from_secs(300)).await;
let err = fx
.manager
.report_activity(Uuid::new_v4(), ActivityState::Idle, None)
.await
.unwrap_err();
assert!(matches!(err, maestro_daemon::SessionError::NotFound(_)));
}
#[tokio::test]
async fn report_sets_error_state_and_detail() {
let fx = fixture(Duration::from_secs(300)).await;
let id = spawn_sleeping(&fx.manager).await;
fx.manager
.report_activity(
id,
ActivityState::Error,
Some("cargo build failed: link error".into()),
)
.await
.unwrap();
let s = observed(&fx.manager, id).await;
assert_eq!(s.activity, ActivityState::Error);
assert_eq!(
s.activity_detail.as_deref(),
Some("cargo build failed: link error")
);
}
#[tokio::test]
async fn replacing_a_report_replaces_both_state_and_detail() {
let fx = fixture(Duration::from_secs(300)).await;
let id = spawn_sleeping(&fx.manager).await;
fx.manager
.report_activity(id, ActivityState::Error, Some("first failure".into()))
.await
.unwrap();
fx.manager
.report_activity(
id,
ActivityState::AwaitingInput,
Some("needs approval".into()),
)
.await
.unwrap();
let s = observed(&fx.manager, id).await;
assert_eq!(s.activity, ActivityState::AwaitingInput);
assert_eq!(s.activity_detail.as_deref(), Some("needs approval"));
}
#[tokio::test]
async fn detail_is_capped_server_side() {
let fx = fixture(Duration::from_secs(300)).await;
let id = spawn_sleeping(&fx.manager).await;
let long = "x".repeat(10_000);
fx.manager
.report_activity(id, ActivityState::Error, Some(long))
.await
.unwrap();
let s = observed(&fx.manager, id).await;
let detail = s.activity_detail.expect("detail present");
assert_eq!(
detail.chars().count(),
maestro_daemon::MAX_REPORT_DETAIL_CHARS
);
}
#[tokio::test]
async fn reported_state_survives_watcher_ticks_until_the_ttl_then_inference_resumes() {
let fx = fixture(Duration::from_millis(150)).await;
let id = spawn_sleeping(&fx.manager).await;
fx.manager.start_liveness_watcher(Duration::from_millis(50));
fx.manager
.report_activity(id, ActivityState::Error, Some("agent died mid-run".into()))
.await
.unwrap();
// Several watcher ticks inside the TTL: nothing infers `Error`, so the
// report must hold above inference.
sleep(Duration::from_millis(80)).await;
let s = observed(&fx.manager, id).await;
assert_eq!(s.activity, ActivityState::Error);
assert_eq!(s.activity_detail.as_deref(), Some("agent died mid-run"));
// After the TTL lapses, inference resumes and the detail goes with it.
common::wait_for_async(Duration::from_secs(5), || async {
let s = observed(&fx.manager, id).await;
s.activity != ActivityState::Error && s.activity_detail.is_none()
})
.await;
}
+103
View File
@@ -346,6 +346,109 @@ async fn delete_owned_session_kills_it() {
assert!(!h.manager.has(session.id).await);
}
/// Spawn a session through the manager and return its id.
async fn spawn_via_manager(h: &Harness) -> Uuid {
h.manager
.create(CreateSessionRequest {
cwd: "/tmp".into(),
command: "sleep 60".into(),
env: HashMap::new(),
metadata: HashMap::new(),
worktree: None,
})
.await
.unwrap()
.id
}
/// The agent activity endpoint on the wire (#105): a report lands in the
/// session snapshot with its detail.
#[tokio::test]
async fn post_activity_reports_error_with_detail() {
let h = spawn("naps-laptop").await;
let id = spawn_via_manager(&h).await;
let resp = reqwest::Client::new()
.post(url(h.addr, &format!("/api/sessions/{id}/activity")))
.json(&serde_json::json!({
"state": "Error",
"detail": "cargo build failed"
}))
.send()
.await
.unwrap();
assert_eq!(resp.status(), reqwest::StatusCode::NO_CONTENT);
let sessions: Vec<Session> = reqwest::get(url(h.addr, "/api/sessions"))
.await
.unwrap()
.json()
.await
.unwrap();
let s = sessions.iter().find(|s| s.id == id).unwrap();
assert_eq!(s.activity, maestro_protocol::ActivityState::Error);
assert_eq!(s.activity_detail.as_deref(), Some("cargo build failed"));
}
#[tokio::test]
async fn post_activity_to_unknown_session_returns_404() {
let h = spawn("naps-laptop").await;
let resp = reqwest::Client::new()
.post(url(
h.addr,
&format!("/api/sessions/{}/activity", Uuid::new_v4()),
))
.json(&serde_json::json!({ "state": "Idle" }))
.send()
.await
.unwrap();
assert_eq!(resp.status(), reqwest::StatusCode::NOT_FOUND);
}
/// Unknown state values are rejected rather than coerced (#105).
#[tokio::test]
async fn post_activity_rejects_an_unknown_state_value() {
let h = spawn("naps-laptop").await;
let id = spawn_via_manager(&h).await;
let resp = reqwest::Client::new()
.post(url(h.addr, &format!("/api/sessions/{id}/activity")))
.json(&serde_json::json!({ "state": "Teleported" }))
.send()
.await
.unwrap();
assert!(resp.status().is_client_error(), "got {}", resp.status());
}
#[tokio::test]
async fn post_activity_caps_an_overlong_detail_server_side() {
let h = spawn("naps-laptop").await;
let id = spawn_via_manager(&h).await;
let resp = reqwest::Client::new()
.post(url(h.addr, &format!("/api/sessions/{id}/activity")))
.json(&serde_json::json!({
"state": "Error",
"detail": "x".repeat(10_000)
}))
.send()
.await
.unwrap();
assert_eq!(resp.status(), reqwest::StatusCode::NO_CONTENT);
let sessions: Vec<Session> = reqwest::get(url(h.addr, "/api/sessions"))
.await
.unwrap()
.json()
.await
.unwrap();
let s = sessions.iter().find(|s| s.id == id).unwrap();
assert_eq!(
s.activity_detail.as_ref().map(|d| d.chars().count()),
Some(maestro_daemon::MAX_REPORT_DETAIL_CHARS)
);
}
/// The kill guard on the wire (#79): `DELETE /api/sessions/:id` answers 409
/// with the structured breakdown, and the session keeps running.
#[tokio::test]
@@ -363,6 +363,9 @@ async fn activity_pass_emits_updated_only_when_something_changed() {
// Still inside `activity::ACTIVE_WINDOW` (3s) since the spawn, so the
// change here is `foreground`, not the activity state.
assert_eq!(updated.activity, ActivityState::Active);
// A foreground/cwd-only change is not a state transition (#104): the
// sidebar's duration must keep counting from the original stamp.
assert_eq!(updated.activity_since, session.activity_since);
// Drain anything already queued, then confirm a steady pane stays quiet.
// Stays well inside the 3s window, so no Active -> Idle transition either.
@@ -374,6 +377,70 @@ async fn activity_pass_emits_updated_only_when_something_changed() {
);
}
/// The sidebar's duration (#104) is time in the *current* state, so
/// `activity_since` is stamped exactly when the decided state differs from
/// the stored one — once per transition. Stamping it every tick would make
/// the duration permanently read zero.
#[tokio::test]
async fn activity_transition_stamps_activity_since_once_per_transition() {
let fx = Fx::new();
let session = fx
.manager
.create(fx.request("sleep 300"))
.await
.expect("create");
fx.fake.set_pane_info(
session.id,
PaneInfo {
// Nothing reads from this pid: `awaiting_input` is deterministically
// false, so past `ACTIVE_WINDOW` the session decides as Idle.
pane_pid: i32::MAX,
command: "sleep".into(),
tty: "/dev/null".into(),
current_path: String::new(),
},
);
let mut events = fx.manager.events();
fx.manager.start_liveness_watcher(Duration::from_millis(25));
let idle = wait_for_activity(&fx.manager, session.id, ActivityState::Idle).await;
assert!(
idle.activity_since >= session.activity_since + chrono::Duration::seconds(2),
"the Active -> Idle transition must stamp a fresh activity_since \
(spawn stamp {:?}, transition stamp {:?})",
session.activity_since,
idle.activity_since
);
// Steady Idle across many more ticks must not re-stamp — no further
// SessionUpdated at all, or the sidebar clock would keep resetting.
while events.try_recv().is_ok() {}
tokio::time::sleep(Duration::from_millis(300)).await;
assert!(
matches!(events.try_recv(), Err(TryRecvError::Empty)),
"a steady state must not re-emit (and re-stamp) on every tick"
);
}
async fn wait_for_activity(
manager: &SessionManager,
id: uuid::Uuid,
want: ActivityState,
) -> maestro_protocol::Session {
let deadline = tokio::time::Instant::now() + Duration::from_secs(6);
loop {
if tokio::time::Instant::now() >= deadline {
panic!("timed out waiting for {id} to become {want:?}");
}
if let Some(s) = manager.snapshot().await.into_iter().find(|s| s.id == id) {
if s.activity == want {
return s;
}
}
tokio::time::sleep(Duration::from_millis(20)).await;
}
}
async fn wait_for_updated(
events: &mut tokio::sync::broadcast::Receiver<CatalogEvent>,
) -> maestro_protocol::Session {
+1
View File
@@ -26,6 +26,7 @@ fn sample(id: Uuid) -> Session {
.with_timezone(&Utc),
foreground: None,
activity: Default::default(),
activity_detail: None,
last_activity_at: chrono::Utc::now(),
activity_since: chrono::Utc::now(),
current_cwd: Some(PathBuf::from("/tmp/work/crates")),
+16 -1
View File
@@ -16,7 +16,7 @@ use uuid::Uuid;
use crate::routes::{self, UrlError};
use crate::{
ApiError, BranchInfo, CreateSessionRequest, DaemonInfo, DirListing, ErrorInfo, GitRoot,
KillOutcome, Project, RecentDirs, RetainedWorktree, Session,
KillOutcome, Project, RecentDirs, ReportActivityRequest, RetainedWorktree, Session,
};
/// Time budget for establishing a TCP connection to the daemon.
@@ -134,6 +134,21 @@ impl DaemonClient {
json(resp).await
}
/// `POST /api/sessions/:id/activity` (#105): report an agent-observed
/// state. The daemon holds it above its own inference for a TTL, then
/// resumes inference. Answers `204 No Content`.
pub async fn report_activity(
&self,
id: Uuid,
req: &ReportActivityRequest,
) -> Result<(), ClientError> {
let resp = self
.send(Method::POST, &routes::session_activity(id), &[], Some(req))
.await?;
check(resp).await?;
Ok(())
}
pub async fn daemon_info(&self) -> Result<DaemonInfo, ClientError> {
self.get(routes::INFO, &[]).await
}
+62
View File
@@ -75,6 +75,12 @@ pub struct Session {
/// byte stream.
#[serde(default)]
pub activity: ActivityState,
/// Short human-readable string an agent reported alongside its activity
/// (#105) — e.g. why it is in `Error`. Shown on a sidebar card's meta line
/// while the report is in force; cleared when the report lapses or is
/// replaced. `None` unless an agent reported one.
#[serde(default)]
pub activity_detail: Option<String>,
/// Wall-clock time of the session's most recent observed PTY output.
/// Drives "idle for Ns" displays. Defaults to the Unix epoch on payloads
/// from daemons that predate the field.
@@ -131,6 +137,18 @@ pub enum ActivityState {
Error,
}
/// HTTP `POST /api/sessions/:id/activity` body (#105): an agent's report of
/// its own state. The daemon holds the reported state above its own inference
/// for a fixed TTL, then resumes inference.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ReportActivityRequest {
pub state: ActivityState,
/// Short human string shown next to the state (e.g. an error message).
/// The daemon caps its length server-side.
#[serde(default)]
pub detail: Option<String>,
}
/// Optional worktree request attached to a `CreateSessionRequest`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WorktreeSpec {
@@ -544,6 +562,7 @@ mod tests {
.with_timezone(&Utc),
foreground: Some("claude".into()),
activity: ActivityState::Active,
activity_detail: None,
last_activity_at: DateTime::parse_from_rfc3339("2026-05-24T12:05:00Z")
.unwrap()
.with_timezone(&Utc),
@@ -639,6 +658,49 @@ mod tests {
assert_eq!(ActivityState::default(), ActivityState::Idle);
}
#[test]
fn activity_detail_defaults_to_none_on_legacy_payload() {
// #105: a daemon predating the detail field omits it; it must
// deserialize to `None` rather than failing, and a present value
// round-trips.
let json = serde_json::json!({
"id": Uuid::from_u128(1),
"cwd": "/tmp",
"command": "bash",
"status": "Running",
"created_at": "2026-05-24T12:00:00Z"
});
let s: Session = serde_json::from_value(json).unwrap();
assert_eq!(s.activity_detail, None);
let mut reported = sample_session();
reported.activity = ActivityState::Error;
reported.activity_detail = Some("build failed".into());
assert_eq!(reported.clone(), round_trip(&reported));
}
#[test]
fn report_activity_request_defaults_detail_and_rejects_unknown_state() {
let bare: ReportActivityRequest =
serde_json::from_value(serde_json::json!({ "state": "Error" })).unwrap();
assert_eq!(bare.state, ActivityState::Error);
assert_eq!(bare.detail, None);
let full = ReportActivityRequest {
state: ActivityState::AwaitingInput,
detail: Some("waiting on permission".into()),
};
assert_eq!(full, round_trip(&full));
// Unknown state values are rejected rather than coerced (#105).
assert!(
serde_json::from_value::<ReportActivityRequest>(serde_json::json!({
"state": "Teleported"
}))
.is_err()
);
}
#[test]
fn session_round_trips() {
let s = sample_session();
+14
View File
@@ -47,6 +47,11 @@ pub fn session(id: Uuid) -> String {
format!("{SESSIONS}/{id}")
}
/// `POST /api/sessions/:id/activity` (#105): an agent reports its own state.
pub fn session_activity(id: Uuid) -> String {
format!("{SESSIONS}/{id}/activity")
}
/// `DELETE /api/worktrees/:id` — reclaim one retained worktree (#80).
pub fn worktree(id: Uuid) -> String {
format!("{WORKTREES}/{id}")
@@ -61,6 +66,7 @@ pub fn attach(id: Uuid) -> String {
/// registers the same paths [`session`] and [`attach`] build.
pub mod patterns {
pub const SESSION: &str = "/api/sessions/:id";
pub const SESSION_ACTIVITY: &str = "/api/sessions/:id/activity";
pub const ATTACH: &str = "/api/attach/:id";
pub const WORKTREE: &str = "/api/worktrees/:id";
}
@@ -169,6 +175,10 @@ mod tests {
session(id()),
"/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
);
assert_eq!(
session_activity(id()),
"/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50/activity"
);
assert_eq!(
attach(id()),
"/api/attach/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
@@ -191,6 +201,10 @@ mod tests {
patterns::SESSION.trim_end_matches(":id"),
session(id()).trim_end_matches(&id().to_string())
);
assert_eq!(
patterns::SESSION_ACTIVITY.trim_end_matches(":id/activity"),
session(id()).trim_end_matches(&id().to_string())
);
assert_eq!(
patterns::ATTACH.trim_end_matches(":id"),
attach(id()).trim_end_matches(&id().to_string())
+1
View File
@@ -41,6 +41,7 @@ pub fn session(id: Uuid, cwd: &str, command: &str) -> Session {
created_at: Utc::now(),
foreground: None,
activity: Default::default(),
activity_detail: None,
last_activity_at: Utc::now(),
activity_since: chrono::Utc::now(),
current_cwd: None,
+2
View File
@@ -1126,6 +1126,7 @@ mod tests {
created_at: Utc::now(),
foreground: None,
activity: Default::default(),
activity_detail: None,
last_activity_at: Utc::now(),
activity_since: chrono::Utc::now(),
current_cwd: None,
@@ -1644,6 +1645,7 @@ mod tests {
created_at: Utc::now(),
foreground: None,
activity: Default::default(),
activity_detail: None,
last_activity_at: chrono::Utc::now(),
activity_since: chrono::Utc::now(),
+1
View File
@@ -193,6 +193,7 @@ mod tests {
created_at: Utc::now(),
foreground: None,
activity: Default::default(),
activity_detail: None,
last_activity_at: chrono::Utc::now(),
activity_since: chrono::Utc::now(),
current_cwd: None,
+66 -6
View File
@@ -19,6 +19,12 @@ use uuid::Uuid;
/// Time-in-state alone earns a meta line only once the session has sat in
/// its current activity state this long (docs/SIDEBAR.md).
const META_LINE_AFTER_SECS: i64 = 30;
/// A payload predating #102 defaults `activity_since` to the Unix epoch. Per
/// docs/SIDEBAR.md such a session contributes no duration — the dot still
/// renders — so anything implausibly old counts as "never observed" rather
/// than a card announcing that the session has been idle for half a century.
/// Mirrors `PLAUSIBLE_EPOCH_MS` in `web/src/activity.ts`.
const PLAUSIBLE_SINCE_YEAR: i32 = 2010;
const INDENT: &str = " ";
const META_INDENT: &str = " ";
/// Spawn-similar and kill, shown on the highlighted card's top-right corner.
@@ -129,25 +135,31 @@ impl Sidebar {
/// The adaptive second line: `<dot> <duration> [<blocked work> | exited]`.
fn meta_row(&self, s: &Session, width: usize) -> Option<Vec<Span<'static>>> {
let now = Utc::now();
let held_secs = (now - s.activity_since).num_seconds();
let held = held_for(s, now);
let held_secs = held.map(|d| d.num_seconds()).unwrap_or(0);
// #83: a worktree that blocks a kill is summarised here rather than
// on line 1; the kill confirm names the specifics.
let blocked = s.blocked_work.filter(|b| !b.is_clear());
let dead = s.status == SessionStatus::Dead;
let errored = s.activity == ActivityState::Error;
if held_secs < META_LINE_AFTER_SECS && blocked.is_none() && !dead && !errored {
if (held.is_none() || held_secs < META_LINE_AFTER_SECS)
&& blocked.is_none()
&& !dead
&& !errored
{
return None;
}
let base = card_base(self.highlight == Some(s.id));
let dot_style = base.patch(Style::default().fg(activity_color(s.activity)));
let muted = Style::default().bg(base.bg.unwrap_or(Color::Reset));
let duration = format_state_duration(now - s.activity_since);
let mut spans = vec![
Span::styled(META_INDENT, base),
Span::styled("●", dot_style),
Span::styled(" ", base),
Span::styled(duration, dot_style),
];
if let Some(d) = held {
spans.push(Span::styled(" ", base));
spans.push(Span::styled(format_state_duration(d), dot_style));
}
if let Some(b) = blocked {
spans.push(Span::styled(format!(" ⚠ {b}"), muted));
}
@@ -171,6 +183,16 @@ fn activity_color(state: ActivityState) -> Color {
/// docs/SIDEBAR.md duration format — floored whole seconds / minutes / hours,
/// measured in the current activity state. No days, no rounding up.
/// How long the session has held its current activity state, or `None` when
/// the daemon never reported one (see [`PLAUSIBLE_SINCE_YEAR`]).
fn held_for(s: &Session, now: chrono::DateTime<Utc>) -> Option<chrono::Duration> {
use chrono::Datelike;
if s.activity_since.year() < PLAUSIBLE_SINCE_YEAR {
return None;
}
Some(now - s.activity_since)
}
fn format_state_duration(elapsed: chrono::Duration) -> String {
let secs = elapsed.num_seconds().max(0);
match secs {
@@ -228,7 +250,7 @@ fn name_for(s: &Session) -> String {
#[cfg(test)]
mod tests {
use super::*;
use chrono::Duration;
use chrono::{DateTime, Duration};
use maestro_protocol::InTheWay;
use ratatui::backend::TestBackend;
use ratatui::buffer::Buffer;
@@ -249,6 +271,7 @@ mod tests {
created_at: Utc::now(),
foreground: None,
activity: Default::default(),
activity_detail: None,
last_activity_at: Utc::now(),
activity_since: Utc::now(),
current_cwd: None,
@@ -508,6 +531,42 @@ mod tests {
);
}
/// docs/SIDEBAR.md: a payload predating #102 carries an epoch
/// `activity_since` and so contributes no duration — a card must not claim
/// the session has been idle since 1970. The dot still renders when some
/// other trigger puts line 2 on screen.
#[test]
fn epoch_activity_since_renders_no_duration() {
let mut legacy = session_named(1, "claude");
legacy.activity_since = DateTime::from_timestamp(0, 0).unwrap();
legacy.status = SessionStatus::Dead;
let sb = Sidebar {
sessions: vec![legacy],
highlight: None,
attached: Default::default(),
};
let rendered = render_to_string(&draw(&sb, 40, 8));
assert!(
rendered.contains("exited"),
"dead session must still show line 2:\n{rendered}"
);
assert!(
!rendered.contains('h') || !rendered.contains("● "),
"no duration may follow the dot for an epoch stamp:\n{rendered}"
);
for line in rendered.lines().filter(|l| l.contains('●')) {
assert!(
!line
.split('●')
.nth(1)
.unwrap_or("")
.trim_start()
.starts_with(char::is_numeric),
"duration rendered from an epoch stamp: {line:?}"
);
}
}
#[test]
fn falls_back_to_command_when_name_metadata_is_absent() {
let s = Session {
@@ -521,6 +580,7 @@ mod tests {
created_at: Utc::now(),
foreground: None,
activity: Default::default(),
activity_detail: None,
last_activity_at: Utc::now(),
activity_since: Utc::now(),
current_cwd: None,
+21 -8
View File
@@ -41,13 +41,25 @@ Otherwise line 2 is absent — never an empty placeholder row.
When present, line 2 reads left to right:
```
<dot> <duration> [<blocked work> | exited]
<dot> <duration> [<detail>] [<blocked work> | exited] [<command>]
```
`<dot>` is a single filled glyph (`●` on both clients) carrying the activity
state's colour, and `<duration>` follows in the same colour. There is no state
word and no second badge: the dot exists so the state is still legible when a
row is dimmed or the terminal renders the duration in the default fg.
row is dimmed or the terminal renders the duration in the default fg. The dot
and duration are unconditional parts of line 2; the bracketed fragments appear
only when their trigger holds. A payload that predates #102 (no usable
`activity_since`) contributes no duration — the dot still renders.
`<detail>` is an agent-reported string (#105) — e.g. why a session is in
`Error`. It sits right after the duration, in the muted style, and shows only
while an agent-reported state is in force (see Precedence): when the report
lapses at its TTL or is replaced, the detail goes with it.
`<command>` is optional and muted: the session's command line, shown only when
the rendered name came from `metadata.name` and differs from the command (the
web has always surfaced this; the TUI may omit it).
## Colour per activity state
@@ -65,9 +77,9 @@ and `prefers-color-scheme` variants for each). The TUI uses the plain ratatui
named colours above; do not introduce RGB values or a new palette module for
this.
The duration text inherits its state's colour; the blocked-work and exited
fragments use the muted colour (`--faint` / default style), since the ⚠ glyph
already signals severity.
The duration text inherits its state's colour; the blocked-work, exited and
command fragments use the muted colour (`--faint` / default style), since the
⚠ glyph already signals severity.
## Duration format
@@ -87,9 +99,10 @@ cutover points land within one tick.
## Precedence
An agent-reported `ActivityState` (#105) overrides the daemon's inference for
the TTL the report carries; when the TTL expires, inference resumes. Clients
never blend the two: whichever source is in force supplies both the colour and
the clock for `activity_since`.
**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 —
if any — clears with the report. Clients never blend the two: whichever source
is in force supplies both the colour and the clock for `activity_since`.
If a client receives an `ActivityState` variant it does not know, it must not
fail rendering: treat it as `Idle` (neutral/dim, line-2 rules apply as usual)
+101
View File
@@ -0,0 +1,101 @@
import { describe, expect, it } from "vitest";
import {
activityColorSlug,
activityDurationLabel,
activityHeldMs,
showsMetaLine,
} from "./activity.js";
import type { Session } from "./types.js";
describe("activityHeldMs", () => {
it("measures time spent in the current state", () => {
const now = Date.now();
const since = new Date(now - 90_000).toISOString();
expect(activityHeldMs(since, now)).toBe(90_000);
});
it("returns null for payloads that predate #102 (epoch default)", () => {
expect(activityHeldMs(undefined, Date.now())).toBeNull();
expect(activityHeldMs(new Date(0).toISOString(), Date.now())).toBeNull();
});
it("returns null for unparseable timestamps", () => {
expect(activityHeldMs("not-a-time", Date.now())).toBeNull();
});
it("never goes negative", () => {
const now = Date.now();
expect(activityHeldMs(new Date(now + 5_000).toISOString(), now)).toBe(0);
});
});
describe("activityDurationLabel (#102)", () => {
it("floors whole seconds under a minute", () => {
expect(activityDurationLabel(30_400)).toBe("30s");
expect(activityDurationLabel(59_900)).toBe("59s");
});
it("floors whole minutes under an hour", () => {
expect(activityDurationLabel(60_000)).toBe("1m");
expect(activityDurationLabel(4 * 60_000 + 59_999)).toBe("4m");
});
it("floors whole hours from an hour up, with no days unit", () => {
expect(activityDurationLabel(60 * 60_000)).toBe("1h");
expect(activityDurationLabel(2 * 3_600_000 + 59 * 60_000 + 59_999)).toBe("2h");
expect(activityDurationLabel(26 * 3_600_000)).toBe("26h");
});
});
describe("activityColorSlug", () => {
it("maps each known state to its contract slug", () => {
expect(activityColorSlug("Active")).toBe("active");
expect(activityColorSlug("Idle")).toBe("idle");
expect(activityColorSlug("AwaitingInput")).toBe("awaiting-input");
expect(activityColorSlug("Error")).toBe("error");
});
it("treats an unknown variant as idle so rendering never fails", () => {
expect(activityColorSlug("Teleported")).toBe("idle");
});
});
function session(overrides: Partial<Session>): Session {
return {
id: "11111111-2222-3333-4444-555555555555",
cwd: "/home/naps/tea/maestro",
command: "claude",
env: {},
metadata: {},
status: "Running",
created_at: "2026-08-24T10:00:00Z",
activity: "Active",
...overrides,
};
}
describe("showsMetaLine", () => {
const fresh = new Date(Date.now() - 10_000).toISOString();
it("stays hidden for a freshly-active session", () => {
expect(showsMetaLine(session({ activity_since: fresh }))).toBe(false);
});
it("appears once the state has been held past 30 seconds", () => {
const held = new Date(Date.now() - 31_000).toISOString();
expect(showsMetaLine(session({ activity_since: held }))).toBe(true);
});
it("appears for blocked work, exited sessions and reported errors", () => {
expect(
showsMetaLine(session({ activity_since: fresh, blocked_work: { uncommitted_files: 1 } })),
).toBe(true);
expect(showsMetaLine(session({ activity_since: fresh, status: "Dead" }))).toBe(true);
expect(showsMetaLine(session({ activity_since: fresh, activity: "Error" }))).toBe(true);
});
it("needs no activity timestamp when another trigger holds", () => {
expect(showsMetaLine(session({ activity_since: undefined, status: "Dead" }))).toBe(true);
});
});
+56
View File
@@ -0,0 +1,56 @@
// docs/SIDEBAR.md: the session card's meta line — activity colour mapping and
// the shared duration format. Both clients compute it identically; the TUI
// mirrors this in crates/maestro-tui.
import type { ActivityState, IsoTimestamp, Session } from "./types.js";
import { sessionBlockers } from "./types.js";
/** A state held shorter than this keeps the card to one line (contract rule 1). */
const META_LINE_MIN_HOLD_MS = 30_000;
// Payloads predating #102 default `activity_since` to the Unix epoch; anything
// implausibly old is treated as "never observed" rather than a huge duration.
const PLAUSIBLE_EPOCH_MS = Date.UTC(2010, 0, 1);
export function activityHeldMs(since: IsoTimestamp | undefined, now: number): number | null {
if (!since) return null;
const t = Date.parse(since);
if (Number.isNaN(t) || t < PLAUSIBLE_EPOCH_MS) return null;
return Math.max(0, now - t);
}
/** `<60s` → whole seconds, `<60m` → whole minutes, else whole hours. Floored
* everywhere so the counter never shows a duration the state hasn't reached. */
export function activityDurationLabel(heldMs: number): string {
const s = Math.floor(heldMs / 1000);
if (s < 60) return `${s}s`;
const m = Math.floor(s / 60);
if (m < 60) return `${m}m`;
return `${Math.floor(m / 60)}h`;
}
/** CSS hook for the state's colour (`styles.css` maps slugs to tokens). An
* unknown variant degrades to idle so rendering never fails (Precedence). */
export function activityColorSlug(state: ActivityState | string): string {
switch (state) {
case "Active":
return "active";
case "AwaitingInput":
return "awaiting-input";
case "Error":
return "error";
default:
return "idle";
}
}
/** Line 2 renders only when at least one contract trigger holds. */
export function showsMetaLine(s: Session, now: number = Date.now()): boolean {
const held = activityHeldMs(s.activity_since, now);
return (
(held !== null && held >= META_LINE_MIN_HOLD_MS) ||
sessionBlockers(s) !== null ||
s.status === "Dead" ||
s.activity === "Error"
);
}
+119
View File
@@ -104,3 +104,122 @@ describe("blocked-work indicator (#83)", () => {
expect(confirmations).toEqual(['Kill session "claude"?']);
});
});
describe("session cards (#107)", () => {
const ago = (ms: number): string => new Date(Date.now() - ms).toISOString();
it("keeps the name and the actions in the same flow line, actions reserving their width", () => {
const s = session({ id: "aaaaaaaa-0000-0000-0000-000000000010" });
const el = renderSidebar(storeWith([s])).el;
const line1 = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line1");
expect(line1).not.toBeNull();
// Same flex line ⇒ the name truncates before it can ever reach the buttons.
expect(line1?.querySelector(".leaf-name")).not.toBeNull();
expect(line1?.querySelector(".leaf-actions")).toBe(line1?.lastElementChild);
});
it("stays a single line while freshly active", () => {
const s = session({
id: "aaaaaaaa-0000-0000-0000-000000000011",
activity: "Active",
activity_since: ago(5_000),
});
const el = renderSidebar(storeWith([s])).el;
expect(rowFor(el, s.id)?.querySelector(".card-line2")).toBeNull();
});
it("shows dot + floored duration once the state has been held past 30s", () => {
const s = session({
id: "aaaaaaaa-0000-0000-0000-000000000012",
activity: "Active",
activity_since: ago(4 * 60_000 + 30_000),
});
const el = renderSidebar(storeWith([s])).el;
const line2 = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2");
expect(line2?.dataset.activity).toBe("active");
expect(line2?.querySelector(".activity-dot")).not.toBeNull();
expect(line2?.querySelector(".activity-duration")?.textContent).toBe("4m");
});
it("maps each activity state to its contract slug", () => {
const mk = (id: string, activity: string) =>
session({
id,
activity: activity as Session["activity"],
status: "Running",
activity_since: ago(90_000),
});
const idle = mk("aaaaaaaa-0000-0000-0000-000000000013", "Idle");
const wait = mk("aaaaaaaa-0000-0000-0000-000000000014", "AwaitingInput");
const error = mk("aaaaaaaa-0000-0000-0000-000000000015", "Error");
const el = renderSidebar(storeWith([idle, wait, error])).el;
expect(rowFor(el, idle.id)?.querySelector(".card-line2")?.getAttribute("data-activity")).toBe(
"idle",
);
expect(rowFor(el, wait.id)?.querySelector(".card-line2")?.getAttribute("data-activity")).toBe(
"awaiting-input",
);
expect(rowFor(el, error.id)?.querySelector(".card-line2")?.getAttribute("data-activity")).toBe(
"error",
);
});
it("treats an unknown activity variant as idle instead of failing to render", () => {
const s = session({
id: "aaaaaaaa-0000-0000-0000-000000000016",
activity: "Teleported" as Session["activity"],
activity_since: ago(120_000),
});
const el = renderSidebar(storeWith([s])).el;
const line2 = rowFor(el, s.id)?.querySelector(".card-line2");
expect(line2?.getAttribute("data-activity")).toBe("idle");
expect(line2?.querySelector(".activity-duration")?.textContent).toBe("2m");
});
it("moves blocked work onto line 2 in the shared phrasing", () => {
const s = session({
id: "aaaaaaaa-0000-0000-0000-000000000017",
blocked_work: { uncommitted_files: 3, unpushed_commits: 2 },
});
const el = renderSidebar(storeWith([s])).el;
const line2 = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2");
expect(line2?.textContent).toContain("⚠");
expect(line2?.textContent).toContain("3 uncommitted files, 2 unpushed commits");
// Line 1 carries no badges.
expect(rowFor(el, s.id)?.querySelector(".leaf-badge")).toBeNull();
});
it("shows exited on line 2 for dead sessions", () => {
const s = session({
id: "aaaaaaaa-0000-0000-0000-000000000018",
status: "Dead",
});
const el = renderSidebar(storeWith([s])).el;
const line2 = rowFor(el, s.id)?.querySelector<HTMLElement>(".card-line2");
expect(line2?.textContent).toContain("exited");
});
it("carries the state word only in tooltips and aria labels, never as text", () => {
const s = session({
id: "aaaaaaaa-0000-0000-0000-000000000019",
command: "claude",
metadata: { name: "worker" },
activity: "AwaitingInput",
activity_since: ago(90_000),
});
const el = renderSidebar(storeWith([s])).el;
const row = rowFor(el, s.id) as HTMLElement;
const dot = row.querySelector<HTMLElement>(".activity-dot");
expect(dot?.getAttribute("title")).toContain("Awaiting input");
expect(dot?.getAttribute("aria-label")).toContain("Awaiting input");
expect(row.textContent).not.toMatch(/awaiting.?input/i);
});
it("keeps the attach navigation and depth indentation", () => {
const s = session({ id: "aaaaaaaa-0000-0000-0000-00000000001a" });
const el = renderSidebar(storeWith([s])).el;
const row = rowFor(el, s.id) as HTMLAnchorElement;
expect(row.getAttribute("href")).toBe("#/attach/aaaaaaaa-0000-0000-0000-00000000001a");
expect(row.style.paddingLeft).toMatch(/^\d+(\.\d+)?px$/);
});
});
+63 -15
View File
@@ -4,6 +4,7 @@ import { HUD_TOGGLE_EVENT, isHudEnabled, toggleHud } from "./debug.js";
import { CatalogStore } from "./events.js";
import type { Session } from "./types.js";
import { abbreviateFolderName, formatInTheWay, sessionBlockers, sessionName } from "./types.js";
import { activityColorSlug, activityDurationLabel, activityHeldMs, showsMetaLine } from "./activity.js";
import type { TreeNode } from "./tree.js";
import { buildTree } from "./tree.js";
import { createThemeToggle } from "./theme.js";
@@ -17,6 +18,41 @@ export function requestOpenSpawn(): void {
const collapsed = new Set<string>();
// docs/SIDEBAR.md: the state word is never rendered — the dot's colour carries
// it. It survives only in tooltips/aria labels so meaning is not colour-only.
const STATE_WORDS: Record<string, string> = {
active: "Active",
idle: "Idle",
"awaiting-input": "Awaiting input",
error: "Error",
};
function metaLine(s: Session, now: number): string {
const name = sessionName(s);
const dead = s.status === "Dead";
const blockers = sessionBlockers(s);
const slug = activityColorSlug(s.activity ?? "Idle");
const stateWord = STATE_WORDS[slug] ?? STATE_WORDS.idle;
const held = activityHeldMs(s.activity_since, now);
const duration = held !== null ? activityDurationLabel(held) : null;
// The directory is the enclosing folder, so only surface the command — and
// only when it isn't already what the name shows.
const showCmd = s.command !== name;
const fragments = [
`<span class="activity-dot" role="img" title="${escapeHtml(stateWord)}" aria-label="${escapeHtml(stateWord)}"></span>`,
duration ? `<span class="activity-duration">${duration}</span>` : "",
blockers
? `<span class="card-flag leaf-blocked" title="Kill will be refused unless forced">⚠ ${escapeHtml(formatInTheWay(blockers))}</span>`
: "",
dead ? `<span class="card-flag">exited</span>` : "",
showCmd
? `<span class="card-flag leaf-cmd" title="${escapeHtml(s.command)}">${escapeHtml(s.command)}</span>`
: "",
];
return `<span class="card-line2" data-activity="${slug}">${fragments.join("")}</span>`;
}
function renderNode(node: TreeNode, depth: number): HTMLElement {
if (node.kind === "folder") {
const wrap = document.createElement("div");
@@ -52,30 +88,34 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
}
const s = node.session;
const now = Date.now();
const row = document.createElement("a");
row.className = "tree-leaf";
row.className = "tree-leaf session-card";
row.href = `#/attach/${encodeURIComponent(s.id)}`;
row.style.paddingLeft = `${depth * 16 + 8}px`;
row.dataset.sessionId = s.id;
const running = s.status === "Running";
row.dataset.status = running ? "running" : "dead";
const name = sessionName(s);
row.setAttribute("aria-label", `${name}, ${running ? "running" : "exited"}`);
// The directory is the enclosing folder, so only surface the command — and
// only when it isn't already what the name shows.
const showCmd = s.command !== name;
// #83: warn on the row itself, in `formatInTheWay`'s shared phrasing, so
// "this will be refused" is visible before the kill is attempted.
const blockers = sessionBlockers(s);
const stateWord =
STATE_WORDS[activityColorSlug(s.activity ?? "Idle")] ?? STATE_WORDS.idle;
row.setAttribute(
"aria-label",
`${name}, ${running ? "running" : "exited"}, ${stateWord}`,
);
// docs/SIDEBAR.md line 1: name + top-right actions in the same flow line —
// the actions reserve their width, so the name truncates before it can ever
// reach them. Line 2 renders only when a contract trigger holds.
const showMeta = showsMetaLine(s, now);
row.innerHTML = `
<span class="leaf-name">${escapeHtml(name)}</span>
${showCmd ? `<span class="leaf-meta"><span class="leaf-cmd">${escapeHtml(s.command)}</span></span>` : ""}
${running ? "" : `<span class="leaf-badge">exited</span>`}
${blockers ? `<span class="leaf-badge leaf-blocked" title="Kill will be refused unless forced">⚠ ${escapeHtml(formatInTheWay(blockers))}</span>` : ""}
<span class="leaf-actions">
<button class="leaf-act leaf-clone" type="button" title="Spawn similar" aria-label="Spawn similar to ${escapeHtml(name)}">⧉</button>
<button class="leaf-act leaf-kill" type="button" title="Kill session" aria-label="Kill ${escapeHtml(name)}">✕</button>
<span class="card-line1">
<span class="leaf-name">${escapeHtml(name)}</span>
<span class="leaf-actions">
<button class="leaf-act leaf-clone" type="button" title="Spawn similar" aria-label="Spawn similar to ${escapeHtml(name)}">⧉</button>
<button class="leaf-act leaf-kill" type="button" title="Kill session" aria-label="Kill ${escapeHtml(name)}">✕</button>
</span>
</span>
${showMeta ? metaLine(s, now) : ""}
`;
const similarBtn = row.querySelector(".leaf-clone") as HTMLButtonElement;
similarBtn.addEventListener("click", (ev) => {
@@ -395,6 +435,13 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
const unsubscribe = store.subscribe(refresh);
// Contract granularity: re-render at least every 30s while visible so the
// duration cutover points land within one tick.
const clock = setInterval(() => {
if (document.visibilityState !== "visible") return;
refresh();
}, 30_000);
return {
el,
setActive(id: string | null) {
@@ -410,6 +457,7 @@ export function renderSidebar(store: CatalogStore, opts: SidebarOptions = {}): S
applyHighlights();
},
dispose() {
clearInterval(clock);
document.removeEventListener("catalog-rerender", rerenderHandler);
unsubscribe();
},
+66 -18
View File
@@ -59,20 +59,28 @@ function leafRow(opts: {
status: "running" | "dead";
active?: boolean;
indent?: number;
activity?: "active" | "idle" | "awaiting-input" | "error";
duration?: string;
}): HTMLElement {
const row = h("a", "tree-leaf");
const row = h("a", "tree-leaf session-card");
(row as HTMLAnchorElement).href = "#/kit";
row.dataset.status = opts.status;
if (opts.active) row.classList.add("is-active");
row.style.paddingLeft = `${(opts.indent ?? 0) * 16 + 8}px`;
const flags = [
opts.status === "dead" ? `<span class="card-flag">exited</span>` : "",
opts.cmd !== opts.name ? `<span class="card-flag leaf-cmd">${opts.cmd}</span>` : "",
].join("");
row.innerHTML = `
<span class="leaf-name">${opts.name}</span>
${opts.cmd !== opts.name ? `<span class="leaf-meta"><span class="leaf-cmd">${opts.cmd}</span></span>` : ""}
${opts.status === "dead" ? `<span class="leaf-badge">exited</span>` : ""}
<span class="leaf-actions">
<button class="leaf-act leaf-clone" type="button" title="Spawn similar" aria-label="Spawn similar to ${opts.name}">⧉</button>
<button class="leaf-act leaf-kill" type="button" title="Kill session" aria-label="Kill ${opts.name}">✕</button>
</span>`;
<span class="card-line1">
<span class="leaf-name">${opts.name}</span>
<span class="leaf-actions">
<button class="leaf-act leaf-clone" type="button" title="Spawn similar">⧉</button>
<button class="leaf-act leaf-kill" type="button" title="Kill session">✕</button>
</span>
</span>
${opts.activity ? `<span class="card-line2" data-activity="${opts.activity}"><span class="activity-dot" title="${opts.activity}"></span><span class="activity-duration">${opts.duration ?? ""}</span>${flags}</span>` : ""}
`;
return row;
}
@@ -190,14 +198,17 @@ export function renderKit(): HTMLElement {
// --- chips & badges ---
{
const { el, body } = section("Chips & badges", "Status-bearing pills and counts.");
const activeLine = h(
"span",
"card-line2",
`<span class="activity-dot"></span><span class="activity-duration">4m</span>`,
);
activeLine.setAttribute("data-activity", "active");
body.append(
specimen("session-tally", h("span", "session-tally", "6 sessions · 5 live")),
specimen("folder-count", h("span", "folder-count", "4")),
specimen("leaf-badge", h("span", "leaf-badge", "exited")),
specimen(
"attach-state · open",
h("span", "attach-state", "live"),
),
specimen("card-line2 · active", activeLine),
specimen("attach-state · open", h("span", "attach-state", "live")),
);
(body.lastElementChild?.querySelector(".attach-state") as HTMLElement)?.setAttribute(
"data-state",
@@ -215,19 +226,56 @@ export function renderKit(): HTMLElement {
{
const { el, body } = section(
"Session rows — nested by host, then directory",
"The working directory (home collapsed to ~) is the nesting, and single-child chains fold into one node like ~/git/maestro. “Alive” is a faint row wash; exited rows recede with a badge; the open session is highlighted.",
"docs/SIDEBAR.md cards: line 1 is name + top-right actions (the name truncates before it can reach them); line 2 only when there's something to say — dot + duration in the state's colour, then blocked-work / exited fragments.",
);
const list = h("div", "kit-tree");
list.append(
folderHeader("~/git/maestro", 3, 0),
folderHeader("web", 2, 1),
leafRow({ name: "redesign", cmd: "claude", status: "running", indent: 2 }),
leafRow({ name: "dev-server", cmd: "vite dev", status: "running", indent: 2, active: true }),
leafRow({
name: "dev-server",
cmd: "vite dev",
status: "running",
indent: 2,
active: true,
activity: "active",
duration: "4m",
}),
folderHeader("crates/daemon", 1, 1),
leafRow({ name: "daemon-work", cmd: "claude", status: "running", indent: 2 }),
leafRow({
name: "daemon-work",
cmd: "claude",
status: "running",
indent: 2,
activity: "awaiting-input",
duration: "12s",
}),
leafRow({
name: "flaky-agent",
cmd: "claude",
status: "running",
indent: 2,
activity: "error",
duration: "2h",
}),
folderHeader("~/work/acme", 2, 0),
leafRow({ name: "billing-api", cmd: "claude", status: "running", indent: 1 }),
leafRow({ name: "scratch", cmd: "bash", status: "dead", indent: 1 }),
leafRow({
name: "billing-api",
cmd: "claude",
status: "running",
indent: 1,
activity: "idle",
duration: "26m",
}),
leafRow({
name: "scratch",
cmd: "bash",
status: "dead",
indent: 1,
activity: "idle",
duration: "5h",
}),
leafRow({ name: "monitor", cmd: "btop", status: "running", indent: 0 }),
);
body.classList.add("kit-tree-host");
+63 -38
View File
@@ -787,60 +787,85 @@ textarea {
font-weight: 400;
}
/* #107: session cards per docs/SIDEBAR.md — line 1 (name + top-right actions)
always, line 2 (meta) only when it has something to say. */
.tree-leaf.session-card {
flex-direction: column;
align-items: stretch;
gap: 1px;
}
.card-line1 {
display: flex;
align-items: center;
gap: var(--sp-2);
min-width: 0;
}
.leaf-name {
font-weight: 500;
font-size: var(--fs-13);
flex: 0 1 auto;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.leaf-meta {
font-size: var(--fs-11);
color: var(--muted);
margin-left: auto;
padding-left: var(--sp-2);
/* Grows to push the actions to the right edge but shrinks first, so the name
truncates before it can ever reach them — overlap is a defect (#107). */
flex: 1 1 auto;
min-width: 0;
flex: 0 1 auto;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
display: inline-flex;
align-items: baseline;
}
/* Line 2 — dot + duration in the state's colour, then muted fragments. The
state word itself is never spelled out here; the colour carries it. */
.card-line2 {
display: flex;
align-items: center;
gap: var(--sp-2);
}
.leaf-cmd {
color: var(--muted);
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.leaf-badge {
font-size: var(--fs-11);
letter-spacing: 0.02em;
text-transform: uppercase;
min-width: 0;
color: var(--muted);
border: 1px solid var(--border);
border-radius: var(--r-pill);
padding: 1px 8px;
}
.card-line2[data-activity="active"] {
color: var(--live);
}
.card-line2[data-activity="idle"] {
color: var(--muted);
}
.card-line2[data-activity="awaiting-input"] {
color: var(--warn);
}
.card-line2[data-activity="error"] {
color: var(--danger);
}
.activity-dot {
width: 7px;
height: 7px;
border-radius: 50%;
background: currentColor;
flex: 0 0 auto;
}
/* #83: the session row's blocked-work warning — an unforced kill will be
refused, and the operator should see that before pressing the button. */
.leaf-badge.leaf-blocked {
color: var(--warn, #b45309);
border-color: var(--warn, #b45309);
.activity-duration {
color: inherit;
flex: 0 0 auto;
}
/* Blocked-work / exited / command fragments recede: the ⚠ glyph already
signals severity and "exited" dims with the row. */
.card-flag {
color: var(--faint);
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
/* Actions live in line 1's flow at its right edge — never overlaid on the
name (#107). They reserve their width even while hover-faded. */
.leaf-actions {
position: absolute;
right: var(--sp-1);
top: 50%;
transform: translateY(-50%);
flex: 0 0 auto;
margin-left: auto;
display: inline-flex;
gap: 2px;
}
+4
View File
@@ -26,6 +26,10 @@ export interface Session {
foreground?: string | null;
/** Inferred activity. Defaults to `Idle` on the wire when omitted. */
activity?: ActivityState;
/** Short human string an agent reported alongside its state (#105) — e.g.
* why it is in `Error`. Shown on a sidebar card's meta line while the
* report is in force; cleared when the report lapses or is replaced. */
activity_detail?: string | null;
/** Wall-clock of the most recent observed PTY output (NAP-340). */
last_activity_at?: IsoTimestamp;
/** Wall-clock of when the session entered its current `activity` state