| |
|
|
| """Tool name conflict resolution for harness tool injection (RFC 005).""" |
|
|
| from __future__ import annotations |
|
|
| from typing import Collection |
|
|
| from ..env_server.mcp_types import RESERVED_TOOL_NAMES, Tool |
|
|
|
|
| def resolve_tool_conflicts( |
| env_tools: list[Tool], |
| harness_builtin_tools: Collection[str], |
| prefix: str = "env_", |
| ) -> list[Tool]: |
| """ |
| Detect and resolve name conflicts between environment and harness tools. |
| |
| Environment tools whose names collide with the harness's built-in tools |
| are renamed with `prefix`. Ambiguous situations fail loudly instead of |
| silently overriding. |
| |
| Args: |
| env_tools (`list[Tool]`): |
| Environment MCP tool definitions to inject into the harness. |
| harness_builtin_tools (`Collection[str]`): |
| Names of the harness's built-in tools. |
| prefix (`str`, *optional*, defaults to `"env_"`): |
| Prefix applied to conflicting environment tool names. |
| |
| Returns: |
| `list[Tool]` of conflict-free tool definitions. The input list is not |
| mutated. |
| |
| Raises: |
| `ValueError`: If an environment tool uses a reserved orchestration |
| name, if environment tool names are duplicated, or if a prefixed |
| name still collides with a built-in or another environment tool. |
| """ |
| reserved = sorted({tool.name for tool in env_tools} & RESERVED_TOOL_NAMES) |
| if reserved: |
| raise ValueError( |
| "Tool names are reserved for orchestration controls: " + ", ".join(reserved) |
| ) |
|
|
| seen: dict[str, Tool] = {} |
| for tool in env_tools: |
| if tool.name in seen: |
| raise ValueError(f"Duplicate environment tool name: {tool.name}") |
| seen[tool.name] = tool |
|
|
| builtin_names = set(harness_builtin_tools) |
| env_names = set(seen) |
| resolved: list[Tool] = [] |
| taken: set[str] = set() |
| for tool in env_tools: |
| name = tool.name |
| if name in builtin_names: |
| renamed = f"{prefix}{name}" |
| if renamed in builtin_names or renamed in env_names: |
| raise ValueError( |
| f"Cannot resolve tool name conflict: '{name}' collides with a " |
| f"harness built-in tool and '{renamed}' is also taken" |
| ) |
| name = renamed |
| if name in taken: |
| raise ValueError(f"Tool name conflict after prefixing: {name}") |
| taken.add(name) |
| resolved.append(tool.model_copy(update={"name": name})) |
| return resolved |
|
|
|
|
| __all__ = ["resolve_tool_conflicts"] |
|
|
