tip_tool.py 3.1 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980
  1. """Point at something in the Hermes desktop GUI and say one line about it — the quiet
  2. sibling of ``tour`` (same ``data-tour`` handles) with no scrim/spotlight/paging.
  3. Fire-and-forget: a tip is not a question, so blocking on a round-trip would stall the
  4. reply. Lives in ``desktop_ui`` and withdraws itself when the user turns tips off."""
  5. import json
  6. from tools import desktop_ui
  7. from tools.registry import registry, tool_error
  8. SIDES = ("top", "right", "bottom", "left")
  9. def tip_tool(text: str, selector: str, title: str = "", side: str = "") -> str:
  10. """Show one tip bubble anchored to ``selector``."""
  11. text = (text or "").strip()
  12. selector = (selector or "").strip()
  13. if not text:
  14. return tool_error("tip needs text — the one line the bubble says.")
  15. if not selector:
  16. return tool_error("tip needs a selector to point at. Call tour(action='targets') to see "
  17. "what's on screen and prefer a target reporting stable: true.")
  18. if side and side not in SIDES:
  19. return tool_error(f"side must be one of: {', '.join(SIDES)}.")
  20. payload = {"selector": selector, "text": text,
  21. **{k: v for k, v in (("title", title), ("side", side)) if v}}
  22. try:
  23. ok = desktop_ui.emit("tip.show", payload)
  24. except Exception as exc:
  25. return tool_error(f"Failed to show the tip: {exc}")
  26. if not ok:
  27. return tool_error("tip is only available in the Hermes desktop app.")
  28. return json.dumps({"success": True, "selector": selector}, ensure_ascii=False)
  29. TIP_SCHEMA = {
  30. "name": "show_tip",
  31. "description": (
  32. "Point at one desktop UI element with a small arrow bubble (no dimming or tour). "
  33. "For when a sentence is clearer with a finger on its subject. Get selectors from tour(action='targets'), "
  34. "prefer stable:true, never guess. One tip at a time (new replaces "
  35. "last); say the same thing in chat too — the bubble is a pointer, "
  36. "not the message. Sparingly: a bubble every turn stops being read."
  37. ),
  38. "parameters": {
  39. "type": "object",
  40. "properties": {
  41. "text": {
  42. "type": "string",
  43. "description": "The one-sentence bubble text.",
  44. },
  45. "selector": {
  46. "type": "string",
  47. "description": "Selector from tour targets.",
  48. },
  49. "title": {
  50. "type": "string",
  51. "description": "Optional heading.",
  52. },
  53. "side": {
  54. "type": "string",
  55. "enum": list(SIDES),
  56. "description": "Omit for 'top'; flips at screen edges.",
  57. },
  58. },
  59. "required": ["text", "selector"],
  60. },
  61. }
  62. def check_tips_enabled() -> bool:
  63. """The user's Settings → Appearance switch. On unless they turned it off."""
  64. return desktop_ui.user_enabled("in_app_tips", default=True)
  65. registry.register(
  66. name="show_tip", toolset="desktop_ui", schema=TIP_SCHEMA, check_fn=check_tips_enabled,
  67. handler=lambda args, **kw: tip_tool(
  68. **{k: args.get(k, "") for k in ("text", "selector", "title", "side")}),
  69. emoji="💡")