@tiny-fish/hermes 0.2.3 → 0.2.5

package/README.md

@@ -7,20 +7,21 @@
 | Search, Fetch (free) | `tinyfish` web provider behind Hermes' `web_search` / `web_extract` |
 | Browser (credits) | `tinyfish` cloud browser provider behind Hermes' browser tools |
 | Agent (credits) | `tinyfish_agent` tool: goal-based automation on a real site |
+| Profiles (free) | `tinyfish_*_profile(s)` tools: saved website sign-ins that `tinyfish_agent` runs with |
 
 ## Install
 
-The supported path is the TinyFish CLI, which installs the plugin from npm
-(`@tiny-fish/hermes@latest`), seeds the API key, and points Hermes' web backends at it:
+Install from the Hermes plugin catalog, then add your key and route web tools to TinyFish:
 
 ```bash
-tinyfish connect hermes
+hermes plugins install tinyfish --enable
+hermes tinyfish setup
 ```
 
-To install just the plugin straight from this repo (no key seeding, no backend wiring):
+Or let the TinyFish CLI do both: it installs the same catalog plugin, seeds the API key, and points Hermes' web backends at it:
 
 ```bash
-hermes plugins install tinyfish-io/tinyfish-web-agent-integrations/hermes --enable
+npx @tiny-fish/cli connect hermes
 ```
 
 ## Authentication
@@ -30,7 +31,7 @@ The plugin authenticates with a TinyFish API key — create one at [agent.tinyfi
 | Env var | Source |
 | ------- | ------ |
 | `TINYFISH_API_KEY` | Set it yourself (shell env, or `hermes tinyfish setup --api-key`) |
-| `MCP_TINYFISH_API_KEY` | Seeded by the TinyFish npm CLI during `tinyfish connect hermes` |
+| `MCP_TINYFISH_API_KEY` | Seeded by the TinyFish npm CLI during `npx @tiny-fish/cli connect hermes` |
 
 ## CLI
 
@@ -88,10 +89,36 @@ tinyfish:
     timeout_seconds: 300  # optional session timeout
 ```
 
+## Browser Context Profiles
+
+A Browser Context Profile is a saved website sign-in. It is unrelated to Hermes profiles and to `tinyfish_agent`'s `browser_profile` (lite/stealth).
+
+| Tool | Does |
+| ---- | ---- |
+| `tinyfish_list_profiles` | Lists profiles with their `signed_in_sites` |
+| `tinyfish_create_profile` | Creates a profile and returns `setup_url`, where the user signs in and clicks Save profile |
+| `tinyfish_profile_sign_in` | Returns `setup_url` to add or refresh a site on an existing profile |
+| `tinyfish_update_profile` | Renames a profile, makes it the default, or sets its proxy country (`none` removes it) |
+| `tinyfish_delete_profile` | Deletes a profile; asks for approval first unless Hermes approvals are off (`--yolo`) |
+
+`tinyfish_agent` runs signed in with `profile_id` (or `use_profile: true` for the default profile). A profile's proxy country (set on create or update) is used for both sign-in and runs, and overrides the run's `proxy_country_code`. If a site blocks the sign-in page, set one and reopen the same link. `setup_url` asks the user to sign in to TinyFish first if that browser isn't already. Nothing bills until the user opens it; runs bill under `tinyfish.credit_policy.agent`.
+
 ## Tool-routing guidance
 
 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
+
+Off unless you turn it on. When you opt in, each `hermes tinyfish setup` run sends TinyFish one event, 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.
+
+| Opt in | How |
+|---|---|
+| Interactive setup | Answer `y` to the setup question (default No). The answer is saved. |
+| Flag | `hermes tinyfish setup --share-usage` |
+| Config | `tinyfish.telemetry: true` in Hermes config |
+
+Set `tinyfish.telemetry: false` to stop sending. `TINYFISH_NO_TELEMETRY=1` (in your shell or `~/.hermes/.env`) turns it off regardless of the other settings.
+
 ## Development
 
 ```bash

package/after-install.md

@@ -9,3 +9,5 @@ hermes tinyfish setup
 No key yet? Create one at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys?source=hermes) — Search and Fetch are free. `setup` will ask for it.
 
 Check anytime with `hermes tinyfish doctor --live` or `/tinyfish-status` in a session.
+
+Signed-in sites: ask Hermes to create a TinyFish profile for a site, sign in at the link it gives you, and `tinyfish_agent` runs as you.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/hermes",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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,6 +1,6 @@
 name: tinyfish
-version: 0.2.3
-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."
+version: 0.2.5
+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, signed in through saved profiles when needed."
 author: TinyFish
 kind: backend
 # 0.19 added the pre_tool_call approve directive; older Hermes would skip credit approval.
@@ -13,6 +13,11 @@ provides_browser_providers:
   - tinyfish
 provides_tools:
   - tinyfish_agent
+  - tinyfish_list_profiles
+  - tinyfish_create_profile
+  - tinyfish_profile_sign_in
+  - tinyfish_update_profile
+  - tinyfish_delete_profile
 provides_hooks:
   - pre_tool_call
   - pre_llm_call

package/pyproject.toml

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

package/tinyfish_hermes/__init__.py

@@ -48,6 +48,7 @@ def register(ctx: Any) -> None:
     from .agent_tool import TINYFISH_AGENT_SCHEMA, tinyfish_agent
     from .browser_provider import TinyFishBrowserProvider, shutdown_cleanup
     from .credit_policy import pre_tool_call_policy
+    from .profile_tools import PROFILE_TOOLS
     from .provider import TinyFishWebSearchProvider, _api_key
     from .routing_context import routing_context_hook
     from .setup_cli import (
@@ -65,16 +66,20 @@ def register(ctx: Any) -> None:
         ctx.register_hook("pre_tool_call", pre_tool_call_policy)
         ctx.register_hook("pre_llm_call", routing_context_hook)
         ctx.register_hook("on_session_finalize", shutdown_cleanup)
-    # tinyfish_agent spends credits, so it also needs the pre_tool_call gate.
+    # Agent credits and profile delete approval both rely on the pre_tool_call gate.
     if hasattr(ctx, "register_hook") and hasattr(ctx, "register_tool"):
-        ctx.register_tool(
-            name="tinyfish_agent",
-            toolset="tinyfish",
-            schema=TINYFISH_AGENT_SCHEMA,
-            handler=tinyfish_agent,
-            check_fn=lambda: bool(_api_key()),
-            emoji="🐟",
-        )
+        for schema, handler in (
+            (TINYFISH_AGENT_SCHEMA, tinyfish_agent),
+            *PROFILE_TOOLS,
+        ):
+            ctx.register_tool(
+                name=schema["name"],
+                toolset="tinyfish",
+                schema=schema,
+                handler=handler,
+                check_fn=lambda: bool(_api_key()),
+                emoji="🐟",
+            )
 
     if hasattr(ctx, "register_cli_command"):
 

package/tinyfish_hermes/agent_tool.py

@@ -7,6 +7,7 @@ import time
 from typing import Any
 
 from . import rest_client
+from .profile_tools import PROFILE_TERM, error_json
 from .provider import MISSING_KEY_ERROR, _api_key, _is_interrupted
 
 TERMINAL_STATUSES = frozenset({"COMPLETED", "FAILED", "CANCELLED"})
@@ -21,8 +22,11 @@ TINYFISH_AGENT_SCHEMA: dict[str, Any] = {
     "description": (
         "Run a TinyFish web agent on a real website to complete a goal: navigate, "
         "click, fill forms, and extract data across multiple pages. Use for "
-        "multi-step site tasks that web_search/web_extract cannot do. Consumes "
-        "TinyFish credits. Returns the agent's result as JSON."
+        "multi-step site tasks that web_search/web_extract cannot do. If the site "
+        "needs sign-in, call tinyfish_list_profiles and pass the profile_id that "
+        "covers it. Ask the user before buying, posting, sending, or changing "
+        "account settings. Consumes TinyFish credits. Returns the agent's result "
+        "as JSON."
     ),
     "parameters": {
         "type": "object",
@@ -43,7 +47,22 @@ TINYFISH_AGENT_SCHEMA: dict[str, Any] = {
             "proxy_country_code": {
                 "type": "string",
                 "enum": ["US", "GB", "CA", "DE", "FR", "JP", "AU"],
-                "description": "Route through a proxy in this country.",
+                "description": (
+                    "Route through a proxy in this country. A profile's own proxy "
+                    "country overrides this."
+                ),
+            },
+            "use_profile": {
+                "type": "boolean",
+                "description": (
+                    f"Run signed in with the user's default profile. {PROFILE_TERM}"
+                ),
+            },
+            "profile_id": {
+                "type": "string",
+                "description": (
+                    "Run signed in with this profile from tinyfish_list_profiles."
+                ),
             },
         },
         "required": ["url", "goal"],
@@ -68,8 +87,19 @@ def _result(payload: dict[str, Any]) -> str:
 
 
 def _summary(run: dict[str, Any]) -> dict[str, Any]:
-    keys = ("run_id", "status", "result", "error", "streaming_url")
-    return {key: run[key] for key in keys if run.get(key) is not None}
+    keys = ("run_id", "status", "result", "error", "streaming_url", "profile_hint")
+    summary = {key: run[key] for key in keys if run.get(key) is not None}
+    # Failed runs nest the hint under error, and its relative link opens outside Hermes.
+    for holder in (summary, summary.get("error")):
+        if not isinstance(holder, dict):
+            continue
+        hint = holder.get("profile_hint")
+        if isinstance(hint, dict) and str(hint.get("setup_url") or "").startswith("/"):
+            holder["profile_hint"] = {
+                **hint,
+                "setup_url": rest_client.AGENT_URL + hint["setup_url"],
+            }
+    return summary
 
 
 def tinyfish_agent(args: dict[str, Any], **_: Any) -> str:
@@ -88,9 +118,11 @@ def tinyfish_agent(args: dict[str, Any], **_: Any) -> str:
             api_key=api_key,
             browser_profile=str(args.get("browser_profile") or "lite"),
             proxy_country_code=args.get("proxy_country_code") or None,
+            use_profile=args.get("use_profile") is True,
+            profile_id=str(args.get("profile_id") or "").strip() or None,
         )
     except rest_client.TinyFishRestError as exc:
-        return json.dumps({"error": str(exc)})
+        return error_json(exc)
     run_id = str(started.get("run_id") or "")
     if not run_id:
         return json.dumps({"error": "TinyFish Agent did not return a run_id."})

package/tinyfish_hermes/credit_policy.py

@@ -115,6 +115,20 @@ def _directive_for_feature(
     return None
 
 
+def _profile_label(profile_id: str) -> str:
+    from . import rest_client
+    from .provider import _api_key
+
+    # The approver needs the real name, not the agent's claim; the id alone still works.
+    try:
+        name = rest_client.get_profile(profile_id, api_key=_api_key(), timeout=5.0).get(
+            "name"
+        )
+    except Exception:
+        return profile_id
+    return f"'{name}' ({profile_id})" if name else profile_id
+
+
 def pre_tool_call_policy(
     tool_name: str, args: dict[str, Any] | None = None, **_: Any
 ) -> dict[str, str] | None:
@@ -125,6 +139,15 @@ def pre_tool_call_policy(
 
     if tool_name == "tinyfish_agent":
         return _directive_for_feature("agent", tool_name, target)
+    if tool_name == "tinyfish_delete_profile":
+        profile_id = str(params.get("profile_id") or "")
+        label = _profile_label(profile_id)
+        # Keyed per profile so one approval never covers deleting a different profile.
+        return {
+            "action": "approve",
+            "message": f"Permanently delete TinyFish profile {label}?",
+            "rule_key": f"tinyfish:profile_delete:{profile_id}",
+        }
     if not tool_name.startswith("browser_"):
         return None
     config = load_config()

package/tinyfish_hermes/profile_tools.py

@@ -0,0 +1,272 @@
+"""Browser Context Profile tools: saved website sign-ins for ``tinyfish_agent``."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from http import HTTPStatus
+from typing import Any
+from urllib.parse import quote, urlencode, urlparse
+
+from . import rest_client
+from .provider import MISSING_KEY_ERROR, _api_key
+
+PROFILE_TERM = (
+    "A TinyFish Browser Context Profile is a saved website sign-in "
+    "(not a Hermes profile, and unrelated to browser_profile)."
+)
+_SUMMARY_KEYS = ("id", "name", "is_default", "proxy_country_code", "domain_count")
+
+_PROFILE_ID = {
+    "type": "string",
+    "description": "Profile id from tinyfish_list_profiles.",
+}
+_SITE = {
+    "type": "string",
+    "description": "Site the user will sign in to, e.g. amazon.com or a URL on it.",
+}
+_PROXY = {
+    "type": "string",
+    "description": (
+        "Proxy country for both sign-in and runs on this profile, as an ISO 3166-1 "
+        "alpha-2 code such as US; 'none' connects directly. Set one when a site "
+        "blocks the sign-in page or needs a local IP. Overrides tinyfish_agent's "
+        "proxy_country_code."
+    ),
+}
+_NO_PROXY = frozenset({"none", "off", "direct"})
+
+
+def _schema(
+    name: str, description: str, properties: dict[str, Any], required: list[str]
+) -> dict[str, Any]:
+    return {
+        "name": name,
+        "description": description,
+        "parameters": {
+            "type": "object",
+            "properties": properties,
+            "required": required,
+        },
+    }
+
+
+LIST_SCHEMA = _schema(
+    "tinyfish_list_profiles",
+    f"List the user's TinyFish Browser Context Profiles. {PROFILE_TERM} For a site "
+    "that needs sign-in, pass the profile_id whose signed_in_sites covers it (an "
+    "entry covers its subdomains) to tinyfish_agent; if signed_in_sites is absent, "
+    "match by name and ask the user. Free.",
+    {},
+    [],
+)
+CREATE_SCHEMA = _schema(
+    "tinyfish_create_profile",
+    "Create a TinyFish Browser Context Profile and get the link where the user "
+    f"signs in. {PROFILE_TERM} Name one per account, e.g. 'Amazon Personal'. Free "
+    "until the user opens the link.",
+    {
+        "name": {"type": "string", "description": "Profile name, 1-100 characters."},
+        "site": _SITE,
+        "set_as_default": {
+            "type": "boolean",
+            "description": "Make this the profile use_profile picks by default.",
+        },
+        "proxy_country_code": _PROXY,
+    },
+    ["name"],
+)
+SIGN_IN_SCHEMA = _schema(
+    "tinyfish_profile_sign_in",
+    "Get a link where the user signs in to a site on an existing TinyFish Browser "
+    "Context Profile, to add a site or refresh an expired sign-in. Free until the "
+    "user opens it.",
+    {"profile_id": _PROFILE_ID, "site": _SITE},
+    ["profile_id"],
+)
+UPDATE_SCHEMA = _schema(
+    "tinyfish_update_profile",
+    "Rename a TinyFish Browser Context Profile, make it the default, or change "
+    "its proxy country (e.g. when a site blocks the sign-in link).",
+    {
+        "profile_id": _PROFILE_ID,
+        "name": {"type": "string", "description": "New name, 1-100 characters."},
+        "set_as_default": {
+            "type": "boolean",
+            "description": "true makes this the default profile; false is ignored.",
+        },
+        "proxy_country_code": _PROXY,
+    },
+    ["profile_id"],
+)
+DELETE_SCHEMA = _schema(
+    "tinyfish_delete_profile",
+    "Permanently delete a TinyFish Browser Context Profile and its saved sign-ins. "
+    "Only when the user asks; name the profile to them first. It cannot be undone. "
+    "Deletes one profile per call: to delete several, call once per profile, one "
+    "after another, never in parallel or batched.",
+    {"profile_id": _PROFILE_ID},
+    ["profile_id"],
+)
+
+
+def setup_url(profile_id: str, site: str = "") -> str:
+    query = {"domain": site} if site else {}
+    query["source"] = "hermes"
+    path = f"/profiles/{quote(profile_id, safe='')}/setup"
+    return f"{rest_client.AGENT_URL}{path}?{urlencode(query)}"
+
+
+def site_host(site: str) -> str:
+    # The setup page ignores anything but a bare hostname.
+    value = site.strip()
+    if not value:
+        return ""
+    host = urlparse(value if "://" in value else f"https://{value}").hostname or ""
+    if "." not in host:
+        raise ValueError(f"'{site}' is not a site; pass a domain such as amazon.com.")
+    return host
+
+
+def sign_in_next_step(profile_id: str) -> str:
+    return (
+        "Give the user setup_url. They may be asked to sign in to TinyFish first; "
+        "that is expected. They then sign in to the site and click Save profile; "
+        "never ask for their password. Wait until they say they are done, check "
+        "tinyfish_list_profiles (if signed_in_sites is absent, take their word), "
+        f'then run tinyfish_agent with profile_id "{profile_id}". If the site blocks '
+        "the sign-in page, set proxy_country_code with tinyfish_update_profile and "
+        "send the same link again."
+    )
+
+
+def error_next_step(exc: rest_client.TinyFishRestError) -> str | None:
+    message = str(exc).lower()
+    if "no default browser context profile" in message:
+        return (
+            "Call tinyfish_list_profiles and pass a profile_id; if there are none, "
+            "call tinyfish_create_profile and give the user setup_url."
+        )
+    if "not found" in message and "profile" in message:
+        return "Call tinyfish_list_profiles and use an exact profile_id from it."
+    if exc.status == HTTPStatus.CONFLICT:
+        return "Wait for the previous call on this profile to finish, then retry."
+    return None
+
+
+def error_json(exc: rest_client.TinyFishRestError) -> str:
+    payload = {"error": str(exc)}
+    next_step = error_next_step(exc)
+    if next_step:
+        payload["next_step"] = next_step
+    return json.dumps(payload)
+
+
+def _summary(profile: dict[str, Any]) -> dict[str, Any]:
+    out = {key: profile.get(key) for key in _SUMMARY_KEYS}
+    sites = profile.get("signed_in_sites")
+    if isinstance(sites, list):
+        out["signed_in_sites"] = [s.get("site") for s in sites if isinstance(s, dict)]
+    return out
+
+
+def _with_key(
+    handler: Callable[[dict[str, Any], str], dict[str, Any]],
+) -> Callable[..., str]:
+    def run(args: dict[str, Any], **_: Any) -> str:
+        api_key = _api_key()
+        if not api_key:
+            return json.dumps({"error": MISSING_KEY_ERROR})
+        try:
+            return json.dumps(handler(args or {}, api_key), ensure_ascii=False)
+        except ValueError as exc:
+            return json.dumps({"error": str(exc)})
+        except rest_client.TinyFishRestError as exc:
+            return error_json(exc)
+
+    return run
+
+
+def _required(args: dict[str, Any], key: str) -> str:
+    value = str(args.get(key) or "").strip()
+    if not value:
+        raise ValueError(f"{key} is required.")
+    return value
+
+
+def _list(args: dict[str, Any], api_key: str) -> dict[str, Any]:
+    profiles = rest_client.list_profiles(api_key=api_key).get("profiles") or []
+    return {"profiles": [_summary(p) for p in profiles if isinstance(p, dict)]}
+
+
+def _proxy_fields(args: dict[str, Any]) -> dict[str, Any]:
+    value = str(args.get("proxy_country_code") or "").strip()
+    if not value:
+        return {}
+    if value.lower() in _NO_PROXY:
+        return {"proxy_country_code": None}
+    if len(value) != 2 or not value.isalpha():
+        raise ValueError(
+            f"proxy_country_code '{value}' must be a 2-letter country code or 'none'."
+        )
+    return {"proxy_country_code": value.upper()}
+
+
+def _create(args: dict[str, Any], api_key: str) -> dict[str, Any]:
+    fields: dict[str, Any] = {"name": _required(args, "name")}
+    site = site_host(str(args.get("site") or ""))
+    if args.get("set_as_default") is not None:
+        fields["set_as_default"] = bool(args["set_as_default"])
+    fields.update(_proxy_fields(args))
+    profile = rest_client.create_profile(fields, api_key=api_key)
+    profile_id = str(profile.get("id") or "")
+    if not profile_id:
+        raise rest_client.TinyFishRestError(
+            "TinyFish Profiles did not return a profile id."
+        )
+    return {
+        **_summary(profile),
+        "setup_url": setup_url(profile_id, site),
+        "next_step": sign_in_next_step(profile_id),
+    }
+
+
+def _sign_in(args: dict[str, Any], api_key: str) -> dict[str, Any]:
+    profile_id = _required(args, "profile_id")
+    site = site_host(str(args.get("site") or ""))
+    return {
+        "profile_id": profile_id,
+        "setup_url": setup_url(profile_id, site),
+        "next_step": sign_in_next_step(profile_id),
+    }
+
+
+def _update(args: dict[str, Any], api_key: str) -> dict[str, Any]:
+    profile_id = _required(args, "profile_id")
+    fields: dict[str, Any] = {}
+    name = str(args.get("name") or "").strip()
+    if name:
+        fields["name"] = name
+    if args.get("set_as_default") is True:
+        fields["set_as_default"] = True
+    fields.update(_proxy_fields(args))
+    if not fields:
+        raise ValueError(
+            "Nothing to update: pass name, proxy_country_code, or set_as_default true."
+        )
+    return _summary(rest_client.update_profile(profile_id, fields, api_key=api_key))
+
+
+def _delete(args: dict[str, Any], api_key: str) -> dict[str, Any]:
+    profile_id = _required(args, "profile_id")
+    rest_client.delete_profile(profile_id, api_key=api_key)
+    return {"profile_id": profile_id, "deleted": True}
+
+
+PROFILE_TOOLS: tuple[tuple[dict[str, Any], Callable[..., str]], ...] = (
+    (LIST_SCHEMA, _with_key(_list)),
+    (CREATE_SCHEMA, _with_key(_create)),
+    (SIGN_IN_SCHEMA, _with_key(_sign_in)),
+    (UPDATE_SCHEMA, _with_key(_update)),
+    (DELETE_SCHEMA, _with_key(_delete)),
+)

package/tinyfish_hermes/provider.py

@@ -28,20 +28,20 @@ MISSING_KEY_ERROR = (
 )
 
 
-def _provider_env(name: str) -> str:
-    """Read Hermes config-aware environment values when available."""
+def _secret(name: str) -> str:
+    """Read a credential through Hermes' profile-aware secret scope."""
 
     try:
-        from agent.web_search_provider import get_provider_env
-
-        return str(get_provider_env(name) or "").strip()
-    except Exception:
+        from agent.secret_scope import get_secret_str
+    except ImportError:  # Hermes before profile secret scopes (2026-06)
         return str(os.getenv(name, "") or "").strip()
+    # Let UnscopedSecretError raise; os.environ there holds another profile's key.
+    return str(get_secret_str(name) or "").strip()
 
 
 def _api_key() -> str:
     for name in API_KEY_ENV_VARS:
-        value = _provider_env(name)
+        value = _secret(name)
         if value:
             return value
     return ""

package/tinyfish_hermes/rest_client.py

@@ -2,9 +2,14 @@
 
 from __future__ import annotations
 
+import hashlib
 import math
+import os
+import sys
 import time
+import uuid
 from typing import Any, NoReturn, cast
+from urllib.parse import quote
 
 import httpx
 
@@ -17,6 +22,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})
@@ -52,6 +58,15 @@ def _json_headers(api_key: str) -> dict[str, str]:
     return headers
 
 
+def _server_message(response: httpx.Response) -> str:
+    try:
+        error = response.json().get("error")
+    except Exception:
+        return ""
+    message = error.get("message") if isinstance(error, dict) else None
+    return message[:500] if isinstance(message, str) else ""
+
+
 def _raise_http_error(service: str, exc: httpx.HTTPStatusError) -> NoReturn:
     status = exc.response.status_code
     if status == 402:
@@ -60,7 +75,12 @@ def _raise_http_error(service: str, exc: httpx.HTTPStatusError) -> NoReturn:
             "TinyFish credits or billing may be required.",
             status,
         ) from exc
-    raise TinyFishRestError(f"{service} returned HTTP {status}", status) from exc
+    # 4xx text is TinyFish's own validation message and tells the agent what to fix.
+    detail = _server_message(exc.response) if 400 <= status < 500 else ""
+    suffix = f": {detail}" if detail else ""
+    raise TinyFishRestError(
+        f"{service} returned HTTP {status}{suffix}", status
+    ) from exc
 
 
 def search(
@@ -289,6 +309,7 @@ def _agent_request(
     api_key: str,
     json_body: dict[str, Any] | None = None,
     timeout: float = 30.0,
+    service: str = "TinyFish Agent",
 ) -> dict[str, Any]:
     try:
         response = httpx.request(
@@ -301,13 +322,13 @@ def _agent_request(
         response.raise_for_status()
         data = response.json()
     except httpx.HTTPStatusError as exc:
-        _raise_http_error("TinyFish Agent", exc)
+        _raise_http_error(service, exc)
     except httpx.RequestError as exc:
-        raise TinyFishRestError(f"Could not reach TinyFish Agent: {exc}") from exc
+        raise TinyFishRestError(f"Could not reach {service}: {exc}") from exc
     except ValueError as exc:
-        raise TinyFishRestError("TinyFish Agent returned invalid JSON") from exc
+        raise TinyFishRestError(f"{service} returned invalid JSON") from exc
     if not isinstance(data, dict):
-        raise TinyFishRestError("TinyFish Agent returned an unexpected response")
+        raise TinyFishRestError(f"{service} returned an unexpected response")
     return data
 
 
@@ -318,6 +339,8 @@ def start_run(
     api_key: str,
     browser_profile: str = "lite",
     proxy_country_code: str | None = None,
+    use_profile: bool = False,
+    profile_id: str | None = None,
 ) -> dict[str, Any]:
     """Enqueue a TinyFish Agent run; returns immediately with ``run_id``."""
 
@@ -329,14 +352,99 @@ def start_run(
     }
     if proxy_country_code:
         body["proxy_config"] = {"enabled": True, "country_code": proxy_country_code}
+    # The API rejects profile_id without use_profile, so an id implies it.
+    if use_profile or profile_id:
+        body["use_profile"] = True
+    if profile_id:
+        body["profile_id"] = profile_id
     return _agent_request(
         "POST", "/v1/automation/run-async", api_key=api_key, json_body=body
     )
 
 
+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)
 
 
 def cancel_run(run_id: str, *, api_key: str) -> dict[str, Any]:
     return _agent_request("POST", f"/v1/runs/{run_id}/cancel", api_key=api_key)
+
+
+def _profile_request(
+    method: str,
+    path: str,
+    *,
+    api_key: str,
+    json_body: dict[str, Any] | None = None,
+    timeout: float = 30.0,
+) -> dict[str, Any]:
+    return _agent_request(
+        method,
+        f"/v1/profiles{path}",
+        api_key=api_key,
+        json_body=json_body,
+        timeout=timeout,
+        service="TinyFish Profiles",
+    )
+
+
+def _profile_path(profile_id: str) -> str:
+    return "/" + quote(profile_id, safe="")
+
+
+def list_profiles(*, api_key: str) -> dict[str, Any]:
+    return _profile_request("GET", "", api_key=api_key)
+
+
+def create_profile(fields: dict[str, Any], *, api_key: str) -> dict[str, Any]:
+    return _profile_request("POST", "", api_key=api_key, json_body=fields)
+
+
+def get_profile(
+    profile_id: str, *, api_key: str, timeout: float = 30.0
+) -> dict[str, Any]:
+    return _profile_request(
+        "GET", _profile_path(profile_id), api_key=api_key, timeout=timeout
+    )
+
+
+def update_profile(
+    profile_id: str, fields: dict[str, Any], *, api_key: str
+) -> dict[str, Any]:
+    return _profile_request(
+        "PATCH", _profile_path(profile_id), api_key=api_key, json_body=fields
+    )
+
+
+def delete_profile(profile_id: str, *, api_key: str) -> dict[str, Any]:
+    return _profile_request("DELETE", _profile_path(profile_id), api_key=api_key)

package/tinyfish_hermes/setup_cli.py

@@ -30,6 +30,7 @@ from .provider import (
     MISSING_KEY_ERROR,
     TinyFishWebSearchProvider,
     _api_key,
+    _secret,
 )
 from .routing_context import tinyfish_mcp_configured
 
@@ -51,6 +52,11 @@ def setup_tinyfish_cli(parser: argparse.ArgumentParser) -> None:
     setup.add_argument(
         "--live", action="store_true", help="Run live doctor checks after setup"
     )
+    setup.add_argument(
+        "--share-usage",
+        action="store_true",
+        help="Send TinyFish the setup outcome (sets tinyfish.telemetry: true)",
+    )
 
     status = sub.add_parser("status", help="Print non-secret TinyFish status")
     status.add_argument(
@@ -140,15 +146,6 @@ def _save_config(config: dict[str, Any]) -> None:
     save_config(config)
 
 
-def _get_env(name: str) -> str:
-    try:
-        from hermes_cli.config import get_env_value
-
-        return str(get_env_value(name) or "").strip()
-    except Exception:
-        return str(os.getenv(name, "") or "").strip()
-
-
 def _save_env_secure(name: str, value: str) -> dict[str, Any]:
     from hermes_cli.config import save_env_value_secure
 
@@ -166,7 +163,7 @@ def _read_saved_env(name: str) -> str:
 
 def _api_key_env_var() -> str:
     for name in API_KEY_ENV_VARS:
-        if _get_env(name):
+        if _secret(name):
             return name
     return ""
 
@@ -251,26 +248,71 @@ def _store_api_key(api_key: str) -> bool:
     return False
 
 
+TELEMETRY_QUESTION = (
+    "Share setup results with TinyFish (outcome, plugin version, OS and a hash "
+    "of your API key, never the key)?"
+)
+
+
+def _share_usage(args: argparse.Namespace) -> bool:
+    """Opt-in only: the flag, a saved tinyfish.telemetry, or a y/N answer."""
+
+    # Profile-scoped, so an opt-out in this profile's .env counts.
+    if rest_client.telemetry_disabled(_secret("TINYFISH_NO_TELEMETRY")):
+        return False
+    config = _load_config()
+    section = config.get("tinyfish")
+    if not isinstance(section, dict):
+        section = config["tinyfish"] = {}
+    if getattr(args, "share_usage", False):
+        choice = True
+    elif isinstance(section.get("telemetry"), bool):
+        return bool(section["telemetry"])
+    elif getattr(args, "yes", False) or not sys.stdin.isatty():
+        return False
+    else:
+        choice = _confirm(TELEMETRY_QUESTION, default=False)
+    section["telemetry"] = choice
+    _save_config(config)
+    return choice
+
+
 def cmd_setup(
     args: argparse.Namespace,
     *,
     provider: TinyFishWebSearchProvider | None = None,
 ) -> int:
+    share_usage = _share_usage(args)
     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:
+        if not share_usage:
+            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 +326,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)