add generic gateway startup readiness checks

agent/model_metadata.py

@@ -36,7 +36,6 @@ _PROVIDER_PREFIXES: frozenset[str] = frozenset({
     "opencode", "zen", "go", "vercel", "kilo", "dashscope", "aliyun", "qwen",
     "mimo", "xiaomi-mimo",
     "arcee-ai", "arceeai",
-    "xai", "x-ai", "x.ai", "grok",
     "qwen-portal",
 })
 

cli.py

@@ -989,7 +989,6 @@ def _prune_orphaned_branches(repo_root: str) -> None:
 _ACCENT_ANSI_DEFAULT = "\033[1;38;2;255;215;0m"  # True-color #FFD700 bold — fallback
 _BOLD = "\033[1m"
 _RST = "\033[0m"
-_STREAM_PAD = "    "  # 4-space indent for streamed response text (matches Panel padding)
 
 
 def _hex_to_ansi(hex_color: str, *, bold: bool = False) -> str:
@@ -2581,7 +2580,7 @@ class HermesCLI:
         _tc = getattr(self, "_stream_text_ansi", "")
         while "\n" in self._stream_buf:
             line, self._stream_buf = self._stream_buf.split("\n", 1)
-            _cprint(f"{_STREAM_PAD}{_tc}{line}{_RST}" if _tc else f"{_STREAM_PAD}{line}")
+            _cprint(f"{_tc}{line}{_RST}" if _tc else line)
 
     def _flush_stream(self) -> None:
         """Emit any remaining partial line from the stream buffer and close the box."""
@@ -2598,7 +2597,7 @@ class HermesCLI:
 
         if self._stream_buf:
             _tc = getattr(self, "_stream_text_ansi", "")
-            _cprint(f"{_STREAM_PAD}{_tc}{self._stream_buf}{_RST}" if _tc else f"{_STREAM_PAD}{self._stream_buf}")
+            _cprint(f"{_tc}{self._stream_buf}{_RST}" if _tc else self._stream_buf)
             self._stream_buf = ""
 
         # Close the response box
@@ -5762,7 +5761,7 @@ class HermesCLI:
                         border_style=_resp_color,
                         style=_resp_text,
                         box=rich_box.HORIZONTALS,
-                        padding=(1, 4),
+                        padding=(1, 2),
                     ))
                 else:
                     _cprint("  (No response generated)")
@@ -5886,7 +5885,7 @@ class HermesCLI:
                         title_align="left",
                         border_style=_resp_color,
                         box=rich_box.HORIZONTALS,
-                        padding=(1, 4),
+                        padding=(1, 2),
                     ))
                 else:
                     _cprint("  💬 /btw: (no response)")
@@ -7649,7 +7648,7 @@ class HermesCLI:
                         label = " ⚕ Hermes "
                         fill = w - 2 - len(label)
                         _cprint(f"\n{_ACCENT}╭─{label}{'─' * max(fill - 1, 0)}╮{_RST}")
-                    _cprint(f"{_STREAM_PAD}{sentence.rstrip()}")
+                    _cprint(sentence.rstrip())
 
                 tts_thread = threading.Thread(
                     target=stream_tts_to_speaker,
@@ -7880,7 +7879,7 @@ class HermesCLI:
                         border_style=_resp_color,
                         style=_resp_text,
                         box=rich_box.HORIZONTALS,
-                        padding=(1, 4),
+                        padding=(1, 2),
                     ))
 
 

gateway/hooks.py

@@ -3,11 +3,12 @@ Event Hook System
 
 A lightweight event-driven system that fires handlers at key lifecycle points.
 Hooks are discovered from ~/.hermes/hooks/ directories, each containing:
-  - HOOK.yaml  (metadata: name, description, events list)
+  - HOOK.yaml  (metadata: name, description, events list, optional startup_readiness)
   - handler.py (Python handler with async def handle(event_type, context))
 
 Events:
   - gateway:startup     -- Gateway process starts
+  - gateway:shutdown    -- Gateway process is shutting down
   - session:start       -- New session created (first message of a new session)
   - session:end         -- Session ends (user ran /new or /reset)
   - session:reset       -- Session reset completed (new session entry created)
@@ -31,6 +32,26 @@ from hermes_cli.config import get_hermes_home
 HOOKS_DIR = get_hermes_home() / "hooks"
 
 
+def _normalize_startup_readiness(hook_name: str, manifest: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """Validate and normalize optional startup readiness metadata."""
+    readiness = manifest.get("startup_readiness")
+    if readiness is None:
+        return None
+    if not isinstance(readiness, dict):
+        print(f"[hooks] Ignoring startup_readiness for {hook_name}: expected mapping", flush=True)
+        return None
+
+    check_id = str(readiness.get("id", "")).strip()
+    if not check_id:
+        print(f"[hooks] Ignoring startup_readiness for {hook_name}: missing id", flush=True)
+        return None
+
+    return {
+        "id": check_id,
+        "required": bool(readiness.get("required", True)),
+    }
+
+
 class HookRegistry:
     """
     Discovers, loads, and fires event hooks.
@@ -62,6 +83,7 @@ class HookRegistry:
                 "description": "Run ~/.hermes/BOOT.md on gateway startup",
                 "events": ["gateway:startup"],
                 "path": "(builtin)",
+                "startup_readiness": None,
             })
         except Exception as e:
             print(f"[hooks] Could not load built-in boot-md hook: {e}", flush=True)
@@ -102,6 +124,7 @@ class HookRegistry:
                 if not events:
                     print(f"[hooks] Skipping {hook_name}: no events declared", flush=True)
                     continue
+                startup_readiness = _normalize_startup_readiness(hook_name, manifest)
 
                 # Dynamically load the handler module
                 spec = importlib.util.spec_from_file_location(
@@ -128,6 +151,7 @@ class HookRegistry:
                     "description": manifest.get("description", ""),
                     "events": events,
                     "path": str(hook_dir),
+                    "startup_readiness": startup_readiness,
                 })
 
                 print(f"[hooks] Loaded hook '{hook_name}' for events: {events}", flush=True)

gateway/platforms/discord.py

@@ -1696,10 +1696,6 @@ class DiscordAdapter(BasePlatformAdapter):
         async def slash_update(interaction: discord.Interaction):
             await self._run_simple_slash(interaction, "/update", "Update initiated~")
 
-        @tree.command(name="restart", description="Gracefully restart the Hermes gateway")
-        async def slash_restart(interaction: discord.Interaction):
-            await self._run_simple_slash(interaction, "/restart", "Restart requested~")
-
         @tree.command(name="approve", description="Approve a pending dangerous command")
         @discord.app_commands.describe(scope="Optional: 'all', 'session', 'always', 'all session', 'all always'")
         async def slash_approve(interaction: discord.Interaction, scope: str = ""):

gateway/run.py

@@ -1405,7 +1405,7 @@ class GatewayRunner:
         action = "restarting" if self._restart_requested else "shutting down"
         hint = (
             "Your current task will be interrupted. "
-            "Send any message after restart to resume where it left off."
+            "Use /retry after restart to continue."
             if self._restart_requested
             else "Your current task will be interrupted."
         )
@@ -1540,7 +1540,7 @@ class GatewayRunner:
             pass
         try:
             from gateway.status import write_runtime_status
-            write_runtime_status(gateway_state="starting", exit_reason=None)
+            write_runtime_status(gateway_state="starting", exit_reason=None, startup_checks={})
         except Exception:
             pass
         
@@ -1582,8 +1582,23 @@ class GatewayRunner:
                 "or configure platform allowlists (e.g., TELEGRAM_ALLOWED_USERS=your_id)."
             )
         
+        # Discover plugins before hooks so plugin-owned hook bundles can
+        # participate in this same startup cycle.
+        try:
+            from hermes_cli.plugins import discover_plugins
+
+            discover_plugins()
+        except Exception as e:
+            logger.warning("Plugin discovery during gateway startup failed: %s", e)
+
         # Discover and load event hooks
         self.hooks.discover_and_load()
+        try:
+            from gateway.status import reset_startup_checks
+
+            reset_startup_checks(self.hooks.loaded_hooks)
+        except Exception as e:
+            logger.warning("Startup readiness initialization failed: %s", e)
         
         # Recover background processes from checkpoint (crash recovery)
         try:
@@ -2104,6 +2119,11 @@ class GatewayRunner:
                     logger.error("Failed to launch detached gateway restart: %s", e)
 
             self._finalize_shutdown_agents(active_agents)
+            await self.hooks.emit("gateway:shutdown", {
+                "restart": self._restart_requested,
+                "service_restart": self._restart_via_service,
+                "detached_restart": self._restart_detached,
+            })
 
             for platform, adapter in list(self.adapters.items()):
                 try:
@@ -8450,21 +8470,6 @@ class GatewayRunner:
             if _msn:
                 message = _msn + "\n\n" + message
 
-            # Auto-continue: if the loaded history ends with a tool result,
-            # the previous agent turn was interrupted mid-work (gateway
-            # restart, crash, SIGTERM).  Prepend a system note so the model
-            # finishes processing the pending tool results before addressing
-            # the user's new message.  (#4493)
-            if agent_history and agent_history[-1].get("role") == "tool":
-                message = (
-                    "[System note: Your previous turn was interrupted before you could "
-                    "process the last tool result(s). The conversation history contains "
-                    "tool outputs you haven't responded to yet. Please finish processing "
-                    "those results and summarize what was accomplished, then address the "
-                    "user's new message below.]\n\n"
-                    + message
-                )
-
             _approval_session_key = session_key or ""
             _approval_session_token = set_current_session_key(_approval_session_key)
             register_gateway_notify(_approval_session_key, _approval_notify_sync)

gateway/status.py

@@ -27,6 +27,7 @@ _RUNTIME_STATUS_FILE = "gateway_state.json"
 _LOCKS_DIRNAME = "gateway-locks"
 _IS_WINDOWS = sys.platform == "win32"
 _UNSET = object()
+_VALID_STARTUP_CHECK_STATES = {"pending", "ready", "failed"}
 
 
 def _get_pid_path() -> Path:
@@ -162,11 +163,39 @@ def _build_runtime_status_record() -> dict[str, Any]:
         "restart_requested": False,
         "active_agents": 0,
         "platforms": {},
+        "startup_checks": {},
         "updated_at": _utc_now_iso(),
     })
     return payload
 
 
+def _normalize_startup_check_entries(
+    startup_checks: Optional[dict[str, Any]],
+) -> dict[str, dict[str, Any]]:
+    """Normalize persisted startup readiness entries."""
+    if not isinstance(startup_checks, dict):
+        return {}
+
+    now = _utc_now_iso()
+    normalized: dict[str, dict[str, Any]] = {}
+    for raw_id, raw_payload in startup_checks.items():
+        check_id = str(raw_id).strip()
+        if not check_id:
+            continue
+        payload = raw_payload if isinstance(raw_payload, dict) else {}
+        state = str(payload.get("state", "pending")).strip().lower()
+        if state not in _VALID_STARTUP_CHECK_STATES:
+            state = "pending"
+        normalized[check_id] = {
+            "state": state,
+            "required": bool(payload.get("required", True)),
+            "source": payload.get("source"),
+            "detail": payload.get("detail"),
+            "updated_at": payload.get("updated_at") or now,
+        }
+    return normalized
+
+
 def _read_json_file(path: Path) -> Optional[dict[str, Any]]:
     if not path.exists():
         return None
@@ -223,6 +252,7 @@ def write_runtime_status(
     exit_reason: Any = _UNSET,
     restart_requested: Any = _UNSET,
     active_agents: Any = _UNSET,
+    startup_checks: Any = _UNSET,
     platform: Any = _UNSET,
     platform_state: Any = _UNSET,
     error_code: Any = _UNSET,
@@ -245,6 +275,8 @@ def write_runtime_status(
         payload["restart_requested"] = bool(restart_requested)
     if active_agents is not _UNSET:
         payload["active_agents"] = max(0, int(active_agents))
+    if startup_checks is not _UNSET:
+        payload["startup_checks"] = _normalize_startup_check_entries(startup_checks)
 
     if platform is not _UNSET:
         platform_payload = payload["platforms"].get(platform, {})
@@ -262,7 +294,109 @@ def write_runtime_status(
 
 def read_runtime_status() -> Optional[dict[str, Any]]:
     """Read the persisted gateway runtime health/status information."""
-    return _read_json_file(_get_runtime_status_path())
+    payload = _read_json_file(_get_runtime_status_path())
+    if payload is None:
+        return None
+    payload.setdefault("platforms", {})
+    payload["startup_checks"] = _normalize_startup_check_entries(payload.get("startup_checks"))
+    return payload
+
+
+def reset_startup_checks(checks: Optional[list[dict[str, Any]]] = None) -> dict[str, dict[str, Any]]:
+    """Replace persisted startup readiness checks for the current run."""
+    normalized: dict[str, dict[str, Any]] = {}
+    now = _utc_now_iso()
+
+    for hook in checks or []:
+        if not isinstance(hook, dict):
+            continue
+        readiness = hook.get("startup_readiness")
+        if not isinstance(readiness, dict):
+            continue
+        check_id = str(readiness.get("id", "")).strip()
+        if not check_id:
+            continue
+        normalized[check_id] = {
+            "state": "pending",
+            "required": bool(readiness.get("required", True)),
+            "source": hook.get("name"),
+            "detail": None,
+            "updated_at": now,
+        }
+
+    write_runtime_status(startup_checks=normalized)
+    return normalized
+
+
+def update_startup_check(
+    check_id: str,
+    state: str,
+    *,
+    detail: Any = _UNSET,
+    required: Any = _UNSET,
+    source: Any = _UNSET,
+) -> dict[str, Any]:
+    """Update a single startup readiness check in the runtime status file."""
+    normalized_id = str(check_id).strip()
+    if not normalized_id:
+        raise ValueError("startup readiness check id is required")
+
+    normalized_state = str(state).strip().lower()
+    if normalized_state not in _VALID_STARTUP_CHECK_STATES:
+        raise ValueError(f"invalid startup readiness state: {state}")
+
+    path = _get_runtime_status_path()
+    payload = _read_json_file(path) or _build_runtime_status_record()
+    checks = _normalize_startup_check_entries(payload.get("startup_checks"))
+    existing = checks.get(normalized_id, {})
+    now = _utc_now_iso()
+
+    checks[normalized_id] = {
+        "state": normalized_state,
+        "required": bool(existing.get("required", True) if required is _UNSET else required),
+        "source": existing.get("source") if source is _UNSET else source,
+        "detail": existing.get("detail") if detail is _UNSET else detail,
+        "updated_at": now,
+    }
+
+    payload["startup_checks"] = checks
+    payload.setdefault("platforms", {})
+    payload.setdefault("kind", _GATEWAY_KIND)
+    payload["pid"] = os.getpid()
+    payload["start_time"] = _get_process_start_time(os.getpid())
+    payload["updated_at"] = now
+    _write_json_file(path, payload)
+    return checks[normalized_id]
+
+
+def mark_startup_check_pending(
+    check_id: str,
+    *,
+    detail: Any = _UNSET,
+    required: Any = _UNSET,
+    source: Any = _UNSET,
+) -> dict[str, Any]:
+    return update_startup_check(check_id, "pending", detail=detail, required=required, source=source)
+
+
+def mark_startup_check_ready(
+    check_id: str,
+    *,
+    detail: Any = _UNSET,
+    required: Any = _UNSET,
+    source: Any = _UNSET,
+) -> dict[str, Any]:
+    return update_startup_check(check_id, "ready", detail=detail, required=required, source=source)
+
+
+def mark_startup_check_failed(
+    check_id: str,
+    *,
+    detail: Any = _UNSET,
+    required: Any = _UNSET,
+    source: Any = _UNSET,
+) -> dict[str, Any]:
+    return update_startup_check(check_id, "failed", detail=detail, required=required, source=source)
 
 
 def remove_pid_file() -> None:

hermes_cli/gateway.py

@@ -10,6 +10,7 @@ import shutil
 import signal
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 PROJECT_ROOT = Path(__file__).parent.parent.resolve()
@@ -37,6 +38,10 @@ from hermes_cli.setup import (
 from hermes_cli.colors import Colors, color
 
 
+_SERVICE_READINESS_TIMEOUT = 30.0
+_SERVICE_READINESS_POLL_INTERVAL = 0.2
+
+
 # =============================================================================
 # Process Management (for manual gateway runs)
 # =============================================================================
@@ -1100,12 +1105,123 @@ def systemd_uninstall(system: bool = False):
     print(f"✓ {_service_scope_label(system).capitalize()} service uninstalled")
 
 
+def _describe_startup_check(check_id: str, check: dict) -> str:
+    source = check.get("source")
+    detail = check.get("detail")
+    label = f"{check_id} ({source})" if source and source != check_id else check_id
+    return f"{label}: {detail}" if detail else label
+
+
+def _classify_startup_checks(state: dict | None) -> tuple[list[str], list[str], list[str]]:
+    checks = (state or {}).get("startup_checks") or {}
+    pending_required: list[str] = []
+    failed_required: list[str] = []
+    optional_warnings: list[str] = []
+
+    if not isinstance(checks, dict):
+        return pending_required, failed_required, optional_warnings
+
+    for check_id, raw_check in checks.items():
+        check = raw_check if isinstance(raw_check, dict) else {}
+        label = _describe_startup_check(str(check_id), check)
+        check_state = str(check.get("state", "pending")).strip().lower()
+        required = bool(check.get("required", True))
+
+        if check_state == "ready":
+            continue
+        if required:
+            if check_state == "failed":
+                failed_required.append(label)
+            else:
+                pending_required.append(label)
+        else:
+            prefix = "failed" if check_state == "failed" else "pending"
+            optional_warnings.append(f"{prefix}: {label}")
+
+    return pending_required, failed_required, optional_warnings
+
+
+def _wait_for_service_readiness(
+    *,
+    action: str,
+    previous_pid: int | None = None,
+    timeout: float = _SERVICE_READINESS_TIMEOUT,
+    poll_interval: float = _SERVICE_READINESS_POLL_INTERVAL,
+) -> list[str]:
+    from gateway.status import get_running_pid, read_runtime_status
+
+    deadline = time.monotonic() + timeout
+    last_pending: list[str] = []
+
+    while time.monotonic() < deadline:
+        live_pid = get_running_pid()
+        if live_pid is None or (previous_pid is not None and live_pid == previous_pid):
+            time.sleep(poll_interval)
+            continue
+
+        runtime = read_runtime_status() or {}
+        try:
+            runtime_pid = int(runtime.get("pid"))
+        except (TypeError, ValueError):
+            runtime_pid = None
+        if runtime_pid != live_pid:
+            time.sleep(poll_interval)
+            continue
+
+        gateway_state = runtime.get("gateway_state")
+        pending_required, failed_required, optional_warnings = _classify_startup_checks(runtime)
+        last_pending = pending_required
+
+        if gateway_state == "startup_failed":
+            reason = runtime.get("exit_reason") or f"gateway {action} failed during startup"
+            raise RuntimeError(reason)
+        if failed_required:
+            raise RuntimeError(
+                "required startup checks failed: " + "; ".join(failed_required)
+            )
+        if gateway_state == "running" and not pending_required:
+            return optional_warnings
+
+        time.sleep(poll_interval)
+
+    if last_pending:
+        raise RuntimeError(
+            "timed out waiting for required startup checks: " + "; ".join(last_pending)
+        )
+    if previous_pid is not None:
+        raise RuntimeError(
+            f"timed out waiting for gateway {action}; previous process is still active or no new runtime became ready"
+        )
+    raise RuntimeError(f"timed out waiting for gateway {action} readiness")
+
+
+def _await_service_ready_or_exit(
+    *,
+    action: str,
+    previous_pid: int | None = None,
+    timeout: float = _SERVICE_READINESS_TIMEOUT,
+) -> None:
+    try:
+        optional_warnings = _wait_for_service_readiness(
+            action=action,
+            previous_pid=previous_pid,
+            timeout=timeout,
+        )
+    except RuntimeError as exc:
+        print_error(f"  Gateway {action} did not become ready: {exc}")
+        raise SystemExit(1) from exc
+
+    for warning in optional_warnings:
+        print_warning(f"  Optional startup check {warning}")
+
+
 def systemd_start(system: bool = False):
     system = _select_systemd_scope(system)
     if system:
         _require_root_for_system_service("start")
     refresh_systemd_unit_if_needed(system=system)
     _run_systemctl(["start", get_service_name()], system=system, check=True, timeout=30)
+    _await_service_ready_or_exit(action="start")
     print(f"✓ {_service_scope_label(system).capitalize()} service started")
 
 
@@ -1128,9 +1244,11 @@ def systemd_restart(system: bool = False):
 
     pid = get_running_pid()
     if pid is not None and _request_gateway_self_restart(pid):
-        print(f"✓ {_service_scope_label(system).capitalize()} service restart requested")
+        _await_service_ready_or_exit(action="restart", previous_pid=pid)
+        print(f"✓ {_service_scope_label(system).capitalize()} service restarted")
         return
     _run_systemctl(["reload-or-restart", get_service_name()], system=system, check=True, timeout=90)
+    _await_service_ready_or_exit(action="restart", previous_pid=pid)
     print(f"✓ {_service_scope_label(system).capitalize()} service restarted")
 
 
@@ -1389,6 +1507,7 @@ def launchd_start():
         plist_path.write_text(generate_launchd_plist(), encoding="utf-8")
         subprocess.run(["launchctl", "bootstrap", _launchd_domain(), str(plist_path)], check=True, timeout=30)
         subprocess.run(["launchctl", "kickstart", f"{_launchd_domain()}/{label}"], check=True, timeout=30)
+        _await_service_ready_or_exit(action="start")
         print("✓ Service started")
         return
 
@@ -1401,6 +1520,7 @@ def launchd_start():
         print("↻ launchd job was unloaded; reloading service definition")
         subprocess.run(["launchctl", "bootstrap", _launchd_domain(), str(plist_path)], check=True, timeout=30)
         subprocess.run(["launchctl", "kickstart", f"{_launchd_domain()}/{label}"], check=True, timeout=30)
+    _await_service_ready_or_exit(action="start")
     print("✓ Service started")
 
 def launchd_stop():
@@ -1471,7 +1591,8 @@ def launchd_restart():
     try:
         pid = get_running_pid()
         if pid is not None and _request_gateway_self_restart(pid):
-            print("✓ Service restart requested")
+            _await_service_ready_or_exit(action="restart", previous_pid=pid)
+            print("✓ Service restarted")
             return
         if pid is not None:
             try:
@@ -1483,6 +1604,7 @@ def launchd_restart():
                 if not exited:
                     print(f"⚠ Gateway drain timed out after {drain_timeout:.0f}s — forcing launchd restart")
         subprocess.run(["launchctl", "kickstart", "-k", target], check=True, timeout=90)
+        _await_service_ready_or_exit(action="restart", previous_pid=pid)
         print("✓ Service restarted")
     except subprocess.CalledProcessError as e:
         if e.returncode not in (3, 113):
@@ -1492,6 +1614,7 @@ def launchd_restart():
         plist_path = get_launchd_plist_path()
         subprocess.run(["launchctl", "bootstrap", _launchd_domain(), str(plist_path)], check=True, timeout=30)
         subprocess.run(["launchctl", "kickstart", target], check=True, timeout=30)
+        _await_service_ready_or_exit(action="restart", previous_pid=pid)
         print("✓ Service restarted")
 
 def launchd_status(deep: bool = False):

hermes_cli/tools_config.py

@@ -121,7 +121,6 @@ TOOL_CATEGORIES = {
         "providers": [
             {
                 "name": "Nous Subscription",
-                "badge": "subscription",
                 "tag": "Managed OpenAI TTS billed to your subscription",
                 "env_vars": [],
                 "tts_provider": "openai",
@@ -131,15 +130,13 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Microsoft Edge TTS",
-                "badge": "★ recommended · free",
-                "tag": "Good quality, no API key needed",
+                "tag": "Free - no API key needed",
                 "env_vars": [],
                 "tts_provider": "edge",
             },
             {
                 "name": "OpenAI TTS",
-                "badge": "paid",
-                "tag": "High quality voices",
+                "tag": "Premium - high quality voices",
                 "env_vars": [
                     {"key": "VOICE_TOOLS_OPENAI_KEY", "prompt": "OpenAI API key", "url": "https://platform.openai.com/api-keys"},
                 ],
@@ -147,8 +144,7 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "ElevenLabs",
-                "badge": "paid",
-                "tag": "Most natural voices",
+                "tag": "Premium - most natural voices",
                 "env_vars": [
                     {"key": "ELEVENLABS_API_KEY", "prompt": "ElevenLabs API key", "url": "https://elevenlabs.io/app/settings/api-keys"},
                 ],
@@ -156,8 +152,7 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Mistral (Voxtral TTS)",
-                "badge": "paid",
-                "tag": "Multilingual, native Opus",
+                "tag": "Multilingual, native Opus, needs MISTRAL_API_KEY",
                 "env_vars": [
                     {"key": "MISTRAL_API_KEY", "prompt": "Mistral API key", "url": "https://console.mistral.ai/"},
                 ],
@@ -173,7 +168,6 @@ TOOL_CATEGORIES = {
         "providers": [
             {
                 "name": "Nous Subscription",
-                "badge": "subscription",
                 "tag": "Managed Firecrawl billed to your subscription",
                 "web_backend": "firecrawl",
                 "env_vars": [],
@@ -183,8 +177,7 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Firecrawl Cloud",
-                "badge": "★ recommended",
-                "tag": "Full-featured search, extract, and crawl",
+                "tag": "Hosted service - search, extract, and crawl",
                 "web_backend": "firecrawl",
                 "env_vars": [
                     {"key": "FIRECRAWL_API_KEY", "prompt": "Firecrawl API key", "url": "https://firecrawl.dev"},
@@ -192,8 +185,7 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Exa",
-                "badge": "paid",
-                "tag": "Neural search with semantic understanding",
+                "tag": "AI-native search and contents",
                 "web_backend": "exa",
                 "env_vars": [
                     {"key": "EXA_API_KEY", "prompt": "Exa API key", "url": "https://exa.ai"},
@@ -201,8 +193,7 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Parallel",
-                "badge": "paid",
-                "tag": "AI-powered search and extract",
+                "tag": "AI-native search and extract",
                 "web_backend": "parallel",
                 "env_vars": [
                     {"key": "PARALLEL_API_KEY", "prompt": "Parallel API key", "url": "https://parallel.ai"},
@@ -210,8 +201,7 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Tavily",
-                "badge": "free tier",
-                "tag": "Search, extract, and crawl — 1000 free searches/mo",
+                "tag": "AI-native search, extract, and crawl",
                 "web_backend": "tavily",
                 "env_vars": [
                     {"key": "TAVILY_API_KEY", "prompt": "Tavily API key", "url": "https://app.tavily.com/home"},
@@ -219,8 +209,7 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Firecrawl Self-Hosted",
-                "badge": "free · self-hosted",
-                "tag": "Run your own Firecrawl instance (Docker)",
+                "tag": "Free - run your own instance",
                 "web_backend": "firecrawl",
                 "env_vars": [
                     {"key": "FIRECRAWL_API_URL", "prompt": "Your Firecrawl instance URL (e.g., http://localhost:3002)"},
@@ -234,7 +223,6 @@ TOOL_CATEGORIES = {
         "providers": [
             {
                 "name": "Nous Subscription",
-                "badge": "subscription",
                 "tag": "Managed FAL image generation billed to your subscription",
                 "env_vars": [],
                 "requires_nous_auth": True,
@@ -243,7 +231,6 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "FAL.ai",
-                "badge": "paid",
                 "tag": "FLUX 2 Pro with auto-upscaling",
                 "env_vars": [
                     {"key": "FAL_KEY", "prompt": "FAL API key", "url": "https://fal.ai/dashboard/keys"},
@@ -257,7 +244,6 @@ TOOL_CATEGORIES = {
         "providers": [
             {
                 "name": "Nous Subscription (Browser Use cloud)",
-                "badge": "subscription",
                 "tag": "Managed Browser Use billed to your subscription",
                 "env_vars": [],
                 "browser_provider": "browser-use",
@@ -268,16 +254,14 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Local Browser",
-                "badge": "★ recommended · free",
-                "tag": "Headless Chromium, no API key needed",
+                "tag": "Free headless Chromium (no API key needed)",
                 "env_vars": [],
                 "browser_provider": "local",
                 "post_setup": "agent_browser",
             },
             {
                 "name": "Browserbase",
-                "badge": "paid",
-                "tag": "Cloud browser with stealth and proxies",
+                "tag": "Cloud browser with stealth & proxies",
                 "env_vars": [
                     {"key": "BROWSERBASE_API_KEY", "prompt": "Browserbase API key", "url": "https://browserbase.com"},
                     {"key": "BROWSERBASE_PROJECT_ID", "prompt": "Browserbase project ID"},
@@ -287,7 +271,6 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Browser Use",
-                "badge": "paid",
                 "tag": "Cloud browser with remote execution",
                 "env_vars": [
                     {"key": "BROWSER_USE_API_KEY", "prompt": "Browser Use API key", "url": "https://browser-use.com"},
@@ -297,7 +280,6 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Firecrawl",
-                "badge": "paid",
                 "tag": "Cloud browser with remote execution",
                 "env_vars": [
                     {"key": "FIRECRAWL_API_KEY", "prompt": "Firecrawl API key", "url": "https://firecrawl.dev"},
@@ -307,8 +289,7 @@ TOOL_CATEGORIES = {
             },
             {
                 "name": "Camofox",
-                "badge": "free · local",
-                "tag": "Anti-detection browser (Firefox/Camoufox)",
+                "tag": "Local anti-detection browser (Firefox/Camoufox)",
                 "env_vars": [
                     {"key": "CAMOFOX_URL", "prompt": "Camofox server URL", "default": "http://localhost:9377",
                      "url": "https://github.com/jo-inc/camofox-browser"},
@@ -857,8 +838,7 @@ def _configure_tool_category(ts_key: str, cat: dict, config: dict):
         # Plain text labels only (no ANSI codes in menu items)
         provider_choices = []
         for p in providers:
-            badge = f" [{p['badge']}]" if p.get("badge") else ""
-            tag = f" — {p['tag']}" if p.get("tag") else ""
+            tag = f" ({p['tag']})" if p.get("tag") else ""
             configured = ""
             env_vars = p.get("env_vars", [])
             if not env_vars or all(get_env_value(v["key"]) for v in env_vars):
@@ -868,7 +848,7 @@ def _configure_tool_category(ts_key: str, cat: dict, config: dict):
                     configured = ""
                 else:
                     configured = " [configured]"
-            provider_choices.append(f"{p['name']}{badge}{tag}{configured}")
+            provider_choices.append(f"{p['name']}{tag}{configured}")
 
         # Add skip option
         provider_choices.append("Skip — keep defaults / configure later")
@@ -1124,8 +1104,7 @@ def _configure_tool_category_for_reconfig(ts_key: str, cat: dict, config: dict):
 
         provider_choices = []
         for p in providers:
-            badge = f" [{p['badge']}]" if p.get("badge") else ""
-            tag = f" — {p['tag']}" if p.get("tag") else ""
+            tag = f" ({p['tag']})" if p.get("tag") else ""
             configured = ""
             env_vars = p.get("env_vars", [])
             if not env_vars or all(get_env_value(v["key"]) for v in env_vars):
@@ -1135,7 +1114,7 @@ def _configure_tool_category_for_reconfig(ts_key: str, cat: dict, config: dict):
                     configured = ""
                 else:
                     configured = " [configured]"
-            provider_choices.append(f"{p['name']}{badge}{tag}{configured}")
+            provider_choices.append(f"{p['name']}{tag}{configured}")
 
         default_idx = _detect_active_provider_index(providers, config)
 

run_agent.py

@@ -264,19 +264,6 @@ def _is_destructive_command(cmd: str) -> bool:
     return False
 
 
-def _is_mcp_tool_parallel_safe(tool_name: str) -> bool:
-    """Check if an MCP tool comes from a server with parallel tool calls enabled.
-
-    Lazy-imports from ``tools.mcp_tool`` to avoid circular dependencies.
-    Returns False if the MCP module is not available.
-    """
-    try:
-        from tools.mcp_tool import is_mcp_tool_parallel_safe
-        return is_mcp_tool_parallel_safe(tool_name)
-    except Exception:
-        return False
-
-
 def _should_parallelize_tool_batch(tool_calls) -> bool:
     """Return True when a tool-call batch is safe to run concurrently."""
     if len(tool_calls) <= 1:
@@ -316,9 +303,7 @@ def _should_parallelize_tool_batch(tool_calls) -> bool:
             continue
 
         if tool_name not in _PARALLEL_SAFE_TOOLS:
-            # Check if it's an MCP tool from a server that opted into parallel calls.
-            if not _is_mcp_tool_parallel_safe(tool_name):
-                return False
+            return False
 
     return True
 
@@ -6990,31 +6975,6 @@ class AIAgent:
                 skip_pre_tool_call_hook=True,
             )
 
-    @staticmethod
-    def _wrap_verbose(label: str, text: str, indent: str = "     ") -> str:
-        """Word-wrap verbose tool output to fit the terminal width.
-
-        Splits *text* on existing newlines and wraps each line individually,
-        preserving intentional line breaks (e.g. pretty-printed JSON).
-        Returns a ready-to-print string with *label* on the first line and
-        continuation lines indented.
-        """
-        import shutil as _shutil
-        import textwrap as _tw
-        cols = _shutil.get_terminal_size((120, 24)).columns
-        wrap_width = max(40, cols - len(indent))
-        out_lines: list[str] = []
-        for raw_line in text.split("\n"):
-            if len(raw_line) <= wrap_width:
-                out_lines.append(raw_line)
-            else:
-                wrapped = _tw.wrap(raw_line, width=wrap_width,
-                                   break_long_words=True,
-                                   break_on_hyphens=False)
-                out_lines.extend(wrapped or [raw_line])
-        body = ("\n" + indent).join(out_lines)
-        return f"{indent}{label}{body}"
-
     def _execute_tool_calls_concurrent(self, assistant_message, messages: list, effective_task_id: str, api_call_count: int = 0) -> None:
         """Execute multiple tool calls concurrently using a thread pool.
 
@@ -7085,7 +7045,7 @@ class AIAgent:
                 args_str = json.dumps(args, ensure_ascii=False)
                 if self.verbose_logging:
                     print(f"  📞 Tool {i}: {name}({list(args.keys())})")
-                    print(self._wrap_verbose("Args: ", json.dumps(args, indent=2, ensure_ascii=False)))
+                    print(f"     Args: {args_str}")
                 else:
                     args_preview = args_str[:self.log_prefix_chars] + "..." if len(args_str) > self.log_prefix_chars else args_str
                     print(f"  📞 Tool {i}: {name}({list(args.keys())}) - {args_preview}")
@@ -7183,7 +7143,7 @@ class AIAgent:
             elif not self.quiet_mode:
                 if self.verbose_logging:
                     print(f"  ✅ Tool {i+1} completed in {tool_duration:.2f}s")
-                    print(self._wrap_verbose("Result: ", function_result))
+                    print(f"     Result: {function_result}")
                 else:
                     response_preview = function_result[:self.log_prefix_chars] + "..." if len(function_result) > self.log_prefix_chars else function_result
                     print(f"  ✅ Tool {i+1} completed in {tool_duration:.2f}s - {response_preview}")
@@ -7276,7 +7236,7 @@ class AIAgent:
                 args_str = json.dumps(function_args, ensure_ascii=False)
                 if self.verbose_logging:
                     print(f"  📞 Tool {i}: {function_name}({list(function_args.keys())})")
-                    print(self._wrap_verbose("Args: ", json.dumps(function_args, indent=2, ensure_ascii=False)))
+                    print(f"     Args: {args_str}")
                 else:
                     args_preview = args_str[:self.log_prefix_chars] + "..." if len(args_str) > self.log_prefix_chars else args_str
                     print(f"  📞 Tool {i}: {function_name}({list(function_args.keys())}) - {args_preview}")
@@ -7564,7 +7524,7 @@ class AIAgent:
             if not self.quiet_mode:
                 if self.verbose_logging:
                     print(f"  ✅ Tool {i} completed in {tool_duration:.2f}s")
-                    print(self._wrap_verbose("Result: ", function_result))
+                    print(f"     Result: {function_result}")
                 else:
                     response_preview = function_result[:self.log_prefix_chars] + "..." if len(function_result) > self.log_prefix_chars else function_result
                     print(f"  ✅ Tool {i} completed in {tool_duration:.2f}s - {response_preview}")

scripts/release.py

@@ -96,7 +96,6 @@ AUTHOR_MAP = {
     "aryan@synvoid.com": "aryansingh",
     "johnsonblake1@gmail.com": "blakejohnson",
     "kennyx102@gmail.com": "bobashopcashier",
-    "shokatalishaikh95@gmail.com": "areu01or00",
     "bryan@intertwinesys.com": "bryanyoung",
     "christo.mitov@gmail.com": "christomitov",
     "hermes@nousresearch.com": "NousResearch",

skills/productivity/google-workspace/SKILL.md

@@ -1,19 +1,35 @@
 ---
 name: google-workspace
-description: Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration for Hermes. Uses Hermes-managed OAuth2 setup, prefers the Google Workspace CLI (`gws`) when available for broader API coverage, and falls back to the Python client libraries otherwise.
-version: 1.0.0
+description: Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration via gws CLI (googleworkspace/cli). Uses OAuth2 with automatic token refresh via bridge script. Requires gws binary.
+version: 2.0.0
 author: Nous Research
 license: MIT
+required_credential_files:
+  - path: google_token.json
+    description: Google OAuth2 token (created by setup script)
+  - path: google_client_secret.json
+    description: Google OAuth2 client credentials (downloaded from Google Cloud Console)
 metadata:
   hermes:
-    tags: [Google, Gmail, Calendar, Drive, Sheets, Docs, Contacts, Email, OAuth]
+    tags: [Google, Gmail, Calendar, Drive, Sheets, Docs, Contacts, Email, OAuth, gws]
     homepage: https://github.com/NousResearch/hermes-agent
     related_skills: [himalaya]
 ---
 
 # Google Workspace
 
-Gmail, Calendar, Drive, Contacts, Sheets, and Docs — through Hermes-managed OAuth and a thin CLI wrapper. When `gws` is installed, the skill uses it as the execution backend for broader Google Workspace coverage; otherwise it falls back to the bundled Python client implementation.
+Gmail, Calendar, Drive, Contacts, Sheets, and Docs — powered by `gws` (Google's official Rust CLI). The skill provides a backward-compatible Python wrapper that handles OAuth token refresh and delegates to `gws`.
+
+## Architecture
+
+```
+google_api.py  →  gws_bridge.py  →  gws CLI
+(argparse compat)  (token refresh)    (Google APIs)
+```
+
+- `setup.py` handles OAuth2 (headless-compatible, works on CLI/Telegram/Discord)
+- `gws_bridge.py` refreshes the Hermes token and injects it into `gws` via `GOOGLE_WORKSPACE_CLI_TOKEN`
+- `google_api.py` provides the same CLI interface as v1 but delegates to `gws`
 
 ## References
 
@@ -22,7 +38,22 @@ Gmail, Calendar, Drive, Contacts, Sheets, and Docs — through Hermes-managed OA
 ## Scripts
 
 - `scripts/setup.py` — OAuth2 setup (run once to authorize)
-- `scripts/google_api.py` — compatibility wrapper CLI. It prefers `gws` for operations when available, while preserving Hermes' existing JSON output contract.
+- `scripts/gws_bridge.py` — Token refresh bridge to gws CLI
+- `scripts/google_api.py` — Backward-compatible API wrapper (delegates to gws)
+
+## Prerequisites
+
+Install `gws`:
+
+```bash
+cargo install google-workspace-cli
+# or via npm (recommended, downloads prebuilt binary):
+npm install -g @googleworkspace/cli
+# or via Homebrew:
+brew install googleworkspace-cli
+```
+
+Verify: `gws --version`
 
 ## First-Time Setup
 
@@ -32,7 +63,13 @@ on CLI, Telegram, Discord, or any platform.
 Define a shorthand first:
 
 ```bash
-GSETUP="python ~/.hermes/skills/productivity/google-workspace/scripts/setup.py"
+HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
+GWORKSPACE_SKILL_DIR="$HERMES_HOME/skills/productivity/google-workspace"
+PYTHON_BIN="${HERMES_PYTHON:-python3}"
+if [ -x "$HERMES_HOME/hermes-agent/venv/bin/python" ]; then
+  PYTHON_BIN="$HERMES_HOME/hermes-agent/venv/bin/python"
+fi
+GSETUP="$PYTHON_BIN $GWORKSPACE_SKILL_DIR/scripts/setup.py"
 ```
 
 ### Step 0: Check if already set up
@@ -45,166 +82,88 @@ If it prints `AUTHENTICATED`, skip to Usage — setup is already done.
 
 ### Step 1: Triage — ask the user what they need
 
-Before starting OAuth setup, ask the user TWO questions:
-
 **Question 1: "What Google services do you need? Just email, or also
 Calendar/Drive/Sheets/Docs?"**
 
-- **Email only** → They don't need this skill at all. Use the `himalaya` skill
-  instead — it works with a Gmail App Password (Settings → Security → App
-  Passwords) and takes 2 minutes to set up. No Google Cloud project needed.
-  Load the himalaya skill and follow its setup instructions.
+- **Email only** → Use the `himalaya` skill instead — simpler setup.
+- **Calendar, Drive, Sheets, Docs (or email + these)** → Continue below.
 
-- **Email + Calendar** → Continue with this skill, but use
-  `--services email,calendar` during auth so the consent screen only asks for
-  the scopes they actually need.
+**Partial scopes**: Users can authorize only a subset of services. The setup
+script accepts partial scopes and warns about missing ones.
 
-- **Calendar/Drive/Sheets/Docs only** → Continue with this skill and use a
-  narrower `--services` set like `calendar,drive,sheets,docs`.
+**Question 2: "Does your Google account use Advanced Protection?"**
 
-- **Full Workspace access** → Continue with this skill and use the default
-  `all` service set.
-
-**Question 2: "Does your Google account use Advanced Protection (hardware
-security keys required to sign in)? If you're not sure, you probably don't
-— it's something you would have explicitly enrolled in."**
-
-- **No / Not sure** → Normal setup. Continue below.
-- **Yes** → Their Workspace admin must add the OAuth client ID to the org's
-  allowed apps list before Step 4 will work. Let them know upfront.
+- **No / Not sure** → Normal setup.
+- **Yes** → Workspace admin must add the OAuth client ID to allowed apps first.
 
 ### Step 2: Create OAuth credentials (one-time, ~5 minutes)
 
 Tell the user:
 
-> You need a Google Cloud OAuth client. This is a one-time setup:
->
-> 1. Create or select a project:
->    https://console.cloud.google.com/projectselector2/home/dashboard
-> 2. Enable the required APIs from the API Library:
->    https://console.cloud.google.com/apis/library
->    Enable: Gmail API, Google Calendar API, Google Drive API,
->    Google Sheets API, Google Docs API, People API
-> 3. Create the OAuth client here:
->    https://console.cloud.google.com/apis/credentials
->    Credentials → Create Credentials → OAuth 2.0 Client ID
-> 4. Application type: "Desktop app" → Create
-> 5. If the app is still in Testing, add the user's Google account as a test user here:
->    https://console.cloud.google.com/auth/audience
->    Audience → Test users → Add users
-> 6. Download the JSON file and tell me the file path
->
-> Important Hermes CLI note: if the file path starts with `/`, do NOT send only the bare path as its own message in the CLI, because it can be mistaken for a slash command. Send it in a sentence instead, like:
-> `The JSON file path is: /home/user/Downloads/client_secret_....json`
-
-Once they provide the path:
+> 1. Go to https://console.cloud.google.com/apis/credentials
+> 2. Create a project (or use an existing one)
+> 3. Enable the APIs you need (Gmail, Calendar, Drive, Sheets, Docs, People)
+> 4. Credentials → Create Credentials → OAuth 2.0 Client ID → Desktop app
+> 5. Download JSON and tell me the file path
 
 ```bash
 $GSETUP --client-secret /path/to/client_secret.json
 ```
 
-If they paste the raw client ID / client secret values instead of a file path,
-write a valid Desktop OAuth JSON file for them yourself, save it somewhere
-explicit (for example `~/Downloads/hermes-google-client-secret.json`), then run
-`--client-secret` against that file.
-
 ### Step 3: Get authorization URL
 
-Use the service set chosen in Step 1. Examples:
-
 ```bash
-$GSETUP --auth-url --services email,calendar --format json
-$GSETUP --auth-url --services calendar,drive,sheets,docs --format json
-$GSETUP --auth-url --services all --format json
+$GSETUP --auth-url
 ```
 
-This returns JSON with an `auth_url` field and also saves the exact URL to
-`~/.hermes/google_oauth_last_url.txt`.
-
-Agent rules for this step:
-- Extract the `auth_url` field and send that exact URL to the user as a single line.
-- Tell the user that the browser will likely fail on `http://localhost:1` after approval, and that this is expected.
-- Tell them to copy the ENTIRE redirected URL from the browser address bar.
-- If the user gets `Error 403: access_denied`, send them directly to `https://console.cloud.google.com/auth/audience` to add themselves as a test user.
+Send the URL to the user. After authorizing, they paste back the redirect URL or code.
 
 ### Step 4: Exchange the code
 
-The user will paste back either a URL like `http://localhost:1/?code=4/0A...&scope=...`
-or just the code string. Either works. The `--auth-url` step stores a temporary
-pending OAuth session locally so `--auth-code` can complete the PKCE exchange
-later, even on headless systems:
-
 ```bash
-$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED" --format json
+$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED"
 ```
 
-If `--auth-code` fails because the code expired, was already used, or came from
-an older browser tab, it now returns a fresh `fresh_auth_url`. In that case,
-immediately send the new URL to the user and have them retry with the newest
-browser redirect only.
-
 ### Step 5: Verify
 
 ```bash
 $GSETUP --check
 ```
 
-Should print `AUTHENTICATED`. Setup is complete — token refreshes automatically from now on.
-
-### Notes
-
-- Token is stored at `~/.hermes/google_token.json` and auto-refreshes.
-- Pending OAuth session state/verifier are stored temporarily at `~/.hermes/google_oauth_pending.json` until exchange completes.
-- If `gws` is installed, `google_api.py` points it at the same `~/.hermes/google_token.json` credentials file. Users do not need to run a separate `gws auth login` flow.
-- To revoke: `$GSETUP --revoke`
+Should print `AUTHENTICATED`. Token refreshes automatically from now on.
 
 ## Usage
 
-All commands go through the API script. Set `GAPI` as a shorthand:
+All commands go through the API script:
 
 ```bash
-GAPI="python ~/.hermes/skills/productivity/google-workspace/scripts/google_api.py"
+HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
+GWORKSPACE_SKILL_DIR="$HERMES_HOME/skills/productivity/google-workspace"
+PYTHON_BIN="${HERMES_PYTHON:-python3}"
+if [ -x "$HERMES_HOME/hermes-agent/venv/bin/python" ]; then
+  PYTHON_BIN="$HERMES_HOME/hermes-agent/venv/bin/python"
+fi
+GAPI="$PYTHON_BIN $GWORKSPACE_SKILL_DIR/scripts/google_api.py"
 ```
 
 ### Gmail
 
 ```bash
-# Search (returns JSON array with id, from, subject, date, snippet)
 $GAPI gmail search "is:unread" --max 10
-$GAPI gmail search "from:boss@company.com newer_than:1d"
-$GAPI gmail search "has:attachment filename:pdf newer_than:7d"
-
-# Read full message (returns JSON with body text)
 $GAPI gmail get MESSAGE_ID
-
-# Send
 $GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
-$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1><p>Details...</p>" --html
-$GAPI gmail send --to user@example.com --subject "Hello" --from '"Research Agent" <user@example.com>' --body "Message text"
-
-# Reply (automatically threads and sets In-Reply-To)
+$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1>" --html
 $GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
-$GAPI gmail reply MESSAGE_ID --from '"Support Bot" <user@example.com>' --body "Thanks"
-
-# Labels
 $GAPI gmail labels
 $GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
-$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
 ```
 
 ### Calendar
 
 ```bash
-# List events (defaults to next 7 days)
 $GAPI calendar list
-$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z
-
-# Create event (ISO 8601 with timezone required)
-$GAPI calendar create --summary "Team Standup" --start 2026-03-01T10:00:00-06:00 --end 2026-03-01T10:30:00-06:00
-$GAPI calendar create --summary "Lunch" --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z --location "Cafe"
-$GAPI calendar create --summary "Review" --start 2026-03-01T14:00:00Z --end 2026-03-01T15:00:00Z --attendees "alice@co.com,bob@co.com"
-
-# Delete event
+$GAPI calendar create --summary "Standup" --start 2026-03-01T10:00:00+01:00 --end 2026-03-01T10:30:00+01:00
+$GAPI calendar create --summary "Review" --start ... --end ... --attendees "alice@co.com,bob@co.com"
 $GAPI calendar delete EVENT_ID
 ```
 
@@ -224,13 +183,8 @@ $GAPI contacts list --max 20
 ### Sheets
 
 ```bash
-# Read
 $GAPI sheets get SHEET_ID "Sheet1!A1:D10"
-
-# Write
 $GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'
-
-# Append rows
 $GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
 ```
 
@@ -240,37 +194,52 @@ $GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
 $GAPI docs get DOC_ID
 ```
 
+### Direct gws access (advanced)
+
+For operations not covered by the wrapper, use `gws_bridge.py` directly:
+
+```bash
+GBRIDGE="$PYTHON_BIN $GWORKSPACE_SKILL_DIR/scripts/gws_bridge.py"
+$GBRIDGE calendar +agenda --today --format table
+$GBRIDGE gmail +triage --labels --format json
+$GBRIDGE drive +upload ./report.pdf
+$GBRIDGE sheets +read --spreadsheet SHEET_ID --range "Sheet1!A1:D10"
+```
+
 ## Output Format
 
-All commands return JSON. Parse with `jq` or read directly. Key fields:
+All commands return JSON via `gws --format json`. Key output shapes:
 
-- **Gmail search**: `[{id, threadId, from, to, subject, date, snippet, labels}]`
-- **Gmail get**: `{id, threadId, from, to, subject, date, labels, body}`
-- **Gmail send/reply**: `{status: "sent", id, threadId}`
-- **Calendar list**: `[{id, summary, start, end, location, description, htmlLink}]`
-- **Calendar create**: `{status: "created", id, summary, htmlLink}`
-- **Drive search**: `[{id, name, mimeType, modifiedTime, webViewLink}]`
-- **Contacts list**: `[{name, emails: [...], phones: [...]}]`
-- **Sheets get**: `[[cell, cell, ...], ...]`
+- **Gmail search/triage**: Array of message summaries (sender, subject, date, snippet)
+- **Gmail get/read**: Message object with headers and body text
+- **Gmail send/reply**: Confirmation with message ID
+- **Calendar list/agenda**: Array of event objects (summary, start, end, location)
+- **Calendar create**: Confirmation with event ID and htmlLink
+- **Drive search**: Array of file objects (id, name, mimeType, webViewLink)
+- **Sheets get/read**: 2D array of cell values
+- **Docs get**: Full document JSON (use `body.content` for text extraction)
+- **Contacts list**: Array of person objects with names, emails, phones
+
+Parse output with `jq` or read JSON directly.
 
 ## Rules
 
-1. **Never send email or create/delete events without confirming with the user first.** Show the draft content and ask for approval.
-2. **Check auth before first use** — run `setup.py --check`. If it fails, guide the user through setup.
-3. **Use the Gmail search syntax reference** for complex queries — load it with `skill_view("google-workspace", file_path="references/gmail-search-syntax.md")`.
-4. **Calendar times must include timezone** — always use ISO 8601 with offset (e.g., `2026-03-01T10:00:00-06:00`) or UTC (`Z`).
-5. **Respect rate limits** — avoid rapid-fire sequential API calls. Batch reads when possible.
+1. **Never send email or create/delete events without confirming with the user first.**
+2. **Check auth before first use** — run `setup.py --check`.
+3. **Use the Gmail search syntax reference** for complex queries.
+4. **Calendar times must include timezone** — ISO 8601 with offset or UTC.
+5. **Respect rate limits** — avoid rapid-fire sequential API calls.
 
 ## Troubleshooting
 
 | Problem | Fix |
 |---------|-----|
-| `NOT_AUTHENTICATED` | Run setup Steps 2-5 above |
-| `REFRESH_FAILED` | Token revoked or expired — redo Steps 3-5 |
-| `HttpError 403: Insufficient Permission` | Missing API scope — `$GSETUP --revoke` then redo Steps 3-5 |
-| `HttpError 403: Access Not Configured` | API not enabled — user needs to enable it in Google Cloud Console |
-| `ModuleNotFoundError` | Run `$GSETUP --install-deps` |
-| Advanced Protection blocks auth | Workspace admin must allowlist the OAuth client ID |
+| `NOT_AUTHENTICATED` | Run setup Steps 2-5 |
+| `REFRESH_FAILED` | Token revoked — redo Steps 3-5 |
+| `gws: command not found` | Install: `npm install -g @googleworkspace/cli` |
+| `HttpError 403` | Missing scope — `$GSETUP --revoke` then redo Steps 3-5 |
+| `HttpError 403: Access Not Configured` | Enable API in Google Cloud Console |
+| Advanced Protection blocks auth | Admin must allowlist the OAuth client ID |
 
 ## Revoking Access
 

skills/productivity/google-workspace/scripts/google_api.py

@@ -1,17 +1,17 @@
 #!/usr/bin/env python3
 """Google Workspace API CLI for Hermes Agent.
 
-Uses the Google Workspace CLI (`gws`) when available, but preserves the
-existing Hermes-facing JSON contract and falls back to the Python client
-libraries if `gws` is not installed.
+Thin wrapper that delegates to gws (googleworkspace/cli) via gws_bridge.py.
+Maintains the same CLI interface for backward compatibility with Hermes skills.
 
 Usage:
   python google_api.py gmail search "is:unread" [--max 10]
   python google_api.py gmail get MESSAGE_ID
   python google_api.py gmail send --to user@example.com --subject "Hi" --body "Hello"
   python google_api.py gmail reply MESSAGE_ID --body "Thanks"
-  python google_api.py calendar list [--from DATE] [--to DATE] [--calendar primary]
+  python google_api.py calendar list [--start DATE] [--end DATE] [--calendar primary]
   python google_api.py calendar create --summary "Meeting" --start DATETIME --end DATETIME
+  python google_api.py calendar delete EVENT_ID
   python google_api.py drive search "budget report" [--max 10]
   python google_api.py contacts list [--max 20]
   python google_api.py sheets get SHEET_ID RANGE
@@ -21,396 +21,47 @@ Usage:
 """
 
 import argparse
-import base64
 import json
 import os
-import shutil
 import subprocess
 import sys
-from datetime import datetime, timedelta, timezone
-from email.mime.text import MIMEText
 from pathlib import Path
 
-HERMES_HOME = Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
-TOKEN_PATH = HERMES_HOME / "google_token.json"
-CLIENT_SECRET_PATH = HERMES_HOME / "google_client_secret.json"
-
-SCOPES = [
-    "https://www.googleapis.com/auth/gmail.readonly",
-    "https://www.googleapis.com/auth/gmail.send",
-    "https://www.googleapis.com/auth/gmail.modify",
-    "https://www.googleapis.com/auth/calendar",
-    "https://www.googleapis.com/auth/drive.readonly",
-    "https://www.googleapis.com/auth/contacts.readonly",
-    "https://www.googleapis.com/auth/spreadsheets",
-    "https://www.googleapis.com/auth/documents.readonly",
-]
+BRIDGE = Path(__file__).parent / "gws_bridge.py"
+PYTHON = sys.executable
 
 
-def _ensure_authenticated():
-    if not TOKEN_PATH.exists():
-        print("Not authenticated. Run the setup script first:", file=sys.stderr)
-        print(f"  python {Path(__file__).parent / 'setup.py'}", file=sys.stderr)
-        sys.exit(1)
-
-
-def _stored_token_scopes() -> list[str]:
-    try:
-        data = json.loads(TOKEN_PATH.read_text())
-    except Exception:
-        return list(SCOPES)
-    scopes = data.get("scopes")
-    if isinstance(scopes, list) and scopes:
-        return scopes
-    return list(SCOPES)
-
-
-def _gws_binary() -> str | None:
-    override = os.getenv("HERMES_GWS_BIN")
-    if override:
-        return override
-    return shutil.which("gws")
-
-
-def _gws_env() -> dict[str, str]:
-    env = os.environ.copy()
-    env["GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE"] = str(TOKEN_PATH)
-    return env
-
-
-def _run_gws(parts: list[str], *, params: dict | None = None, body: dict | None = None):
-    binary = _gws_binary()
-    if not binary:
-        raise RuntimeError("gws not installed")
-
-    _ensure_authenticated()
-
-    cmd = [binary, *parts]
-    if params is not None:
-        cmd.extend(["--params", json.dumps(params)])
-    if body is not None:
-        cmd.extend(["--json", json.dumps(body)])
-
+def gws(*args: str) -> None:
+    """Call gws via the bridge and exit with its return code."""
     result = subprocess.run(
-        cmd,
-        capture_output=True,
-        text=True,
-        env=_gws_env(),
+        [PYTHON, str(BRIDGE)] + list(args),
+        env={**os.environ, "HERMES_HOME": os.environ.get("HERMES_HOME", str(Path.home() / ".hermes"))},
     )
-    if result.returncode != 0:
-        err = result.stderr.strip() or result.stdout.strip() or "Unknown gws error"
-        print(err, file=sys.stderr)
-        sys.exit(result.returncode or 1)
-
-    stdout = result.stdout.strip()
-    if not stdout:
-        return {}
-
-    try:
-        return json.loads(stdout)
-    except json.JSONDecodeError:
-        print("ERROR: Unexpected non-JSON output from gws:", file=sys.stderr)
-        print(stdout, file=sys.stderr)
-        sys.exit(1)
+    sys.exit(result.returncode)
 
 
-def _headers_dict(msg: dict) -> dict[str, str]:
-    return {h["name"]: h["value"] for h in msg.get("payload", {}).get("headers", [])}
-
-
-def _extract_message_body(msg: dict) -> str:
-    body = ""
-    payload = msg.get("payload", {})
-    if payload.get("body", {}).get("data"):
-        body = base64.urlsafe_b64decode(payload["body"]["data"]).decode("utf-8", errors="replace")
-    elif payload.get("parts"):
-        for part in payload["parts"]:
-            if part.get("mimeType") == "text/plain" and part.get("body", {}).get("data"):
-                body = base64.urlsafe_b64decode(part["body"]["data"]).decode("utf-8", errors="replace")
-                break
-        if not body:
-            for part in payload["parts"]:
-                if part.get("mimeType") == "text/html" and part.get("body", {}).get("data"):
-                    body = base64.urlsafe_b64decode(part["body"]["data"]).decode("utf-8", errors="replace")
-                    break
-    return body
-
-
-def _extract_doc_text(doc: dict) -> str:
-    text_parts = []
-    for element in doc.get("body", {}).get("content", []):
-        paragraph = element.get("paragraph", {})
-        for pe in paragraph.get("elements", []):
-            text_run = pe.get("textRun", {})
-            if text_run.get("content"):
-                text_parts.append(text_run["content"])
-    return "".join(text_parts)
-
-
-def _datetime_with_timezone(value: str) -> str:
-    if not value:
-        return value
-    if "T" not in value:
-        return value
-    if value.endswith("Z"):
-        return value
-    tail = value[10:]
-    if "+" in tail or "-" in tail:
-        return value
-    return value + "Z"
-
-
-def get_credentials():
-    """Load and refresh credentials from token file."""
-    _ensure_authenticated()
-
-    from google.oauth2.credentials import Credentials
-    from google.auth.transport.requests import Request
-
-    creds = Credentials.from_authorized_user_file(str(TOKEN_PATH), _stored_token_scopes())
-    if creds.expired and creds.refresh_token:
-        creds.refresh(Request())
-        TOKEN_PATH.write_text(creds.to_json())
-    if not creds.valid:
-        print("Token is invalid. Re-run setup.", file=sys.stderr)
-        sys.exit(1)
-    return creds
-
-
-def build_service(api, version):
-    from googleapiclient.discovery import build
-
-    return build(api, version, credentials=get_credentials())
-
-
-# =========================================================================
-# Gmail
-# =========================================================================
-
+# -- Gmail --
 
 def gmail_search(args):
-    if _gws_binary():
-        results = _run_gws(
-            ["gmail", "users", "messages", "list"],
-            params={"userId": "me", "q": args.query, "maxResults": args.max},
-        )
-        messages = results.get("messages", [])
-        output = []
-        for msg_meta in messages:
-            msg = _run_gws(
-                ["gmail", "users", "messages", "get"],
-                params={
-                    "userId": "me",
-                    "id": msg_meta["id"],
-                    "format": "metadata",
-                    "metadataHeaders": ["From", "To", "Subject", "Date"],
-                },
-            )
-            headers = _headers_dict(msg)
-            output.append(
-                {
-                    "id": msg["id"],
-                    "threadId": msg["threadId"],
-                    "from": headers.get("From", ""),
-                    "to": headers.get("To", ""),
-                    "subject": headers.get("Subject", ""),
-                    "date": headers.get("Date", ""),
-                    "snippet": msg.get("snippet", ""),
-                    "labels": msg.get("labelIds", []),
-                }
-            )
-        print(json.dumps(output, indent=2, ensure_ascii=False))
-        return
-
-    service = build_service("gmail", "v1")
-    results = service.users().messages().list(
-        userId="me", q=args.query, maxResults=args.max
-    ).execute()
-    messages = results.get("messages", [])
-    if not messages:
-        print("No messages found.")
-        return
-
-    output = []
-    for msg_meta in messages:
-        msg = service.users().messages().get(
-            userId="me", id=msg_meta["id"], format="metadata",
-            metadataHeaders=["From", "To", "Subject", "Date"],
-        ).execute()
-        headers = _headers_dict(msg)
-        output.append({
-            "id": msg["id"],
-            "threadId": msg["threadId"],
-            "from": headers.get("From", ""),
-            "to": headers.get("To", ""),
-            "subject": headers.get("Subject", ""),
-            "date": headers.get("Date", ""),
-            "snippet": msg.get("snippet", ""),
-            "labels": msg.get("labelIds", []),
-        })
-    print(json.dumps(output, indent=2, ensure_ascii=False))
-
-
+    cmd = ["gmail", "+triage", "--query", args.query, "--max", str(args.max), "--format", "json"]
+    gws(*cmd)
 
 def gmail_get(args):
-    if _gws_binary():
-        msg = _run_gws(
-            ["gmail", "users", "messages", "get"],
-            params={"userId": "me", "id": args.message_id, "format": "full"},
-        )
-        headers = _headers_dict(msg)
-        result = {
-            "id": msg["id"],
-            "threadId": msg["threadId"],
-            "from": headers.get("From", ""),
-            "to": headers.get("To", ""),
-            "subject": headers.get("Subject", ""),
-            "date": headers.get("Date", ""),
-            "labels": msg.get("labelIds", []),
-            "body": _extract_message_body(msg),
-        }
-        print(json.dumps(result, indent=2, ensure_ascii=False))
-        return
-
-    service = build_service("gmail", "v1")
-    msg = service.users().messages().get(
-        userId="me", id=args.message_id, format="full"
-    ).execute()
-
-    headers = _headers_dict(msg)
-    result = {
-        "id": msg["id"],
-        "threadId": msg["threadId"],
-        "from": headers.get("From", ""),
-        "to": headers.get("To", ""),
-        "subject": headers.get("Subject", ""),
-        "date": headers.get("Date", ""),
-        "labels": msg.get("labelIds", []),
-        "body": _extract_message_body(msg),
-    }
-    print(json.dumps(result, indent=2, ensure_ascii=False))
-
-
+    gws("gmail", "+read", "--id", args.message_id, "--headers", "--format", "json")
 
 def gmail_send(args):
-    if _gws_binary():
-        message = MIMEText(args.body, "html" if args.html else "plain")
-        message["to"] = args.to
-        message["subject"] = args.subject
-        if args.cc:
-            message["cc"] = args.cc
-        if args.from_header:
-            message["from"] = args.from_header
-
-        raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
-        body = {"raw": raw}
-        if args.thread_id:
-            body["threadId"] = args.thread_id
-
-        result = _run_gws(
-            ["gmail", "users", "messages", "send"],
-            params={"userId": "me"},
-            body=body,
-        )
-        print(json.dumps({"status": "sent", "id": result["id"], "threadId": result.get("threadId", "")}, indent=2))
-        return
-
-    service = build_service("gmail", "v1")
-    message = MIMEText(args.body, "html" if args.html else "plain")
-    message["to"] = args.to
-    message["subject"] = args.subject
+    cmd = ["gmail", "+send", "--to", args.to, "--subject", args.subject, "--body", args.body, "--format", "json"]
     if args.cc:
-        message["cc"] = args.cc
-    if args.from_header:
-        message["from"] = args.from_header
-
-    raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
-    body = {"raw": raw}
-
-    if args.thread_id:
-        body["threadId"] = args.thread_id
-
-    result = service.users().messages().send(userId="me", body=body).execute()
-    print(json.dumps({"status": "sent", "id": result["id"], "threadId": result.get("threadId", "")}, indent=2))
-
-
+        cmd += ["--cc", args.cc]
+    if args.html:
+        cmd.append("--html")
+    gws(*cmd)
 
 def gmail_reply(args):
-    if _gws_binary():
-        original = _run_gws(
-            ["gmail", "users", "messages", "get"],
-            params={
-                "userId": "me",
-                "id": args.message_id,
-                "format": "metadata",
-                "metadataHeaders": ["From", "Subject", "Message-ID"],
-            },
-        )
-        headers = _headers_dict(original)
-
-        subject = headers.get("Subject", "")
-        if not subject.startswith("Re:"):
-            subject = f"Re: {subject}"
-
-        message = MIMEText(args.body)
-        message["to"] = headers.get("From", "")
-        message["subject"] = subject
-        if args.from_header:
-            message["from"] = args.from_header
-        if headers.get("Message-ID"):
-            message["In-Reply-To"] = headers["Message-ID"]
-            message["References"] = headers["Message-ID"]
-
-        raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
-        result = _run_gws(
-            ["gmail", "users", "messages", "send"],
-            params={"userId": "me"},
-            body={"raw": raw, "threadId": original["threadId"]},
-        )
-        print(json.dumps({"status": "sent", "id": result["id"], "threadId": result.get("threadId", "")}, indent=2))
-        return
-
-    service = build_service("gmail", "v1")
-    original = service.users().messages().get(
-        userId="me", id=args.message_id, format="metadata",
-        metadataHeaders=["From", "Subject", "Message-ID"],
-    ).execute()
-    headers = _headers_dict(original)
-
-    subject = headers.get("Subject", "")
-    if not subject.startswith("Re:"):
-        subject = f"Re: {subject}"
-
-    message = MIMEText(args.body)
-    message["to"] = headers.get("From", "")
-    message["subject"] = subject
-    if args.from_header:
-        message["from"] = args.from_header
-    if headers.get("Message-ID"):
-        message["In-Reply-To"] = headers["Message-ID"]
-        message["References"] = headers["Message-ID"]
-
-    raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
-    body = {"raw": raw, "threadId": original["threadId"]}
-
-    result = service.users().messages().send(userId="me", body=body).execute()
-    print(json.dumps({"status": "sent", "id": result["id"], "threadId": result.get("threadId", "")}, indent=2))
-
-
+    gws("gmail", "+reply", "--message-id", args.message_id, "--body", args.body, "--format", "json")
 
 def gmail_labels(args):
-    if _gws_binary():
-        results = _run_gws(["gmail", "users", "labels", "list"], params={"userId": "me"})
-        labels = [{"id": l["id"], "name": l["name"], "type": l.get("type", "")} for l in results.get("labels", [])]
-        print(json.dumps(labels, indent=2))
-        return
-
-    service = build_service("gmail", "v1")
-    results = service.users().labels().list(userId="me").execute()
-    labels = [{"id": l["id"], "name": l["name"], "type": l.get("type", "")} for l in results.get("labels", [])]
-    print(json.dumps(labels, indent=2))
-
-
+    gws("gmail", "users", "labels", "list", "--params", json.dumps({"userId": "me"}), "--format", "json")
 
 def gmail_modify(args):
     body = {}
@@ -418,310 +69,145 @@ def gmail_modify(args):
         body["addLabelIds"] = args.add_labels.split(",")
     if args.remove_labels:
         body["removeLabelIds"] = args.remove_labels.split(",")
-
-    if _gws_binary():
-        result = _run_gws(
-            ["gmail", "users", "messages", "modify"],
-            params={"userId": "me", "id": args.message_id},
-            body=body,
-        )
-        print(json.dumps({"id": result["id"], "labels": result.get("labelIds", [])}, indent=2))
-        return
-
-    service = build_service("gmail", "v1")
-    result = service.users().messages().modify(userId="me", id=args.message_id, body=body).execute()
-    print(json.dumps({"id": result["id"], "labels": result.get("labelIds", [])}, indent=2))
+    gws(
+        "gmail", "users", "messages", "modify",
+        "--params", json.dumps({"userId": "me", "id": args.message_id}),
+        "--json", json.dumps(body),
+        "--format", "json",
+    )
 
 
-# =========================================================================
-# Calendar
-# =========================================================================
-
+# -- Calendar --
 
 def calendar_list(args):
-    now = datetime.now(timezone.utc)
-    time_min = _datetime_with_timezone(args.start or now.isoformat())
-    time_max = _datetime_with_timezone(args.end or (now + timedelta(days=7)).isoformat())
-
-    if _gws_binary():
-        results = _run_gws(
-            ["calendar", "events", "list"],
-            params={
+    if args.start or args.end:
+        # Specific date range — use raw Calendar API for precise timeMin/timeMax
+        from datetime import datetime, timedelta, timezone as tz
+        now = datetime.now(tz.utc)
+        time_min = args.start or now.isoformat()
+        time_max = args.end or (now + timedelta(days=7)).isoformat()
+        gws(
+            "calendar", "events", "list",
+            "--params", json.dumps({
                 "calendarId": args.calendar,
                 "timeMin": time_min,
                 "timeMax": time_max,
                 "maxResults": args.max,
                 "singleEvents": True,
                 "orderBy": "startTime",
-            },
+            }),
+            "--format", "json",
         )
-        events = []
-        for e in results.get("items", []):
-            events.append({
-                "id": e["id"],
-                "summary": e.get("summary", "(no title)"),
-                "start": e.get("start", {}).get("dateTime", e.get("start", {}).get("date", "")),
-                "end": e.get("end", {}).get("dateTime", e.get("end", {}).get("date", "")),
-                "location": e.get("location", ""),
-                "description": e.get("description", ""),
-                "status": e.get("status", ""),
-                "htmlLink": e.get("htmlLink", ""),
-            })
-        print(json.dumps(events, indent=2, ensure_ascii=False))
-        return
-
-    service = build_service("calendar", "v3")
-    results = service.events().list(
-        calendarId=args.calendar, timeMin=time_min, timeMax=time_max,
-        maxResults=args.max, singleEvents=True, orderBy="startTime",
-    ).execute()
-
-    events = []
-    for e in results.get("items", []):
-        events.append({
-            "id": e["id"],
-            "summary": e.get("summary", "(no title)"),
-            "start": e.get("start", {}).get("dateTime", e.get("start", {}).get("date", "")),
-            "end": e.get("end", {}).get("dateTime", e.get("end", {}).get("date", "")),
-            "location": e.get("location", ""),
-            "description": e.get("description", ""),
-            "status": e.get("status", ""),
-            "htmlLink": e.get("htmlLink", ""),
-        })
-    print(json.dumps(events, indent=2, ensure_ascii=False))
-
-
+    else:
+        # No date range — use +agenda helper (defaults to 7 days)
+        cmd = ["calendar", "+agenda", "--days", "7", "--format", "json"]
+        if args.calendar != "primary":
+            cmd += ["--calendar", args.calendar]
+        gws(*cmd)
 
 def calendar_create(args):
-    event = {
-        "summary": args.summary,
-        "start": {"dateTime": args.start},
-        "end": {"dateTime": args.end},
-    }
+    cmd = [
+        "calendar", "+insert",
+        "--summary", args.summary,
+        "--start", args.start,
+        "--end", args.end,
+        "--format", "json",
+    ]
     if args.location:
-        event["location"] = args.location
+        cmd += ["--location", args.location]
     if args.description:
-        event["description"] = args.description
+        cmd += ["--description", args.description]
     if args.attendees:
-        event["attendees"] = [{"email": e.strip()} for e in args.attendees.split(",") if e.strip()]
-
-    if _gws_binary():
-        result = _run_gws(
-            ["calendar", "events", "insert"],
-            params={"calendarId": args.calendar},
-            body=event,
-        )
-        print(json.dumps({
-            "status": "created",
-            "id": result["id"],
-            "summary": result.get("summary", ""),
-            "htmlLink": result.get("htmlLink", ""),
-        }, indent=2))
-        return
-
-    service = build_service("calendar", "v3")
-    result = service.events().insert(calendarId=args.calendar, body=event).execute()
-    print(json.dumps({
-        "status": "created",
-        "id": result["id"],
-        "summary": result.get("summary", ""),
-        "htmlLink": result.get("htmlLink", ""),
-    }, indent=2))
-
-
+        for email in args.attendees.split(","):
+            cmd += ["--attendee", email.strip()]
+    if args.calendar != "primary":
+        cmd += ["--calendar", args.calendar]
+    gws(*cmd)
 
 def calendar_delete(args):
-    if _gws_binary():
-        _run_gws(["calendar", "events", "delete"], params={"calendarId": args.calendar, "eventId": args.event_id})
-        print(json.dumps({"status": "deleted", "eventId": args.event_id}))
-        return
-
-    service = build_service("calendar", "v3")
-    service.events().delete(calendarId=args.calendar, eventId=args.event_id).execute()
-    print(json.dumps({"status": "deleted", "eventId": args.event_id}))
+    gws(
+        "calendar", "events", "delete",
+        "--params", json.dumps({"calendarId": args.calendar, "eventId": args.event_id}),
+        "--format", "json",
+    )
 
 
-# =========================================================================
-# Drive
-# =========================================================================
-
+# -- Drive --
 
 def drive_search(args):
     query = args.query if args.raw_query else f"fullText contains '{args.query}'"
-    if _gws_binary():
-        results = _run_gws(
-            ["drive", "files", "list"],
-            params={
-                "q": query,
-                "pageSize": args.max,
-                "fields": "files(id, name, mimeType, modifiedTime, webViewLink)",
-            },
-        )
-        print(json.dumps(results.get("files", []), indent=2, ensure_ascii=False))
-        return
-
-    service = build_service("drive", "v3")
-    results = service.files().list(
-        q=query, pageSize=args.max, fields="files(id, name, mimeType, modifiedTime, webViewLink)",
-    ).execute()
-    files = results.get("files", [])
-    print(json.dumps(files, indent=2, ensure_ascii=False))
+    gws(
+        "drive", "files", "list",
+        "--params", json.dumps({
+            "q": query,
+            "pageSize": args.max,
+            "fields": "files(id,name,mimeType,modifiedTime,webViewLink)",
+        }),
+        "--format", "json",
+    )
 
 
-# =========================================================================
-# Contacts
-# =========================================================================
-
+# -- Contacts --
 
 def contacts_list(args):
-    if _gws_binary():
-        results = _run_gws(
-            ["people", "people", "connections", "list"],
-            params={
-                "resourceName": "people/me",
-                "pageSize": args.max,
-                "personFields": "names,emailAddresses,phoneNumbers",
-            },
-        )
-        contacts = []
-        for person in results.get("connections", []):
-            names = person.get("names", [{}])
-            emails = person.get("emailAddresses", [])
-            phones = person.get("phoneNumbers", [])
-            contacts.append({
-                "name": names[0].get("displayName", "") if names else "",
-                "emails": [e.get("value", "") for e in emails],
-                "phones": [p.get("value", "") for p in phones],
-            })
-        print(json.dumps(contacts, indent=2, ensure_ascii=False))
-        return
-
-    service = build_service("people", "v1")
-    results = service.people().connections().list(
-        resourceName="people/me",
-        pageSize=args.max,
-        personFields="names,emailAddresses,phoneNumbers",
-    ).execute()
-    contacts = []
-    for person in results.get("connections", []):
-        names = person.get("names", [{}])
-        emails = person.get("emailAddresses", [])
-        phones = person.get("phoneNumbers", [])
-        contacts.append({
-            "name": names[0].get("displayName", "") if names else "",
-            "emails": [e.get("value", "") for e in emails],
-            "phones": [p.get("value", "") for p in phones],
-        })
-    print(json.dumps(contacts, indent=2, ensure_ascii=False))
+    gws(
+        "people", "people", "connections", "list",
+        "--params", json.dumps({
+            "resourceName": "people/me",
+            "pageSize": args.max,
+            "personFields": "names,emailAddresses,phoneNumbers",
+        }),
+        "--format", "json",
+    )
 
 
-# =========================================================================
-# Sheets
-# =========================================================================
-
+# -- Sheets --
 
 def sheets_get(args):
-    if _gws_binary():
-        result = _run_gws(
-            ["sheets", "spreadsheets", "values", "get"],
-            params={"spreadsheetId": args.sheet_id, "range": args.range},
-        )
-        print(json.dumps(result.get("values", []), indent=2, ensure_ascii=False))
-        return
-
-    service = build_service("sheets", "v4")
-    result = service.spreadsheets().values().get(
-        spreadsheetId=args.sheet_id, range=args.range,
-    ).execute()
-    print(json.dumps(result.get("values", []), indent=2, ensure_ascii=False))
-
-
+    gws(
+        "sheets", "+read",
+        "--spreadsheet", args.sheet_id,
+        "--range", args.range,
+        "--format", "json",
+    )
 
 def sheets_update(args):
     values = json.loads(args.values)
-    body = {"values": values}
-
-    if _gws_binary():
-        result = _run_gws(
-            ["sheets", "spreadsheets", "values", "update"],
-            params={
-                "spreadsheetId": args.sheet_id,
-                "range": args.range,
-                "valueInputOption": "USER_ENTERED",
-            },
-            body=body,
-        )
-        print(json.dumps({"updatedCells": result.get("updatedCells", 0), "updatedRange": result.get("updatedRange", "")}, indent=2))
-        return
-
-    service = build_service("sheets", "v4")
-    result = service.spreadsheets().values().update(
-        spreadsheetId=args.sheet_id, range=args.range,
-        valueInputOption="USER_ENTERED", body=body,
-    ).execute()
-    print(json.dumps({"updatedCells": result.get("updatedCells", 0), "updatedRange": result.get("updatedRange", "")}, indent=2))
-
-
+    gws(
+        "sheets", "spreadsheets", "values", "update",
+        "--params", json.dumps({
+            "spreadsheetId": args.sheet_id,
+            "range": args.range,
+            "valueInputOption": "USER_ENTERED",
+        }),
+        "--json", json.dumps({"values": values}),
+        "--format", "json",
+    )
 
 def sheets_append(args):
     values = json.loads(args.values)
-    body = {"values": values}
-
-    if _gws_binary():
-        result = _run_gws(
-            ["sheets", "spreadsheets", "values", "append"],
-            params={
-                "spreadsheetId": args.sheet_id,
-                "range": args.range,
-                "valueInputOption": "USER_ENTERED",
-                "insertDataOption": "INSERT_ROWS",
-            },
-            body=body,
-        )
-        print(json.dumps({"updatedCells": result.get("updates", {}).get("updatedCells", 0)}, indent=2))
-        return
-
-    service = build_service("sheets", "v4")
-    result = service.spreadsheets().values().append(
-        spreadsheetId=args.sheet_id, range=args.range,
-        valueInputOption="USER_ENTERED", insertDataOption="INSERT_ROWS", body=body,
-    ).execute()
-    print(json.dumps({"updatedCells": result.get("updates", {}).get("updatedCells", 0)}, indent=2))
+    gws(
+        "sheets", "+append",
+        "--spreadsheet", args.sheet_id,
+        "--json-values", json.dumps(values),
+        "--format", "json",
+    )
 
 
-# =========================================================================
-# Docs
-# =========================================================================
-
+# -- Docs --
 
 def docs_get(args):
-    if _gws_binary():
-        doc = _run_gws(["docs", "documents", "get"], params={"documentId": args.doc_id})
-        result = {
-            "title": doc.get("title", ""),
-            "documentId": doc.get("documentId", ""),
-            "body": _extract_doc_text(doc),
-        }
-        print(json.dumps(result, indent=2, ensure_ascii=False))
-        return
-
-    service = build_service("docs", "v1")
-    doc = service.documents().get(documentId=args.doc_id).execute()
-    result = {
-        "title": doc.get("title", ""),
-        "documentId": doc.get("documentId", ""),
-        "body": _extract_doc_text(doc),
-    }
-    print(json.dumps(result, indent=2, ensure_ascii=False))
+    gws(
+        "docs", "documents", "get",
+        "--params", json.dumps({"documentId": args.doc_id}),
+        "--format", "json",
+    )
 
 
-# =========================================================================
-# CLI parser
-# =========================================================================
-
+# -- CLI parser (backward-compatible interface) --
 
 def main():
-    parser = argparse.ArgumentParser(description="Google Workspace API for Hermes Agent")
+    parser = argparse.ArgumentParser(description="Google Workspace API for Hermes Agent (gws backend)")
     sub = parser.add_subparsers(dest="service", required=True)
 
     # --- Gmail ---
@@ -742,15 +228,13 @@ def main():
     p.add_argument("--subject", required=True)
     p.add_argument("--body", required=True)
     p.add_argument("--cc", default="")
-    p.add_argument("--from", dest="from_header", default="", help="Custom From header (e.g. '\"Agent Name\" <user@example.com>')")
     p.add_argument("--html", action="store_true", help="Send body as HTML")
-    p.add_argument("--thread-id", default="", help="Thread ID for threading")
+    p.add_argument("--thread-id", default="", help="Thread ID (unused with gws, kept for compat)")
     p.set_defaults(func=gmail_send)
 
     p = gmail_sub.add_parser("reply")
     p.add_argument("message_id", help="Message ID to reply to")
     p.add_argument("--body", required=True)
-    p.add_argument("--from", dest="from_header", default="", help="Custom From header (e.g. '\"Agent Name\" <user@example.com>')")
     p.set_defaults(func=gmail_reply)
 
     p = gmail_sub.add_parser("labels")

tests/gateway/test_auto_continue.py

@@ -1,95 +0,0 @@
-"""Tests for the auto-continue feature (#4493).
-
-When the gateway restarts mid-agent-work, the session transcript ends on a
-tool result that the agent never processed.  The auto-continue logic detects
-this and prepends a system note to the next user message so the model
-finishes the interrupted work before addressing the new input.
-"""
-
-import pytest
-
-
-def _simulate_auto_continue(agent_history: list, user_message: str) -> str:
-    """Reproduce the auto-continue injection logic from _run_agent().
-
-    This mirrors the exact code in gateway/run.py so we can test the
-    detection and message transformation without spinning up a full
-    gateway runner.
-    """
-    message = user_message
-    if agent_history and agent_history[-1].get("role") == "tool":
-        message = (
-            "[System note: Your previous turn was interrupted before you could "
-            "process the last tool result(s). The conversation history contains "
-            "tool outputs you haven't responded to yet. Please finish processing "
-            "those results and summarize what was accomplished, then address the "
-            "user's new message below.]\n\n"
-            + message
-        )
-    return message
-
-
-class TestAutoDetection:
-    """Test that trailing tool results are correctly detected."""
-
-    def test_trailing_tool_result_triggers_note(self):
-        history = [
-            {"role": "user", "content": "deploy the app"},
-            {"role": "assistant", "content": None, "tool_calls": [
-                {"id": "call_1", "function": {"name": "terminal", "arguments": "{}"}}
-            ]},
-            {"role": "tool", "tool_call_id": "call_1", "content": "deployed successfully"},
-        ]
-        result = _simulate_auto_continue(history, "what happened?")
-        assert "[System note:" in result
-        assert "interrupted" in result
-        assert "what happened?" in result
-
-    def test_trailing_assistant_message_no_note(self):
-        history = [
-            {"role": "user", "content": "hello"},
-            {"role": "assistant", "content": "Hi there!"},
-        ]
-        result = _simulate_auto_continue(history, "how are you?")
-        assert "[System note:" not in result
-        assert result == "how are you?"
-
-    def test_empty_history_no_note(self):
-        result = _simulate_auto_continue([], "hello")
-        assert result == "hello"
-
-    def test_trailing_user_message_no_note(self):
-        """Shouldn't happen in practice, but ensure no false positive."""
-        history = [
-            {"role": "user", "content": "hello"},
-        ]
-        result = _simulate_auto_continue(history, "hello again")
-        assert result == "hello again"
-
-    def test_multiple_tool_results_still_triggers(self):
-        """Multiple tool calls in a row — last one is still role=tool."""
-        history = [
-            {"role": "user", "content": "search and read"},
-            {"role": "assistant", "content": None, "tool_calls": [
-                {"id": "call_1", "function": {"name": "search", "arguments": "{}"}},
-                {"id": "call_2", "function": {"name": "read", "arguments": "{}"}},
-            ]},
-            {"role": "tool", "tool_call_id": "call_1", "content": "found it"},
-            {"role": "tool", "tool_call_id": "call_2", "content": "file content here"},
-        ]
-        result = _simulate_auto_continue(history, "continue")
-        assert "[System note:" in result
-
-    def test_original_message_preserved_after_note(self):
-        """The user's actual message must appear after the system note."""
-        history = [
-            {"role": "assistant", "content": None, "tool_calls": [
-                {"id": "c1", "function": {"name": "t", "arguments": "{}"}}
-            ]},
-            {"role": "tool", "tool_call_id": "c1", "content": "done"},
-        ]
-        result = _simulate_auto_continue(history, "now do X")
-        # System note comes first, then user's message
-        note_end = result.index("]\n\n")
-        user_msg_start = result.index("now do X")
-        assert user_msg_start > note_end

tests/gateway/test_discord_slash_commands.py

@@ -117,23 +117,6 @@ async def test_registers_native_thread_slash_command(adapter):
     adapter._handle_thread_create_slash.assert_awaited_once_with(interaction, "Planning", "", 1440)
 
 
-@pytest.mark.asyncio
-async def test_registers_native_restart_slash_command(adapter):
-    adapter._run_simple_slash = AsyncMock()
-    adapter._register_slash_commands()
-
-    assert "restart" in adapter._client.tree.commands
-
-    interaction = SimpleNamespace()
-    await adapter._client.tree.commands["restart"](interaction)
-
-    adapter._run_simple_slash.assert_awaited_once_with(
-        interaction,
-        "/restart",
-        "Restart requested~",
-    )
-
-
 # ------------------------------------------------------------------
 # _handle_thread_create_slash — success, session dispatch, failure
 # ------------------------------------------------------------------

tests/gateway/test_gateway_shutdown.py

@@ -125,6 +125,25 @@ async def test_gateway_stop_service_restart_sets_named_exit_code():
     assert runner._exit_code == GATEWAY_SERVICE_RESTART_EXIT_CODE
 
 
+@pytest.mark.asyncio
+async def test_gateway_stop_emits_shutdown_hook_after_drain(monkeypatch):
+    runner, adapter = make_restart_runner()
+    adapter.disconnect = AsyncMock()
+    runner.hooks.emit = AsyncMock()
+
+    with patch("gateway.status.remove_pid_file"), patch("gateway.status.write_runtime_status"):
+        await runner.stop(restart=True, service_restart=True)
+
+    runner.hooks.emit.assert_awaited_once_with(
+        "gateway:shutdown",
+        {
+            "restart": True,
+            "service_restart": True,
+            "detached_restart": False,
+        },
+    )
+
+
 @pytest.mark.asyncio
 async def test_drain_active_agents_throttles_status_updates():
     runner, _adapter = make_restart_runner()

tests/gateway/test_hooks.py

@@ -9,7 +9,7 @@ import pytest
 from gateway.hooks import HookRegistry
 
 
-def _create_hook(hooks_dir, hook_name, events, handler_code):
+def _create_hook(hooks_dir, hook_name, events, handler_code, *, manifest_extra=""):
     """Helper to create a hook directory with HOOK.yaml and handler.py."""
     hook_dir = hooks_dir / hook_name
     hook_dir.mkdir(parents=True)
@@ -17,6 +17,7 @@ def _create_hook(hooks_dir, hook_name, events, handler_code):
         f"name: {hook_name}\n"
         f"description: Test hook\n"
         f"events: {events}\n"
+        f"{manifest_extra}"
     )
     (hook_dir / "handler.py").write_text(handler_code)
     return hook_dir
@@ -112,6 +113,24 @@ class TestDiscoverAndLoad:
 
         assert len(reg.loaded_hooks) == 2
 
+    def test_preserves_optional_startup_readiness_metadata(self, tmp_path):
+        _create_hook(
+            tmp_path,
+            "ready-hook",
+            '["gateway:startup"]',
+            "def handle(e, c): pass\n",
+            manifest_extra="startup_readiness:\n  id: beam-runtime\n  required: false\n",
+        )
+
+        reg = HookRegistry()
+        with patch("gateway.hooks.HOOKS_DIR", tmp_path), _patch_no_builtins(reg):
+            reg.discover_and_load()
+
+        assert reg.loaded_hooks[0]["startup_readiness"] == {
+            "id": "beam-runtime",
+            "required": False,
+        }
+
 
 class TestEmit:
     @pytest.mark.asyncio

tests/gateway/test_restart_drain.py

@@ -193,7 +193,7 @@ async def test_shutdown_notification_says_restarting_when_restart_requested():
 
     assert len(adapter.sent) == 1
     assert "restarting" in adapter.sent[0]
-    assert "resume" in adapter.sent[0]
+    assert "/retry" in adapter.sent[0]
 
 
 @pytest.mark.asyncio

tests/gateway/test_runner_startup_failures.py

@@ -132,6 +132,68 @@ async def test_runner_records_connected_platform_state_on_success(monkeypatch, t
     assert state["platforms"]["discord"]["error_message"] is None
 
 
+@pytest.mark.asyncio
+async def test_runner_discovers_plugins_before_loading_hooks(monkeypatch, tmp_path):
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    config = GatewayConfig(
+        platforms={
+            Platform.DISCORD: PlatformConfig(enabled=True, token="***")
+        },
+        sessions_dir=tmp_path / "sessions",
+    )
+    runner = GatewayRunner(config)
+    order: list[str] = []
+
+    monkeypatch.setattr(runner, "_create_adapter", lambda platform, platform_config: _SuccessfulAdapter())
+    monkeypatch.setattr("hermes_cli.plugins.discover_plugins", lambda: order.append("plugins"))
+    monkeypatch.setattr(runner.hooks, "discover_and_load", lambda: order.append("hooks"))
+    monkeypatch.setattr(runner.hooks, "emit", AsyncMock())
+
+    ok = await runner.start()
+
+    assert ok is True
+    assert order == ["plugins", "hooks"]
+
+
+@pytest.mark.asyncio
+async def test_runner_initializes_startup_checks_before_gateway_startup_emit(monkeypatch, tmp_path):
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    config = GatewayConfig(
+        platforms={
+            Platform.DISCORD: PlatformConfig(enabled=True, token="***")
+        },
+        sessions_dir=tmp_path / "sessions",
+    )
+    runner = GatewayRunner(config)
+
+    runner.hooks._loaded_hooks = [
+        {
+            "name": "beam-runtime",
+            "events": ["gateway:startup"],
+            "path": str(tmp_path / "hook"),
+            "startup_readiness": {
+                "id": "beam-runtime",
+                "required": True,
+            },
+        }
+    ]
+    monkeypatch.setattr(runner, "_create_adapter", lambda platform, platform_config: _SuccessfulAdapter())
+    monkeypatch.setattr("hermes_cli.plugins.discover_plugins", lambda: None)
+    monkeypatch.setattr(runner.hooks, "discover_and_load", lambda: None)
+
+    async def _assert_checks(event_type, context):
+        state = read_runtime_status()
+        assert event_type == "gateway:startup"
+        assert state["startup_checks"]["beam-runtime"]["state"] == "pending"
+        assert state["startup_checks"]["beam-runtime"]["required"] is True
+
+    monkeypatch.setattr(runner.hooks, "emit", _assert_checks)
+
+    ok = await runner.start()
+
+    assert ok is True
+
+
 @pytest.mark.asyncio
 async def test_start_gateway_verbosity_imports_redacting_formatter(monkeypatch, tmp_path):
     """Verbosity != None must not crash with NameError on RedactingFormatter (#8044)."""

tests/gateway/test_status.py

@@ -132,6 +132,72 @@ class TestGatewayRuntimeStatus:
         assert payload["platforms"]["discord"]["error_code"] is None
         assert payload["platforms"]["discord"]["error_message"] is None
 
+    def test_reset_startup_checks_replaces_previous_run_entries(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+
+        status.write_runtime_status(
+            gateway_state="running",
+            startup_checks={
+                "old-check": {
+                    "state": "ready",
+                    "required": True,
+                    "source": "old-hook",
+                    "detail": None,
+                }
+            },
+        )
+
+        status.reset_startup_checks([
+            {
+                "name": "new-hook",
+                "startup_readiness": {
+                    "id": "new-check",
+                    "required": False,
+                },
+            }
+        ])
+
+        payload = status.read_runtime_status()
+        assert set(payload["startup_checks"]) == {"new-check"}
+        assert payload["startup_checks"]["new-check"]["state"] == "pending"
+        assert payload["startup_checks"]["new-check"]["required"] is False
+        assert payload["startup_checks"]["new-check"]["source"] == "new-hook"
+
+    def test_mark_startup_check_ready_persists_detail(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+
+        status.reset_startup_checks([
+            {
+                "name": "beam",
+                "startup_readiness": {
+                    "id": "beam-runtime",
+                    "required": True,
+                },
+            }
+        ])
+
+        status.mark_startup_check_ready("beam-runtime", detail="ready for RPC")
+
+        payload = status.read_runtime_status()
+        assert payload["startup_checks"]["beam-runtime"]["state"] == "ready"
+        assert payload["startup_checks"]["beam-runtime"]["detail"] == "ready for RPC"
+
+    def test_mark_startup_check_failed_creates_missing_entry(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+
+        status.mark_startup_check_failed(
+            "late-hook",
+            detail="startup hook crashed",
+            required=False,
+            source="late-hook",
+        )
+
+        payload = status.read_runtime_status()
+        assert payload["startup_checks"]["late-hook"]["state"] == "failed"
+        assert payload["startup_checks"]["late-hook"]["required"] is False
+        assert payload["startup_checks"]["late-hook"]["source"] == "late-hook"
+        assert payload["startup_checks"]["late-hook"]["detail"] == "startup hook crashed"
+
 
 class TestTerminatePid:
     def test_force_uses_taskkill_on_windows(self, monkeypatch):

tests/hermes_cli/test_gateway_service.py

@@ -6,12 +6,21 @@ from pathlib import Path
 from types import SimpleNamespace
 
 import hermes_cli.gateway as gateway_cli
+import pytest
 from gateway.restart import (
     DEFAULT_GATEWAY_RESTART_DRAIN_TIMEOUT,
     GATEWAY_SERVICE_RESTART_EXIT_CODE,
 )
 
 
+_REAL_AWAIT_SERVICE_READY = gateway_cli._await_service_ready_or_exit
+
+
+@pytest.fixture(autouse=True)
+def _stub_service_readiness(monkeypatch):
+    monkeypatch.setattr(gateway_cli, "_await_service_ready_or_exit", lambda **kwargs: None)
+
+
 class TestSystemdServiceRefresh:
     def test_systemd_install_repairs_outdated_unit_without_force(self, tmp_path, monkeypatch):
         unit_path = tmp_path / "hermes-gateway.service"
@@ -82,6 +91,30 @@ class TestSystemdServiceRefresh:
             ["systemctl", "--user", "reload-or-restart", gateway_cli.get_service_name()],
         ]
 
+    def test_systemd_start_waits_for_readiness_before_reporting_success(self, monkeypatch):
+        calls = []
+
+        monkeypatch.setattr(gateway_cli, "_select_systemd_scope", lambda system=False: False)
+        monkeypatch.setattr(gateway_cli, "refresh_systemd_unit_if_needed", lambda system=False: calls.append(("refresh", system)))
+        monkeypatch.setattr(
+            gateway_cli,
+            "_run_systemctl",
+            lambda cmd, system=False, check=True, timeout=30, **kwargs: calls.append((tuple(cmd), system, timeout)),
+        )
+        monkeypatch.setattr(
+            gateway_cli,
+            "_await_service_ready_or_exit",
+            lambda **kwargs: calls.append(("ready", kwargs)),
+        )
+
+        gateway_cli.systemd_start()
+
+        assert calls == [
+            ("refresh", False),
+            (("start", gateway_cli.get_service_name()), False, 30),
+            ("ready", {"action": "start"}),
+        ]
+
 
 class TestGeneratedSystemdUnits:
     def test_user_unit_avoids_recursive_execstop_and_uses_extended_stop_timeout(self):
@@ -268,6 +301,32 @@ class TestLaunchdServiceRecovery:
             ["launchctl", "kickstart", target],
         ]
 
+    def test_launchd_start_waits_for_readiness_before_reporting_success(self, tmp_path, monkeypatch):
+        plist_path = tmp_path / "ai.hermes.gateway.plist"
+        plist_path.write_text(gateway_cli.generate_launchd_plist(), encoding="utf-8")
+        label = gateway_cli.get_launchd_label()
+        calls = []
+
+        monkeypatch.setattr(gateway_cli, "get_launchd_plist_path", lambda: plist_path)
+        monkeypatch.setattr(gateway_cli, "refresh_launchd_plist_if_needed", lambda: None)
+        monkeypatch.setattr(
+            gateway_cli.subprocess,
+            "run",
+            lambda cmd, check=False, **kwargs: calls.append(cmd) or SimpleNamespace(returncode=0, stdout="", stderr=""),
+        )
+        monkeypatch.setattr(
+            gateway_cli,
+            "_await_service_ready_or_exit",
+            lambda **kwargs: calls.append(("ready", kwargs)),
+        )
+
+        gateway_cli.launchd_start()
+
+        assert calls == [
+            ["launchctl", "kickstart", f"{gateway_cli._launchd_domain()}/{label}"],
+            ("ready", {"action": "start"}),
+        ]
+
     def test_launchd_restart_drains_running_gateway_before_kickstart(self, monkeypatch):
         calls = []
         target = f"{gateway_cli._launchd_domain()}/{gateway_cli.get_launchd_label()}"
@@ -315,7 +374,7 @@ class TestLaunchdServiceRecovery:
         gateway_cli.launchd_restart()
 
         assert calls == [("self", 321)]
-        assert "restart requested" in capsys.readouterr().out.lower()
+        assert "service restarted" in capsys.readouterr().out.lower()
 
     def test_launchd_stop_uses_bootout_not_kill(self, monkeypatch):
         """launchd_stop must bootout the service so KeepAlive doesn't respawn it."""
@@ -393,6 +452,109 @@ class TestLaunchdServiceRecovery:
         assert "not loaded" in output.lower()
 
 
+class TestGatewayServiceReadiness:
+    def test_wait_for_service_readiness_accepts_running_gateway_without_checks(self, monkeypatch):
+        monkeypatch.setattr("gateway.status.get_running_pid", lambda: 123)
+        monkeypatch.setattr(
+            "gateway.status.read_runtime_status",
+            lambda: {"pid": 123, "gateway_state": "running", "startup_checks": {}},
+        )
+
+        warnings = gateway_cli._wait_for_service_readiness(action="start", timeout=0.1, poll_interval=0.0)
+
+        assert warnings == []
+
+    def test_wait_for_service_readiness_ignores_stale_runtime_state_until_pid_matches(self, monkeypatch):
+        runtime_states = iter(
+            [
+                {"pid": 999, "gateway_state": "running", "startup_checks": {}},
+                {"pid": 123, "gateway_state": "running", "startup_checks": {}},
+            ]
+        )
+
+        monkeypatch.setattr("gateway.status.get_running_pid", lambda: 123)
+        monkeypatch.setattr("gateway.status.read_runtime_status", lambda: next(runtime_states))
+
+        warnings = gateway_cli._wait_for_service_readiness(action="start", timeout=0.1, poll_interval=0.0)
+
+        assert warnings == []
+
+    def test_wait_for_service_readiness_returns_optional_pending_warnings(self, monkeypatch):
+        monkeypatch.setattr("gateway.status.get_running_pid", lambda: 123)
+        monkeypatch.setattr(
+            "gateway.status.read_runtime_status",
+            lambda: {
+                "pid": 123,
+                "gateway_state": "running",
+                "startup_checks": {
+                    "optional-check": {
+                        "state": "pending",
+                        "required": False,
+                        "source": "test-hook",
+                        "detail": "still warming",
+                    }
+                },
+            },
+        )
+
+        warnings = gateway_cli._wait_for_service_readiness(action="start", timeout=0.1, poll_interval=0.0)
+
+        assert warnings == ["pending: optional-check (test-hook): still warming"]
+
+    def test_wait_for_service_readiness_fails_when_required_check_fails(self, monkeypatch):
+        monkeypatch.setattr("gateway.status.get_running_pid", lambda: 123)
+        monkeypatch.setattr(
+            "gateway.status.read_runtime_status",
+            lambda: {
+                "pid": 123,
+                "gateway_state": "running",
+                "startup_checks": {
+                    "beam-runtime": {
+                        "state": "failed",
+                        "required": True,
+                        "source": "beam",
+                        "detail": "RPC boot failed",
+                    }
+                },
+            },
+        )
+
+        with pytest.raises(RuntimeError, match=r"required startup checks failed: beam-runtime \(beam\): RPC boot failed"):
+            gateway_cli._wait_for_service_readiness(action="start", timeout=0.1, poll_interval=0.0)
+
+    def test_wait_for_service_readiness_times_out_on_pending_required_check(self, monkeypatch):
+        monkeypatch.setattr("gateway.status.get_running_pid", lambda: 123)
+        monkeypatch.setattr(
+            "gateway.status.read_runtime_status",
+            lambda: {
+                "pid": 123,
+                "gateway_state": "running",
+                "startup_checks": {
+                    "beam-runtime": {
+                        "state": "pending",
+                        "required": True,
+                        "source": "beam",
+                        "detail": "waiting for runtime",
+                    }
+                },
+            },
+        )
+
+        with pytest.raises(RuntimeError, match=r"timed out waiting for required startup checks: beam-runtime \(beam\): waiting for runtime"):
+            gateway_cli._wait_for_service_readiness(action="start", timeout=0.01, poll_interval=0.0)
+
+    def test_await_service_ready_or_exit_raises_system_exit_when_not_ready(self, monkeypatch):
+        monkeypatch.setattr(gateway_cli, "_await_service_ready_or_exit", _REAL_AWAIT_SERVICE_READY)
+        monkeypatch.setattr(
+            gateway_cli,
+            "_wait_for_service_readiness",
+            lambda **kwargs: (_ for _ in ()).throw(RuntimeError("not ready")),
+        )
+
+        with pytest.raises(SystemExit, match="1"):
+            gateway_cli._await_service_ready_or_exit(action="start")
+
+
 class TestGatewayServiceDetection:
     def test_supports_systemd_services_requires_systemctl_binary(self, monkeypatch):
         monkeypatch.setattr(gateway_cli, "is_linux", lambda: True)
@@ -475,7 +637,7 @@ class TestGatewaySystemServiceRouting:
         gateway_cli.systemd_restart()
 
         assert calls == [("refresh", False), ("self", 654)]
-        assert "restart requested" in capsys.readouterr().out.lower()
+        assert "service restarted" in capsys.readouterr().out.lower()
 
     def test_gateway_install_passes_system_flags(self, monkeypatch):
         monkeypatch.setattr(gateway_cli, "supports_systemd_services", lambda: True)

tests/run_agent/test_run_agent.py

@@ -1622,60 +1622,6 @@ class TestParallelScopePathNormalization:
         assert not _should_parallelize_tool_batch([tc1, tc2])
 
 
-class TestMcpParallelToolBatch:
-    """Integration test: _should_parallelize_tool_batch respects MCP parallel flag."""
-
-    def test_mcp_tools_default_sequential(self):
-        """MCP tools without supports_parallel_tool_calls are sequential."""
-        from run_agent import _should_parallelize_tool_batch
-        tc1 = _mock_tool_call(name="mcp_github_list_repos", arguments='{"org":"openai"}', call_id="c1")
-        tc2 = _mock_tool_call(name="mcp_github_search_code", arguments='{"q":"test"}', call_id="c2")
-        assert not _should_parallelize_tool_batch([tc1, tc2])
-
-    def test_mcp_tools_parallel_when_server_opted_in(self):
-        """MCP tools from a parallel-safe server can run concurrently."""
-        from run_agent import _should_parallelize_tool_batch
-        from tools.mcp_tool import _parallel_safe_servers, _lock
-        with _lock:
-            _parallel_safe_servers.add("github")
-        try:
-            tc1 = _mock_tool_call(name="mcp_github_list_repos", arguments='{"org":"openai"}', call_id="c1")
-            tc2 = _mock_tool_call(name="mcp_github_search_code", arguments='{"q":"test"}', call_id="c2")
-            assert _should_parallelize_tool_batch([tc1, tc2])
-        finally:
-            with _lock:
-                _parallel_safe_servers.discard("github")
-
-    def test_mixed_mcp_and_builtin_parallel(self):
-        """MCP parallel tools mixed with built-in parallel-safe tools."""
-        from run_agent import _should_parallelize_tool_batch
-        from tools.mcp_tool import _parallel_safe_servers, _lock
-        with _lock:
-            _parallel_safe_servers.add("docs")
-        try:
-            tc1 = _mock_tool_call(name="mcp_docs_search", arguments='{"query":"api"}', call_id="c1")
-            tc2 = _mock_tool_call(name="web_search", arguments='{"query":"test"}', call_id="c2")
-            assert _should_parallelize_tool_batch([tc1, tc2])
-        finally:
-            with _lock:
-                _parallel_safe_servers.discard("docs")
-
-    def test_mixed_parallel_and_serial_mcp_servers(self):
-        """One parallel MCP server + one non-parallel MCP server = sequential."""
-        from run_agent import _should_parallelize_tool_batch
-        from tools.mcp_tool import _parallel_safe_servers, _lock
-        with _lock:
-            _parallel_safe_servers.add("docs")
-            # "github" is NOT in _parallel_safe_servers
-        try:
-            tc1 = _mock_tool_call(name="mcp_docs_search", arguments='{"query":"api"}', call_id="c1")
-            tc2 = _mock_tool_call(name="mcp_github_list_repos", arguments='{"org":"openai"}', call_id="c2")
-            assert not _should_parallelize_tool_batch([tc1, tc2])
-        finally:
-            with _lock:
-                _parallel_safe_servers.discard("docs")
-
-
 class TestHandleMaxIterations:
     def test_returns_summary(self, agent):
         resp = _mock_response(content="Here is a summary of what I did.")

tests/tools/test_browser_homebrew_paths.py

@@ -31,25 +31,18 @@ def _clear_browser_caches():
 
 
 class TestSanePath:
-    """Verify _SANE_PATH includes fallback directories used by browser_tool."""
-
-    def test_includes_termux_bin(self):
-        assert "/data/data/com.termux/files/usr/bin" in _SANE_PATH.split(os.pathsep)
-
-    def test_includes_termux_sbin(self):
-        assert "/data/data/com.termux/files/usr/sbin" in _SANE_PATH.split(os.pathsep)
+    """Verify _SANE_PATH includes Homebrew directories."""
 
     def test_includes_homebrew_bin(self):
-        assert "/opt/homebrew/bin" in _SANE_PATH.split(os.pathsep)
+        assert "/opt/homebrew/bin" in _SANE_PATH
 
     def test_includes_homebrew_sbin(self):
-        assert "/opt/homebrew/sbin" in _SANE_PATH.split(os.pathsep)
+        assert "/opt/homebrew/sbin" in _SANE_PATH
 
     def test_includes_standard_dirs(self):
-        path_parts = _SANE_PATH.split(os.pathsep)
-        assert "/usr/local/bin" in path_parts
-        assert "/usr/bin" in path_parts
-        assert "/bin" in path_parts
+        assert "/usr/local/bin" in _SANE_PATH
+        assert "/usr/bin" in _SANE_PATH
+        assert "/bin" in _SANE_PATH
 
 
 class TestDiscoverHomebrewNodeDirs:
@@ -150,44 +143,6 @@ class TestFindAgentBrowser:
             result = _find_agent_browser()
             assert result == "npx agent-browser"
 
-    def test_finds_npx_in_termux_fallback_path(self):
-        """Should find npx when only Termux fallback dirs are available."""
-        def mock_which(cmd, path=None):
-            if cmd == "agent-browser":
-                return None
-            if cmd == "npx":
-                if path and "/data/data/com.termux/files/usr/bin" in path:
-                    return "/data/data/com.termux/files/usr/bin/npx"
-                return None
-            return None
-
-        original_path_exists = Path.exists
-
-        def mock_path_exists(self):
-            if "node_modules" in str(self) and "agent-browser" in str(self):
-                return False
-            return original_path_exists(self)
-
-        real_isdir = os.path.isdir
-
-        def selective_isdir(path):
-            if path in (
-                "/data/data/com.termux/files/usr/bin",
-                "/data/data/com.termux/files/usr/sbin",
-            ):
-                return True
-            return real_isdir(path)
-
-        with patch("shutil.which", side_effect=mock_which), \
-             patch("os.path.isdir", side_effect=selective_isdir), \
-             patch.object(Path, "exists", mock_path_exists), \
-             patch(
-                 "tools.browser_tool._discover_homebrew_node_dirs",
-                 return_value=[],
-             ):
-            result = _find_agent_browser()
-            assert result == "npx agent-browser"
-
     def test_raises_when_not_found(self):
         """Should raise FileNotFoundError when nothing works."""
         original_path_exists = Path.exists
@@ -444,51 +399,3 @@ class TestRunBrowserCommandPathConstruction:
         result_path = captured_env.get("PATH", "")
         assert "/opt/homebrew/bin" in result_path
         assert "/opt/homebrew/sbin" in result_path
-
-    def test_subprocess_path_includes_termux_fallback_dirs(self, tmp_path):
-        """Termux fallback dirs should survive browser PATH rebuilding."""
-        captured_env = {}
-
-        mock_proc = MagicMock()
-        mock_proc.returncode = 0
-        mock_proc.wait.return_value = 0
-
-        def capture_popen(cmd, **kwargs):
-            captured_env.update(kwargs.get("env", {}))
-            return mock_proc
-
-        fake_session = {
-            "session_name": "test-session",
-            "session_id": "test-id",
-            "cdp_url": None,
-        }
-
-        fake_json = json.dumps({"success": True})
-        real_isdir = os.path.isdir
-
-        def selective_isdir(path):
-            if path in (
-                "/data/data/com.termux/files/usr/bin",
-                "/data/data/com.termux/files/usr/sbin",
-            ):
-                return True
-            if path.startswith(str(tmp_path)):
-                return True
-            return real_isdir(path)
-
-        with patch("tools.browser_tool._find_agent_browser", return_value="/usr/local/bin/agent-browser"), \
-             patch("tools.browser_tool._get_session_info", return_value=fake_session), \
-             patch("tools.browser_tool._socket_safe_tmpdir", return_value=str(tmp_path)), \
-             patch("tools.browser_tool._discover_homebrew_node_dirs", return_value=[]), \
-             patch("os.path.isdir", side_effect=selective_isdir), \
-             patch("subprocess.Popen", side_effect=capture_popen), \
-             patch("os.open", return_value=99), \
-             patch("os.close"), \
-             patch("tools.interrupt.is_interrupted", return_value=False), \
-             patch.dict(os.environ, {"PATH": "/usr/bin:/bin", "HOME": "/home/test"}, clear=True):
-            with patch("builtins.open", mock_open(read_data=fake_json)):
-                _run_browser_command("test-task", "navigate", ["https://example.com"])
-
-        result_path = captured_env.get("PATH", "")
-        assert "/data/data/com.termux/files/usr/bin" in result_path
-        assert "/data/data/com.termux/files/usr/sbin" in result_path

tests/tools/test_mcp_tool.py

@@ -3140,138 +3140,3 @@ class TestRegisterMcpServers:
                 )
 
         _servers.pop("srv", None)
-
-
-# ---------------------------------------------------------------------------
-# Tests for parallel tool call support (port from openai/codex#17667)
-# ---------------------------------------------------------------------------
-
-class TestMcpParallelToolCalls:
-    """Tests for the supports_parallel_tool_calls config option."""
-
-    def test_is_mcp_tool_parallel_safe_non_mcp_tool(self):
-        """Non-MCP tool names always return False."""
-        from tools.mcp_tool import is_mcp_tool_parallel_safe
-        assert is_mcp_tool_parallel_safe("web_search") is False
-        assert is_mcp_tool_parallel_safe("read_file") is False
-        assert is_mcp_tool_parallel_safe("terminal") is False
-        assert is_mcp_tool_parallel_safe("") is False
-
-    def test_is_mcp_tool_parallel_safe_no_servers(self):
-        """MCP tool from unknown server returns False."""
-        from tools.mcp_tool import is_mcp_tool_parallel_safe, _parallel_safe_servers, _lock
-        with _lock:
-            _parallel_safe_servers.clear()
-        assert is_mcp_tool_parallel_safe("mcp_docs_search") is False
-
-    def test_is_mcp_tool_parallel_safe_with_flag(self):
-        """MCP tool from a parallel-safe server returns True."""
-        from tools.mcp_tool import is_mcp_tool_parallel_safe, _parallel_safe_servers, _lock
-        with _lock:
-            _parallel_safe_servers.add("docs")
-        try:
-            assert is_mcp_tool_parallel_safe("mcp_docs_search") is True
-            assert is_mcp_tool_parallel_safe("mcp_docs_read_file") is True
-            # Different server should be False
-            assert is_mcp_tool_parallel_safe("mcp_github_list_repos") is False
-        finally:
-            with _lock:
-                _parallel_safe_servers.discard("docs")
-
-    def test_is_mcp_tool_parallel_safe_server_with_underscores(self):
-        """Server names containing underscores are correctly matched."""
-        from tools.mcp_tool import is_mcp_tool_parallel_safe, _parallel_safe_servers, _lock
-        with _lock:
-            _parallel_safe_servers.add("my_server")
-        try:
-            assert is_mcp_tool_parallel_safe("mcp_my_server_query") is True
-        finally:
-            with _lock:
-                _parallel_safe_servers.discard("my_server")
-
-    def test_is_mcp_tool_parallel_safe_no_tool_suffix(self):
-        """Tool name that is just 'mcp_{server}' without a tool part returns False."""
-        from tools.mcp_tool import is_mcp_tool_parallel_safe, _parallel_safe_servers, _lock
-        with _lock:
-            _parallel_safe_servers.add("docs")
-        try:
-            # "mcp_docs" has no tool part after the server name
-            assert is_mcp_tool_parallel_safe("mcp_docs") is False
-            # "mcp_docs_" has empty tool part
-            assert is_mcp_tool_parallel_safe("mcp_docs_") is False
-        finally:
-            with _lock:
-                _parallel_safe_servers.discard("docs")
-
-    def test_register_mcp_servers_tracks_parallel_flag(self):
-        """register_mcp_servers populates _parallel_safe_servers from config."""
-        from tools.mcp_tool import (
-            register_mcp_servers, _parallel_safe_servers, _lock,
-            sanitize_mcp_name_component,
-        )
-        fake_config = {
-            "parallel_srv": {
-                "command": "echo",
-                "supports_parallel_tool_calls": True,
-            },
-            "serial_srv": {
-                "command": "echo",
-                "supports_parallel_tool_calls": False,
-            },
-            "default_srv": {
-                "command": "echo",
-                # no supports_parallel_tool_calls key
-            },
-        }
-        with patch("tools.mcp_tool._MCP_AVAILABLE", True), \
-             patch("tools.mcp_tool._ensure_mcp_loop"), \
-             patch("tools.mcp_tool._run_on_mcp_loop"), \
-             patch("tools.mcp_tool._sync_mcp_toolsets"), \
-             patch("tools.mcp_tool._existing_tool_names", return_value=[]):
-            register_mcp_servers(fake_config)
-
-        with _lock:
-            assert sanitize_mcp_name_component("parallel_srv") in _parallel_safe_servers
-            assert sanitize_mcp_name_component("serial_srv") not in _parallel_safe_servers
-            assert sanitize_mcp_name_component("default_srv") not in _parallel_safe_servers
-            # Cleanup
-            _parallel_safe_servers.discard(sanitize_mcp_name_component("parallel_srv"))
-
-    def test_register_mcp_servers_removes_parallel_flag_on_toggle(self):
-        """Toggling supports_parallel_tool_calls to false removes server from the set."""
-        from tools.mcp_tool import (
-            register_mcp_servers, _parallel_safe_servers, _lock,
-            sanitize_mcp_name_component,
-        )
-
-        # First registration: parallel enabled
-        config_on = {
-            "toggle_srv": {
-                "command": "echo",
-                "supports_parallel_tool_calls": True,
-            },
-        }
-        with patch("tools.mcp_tool._MCP_AVAILABLE", True), \
-             patch("tools.mcp_tool._ensure_mcp_loop"), \
-             patch("tools.mcp_tool._run_on_mcp_loop"), \
-             patch("tools.mcp_tool._sync_mcp_toolsets"), \
-             patch("tools.mcp_tool._existing_tool_names", return_value=[]):
-            register_mcp_servers(config_on)
-        with _lock:
-            assert sanitize_mcp_name_component("toggle_srv") in _parallel_safe_servers
-
-        # Second registration: parallel disabled
-        config_off = {
-            "toggle_srv": {
-                "command": "echo",
-                "supports_parallel_tool_calls": False,
-            },
-        }
-        with patch("tools.mcp_tool._MCP_AVAILABLE", True), \
-             patch("tools.mcp_tool._ensure_mcp_loop"), \
-             patch("tools.mcp_tool._run_on_mcp_loop"), \
-             patch("tools.mcp_tool._sync_mcp_toolsets"), \
-             patch("tools.mcp_tool._existing_tool_names", return_value=[]):
-            register_mcp_servers(config_off)
-        with _lock:
-            assert sanitize_mcp_name_component("toggle_srv") not in _parallel_safe_servers

tools/browser_tool.py

@@ -94,21 +94,11 @@ except ImportError:
 logger = logging.getLogger(__name__)
 
 # Standard PATH entries for environments with minimal PATH (e.g. systemd services).
-# Includes Android/Termux and macOS Homebrew locations needed for agent-browser,
-# npx, node, and Android's glibc runner (grun).
-_SANE_PATH_DIRS = (
-    "/data/data/com.termux/files/usr/bin",
-    "/data/data/com.termux/files/usr/sbin",
-    "/opt/homebrew/bin",
-    "/opt/homebrew/sbin",
-    "/usr/local/sbin",
-    "/usr/local/bin",
-    "/usr/sbin",
-    "/usr/bin",
-    "/sbin",
-    "/bin",
+# Includes macOS Homebrew paths (/opt/homebrew/* for Apple Silicon).
+_SANE_PATH = (
+    "/opt/homebrew/bin:/opt/homebrew/sbin:"
+    "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
 )
-_SANE_PATH = os.pathsep.join(_SANE_PATH_DIRS)
 
 
 @functools.lru_cache(maxsize=1)
@@ -133,28 +123,6 @@ def _discover_homebrew_node_dirs() -> tuple[str, ...]:
         pass
     return tuple(dirs)
 
-
-def _browser_candidate_path_dirs() -> list[str]:
-    """Return ordered browser CLI PATH candidates shared by discovery and execution."""
-    hermes_home = get_hermes_home()
-    hermes_node_bin = str(hermes_home / "node" / "bin")
-    return [hermes_node_bin, *list(_discover_homebrew_node_dirs()), *_SANE_PATH_DIRS]
-
-
-def _merge_browser_path(existing_path: str = "") -> str:
-    """Prepend browser-specific PATH fallbacks without reordering existing entries."""
-    path_parts = [p for p in (existing_path or "").split(os.pathsep) if p]
-    existing_parts = set(path_parts)
-    prefix_parts: list[str] = []
-
-    for part in _browser_candidate_path_dirs():
-        if not part or part in existing_parts or part in prefix_parts:
-            continue
-        if os.path.isdir(part):
-            prefix_parts.append(part)
-
-    return os.pathsep.join(prefix_parts + path_parts)
-
 # Throttle screenshot cleanup to avoid repeated full directory scans.
 _last_screenshot_cleanup_by_dir: dict[str, float] = {}
 
@@ -927,10 +895,21 @@ def _find_agent_browser() -> str:
         _agent_browser_resolved = True
         return which_result
 
-    # Build an extended search PATH including Hermes-managed Node, macOS
-    # versioned Homebrew installs, and fallback system dirs like Termux.
-    extended_path = _merge_browser_path("")
-    if extended_path:
+    # Build an extended search PATH including Homebrew and Hermes-managed dirs.
+    # This covers macOS where the process PATH may not include Homebrew paths.
+    extra_dirs: list[str] = []
+    for d in ["/opt/homebrew/bin", "/usr/local/bin"]:
+        if os.path.isdir(d):
+            extra_dirs.append(d)
+    extra_dirs.extend(_discover_homebrew_node_dirs())
+
+    hermes_home = get_hermes_home()
+    hermes_node_bin = str(hermes_home / "node" / "bin")
+    if os.path.isdir(hermes_node_bin):
+        extra_dirs.append(hermes_node_bin)
+
+    if extra_dirs:
+        extended_path = os.pathsep.join(extra_dirs)
         which_result = shutil.which("agent-browser", path=extended_path)
         if which_result:
             _cached_agent_browser = which_result
@@ -945,10 +924,10 @@ def _find_agent_browser() -> str:
         _agent_browser_resolved = True
         return _cached_agent_browser
     
-    # Check common npx locations (also search the extended fallback PATH)
+    # Check common npx locations (also search extended dirs)
     npx_path = shutil.which("npx")
-    if not npx_path and extended_path:
-        npx_path = shutil.which("npx", path=extended_path)
+    if not npx_path and extra_dirs:
+        npx_path = shutil.which("npx", path=os.pathsep.join(extra_dirs))
     if npx_path:
         _cached_agent_browser = "npx agent-browser"
         _agent_browser_resolved = True
@@ -1067,9 +1046,24 @@ def _run_browser_command(
         
         browser_env = {**os.environ}
 
-        # Ensure subprocesses inherit the same browser-specific PATH fallbacks
-        # used during CLI discovery.
-        browser_env["PATH"] = _merge_browser_path(browser_env.get("PATH", ""))
+        # Ensure PATH includes Hermes-managed Node first, Homebrew versioned
+        # node dirs (for macOS ``brew install node@24``), then standard system dirs.
+        hermes_home = get_hermes_home()
+        hermes_node_bin = str(hermes_home / "node" / "bin")
+
+        existing_path = browser_env.get("PATH", "")
+        path_parts = [p for p in existing_path.split(":") if p]
+        candidate_dirs = (
+            [hermes_node_bin]
+            + list(_discover_homebrew_node_dirs())
+            + [p for p in _SANE_PATH.split(":") if p]
+        )
+
+        for part in reversed(candidate_dirs):
+            if os.path.isdir(part) and part not in path_parts:
+                path_parts.insert(0, part)
+
+        browser_env["PATH"] = ":".join(path_parts)
         browser_env["AGENT_BROWSER_SOCKET_DIR"] = task_socket_dir
         
         # Use temp files for stdout/stderr instead of pipes.

tools/mcp_tool.py

@@ -24,7 +24,6 @@ Example config::
         args: ["-y", "@modelcontextprotocol/server-github"]
         env:
           GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
-        supports_parallel_tool_calls: true  # tools from this server may run concurrently
       remote_api:
         url: "https://my-mcp-server.example.com/mcp"
         headers:
@@ -52,8 +51,6 @@ Features:
     - Thread-safe architecture with dedicated background event loop
     - Sampling support: MCP servers can request LLM completions via
       sampling/createMessage (text and tool-use responses)
-    - Parallel tool call opt-in: per-server ``supports_parallel_tool_calls``
-      flag allows concurrent execution of tools from the same server
 
 Architecture:
     A dedicated background event loop (_mcp_loop) runs in a daemon thread.
@@ -1170,16 +1167,11 @@ class MCPServerTask:
 
 _servers: Dict[str, MCPServerTask] = {}
 
-# Sanitized server names whose ``supports_parallel_tool_calls`` config is True.
-# Populated during ``register_mcp_servers()`` and queried by
-# ``is_mcp_tool_parallel_safe()`` for the parallel-execution check in run_agent.
-_parallel_safe_servers: set = set()
-
 # Dedicated event loop running in a background daemon thread.
 _mcp_loop: Optional[asyncio.AbstractEventLoop] = None
 _mcp_thread: Optional[threading.Thread] = None
 
-# Protects _mcp_loop, _mcp_thread, _servers, _parallel_safe_servers, and _stdio_pids.
+# Protects _mcp_loop, _mcp_thread, _servers, and _stdio_pids.
 _lock = threading.Lock()
 
 # PIDs of stdio MCP server subprocesses.  Tracked so we can force-kill
@@ -2055,12 +2047,6 @@ def register_mcp_servers(servers: Dict[str, dict]) -> List[str]:
             for k, v in servers.items()
             if k not in _servers and _parse_boolish(v.get("enabled", True), default=True)
         }
-        # Track which servers opt-in to parallel tool calls (idempotent).
-        for srv_name, srv_cfg in servers.items():
-            if _parse_boolish(srv_cfg.get("supports_parallel_tool_calls", False), default=False):
-                _parallel_safe_servers.add(sanitize_mcp_name_component(srv_name))
-            else:
-                _parallel_safe_servers.discard(sanitize_mcp_name_component(srv_name))
 
     if not new_servers:
         _sync_mcp_toolsets(list(servers.keys()))
@@ -2162,29 +2148,6 @@ def discover_mcp_tools() -> List[str]:
     return tool_names
 
 
-def is_mcp_tool_parallel_safe(tool_name: str) -> bool:
-    """Check if an MCP tool belongs to a server that supports parallel tool calls.
-
-    MCP tool names follow the pattern ``mcp_{server}_{tool}``.  This extracts
-    the server component and checks it against the set of servers whose config
-    includes ``supports_parallel_tool_calls: true``.
-
-    Returns False for non-MCP tools or tools from servers without the flag.
-    """
-    if not tool_name.startswith("mcp_"):
-        return False
-    # Strip the "mcp_" prefix and extract the server name.
-    # Tool names are: mcp_{sanitized_server}_{sanitized_tool}
-    # We need to check all possible server prefixes because the server name
-    # itself may contain underscores after sanitization.
-    rest = tool_name[4:]  # strip "mcp_"
-    with _lock:
-        for server_name in _parallel_safe_servers:
-            if rest.startswith(server_name + "_") and len(rest) > len(server_name) + 1:
-                return True
-    return False
-
-
 def get_mcp_status() -> List[dict]:
     """Return status of all configured MCP servers for banner display.
 

website/docs/getting-started/termux.md

@@ -152,15 +152,12 @@ hermes setup
 
 ### Install optional Node dependencies manually
 
-The tested Termux path skips Node/browser bootstrap on purpose. If you want to experiment with browser tooling later:
+The tested Termux path skips Node/browser bootstrap on purpose. If you want to experiment later:
 
 ```bash
-pkg install nodejs-lts
 npm install
 ```
 
-The browser tool automatically includes Termux directories (`/data/data/com.termux/files/usr/bin`) in its PATH search, so `agent-browser` and `npx` are discovered without any extra PATH configuration.
-
 Treat browser / WhatsApp tooling on Android as experimental until documented otherwise.
 
 ---

website/docs/reference/mcp-config-reference.md

@@ -28,7 +28,6 @@ mcp_servers:
     enabled: true
     timeout: 120
     connect_timeout: 60
-    supports_parallel_tool_calls: false
     tools:
       include: []
       exclude: []
@@ -48,7 +47,6 @@ mcp_servers:
 | `enabled` | bool | both | Skip the server entirely when false |
 | `timeout` | number | both | Tool call timeout |
 | `connect_timeout` | number | both | Initial connection timeout |
-| `supports_parallel_tool_calls` | bool | both | Allow tools from this server to run concurrently |
 | `tools` | mapping | both | Filtering and utility-tool policy |
 | `auth` | string | HTTP | Authentication method. Set to `oauth` to enable OAuth 2.1 with PKCE |
 | `sampling` | mapping | both | Server-initiated LLM request policy (see MCP guide) |

website/docs/user-guide/features/mcp.md

@@ -105,7 +105,6 @@ Hermes reads MCP config from `~/.hermes/config.yaml` under `mcp_servers`.
 | `timeout` | number | Tool call timeout |
 | `connect_timeout` | number | Initial connection timeout |
 | `enabled` | bool | If `false`, Hermes skips the server entirely |
-| `supports_parallel_tool_calls` | bool | If `true`, tools from this server may run concurrently |
 | `tools` | mapping | Per-server tool filtering and utility policy |
 
 ### Minimal stdio example
@@ -410,23 +409,6 @@ Because Hermes now only registers those wrappers when both are true:
 
 This is intentional and keeps the tool list honest.
 
-## Parallel Tool Calls
-
-By default, MCP tools run sequentially — one at a time. If your MCP server exposes tools that are safe to run concurrently (e.g. read-only queries, independent API calls), you can opt-in to parallel execution:
-
-```yaml
-mcp_servers:
-  docs:
-    command: "docs-server"
-    supports_parallel_tool_calls: true
-```
-
-When `supports_parallel_tool_calls` is `true`, Hermes may execute multiple tools from that server at the same time within a single tool-call batch, just like it does for built-in read-only tools (web_search, read_file, etc.).
-
-:::caution
-Only enable parallel calls for MCP servers whose tools are safe to run at the same time. If tools read and write shared state, files, databases, or external resources, review the read/write race conditions before enabling this setting.
-:::
-
 ## MCP Sampling Support
 
 MCP servers can request LLM inference from Hermes via the `sampling/createMessage` protocol. This allows an MCP server to ask Hermes to generate text on its behalf — useful for servers that need LLM capabilities but don't have their own model access.

website/docs/user-guide/skills/google-workspace.md

@@ -1,191 +0,0 @@
----
-sidebar_position: 2
-sidebar_label: "Google Workspace"
-title: "Google Workspace — Gmail, Calendar, Drive, Sheets & Docs"
-description: "Send email, manage calendar events, search Drive, read/write Sheets, and access Docs — all through OAuth2-authenticated Google APIs"
----
-
-# Google Workspace Skill
-
-Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration for Hermes. Uses OAuth2 with automatic token refresh. Prefers the [Google Workspace CLI (`gws`)](https://github.com/nicholasgasior/gws) when available for broader coverage, and falls back to Google's Python client libraries otherwise.
-
-**Skill path:** `skills/productivity/google-workspace/`
-
-## Setup
-
-The setup is fully agent-driven — ask Hermes to set up Google Workspace and it walks you through each step. The flow:
-
-1. **Create a Google Cloud project** and enable the required APIs (Gmail, Calendar, Drive, Sheets, Docs, People)
-2. **Create OAuth 2.0 credentials** (Desktop app type) and download the client secret JSON
-3. **Authorize** — Hermes generates an auth URL, you approve in the browser, paste back the redirect URL
-4. **Done** — token auto-refreshes from that point on
-
-:::tip Email-only users
-If you only need email (no Calendar/Drive/Sheets), use the **himalaya** skill instead — it works with a Gmail App Password and takes 2 minutes. No Google Cloud project needed.
-:::
-
-## Gmail
-
-### Searching
-
-```bash
-$GAPI gmail search "is:unread" --max 10
-$GAPI gmail search "from:boss@company.com newer_than:1d"
-$GAPI gmail search "has:attachment filename:pdf newer_than:7d"
-```
-
-Returns JSON with `id`, `from`, `subject`, `date`, `snippet`, and `labels` for each message.
-
-### Reading
-
-```bash
-$GAPI gmail get MESSAGE_ID
-```
-
-Returns the full message body as text (prefers plain text, falls back to HTML).
-
-### Sending
-
-```bash
-# Basic send
-$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
-
-# HTML email
-$GAPI gmail send --to user@example.com --subject "Report" \
-  --body "<h1>Q4 Results</h1><p>Details here</p>" --html
-
-# Custom From header (display name + email)
-$GAPI gmail send --to user@example.com --subject "Hello" \
-  --from '"Research Agent" <user@example.com>' --body "Message text"
-
-# With CC
-$GAPI gmail send --to user@example.com --cc "team@example.com" \
-  --subject "Update" --body "FYI"
-```
-
-### Custom From Header
-
-The `--from` flag lets you customize the sender display name on outgoing emails. This is useful when multiple agents share the same Gmail account but you want recipients to see different names:
-
-```bash
-# Agent 1
-$GAPI gmail send --to client@co.com --subject "Research Summary" \
-  --from '"Research Agent" <shared@company.com>' --body "..."
-
-# Agent 2  
-$GAPI gmail send --to client@co.com --subject "Code Review" \
-  --from '"Code Assistant" <shared@company.com>' --body "..."
-```
-
-**How it works:** The `--from` value is set as the RFC 5322 `From` header on the MIME message. Gmail allows customizing the display name on your own authenticated email address without any additional configuration. Recipients see the custom display name (e.g. "Research Agent") while the email address stays the same.
-
-**Important:** If you use a *different email address* in `--from` (not the authenticated account), Gmail requires that address to be configured as a [Send As alias](https://support.google.com/mail/answer/22370) in Gmail Settings → Accounts → Send mail as.
-
-The `--from` flag works on both `send` and `reply`:
-
-```bash
-$GAPI gmail reply MESSAGE_ID \
-  --from '"Support Bot" <shared@company.com>' --body "We're on it"
-```
-
-### Replying
-
-```bash
-$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
-```
-
-Automatically threads the reply (sets `In-Reply-To` and `References` headers) and uses the original message's thread ID.
-
-### Labels
-
-```bash
-# List all labels
-$GAPI gmail labels
-
-# Add/remove labels
-$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
-$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
-```
-
-## Calendar
-
-```bash
-# List events (defaults to next 7 days)
-$GAPI calendar list
-$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z
-
-# Create event (timezone required)
-$GAPI calendar create --summary "Team Standup" \
-  --start 2026-03-01T10:00:00-07:00 --end 2026-03-01T10:30:00-07:00
-
-# With location and attendees
-$GAPI calendar create --summary "Lunch" \
-  --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z \
-  --location "Cafe" --attendees "alice@co.com,bob@co.com"
-
-# Delete event
-$GAPI calendar delete EVENT_ID
-```
-
-:::warning
-Calendar times **must** include a timezone offset (e.g. `-07:00`) or use UTC (`Z`). Bare datetimes like `2026-03-01T10:00:00` are ambiguous and will be treated as UTC.
-:::
-
-## Drive
-
-```bash
-$GAPI drive search "quarterly report" --max 10
-$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5
-```
-
-## Sheets
-
-```bash
-# Read a range
-$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
-
-# Write to a range
-$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'
-
-# Append rows
-$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
-```
-
-## Docs
-
-```bash
-$GAPI docs get DOC_ID
-```
-
-Returns the document title and full text content.
-
-## Contacts
-
-```bash
-$GAPI contacts list --max 20
-```
-
-## Output Format
-
-All commands return JSON. Key fields per service:
-
-| Command | Fields |
-|---------|--------|
-| `gmail search` | `id`, `threadId`, `from`, `to`, `subject`, `date`, `snippet`, `labels` |
-| `gmail get` | `id`, `threadId`, `from`, `to`, `subject`, `date`, `labels`, `body` |
-| `gmail send/reply` | `status`, `id`, `threadId` |
-| `calendar list` | `id`, `summary`, `start`, `end`, `location`, `description`, `htmlLink` |
-| `calendar create` | `status`, `id`, `summary`, `htmlLink` |
-| `drive search` | `id`, `name`, `mimeType`, `modifiedTime`, `webViewLink` |
-| `contacts list` | `name`, `emails`, `phones` |
-| `sheets get` | 2D array of cell values |
-
-## Troubleshooting
-
-| Problem | Fix |
-|---------|-----|
-| `NOT_AUTHENTICATED` | Run setup (ask Hermes to set up Google Workspace) |
-| `REFRESH_FAILED` | Token revoked — re-run authorization steps |
-| `HttpError 403: Insufficient Permission` | Missing scope — revoke and re-authorize with the right services |
-| `HttpError 403: Access Not Configured` | API not enabled in Google Cloud Console |
-| `ModuleNotFoundError` | Run setup script with `--install-deps` |

website/sidebars.ts

@@ -92,7 +92,6 @@ const sidebars: SidebarsConfig = {
           label: 'Skills',
           items: [
             'user-guide/skills/godmode',
-            'user-guide/skills/google-workspace',
           ],
         },
       ],
@@ -119,6 +118,7 @@ const sidebars: SidebarsConfig = {
         'user-guide/messaging/wecom-callback',
         'user-guide/messaging/weixin',
         'user-guide/messaging/bluebubbles',
+        'user-guide/messaging/qqbot',
         'user-guide/messaging/open-webui',
         'user-guide/messaging/webhooks',
       ],
@@ -153,6 +153,7 @@ const sidebars: SidebarsConfig = {
         'guides/use-voice-mode-with-hermes',
         'guides/build-a-hermes-plugin',
         'guides/automate-with-cron',
+        'guides/automation-templates',
         'guides/cron-troubleshooting',
         'guides/work-with-skills',
         'guides/delegation-patterns',