feat(plugins): google_meet \u2014 join, transcribe, speak, follow up (#16364)

* feat(plugins): google_meet — bundled plugin for join+transcribe Meet calls

v1 shipping transcribe-only. Spawns headless Chromium via Playwright,
joins an explicit https://meet.google.com/ URL, enables live captions,
and scrapes them into a transcript file the agent can read across turns.
The agent then has the meeting content in context and can do followup
work (send recap, file issues, schedule followups) with its regular tools.

Surface:
  - Tools: meet_join, meet_status, meet_transcript, meet_leave, meet_say
    (meet_say is a v1 stub — returns not-implemented; v2 will wire
    realtime duplex audio via OpenAI Realtime / Gemini Live +
    BlackHole / PulseAudio null-sink.)
  - CLI: hermes meet setup | auth | join | status | transcript | stop
  - Lifecycle: on_session_end auto-leaves any still-running bot.

Safety:
  - URL regex rejects anything that isn't https://meet.google.com/...
  - No calendar scanning, no auto-dial, no auto-consent announcement.
  - Single active meeting per install; a second meet_join leaves the first.
  - Platform-gated to Linux + macOS (Windows audio routing for v2 untested).
  - Opt-in: standalone plugin, user must add 'google_meet' to
    plugins.enabled in config.yaml.

Zero core changes. Plugin uses existing register_tool /
register_cli_command / register_hook surfaces. 21 new unit tests cover the
URL safety gate, transcript dedup + status round-trip, process-manager
refusals/start/stop paths, tool-handler JSON shape under each branch,
session-end cleanup, and platform-gated register().

* feat(plugins/google_meet): v2 realtime audio + v3 remote node host

v2 \u2014 agent speaks in-meeting
  audio_bridge.py: PulseAudio null-sink (Linux) + BlackHole probe (macOS).
    On Linux we load pactl module-null-sink + module-virtual-source, track
    module ids for teardown; Chrome gets PULSE_SOURCE=<virt src> env so its
    fake mic reads what we write to the sink. macOS just probes BlackHole
    2ch and returns its device name \u2014 the plugin refuses to switch the
    user's default audio input (that would surprise them).
  realtime/openai_client.py: sync WebSocket client for the OpenAI Realtime
    API. RealtimeSession.speak(text) sends conversation.item.create +
    response.create, accumulates response.audio.delta PCM bytes, appends
    them to a file. RealtimeSpeaker runs a JSONL-queue loop consuming
    meet_say calls. 'websockets' is an optional dep imported lazily.
  meet_bot.py: when HERMES_MEET_MODE=realtime, provisions AudioBridge,
    starts RealtimeSession + speaker thread, spawns paplay to pump PCM
    into the null-sink, then cleans everything up on SIGTERM. If any
    realtime setup step fails, falls back cleanly to transcribe mode
    with an error flagged in status.json.
  process_manager.enqueue_say(): writes a JSONL line to say_queue.jsonl;
    refuses when no active meeting or active meeting is transcribe-only.
  tools.meet_say: real implementation; requires active mode='realtime'.
  meet_join: adds mode='transcribe'|'realtime' param.

v3 \u2014 remote node host
  node/protocol.py: JSON envelope (type, id, token, payload) + validate.
  node/registry.py: $HERMES_HOME/workspace/meetings/nodes.json, with
    resolve() auto-selecting the sole registered node when name is None.
  node/server.py: NodeServer \u2014 websockets.serve, bearer-token auth,
    dispatches start_bot/stop/status/transcript/say/ping onto the local
    process_manager. Token auto-generated + persisted on first run.
  node/client.py: NodeClient \u2014 short-lived sync WS per RPC, raises
    RuntimeError on error envelopes, clean API matching the server.
  node/cli.py: 'hermes meet node {run,list,approve,remove,status,ping}'
    subtree; wired into the main meet CLI by cli.py so 'hermes meet node'
    Just Works.
  tools.py: every meet_* tool accepts node='<name>'|'auto'; when set,
    routes through NodeClient to the remote bot instead of running
    locally. Unknown node \u2192 clear 'no registered meet node matches ...'
    error.
  cli.py: 'hermes meet join --node my-mac --mode realtime' and
    'hermes meet say "..." --node my-mac' route to the node; 'hermes
    meet node approve <name> <url> <token>' registers one.

Tests
  21 v1 tests updated (meet_say is no longer a stub; active-record now
    carries mode).
  20 new audio_bridge + realtime tests.
  42 new node tests (protocol/registry/server/client/cli).
  17 new v1/v2/v3 integration tests at the plugin level covering
    enqueue_say edge cases, env var passthrough, mode validation, node
    routing (known/unknown/auto/ambiguous), and argparse wiring for
    `hermes meet say` + `hermes meet node` + --mode/--node flags.
  Total: 100 plugin tests + 58 plugin-system tests = 158 passing.

E2E verified on Linux with fresh HERMES_HOME: plugin loads, 5 tools
register, on_session_end hook wires, 'hermes meet' CLI tree wires
including the node subtree, NodeRegistry round-trips, meet_join routes
correctly to NodeClient under node='my-mac' with mode='realtime',
enqueue_say accepts realtime/rejects transcribe, argparse parses every
new flag cleanly.

Zero changes to core. All new code lives under plugins/google_meet/.

* feat(plugins/google_meet): auto-install, admission detect, mac PCM pump, barge-in, richer status

Ready-for-live-test follow-up on PR #16364. Five additions that matter for
the first live run on a real Meet, in priority order:

1. hermes meet install [--realtime] [--yes]
   pip install playwright websockets + python -m playwright install chromium
   --realtime: installs platform audio deps (pulseaudio-utils on Linux via
   sudo apt, blackhole-2ch + ffmpeg on macOS via brew). Prompts before
   sudo/brew unless --yes. Refuses on Windows. Refuses to auto-flip the
   macOS default input — user still selects BlackHole in System Settings
   (deliberate; surprise audio rerouting is worse than a manual step).

2. Admission detection
   _detect_admission(page): Leave-button visible OR caption region
   attached OR participants list present → we're in-call.
   _detect_denied(page): 'You can\'t join this video call' / 'You were
   removed' / 'No one responded to your request' → bail out.
   HERMES_MEET_LOBBY_TIMEOUT (default 300s) caps how long we sit in
   the lobby before giving up. in_call stays False until admitted.
   Status surfaces leaveReason: duration_expired | lobby_timeout |
   denied | page_closed.

3. macOS PCM pump
   ffmpeg reads speaker.pcm (24kHz s16le mono) and writes to the
   BlackHole AVFoundation output via -f audiotoolbox
   -audio_device_index <N>. _mac_audio_device_index() probes
   ffmpeg -f avfoundation -list_devices true to resolve 'BlackHole 2ch'
   → numeric index. Falls back to index 0 on probe failure. Linux
   paplay pump unchanged.

4. Richer status dict
   _BotState now tracks realtime, realtimeReady, realtimeDevice,
   audioBytesOut, lastAudioOutAt, lastBargeInAt, joinAttemptedAt,
   leaveReason. RealtimeSession.audio_bytes_out / last_audio_out_at
   counters fold into the status file once a second so meet_status()
   can show the agent's voice activity in near-real-time.

5. Barge-in
   RealtimeSession.cancel_response() sends type='response.cancel' over
   the same WS (lock-guarded so it's safe to call from the caption
   thread while speak() is reading frames). Handles response.cancelled
   as a terminal frame type. _looks_like_human_speaker() gates triggers
   so the bot's own name, 'You', 'Unknown', and blanks don't self-cancel.
   Called from the caption drain loop: when a new caption arrives
   attributed to a real participant while rt.session exists, we fire
   cancel_response() and stamp lastBargeInAt.

Tests: 20 new unit tests across _BotState telemetry, barge-in gating,
admission/denied probe error handling, cancel_response with and without
a connected WS, and `hermes meet install` CLI wiring (flag parsing +
end-to-end subprocess.run verification + Linux-already-installed fast
path). Total 171 passing across all google_meet test files + the
plugin-system regression suite.

E2E verified on Linux: plugin loads, all 5 tools register,
`hermes meet install --realtime --yes` parses, fresh-bot status.json
has every new telemetry key, cancel_response on a disconnected session
returns False without raising, barge-in helper gates the bot's own
name correctly.

Still out of scope (for a future PR, not blocking live test):
mic → Realtime duplex (the agent listening to meeting audio via
WebRTC), node-host TLS/pairing UX, Windows audio, Meet create+Twilio.

Docs updated: SKILL.md now lists the installer subcommand, lobby
timeout, barge-in caveat, and the full status-dict reference table.
README.md quick-start uses hermes meet install.

plugins/google_meet/node/server.py

@@ -0,0 +1,193 @@
+"""Remote node server.
+
+Runs on the machine that will host the Meet bot (typically the user's
+Mac laptop with a signed-in Chrome). Exposes a WebSocket endpoint that
+accepts signed RPC requests and dispatches them to the existing
+``plugins.google_meet.process_manager`` module.
+
+Launched by ``hermes meet node run``.
+
+Token handling
+--------------
+On first boot we mint 32 hex chars of entropy and persist them at
+``$HERMES_HOME/workspace/meetings/node_token.json``. Subsequent boots
+reuse the same token so previously-approved gateways don't need to be
+re-paired. The operator copies this token out-of-band to the gateway
+via ``hermes meet node approve <name> <url> <token>``.
+
+Dependencies
+------------
+``websockets`` is an optional dep. We import it lazily inside
+:meth:`serve` so installing the plugin doesn't require it unless you
+actually host a node.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from hermes_constants import get_hermes_home
+from plugins.google_meet.node import protocol as _proto
+
+
+def _default_token_path() -> Path:
+    return Path(get_hermes_home()) / "workspace" / "meetings" / "node_token.json"
+
+
+class NodeServer:
+    """WebSocket server that executes meet bot RPCs locally."""
+
+    def __init__(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 18789,
+        token_path: Optional[Path] = None,
+        display_name: str = "hermes-meet-node",
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.display_name = display_name
+        self.token_path = Path(token_path) if token_path is not None else _default_token_path()
+        self._token: Optional[str] = None
+
+    # ----- token management --------------------------------------------
+
+    def ensure_token(self) -> str:
+        """Return the persisted shared secret, generating one on first use."""
+        if self._token:
+            return self._token
+        if self.token_path.is_file():
+            try:
+                data = json.loads(self.token_path.read_text(encoding="utf-8"))
+                tok = data.get("token")
+                if isinstance(tok, str) and tok:
+                    self._token = tok
+                    return tok
+            except (OSError, json.JSONDecodeError):
+                pass
+        tok = secrets.token_hex(16)  # 32 hex chars
+        self.token_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.token_path.with_suffix(".json.tmp")
+        tmp.write_text(
+            json.dumps({"token": tok, "generated_at": time.time()}, indent=2),
+            encoding="utf-8",
+        )
+        tmp.replace(self.token_path)
+        self._token = tok
+        return tok
+
+    def get_token(self) -> str:
+        """Alias for :meth:`ensure_token`; does not mutate on subsequent calls."""
+        return self.ensure_token()
+
+    # ----- dispatch -----------------------------------------------------
+
+    async def _handle_request(self, msg: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate + dispatch a single decoded request envelope.
+
+        Always returns a response envelope (success or error); never
+        raises. Errors from inside the process_manager are wrapped into
+        the response payload's ``ok``/``error`` keys (which pm already
+        does) rather than being re-encoded as error envelopes — the
+        envelope-level error channel is reserved for auth / protocol
+        failures.
+        """
+        expected = self.ensure_token()
+        ok, reason = _proto.validate_request(msg, expected)
+        if not ok:
+            return _proto.make_error(str(msg.get("id") or ""), reason)
+
+        req_id = msg["id"]
+        t = msg["type"]
+        payload = msg["payload"]
+
+        # Import lazily so test mocks can monkeypatch freely.
+        from plugins.google_meet import process_manager as pm
+
+        try:
+            if t == "ping":
+                return {"type": "pong", "id": req_id,
+                        "payload": {"display_name": self.display_name,
+                                    "ts": time.time()}}
+            if t == "start_bot":
+                # Whitelist kwargs we pass through to pm.start.
+                kwargs = {
+                    k: payload[k]
+                    for k in ("url", "guest_name", "duration", "headed",
+                              "auth_state", "session_id", "out_dir")
+                    if k in payload
+                }
+                if "url" not in kwargs:
+                    return _proto.make_error(req_id, "missing 'url' in payload")
+                result = pm.start(**kwargs)
+                return _proto.make_response(req_id, result)
+            if t == "stop":
+                reason_arg = payload.get("reason", "requested")
+                result = pm.stop(reason=reason_arg)
+                return _proto.make_response(req_id, result)
+            if t == "status":
+                return _proto.make_response(req_id, pm.status())
+            if t == "transcript":
+                last = payload.get("last")
+                result = pm.transcript(last=last)
+                return _proto.make_response(req_id, result)
+            if t == "say":
+                # v2 wiring: enqueue into say_queue.jsonl inside the
+                # active meeting's out_dir when present. The bot-side
+                # consumer is v3+ (for v1 this is a stub returning ok).
+                text = payload.get("text", "")
+                active = pm._read_active()  # type: ignore[attr-defined]
+                enqueued = False
+                if active and active.get("out_dir"):
+                    queue = Path(active["out_dir"]) / "say_queue.jsonl"
+                    try:
+                        queue.parent.mkdir(parents=True, exist_ok=True)
+                        with queue.open("a", encoding="utf-8") as fh:
+                            fh.write(json.dumps({"text": text, "ts": time.time()}) + "\n")
+                        enqueued = True
+                    except OSError:
+                        enqueued = False
+                return _proto.make_response(
+                    req_id,
+                    {"ok": True, "enqueued": enqueued, "text": text},
+                )
+        except Exception as exc:  # noqa: BLE001 — surface any pm crash to client
+            return _proto.make_error(req_id, f"{type(exc).__name__}: {exc}")
+
+        return _proto.make_error(req_id, f"unhandled type: {t!r}")
+
+    # ----- server loop --------------------------------------------------
+
+    async def serve(self) -> None:
+        """Run the WebSocket server until cancelled.
+
+        Blocks forever. Callers typically wrap this in ``asyncio.run``.
+        """
+        try:
+            import websockets  # type: ignore
+        except ImportError as exc:
+            raise RuntimeError(
+                "NodeServer.serve requires the 'websockets' package. "
+                "Install it with: pip install websockets"
+            ) from exc
+
+        self.ensure_token()
+
+        async def _handler(ws):
+            async for raw in ws:
+                try:
+                    msg = _proto.decode(raw if isinstance(raw, str) else raw.decode("utf-8"))
+                except ValueError as exc:
+                    await ws.send(_proto.encode(_proto.make_error("", f"decode: {exc}")))
+                    continue
+                reply = await self._handle_request(msg)
+                await ws.send(_proto.encode(reply))
+
+        async with websockets.serve(_handler, self.host, self.port):
+            # Run until cancelled.
+            import asyncio
+            await asyncio.Future()