| """Persistent element annotations in the Hermes desktop GUI's in-app browser. |
| |
| Unlike ``drive_preview``'s self-retiring marks, an annotation outlines an element |
| (or, with ``hold``, the whole visible field) until removed. Annotations bind to |
| elements, not coordinates: they ride scrolls and vanish with their element, so |
| navigation clears them. Same ``preview.act`` bridge as ``drive_preview`` (the |
| renderer resolves refs and owns the overlay). ``desktop_ui`` toolset only. |
| """ |
|
|
| import json |
| from typing import Callable, Optional |
|
|
| from tools.registry import registry, tool_error |
|
|
| ACTIONS = ("add", "hold", "remove", "clear") |
|
|
| |
| WIRE = {"add": "pin", "hold": "hold", "remove": "unpin", "clear": "unpin"} |
|
|
|
|
| def annotate_preview_tool( |
| action: str = "add", ref: Optional[str] = None, selector: Optional[str] = None, |
| label: Optional[str] = None, callback: Optional[Callable] = None, |
| ) -> str: |
| """Put one annotation up, take one down, or clear them all.""" |
| if callback is None: |
| return tool_error("annotate_preview is only available in the Hermes desktop app.") |
| verb = (action or "add").strip().lower() |
| if verb not in ACTIONS: |
| return tool_error(f"action must be one of: {', '.join(ACTIONS)}.") |
| if verb in ("add", "remove") and not (ref or selector): |
| return tool_error(f"{verb} needs a ref from drive_preview action='elements' (e.g. 'btn-sign-in') or a CSS selector.") |
|
|
| targeted = verb not in ("clear", "hold") |
| fields = (("action", WIRE[verb]), ("ref", ref if targeted else None), ("selector", selector if targeted else None), ("text", label)) |
| payload = {name: val for name, val in fields if val is not None} |
| try: |
| raw = callback(payload) |
| except Exception as exc: |
| return tool_error(f"Failed to annotate the in-app browser: {exc}") |
| if not raw: |
| return tool_error("The annotation timed out, or no GUI window answered. Open a page with open_preview first.") |
| try: |
| return json.dumps(json.loads(raw), ensure_ascii=False) |
| except (TypeError, ValueError): |
| return json.dumps({"text": str(raw)}, ensure_ascii=False) |
|
|
|
|
| ANNOTATE_PREVIEW_SCHEMA = { |
| "name": "annotate_preview", |
| "description": ( |
| "Highlight elements on the preview-pane page, lastingly (drive_preview's own " |
| "marks fade; annotations stay until removed) — point at findings, " |
| "flag what you're about to change, keep your place. Use the refs " |
| "from drive_preview action='elements'. add: outline one element " |
| "(optional short label — a word or two, drawn on the page). hold: " |
| "freeze the whole visible field, every element outlined and named. " |
| "remove/clear: take one/all down. Marks follow their element on " |
| "scroll; navigation clears them." |
| ), |
| "parameters": { |
| "type": "object", |
| "properties": { |
| "action": { |
| "type": "string", |
| "enum": list(ACTIONS), |
| "description": "Defaults to 'add'.", |
| }, |
| "ref": { |
| "type": "string", |
| "description": "Ref from drive_preview elements.", |
| }, |
| "selector": { |
| "type": "string", |
| "description": "CSS selector fallback. Prefer ref.", |
| }, |
| "label": { |
| "type": "string", |
| "description": "Optional caption, e.g. 'cheapest'.", |
| }, |
| }, |
| "required": [], |
| }, |
| } |
|
|
|
|
| registry.register( |
| name="annotate_preview", |
| toolset="desktop_ui", |
| schema=ANNOTATE_PREVIEW_SCHEMA, |
| handler=lambda args, **kw: annotate_preview_tool( |
| action=args.get("action", "add"), |
| ref=args.get("ref"), |
| selector=args.get("selector"), |
| label=args.get("label"), |
| callback=kw.get("callback"), |
| ), |
| emoji="🔖", |
| ) |
|
|
