monkeybot 2.1.1__py3-none-any.whl

monkeybot/core/config/runtime_env.py

@@ -0,0 +1,262 @@
+"""Load ``monkeybot_config/monkeybot.yaml`` into ``os.environ`` for unset keys only.
+
+Precedence: existing process environment (including ``.env`` via dotenv) wins.
+Discovery: ``MONKEYBOT_CONFIG`` if set, else ``<cwd>/monkeybot_config/monkeybot.yaml``.
+Optional ``includes``: list of paths relative to the primary config file's directory.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+_RUNTIME_ENV_APPLIED = False
+
+# (section, key) -> os.environ name
+# YAML gcp/anthropic_vertex project ids map here; prefer GOOGLE_CLOUD_PROJECT when set in .env.
+_GCP_PROJECT_ENV_KEYS = frozenset({"VERTEX_AI_PROJECT_ID", "ANTHROPIC_VERTEX_PROJECT_ID"})
+
+# Public alias for CLI / validation (stable API).
+ENV_MAP: dict[tuple[str, str], str] = {
+    ("runtime", "log_level"): "LOG_LEVEL",
+    ("runtime", "port"): "PORT",
+    ("runtime", "gateway_port"): "GATEWAY_PORT",
+    ("paths", "agent_md"): "AGENT_MD",
+    ("paths", "memory_path"): "MEMORY_PATH",
+    ("paths", "memory_storage_uri"): "MEMORY_STORAGE_URI",
+    ("paths", "skills_path"): "SKILLS_PATH",
+    ("paths", "db_url"): "DB_URL",
+    ("paths", "mcp_config"): "MCP_CONFIG",
+    ("paths", "command_allowlist_config"): "COMMAND_ALLOWLIST_CONFIG",
+    ("paths", "permission_config"): "PERMISSION_CONFIG",
+    ("paths", "workspace_root"): "MONKEYBOT_WORKSPACE_ROOT",
+    ("model", "provider"): "MODEL_PROVIDER",
+    ("model", "name"): "MODEL_NAME",
+    ("model", "temperature"): "MODEL_TEMPERATURE",
+    ("model", "max_tokens"): "MODEL_MAX_TOKENS",
+    ("model", "thinking_budget"): "MODEL_THINKING_BUDGET",
+    ("model", "context_window"): "MODEL_CONTEXT_WINDOW",
+    ("model", "summarization_model"): "CONTEXT_SUMMARIZATION_MODEL",
+    ("model", "max_turns"): "MAX_TURNS",
+    ("model", "cache_retention"): "MODEL_CACHE_RETENTION",
+    ("gcp", "project_id"): "VERTEX_AI_PROJECT_ID",
+    ("gcp", "location"): "VERTEX_AI_LOCATION",
+    ("anthropic_vertex", "project_id"): "ANTHROPIC_VERTEX_PROJECT_ID",
+    ("anthropic_vertex", "region"): "ANTHROPIC_VERTEX_REGION",
+    ("gateway", "pending_response_timeout_sec"): "PENDING_RESPONSE_TIMEOUT_SEC",
+    ("gateway", "sse_replay_max"): "SSE_REPLAY_MAX",
+    ("gateway", "graceful_shutdown_timeout_sec"): "GRACEFUL_SHUTDOWN_TIMEOUT_SEC",
+    ("gateway", "cors_allow_origins"): "MONKEYBOT_CORS_ALLOW_ORIGINS",
+    ("context_curation", "enabled"): "CONTEXT_CURATION_ENABLED",
+    ("context_curation", "memory_window_lines"): "CONTEXT_CURATION_MEMORY_WINDOW_LINES",
+    ("context_curation", "memory_index_cap"): "MEMORY_INDEX_CAP",
+    ("context_curation", "memory_token_threshold"): "CONTEXT_CURATION_MEMORY_TOKEN_THRESHOLD",
+    ("context_curation", "curator_model"): "CONTEXT_CURATOR_MODEL",
+    ("context_curation", "timeout_sec"): "CONTEXT_CURATION_TIMEOUT_SEC",
+    ("memory_hook", "enabled"): "MONKEYBOT_MEMORY_HOOK_ENABLED",
+    ("subagent", "timeout_sec"): "SUBAGENT_TIMEOUT_SEC",
+    ("subagent", "max_turns"): "SUBAGENT_MAX_TURNS",
+    ("subagent", "agent_md"): "MONKEYBOT_SUBAGENT_AGENT_MD",
+    ("tools", "denied_patterns"): "MONKEYBOT_TOOL_DENIED_PATTERNS",
+    ("tools", "read_max_lines"): "MONKEYBOT_READ_MAX_LINES",
+    ("tools", "read_default_lines"): "MONKEYBOT_READ_DEFAULT_LINES",
+    ("tools", "spill_read_max_lines"): "MONKEYBOT_SPILL_READ_MAX_LINES",
+    ("tools", "spill_min_chars"): "MONKEYBOT_SPILL_MIN_CHARS",
+    ("tools", "result_budget_fraction"): "MONKEYBOT_RESULT_BUDGET_FRACTION",
+    ("tools", "result_budget_floor_tokens"): "MONKEYBOT_RESULT_BUDGET_FLOOR_TOKENS",
+    ("compression", "light_ratio"): "MONKEYBOT_PRESSURE_LIGHT_RATIO",
+    ("compression", "moderate_ratio"): "MONKEYBOT_PRESSURE_MODERATE_RATIO",
+    ("compression", "aggressive_ratio"): "MONKEYBOT_PRESSURE_AGGRESSIVE_RATIO",
+    ("compression", "resume_thinking_budget"): "MONKEYBOT_RESUME_THINKING_BUDGET",
+    ("web_search", "backend"): "WEB_SEARCH_BACKEND",
+    ("web_search", "max_results"): "WEB_SEARCH_MAX_RESULTS",
+    ("sandbox", "enabled"): "SANDBOX_ENABLED",
+    ("sandbox", "server_url"): "SANDBOX_SERVER_URL",
+    ("sandbox", "image"): "SANDBOX_IMAGE",
+    ("sandbox", "ttl_seconds"): "SANDBOX_TTL_SECONDS",
+    ("fake_provider", "events_json"): "MONKEYBOT_FAKE_PROVIDER_EVENTS",
+    ("emission", "style"): "MONKEYBOT_EMISSION_STYLE",
+    ("runtime", "transcript_enabled"): "MONKEYBOT_TRANSCRIPT_ENABLED",
+    ("runtime", "transcript_include_live"): "MONKEYBOT_TRANSCRIPT_INCLUDE_LIVE",
+    ("harness", "mode"): "MONKEYBOT_HARNESS_MODE",
+    ("realtime", "websocket.enabled"): "MONKEYBOT_REALTIME_WS_ENABLED",
+    ("realtime", "websocket.port"): "MONKEYBOT_REALTIME_WS_PORT",
+    ("realtime", "audio.input_format"): "MONKEYBOT_REALTIME_AUDIO_INPUT_FORMAT",
+    ("realtime", "audio.output_format"): "MONKEYBOT_REALTIME_AUDIO_OUTPUT_FORMAT",
+    ("realtime", "audio.chunk_ms"): "MONKEYBOT_REALTIME_AUDIO_CHUNK_MS",
+    ("realtime", "audio.max_utterance_sec"): "MONKEYBOT_REALTIME_AUDIO_MAX_UTTERANCE_SEC",
+    ("realtime", "session.max_duration_sec"): "MONKEYBOT_REALTIME_SESSION_MAX_DURATION_SEC",
+    ("realtime", "session.idle_timeout_sec"): "MONKEYBOT_REALTIME_SESSION_IDLE_TIMEOUT_SEC",
+    ("realtime", "session.max_response_turn_sec"): "MONKEYBOT_REALTIME_SESSION_MAX_RESPONSE_TURN_SEC",
+    ("realtime", "session.max_concurrent_sessions"): "MONKEYBOT_REALTIME_SESSION_MAX_CONCURRENT_SESSIONS",
+    ("realtime", "metrics.emit_summary_on_close"): "MONKEYBOT_REALTIME_METRICS_EMIT_SUMMARY_ON_CLOSE",
+}
+
+# Backward-compatible alias for internal/tests.
+_ENV_MAP = ENV_MAP
+
+
+def reset_runtime_env_state_for_tests() -> None:
+    """Allow a second ``apply_monkeybot_runtime_env`` in the same interpreter (tests only)."""
+    global _RUNTIME_ENV_APPLIED
+    _RUNTIME_ENV_APPLIED = False
+
+
+def _deep_merge(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = dict(base)
+    for k, v in overlay.items():
+        if k in out and isinstance(out[k], dict) and isinstance(v, dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def _scalar_to_env(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, str):
+        return value
+    return None
+
+
+def _denied_patterns_to_env(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        parts = [str(x).strip() for x in value if str(x).strip()]
+        return ",".join(parts)
+    return None
+
+
+def _get_nested(mapping: Mapping[str, Any], dotted_key: str) -> Any:
+    current: Any = mapping
+    for part in dotted_key.split("."):
+        if not isinstance(current, dict):
+            return None
+        current = current.get(part)
+        if current is None:
+            return None
+    return current
+
+
+def _flatten_config(data: Mapping[str, Any]) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for (section, key), env_name in ENV_MAP.items():
+        sec = data.get(section)
+        if not isinstance(sec, dict):
+            continue
+        raw = _get_nested(sec, key)
+        if raw is None:
+            continue
+        if env_name == "MONKEYBOT_TOOL_DENIED_PATTERNS":
+            s = _denied_patterns_to_env(raw)
+        else:
+            s = _scalar_to_env(raw)
+        if s is not None:
+            out[env_name] = s
+    return out
+
+
+def _resolve_config_path() -> Path | None:
+    explicit = os.environ.get("MONKEYBOT_CONFIG", "").strip()
+    if explicit:
+        p = Path(explicit).expanduser()
+        if p.is_file():
+            return p.resolve()
+        logger.warning("MONKEYBOT_CONFIG is set but not a file: %s", p)
+        return None
+    default = Path.cwd() / "monkeybot_config" / "monkeybot.yaml"
+    if default.is_file():
+        return default.resolve()
+    return None
+
+
+def _load_yaml_file(path: Path) -> dict[str, Any]:
+    with open(path, encoding="utf-8") as f:
+        loaded = yaml.safe_load(f)
+    if loaded is None:
+        return {}
+    if not isinstance(loaded, dict):
+        raise ValueError(f"Expected mapping at root of {path}, got {type(loaded).__name__}")
+    return loaded
+
+
+def _merge_with_includes(primary_path: Path, root: dict[str, Any]) -> dict[str, Any]:
+    raw_includes = root.get("includes")
+    base = {k: v for k, v in root.items() if k != "includes"}
+    if not raw_includes:
+        return base
+    if not isinstance(raw_includes, list):
+        logger.warning("includes: must be a list of paths; ignoring")
+        return base
+    merged: dict[str, Any] = dict(base)
+    parent = primary_path.parent
+    for item in raw_includes:
+        if not isinstance(item, str) or not item.strip():
+            continue
+        inc_path = (parent / item.strip()).resolve()
+        if not inc_path.is_file():
+            logger.warning("include not found, skipping: %s", inc_path)
+            continue
+        try:
+            inc_doc = _load_yaml_file(inc_path)
+        except Exception as exc:
+            logger.warning("failed to load include %s: %s", inc_path, exc)
+            continue
+        inc_body = {k: v for k, v in inc_doc.items() if k != "includes"}
+        merged = _deep_merge(merged, inc_body)
+    return merged
+
+
+def apply_monkeybot_runtime_env() -> Path | None:
+    """Apply YAML-backed defaults to ``os.environ`` (unset keys only). Safe to call twice."""
+    global _RUNTIME_ENV_APPLIED
+    if _RUNTIME_ENV_APPLIED:
+        return None
+
+    path = _resolve_config_path()
+    if path is None:
+        _RUNTIME_ENV_APPLIED = True
+        logger.debug(
+            "No monkeybot.yaml found (MONKEYBOT_CONFIG / monkeybot_config/monkeybot.yaml); skipping"
+        )
+        return None
+
+    try:
+        root = _load_yaml_file(path)
+        merged = _merge_with_includes(path, root)
+        flat = _flatten_config(merged)
+    except Exception as exc:
+        logger.error("Failed to load %s: %s", path, exc)
+        raise
+
+    _RUNTIME_ENV_APPLIED = True
+    google_cloud_project = (os.environ.get("GOOGLE_CLOUD_PROJECT") or "").strip()
+    for env_key, env_val in flat.items():
+        if env_key in os.environ:
+            continue
+        if env_key in _GCP_PROJECT_ENV_KEYS and google_cloud_project:
+            os.environ[env_key] = google_cloud_project
+            logger.debug(
+                "Set from GOOGLE_CLOUD_PROJECT: %s=%s", env_key, google_cloud_project
+            )
+            continue
+        os.environ[env_key] = env_val
+        logger.debug("Set from monkeybot.yaml: %s=%s", env_key, env_val)
+
+    logger.info("Applied runtime config from %s (%d keys)", path, len(flat))
+    return path

monkeybot/core/config/settings.py

@@ -0,0 +1,341 @@
+"""Provider resolution and configuration types for the monkeybot harness."""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from monkeybot.core.config.yaml_loader import load_monkeybot_yaml_dict
+from monkeybot.core.llm.provider import Provider
+from monkeybot.providers.claude import ClaudeProvider
+from monkeybot.providers.gemini import GeminiProvider
+from monkeybot.providers.huggingface import HuggingFaceProvider
+from monkeybot.providers.nvidia import NvidiaProvider
+from monkeybot.providers.ollama import OllamaProvider
+from monkeybot.providers.openai import OpenAIProvider
+from monkeybot.providers.sampling import resolve_model_sampling
+from monkeybot.providers.vertex_claude import VertexClaudeProvider
+
+logger = logging.getLogger(__name__)
+
+_MODEL_PROVIDER_ALIASES: dict[str, str] = {
+    "gemini": "google_vertexai",
+    "vertex": "google_vertexai",
+    "google-vertexai": "google_vertexai",
+    "vertex-claude": "vertex_anthropic",
+    "vertex_claude": "vertex_anthropic",
+}
+
+
+def normalize_model_provider(provider: str) -> str:
+    """Map config aliases (e.g. ``gemini``, ``vertex-claude``) to canonical provider ids."""
+    key = provider.strip().lower()
+    return _MODEL_PROVIDER_ALIASES.get(key, key)
+
+
+class ConfigError(Exception):
+    """Configuration error with actionable message."""
+
+    pass
+
+
+@dataclass
+class CustomMemoryFolder:
+    """User-defined memory folder registered with the memory organizer classifier."""
+
+    name: str
+    description: str
+
+    def __post_init__(self) -> None:
+        import re
+
+        if not re.match(r"^[a-z0-9-]+$", self.name):
+            raise ConfigError(
+                f"CustomMemoryFolder.name '{self.name}' is invalid. "
+                "Use lowercase letters, digits, and hyphens only."
+            )
+        reserved = {"episodic", "semantic", "procedural", "working", "raw"}
+        if self.name in reserved:
+            raise ConfigError(
+                f"CustomMemoryFolder.name '{self.name}' conflicts with a built-in folder. "
+                f"Reserved names: {sorted(reserved)}"
+            )
+
+
+@dataclass
+class SubagentConfig:
+    """Configuration for a single named subagent persona."""
+
+    name: str
+    description: str
+    skills: list[str]
+    agent_md: str | None = None
+    model: str | None = None
+    vertex_location: str | None = None
+
+
+@dataclass(frozen=True)
+class ProviderConfig:
+    """Native streaming Provider plus model id."""
+
+    provider: Provider
+    model: str
+
+
+def _resolve_gcp_project_id() -> str:
+    """GCP project for Vertex providers."""
+    return (
+        (os.getenv("GCP_PROJECT_ID") or "").strip()
+        or (os.getenv("VERTEX_AI_PROJECT_ID") or "").strip()
+        or (os.getenv("ANTHROPIC_VERTEX_PROJECT_ID") or "").strip()
+        or (os.getenv("GOOGLE_CLOUD_PROJECT") or "").strip()
+    )
+
+
+def get_provider_config(
+    provider: str | None = None,
+    model_name: str | None = None,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    thinking_budget: int | None = None,
+) -> ProviderConfig:
+    """Resolve a Provider and model id from environment or explicit parameters."""
+    raw_provider = str(provider or os.getenv("MODEL_PROVIDER") or "google_vertexai")
+    provider_key = normalize_model_provider(raw_provider)
+    if provider_key == "fake":
+        raise ValueError(
+            "MODEL_PROVIDER=fake is for gateway/tests only; inject ScriptedFakeProvider directly "
+            "or use the gateway fake provider path."
+        )
+    resolved_model = str(model_name or os.getenv("MODEL_NAME") or "gemini-2.5-flash")
+    sampling = resolve_model_sampling(temperature=temperature, max_tokens=max_tokens)
+    thinking_budget = (
+        thinking_budget if thinking_budget is not None else int(os.getenv("MODEL_THINKING_BUDGET", "-1"))
+    )
+    if provider_key == "google_vertexai":
+        return ProviderConfig(
+            GeminiProvider(
+                temperature=sampling.temperature,
+                max_tokens=sampling.max_tokens,
+                thinking_budget=thinking_budget,
+            ),
+            resolved_model,
+        )
+    if provider_key == "google_genai":
+        api_key = (os.getenv("GEMINI_API_KEY") or "").strip()
+        if not api_key:
+            raise ValueError(
+                "MODEL_PROVIDER=google_genai requires GEMINI_API_KEY. "
+                "Set it in your environment or .env file."
+            )
+        return ProviderConfig(
+            GeminiProvider(
+                temperature=sampling.temperature,
+                max_tokens=sampling.max_tokens,
+                thinking_budget=thinking_budget,
+                api_key=api_key,
+            ),
+            resolved_model,
+        )
+    if provider_key == "openai":
+        return ProviderConfig(
+            OpenAIProvider(
+                temperature=sampling.temperature,
+                max_tokens=sampling.max_tokens,
+            ),
+            resolved_model,
+        )
+    if provider_key == "anthropic":
+        return ProviderConfig(
+            ClaudeProvider(
+                temperature=sampling.temperature,
+                max_tokens=sampling.max_tokens,
+            ),
+            resolved_model,
+        )
+    if provider_key == "vertex_anthropic":
+        project = _resolve_gcp_project_id()
+        if not project:
+            raise ValueError(
+                "vertex_anthropic provider requires a GCP project. "
+                "Set GCP_PROJECT_ID, VERTEX_AI_PROJECT_ID, ANTHROPIC_VERTEX_PROJECT_ID, "
+                "or GOOGLE_CLOUD_PROJECT (or gcp.project_id in monkeybot.yaml)."
+            )
+        if os.getenv("VERTEX_AI_LOCATION"):
+            logger.warning(
+                "VERTEX_AI_LOCATION is no longer read for vertex_anthropic; "
+                "set ANTHROPIC_VERTEX_REGION instead"
+            )
+        region = (os.getenv("ANTHROPIC_VERTEX_REGION") or "us-east5").strip() or "us-east5"
+        return ProviderConfig(
+            VertexClaudeProvider(
+                project_id=project,
+                region=region,
+                temperature=sampling.temperature,
+                max_tokens=sampling.max_tokens,
+            ),
+            resolved_model,
+        )
+    if provider_key == "huggingface":
+        return ProviderConfig(
+            HuggingFaceProvider(
+                temperature=sampling.temperature,
+                max_tokens=sampling.max_tokens,
+            ),
+            resolved_model,
+        )
+    if provider_key == "ollama":
+        return ProviderConfig(
+            OllamaProvider(
+                temperature=sampling.temperature,
+                max_tokens=sampling.max_tokens,
+                thinking_budget=thinking_budget,
+            ),
+            resolved_model,
+        )
+    if provider_key == "nvidia":
+        return ProviderConfig(
+            NvidiaProvider(
+                temperature=sampling.temperature,
+                max_tokens=sampling.max_tokens,
+            ),
+            resolved_model,
+        )
+    if provider_key == "aws_bedrock":
+        from monkeybot.providers.bedrock import BedrockClaudeProvider  # noqa: PLC0415
+
+        aws_region = os.getenv("AWS_REGION") or os.getenv("AWS_DEFAULT_REGION")
+        return ProviderConfig(
+            BedrockClaudeProvider(
+                aws_region=aws_region,
+                temperature=sampling.temperature,
+                max_tokens=sampling.max_tokens,
+            ),
+            resolved_model,
+        )
+    raise ValueError(
+        f"Unsupported model provider: {provider_key}. "
+        "Supported providers: google_vertexai, openai, anthropic, vertex_anthropic, "
+        "huggingface, ollama, nvidia, aws_bedrock"
+    )
+
+
+def _parse_subagent_entries(raw_entries: Any) -> list[SubagentConfig]:
+    if not raw_entries or not isinstance(raw_entries, list):
+        return []
+    configs: list[SubagentConfig] = []
+    for entry in raw_entries:
+        if not isinstance(entry, dict):
+            logger.warning("Skipping non-dict subagent entry: %s", entry)
+            continue
+        if "name" not in entry or "description" not in entry:
+            logger.warning("Skipping subagent entry missing 'name' or 'description': %s", entry)
+            continue
+        vloc = entry.get("vertex_location")
+        if vloc is None and "location" in entry:
+            vloc = entry.get("location")
+        raw_skills = entry.get("skills", [])
+        skills = list(raw_skills) if isinstance(raw_skills, list) else []
+        agent_md = entry.get("agent_md") or entry.get("prompt_file")
+        if agent_md is not None and not isinstance(agent_md, str):
+            logger.warning("Skipping subagent %s: agent_md must be a string", entry.get("name"))
+            continue
+        configs.append(
+            SubagentConfig(
+                name=entry["name"],
+                description=entry["description"],
+                skills=skills,
+                agent_md=agent_md.strip() if isinstance(agent_md, str) and agent_md.strip() else None,
+                model=entry.get("model"),
+                vertex_location=vloc,
+            )
+        )
+    return configs
+
+
+def get_subagent_configs(config_path: str | None = None) -> list[SubagentConfig]:
+    """Return subagent configurations from ``subagents:`` in monkeybot.yaml."""
+    _, doc = load_monkeybot_yaml_dict(config_path)
+    return _parse_subagent_entries(doc.get("subagents"))
+
+
+def get_subagent_registry(config_path: str | None = None) -> dict[str, SubagentConfig]:
+    """Named subagent personas keyed by ``name``; raises :class:`ConfigError` on duplicates."""
+    registry: dict[str, SubagentConfig] = {}
+    for cfg in get_subagent_configs(config_path):
+        if cfg.name in registry:
+            raise ConfigError(f"Duplicate subagent name in monkeybot.yaml: {cfg.name!r}")
+        registry[cfg.name] = cfg
+    return registry
+
+
+def _bool_config_flag(
+    doc: dict[str, Any],
+    section: str,
+    key: str,
+    *,
+    default: bool,
+    label: str,
+) -> bool:
+    section_obj = doc.get(section)
+    if not isinstance(section_obj, dict):
+        return default
+    raw = section_obj.get(key)
+    if raw is None:
+        return default
+    if isinstance(raw, bool):
+        return raw
+    raise ConfigError(f"{label} must be true or false, got {raw!r}")
+
+
+def auto_schema_enabled_from_config(config_path: str | None = None) -> bool:
+    """Whether storage backends should apply DDL on ``open()`` (``paths.auto_schema``).
+
+    Defaults to ``True`` when the key is absent. Only read from monkeybot.yaml —
+    not from environment variables.
+    """
+    _, doc = load_monkeybot_yaml_dict(config_path)
+    paths = doc.get("paths")
+    if not isinstance(paths, dict):
+        return True
+    raw = paths.get("auto_schema")
+    if raw is None:
+        return True
+    if isinstance(raw, bool):
+        return raw
+    raise ConfigError(f"paths.auto_schema must be true or false, got {raw!r}")
+
+
+def vertex_google_search_enabled_from_config(config_path: str | None = None) -> bool:
+    """Whether the main agent enables Gemini's native ``google_search`` grounding tool.
+
+    Read from ``web_search.vertex_google_search`` in monkeybot.yaml. Additive to, and
+    independent of, ``web_search.backend`` (the harness's pluggable DuckDuckGo/Tavily/
+    Firecrawl custom tool). Defaults to ``False`` when absent. Config-file only.
+    """
+    _, doc = load_monkeybot_yaml_dict(config_path)
+    return _bool_config_flag(
+        doc,
+        "web_search",
+        "vertex_google_search",
+        default=False,
+        label="web_search.vertex_google_search",
+    )
+
+
+def subagent_vertex_google_search_from_config(config_path: str | None = None) -> bool:
+    """Whether subagent runs enable Gemini's native ``google_search`` grounding tool.
+
+    Read from ``subagent.vertex_google_search`` in monkeybot.yaml. Defaults to ``False``
+    when absent. Config-file only — not exposed via environment variables.
+    """
+    _, doc = load_monkeybot_yaml_dict(config_path)
+    return _bool_config_flag(
+        doc,
+        "subagent",
+        "vertex_google_search",
+        default=False,
+        label="subagent.vertex_google_search",
+    )