@tiny-fish/hermes 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,12 @@
 # TinyFish for Hermes Agent
 
-`tinyfish-hermes` is the first-party TinyFish plugin for [Hermes Agent](https://github.com/NousResearch/Hermes-Agent). It registers a `tinyfish` web provider that serves Hermes' web search and extract tools through the TinyFish Search and Fetch REST APIs, plus a `tinyfish` cloud browser provider for credit-gated remote browser sessions.
+`tinyfish-hermes` is the first-party TinyFish plugin for [Hermes Agent](https://github.com/NousResearch/Hermes-Agent). It gives Hermes:
+
+| Capability | How |
+| ---------- | --- |
+| 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 |
 
 ## Install
 
@@ -19,7 +25,7 @@ hermes plugins install tinyfish-io/tinyfish-web-agent-integrations/hermes --enab
 
 ## Authentication
 
-The plugin authenticates with a TinyFish API key — create one at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys). Keys are resolved in order:
+The plugin authenticates with a TinyFish API key — create one at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys?source=hermes). `hermes plugins install` and `hermes tinyfish setup` both prompt for it (hidden input); `setup` also verifies it with one free search. Keys are resolved in order:
 
 | Env var | Source |
 | ------- | ------ |
@@ -35,7 +41,7 @@ The plugin registers a `hermes tinyfish` command and an in-session `/tinyfish-st
 | `setup [--yes] [--api-key KEY] [--no-web-backend] [--live]` | Route web tools to TinyFish and save the API key |
 | `status [--json]` | Non-secret configuration status |
 | `doctor [--json] [--live] [--live-paid]` | Diagnostics; `--live` runs one real search+fetch, `--live-paid` a browser session per credit policy |
-| `credits {status,set,reset}` | Inspect or change `tinyfish.credit_policy.browser` |
+| `credits {status,set,reset}` | Inspect or change `tinyfish.credit_policy.{browser,agent}` |
 | `browser {enable,disable,status}` | Toggle `browser.cloud_provider: tinyfish` |
 | `usage [--json]` | Wallet balance, auto-reload, and billing rates |
 
@@ -57,19 +63,20 @@ tinyfish:
     location: US          # also: language, recency_minutes, after_date,
     domain_type: news     # before_date, page, purpose
   fetch:
-    format: markdown      # default output format for extract
-    ttl: 300              # also: per_url_timeout_ms, links, image_links
+    ttl: 300              # also: per_url_timeout_ms (default 90000), links, image_links
 ```
 
 ## Browser sessions
 
-Setting `browser.cloud_provider: tinyfish` routes Hermes' browser tools through TinyFish remote browser sessions. Each session consumes TinyFish credits, so sessions are policy-gated via `tinyfish.credit_policy.browser`:
+Setting `browser.cloud_provider: tinyfish` routes Hermes' browser tools — the default Browser Use `browser_exec`, or the built-in `browser_*` tools with `browser.backend: off` — through TinyFish remote browser sessions. Sessions consume TinyFish credits, so they are policy-gated via `tinyfish.credit_policy.browser`; `tinyfish_agent` runs use `tinyfish.credit_policy.agent`:
 
 | Policy | Behavior |
 | ------ | -------- |
-| `request` (default) | Every session goes through Hermes' approval gate |
-| `allow` | Sessions start without per-session approval |
-| `deny` | Browser tools are blocked while routed to TinyFish |
+| `request` (default) | Opening a session (or starting an agent run) goes through Hermes' approval gate; answer `[s]ession` to approve the rest of the session |
+| `allow` | No approval prompt |
+| `deny` | Blocked |
+
+One-shot `hermes chat -q` runs skip Hermes' own browser cleanup at exit, so the plugin closes any TinyFish sessions still open when they finish.
 
 ```yaml
 browser:
@@ -91,12 +98,9 @@ When the `tinyfish` MCP server is also configured in Hermes (`mcp_servers.tinyfi
 python -m pip install -e . -r requirements-dev.txt  # dev deps are version-bounded in requirements-dev.txt
 make lint
 make test
+scripts/e2e.sh  # real Hermes: validate, doctor, git install; live Search/Fetch with TINYFISH_API_KEY
 ```
 
-## Credits
-
-The provider architecture is ported from [gabeosx/hermes-plugin-tinyfish](https://github.com/gabeosx/hermes-plugin-tinyfish) (MIT), an independent community plugin. Both plugins register a web provider named `tinyfish`, so install only one of them.
-
 ## License
 
 MIT

package/after-install.md

@@ -0,0 +1,11 @@
+# TinyFish installed
+
+**Next:** route Hermes' web tools to TinyFish and verify your key:
+
+```bash
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/hermes",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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",
@@ -24,6 +24,7 @@
   "files": [
     "tinyfish_hermes/*.py",
     "plugin.yaml",
+    "after-install.md",
     "pyproject.toml",
     "__init__.py"
   ],

package/plugin.yaml

@@ -1,13 +1,26 @@
 name: tinyfish
-version: 0.1.1
-description: "First-party TinyFish provider plugin for Hermes Agent: Search and Fetch over the TinyFish REST APIs with API-key auth, plus credit-gated Browser sessions."
+version: 0.2.0
+description: "First-party TinyFish plugin for Hermes Agent: free Search and Fetch, plus credit-gated Browser sessions and the tinyfish_agent web agent."
 author: TinyFish
 kind: backend
+# 0.19 added the pre_tool_call approve directive; older Hermes would skip credit approval.
+requires_hermes: ">=0.19"
+# httpx ships with Hermes core; without this Hermes prompts for deps and leaves non-TTY installs disabled.
+python_runtime: external
 provides_web_providers:
   - tinyfish
 provides_browser_providers:
   - tinyfish
+provides_tools:
+  - tinyfish_agent
+provides_hooks:
+  - pre_tool_call
+  - pre_llm_call
+  - on_session_finalize
 requires_env:
-  - TINYFISH_API_KEY
+  - name: TINYFISH_API_KEY
+    description: "TinyFish API key (Search and Fetch are free)"
+    url: "https://agent.tinyfish.ai/api-keys?source=hermes"
+    secret: true
 homepage: "https://tinyfish.ai"
 license: MIT

package/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tinyfish-hermes"
-version = "0.1.1"
-description = "TinyFish web provider plugin for Hermes Agent - Search and Fetch over the TinyFish REST APIs"
+version = "0.2.0"
+description = "TinyFish plugin for Hermes Agent - Search, Fetch, Browser, and the tinyfish_agent web agent"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"

package/tinyfish_hermes/__init__.py

@@ -45,9 +45,10 @@ __version__ = _resolve_version()
 def register(ctx: Any) -> None:
     """Register TinyFish providers, lifecycle hooks, and CLI commands with Hermes."""
 
-    from .browser_provider import TinyFishBrowserProvider
+    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 .provider import TinyFishWebSearchProvider
+    from .provider import TinyFishWebSearchProvider, _api_key
     from .routing_context import routing_context_hook
     from .setup_cli import (
         dispatch_tinyfish_cli,
@@ -63,6 +64,17 @@ def register(ctx: Any) -> None:
             ctx.register_browser_provider(TinyFishBrowserProvider())
         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.
+    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="🐟",
+        )
 
     if hasattr(ctx, "register_cli_command"):
 

package/tinyfish_hermes/agent_tool.py

@@ -0,0 +1,124 @@
+"""``tinyfish_agent``: goal-based TinyFish web automation as a Hermes tool."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+from . import rest_client
+from .provider import MISSING_KEY_ERROR, _api_key, _is_interrupted
+
+TERMINAL_STATUSES = frozenset({"COMPLETED", "FAILED", "CANCELLED"})
+# Hermes' tool batch deadline is 420s; stop polling well before it.
+POLL_BUDGET_SECONDS = 300.0
+POLL_INTERVAL_SECONDS = 3.0
+# Hermes' context pruner targets results above ~8k chars.
+MAX_RESULT_CHARS = 12_000
+
+TINYFISH_AGENT_SCHEMA: dict[str, Any] = {
+    "name": "tinyfish_agent",
+    "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."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "url": {"type": "string", "description": "Website URL to start on."},
+            "goal": {
+                "type": "string",
+                "description": (
+                    "Plain-language task, including what data to return and its "
+                    "shape, e.g. 'Return the first 5 product names and prices as JSON'."
+                ),
+            },
+            "browser_profile": {
+                "type": "string",
+                "enum": ["lite", "stealth"],
+                "description": "Use 'stealth' for sites with bot protection.",
+            },
+            "proxy_country_code": {
+                "type": "string",
+                "enum": ["US", "GB", "CA", "DE", "FR", "JP", "AU"],
+                "description": "Route through a proxy in this country.",
+            },
+        },
+        "required": ["url", "goal"],
+    },
+}
+
+
+def _result(payload: dict[str, Any]) -> str:
+    text = json.dumps(payload, ensure_ascii=False)
+    if len(text) <= MAX_RESULT_CHARS:
+        return text
+    # Partial JSON text, not the original structure, under a key that says so.
+    full = json.dumps(payload.pop("result", None), ensure_ascii=False)
+    payload["truncated"] = True
+    cut = MAX_RESULT_CHARS - len(json.dumps({**payload, "result_preview": ""}))
+    while cut > 0:
+        text = json.dumps({**payload, "result_preview": full[:cut]}, ensure_ascii=False)
+        if len(text) <= MAX_RESULT_CHARS:
+            return text
+        cut -= len(text) - MAX_RESULT_CHARS
+    return json.dumps(payload, ensure_ascii=False)
+
+
+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}
+
+
+def tinyfish_agent(args: dict[str, Any], **_: Any) -> str:
+    api_key = _api_key()
+    if not api_key:
+        return json.dumps({"error": MISSING_KEY_ERROR})
+    url = str(args.get("url") or "").strip()
+    goal = str(args.get("goal") or "").strip()
+    if not url or not goal:
+        return json.dumps({"error": "tinyfish_agent needs both url and goal."})
+
+    try:
+        started = rest_client.start_run(
+            url,
+            goal,
+            api_key=api_key,
+            browser_profile=str(args.get("browser_profile") or "lite"),
+            proxy_country_code=args.get("proxy_country_code") or None,
+        )
+    except rest_client.TinyFishRestError as exc:
+        return json.dumps({"error": str(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."})
+
+    deadline = time.monotonic() + POLL_BUDGET_SECONDS
+    run: dict[str, Any] = {"run_id": run_id, "status": "PENDING"}
+    while time.monotonic() < deadline:
+        if _is_interrupted():
+            try:
+                rest_client.cancel_run(run_id, api_key=api_key)
+            except rest_client.TinyFishRestError as exc:
+                # The run may still be billing; never claim it stopped.
+                error = f"Cancel failed, run may still be active: {exc}"
+                return json.dumps(
+                    {"run_id": run_id, "status": "UNKNOWN", "error": error}
+                )
+            return json.dumps({"run_id": run_id, "status": "CANCELLED"})
+        time.sleep(POLL_INTERVAL_SECONDS)
+        try:
+            run = rest_client.get_run(run_id, api_key=api_key)
+        except rest_client.TinyFishRestError as exc:
+            # Retry transient failures; a 4xx (bar 429) will not fix itself.
+            if exc.status and 400 <= exc.status < 500 and exc.status != 429:
+                return json.dumps({"run_id": run_id, "error": str(exc)})
+            continue
+        if str(run.get("status") or "").upper() in TERMINAL_STATUSES:
+            return _result(_summary(run))
+
+    pending = _summary(run)
+    pending["note"] = "Still running on TinyFish after 300s; give the user the run_id."
+    return _result(pending)

package/tinyfish_hermes/browser_provider.py

@@ -15,7 +15,7 @@ except Exception:  # pragma: no cover - lets the package import outside Hermes
 
 
 from . import rest_client
-from .config import credit_policy, tinyfish_config
+from .config import browser_cloud_provider, credit_policy, tinyfish_config
 from .credit_policy import block_message
 from .provider import API_KEY_URL, MISSING_KEY_ERROR, _api_key
 
@@ -81,7 +81,8 @@ class TinyFishBrowserProvider(_HermesBrowserProvider):  # type: ignore[misc]
             raise RuntimeError(
                 "TinyFish Browser did not return session_id and cdp_url."
             )
-        session_name = f"tinyfish_{task_id}_{uuid.uuid4().hex[:8]}"
+        # hermes_* lets Hermes' orphan reaper clean up after a crash.
+        session_name = f"hermes_tf_{uuid.uuid4().hex[:10]}"
         logger.info("Created TinyFish browser session")
         return {
             "session_name": session_name,
@@ -131,3 +132,17 @@ class TinyFishBrowserProvider(_HermesBrowserProvider):  # type: ignore[misc]
             ],
             "post_setup": "agent_browser",
         }
+
+
+def shutdown_cleanup(**kwargs: Any) -> None:
+    """``on_session_finalize`` hook: ``-q`` runs skip Hermes' atexit browser cleanup."""
+
+    # Other reasons (/new, idle) finalize one session while the process keeps others.
+    if kwargs.get("reason") != "shutdown" or browser_cloud_provider() != "tinyfish":
+        return
+    try:
+        from tools.browser_tool_lifecycle import cleanup_all_browsers
+
+        cleanup_all_browsers()
+    except Exception as exc:
+        logger.debug("TinyFish shutdown cleanup failed (%s)", type(exc).__name__)

package/tinyfish_hermes/config.py

@@ -4,10 +4,10 @@ from __future__ import annotations
 
 from typing import Any, Literal
 
-CreditFeature = Literal["browser"]
+CreditFeature = Literal["browser", "agent"]
 CreditPolicy = Literal["deny", "request", "allow"]
 
-CREDIT_FEATURES: tuple[CreditFeature, ...] = ("browser",)
+CREDIT_FEATURES: tuple[CreditFeature, ...] = ("browser", "agent")
 CREDIT_POLICIES: tuple[CreditPolicy, ...] = ("deny", "request", "allow")
 # 'request' is inert until browser.cloud_provider is tinyfish, and still
 # routes each session through Hermes approval once it is.
@@ -39,10 +39,13 @@ def tinyfish_config(config: dict[str, Any] | None = None) -> dict[str, Any]:
 
 
 def normalize_feature(value: str) -> CreditFeature:
-    if value.strip().lower().replace("_", "-") == "browser":
+    feature = value.strip().lower().replace("_", "-")
+    if feature == "browser":
         return "browser"
+    if feature == "agent":
+        return "agent"
     raise ValueError(
-        f"Unknown TinyFish credit feature '{value}'. Valid features: browser"
+        f"Unknown TinyFish credit feature '{value}'. Valid features: browser, agent"
     )
 
 
@@ -155,10 +158,3 @@ def fetch_options(config: dict[str, Any] | None = None) -> FetchOptions:
         if value is not None:
             options[key] = value
     return options
-
-
-def default_fetch_format(config: dict[str, Any] | None = None) -> str:
-    section = tinyfish_config(config).get("fetch") or {}
-    if isinstance(section, dict) and section.get("format"):
-        return str(section["format"])
-    return "markdown"

package/tinyfish_hermes/credit_policy.py

@@ -16,9 +16,15 @@ from .config import (
 
 FEATURE_LABELS: dict[CreditFeature, str] = {
     "browser": "TinyFish Browser",
+    "agent": "TinyFish Agent",
 }
 
 
+def rule_key(feature: CreditFeature) -> str:
+    # Domain-free so one [s]ession answer covers every step of the session.
+    return f"tinyfish:{feature}"
+
+
 def target_domain(target: str | None) -> str:
     if not target:
         return ""
@@ -75,11 +81,8 @@ def request_credit_approval(
     try:
         from tools.approval import request_tool_approval
 
-        # Domain-grained key: one [a]lways covers the browse; new domains still prompt.
         result = request_tool_approval(
-            f"tinyfish_{normalized}",
-            reason,
-            rule_key=f"tinyfish:{normalized}:{target_domain(target)}",
+            f"tinyfish_{normalized}", reason, rule_key=rule_key(normalized)
         )
     except Exception as exc:
         return False, (
@@ -107,7 +110,7 @@ def _directive_for_feature(
         return {
             "action": "approve",
             "message": approval_reason(feature, operation, target),
-            "rule_key": f"tinyfish:{feature}:{target_domain(target)}",
+            "rule_key": rule_key(feature),
         }
     return None
 
@@ -118,11 +121,14 @@ def pre_tool_call_policy(
     """Hermes plugin hook for policy-gating TinyFish credit-consuming tools."""
 
     params = args or {}
+    target = str(params.get("url") or params.get("target") or "")
 
+    if tool_name == "tinyfish_agent":
+        return _directive_for_feature("agent", tool_name, target)
     if not tool_name.startswith("browser_"):
         return None
     config = load_config()
     if browser_cloud_provider(config) != "tinyfish":
         return None
-    target = str(params.get("url") or params.get("target") or "")
+    # Any browser_* call can open a billed session (first call, or after inactivity).
     return _directive_for_feature("browser", tool_name, target, config)

package/tinyfish_hermes/provider.py

@@ -15,16 +15,16 @@ except Exception:  # pragma: no cover - lets the package import outside Hermes
 
 
 from . import rest_client
-from .config import default_fetch_format, fetch_options, search_options
+from .config import fetch_options, search_options
 from .normalize import normalize_fetch_documents, normalize_search_response
 
 logger = logging.getLogger(__name__)
 
 API_KEY_ENV_VARS = ("TINYFISH_API_KEY", "MCP_TINYFISH_API_KEY")
-API_KEY_URL = "https://agent.tinyfish.ai/api-keys"
+API_KEY_URL = "https://agent.tinyfish.ai/api-keys?source=hermes"
 MISSING_KEY_ERROR = (
-    "TinyFish API key not found. Set TINYFISH_API_KEY or MCP_TINYFISH_API_KEY; "
-    f"create a key at {API_KEY_URL}."
+    f"TinyFish API key not found. Create one at {API_KEY_URL}, then run "
+    "`hermes tinyfish setup` (or set TINYFISH_API_KEY)."
 )
 
 
@@ -131,33 +131,18 @@ class TinyFishWebSearchProvider(_HermesWebSearchProvider):  # type: ignore[misc]
         api_key = _api_key()
         if not api_key:
             return [_error_document(url, MISSING_KEY_ERROR) for url in urls]
-        output_format = str(
-            kwargs.get("format")
-            or kwargs.get("output_format")
-            or default_fetch_format()
-        )
+        # Hermes caches extract results per requested format, so honour it verbatim.
+        output_format = str(kwargs.get("format") or "markdown")
         options = fetch_options()
-        documents: list[dict[str, Any]] = []
-        # The Fetch API caps a request at 10 URLs; oversized batches 400.
-        for start in range(0, len(urls), rest_client.FETCH_MAX_URLS):
-            if start and _is_interrupted():
-                documents.extend(
-                    _error_document(url, "Interrupted") for url in urls[start:]
-                )
-                break
-            chunk = urls[start : start + rest_client.FETCH_MAX_URLS]
-            try:
-                raw = rest_client.fetch(
-                    chunk,
-                    api_key=api_key,
-                    output_format=output_format,
-                    **options,
-                )
-                documents.extend(normalize_fetch_documents(raw, fallback_urls=chunk))
-            except Exception as exc:  # noqa: BLE001 - controlled failure envelope
-                logger.warning("TinyFish REST fetch failed (%s)", type(exc).__name__)
-                documents.extend(
-                    _error_document(url, _safe_rest_failure("fetch", exc))
-                    for url in chunk
-                )
-        return documents
+        # Hermes abandons a whole extract at 120s; per-URL timeouts keep the fast pages.
+        options.setdefault("per_url_timeout_ms", 90_000)
+        try:
+            raw = rest_client.fetch(
+                urls, api_key=api_key, output_format=output_format, **options
+            )
+        except Exception as exc:  # noqa: BLE001 - controlled failure envelope
+            logger.warning("TinyFish REST fetch failed (%s)", type(exc).__name__)
+            return [
+                _error_document(url, _safe_rest_failure("fetch", exc)) for url in urls
+            ]
+        return normalize_fetch_documents(raw, fallback_urls=urls)

package/tinyfish_hermes/rest_client.py

@@ -12,9 +12,9 @@ from . import __version__
 
 SEARCH_URL = "https://api.search.tinyfish.ai"
 FETCH_URL = "https://api.fetch.tinyfish.ai"
-FETCH_MAX_URLS = 10
 BROWSER_URL = "https://api.browser.tinyfish.ai"
-WALLET_URL = "https://agent.tinyfish.ai/v1/wallet"
+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"
 
@@ -27,6 +27,10 @@ _BROWSER_CLOSE_RETRY_BASE_SECONDS = 0.25
 class TinyFishRestError(RuntimeError):
     """Raised for TinyFish REST transport or HTTP failures."""
 
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
 
 class TinyFishWalletNotFound(TinyFishRestError):
     """Raised when an account uses legacy billing or has no wallet yet."""
@@ -52,9 +56,11 @@ def _raise_http_error(service: str, exc: httpx.HTTPStatusError) -> NoReturn:
     status = exc.response.status_code
     if status == 402:
         raise TinyFishRestError(
-            f"{service} returned HTTP 402. TinyFish credits or billing may be required."
+            f"{service} returned HTTP 402. "
+            "TinyFish credits or billing may be required.",
+            status,
         ) from exc
-    raise TinyFishRestError(f"{service} returned HTTP {status}") from exc
+    raise TinyFishRestError(f"{service} returned HTTP {status}", status) from exc
 
 
 def search(
@@ -113,8 +119,8 @@ def fetch(
     image_links: bool | None = None,
     ttl: int | None = None,
     per_url_timeout_ms: int | None = None,
-    # Batches can run ~120s server-side; docs recommend a client timeout >= 150s.
-    timeout: float = 150.0,
+    # Hermes abandons an extract at 120s, so return our own error before that.
+    timeout: float = 110.0,
 ) -> dict[str, Any]:
     """Run the TinyFish Fetch API for one or more URLs."""
 
@@ -274,3 +280,63 @@ def wallet(*, api_key: str, timeout: float = 30.0) -> dict[str, Any]:
         raise TinyFishRestError(f"Could not reach TinyFish Wallet: {exc}") from exc
     except ValueError as exc:
         raise TinyFishRestError("TinyFish Wallet returned invalid JSON") from exc
+
+
+def _agent_request(
+    method: str,
+    path: str,
+    *,
+    api_key: str,
+    json_body: dict[str, Any] | None = None,
+    timeout: float = 30.0,
+) -> dict[str, Any]:
+    try:
+        response = httpx.request(
+            method,
+            f"{AGENT_URL}{path}",
+            json=json_body,
+            headers=_json_headers(api_key),
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        data = response.json()
+    except httpx.HTTPStatusError as exc:
+        _raise_http_error("TinyFish Agent", exc)
+    except httpx.RequestError as exc:
+        raise TinyFishRestError(f"Could not reach TinyFish Agent: {exc}") from exc
+    except ValueError as exc:
+        raise TinyFishRestError("TinyFish Agent returned invalid JSON") from exc
+    if not isinstance(data, dict):
+        raise TinyFishRestError("TinyFish Agent returned an unexpected response")
+    return data
+
+
+def start_run(
+    url: str,
+    goal: str,
+    *,
+    api_key: str,
+    browser_profile: str = "lite",
+    proxy_country_code: str | None = None,
+) -> dict[str, Any]:
+    """Enqueue a TinyFish Agent run; returns immediately with ``run_id``."""
+
+    body: dict[str, Any] = {
+        "url": url,
+        "goal": goal,
+        "browser_profile": browser_profile,
+        "api_integration": "hermes",
+    }
+    if proxy_country_code:
+        body["proxy_config"] = {"enabled": True, "country_code": proxy_country_code}
+    return _agent_request(
+        "POST", "/v1/automation/run-async", api_key=api_key, json_body=body
+    )
+
+
+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)

package/tinyfish_hermes/routing_context.py

@@ -6,7 +6,8 @@ from collections.abc import Mapping, Sequence
 from typing import Any
 from urllib.parse import urlparse
 
-from .config import load_config, routing_context_enabled
+from .config import browser_cloud_provider, load_config, routing_context_enabled
+from .provider import API_KEY_URL, _api_key
 
 ROUTING_CONTEXT_MARKER = '<tinyfish-routing-context version="1">'
 ROUTING_GUIDANCE = f"""{ROUTING_CONTEXT_MARKER}
@@ -16,6 +17,18 @@ TinyFish tool-routing guidance:
 - Infer the choice from the user's plain language. Do not ask them to choose MCP versus the provider, and do not persist per-request controls as configuration. If a required native tool is unavailable, use the generic provider only when it can preserve the requested constraints; otherwise explain which control is unavailable rather than silently dropping it."""
 
 
+SETUP_CONTEXT_MARKER = '<tinyfish-setup-context version="1">'
+SETUP_GUIDANCE = f"""{SETUP_CONTEXT_MARKER}
+TinyFish is installed but has no API key, so its web search, fetch, and browser tools are unavailable. If the user needs web access, tell them to create a free key at {API_KEY_URL} and run `hermes tinyfish setup`."""
+
+
+def tinyfish_backend_configured(config: dict[str, Any]) -> bool:
+    web = config.get("web") or {}
+    web_keys = ("search_backend", "extract_backend", "backend")
+    routed = isinstance(web, dict) and "tinyfish" in {web.get(k) for k in web_keys}
+    return routed or browser_cloud_provider(config) == "tinyfish"
+
+
 def tinyfish_mcp_configured(config: dict[str, Any]) -> bool:
     servers = config.get("mcp_servers") or {}
     if not isinstance(servers, dict):
@@ -32,18 +45,20 @@ def tinyfish_mcp_configured(config: dict[str, Any]) -> bool:
     )
 
 
-def _contains_routing_marker(value: object) -> bool:
+def _contains_marker(value: object, marker: str) -> bool:
     if isinstance(value, str):
-        return ROUTING_CONTEXT_MARKER in value
+        return marker in value
     if isinstance(value, Mapping):
-        return any(_contains_routing_marker(item) for item in value.values())
+        return any(_contains_marker(item, marker) for item in value.values())
     if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
-        return any(_contains_routing_marker(item) for item in value)
+        return any(_contains_marker(item, marker) for item in value)
     return False
 
 
-def routing_guidance_present(conversation_history: object) -> bool:
-    """Return whether Hermes already carries this routing version in context."""
+def routing_guidance_present(
+    conversation_history: object, marker: str = ROUTING_CONTEXT_MARKER
+) -> bool:
+    """Return whether Hermes already carries this marker version in context."""
 
     if not isinstance(conversation_history, Sequence) or isinstance(
         conversation_history, (str, bytes, bytearray)
@@ -52,9 +67,9 @@ def routing_guidance_present(conversation_history: object) -> bool:
     for message in conversation_history:
         if not isinstance(message, Mapping):
             continue
-        if _contains_routing_marker(message.get("api_content")):
+        if _contains_marker(message.get("api_content"), marker):
             return True
-        if _contains_routing_marker(message.get("content")):
+        if _contains_marker(message.get("content"), marker):
             return True
     return False
 
@@ -62,9 +77,18 @@ def routing_guidance_present(conversation_history: object) -> bool:
 def routing_context_hook(**kwargs: Any) -> dict[str, str] | None:
     """Hermes ``pre_llm_call`` hook injecting versioned routing guidance once."""
 
+    history = kwargs.get("conversation_history")
     config = load_config()
-    if not routing_context_enabled(config) or not tinyfish_mcp_configured(config):
+    if not routing_context_enabled(config):
+        return None
+    if not _api_key():
+        if not tinyfish_backend_configured(config):
+            return None
+        if routing_guidance_present(history, SETUP_CONTEXT_MARKER):
+            return None
+        return {"context": SETUP_GUIDANCE}
+    if not tinyfish_mcp_configured(config):
         return None
-    if routing_guidance_present(kwargs.get("conversation_history")):
+    if routing_guidance_present(history):
         return None
     return {"context": ROUTING_GUIDANCE}

package/tinyfish_hermes/setup_cli.py

@@ -5,6 +5,9 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
+import shutil
+import subprocess
 import sys
 from typing import Any
 
@@ -195,6 +198,28 @@ def _prompt_secret(question: str) -> str:
         return ""
 
 
+def _prompt_for_key() -> str:
+    print(f"TinyFish needs an API key. Create one (free) at {API_KEY_URL}")
+    if _confirm("Open that page in your browser?", default=True):
+        import webbrowser
+
+        webbrowser.open(API_KEY_URL)
+    return _prompt_secret("Paste your TinyFish API key (Enter to skip): ")
+
+
+def _validate_key(api_key: str) -> str | None:
+    """Return an error message when TinyFish rejects the key; one free search."""
+
+    try:
+        rest_client.search("TinyFish", api_key=api_key, timeout=15.0)
+    except rest_client.TinyFishRestError as exc:
+        if exc.status in (401, 403):
+            return f"TinyFish rejected that API key ({exc}). Get one at {API_KEY_URL}"
+        # Network trouble shouldn't block saving a key that may be fine.
+        print(f"Warning: could not verify the key ({exc}); saving it anyway.")
+    return None
+
+
 def _apply_web_backend_config(config: dict[str, Any]) -> None:
     web = config.setdefault("web", {})
     web["search_backend"] = "tinyfish"
@@ -231,8 +256,25 @@ def cmd_setup(
     *,
     provider: TinyFishWebSearchProvider | None = None,
 ) -> int:
-    config = _load_config()
+    api_key = (getattr(args, "api_key", None) or "").strip()
+    existing = _api_key_env_var()
+    if not api_key and existing:
+        print(f"Using the TinyFish API key from {existing}")
+    elif not api_key and sys.stdin.isatty():
+        api_key = _prompt_for_key()
+    if api_key:
+        rejection = _validate_key(api_key)
+        if rejection:
+            print(rejection, file=sys.stderr)
+            return 1
+        if not _store_api_key(api_key):
+            return 1
+    elif not existing:
+        print(MISSING_KEY_ERROR, file=sys.stderr)
+        return 1
 
+    # Route web tools only once a usable key exists, so a failed setup changes nothing.
+    config = _load_config()
     if not getattr(args, "no_web_backend", False) and _confirm(
         "Set Hermes web.search_backend and web.extract_backend to tinyfish?",
         default=True,
@@ -241,17 +283,8 @@ def cmd_setup(
         _apply_web_backend_config(config)
         _save_config(config)
         print("Configured Hermes web backends to use TinyFish")
-
-    api_key = (getattr(args, "api_key", None) or "").strip()
-    if (
-        not api_key
-        and not _api_key_env_var()
-        and sys.stdin.isatty()
-        and _confirm("Add TINYFISH_API_KEY now?", default=True, assume_yes=False)
-    ):
-        api_key = _prompt_secret(f"TinyFish API key (create at {API_KEY_URL}): ")
-    if api_key and not _store_api_key(api_key):
-        return 1
+        if not _enable_toolset("web"):
+            return 1
 
     if getattr(args, "live", False):
         doctor_args = argparse.Namespace(json=False, live=True, live_paid=False)
@@ -518,6 +551,69 @@ def _policy_effect_line(policy: str) -> str:
     return "Policy 'request': each TinyFish browser session asks for approval."
 
 
+AGENT_BROWSER_SETUP = ("tools", "post-setup", "agent_browser")
+
+
+def _hermes(*args: str, capture: bool = True) -> subprocess.CompletedProcess[str]:
+    # The running interpreter is Hermes'; a `hermes` on PATH may be another install.
+    return subprocess.run(
+        [sys.executable, "-m", "hermes_cli.main", *args],
+        capture_output=capture,
+        text=True,
+        check=False,
+    )
+
+
+def _agent_browser_installed() -> bool:
+    try:
+        import pm
+
+        if pm.installed_package("agent-browser"):
+            return True
+    except Exception:  # pm is Hermes-internal; fall back to PATH
+        pass
+    return shutil.which("agent-browser") is not None
+
+
+def _toolset_disabled(name: str) -> bool | None:
+    result = _hermes("tools", "list")
+    if result.returncode != 0:
+        return None
+    return re.search(rf"\bdisabled\s+{re.escape(name)}\s", result.stdout) is not None
+
+
+def _enable_toolset(name: str) -> bool:
+    # `tools enable` pins an explicit toolset list, so only touch a disabled toolset.
+    disabled = _toolset_disabled(name)
+    if disabled is False:
+        return True
+    result = _hermes("tools", "enable", name) if disabled else None
+    if result is not None and result.returncode == 0:
+        print(f"Enabled Hermes' {name} toolset (CLI); start a new session to use it.")
+        return True
+    print(
+        f"Could not enable the {name} toolset; run `hermes tools enable {name}`.",
+        file=sys.stderr,
+    )
+    return False
+
+
+def _ensure_agent_browser() -> bool:
+    if _agent_browser_installed():
+        return True
+    command = " ".join(("hermes", *AGENT_BROWSER_SETUP))
+    print("Hermes' browser tools need the agent-browser CLI, which is not installed.")
+    if _confirm("Install it now?", default=True):
+        # post-setup exits 0 even when the install fails, so re-check instead.
+        _hermes(*AGENT_BROWSER_SETUP, capture=False)
+        if _agent_browser_installed():
+            return True
+        print(f"Install failed; retry with `{command}`.", file=sys.stderr)
+        return False
+    print(f"Install it with `{command}`.")
+    return True
+
+
 def cmd_browser(args: argparse.Namespace) -> int:
     subcommand = getattr(args, "browser_command", None) or "status"
     config = _load_config()
@@ -535,7 +631,8 @@ def cmd_browser(args: argparse.Namespace) -> int:
             _save_config(config)
             print("Set browser.cloud_provider to tinyfish.")
         print(_policy_effect_line(policy))
-        return 0
+        toolset_ok = _enable_toolset("browser")
+        return 0 if _ensure_agent_browser() and toolset_ok else 1
     if subcommand == "disable":
         if current != "tinyfish":
             print("TinyFish is not Hermes' browser cloud provider; nothing to change.")