feat: polish inactivity timeout support

Author: junhsss

skills/steel-browser/references/steel-browser-lifecycle.md

@@ -51,6 +51,9 @@ Main flags:
 - `--credentials` — enable credential injection for the session
 - `--profile <name>` — load a named browser profile into the session
 - `--update-profile` — save session state back to the profile on end
+- `--inactivity-timeout <ms>` — release the session after this much idle time (no CDP command or remote input). Defaults to 120000 (2 min); pass `0` to disable.
+
+Note: sessions created via the CLI auto-release after ~2 minutes of inactivity by default. If you expect a session to sit idle between manual steps, pass `--inactivity-timeout 0` (disable) or a larger value at `start`, and check `inactivity_timeout` in the start output.
 
 Parse these output fields:
 
@@ -59,6 +62,7 @@ Parse these output fields:
 - `name`: session alias if provided
 - `live_url`: live-view URL when available
 - `connect_url`: display-safe URL with sensitive values redacted
+- `inactivity_timeout`: idle-release limit when set (human output); `inactivityTimeoutMs` in JSON
 
 Use `id` for stable machine parsing. Treat `connect_url` as display metadata, not a raw credential.
 

src/browser/daemon/protocol.rs

@@ -60,6 +60,8 @@ pub struct SessionInfo {
     /// Session timeout in milliseconds (from create params). `None` = no timeout.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub timeout_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub inactivity_timeout_ms: Option<u64>,
     /// Epoch milliseconds when the session was created. Used with `timeout_ms`
     /// to compute remaining time on the client side.
     #[serde(skip_serializing_if = "Option::is_none")]

src/browser/daemon/server.rs

@@ -8,7 +8,8 @@ use tokio::net::UnixListener;
 use crate::api::client::SteelClient;
 use crate::browser::engine::BrowserEngine;
 use crate::browser::lifecycle::{
-    get_session_created_at_ms, get_session_timeout, to_session_summary,
+    get_session_created_at_ms, get_session_inactivity_timeout, get_session_timeout,
+    to_session_summary,
 };
 use crate::config::auth::{Auth, AuthSource};
 
@@ -64,6 +65,8 @@ pub async fn run(session_name: String, params: DaemonCreateParams) -> Result<()>
 
     // Prefer API-reported timeout over what we requested — the server may apply defaults
     let effective_timeout = get_session_timeout(&session).or(params.timeout_ms);
+    let effective_inactivity_timeout =
+        get_session_inactivity_timeout(&session).or(params.inactivity_timeout_ms);
     // Prefer API-reported createdAt; fall back to local clock
     let created_at_ms = get_session_created_at_ms(&session).or_else(|| {
         std::time::SystemTime::now()
@@ -81,6 +84,7 @@ pub async fn run(session_name: String, params: DaemonCreateParams) -> Result<()>
         viewer_url: summary.viewer_url,
         profile_id: summary.profile_id,
         timeout_ms: effective_timeout,
+        inactivity_timeout_ms: effective_inactivity_timeout,
         created_at_ms,
     };
 

src/browser/lifecycle.rs

@@ -111,6 +111,27 @@ pub fn get_session_timeout(session: &Value) -> Option<u64> {
     None
 }
 
+pub fn get_session_inactivity_timeout(session: &Value) -> Option<u64> {
+    let keys = [
+        "inactivityTimeout",
+        "inactivity_timeout",
+        "inactivityTimeoutMs",
+    ];
+    for key in &keys {
+        if let Some(v) = session.get(key) {
+            if let Some(n) = v.as_u64() {
+                return Some(n);
+            }
+            if let Some(s) = v.as_str()
+                && let Ok(n) = s.trim().parse::<u64>()
+            {
+                return Some(n);
+            }
+        }
+    }
+    None
+}
+
 /// Extract session creation timestamp as epoch milliseconds from API response.
 /// Looks for `createdAt` or `created_at` as ISO 8601 / RFC 3339 string.
 pub fn get_session_created_at_ms(session: &Value) -> Option<u64> {
@@ -517,6 +538,19 @@ mod tests {
         assert_eq!(get_session_timeout(&json!({"id": "s1"})), None);
     }
 
+    #[test]
+    fn inactivity_timeout_from_response() {
+        assert_eq!(
+            get_session_inactivity_timeout(&json!({"inactivityTimeout": 120000})),
+            Some(120000)
+        );
+        assert_eq!(
+            get_session_inactivity_timeout(&json!({"inactivityTimeout": "120000"})),
+            Some(120000)
+        );
+        assert_eq!(get_session_inactivity_timeout(&json!({"id": "s1"})), None);
+    }
+
     #[test]
     fn session_created_at_iso() {
         let s = json!({"createdAt": "2025-01-15T10:30:00Z"});

src/commands/browser/start.rs

@@ -82,6 +82,13 @@ pub async fn run(args: Args, session: Option<&str>) -> anyhow::Result<()> {
     let proxy_enabled = args.proxy.is_some();
     let namespace_set = args.namespace.is_some();
     let inactivity_timeout_ms = resolve_inactivity_timeout(args.inactivity_timeout);
+    if let (Some(timeout), Some(inactivity)) = (args.session_timeout, inactivity_timeout_ms)
+        && inactivity >= timeout
+    {
+        eprintln!(
+            "warning: --inactivity-timeout ({inactivity}ms) >= --session-timeout ({timeout}ms); inactivity timeout has no effect because the session timeout elapses first"
+        );
+    }
 
     // If a daemon is already running for this session name, stop it first.
     // `start` always creates a fresh session — use `steel browser sessions`
@@ -175,6 +182,9 @@ fn display_session_info(info: &SessionInfo) {
         if let Some(ref rem) = remaining {
             data["remainingMs"] = json!(rem.0);
         }
+        if let Some(ms) = info.inactivity_timeout_ms {
+            data["inactivityTimeoutMs"] = json!(ms);
+        }
         output::success_data(data);
     } else {
         println!("id: {}", info.session_id);
@@ -193,6 +203,9 @@ fn display_session_info(info: &SessionInfo) {
                 println!("expires_in: {label}");
             }
         }
+        if let Some(ms) = info.inactivity_timeout_ms {
+            println!("inactivity_timeout: {}", humanize_secs(ms / 1000));
+        }
     }
 }
 
@@ -209,18 +222,20 @@ fn remaining_time_str(info: &SessionInfo) -> Option<(u64, String)> {
         return Some((0, "expired".to_string()));
     }
     let remaining = expires_at - now;
-    let secs = remaining / 1000;
-    let label = if secs >= 3600 {
+    Some((remaining, humanize_secs(remaining / 1000)))
+}
+
+fn humanize_secs(secs: u64) -> String {
+    if secs >= 3600 {
         format!("{}h {}m", secs / 3600, (secs % 3600) / 60)
     } else if secs >= 60 {
         format!("{}m {}s", secs / 60, secs % 60)
     } else {
         format!("{secs}s")
-    };
-    Some((remaining, label))
+    }
 }
 
-fn resolve_inactivity_timeout(explicit: Option<u64>) -> Option<u64> {
+const fn resolve_inactivity_timeout(explicit: Option<u64>) -> Option<u64> {
     match explicit {
         None => Some(DEFAULT_INACTIVITY_TIMEOUT_MS),
         Some(0) => None,
@@ -249,4 +264,11 @@ mod tests {
     fn inactivity_zero_disables() {
         assert_eq!(resolve_inactivity_timeout(Some(0)), None);
     }
+
+    #[test]
+    fn humanize_secs_formats() {
+        assert_eq!(humanize_secs(45), "45s");
+        assert_eq!(humanize_secs(120), "2m 0s");
+        assert_eq!(humanize_secs(3661), "1h 1m");
+    }
 }

tests/cli_compat.rs

@@ -294,6 +294,7 @@ fn browser_start_flags() {
             flag("stealth"),
             flag_val_short("proxy", 'p'),
             flag_val("session-timeout"),
+            flag_val("inactivity-timeout"),
             flag("session-solve-captcha"),
             flag_val("profile"),
             flag("update-profile"),

tests/lifecycle_contract.rs

@@ -385,6 +385,7 @@ fn session_info_json_roundtrip() {
         viewer_url: Some("https://app.steel.dev/sessions/sess-123".to_string()),
         profile_id: Some("prof-1".to_string()),
         timeout_ms: Some(300_000),
+        inactivity_timeout_ms: Some(120_000),
         created_at_ms: Some(1_700_000_000_000),
     };
 
@@ -399,6 +400,7 @@ fn session_info_json_roundtrip() {
     assert!(back.viewer_url.is_some());
     assert_eq!(back.profile_id.as_deref(), Some("prof-1"));
     assert_eq!(back.timeout_ms, Some(300_000));
+    assert_eq!(back.inactivity_timeout_ms, Some(120_000));
     assert_eq!(back.created_at_ms, Some(1_700_000_000_000));
 }
 
@@ -413,6 +415,7 @@ fn session_info_minimal_roundtrip() {
         viewer_url: None,
         profile_id: None,
         timeout_ms: None,
+        inactivity_timeout_ms: None,
         created_at_ms: None,
     };
 
@@ -428,6 +431,7 @@ fn session_info_minimal_roundtrip() {
 
     // Optional fields should be omitted from JSON when None
     assert!(!json_str.contains("timeout_ms"));
+    assert!(!json_str.contains("inactivity_timeout_ms"));
     assert!(!json_str.contains("created_at_ms"));
 }