Session tools
Start, escalate, inspect and end lifecycle sessions.
Start, escalate, inspect and end lifecycle sessions.
| Tool | Description | Platforms |
|---|---|---|
start_session | Optionally create or return a lifecycle session before acting. | macOS, Linux, Windows |
escalate_session | Deprecated compatibility tool for legacy capture-scope sessions. | macOS, Linux, Windows |
get_session | Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. | macOS, Linux, Windows |
list_sessions | List content-free lifecycle summaries attached to this authenticated transport lease. | macOS, Linux, Windows |
get_session_state | Deprecated compatibility alias that reads a live legacy session's capture policy. | macOS, Linux, Windows |
end_session | End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. | macOS, Linux, Windows |
Served by cua-driver mcp; see MCP tools for every tool.
start_session#Optionally create or return a lifecycle session before acting. For multi-call work, prefer a short public session label and repeat it on every call that accepts it; an omitted value uses the authenticated transport lease's implicit session instead. This tool is optional because an ordinary action can create or reuse a named run directly. Use it to set the initial cursor theme before acting or to revive a public name after it has ended; ordinary actions never revive ended names. capture_scope is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.
Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
capture_scope | "auto" | "window" | "desktop" | Deprecated compatibility policy. New callers select window or desktop modality on each action instead of storing it on the session. | |
cursor_motion | object | Optional initial cursor motion (style, timing, effects and tuning). The host applies it before the cursor is first made visible. A later set_agent_cursor_motion call wins; this wins over the saved default (cursor.motion.* in the driver config) and the built-in signature_arc. Reduced motion always wins. | |
cursor_motion.arc_flow | number | Added to the arc asymmetry of signature_arc, spring_settle and comet_swoop: positive moves the apex toward the destination. Clamped to -1..1 (default 0). | |
cursor_motion.arc_size | number | Scales the arc of signature_arc, spring_settle and comet_swoop: 0.25 (default) keeps the style's arc, 0 is a straight line, 0.5 doubles it. Clamped to 0..1. | |
cursor_motion.dwell_after_click_ms | number | Pause after a click animation, in milliseconds. Clamped to 0..5000 (default 80). | |
cursor_motion.effects | object | Turn effects on or off. Omit a field to keep it; "default" restores the style default. | |
cursor_motion.end_handle | number | Arc control-point offset from the end, as a fraction of the distance, for signature_arc, spring_settle and comet_swoop. Clamped to 0..1 (default 0.3). | |
cursor_motion.glide_duration_ms | number | Move duration in milliseconds for fixed timing (1430 ms when 0, the default). A nonzero value with native or the default steady timing also fixes the duration. Clamped to 0..5000. | |
cursor_motion.idle_hide_ms | number | Hide the cursor after this many idle milliseconds; 0 never hides it. Clamped to 0..60000 (default 15000). | |
cursor_motion.spring | number | Arrival spring damping for classic: 1 is critically damped, 0.3 is bouncy. Clamped to 0.3..1 (default 0.72). | |
cursor_motion.start_handle | number | Arc control-point offset from the start, as a fraction of the distance, for signature_arc, spring_settle and comet_swoop. Clamped to 0..1 (default 0.3). | |
cursor_motion.style | "signature_arc" | "spring_settle" | "magnetic" | "comet_swoop" | "adaptive" | "classic" | Trajectory style. signature_arc (default) is one arc with a small follow-through; spring_settle lands with one soft bounce; magnetic is pulled into the target; comet_swoop is a wide arc with a short trail; adaptive picks a careful approach for small targets and a swoop for long moves; classic is the previous Dubins glide. When the theme's reduced motion is on, every move is a short straight glide with no effects. | |
cursor_motion.timing | "native" | "fitts" | "fixed" | "relaxed" | "steady" | "calm" | "deliberate" | steady (default) keeps the style's timing but makes every move take at least 600 ms, with a gentler ease; relaxed and calm do the same with a 450 or 750 ms floor. native uses the style's own timing; fitts scales the move time with distance and target size; deliberate is a slower Fitts curve (450..1300 ms); fixed uses glide_duration_ms (1430 ms when 0). | |
cursor_motion.turn_radius | number | Minimum turning radius of the classic glide path, in points; smaller turns tighter. Clamped to 1..1000 (default 80). | |
cursor_theme | object | Optional initial cursor theme. The host applies it before the cursor is first made visible, avoiding a flash of the default theme. | |
cursor_theme.reduced_motion | "auto" | "on" | "off" | "auto" | |
cursor_theme.theme_id | string | ||
session | string | Optional stable public label for this run (e.g. "research-run-1"). When omitted, the authenticated transport lease's implicit session is created or returned. |
escalate_session#Deprecated compatibility tool for legacy capture-scope sessions. New callers select window or desktop modality on each action. No deescalate_session tool exists.
Effect: mutating. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
detail | string | Optional bounded diagnostic detail. Never use secrets or page content. | |
reason | "ax_tree_pixel_mismatch" | "background_delivery_failed" | "foreground_ineffective" | "no_window_target" | "other" | required | Why the window-scoped attempt failed and desktop capture is needed. |
session | string | required | Public label of the legacy capture-scope session to escalate. |
Example arguments
{"session":"<session>","reason":"ax_tree_pixel_mismatch"}get_session#Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. Omit session to inspect its implicit session.
Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
session | string | Optional public label. When omitted, inspect the caller's attached implicit session. |
list_sessions#List content-free lifecycle summaries attached to this authenticated transport lease. It does not enumerate other callers' sessions.
Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
cursor | string | Opaque continuation cursor returned by a previous call. | |
limit | integer | Maximum number of content-free summaries to return (default 50, max 100). Ordinary agent transports are scoped to their own lease. Minimum: 0. |
get_session_state#Deprecated compatibility alias that reads a live legacy session's capture policy. Use get_session for lifecycle state.
Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
session | string | Optional public label. When omitted, inspect the caller's attached implicit session. |
end_session#End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. Omit session to end the authenticated transport's implicit session. Idempotent.
Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
session | string | Optional public label to end. When omitted, end the caller's attached implicit session. |