| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515 |
- """Toolset helpers: get/resolve/validate named tool groups (static TOOLSETS + registry-registered)."""
- from typing import Dict, List, Any, Set, Optional, Tuple
- # Shared tool list for CLI and all messaging platform toolsets (edit once, all
- # platforms follow). Desktop GUI affordances are deliberately NOT here: they live
- # in `desktop_ui`/`project`, enabled per desktop-sourced session by the GUI gateway
- # (tui_gateway/server.py::_load_enabled_toolsets). HA, kanban and computer_use
- # entries are further gated by their tools' check_fns.
- _HERMES_CORE_TOOLS = [
- "web_search", "web_extract",
- "terminal", "process_manage",
- "read_file", "write_file", "patch", "search_files",
- "vision_analyze", "image_generate",
- "skills_list", "skill_view", "skill_manage",
- "browser_exec", # THE browser: Python over CDP (browser-harness)
- "browser_cdp", "browser_dialog",
- "browser_vault", # rides with the browser; deferred by default (tools.tool_search.defer)
- "text_to_speech",
- "todo_list", "memory",
- "session_search",
- "clarify",
- "execute_code", "delegate_task",
- "cronjob_manage",
- "kanban_show", "kanban_list",
- "kanban_complete", "kanban_block", "kanban_request_review",
- "kanban_request_changes",
- "kanban_heartbeat",
- "kanban_comment", "kanban_create", "kanban_link",
- "kanban_unblock",
- "kanban_attach", "kanban_attach_url", "kanban_attachments",
- "computer_use",
- # Service-gated connector account status and authorization links.
- "manage_connections",
- ]
- # Webhook payloads are untrusted third-party content: no file/system execution.
- _HERMES_WEBHOOK_SAFE_TOOLS = ["web_search", "web_extract", "vision_analyze", "clarify"]
- _FEISHU_TOOLS = [
- "feishu_doc_read", "feishu_drive_list_comments", "feishu_drive_list_comment_replies",
- "feishu_drive_reply_comment", "feishu_drive_add_comment",
- ]
- _YUANBAO_TOOLS = ["yb_query_group_info", "yb_query_group_members", "yb_send_dm", "yb_search_sticker", "yb_send_sticker"]
- def _ts(description, tools=(), includes=(), **extra):
- """One TOOLSETS entry (fresh lists per entry; extra keys such as posture pass through)."""
- return {"description": description, "tools": list(tools), "includes": list(includes), **extra}
- def _bundle(description, extras=()):
- """A `hermes-*` platform bundle: the shared core tools plus optional platform extras."""
- return _ts(description, _HERMES_CORE_TOOLS + list(extras))
- def _core_without(*excluded, kanban=True):
- """_HERMES_CORE_TOOLS minus *excluded* (and, unless kanban=True, every kanban_* tool); order preserved."""
- return [t for t in _HERMES_CORE_TOOLS if t not in excluded and (kanban or not t.startswith("kanban_"))]
- # Coding posture: everything you reach for while pairing on code; drops messaging,
- # tts, image_gen, cron, kanban and computer-use.
- _CODING_TOOLS = _core_without("image_generate", "text_to_speech", "cronjob_manage", "computer_use", kanban=False)
- # Toolsets a CLIENT adds to its own sessions (tui_gateway/server.py::_gui_surface_toolsets), never
- # config: another surface lacking them made no configuration choice.
- CLIENT_SURFACE_TOOLSETS = frozenset({"project", "desktop_ui", "catalog"})
- # Core toolset definitions: individual tools or references to other toolsets.
- TOOLSETS = {
- # Basic toolsets - individual tool categories
- "web": _ts("Web research and content extraction tools", ["web_search", "web_extract"]),
- "search": _ts("Web search only (no content extraction/scraping)", ["web_search"]),
- "x_search": _ts(
- "Search X (Twitter) posts and threads via xAI's built-in x_search Responses "
- "tool. Read-only public X discovery; use the xurl skill for authenticated X "
- "API reads and account actions. Available when xAI credentials are configured "
- "(SuperGrok OAuth or XAI_API_KEY). Off by default; enable in `hermes tools` → "
- "X (Twitter) Search.",
- ["x_search"],
- ),
- "vision": _ts("Image analysis and vision tools", ["vision_analyze"]),
- "video": _ts("Video analysis and understanding tools (opt-in, not in default toolset)", ["video_analyze"]),
- "image_gen": _ts("Creative generation tools (images)", ["image_generate"]),
- "video_gen": _ts(
- "Video generation tools. Single ``video_generate`` tool covers text-to-video "
- "(prompt only) and image-to-video (prompt + image_url), plus "
- "reference-to-video. Provider-specific edit/extend workflows may appear as "
- "separate tools. Configure via ``hermes tools`` → Video Generation.",
- ["video_generate", "xai_video_edit", "xai_video_extend"],
- ),
- "computer_use": _ts(
- "Background desktop control via cua-driver (macOS/Windows/Linux) — "
- "screenshots, mouse, keyboard, scroll, drag. Does NOT steal the user's cursor "
- "or keyboard focus. Works with any tool-capable model.",
- ["computer_use"],
- ),
- "terminal": _ts("Terminal/command execution and process management tools", ["terminal", "process_manage"]),
- "skills": _ts(
- "Access, create, edit, and manage skill documents with specialized "
- "instructions and knowledge",
- ["skills_list", "skill_view", "skill_manage"],
- ),
- # web_search belongs to `web`/`search` only. Listing it here too let
- # `disabled_toolsets: [browser]` (headless/Docker deployments) strip
- # web_search from every session, because disabled toolsets are a strict
- # end-of-pipeline subtraction (#17309, #64503).
- "browser": _ts(
- "Browser automation: drive a real browser with Python over CDP (navigate, "
- "click, type, extract, screenshots), raw CDP, dialogs and vault logins",
- [t for t in _HERMES_CORE_TOOLS if t.startswith("browser_")],
- ),
- "cronjob": _ts(
- "Cronjob management tool - create, list, update, pause, resume, remove, and "
- "trigger scheduled tasks",
- ["cronjob_manage"],
- ),
- "file": _ts(
- "File manipulation tools: read, write, patch (with fuzzy matching), and "
- "search (content + files)",
- ["read_file", "write_file", "patch", "search_files"],
- ),
- "tts": _ts("Text-to-speech: convert text to audio with Edge TTS (free), ElevenLabs, OpenAI, or xAI", ["text_to_speech"]),
- "todo": _ts("Task planning and tracking for multi-step work", ["todo_list"]),
- "memory": _ts("Persistent memory across sessions (personal notes + user profile)", ["memory"]),
- "context_engine": _ts("Runtime tools exposed by the active context engine"),
- "session_search": _ts("Search and recall past conversations with summarization", ["session_search"]),
- "connections": _ts("Remote connector discovery, execution, and account authorization", ["manage_connections"]),
- "project": _ts("Desktop Projects — create/switch named workspaces (GUI sessions only)", ["desktop_project"]),
- "bot_room": _ts("Verified text-only Group Chat turn capabilities"),
- # GUI-renderer affordances, enabled per desktop-sourced SESSION by the GUI
- # gateway (tui_gateway/server.py::_load_enabled_toolsets) — never by a
- # process env var, which is blind to a desktop client on a remote backend.
- "desktop_ui": _ts(
- "Desktop GUI affordances — in-app terminal/browser panes, pane focus, "
- "reactions, appearance (GUI sessions only)",
- ["read_terminal", "close_terminal", "desktop_preview", "drive_preview",
- "annotate_preview", "read_window_below", "focus_pane", "react_to_message",
- "gui_tour", "show_tip", "set_theme"],
- ),
- "onboarding": _ts("First-run onboarding cards; folded in only for the onboarding chat (tui_gateway/methods_onboarding.py)",
- ["setup_beat"], platforms=frozenset({"desktop"})),
- # ``platforms``: the session platforms this toolset exists for (TOOLSET_SESSION_PLATFORMS).
- "catalog": _ts(
- "Desktop catalog plugin/skill install requests through the approval card (GUI sessions only)",
- ["manage_catalog"],
- platforms=frozenset({"desktop"}),
- ),
- "clarify": _ts("Ask the user clarifying questions (multiple-choice or open-ended)", ["clarify"]),
- "code_execution": _ts("Run Python scripts that call tools programmatically (reduces LLM round trips)", ["execute_code"]),
- "delegation": _ts("Spawn subagents with isolated context for complex subtasks", ["delegate_task"]),
- "kanban": _ts(
- "Kanban multi-agent coordination — only active when the agent is spawned by "
- "the kanban dispatcher (HERMES_KANBAN_TASK env set). The dispatcher runs "
- "inside the gateway by default; see `kanban.dispatch_in_gateway` in "
- "config.yaml. Lets workers mark tasks done with structured handoffs, enter "
- "first-class review (request_review — not a block), return review changes, "
- "block for human input, heartbeat during long ops, comment on threads, attach "
- "files, and (for orchestrators) list, unblock, and fan out tasks.",
- [t for t in _HERMES_CORE_TOOLS if t.startswith("kanban_")],
- ),
- "discord": _ts("Discord read and participate tools (fetch messages, search members, create threads)", ["discord"]),
- "discord_admin": _ts("Discord server management (list channels/roles, pin messages, assign roles)", ["discord_admin"]),
- "yuanbao": _ts("Yuanbao platform tools - group info, member queries, DM, stickers", _YUANBAO_TOOLS),
- "feishu_doc": _ts("Read Feishu/Lark document content", ["feishu_doc_read"]),
- "feishu_drive": _ts("Feishu/Lark document comment operations (list, reply, add)", _FEISHU_TOOLS[1:]),
- # Scenario-specific toolsets
- "debugging": _ts("Debugging and troubleshooting toolkit", ["terminal", "process_manage"], includes=["web", "file"]),
- "safe": _ts("Safe toolkit without terminal access", [], includes=["web", "vision", "image_gen"]),
- # Coding posture, auto-selected in a code workspace (agent/coding_context.py).
- # `desktop_ui` is folded in separately by the GUI gateway for desktop sessions.
- # posture=True: per-session posture, never auto-recovered into platform tool
- # config (see the non-configurable-toolset recovery loop in hermes_cli/tools_config.py).
- "coding": _ts(
- "Coding-focused toolset: files, terminal, search, web docs, skills, todo, "
- "delegate, vision, browser",
- _CODING_TOOLS,
- posture=True,
- ),
- # Full Hermes toolsets (CLI + messaging platforms). All share the core tools;
- # there is deliberately no agent-callable send_message tool. hermes-acp is the
- # coding posture minus the interactive clarify UI.
- "hermes-acp": _ts(
- "Editor integration (VS Code, Zed, JetBrains) — coding-focused tools without "
- "messaging, audio, or clarify UI",
- [t for t in _CODING_TOOLS if t != "clarify"],
- ),
- "hermes-api-server": _ts(
- "OpenAI-compatible API server — full agent tools accessible via HTTP (no "
- "interactive UI tools like clarify or send_message)",
- _core_without("text_to_speech", "clarify", "computer_use", kanban=False),
- ),
- "hermes-cli": _bundle("Full interactive CLI toolset - all default tools plus cronjob management"),
- # Mirrors hermes-cli; `hermes tools` platform config filters it down and
- # _get_platform_tools() drops _DEFAULT_OFF_TOOLSETS unless user-enabled.
- "hermes-cron": _bundle("Default cron toolset - same core tools as hermes-cli; gated by `hermes tools`"),
- "hermes-telegram": _bundle("Telegram bot toolset - full access for personal use (terminal has safety checks)"),
- "hermes-discord": _bundle(
- "Discord bot toolset - full access (terminal has safety checks via dangerous "
- "command approval)",
- ["discord", "discord_admin"],
- ),
- "hermes-whatsapp": _bundle("WhatsApp bot toolset - similar to Telegram (personal messaging, more trusted)"),
- "hermes-slack": _bundle("Slack bot toolset - full access for workspace use (terminal has safety checks)"),
- "hermes-signal": _bundle("Signal bot toolset - encrypted messaging platform (full access)"),
- "hermes-bluebubbles": _bundle("BlueBubbles iMessage bot toolset - Apple iMessage via local BlueBubbles server"),
- "hermes-email": _bundle("Email bot toolset - interact with Hermes via email (IMAP/SMTP)"),
- "hermes-mattermost": _bundle("Mattermost bot toolset - self-hosted team messaging (full access)"),
- "hermes-matrix": _bundle("Matrix bot toolset - decentralized encrypted messaging (full access)"),
- "hermes-dingtalk": _bundle("DingTalk bot toolset - enterprise messaging platform (full access)"),
- "hermes-feishu": _bundle("Feishu/Lark bot toolset - enterprise messaging via Feishu/Lark (full access)", _FEISHU_TOOLS),
- "hermes-weixin": _bundle("Weixin bot toolset - personal WeChat messaging via iLink (full access)"),
- "hermes-qqbot": _bundle("QQBot toolset - QQ messaging via Official Bot API v2 (full access)"),
- "hermes-wecom": _bundle("WeCom bot toolset - enterprise WeChat messaging (full access)"),
- "hermes-wecom-callback": _bundle("WeCom callback toolset - enterprise self-built app messaging (full access)"),
- "hermes-yuanbao": {
- "description": "Yuanbao Bot 元宝消息平台工具集 - 群信息、成员查询、私聊、贴纸表情",
- "tools": _HERMES_CORE_TOOLS + _YUANBAO_TOOLS,
- "module": "tools.yuanbao_tools",
- "includes": [],
- },
- "hermes-sms": _bundle("SMS bot toolset - interact with Hermes via SMS (Twilio)"),
- "hermes-webhook": _ts("Webhook toolset - receive and process external webhook events", _HERMES_WEBHOOK_SAFE_TOOLS),
- "hermes-gateway": _ts(
- "Gateway toolset - union of all messaging platform tools",
- [],
- includes=[
- "hermes-telegram", "hermes-discord", "hermes-whatsapp", "hermes-slack",
- "hermes-signal", "hermes-bluebubbles", "hermes-email",
- "hermes-sms", "hermes-mattermost", "hermes-matrix", "hermes-dingtalk",
- "hermes-feishu", "hermes-wecom", "hermes-wecom-callback", "hermes-weixin",
- "hermes-qqbot", "hermes-webhook", "hermes-yuanbao",
- ],
- ),
- }
- # Toolset -> the session platforms it exists for, from the specs that carry ``platforms``.
- TOOLSET_SESSION_PLATFORMS = {name: spec["platforms"] for name, spec in TOOLSETS.items() if "platforms" in spec}
- # Captured before create_custom_toolset() can add user-named tools: shared metrics may export only
- # these names, so a plugin, MCP server or custom toolset name never leaves the machine.
- BUILTIN_TOOL_NAMES = frozenset(tool for spec in TOOLSETS.values() for tool in spec["tools"])
- BUILTIN_TOOLSET_NAMES = frozenset(TOOLSETS)
- def _registry():
- """Live tool registry, or None when tools.registry can't be imported."""
- try:
- from tools.registry import registry
- return registry
- except Exception:
- return None
- def _registry_call(method: str, default):
- """registry.<method>() or *default* when the registry is unavailable or the call fails."""
- try:
- return getattr(_registry(), method)()
- except Exception: # registry None (AttributeError) or the call failed
- return default
- def _registry_generation() -> tuple[int, int]:
- reg = _registry()
- return (id(reg), getattr(reg, "_generation", 0)) if reg is not None else (0, 0)
- def get_toolset(name: str, *, include_registry: bool = True) -> Optional[dict[str, Any]]:
- """Toolset definition, or None if unknown.
- include_registry=True merges plugin/overlay tools registered into this toolset
- and resolves registry-only (plugin/MCP) toolsets and aliases; False returns a
- copy of the static TOOLSETS entry only, so platform reverse-mapping is
- unaffected by registry additions.
- Args: name (str): Name of the toolset include_registry (bool): When True (default), merge in tools that
- plugins/overlays registered into this toolset via the registry. Platform reverse-mapping in
- ``_get_platform_tools`` uses False so that a tool registered into a toolset but absent from a platform's
- static composite does not drop the whole toolset from inference. See issue #49622.
- """
- toolset = TOOLSETS.get(name)
- if not include_registry:
- return {**toolset, "tools": list(toolset.get("tools", [])), "includes": list(toolset.get("includes", []))} if toolset else None
- registry = _registry()
- if registry is None:
- return toolset if toolset else None
- if toolset:
- merged_tools = set(toolset.get("tools", [])) | set(registry.get_tool_names_for_toolset(name))
- # An MCP server named like a built-in toolset ("browser", "memory") registers a bare
- # alias to its `mcp-<name>` toolset; without this union the static entry shadows it and the
- # server's tools never reach the model even though discovery registered them.
- alias_target = registry.get_toolset_alias_target(name)
- if alias_target and alias_target != name:
- merged_tools |= set(registry.get_tool_names_for_toolset(alias_target))
- return {**toolset, "tools": sorted(merged_tools)}
- if name in _get_plugin_toolset_names():
- # Plugin toolset; shown as its MCP server alias when one exists.
- registry_toolset = name
- alias = _display_alias(name, _get_registry_toolset_aliases())
- description = f"MCP server '{alias}' tools" if alias else f"Plugin toolset: {name}"
- else:
- registry_toolset = registry.get_toolset_alias_target(name)
- if not registry_toolset:
- return None
- description = f"MCP server '{name}' tools"
- return {"description": description, "tools": registry.get_tool_names_for_toolset(registry_toolset), "includes": []}
- def bundle_non_core_tools(toolset_name: str) -> set[str]:
- """A bundle's tools minus _HERMES_CORE_TOOLS (one level of includes).
- Disabling a `core + extras` bundle must not strip the core tools every other
- toolset shares. One `includes` pass suffices (only hermes-gateway nests
- bundles). Unknown names: full resolution minus core.
- """
- core = set(_HERMES_CORE_TOOLS)
- ts_def = get_toolset(toolset_name)
- if not (ts_def and "tools" in ts_def):
- return set(resolve_toolset(toolset_name)) - core
- to_remove = set(ts_def["tools"])
- for inc_def in map(get_toolset, ts_def.get("includes", [])):
- if inc_def and "tools" in inc_def:
- to_remove.update(inc_def["tools"])
- return to_remove - core
- # Memo keyed on (name, include_registry, id(registry), registry generation, profile scope);
- # engages only at the public entry (visited is None). The scope is part of the key because a
- # multiplexed process resolves ``mcp-<server>`` per profile overlay: without it profile B got
- # profile A's tool names for a server B never connected (#106005).
- _resolve_toolset_memo: dict[tuple[str, bool, int, int, str], list[str]] = {}
- def _plugin_platform_bundle(name: str) -> list[str]:
- """Implicit `hermes-<platform>` bundle for a registered plugin platform: core
- tools plus whatever the plugin registered under the platform name. [] otherwise."""
- if not name.startswith("hermes-"):
- return []
- platform_name = name[len("hermes-"):]
- try:
- from gateway.platform_registry import platform_registry
- if not platform_registry.is_registered(platform_name):
- return []
- except Exception:
- return []
- tools = set(_HERMES_CORE_TOOLS)
- try:
- tools.update(e.name for e in _registry_call("get_all_entries", ()) if e.toolset == platform_name)
- except Exception:
- pass
- return list(tools)
- def resolve_toolset(name: str, visited: set[str] | None = None, *, include_registry: bool = True) -> list[str]:
- """Recursively resolve a toolset (and its includes) to a sorted tool-name list.
- include_registry=False resolves the static TOOLSETS view only.
- Args: name (str): Name of the toolset to resolve visited (Set[str]): Set of already visited toolsets
- (for cycle detection) include_registry (bool): When True (default), include tools that plugins/overlays
- registered into a toolset. Platform reverse-mapping uses False so a registry-added tool cannot drop the
- whole toolset from inference (see #49622 and ``_get_platform_tools``).
- """
- external_call = visited is None
- if external_call:
- memo_key = (name, include_registry, *_registry_generation(), _registry_call("current_scope_key", ""))
- cached = _resolve_toolset_memo.get(memo_key)
- if cached is not None:
- return list(cached)
- visited = set()
- # "all"/"*" span every toolset so new toolsets are included automatically, except the ones a
- # session platform gates: a profile gets those only when its config names them.
- if name in {"all", "*"}:
- all_tools: set[str] = set()
- for toolset_name in get_toolset_names():
- if toolset_name not in TOOLSET_SESSION_PLATFORMS:
- all_tools.update(resolve_toolset(toolset_name, visited.copy(), include_registry=include_registry))
- return sorted(all_tools)
- # Diamond include or cycle: [] silently — the tools are collected via another path.
- if name in visited:
- return []
- visited.add(name)
- toolset = get_toolset(name, include_registry=include_registry)
- if not toolset:
- return _plugin_platform_bundle(name) if include_registry else []
- tools = set(toolset.get("tools", []))
- for included_name in toolset.get("includes", []):
- tools.update(resolve_toolset(included_name, visited, include_registry=include_registry))
- result = sorted(tools)
- if external_call:
- if len(_resolve_toolset_memo) >= 256: # stale-generation entries are never hit again
- _resolve_toolset_memo.clear()
- _resolve_toolset_memo[memo_key] = list(result)
- return result
- def _get_plugin_toolset_names() -> set[str]:
- """Registry toolset names absent from the static TOOLSETS dict."""
- return {n for n in _registry_call("get_registered_toolset_names", ()) if n not in TOOLSETS}
- def _get_registry_toolset_aliases() -> dict[str, str]:
- return _registry_call("get_registered_toolset_aliases", {})
- def _display_alias(ts_name: str, aliases: dict[str, str]) -> Optional[str]:
- """First non-static alias pointing at *ts_name*, or None."""
- return next((a for a, canonical in aliases.items() if canonical == ts_name and a not in TOOLSETS), None)
- def _plugin_display_names() -> list[str]:
- """Plugin toolset names, shown under their first non-static alias when one exists."""
- aliases = _get_registry_toolset_aliases()
- return [_display_alias(n, aliases) or n for n in _get_plugin_toolset_names()]
- def get_all_toolsets() -> dict[str, dict[str, Any]]:
- """All toolset definitions: static plus plugin-registered."""
- result = dict(TOOLSETS)
- aliases = _get_registry_toolset_aliases()
- for display_name in _plugin_display_names():
- toolset = None if display_name in result else get_toolset(display_name)
- if toolset:
- result[display_name] = toolset
- # Static names an MCP server also aliases show the merged view get_toolset() resolves.
- for name in TOOLSETS.keys() & aliases.keys():
- result[name] = get_toolset(name) or result[name]
- return result
- def get_toolset_names() -> list[str]:
- """Sorted names of all toolsets (static + plugin), excluding aliases."""
- return sorted(set(TOOLSETS.keys()) | set(_plugin_display_names()))
- def session_platform_tool_drops(platform: Optional[str]) -> frozenset:
- """Tools of every platform-gated toolset that a session on *platform* does not get."""
- return frozenset(tool for name, platforms in TOOLSET_SESSION_PLATFORMS.items() if platform not in platforms
- for tool in resolve_toolset(name))
- def session_disabled_toolsets(
- disabled: Optional[list[str]], platform: Optional[str], *, oneshot: bool = False,
- ) -> Optional[list[str]]:
- """*disabled* plus every platform-gated toolset a session on *platform* does not get, and for a *oneshot*
- session the toolsets nobody is there to use (``agent.oneshot_footprint.ONESHOT_DISABLED_TOOLSETS``). An agent
- stores this as its ``disabled_toolsets``, so the tool list, the tool_search listing and bridge, MCP refreshes
- and delegate children (which inherit it) all subtract the gated tools in ``_select_tool_names``."""
- from agent.oneshot_footprint import ONESHOT_DISABLED_TOOLSETS
- gated = [name for name, platforms in TOOLSET_SESSION_PLATFORMS.items() if platform not in platforms]
- gated += ONESHOT_DISABLED_TOOLSETS if oneshot else ()
- gated = [name for name in gated if name not in (disabled or ())]
- return [*(disabled or ()), *gated] if gated else disabled
- def tool_selection_key(enabled: Optional[list[str]], disabled: Optional[list[str]]) -> tuple:
- """The toolset selection a tools[] snapshot was built from, order-free. Recorded next to the registry
- generation: the tools[] freeze (``tools.mcp_tool_agent``) holds new tools back only while neither moved."""
- return frozenset(enabled) if enabled is not None else None, frozenset(disabled or ())
- def agent_tool_drops(agent: Any) -> frozenset:
- """Tool names *agent* never carries, whatever its toolsets resolved to: the side-agent drops and
- the toolsets its session platform does not get. Applied at load, MCP refresh and prefix restore."""
- from tools.connectors.turn import side_agent_tool_drops
- return side_agent_tool_drops(agent) | session_platform_tool_drops(getattr(agent, "platform", None))
- def agent_tool_surface(agent: Any, tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
- """*tools* as *agent* carries them: :func:`agent_tool_drops` removed and, in a one-shot session or a gateway
- session that joins its delegations in the turn (``delegation.gateway_mode``), the joined ``delegate_task``
- variant (``agent.oneshot_footprint.oneshot_tool_schemas``). Applied to FRESH definitions (load, MCP refresh)
- before any merge: a pinned or carried entry keeps the bytes already sent."""
- from agent.oneshot_footprint import agent_is_oneshot, oneshot_tool_schemas
- from tools.delegate_tool_config import agent_joins_delegation
- drops = agent_tool_drops(agent)
- tools = [tool for tool in tools if (tool.get("function") or {}).get("name") not in drops] if drops else list(tools)
- return oneshot_tool_schemas(tools) if agent_is_oneshot(agent) or agent_joins_delegation(agent) else tools
- def validate_toolset(name: str) -> bool:
- return (name in {"all", "*"} or name in TOOLSETS
- or name in _get_plugin_toolset_names() or name in _get_registry_toolset_aliases())
- def create_custom_toolset(name: str, description: str, tools: list[str] | None = None, includes: list[str] | None = None) -> None:
- """Register a runtime toolset in TOOLSETS."""
- TOOLSETS[name] = _ts(description, tools or [], includes or [])
- def get_toolset_info(name: str) -> dict[str, Any]:
- """Toolset definition plus its resolved tools, or None if unknown."""
- toolset = get_toolset(name)
- if not toolset:
- return None
- resolved_tools = resolve_toolset(name)
- return {
- "name": name, "description": toolset["description"],
- "direct_tools": toolset["tools"], "includes": toolset["includes"],
- "resolved_tools": resolved_tools, "tool_count": len(resolved_tools),
- "is_composite": bool(toolset["includes"]),
- }
|