@clawpump/claw-agent 0.1.5 → 0.1.6

package/agent/tools/blueprints.py

@@ -0,0 +1,325 @@
+"""Blueprints: shareable plain-language automations layered on skills + cron.
+
+A "blueprint" is NOT a new object type. It is an ordinary skill (a SKILL.md the
+agent loads) that additionally declares an automation schedule in its
+frontmatter:
+
+    metadata:
+      hermes:
+        blueprint:
+          schedule: "0 9 * * *"     # presence of `blueprint:` marks it runnable
+          deliver: origin            # optional (default "origin")
+          prompt: "..."              # optional task instruction for the run
+          no_agent: false            # optional
+
+Because a blueprint is just a skill, it flows through the ENTIRE existing
+skills-hub pipeline for free — search, inspect, quarantine, security scan,
+install, lock-file provenance, audit log, taps, the centralized index, and
+`hermes skills publish` for sharing. No new source type, no new store, no new
+transport. This module is the thin bridge between that skill metadata and the
+existing cron `create_job()` API:
+
+  * ``parse_blueprint(skill_md_text)``  -> BlueprintSpec | None
+  * ``blueprint_spec_for_installed(name)`` -> BlueprintSpec | None
+  * ``create_blueprint_job(spec, ...)`` -> the created cron job dict
+  * ``export_blueprint(job, body)``      -> a shareable SKILL.md string
+
+The dev guide's "Extend, Don't Duplicate" rule is the whole design: the blueprint
+is a skill, the schedule is a cron job, sharing is the existing publish/tap/
+index path.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "BlueprintSpec",
+    "parse_blueprint",
+    "blueprint_spec_for_installed",
+    "blueprint_to_job_spec",
+    "create_blueprint_job",
+    "register_blueprint_suggestion",
+    "export_blueprint",
+    "BlueprintError",
+]
+
+
+class BlueprintError(ValueError):
+    """Raised when a blueprint block is present but malformed."""
+
+
+@dataclass
+class BlueprintSpec:
+    """Parsed ``metadata.hermes.blueprint`` automation spec for a skill."""
+
+    skill_name: str
+    schedule: str
+    deliver: str = "origin"
+    prompt: Optional[str] = None
+    no_agent: bool = False
+    model: Optional[str] = None
+    provider: Optional[str] = None
+    enabled_toolsets: Optional[List[str]] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+
+def _split_frontmatter(text: str) -> Optional[Dict[str, Any]]:
+    """Return the parsed YAML frontmatter mapping, or None if absent/invalid."""
+    if not isinstance(text, str):
+        return None
+    stripped = text.lstrip()
+    if not stripped.startswith("---"):
+        return None
+    # Find the closing fence after the opening one.
+    after_open = stripped[3:]
+    end = after_open.find("\n---")
+    if end == -1:
+        return None
+    fm_text = after_open[:end]
+    try:
+        import yaml
+
+        data = yaml.safe_load(fm_text)
+    except Exception as e:  # pragma: no cover - malformed YAML
+        logger.debug("blueprint: frontmatter YAML parse failed: %s", e)
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def parse_blueprint(skill_md_text: str) -> Optional[BlueprintSpec]:
+    """Extract a BlueprintSpec from a SKILL.md string, or None if not a blueprint.
+
+    A skill is a blueprint iff ``metadata.hermes.blueprint`` is a mapping containing
+    a non-empty ``schedule``. Raises BlueprintError if the block exists but is
+    structurally invalid (so a typo surfaces instead of silently no-op'ing).
+    """
+    fm = _split_frontmatter(skill_md_text)
+    if not fm:
+        return None
+
+    name = str(fm.get("name", "")).strip()
+
+    meta = fm.get("metadata")
+    hermes = meta.get("hermes") if isinstance(meta, dict) else None
+    blueprint = hermes.get("blueprint") if isinstance(hermes, dict) else None
+    if blueprint is None:
+        return None
+    if not isinstance(blueprint, dict):
+        raise BlueprintError("metadata.hermes.blueprint must be a mapping")
+
+    schedule = str(blueprint.get("schedule", "")).strip()
+    if not schedule:
+        raise BlueprintError("blueprint.schedule is required and must be non-empty")
+
+    deliver = str(blueprint.get("deliver", "origin")).strip() or "origin"
+    prompt = blueprint.get("prompt")
+    if prompt is not None:
+        prompt = str(prompt)
+    no_agent = bool(blueprint.get("no_agent", False))
+    model = blueprint.get("model")
+    provider = blueprint.get("provider")
+    toolsets = blueprint.get("enabled_toolsets")
+    if toolsets is not None and not isinstance(toolsets, list):
+        raise BlueprintError("blueprint.enabled_toolsets must be a list when present")
+
+    return BlueprintSpec(
+        skill_name=name,
+        schedule=schedule,
+        deliver=deliver,
+        prompt=prompt,
+        no_agent=no_agent,
+        model=str(model).strip() if model else None,
+        provider=str(provider).strip() if provider else None,
+        enabled_toolsets=[str(t) for t in toolsets] if toolsets else None,
+        raw=blueprint,
+    )
+
+
+def blueprint_spec_for_installed(skill_name: str) -> Optional[BlueprintSpec]:
+    """Locate an installed skill's SKILL.md and parse its blueprint block.
+
+    Searches the standard skills tree for ``<skill_name>/SKILL.md``. Returns
+    None if the skill isn't found or isn't a blueprint.
+    """
+    try:
+        from tools.skills_hub import SKILLS_DIR
+    except Exception:  # pragma: no cover - import guard
+        return None
+
+    base = Path(SKILLS_DIR)
+    # Skills live at skills/<category>/<name>/SKILL.md or skills/<name>/SKILL.md.
+    candidates = list(base.glob(f"**/{skill_name}/SKILL.md"))
+    for path in candidates:
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        spec = parse_blueprint(text)
+        if spec is not None:
+            # Prefer the frontmatter name, fall back to the directory name.
+            if not spec.skill_name:
+                spec.skill_name = skill_name
+            return spec
+    return None
+
+
+def blueprint_to_job_spec(
+    spec: BlueprintSpec,
+    *,
+    name: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Build the ``cron.jobs.create_job`` kwargs dict for a BlueprintSpec.
+
+    This is the single source of truth for translating a blueprint into a job.
+    Both the direct ``create_blueprint_job`` path and the suggestion path
+    (``register_blueprint_suggestion``) build on it, so a blueprint scheduled now and
+    a blueprint accepted from a suggestion produce an identical job.
+    """
+    return {
+        "prompt": spec.prompt,
+        "schedule": spec.schedule,
+        "name": name or f"blueprint:{spec.skill_name}",
+        "deliver": spec.deliver,
+        "skills": [spec.skill_name] if spec.skill_name else None,
+        "model": spec.model,
+        "provider": spec.provider,
+        "enabled_toolsets": spec.enabled_toolsets,
+        "no_agent": spec.no_agent,
+    }
+
+
+def create_blueprint_job(
+    spec: BlueprintSpec,
+    *,
+    origin: Optional[Dict[str, Any]] = None,
+    name: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Create the cron job described by a BlueprintSpec via the existing cron API.
+
+    The blueprint's skill is loaded before the run (cron ``skills=[name]``); the
+    optional ``prompt`` becomes the task instruction. Delivery, model, and
+    toolsets carry through. Returns the created job dict.
+    """
+    from cron.jobs import create_job
+
+    job_spec = blueprint_to_job_spec(spec, name=name)
+    if origin is not None:
+        job_spec["origin"] = origin
+    return create_job(**job_spec)
+
+
+def register_blueprint_suggestion(spec: BlueprintSpec) -> Optional[Dict[str, Any]]:
+    """Turn an installed blueprint into a pending Suggested Cron Job.
+
+    Blueprints are source ``blueprint`` of the unified suggestion surface: installing
+    a skill that carries a ``blueprint:`` block does NOT auto-schedule it — it
+    registers a suggestion the user accepts (or dismisses) like any other.
+    Returns the suggestion record, or None if it was skipped (already
+    seen/dismissed, backlog full, etc.).
+    """
+    if not spec.skill_name:
+        return None
+    try:
+        from cron.suggestions import add_suggestion
+    except Exception:  # pragma: no cover - import guard
+        return None
+
+    return add_suggestion(
+        title=f"Schedule '{spec.skill_name}'",
+        description=(
+            f"The '{spec.skill_name}' blueprint runs on schedule {spec.schedule}"
+            + (f", delivering to {spec.deliver}" if spec.deliver and spec.deliver != "origin" else "")
+            + "."
+        ),
+        source="blueprint",
+        job_spec=blueprint_to_job_spec(spec),
+        dedup_key=f"blueprint:{spec.skill_name}:{spec.schedule}",
+    )
+
+
+def export_blueprint(job: Dict[str, Any], body: str, *, blueprint_name: Optional[str] = None) -> str:
+    """Render a shareable blueprint SKILL.md from an existing cron job dict.
+
+    The inverse of ``create_blueprint_job``: take a cron job a user already built
+    and emit a SKILL.md (with a ``metadata.hermes.blueprint`` block) they can hand
+    to ``hermes skills publish`` to share. ``body`` is the plain-language
+    description / instructions that become the SKILL.md body.
+    """
+    import yaml
+
+    name = blueprint_name or job.get("name") or "shared-blueprint"
+    # Sanitize to a valid skill identifier.
+    name = "".join(c if (c.isalnum() or c in "-_") else "-" for c in str(name).lower())
+    name = name.strip("-_") or "shared-blueprint"
+
+    schedule = job.get("schedule_display") or _schedule_to_string(job.get("schedule"))
+    skills = job.get("skills") or ([job["skill"]] if job.get("skill") else [])
+
+    blueprint_block: Dict[str, Any] = {"schedule": schedule}
+    deliver = job.get("deliver")
+    if deliver and deliver != "origin":
+        blueprint_block["deliver"] = deliver
+    if job.get("prompt"):
+        blueprint_block["prompt"] = job["prompt"]
+    if job.get("no_agent"):
+        blueprint_block["no_agent"] = True
+    if job.get("model"):
+        blueprint_block["model"] = job["model"]
+    if job.get("provider"):
+        blueprint_block["provider"] = job["provider"]
+    if job.get("enabled_toolsets"):
+        blueprint_block["enabled_toolsets"] = job["enabled_toolsets"]
+
+    description = (
+        (body.strip().splitlines() or ["Shared automation blueprint."])[0][:200]
+        if body.strip()
+        else "Shared automation blueprint."
+    )
+
+    frontmatter = {
+        "name": name,
+        "description": description,
+        "version": "1.0.0",
+        "license": "MIT",
+        "metadata": {
+            "hermes": {
+                "tags": ["blueprint", "automation"],
+                "blueprint": blueprint_block,
+            }
+        },
+    }
+    fm_yaml = yaml.safe_dump(frontmatter, sort_keys=False, allow_unicode=True).strip()
+    body_text = body.strip() or f"# {name}\n\nShared automation blueprint."
+    return f"---\n{fm_yaml}\n---\n\n{body_text}\n"
+
+
+def _schedule_to_string(schedule: Any) -> str:
+    """Best-effort render of a parsed schedule dict back to a string."""
+    if isinstance(schedule, str):
+        return schedule
+    if isinstance(schedule, dict):
+        kind = schedule.get("kind")
+        if kind == "cron" and schedule.get("expr"):
+            return str(schedule["expr"])
+        if kind == "interval":
+            # parse_schedule stores interval periods as "minutes"; tolerate a
+            # legacy/foreign "seconds" form too.
+            if schedule.get("minutes"):
+                mins = int(schedule["minutes"])
+                if mins % 60 == 0:
+                    return f"every {mins // 60}h"
+                return f"every {mins}m"
+            if schedule.get("seconds"):
+                secs = int(schedule["seconds"])
+                if secs % 3600 == 0:
+                    return f"every {secs // 3600}h"
+                if secs % 60 == 0:
+                    return f"every {secs // 60}m"
+                return f"every {secs}s"
+    return "0 9 * * *"  # safe daily fallback

package/agent/tools/browser_cdp_tool.py

@@ -28,9 +28,9 @@ logger = logging.getLogger(__name__)
 
 CDP_DOCS_URL = "https://chromedevtools.github.io/devtools-protocol/"
 
-# ``websockets`` is a transitive dependency of hermes-agent (via fal_client
-# and firecrawl-py) and is already imported by gateway/platforms/feishu.py.
-# Wrap the import so a clean error surfaces if the package is ever absent.
+# ``websockets`` is a direct hermes-agent dependency because the browser CDP
+# supervisor and browser_dialog tool import it during tool discovery. Wrap the
+# import so a clean error surfaces if an environment is stale or incomplete.
 try:
     import websockets
     from websockets.exceptions import WebSocketException

package/agent/tools/browser_tool.py

@@ -66,8 +66,8 @@ from typing import Dict, Any, Optional, List, Tuple, Union
 from pathlib import Path
 from agent.auxiliary_client import call_llm
 from hermes_constants import get_hermes_home
-from utils import is_truthy_value
-from hermes_cli.config import cfg_get
+from utils import env_int, is_truthy_value
+from hermes_cli.config import DEFAULT_CONFIG, cfg_get
 
 try:
     from tools.website_policy import check_website_access
@@ -78,10 +78,12 @@ try:
     from tools.url_safety import (
         is_safe_url as _is_safe_url,
         is_always_blocked_url as _is_always_blocked_url,
+        normalize_url_for_request as _normalize_url_for_request,
     )
 except Exception:
     _is_safe_url = lambda url: False  # noqa: E731 — fail-closed: block all if safety module unavailable
     _is_always_blocked_url = lambda url: True  # noqa: E731 — fail-closed on the floor too
+    _normalize_url_for_request = lambda url: url  # noqa: E731 — best-effort fallback
 # Browser-provider ABC + registry — PR #25214 moved the per-vendor providers
 # (Browserbase / Browser Use / Firecrawl) out of ``tools/browser_providers/``
 # and into ``plugins/browser/<vendor>/``. The dispatcher consults the
@@ -1175,10 +1177,28 @@ _cleanup_done = False
 # Inactivity Timeout Configuration
 # =============================================================================
 
-# Session inactivity timeout (seconds) - cleanup if no activity for this long
-# Default: 5 minutes. Needs headroom for LLM reasoning between browser commands,
-# especially when subagents are doing multi-step browser tasks.
-BROWSER_SESSION_INACTIVITY_TIMEOUT = int(os.environ.get("BROWSER_INACTIVITY_TIMEOUT", "300"))
+# Session inactivity timeout (seconds) - cleanup if no activity for this long.
+# config.yaml is authoritative; BROWSER_INACTIVITY_TIMEOUT remains a legacy
+# fallback so old deployments keep working if they have not migrated yet.
+DEFAULT_SESSION_INACTIVITY_TIMEOUT = int(
+    DEFAULT_CONFIG.get("browser", {}).get("inactivity_timeout", 120)
+)
+
+
+def _get_session_inactivity_timeout() -> int:
+    result = env_int("BROWSER_INACTIVITY_TIMEOUT", DEFAULT_SESSION_INACTIVITY_TIMEOUT)
+    try:
+        from hermes_cli.config import read_raw_config
+        cfg = read_raw_config()
+        val = cfg_get(cfg, "browser", "inactivity_timeout")
+        if val is not None:
+            result = max(int(val), 30)  # Floor at 30s to avoid instant reaping
+    except Exception as e:
+        logger.debug("Could not read inactivity_timeout from config: %s", e)
+    return result
+
+
+BROWSER_SESSION_INACTIVITY_TIMEOUT = _get_session_inactivity_timeout()
 
 # Track last activity time per session
 _session_last_activity: Dict[str, float] = {}
@@ -2310,6 +2330,14 @@ def browser_navigate(url: str, task_id: Optional[str] = None) -> str:
             "error": "Blocked: URL contains what appears to be an API key or token. "
                      "Secrets must not be sent in URLs.",
         })
+    url = _normalize_url_for_request(url)
+    normalized_decoded = urllib.parse.unquote(url)
+    if _PREFIX_RE.search(url) or _PREFIX_RE.search(normalized_decoded):
+        return json.dumps({
+            "success": False,
+            "error": "Blocked: URL contains what appears to be an API key or token. "
+                     "Secrets must not be sent in URLs.",
+        })
 
     # SSRF protection — block private/internal addresses before navigating.
     # Skipped for local backends (Camofox, headless Chromium without a cloud

package/agent/tools/checkpoint_manager.py

@@ -60,6 +60,8 @@ from pathlib import Path
 from hermes_constants import get_hermes_home
 from typing import Dict, List, Optional, Set, Tuple
 
+from utils import env_int
+
 logger = logging.getLogger(__name__)
 
 # ---------------------------------------------------------------------------
@@ -139,7 +141,7 @@ DEFAULT_EXCLUDES = [
 ]
 
 # Git subprocess timeout (seconds).
-_GIT_TIMEOUT: int = max(10, min(60, int(os.getenv("HERMES_CHECKPOINT_TIMEOUT", "30"))))
+_GIT_TIMEOUT: int = max(10, min(60, env_int("HERMES_CHECKPOINT_TIMEOUT", 30)))
 
 # Max files to snapshot — skip huge directories to avoid slowdowns.
 _MAX_FILES = 50_000
@@ -270,6 +272,28 @@ def _git_env(
     return env
 
 
+def _repair_bare_repo_dirs(store: Path) -> None:
+    """Recreate refs/ and branches/ dirs that ``git gc`` may have removed.
+
+    ``git gc --prune=now`` on a bare repo with only packed refs can remove
+    the empty ``refs/heads/`` directory.  Git 2.34+ requires ``refs/`` (and
+    some versions require ``branches/``) to exist even when all refs are
+    packed in ``packed-refs``.  Without them, ``git add -A`` returns
+    ``fatal: not a git repository`` and all checkpoint operations fail
+    silently.
+    """
+    for subdir in ("refs/heads", "branches"):
+        path = store / subdir
+        if not path.exists():
+            try:
+                path.mkdir(parents=True, exist_ok=True)
+                logger.debug("Repaired missing %s in checkpoint store", subdir)
+            except OSError as exc:
+                logger.warning(
+                    "Cannot create %s in checkpoint store: %s", subdir, exc,
+                )
+
+
 def _run_git(
     args: List[str],
     store: Path,
@@ -305,6 +329,7 @@ def _run_git(
             timeout=timeout,
             env=env,
             cwd=str(normalized_working_dir),
+            stdin=subprocess.DEVNULL,
         )
         ok = result.returncode == 0
         stdout = result.stdout.strip()
@@ -424,6 +449,7 @@ def _init_store(store: Path, working_dir: str) -> Optional[str]:
             ["git", "init", "--bare", str(store)],
             capture_output=True, text=True,
             env=init_env, timeout=_GIT_TIMEOUT,
+            stdin=subprocess.DEVNULL,
         )
         if result.returncode != 0:
             return f"Shadow store init failed: {result.stderr.strip()}"
@@ -1082,6 +1108,7 @@ class CheckpointManager:
             ["gc", "--prune=now", "--quiet"],
             store, working_dir, timeout=_GIT_TIMEOUT * 3,
         )
+        _repair_bare_repo_dirs(store)
 
     def _enforce_size_cap(self, store: Path) -> None:
         """If total store size exceeds ``max_total_size_mb``, drop oldest
@@ -1169,6 +1196,7 @@ class CheckpointManager:
             ["gc", "--prune=now", "--quiet"],
             store, str(store.parent), timeout=_GIT_TIMEOUT * 3,
         )
+        _repair_bare_repo_dirs(store)
 
 
 def format_checkpoint_list(checkpoints: List[Dict], directory: str) -> str:
@@ -1380,6 +1408,7 @@ def prune_checkpoints(
             ["gc", "--prune=now", "--quiet"],
             store, str(base), timeout=_GIT_TIMEOUT * 3,
         )
+        _repair_bare_repo_dirs(store)
 
         # Size-cap pass across remaining projects.
         if max_total_size_mb > 0:
@@ -1451,6 +1480,7 @@ def prune_checkpoints(
                 ["gc", "--prune=now", "--quiet"],
                 store, str(base), timeout=_GIT_TIMEOUT * 3,
             )
+            _repair_bare_repo_dirs(store)
 
     size_after = _dir_size_bytes(base)
     delta = size_before - size_after

package/agent/tools/clarify_tool.py

@@ -20,6 +20,39 @@ from typing import List, Optional, Callable
 MAX_CHOICES = 4
 
 
+def _flatten_choice(c) -> str:
+    """Coerce a single choice into its user-facing display string.
+
+    The schema declares choices as bare strings, but LLMs sometimes emit
+    dict-shaped choices like ``[{"description": "..."}]``. A naive ``str(c)``
+    turns the whole dict into its Python repr — ``{'description': '...'}`` —
+    which then leaks onto every surface that renders the choice (CLI panel,
+    Discord buttons, Telegram numbered list) AND is returned verbatim as the
+    user's answer. Normalising here, at the one platform-agnostic entry point,
+    fixes the whole class in one place instead of per-adapter.
+
+    Dict unwrap order is the canonical LLM tool-call user-facing keys:
+    ``label`` → ``description`` → ``text`` → ``title``. ``name`` and ``value``
+    are deliberately excluded — they're component-shaped fields that could
+    carry raw enum values or short identifiers, not human-readable labels. A
+    dict with none of the canonical keys is dropped (returns ""), since a
+    garbage label is worse than no choice at all.
+    """
+    if c is None:
+        return ""
+    if isinstance(c, str):
+        return c.strip()
+    if isinstance(c, dict):
+        for key in ("label", "description", "text", "title"):
+            v = c.get(key)
+            if isinstance(v, str) and v.strip():
+                return v.strip()
+        return ""
+    if isinstance(c, (list, tuple)):
+        return " ".join(_flatten_choice(x) for x in c).strip()
+    return str(c).strip()
+
+
 def clarify_tool(
     question: str,
     choices: Optional[List[str]] = None,
@@ -48,7 +81,12 @@ def clarify_tool(
     if choices is not None:
         if not isinstance(choices, list):
             return tool_error("choices must be a list of strings.")
-        choices = [str(c).strip() for c in choices if str(c).strip()]
+        # LLMs sometimes emit dict-shaped choices (e.g. [{"description": "..."}])
+        # instead of bare strings. _flatten_choice unwraps them to their
+        # user-facing text here — the single platform-agnostic entry point —
+        # so the CLI panel, Discord buttons, and Telegram list all render clean
+        # text and the resolved answer is never a raw Python dict repr.
+        choices = [s for s in (_flatten_choice(c) for c in choices) if s]
         if len(choices) > MAX_CHOICES:
             choices = choices[:MAX_CHOICES]
         if not choices:
@@ -93,6 +131,12 @@ CLARIFY_SCHEMA = {
         "or types their own answer via a 5th 'Other' option.\n"
         "2. **Open-ended** — omit choices entirely. The user types a free-form "
         "response.\n\n"
+        "CRITICAL: when you are offering options, put each option ONLY in the "
+        "`choices` array — NEVER enumerate the options inside the `question` "
+        "text. The UI renders `choices` as selectable rows; options written "
+        "into the question string render as dead prose the user can't pick. "
+        "Right: question='Which deployment target?', choices=['staging', "
+        "'prod']. Wrong: question='Which target? 1) staging 2) prod', choices=[].\n\n"
         "Use this tool when:\n"
         "- The task is ambiguous and you need the user to choose an approach\n"
         "- You want post-task feedback ('How did that work out?')\n"
@@ -107,16 +151,22 @@ CLARIFY_SCHEMA = {
         "properties": {
             "question": {
                 "type": "string",
-                "description": "The question to present to the user.",
+                "description": (
+                    "The question itself, and ONLY the question (e.g. 'Which "
+                    "deployment target?'). Do NOT embed the answer options here "
+                    "— pass them as separate elements in `choices`."
+                ),
             },
             "choices": {
                 "type": "array",
                 "items": {"type": "string"},
                 "maxItems": MAX_CHOICES,
                 "description": (
-                    "Up to 4 answer choices. Omit this parameter entirely to "
-                    "ask an open-ended question. When provided, the UI "
-                    "automatically appends an 'Other (type your answer)' option."
+                    "REQUIRED whenever you are presenting selectable options: "
+                    "each distinct option is its own array element (up to 4). "
+                    "The UI renders these as pickable rows and auto-appends an "
+                    "'Other (type your answer)' option. Omit this parameter "
+                    "entirely ONLY for a genuinely open-ended free-text question."
                 ),
             },
         },