sjcdZddlZddlmZmZddlmZmZdZdZ dZ d2d e d ee d ee d ee d ee dee dee dee deede fdZddddddddddde e ddddZdddde ed dde e d!ddd"ddd#ddd$dde e d%dd&ed'd(d)d*dd+d gd,d-Zejdd.ed/d01dS)3uRun a guided tour (highlight + narrate UI elements) in the Hermes desktop GUI. One generic tool, no baked-in tour definitions: the agent discovers what is on screen (``action="targets"``), then highlights any element by CSS selector with its own title/text — either one step at a time (``show``, agent-paced) or as a full step list the user pages through with Next/Prev (``start``). Two surfaces share the same engine (driver.js in the renderer): - ``surface="app"`` — the Hermes desktop app's own DOM (tours of Hermes itself). - ``surface="preview"`` — the page loaded in the in-app browser/preview pane (tours of ANY web app, e.g. a project open via open_preview). Round-trips through the gateway's blocking-prompt bridge like ``read_preview``: tui_gateway emits ``tour.request``, the renderer drives driver.js (injecting it into the preview's webview when needed) and answers ``tour.respond`` with the outcome, so the agent knows whether the selector matched. This module is just schema + a thin dispatcher over the platform-injected callback. Lives in the ``desktop_ui`` toolset, which the GUI gateway enables only for desktop-sourced sessions. N)CallableOptional)registry tool_error)targetsshowstartnextprevstop)apppreview)toprightbottomleftactionsurfaceselectortitletextsidesteps step_indexcallbackreturnc "|tdS|pd} | tvr+tddtdS|pd} | t vr+tddt dS|4|t vr+td dt dSd td tfd } | d kr| |||drtdS| dkrt|tr|stdSt|D]O\} } t| tstd| dcS| | rtd| dcSPdd| fd| fd|fd|fd|fd|fd|fd|ffD} ||}n)#t$r}td|cYd}~Sd}~wwxYw|stdS tjtj|d !S#t t"f$r(tjdt%|id !cYSwxYw)"zHDispatch one tour action to the desktop renderer and return its outcome.Nz1tour is only available in the Hermes desktop app.rzaction must be one of: z, .r zsurface must be one of: zside must be one of: steprc|dp)|dp|d S)Nrrr)get)r s 3/home/agent/.hermes/hermes-agent/tools/tour_tool.py_emptyztour_tool.._empty>s9HHZ((QDHHW,=,=Q&AQAQRRr)rrrz:show needs a selector (and/or title/text for the popover).r z$start needs a non-empty steps array.zsteps[z] must be an object.z%] needs a selector and/or title/text.ci|] \}}||| S)N).0keyvals r# ztour_tool..Ms/    C ? S ??r%rrrrrrrrzTour action failed: zsThe tour request timed out, or no GUI window answered. For surface='preview' open a page in the preview pane first.F) ensure_ascii)rstriplowerACTIONSjoinSURFACESSIDESdictbool isinstancelist enumerate Exceptionjsondumpsloads TypeError ValueErrorstr)rrrrrrrrrverbwherer$ir payloadrawexcs r# tour_toolrE#sSMNNN Lb   ! ! ' ' ) )D 7IDIIg4F4FIIIJJJ   $ $ & & , , . .E HKTYYx5H5HKKKLLL D--E$))E2B2BEEEFFFSTSdSSSS v~~&&hPT!U!UVV~VWWW w%&& Fe FDEE E '' U UGAtdD)) D!"B1"B"B"BCCCCCvd|| U!"S1"S"S"STTTTT U  t     " e  TN TN e  : &     G8hw 888666777777778   K   Bz$*S//>>>> z "BBBz63s88,5AAAAAABs0& G22 H<H HH-'I6J JobjectstringzZCSS selector of the element this step highlights. Omit for a centered narration-only step.)type descriptionzPopover title.zPopover body text.z+Preferred popover side. Omit to auto-place.)rHenumrI)rrrr)rH propertiestouruGive a live guided tour in the Hermes desktop GUI: dim the screen, highlight an element, and attach a popover with your own title/text. Works on two surfaces — 'app' (the Hermes app itself) and 'preview' (whatever page is open in the in-app browser, so any web app can be toured). ALWAYS call action='targets' first to discover what is on screen instead of guessing selectors; each target reports `stable: true` when its selector keys off identity (data-tour, id, data-testid, aria-label) and survives a re-render — prefer those, and re-scan if a selector stops matching. Then either narrate at your own pace with action='show' (one highlight per call — replaces the previous one; pair each with a chat message describing it), or hand control to the user with action='start' + a steps array (driver.js renders Next/Prev buttons; 'next'/'prev' also page it programmatically). action='stop' clears the tour. Use when the user asks how something works, where something is, or for a walkthrough of an app or workflow.ztargets: list tourable elements. show: highlight one element. start: begin a multi-step user-paced tour. next/prev: page a started tour. stop: end the tour.zkWhere the tour runs: 'app' (Hermes desktop UI, default) or 'preview' (the page in the in-app browser pane).zFor show: CSS selector of the element to highlight (from action='targets', preferring a stable one). Omit for a centered narration popover.zFor show: popover title.zFor show: popover body text.z5For show: preferred popover side. Omit to auto-place.arrayz"For start: the ordered tour steps.)rHitemsrIintegerz2For start: 0-indexed step to begin at (default 0).)rrrrrrrr)rHrKrequired)namerI parameters desktop_uic t|dd|d|d|d|d|d|d|d |d  S) Nrrrrrrrrrr) rrrrrrrrr)rEr")argskws r#rWsyxx"%%##*%%hhw XXf   XXf  hhw88L)) ##   r%u🧭)rQtoolsetschemahandleremoji) rNNNNNNNN)__doc__r9typingrrtools.registryrrr/r1r2r>r6intrE _STEP_SCHEMA TOUR_SCHEMAregisterr'r%r#rcs. %%%%%%%%//////// > *!" $#'HBHB HB c]HBsmHB C= HB 3- HB 3- HB D>HB HBx HB HBHBHBHBX w  #3CDD!2FGGDKKH     $  $!W  ~ !X M ! m'7QRR%6TUU U V  %C "S7  @JE##)88 v      r%