Screen Tool: Arrange Connected Control UI Layout
This page covers the screen tool for arranging browser-based Control UI panes. It is intended for developers using the ui-commands capability to manage session layouts.
Read this when
- You want an agent to split, focus, close, or navigate Control UI panes
- You want an agent to show or hide the sidebar, terminal, or browser panels
- You need the ui.command capability and fan-out contract
The screen tool enables an agent to manipulate the browser based Control UI. This is a structured layout and navigation interface, not a screenshot tool or browser automation utility.
This tool is only available when the originating client declares the ui-commands capability. A compatible Control UI must remain connected during execution; otherwise, the Gateway responds with UNAVAILABLE.
Actions
| Action | Effect | Optional inputs |
|---|---|---|
split_right | Divide the targeted session pane to the right | sessionKey (uses the current session if not specified) |
split_down | Divide the targeted session pane downward | sessionKey (uses the current session if not specified) |
close_pane | Remove the targeted session pane | sessionKey (uses the current session if not specified) |
focus | Bring the targeted session pane into focus | sessionKey (uses the current session if not specified) |
navigate | Launch the targeted session | sessionKey (uses the current session if not specified) |
sidebar_show / sidebar_hide | Toggle the main sidebar visibility | - |
terminal_show / terminal_hide | Toggle the operator terminal panel visibility | dock (bottom or right) when making it visible |
browser_show / browser_hide | Toggle the browser panel visibility | dock (bottom or right) when making it visible |
After the Gateway broadcasts the typed ui.command event, a successful command returns { "ok": true }.
Routing and security
In protocol v1, the command is sent to every Control UI that declares ui-commands; it is not directed at a single browser tab. This distinction is relevant when an operator has multiple dashboards open simultaneously.
The Gateway RPC requires operator.write. This tool can only modify presentation state: it cannot read pixels, capture screenshots, interact with arbitrary page elements, or bypass the permissions of the chosen session and operator panels.