@tiny-fish/hermes 0.2.3 → 0.2.4

package/README.md

@@ -92,6 +92,10 @@ tinyfish:
 
 When the `tinyfish` MCP server is also configured in Hermes (`mcp_servers.tinyfish.url: https://agent.tinyfish.ai/mcp`), the plugin injects once-per-context guidance steering the model between the generic web tools and the native MCP tools. Disable with `tinyfish.routing_context: false`.
 
+## Telemetry
+
+Each `hermes tinyfish setup` run sends one event to TinyFish, whether it succeeds or fails: the outcome (for example `completed` or `key_rejected`), where the key came from (`flag`, `prompt`, `env` or `none`), the plugin version and OS. It sends a one-way hash of the API key, never the key itself, so the event joins your account. Set `TINYFISH_NO_TELEMETRY=1` in your shell or in `~/.hermes/.env` to turn it off.
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/hermes",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "TinyFish web provider plugin for Hermes Agent, delivered via npm for the TinyFish CLI. Installed by `tinyfish connect hermes`; not a JavaScript library.",
   "license": "MIT",
   "homepage": "https://docs.tinyfish.ai",

package/plugin.yaml

@@ -1,5 +1,5 @@
 name: tinyfish
-version: 0.2.3
+version: 0.2.4
 description: "TinyFish: the web, built into Hermes. Free Search and Fetch power Hermes's own web_search and web_extract, and when a site needs clicks, forms or a login, a remote browser and the tinyfish_agent web agent handle it."
 author: TinyFish
 kind: backend

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tinyfish-hermes"
-version = "0.2.3"
+version = "0.2.4"
 description = "TinyFish plugin for Hermes Agent - Search, Fetch, Browser, and the tinyfish_agent web agent"
 readme = "README.md"
 license = { text = "MIT" }

package/tinyfish_hermes/rest_client.py

@@ -2,8 +2,12 @@
 
 from __future__ import annotations
 
+import hashlib
 import math
+import os
+import sys
 import time
+import uuid
 from typing import Any, NoReturn, cast
 
 import httpx
@@ -17,6 +21,7 @@ AGENT_URL = "https://agent.tinyfish.ai"
 WALLET_URL = f"{AGENT_URL}/v1/wallet"
 SEARCH_USAGE_URL = f"{SEARCH_URL}/usage"
 FETCH_USAGE_URL = f"{FETCH_URL}/usage"
+TELEMETRY_URL = f"{AGENT_URL}/api/cli/connect-event"
 
 _BROWSER_CLOSE_MAX_ATTEMPTS = 3
 _BROWSER_CLOSE_RETRYABLE_STATUSES = frozenset({409, 429, 500, 503, 504})
@@ -334,6 +339,36 @@ def start_run(
     )
 
 
+def telemetry_disabled(value: str | None = None) -> bool:
+    # Matches the TinyFish CLI: anything but empty, 0 or false opts out.
+    if value is None:
+        value = os.environ.get("TINYFISH_NO_TELEMETRY", "")
+    return value.strip().lower() not in ("", "0", "false")
+
+
+def report_setup(outcome: str, *, key_source: str, api_key: str = "") -> None:
+    """Record a ``hermes tinyfish setup`` outcome; never raises."""
+
+    if telemetry_disabled():
+        return
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["x-api-key-lookup"] = hashlib.sha256(api_key.encode()).hexdigest()
+    body = {
+        "event": "harness_plugin_setup",
+        "harness": "hermes",
+        "plugin_version": __version__,
+        "outcome": outcome,
+        "key_source": key_source,
+        "runtime_platform": sys.platform,
+        "setup_id": str(uuid.uuid4()),
+    }
+    try:
+        httpx.post(TELEMETRY_URL, headers=headers, json=body, timeout=2.0)
+    except Exception:
+        pass
+
+
 def get_run(run_id: str, *, api_key: str) -> dict[str, Any]:
     return _agent_request("GET", f"/v1/runs/{run_id}", api_key=api_key)
 

package/tinyfish_hermes/setup_cli.py

@@ -257,20 +257,36 @@ def cmd_setup(
     provider: TinyFishWebSearchProvider | None = None,
 ) -> int:
     api_key = (getattr(args, "api_key", None) or "").strip()
+    key_source = "flag" if api_key else "none"
     existing = _api_key_env_var()
     if not api_key and existing:
         print(f"Using the TinyFish API key from {existing}")
+        key_source = "env"
     elif not api_key and sys.stdin.isatty():
         api_key = _prompt_for_key()
+        key_source = "prompt" if api_key else "none"
+
+    # Catalog installs skip `tinyfish connect`; this is their install signal.
+    def report(outcome: str) -> None:
+        # Hermes keeps settings in its .env, which never reaches os.environ.
+        if rest_client.telemetry_disabled(_get_env("TINYFISH_NO_TELEMETRY")):
+            return
+        rest_client.report_setup(
+            outcome, key_source=key_source, api_key=api_key or _api_key()
+        )
+
     if api_key:
         rejection = _validate_key(api_key)
         if rejection:
             print(rejection, file=sys.stderr)
+            report("key_rejected")
             return 1
         if not _store_api_key(api_key):
+            report("save_failed")
             return 1
     elif not existing:
         print(MISSING_KEY_ERROR, file=sys.stderr)
+        report("no_key")
         return 1
 
     # Route web tools only once a usable key exists, so a failed setup changes nothing.
@@ -284,8 +300,10 @@ def cmd_setup(
         _save_config(config)
         print("Configured Hermes web backends to use TinyFish")
         if not _enable_toolset("web"):
+            report("backend_failed")
             return 1
 
+    report("completed")
     if getattr(args, "live", False):
         doctor_args = argparse.Namespace(json=False, live=True, live_paid=False)
         return cmd_doctor(doctor_args, provider=provider)