Skip to content

The agent that grows with you

docs(bot-desktop): comments match the human-lease lapse and the stable idle command

kshitijk4poora88398c07fc9
diff --git a/tools/bot_desktop/idle_watch.py b/tools/bot_desktop/idle_watch.py
index 534e4082d70..828e93df3d1 100644
--- a/tools/bot_desktop/idle_watch.py
+++ b/tools/bot_desktop/idle_watch.py
@@ -2,11 +2,10 @@
The screen outlives the gateway that started it on purpose (a restarted gateway re-attaches to it), so the
gateway's display watcher cannot be the only thing that ever stops it: when no gateway comes back, Xvnc +
-Xfce and any browser left open run until reboot. ``launcher.sh`` therefore runs
-``python -m tools.bot_desktop.idle_watch`` in a loop of its own. Each run applies
-:func:`runtime.stop_if_idle` (the same ``bot_desktop.idle_stop_minutes`` window and the same rule that a
-human holding the screen is never timed out) and prints how long the launcher should sleep before the next
-run, so no interpreter stays resident between checks.
+Xfce and any browser left open run until reboot. ``launcher.sh`` therefore runs this module (through the
+install's stable command) in a loop of its own. Each run applies :func:`runtime.stop_if_idle` (the same
+``bot_desktop.idle_stop_minutes`` window and the same human-lease rule as the gateway's watcher) and prints
+how long the launcher should sleep before the next run, so no interpreter stays resident between checks.
"""
from __future__ import annotations
diff --git a/tools/bot_desktop/launcher.sh b/tools/bot_desktop/launcher.sh
index ef963da6d20..abfc1c5ccca 100755
--- a/tools/bot_desktop/launcher.sh
+++ b/tools/bot_desktop/launcher.sh
@@ -277,7 +277,7 @@ xset -display "$DISPLAY" s off -dpms s noblank 2>/dev/null || true
# ---- idle self-stop: the screen outlives the gateway that started it (a restarted gateway re-attaches),
# so it must also stop itself when no gateway ever comes back. tools/bot_desktop/idle_watch.py applies the
-# gateway watcher's own rule (bot_desktop.idle_stop_minutes; never while a human holds the screen) once per
+# gateway watcher's own rule (bot_desktop.idle_stop_minutes; never while a human is using the screen) once per
# run and prints the seconds until the next check; nothing stays resident in between. runtime.py passes the
# install's command for it, shell-quoted (the launcher's pid is appended); skipped when it passed none (the
# sandbox-hosted screen, whose sandbox lifetime bounds it).
diff --git a/tools/bot_desktop/runtime.py b/tools/bot_desktop/runtime.py
index 4ebf0094de6..e68c21269a4 100644
--- a/tools/bot_desktop/runtime.py
+++ b/tools/bot_desktop/runtime.py
@@ -422,8 +422,9 @@ def _should_auto_start(env: dict[str, str]) -> bool:
# A desktop nobody is using still holds ~220 MiB (plus whatever browser was left open). Every use —
# a computer_use action, a browser spawn onto the screen, a viewer attached, a human takeover — stamps
# ``activity``; :func:`stop_if_idle` stops a screen idle past ``bot_desktop.idle_stop_minutes`` unless a
-# human holds it. Two callers apply it: the gateway's display watcher and the screen's own launcher
-# (``idle_watch``), so a screen whose gateway never came back still stops. The next use starts it again.
+# human is using it (see the lease lapse below). Two callers apply it: the gateway's display watcher and
+# the screen's own launcher (``idle_watch``), so a screen whose gateway never came back still stops. The
+# next use starts it again.
DEFAULT_IDLE_STOP_MINUTES = 30
# A human holding the screen is never timed out while there is evidence of one: an attached viewer stamps
# ``activity`` (every RFB update it receives, at most once a minute; the panel clock repaints every minute).
@@ -803,7 +804,8 @@ def _spawn_and_wait(sd: Path, wait_seconds: float) -> DesktopStatus:
# command (the ``hermes --run-module`` launcher on a store install, which follows Python pin changes
# and picks the current dependency generation at every run; this interpreter elsewhere), in this
# home, first once the screen could be due (nothing is idle at start). The screen outlives updates,
- # so neither this interpreter nor the inherited PYTHONPATH generation may be pinned.
+ # so the inherited PYTHONPATH generation is never pinned, and on a store install neither is this
+ # interpreter.
"HERMES_BD_IDLE_CMD": shlex.join(installation_command(
Path(__file__).resolve().parents[2], module="tools.bot_desktop.idle_watch")),
"HERMES_BD_HOME": str(get_hermes_home()),
@@ -888,7 +890,8 @@ def _sandbox_published_env() -> dict[str, str]:
def stop(still_due: Optional[Callable[[], bool]] = None) -> bool:
"""Stop this profile's desktop; True when a running launcher (or the X server a dead one left behind)
- was signalled. ``still_due`` is re-asked under ``start.lock``; False there leaves the screen running."""
+ was signalled. ``still_due`` is asked again before anything is killed (under ``start.lock`` for a screen on
+ this host); False there leaves the screen running."""
from tools.bot_desktop import sandbox_host
if sandbox_host._read_marker() or placement.resolve().where == placement.TERMINAL:
if still_due is not None and not still_due():
diff --git a/website/docs/user-guide/features/bot-screen.md b/website/docs/user-guide/features/bot-screen.md
index 8a0a9747b42..1e7a3e4f529 100644
--- a/website/docs/user-guide/features/bot-screen.md
+++ b/website/docs/user-guide/features/bot-screen.md
@@ -94,8 +94,7 @@ reverse proxy's access log may record an already-spent ticket.
started it is gone and never restarts. A screen a human has taken over is
kept while their viewer keeps it in use; once nothing has used it for four
windows, and at least 10 minutes (a viewer whose link dropped and never came
- back), it stops as well.
- Practical guidance
+ back), it stops as well and control returns to the agent. Practical guidance
for small instances: 4 GB runs the desktop, 8 GB is where a takeover with a
browser is comfortable.