tools.py 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178
  1. """Agent-facing tools for the google_meet plugin.
  2. meet_join — join a Meet URL (locally, or on a remote node via node=<name>)
  3. meet_status — bot liveness + transcript progress
  4. meet_transcript — read the transcript (optional last-N)
  5. meet_leave — signal the bot to leave cleanly
  6. meet_say — speak text through the realtime bridge (mode='realtime' only)
  7. """
  8. from __future__ import annotations
  9. import json
  10. from typing import Any, Dict, Optional
  11. from plugins.google_meet import process_manager as pm
  12. def check_meet_requirements() -> bool:
  13. """True when the plugin can run LOCALLY: Linux/macOS + importable ``playwright``.
  14. Remote-node operation only needs ``websockets``; handlers relax this gate when a node is addressed."""
  15. import importlib.util
  16. import platform as _p
  17. return (_p.system().lower() in {"linux", "darwin"}
  18. and importlib.util.find_spec("playwright") is not None)
  19. def resolve_node(node: str):
  20. """``(NodeClient, node_name)`` for *node* (``'auto'`` = the sole registered node), or ``(None, None)``."""
  21. from plugins.google_meet.node.registry import NodeRegistry
  22. from plugins.google_meet.node.client import NodeClient
  23. entry = NodeRegistry().resolve(node if node != "auto" else None)
  24. if entry is None:
  25. return None, None
  26. return NodeClient(url=entry["url"], token=entry["token"]), entry.get("name")
  27. _NODE_PROP = {"type": "string"}
  28. def _str(description: str) -> dict[str, Any]:
  29. return {"type": "string", "description": description}
  30. def _schema(name: str, description: str, properties: dict[str, Any], required=None) -> dict[str, Any]:
  31. params: dict[str, Any] = {"type": "object", "properties": properties}
  32. if required:
  33. params["required"] = required
  34. params["additionalProperties"] = False
  35. return {"name": name, "description": description, "parameters": params}
  36. MEET_JOIN_SCHEMA = _schema(
  37. "meet_join",
  38. "Join a Google Meet call and start scraping live captions into a transcript file. Only "
  39. "meet.google.com URLs are accepted; no calendar scanning, no auto-dial. Spawns a headless "
  40. "Chromium subprocess that runs in parallel with the agent loop — returns immediately. Poll "
  41. "with meet_status and read captions with meet_transcript. Reminder to the agent: you "
  42. "should announce yourself in the meeting (there is no automatic consent announcement).",
  43. {"url": _str("Full https://meet.google.com/... URL. Required."),
  44. "mode": {"type": "string", "enum": ["transcribe", "realtime"],
  45. "description": ("transcribe (default): listen-only, scrape captions. "
  46. "realtime: also enable agent speech via meet_say "
  47. "(requires OpenAI Realtime key + platform audio bridge).")},
  48. "guest_name": _str("Display name to use when joining as guest. Defaults to 'Hermes Agent'."),
  49. "duration": _str("Optional max duration before auto-leave (e.g. '30m', "
  50. "'2h', '90s'). Omit to stay until meet_leave is called."),
  51. "headed": {"type": "boolean",
  52. "description": "Run Chromium headed instead of headless (debug only). Default false."},
  53. "node": _str("Name of a registered remote node to run the bot on (useful when the gateway "
  54. "runs on a headless Linux box but the user's Chrome with a signed-in Google "
  55. "profile lives on their Mac). Pass 'auto' to use the single registered node. "
  56. "Default: run locally. Nodes are approved via `hermes meet node approve`.")},
  57. required=["url"])
  58. MEET_STATUS_SCHEMA = _schema(
  59. "meet_status",
  60. "Report the current Meet session state — whether the bot is alive, has joined, is sitting "
  61. "in the lobby, number of transcript lines captured, and last-caption timestamp.",
  62. {"node": _NODE_PROP})
  63. MEET_TRANSCRIPT_SCHEMA = _schema(
  64. "meet_transcript",
  65. "Read the scraped transcript for the active Meet session. Returns "
  66. "full transcript unless 'last' is set, in which case returns the last N lines only.",
  67. {"last": {"type": "integer",
  68. "description": ("Optional: return only the last N caption lines. Useful "
  69. "for polling during a meeting without re-reading the whole transcript."),
  70. "minimum": 1},
  71. "node": _NODE_PROP})
  72. MEET_LEAVE_SCHEMA = _schema(
  73. "meet_leave",
  74. "Leave the active Meet call cleanly, stop caption scraping, and finalize the transcript "
  75. "file. Safe to call when no meeting is active — returns ok=false with a reason.",
  76. {"node": _NODE_PROP})
  77. MEET_SAY_SCHEMA = _schema(
  78. "meet_say",
  79. "Speak text into the active Meet call. Requires the active meeting to have been joined "
  80. "with mode='realtime'. The text is queued to the bot's OpenAI Realtime session; the "
  81. "generated audio is streamed into Chrome's fake microphone via a virtual audio device "
  82. "(PulseAudio null-sink on Linux, BlackHole on macOS). Returns immediately — the actual "
  83. "speech lags by a couple of seconds.",
  84. {"text": _str("Text to speak."), "node": _NODE_PROP},
  85. required=["text"])
  86. def _json(obj: Any) -> str:
  87. return json.dumps(obj, ensure_ascii=False)
  88. def _err(msg: str, **extra) -> str:
  89. return _json({"success": False, "error": msg, **extra})
  90. def _dispatch(node: Optional[str], op: str, remote, local) -> str:
  91. """Run *remote(client)* on the addressed node, else *local()*; wrap as a tool result."""
  92. if not node:
  93. res = local()
  94. return _json({"success": bool(res.get("ok")), **res})
  95. client, node_name = resolve_node(node)
  96. if client is None:
  97. return _err(f"no registered meet node matches {node!r} — "
  98. "run `hermes meet node approve <name> <url> <token>` first")
  99. try:
  100. res = remote(client)
  101. except Exception as e:
  102. return _err(f"remote node {op} failed: {e}", node=node_name)
  103. return _json({"success": bool(res.get("ok")), "node": node_name, **res})
  104. def handle_meet_join(args: dict[str, Any], **_kw) -> str:
  105. url = (args.get("url") or "").strip()
  106. if not url:
  107. return _err("url is required")
  108. mode = (args.get("mode") or "transcribe").strip().lower()
  109. if mode not in {"transcribe", "realtime"}:
  110. return _err(f"mode must be 'transcribe' or 'realtime' (got {mode!r})")
  111. common: dict[str, Any] = dict(
  112. url=url, guest_name=str(args.get("guest_name") or "Hermes Agent"),
  113. duration=str(args.get("duration")) if args.get("duration") else None,
  114. headed=bool(args.get("headed", False)), mode=mode)
  115. def _local():
  116. if not check_meet_requirements():
  117. return {"ok": False, "error": (
  118. "google_meet plugin prerequisites missing — install with "
  119. "`hermes meet install`. Plugin is supported on Linux and macOS only.")}
  120. return pm.start(**common)
  121. return _dispatch(args.get("node"), "start_bot", lambda c: c.start_bot(**common), _local)
  122. def handle_meet_status(args: dict[str, Any], **_kw) -> str:
  123. return _dispatch(args.get("node"), "status", lambda c: c.status(), pm.status)
  124. def handle_meet_transcript(args: dict[str, Any], **_kw) -> str:
  125. try:
  126. last = int(args["last"]) if args.get("last") is not None else None
  127. except (TypeError, ValueError):
  128. last = None
  129. if last is not None and last < 1:
  130. last = None
  131. return _dispatch(args.get("node"), "transcript", lambda c: c.transcript(last=last),
  132. lambda: pm.transcript(last=last))
  133. def handle_meet_leave(args: dict[str, Any], **_kw) -> str:
  134. return _dispatch(args.get("node"), "stop", lambda c: c.stop(),
  135. lambda: pm.stop(reason="agent called meet_leave"))
  136. def handle_meet_say(args: dict[str, Any], **_kw) -> str:
  137. text = (args.get("text") or "").strip()
  138. if not text:
  139. return _err("text is required")
  140. return _dispatch(args.get("node"), "say", lambda c: c.say(text), lambda: pm.enqueue_say(text))