# retoor <retoor@molodetz.nl>
from __future__ import annotations
from .spec import Action, Param
def arg(
name: str, description: str, required: bool = False, kind: str = "string"
) -> Param:
return Param(
name=name,
location="body",
description=description,
required=required,
type=kind,
)
CLIENT = (
"Runs in the user's own browser through the web terminal. Only effective in the web "
"interface with a live connection; elsewhere it reports that no browser is attached."
)
CLIENT_ACTIONS: tuple[Action, ...] = (
Action(
name="get_page_context",
method="LOCAL",
path="",
summary="Read the user's current page: URL, title, viewport, scroll, selected text, visible headings, and whether they are signed in",
description=CLIENT
+ " Use this to understand where the user is and what they are looking at before acting or guiding them.",
handler="client",
requires_auth=False,
read_only=True,
),
Action(
name="run_js",
method="LOCAL",
path="",
summary="Execute JavaScript in the user's browser and return its result",
description=(
CLIENT
+ " The code is the body of an async function; use 'return value' to return a "
"JSON-serializable result. You have full access to window and document. Use this for "
"anything not covered by the dedicated tools: read or change the DOM, drive a live "
"demo, inspect state, or update the screen. Prefer the dedicated tools "
"(highlight_element, show_toast, scroll_to_element, navigate_to, reload_page) when they fit."
),
handler="client",
requires_auth=False,
params=(
arg(
"code",
"JavaScript to run as an async function body. Return a JSON-serializable value.",
required=True,
),
),
),
Action(
name="highlight_element",
method="LOCAL",
path="",
summary="Highlight an element on screen with an outline and an optional callout label, for live tutorials",
description=CLIENT
+ " Scrolls the element into view and draws an attention outline. Call clear_highlights to remove it.",
handler="client",
requires_auth=False,
params=(
arg(
"selector",
"CSS selector, or the element's exact visible text (e.g. a heading or link label).",
required=True,
),
arg("label", "Optional callout text shown next to the element."),
),
),
Action(
name="clear_highlights",
method="LOCAL",
path="",
summary="Remove all highlights and callouts placed by highlight_element",
description=CLIENT,
handler="client",
requires_auth=False,
),
Action(
name="show_toast",
method="LOCAL",
path="",
summary="Show a brief on-screen message (toast) to the user",
description=CLIENT,
handler="client",
requires_auth=False,
params=(
arg("text", "Message to display.", required=True),
arg(
"duration_ms",
"How long to show it, in milliseconds (default 4000).",
kind="integer",
),
),
),
Action(
name="scroll_to_element",
method="LOCAL",
path="",
summary="Smoothly scroll an element into view",
description=CLIENT,
handler="client",
requires_auth=False,
params=(
arg(
"selector",
"CSS selector, or the element's exact visible text.",
required=True,
),
),
),
Action(
name="navigate_to",
method="LOCAL",
path="",
summary="Send the user's browser to a URL",
description=(
CLIENT
+ " Use a same-origin path like /feed or /docs/index.html, or a full URL. The "
"page reloads; the user's Devii session and conversation persist and reconnect automatically."
),
handler="client",
requires_auth=False,
params=(arg("url", "Path or URL to navigate to.", required=True),),
),
Action(
name="reload_page",
method="LOCAL",
path="",
summary="Refresh the user's current page, e.g. after something changed",
description=CLIENT
+ " The Devii session and conversation persist and reconnect automatically.",
handler="client",
requires_auth=False,
),
Action(
name="discover_elements",
method="LOCAL",
path="",
summary="List the actionable elements on the user's screen in reading order, each with a stable ref, role, label, selector, and state",
description=(
CLIENT
+ " This is how you SEE the page before acting: it returns buttons, links, inputs, "
"textboxes, checkboxes, selects, tabs, and menu items in document (logical) order, each "
"with a `ref` (like e3) you can pass to click_element/fill_field/etc, plus its role, "
"accessible label, a robust CSS selector, current state (visible, enabled, checked, value), "
"and which form or modal it belongs to. Call this first, then act on the refs. Use `query` "
"to filter by label, `within` to scope to a region (a ref/selector, e.g. an open modal), and "
"`kind` to keep only one type."
),
handler="client",
requires_auth=False,
read_only=True,
params=(
arg("query", "Only return elements whose label contains this text (case-insensitive)."),
arg(
"within",
"Scope discovery to inside this element (a ref, CSS selector, or exact text), e.g. an open modal or form.",
),
arg(
"kind",
"Keep only one type: button, link, input, textbox, checkbox, radio, select, tab, or menuitem.",
),
arg("limit", "Maximum number of elements to return (default 40).", kind="integer"),
),
),
Action(
name="read_element",
method="LOCAL",
path="",
summary="Read one element in detail: text, value, attributes, state, position, and visibility",
description=CLIENT
+ " Use this to investigate a specific element you found with discover_elements, "
"or to confirm the result of an action (its value, whether it is checked, any error text near it).",
handler="client",
requires_auth=False,
read_only=True,
params=(
arg(
"target",
"The element to read: a ref (e3), a CSS selector, or its exact visible text.",
required=True,
),
),
),
Action(
name="click_element",
method="LOCAL",
path="",
summary="Click an element on the user's screen and report what changed",
description=(
CLIENT
+ " Scrolls the element into view, waits briefly for it to be visible and enabled, "
"dispatches a real click, and returns a delta (did the URL change, did a modal open or close, "
"any new toast or validation error, is the element still there). Prefer this over run_js for clicking. "
"Set `button` to 'right' for a context menu or 'double' for a double-click."
),
handler="client",
requires_auth=False,
params=(
arg(
"target",
"The element to click: a ref (e3), a CSS selector, or its exact visible text.",
required=True,
),
arg("button", "left (default), right, or double."),
),
),
Action(
name="fill_field",
method="LOCAL",
path="",
summary="Type a value into an input, textarea, contenteditable, or code editor and fire the right events",
description=(
CLIENT
+ " Sets the value through the native setter and dispatches input and change events, so "
"framework and validation handlers actually run (plain run_js value assignment does not). "
"Supports text inputs, textareas, contenteditable elements, and CodeMirror editors. "
"Returns the resulting value and any validation message shown near the field."
),
handler="client",
requires_auth=False,
params=(
arg(
"target",
"The field to fill: a ref (e3), a CSS selector, or its label/placeholder text.",
required=True,
),
arg("value", "The value to type into the field.", required=True),
),
),
Action(
name="set_control",
method="LOCAL",
path="",
summary="Toggle a checkbox or radio, or choose an option in a select",
description=CLIENT
+ " For a checkbox or radio pass `checked` true/false; for a select pass `option` "
"(matched against option value or visible label). Dispatches a change event.",
handler="client",
requires_auth=False,
params=(
arg(
"target",
"The control: a ref (e3), a CSS selector, or its label text.",
required=True,
),
arg("checked", "For a checkbox or radio: true to check, false to uncheck.", kind="boolean"),
arg("option", "For a select: the option value or visible label to choose."),
),
),
Action(
name="submit_form",
method="LOCAL",
path="",
summary="Optionally fill a form's fields, then submit it, and report what changed",
description=(
CLIENT
+ " Resolves the form that contains `target` (a ref/selector/text for the form, a field in it, "
"or its submit button). If `fields` is given (a map of field name/label to value) each is filled "
"first with the proper events, then the form is submitted by clicking its submit button (so app "
"handlers run) or calling requestSubmit. Returns a delta (URL change, modal open/close, toast, errors). "
"This is the primary tool for completing a mutation such as creating a post or saving a profile."
),
handler="client",
requires_auth=False,
params=(
arg(
"target",
"The form, one of its fields, or its submit button: a ref (e3), CSS selector, or exact text.",
required=True,
),
arg(
"fields",
"Optional map of field name or label to the value to fill before submitting.",
kind="object",
),
),
),
Action(
name="wait_for",
method="LOCAL",
path="",
summary="Wait until an element becomes visible, hidden, or contains text, before continuing",
description=(
CLIENT
+ " Polls the page until the condition holds or it times out, so sequences after a navigation, "
"click, or fetch do not race. `condition` is visible (default), hidden, or text_contains "
"(supply `text`). Returns whether it was satisfied and how long it waited."
),
handler="client",
requires_auth=False,
read_only=True,
params=(
arg(
"target",
"The element to wait on: a ref (e3), a CSS selector, or exact visible text.",
required=True,
),
arg("condition", "visible (default), hidden, or text_contains."),
arg("text", "For text_contains: the text the element should contain."),
arg("timeout_ms", "Maximum wait in milliseconds (default 8000, capped at 55000).", kind="integer"),
),
),
Action(
name="press_key",
method="LOCAL",
path="",
summary="Send a keypress to an element or the page (Enter, Escape, Tab, arrows, etc.)",
description=CLIENT
+ " Dispatches keydown/keypress/keyup for the named key to `target` (or the focused element "
"if omitted). Use Enter to submit, Escape to close a modal, Tab to move focus.",
handler="client",
requires_auth=False,
params=(
arg("key", "The key name: Enter, Escape, Tab, ArrowDown, a, etc.", required=True),
arg("target", "Optional element to send the key to: a ref (e3), selector, or exact text."),
),
),
Action(
name="run_sequence",
method="LOCAL",
path="",
summary="Run an ordered list of client steps in one round-trip, stopping on the first failure",
description=(
CLIENT
+ " Each step is an object with an `action` (click_element, fill_field, set_control, submit_form, "
"wait_for, press_key, scroll_to_element, read_element, discover_elements, highlight_element, show_toast) "
"and its arguments. Steps run in order with the page settling between them; execution stops at the first "
"error and returns every step's result plus the final page context. Use this to perform a whole UI flow "
"(open a modal, fill it, submit) reliably without a round-trip per step. run_js is not allowed inside a sequence."
),
handler="client",
requires_auth=False,
params=(
arg(
"steps",
"Ordered list of step objects, each with an `action` field and that action's arguments.",
required=True,
kind="array",
),
),
),
Action(
name="open_terminal",
method="LOCAL",
path="",
summary="Open a floating interactive terminal window attached to a running container instance",
description=(
CLIENT
+ " Opens a new xterm.js window in the user's browser connected to the container's "
"interactive shell (admin only). Resolve the instance first with container_list_instances, "
"then pass the project slug and the instance slug or uid."
),
handler="client",
requires_admin=True,
params=(
arg(
"project_slug",
"Project slug or uid that owns the container.",
required=True,
),
arg("instance", "Container instance slug or uid.", required=True),
arg("label", "Optional window title (defaults to the instance name)."),
),
),
)
Reference in New Issue View Git Blame Copy Permalink