| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980 |
- """Point at something in the Hermes desktop GUI and say one line about it — the quiet
- sibling of ``tour`` (same ``data-tour`` handles) with no scrim/spotlight/paging.
- Fire-and-forget: a tip is not a question, so blocking on a round-trip would stall the
- reply. Lives in ``desktop_ui`` and withdraws itself when the user turns tips off."""
- import json
- from tools import desktop_ui
- from tools.registry import registry, tool_error
- SIDES = ("top", "right", "bottom", "left")
- def tip_tool(text: str, selector: str, title: str = "", side: str = "") -> str:
- """Show one tip bubble anchored to ``selector``."""
- text = (text or "").strip()
- selector = (selector or "").strip()
- if not text:
- return tool_error("tip needs text — the one line the bubble says.")
- if not selector:
- return tool_error("tip needs a selector to point at. Call tour(action='targets') to see "
- "what's on screen and prefer a target reporting stable: true.")
- if side and side not in SIDES:
- return tool_error(f"side must be one of: {', '.join(SIDES)}.")
- payload = {"selector": selector, "text": text,
- **{k: v for k, v in (("title", title), ("side", side)) if v}}
- try:
- ok = desktop_ui.emit("tip.show", payload)
- except Exception as exc:
- return tool_error(f"Failed to show the tip: {exc}")
- if not ok:
- return tool_error("tip is only available in the Hermes desktop app.")
- return json.dumps({"success": True, "selector": selector}, ensure_ascii=False)
- TIP_SCHEMA = {
- "name": "show_tip",
- "description": (
- "Point at one desktop UI element with a small arrow bubble (no dimming or tour). "
- "For when a sentence is clearer with a finger on its subject. Get selectors from tour(action='targets'), "
- "prefer stable:true, never guess. One tip at a time (new replaces "
- "last); say the same thing in chat too — the bubble is a pointer, "
- "not the message. Sparingly: a bubble every turn stops being read."
- ),
- "parameters": {
- "type": "object",
- "properties": {
- "text": {
- "type": "string",
- "description": "The one-sentence bubble text.",
- },
- "selector": {
- "type": "string",
- "description": "Selector from tour targets.",
- },
- "title": {
- "type": "string",
- "description": "Optional heading.",
- },
- "side": {
- "type": "string",
- "enum": list(SIDES),
- "description": "Omit for 'top'; flips at screen edges.",
- },
- },
- "required": ["text", "selector"],
- },
- }
- def check_tips_enabled() -> bool:
- """The user's Settings → Appearance switch. On unless they turned it off."""
- return desktop_ui.user_enabled("in_app_tips", default=True)
- registry.register(
- name="show_tip", toolset="desktop_ui", schema=TIP_SCHEMA, check_fn=check_tips_enabled,
- handler=lambda args, **kw: tip_tool(
- **{k: args.get(k, "") for k in ("text", "selector", "title", "side")}),
- emoji="💡")
|