computer_use.py 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205
  1. """``hermes computer-use`` subcommand parser."""
  2. from __future__ import annotations
  3. import sys
  4. from hermes_cli.subcommands._shared import add_json_flag
  5. def _exit_if_plugin_backend(*, doctor: bool = False) -> None:
  6. """cua-driver checks do not apply when ``computer_use.backend`` selects another backend: report it
  7. (running its own ``doctor()`` when asked and it ships one) and exit; return for the built-in."""
  8. from plugins.computer_use import DEFAULT_BACKEND, configured_backend_name, get_active_provider
  9. if configured_backend_name() == DEFAULT_BACKEND:
  10. return
  11. try:
  12. provider = get_active_provider()
  13. except LookupError as e:
  14. print(f"Computer Use: {e}")
  15. sys.exit(2)
  16. if doctor and (rc := provider.doctor()) is not None:
  17. sys.exit(rc)
  18. ok = provider.is_available()
  19. print(f"Computer Use backend: {provider.name} ({provider.display_name}) — "
  20. f"{'available' if ok else 'not available'}. cua-driver checks do not apply to this backend.")
  21. sys.exit(0 if ok else 1)
  22. def _cu_install(args) -> int:
  23. from hermes_cli.tools_config_cua import install_cua_driver
  24. return 0 if install_cua_driver(upgrade=bool(getattr(args, "upgrade", False))) else 1
  25. def _cu_status(args) -> int:
  26. _exit_if_plugin_backend()
  27. import os as _os
  28. from hermes_cli.tools_config_cua import _cua_driver_contract_status, _cua_version_summary
  29. from tools.computer_use.cua_backend_driver import resolve_cua_driver_cmd
  30. path = resolve_cua_driver_cmd()
  31. override = _os.environ.get("HERMES_CUA_DRIVER_CMD", "").strip()
  32. if not path:
  33. print("cua-driver: not installed")
  34. print(" Run: hermes computer-use install")
  35. return 1
  36. contract = _cua_driver_contract_status(path)
  37. version = _cua_version_summary(contract.get("version") or "")
  38. # Name the override here too. Without it the operator is told to repair an
  39. # install that `hermes computer-use install` will (correctly) refuse to touch,
  40. # with nothing pointing at the env var that actually selected the binary.
  41. origin = " [custom binary from HERMES_CUA_DRIVER_CMD]" if override else ""
  42. print(f"cua-driver: installed at {path}{origin}" + (f" ({version})" if version else ""))
  43. if not contract.get("ready"):
  44. print(" ⚠ Repair required: " + (contract.get("reason") or "runtime contract is incomplete"))
  45. if override:
  46. print(
  47. " Update the binary selected by HERMES_CUA_DRIVER_CMD, or unset "
  48. "the override and run: hermes computer-use install --upgrade")
  49. else:
  50. print(" Run: hermes computer-use install")
  51. return 1
  52. rc = 0
  53. if sys.platform == "linux": # hand-written daemon units: dead `serve` is invisible to the binary contract (#114748)
  54. from tools.computer_use.cua_backend import cua_daemon_listening
  55. from tools.computer_use.doctor import cua_daemon_units
  56. for _kind, unit, _target, serve, socket in cua_daemon_units():
  57. if serve and cua_daemon_listening(path, socket) is False:
  58. print(f" ✗ Daemon unit {unit}: no `cua-driver serve` is listening on {socket or 'the default socket'}")
  59. print(f" Check: systemctl --user status {unit} (reinstalling the driver does not start it)")
  60. rc = 1
  61. print(" ✓ Runtime contract ready (externally managed)." if override
  62. else " ✓ Runtime contract ready (Hermes PM pin).")
  63. return rc
  64. def _cu_doctor(args) -> None:
  65. _exit_if_plugin_backend(doctor=True)
  66. from tools.computer_use.doctor import run_doctor
  67. sys.exit(run_doctor(
  68. include=list(getattr(args, "include", []) or []),
  69. skip=list(getattr(args, "skip", []) or []),
  70. json_output=bool(getattr(args, "json", False))))
  71. def _cu_perms_status(args) -> None:
  72. if not getattr(args, "json", False): # --json: computer_use_status() reports the selected backend itself
  73. _exit_if_plugin_backend()
  74. import json as _json
  75. from tools.computer_use.permissions import TCC_FIELDS, computer_use_status, stale_tcc_grant_hint
  76. st = computer_use_status()
  77. if bool(getattr(args, "json", False)):
  78. print(_json.dumps(st, indent=2, sort_keys=True))
  79. sys.exit(0 if st["ready"] else 1)
  80. if not st["platform_supported"]:
  81. print(f"Computer Use is not supported on {st['platform']}.")
  82. sys.exit(1)
  83. if not st["installed"]:
  84. print("cua-driver: not installed. Run: hermes computer-use install")
  85. sys.exit(1)
  86. glyph = lambda v: "✅" if v is True else ("❌" if v is False else "•")
  87. print(f"cua-driver: {st['version'] or 'installed'} ({st['platform']})")
  88. if st["can_grant"]: # macOS TCC permissions
  89. print(f" {glyph(st['accessibility'])} Accessibility")
  90. print(f" {glyph(st['screen_recording'])} Screen Recording")
  91. if not st["ready"]:
  92. print(" Grant: hermes computer-use permissions grant")
  93. if hint := stale_tcc_grant_hint(*(f for f in TCC_FIELDS if st[f] is False)):
  94. print(f" {hint}")
  95. else: # no TCC model — readiness is driver health
  96. print(f" {glyph(st['ready'])} driver health (no permission toggles on {st['platform']})")
  97. for c in st["checks"]:
  98. if c["status"] != "ok":
  99. print(f" ⚠ {c['label']}: {c['message']}")
  100. if st["error"]:
  101. print(f" ⚠ {st['error']}")
  102. sys.exit(0 if st["ready"] else 1)
  103. def _cu_perms_grant(args) -> None:
  104. _exit_if_plugin_backend()
  105. from tools.computer_use.permissions import request_permissions_grant
  106. sys.exit(request_permissions_grant())
  107. def build_computer_use_parser(subparsers) -> None:
  108. """Attach the ``computer-use`` subcommand to ``subparsers``."""
  109. computer_use_parser = subparsers.add_parser(
  110. "computer-use", help="Manage the Computer Use (cua-driver) backend (macOS/Windows/Linux)",
  111. description="Install or check the cua-driver binary used by the\n"
  112. "`computer_use` toolset. Supported on macOS, Windows, and\n"
  113. "Linux.\n\n"
  114. "Use `hermes computer-use install` to prepare the pinned\n"
  115. "cua-driver package and host integration. This is equivalent to the\n"
  116. "post-setup hook that `hermes tools` runs when you first\n"
  117. "enable the Computer Use toolset, and is a stable target\n"
  118. "for re-running the install if it didn't fire (e.g. when\n"
  119. "toggling the toolset on a returning-user setup).\n\n"
  120. "Use `hermes computer-use doctor` to run cua-driver's\n"
  121. "`health_report` MCP tool and surface its check matrix\n"
  122. "(TCC, bundle identity, version, platform support, ...)\n"
  123. "in human-readable form.")
  124. computer_use_sub = computer_use_parser.add_subparsers(dest="computer_use_action")
  125. computer_use_install = computer_use_sub.add_parser(
  126. "install", help="Install or repair the cua-driver binary (macOS/Windows/Linux)")
  127. computer_use_install.add_argument(
  128. "--upgrade", action="store_true",
  129. help="Reconcile cua-driver with Hermes' pinned PM package and repair host setup.")
  130. computer_use_sub.add_parser("status", help="Check the selected cua-driver and its runtime contract")
  131. computer_use_doctor = computer_use_sub.add_parser(
  132. "doctor", help="Run cua-driver `health_report` and surface the check matrix",
  133. description="Drive cua-driver's stable `health_report` MCP tool and render\n"
  134. "its check matrix (TCC permissions, bundle identity, version,\n"
  135. "platform support, screenshot probe, …) as human-readable\n"
  136. "output. cua-driver owns the health model; this command stays\n"
  137. "thin so new checks added upstream surface here without code\n"
  138. "changes. Exits 0 when overall=ok, 1 when degraded/failed, 2\n"
  139. "when the binary is missing or unreachable.")
  140. computer_use_doctor.add_argument(
  141. "--include", action="append", default=[], metavar="CHECK",
  142. help="Run only the listed checks. Repeat for multiple "
  143. "(e.g. --include tcc_accessibility --include bundle_identity). "
  144. "Unknown names are reported by cua-driver.")
  145. computer_use_doctor.add_argument(
  146. "--skip", action="append", default=[], metavar="CHECK",
  147. help="Skip the listed checks. Repeat for multiple. Wins over --include.")
  148. add_json_flag(computer_use_doctor,
  149. "Emit the raw structured payload as JSON (same shape as `tools/call`).")
  150. computer_use_perms = computer_use_sub.add_parser(
  151. "permissions", help="Check or grant macOS Accessibility + Screen Recording (macOS)",
  152. description="Computer Use drives the Mac through cua-driver, whose TCC grants\n"
  153. "attach to cua-driver's own identity (com.trycua.driver) — not the\n"
  154. "terminal or the Hermes app. `status` reports the driver's grant\n"
  155. "state; `grant` launches CuaDriver via LaunchServices so the macOS\n"
  156. "permission dialog is attributed to the process that does the work.")
  157. computer_use_perms_sub = computer_use_perms.add_subparsers(dest="computer_use_perms_action")
  158. computer_use_perms_status = computer_use_perms_sub.add_parser(
  159. "status", help="Report Accessibility + Screen Recording grant state (read-only)")
  160. add_json_flag(computer_use_perms_status, "Emit the normalized permission payload as JSON.")
  161. computer_use_perms_sub.add_parser(
  162. "grant", help="Request the grants (opens the dialog attributed to CuaDriver)")
  163. _perms_actions = {"grant": _cu_perms_grant, "status": _cu_perms_status}
  164. from hermes_cli.subcommands.computer_use_screen import build_screen_parser
  165. build_screen_parser(computer_use_sub, add_json_flag)
  166. def _cu_screen(args):
  167. return args.screen_func(args)
  168. def _cu_permissions(args):
  169. handler = _perms_actions.get(getattr(args, "computer_use_perms_action", None))
  170. if handler is not None:
  171. return handler(args)
  172. computer_use_perms.print_help()
  173. _actions = {"install": _cu_install, "status": _cu_status, "doctor": _cu_doctor,
  174. "permissions": _cu_permissions, "screen": _cu_screen}
  175. def cmd_computer_use(args):
  176. handler = _actions.get(getattr(args, "computer_use_action", None))
  177. if handler is not None:
  178. return handler(args)
  179. computer_use_parser.print_help() # no subcommand → help
  180. computer_use_parser.set_defaults(func=cmd_computer_use)