devplacepy/client_actions.py at e6986639752773d4bae5878baedeb1b6551252f0

 # 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="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)."),
         ),
     ),
 )