@tiny-fish/hermes 0.1.1

package/LICENSE

@@ -0,0 +1,38 @@
+MIT License
+
+Copyright (c) 2026 Tiny Fish, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+Third-party notices
+
+The provider architecture is ported from hermes-plugin-tinyfish
+(https://github.com/gabeosx/hermes-plugin-tinyfish), used under the MIT License:
+
+MIT License
+
+Copyright (c) 2026 gabeosx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# 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.
+
+## 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:
+
+```bash
+tinyfish connect hermes
+```
+
+To install just the plugin straight from this repo (no key seeding, no backend wiring):
+
+```bash
+hermes plugins install tinyfish-io/tinyfish-web-agent-integrations/hermes --enable
+```
+
+## 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:
+
+| 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` |
+
+## CLI
+
+The plugin registers a `hermes tinyfish` command and an in-session `/tinyfish-status [live]` command:
+
+| Subcommand | Purpose |
+| ---------- | ------- |
+| `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` |
+| `browser {enable,disable,status}` | Toggle `browser.cloud_provider: tinyfish` |
+| `usage [--json]` | Wallet balance, auto-reload, and billing rates |
+
+## Configuration
+
+`hermes tinyfish setup` routes Hermes' web tools to TinyFish; the equivalent Hermes configuration is:
+
+```yaml
+web:
+  search_backend: tinyfish
+  extract_backend: tinyfish
+```
+
+Optional request tuning under a `tinyfish` section:
+
+```yaml
+tinyfish:
+  search:
+    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
+```
+
+## 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`:
+
+| 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 |
+
+```yaml
+browser:
+  cloud_provider: tinyfish
+tinyfish:
+  credit_policy:
+    browser: request
+  browser:
+    timeout_seconds: 300  # optional session timeout
+```
+
+## 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`.
+
+## Development
+
+```bash
+python -m pip install -e . -r requirements-dev.txt  # dev deps are version-bounded in requirements-dev.txt
+make lint
+make test
+```
+
+## 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/__init__.py

@@ -0,0 +1,10 @@
+"""Directory-plugin entry point loaded by ``hermes plugins install``."""
+
+from __future__ import annotations
+
+try:
+    from .tinyfish_hermes import __version__, register
+except ImportError:  # pip installs import the packaged module directly
+    from tinyfish_hermes import __version__, register
+
+__all__ = ["__version__", "register"]

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@tiny-fish/hermes",
+  "version": "0.1.1",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tinyfish-io/tinyfish-web-agent-integrations.git",
+    "directory": "hermes"
+  },
+  "author": {
+    "name": "TinyFish",
+    "email": "support@tinyfish.io",
+    "url": "https://tinyfish.ai"
+  },
+  "keywords": [
+    "hermes",
+    "tinyfish",
+    "web-search",
+    "web-fetch",
+    "ai-agent"
+  ],
+  "files": [
+    "tinyfish_hermes/*.py",
+    "plugin.yaml",
+    "pyproject.toml",
+    "__init__.py"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.yaml

@@ -0,0 +1,13 @@
+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."
+author: TinyFish
+kind: backend
+provides_web_providers:
+  - tinyfish
+provides_browser_providers:
+  - tinyfish
+requires_env:
+  - TINYFISH_API_KEY
+homepage: "https://tinyfish.ai"
+license: MIT

package/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+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"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "TinyFish", email = "support@tinyfish.io" }]
+keywords = ["hermes", "tinyfish", "web-search", "web-fetch", "ai-agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "httpx>=0.24,<1.0",
+]
+
+[project.urls]
+Homepage = "https://tinyfish.ai"
+Documentation = "https://docs.tinyfish.ai"
+Repository = "https://github.com/tinyfish-io/tinyfish-web-agent-integrations"
+
+[project.entry-points."hermes_agent.plugins"]
+tinyfish = "tinyfish_hermes"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tinyfish_hermes"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "T201", "W"]
+
+[tool.ruff.lint.per-file-ignores]
+# ROUTING_GUIDANCE is injected verbatim into LLM context, one bullet per line.
+"tinyfish_hermes/routing_context.py" = ["E501"]
+# The CLI's output medium is stdout.
+"tinyfish_hermes/setup_cli.py" = ["T201"]
+
+[tool.mypy]
+python_version = "3.10"
+# The directory-install shim (./__init__.py) would otherwise make mypy see the package twice.
+explicit_package_bases = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers --strict-config --durations=5"

package/tinyfish_hermes/__init__.py

@@ -0,0 +1,113 @@
+"""First-party TinyFish web provider plugin for Hermes Agent."""
+
+from __future__ import annotations
+
+from importlib import metadata
+from pathlib import Path
+from typing import Any
+
+_DISTRIBUTION_NAME = "tinyfish-hermes"
+_PLUGIN_MANIFEST = Path(__file__).resolve().parents[1] / "plugin.yaml"
+
+
+def _version_from_plugin_manifest(path: Path | None = None) -> str | None:
+    path = _PLUGIN_MANIFEST if path is None else path
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError):
+        return None
+    for line in lines:
+        if not line.startswith("version:"):
+            continue
+        value = line.partition(":")[2].split("#", 1)[0].strip().strip("'\"")
+        return value or None
+    return None
+
+
+def _version_from_metadata() -> str | None:
+    try:
+        return metadata.version(_DISTRIBUTION_NAME)
+    except Exception:  # directory installs must not depend on package metadata
+        return None
+
+
+def _resolve_version() -> str:
+    # httpx headers must be ASCII; wheels omit plugin.yaml.
+    for candidate in (_version_from_plugin_manifest(), _version_from_metadata()):
+        if candidate and candidate.isascii():
+            return candidate
+    return "0+unknown"
+
+
+__version__ = _resolve_version()
+
+
+def register(ctx: Any) -> None:
+    """Register TinyFish providers, lifecycle hooks, and CLI commands with Hermes."""
+
+    from .browser_provider import TinyFishBrowserProvider
+    from .credit_policy import pre_tool_call_policy
+    from .provider import TinyFishWebSearchProvider
+    from .routing_context import routing_context_hook
+    from .setup_cli import (
+        dispatch_tinyfish_cli,
+        setup_tinyfish_cli,
+        tinyfish_status_command,
+    )
+
+    provider = TinyFishWebSearchProvider()
+    ctx.register_web_search_provider(provider)
+    if hasattr(ctx, "register_hook"):
+        # Only offer the browser provider where the pre_tool_call credit gate lands.
+        if hasattr(ctx, "register_browser_provider"):
+            ctx.register_browser_provider(TinyFishBrowserProvider())
+        ctx.register_hook("pre_tool_call", pre_tool_call_policy)
+        ctx.register_hook("pre_llm_call", routing_context_hook)
+
+    if hasattr(ctx, "register_cli_command"):
+
+        def _dispatch_cli(args: Any) -> int:
+            # Hermes' CLI main() propagates a nonzero int return to sys.exit.
+            return dispatch_tinyfish_cli(args, provider=provider)
+
+        ctx.register_cli_command(
+            name="tinyfish",
+            help="Configure and diagnose the TinyFish web provider",
+            setup_fn=setup_tinyfish_cli,
+            handler_fn=_dispatch_cli,
+            description=(
+                "Route Hermes web tools to TinyFish and manage the API key, "
+                "credit policies, and browser sessions."
+            ),
+        )
+    if hasattr(ctx, "register_command"):
+        ctx.register_command(
+            name="tinyfish-status",
+            handler=lambda raw_args: tinyfish_status_command(
+                raw_args, provider=provider
+            ),
+            description=(
+                "Show TinyFish provider status; pass 'live' to test Search and Fetch."
+            ),
+            args_hint="[live]",
+        )
+
+
+def __getattr__(name: str) -> Any:
+    if name == "TinyFishWebSearchProvider":
+        from .provider import TinyFishWebSearchProvider
+
+        return TinyFishWebSearchProvider
+    if name == "TinyFishBrowserProvider":
+        from .browser_provider import TinyFishBrowserProvider
+
+        return TinyFishBrowserProvider
+    raise AttributeError(name)
+
+
+__all__ = [
+    "TinyFishBrowserProvider",
+    "TinyFishWebSearchProvider",
+    "__version__",
+    "register",
+]

package/tinyfish_hermes/browser_provider.py

@@ -0,0 +1,133 @@
+"""Hermes BrowserProvider implementation for TinyFish Browser sessions."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any
+
+try:
+    from agent.browser_provider import BrowserProvider as _HermesBrowserProvider
+except Exception:  # pragma: no cover - lets the package import outside Hermes
+
+    class _HermesBrowserProvider:  # type: ignore[no-redef]
+        pass
+
+
+from . import rest_client
+from .config import credit_policy, tinyfish_config
+from .credit_policy import block_message
+from .provider import API_KEY_URL, MISSING_KEY_ERROR, _api_key
+
+logger = logging.getLogger(__name__)
+
+
+class TinyFishBrowserProvider(_HermesBrowserProvider):  # type: ignore[misc]
+    """TinyFish cloud browser backend for Hermes browser tools."""
+
+    @property
+    def name(self) -> str:
+        return "tinyfish"
+
+    @property
+    def display_name(self) -> str:
+        return "TinyFish"
+
+    def is_available(self) -> bool:
+        return bool(credit_policy("browser") in {"request", "allow"} and _api_key())
+
+    def create_session(self, task_id: str) -> dict[str, object]:
+        api_key = _api_key()
+        if not api_key:
+            # Hermes falls back to a local browser on raise; the hook is the real gate.
+            logger.warning(
+                "TinyFish Browser create_session refused (missing API key); "
+                "Hermes will fall back to a local browser"
+            )
+            raise ValueError(MISSING_KEY_ERROR)
+        if credit_policy("browser") == "deny":
+            logger.warning(
+                "TinyFish Browser create_session refused (policy deny); "
+                "Hermes will fall back to a local browser"
+            )
+            raise ValueError(block_message("browser"))
+        browser_cfg = tinyfish_config().get("browser") or {}
+        timeout_seconds = None
+        if isinstance(browser_cfg, dict) and browser_cfg.get("timeout_seconds") not in (
+            None,
+            "",
+        ):
+            try:
+                timeout_seconds = int(browser_cfg["timeout_seconds"])
+            except (TypeError, ValueError):
+                logger.warning(
+                    "Ignoring malformed tinyfish.browser.timeout_seconds %r",
+                    browser_cfg["timeout_seconds"],
+                )
+                timeout_seconds = None
+
+        data = rest_client.create_browser_session(
+            api_key=api_key, timeout_seconds=timeout_seconds
+        )
+        session_id = str(data.get("session_id") or data.get("id") or "")
+        cdp_url = str(data.get("cdp_url") or data.get("cdpUrl") or "")
+        if not session_id or not cdp_url:
+            if session_id:
+                # A half-created session bills until the server's inactivity GC.
+                try:
+                    rest_client.close_browser_session(session_id, api_key=api_key)
+                except Exception:
+                    pass
+            raise RuntimeError(
+                "TinyFish Browser did not return session_id and cdp_url."
+            )
+        session_name = f"tinyfish_{task_id}_{uuid.uuid4().hex[:8]}"
+        logger.info("Created TinyFish browser session")
+        return {
+            "session_name": session_name,
+            "bb_session_id": session_id,
+            "cdp_url": cdp_url,
+            "features": {
+                "tinyfish": True,
+                "credit_policy": credit_policy("browser"),
+                "base_url": str(data.get("base_url") or ""),
+            },
+        }
+
+    def close_session(self, session_id: str) -> bool:
+        # Hermes' BrowserProvider contract: close_session must never raise.
+        try:
+            api_key = _api_key()
+            if not api_key:
+                logger.warning("Cannot close TinyFish browser session: missing API key")
+                return False
+            return rest_client.close_browser_session(session_id, api_key=api_key)
+        except Exception as exc:
+            logger.debug("TinyFish browser close failed (%s)", type(exc).__name__)
+            return False
+
+    def emergency_cleanup(self, session_id: str) -> None:
+        try:
+            self.close_session(session_id)
+        except Exception as exc:
+            logger.debug(
+                "TinyFish browser emergency cleanup failed (%s)", type(exc).__name__
+            )
+
+    def get_setup_schema(self) -> dict[str, Any]:
+        return {
+            "name": "TinyFish",
+            "badge": "credit-gated",
+            "tag": (
+                "Remote browser sessions; each session consumes TinyFish credits. "
+                "Default policy 'request' asks for approval per session."
+            ),
+            "env_vars": [
+                {
+                    "key": "TINYFISH_API_KEY",
+                    "prompt": "TinyFish API key",
+                    "url": API_KEY_URL,
+                }
+            ],
+            "post_setup": "agent_browser",
+        }

package/tinyfish_hermes/config.py

@@ -0,0 +1,164 @@
+"""Read the ``tinyfish`` section of Hermes' user configuration."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+CreditFeature = Literal["browser"]
+CreditPolicy = Literal["deny", "request", "allow"]
+
+CREDIT_FEATURES: tuple[CreditFeature, ...] = ("browser",)
+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.
+DEFAULT_CREDIT_POLICY: CreditPolicy = "request"
+
+SearchOptions = dict[str, Any]
+FetchOptions = dict[str, Any]
+
+
+def load_config() -> dict[str, Any]:
+    try:
+        from hermes_cli.config import load_config as _load_config
+
+        return dict(_load_config() or {})
+    except Exception:  # config layer is optional outside Hermes
+        return {}
+
+
+def save_config(config: dict[str, Any]) -> None:
+    from hermes_cli.config import save_config as _save_config
+
+    _save_config(config)
+
+
+def tinyfish_config(config: dict[str, Any] | None = None) -> dict[str, Any]:
+    cfg = load_config() if config is None else config
+    section = cfg.get("tinyfish") or {}
+    return section if isinstance(section, dict) else {}
+
+
+def normalize_feature(value: str) -> CreditFeature:
+    if value.strip().lower().replace("_", "-") == "browser":
+        return "browser"
+    raise ValueError(
+        f"Unknown TinyFish credit feature '{value}'. Valid features: browser"
+    )
+
+
+def normalize_policy(value: Any) -> CreditPolicy:
+    policy = str(value or DEFAULT_CREDIT_POLICY).strip().lower()
+    if policy not in CREDIT_POLICIES:
+        valid = ", ".join(CREDIT_POLICIES)
+        raise ValueError(
+            f"Unknown TinyFish credit policy '{value}'. Valid policies: {valid}"
+        )
+    return policy
+
+
+def credit_policy(
+    feature: CreditFeature | str, config: dict[str, Any] | None = None
+) -> CreditPolicy:
+    normalized = normalize_feature(str(feature))
+    policies = tinyfish_config(config).get("credit_policy") or {}
+    if not isinstance(policies, dict):
+        return DEFAULT_CREDIT_POLICY
+    return normalize_policy(policies.get(normalized, DEFAULT_CREDIT_POLICY))
+
+
+def set_credit_policy(
+    config: dict[str, Any], feature: CreditFeature | str, policy: CreditPolicy | str
+) -> None:
+    normalized_feature = normalize_feature(str(feature))
+    normalized_policy = normalize_policy(policy)
+    section = config.setdefault("tinyfish", {})
+    if not isinstance(section, dict):
+        section = {}
+        config["tinyfish"] = section
+    policies = section.setdefault("credit_policy", {})
+    if not isinstance(policies, dict):
+        policies = {}
+        section["credit_policy"] = policies
+    policies[normalized_feature] = normalized_policy
+
+
+def credit_policy_summary(
+    config: dict[str, Any] | None = None,
+) -> dict[CreditFeature, CreditPolicy]:
+    return {feature: credit_policy(feature, config) for feature in CREDIT_FEATURES}
+
+
+def routing_context_enabled(config: dict[str, Any] | None = None) -> bool:
+    value = _bool_option(tinyfish_config(config).get("routing_context"))
+    return True if value is None else value
+
+
+def browser_cloud_provider(config: dict[str, Any] | None = None) -> str:
+    cfg = load_config() if config is None else config
+    section = cfg.get("browser") or {}
+    if not isinstance(section, dict):
+        return ""
+    return str(section.get("cloud_provider") or "").strip().lower()
+
+
+def _int_option(value: Any) -> int | None:
+    if value is None or value == "":
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _bool_option(value: Any) -> bool | None:
+    if value is None or value == "":
+        return None
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def search_options(config: dict[str, Any] | None = None) -> SearchOptions:
+    section = tinyfish_config(config).get("search") or {}
+    if not isinstance(section, dict):
+        return {}
+    options: SearchOptions = {}
+    for key in (
+        "location",
+        "language",
+        "after_date",
+        "before_date",
+        "domain_type",
+        "purpose",
+    ):
+        value = section.get(key)
+        if value not in (None, ""):
+            options[key] = str(value)
+    for key in ("recency_minutes", "page"):
+        value = _int_option(section.get(key))
+        if value is not None:
+            options[key] = value
+    return options
+
+
+def fetch_options(config: dict[str, Any] | None = None) -> FetchOptions:
+    section = tinyfish_config(config).get("fetch") or {}
+    if not isinstance(section, dict):
+        return {}
+    options: FetchOptions = {}
+    for key in ("ttl", "per_url_timeout_ms"):
+        value = _int_option(section.get(key))
+        if value is not None:
+            options[key] = value
+    for key in ("links", "image_links"):
+        value = _bool_option(section.get(key))
+        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"