Files
codex/codex-sdk-v2/src/codex_sdk_v2/tools.py
T

284 lines
7.2 KiB
Python

from __future__ import annotations
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Awaitable, Callable, ClassVar, Mapping, Sequence
if TYPE_CHECKING:
from .pending_tool_calls import PendingCommandExecution
from .pending_tool_calls import PendingFunctionToolCall
from .pending_tool_calls import ToolDecision
if TYPE_CHECKING:
BuiltinApprovalPolicy = Callable[
[PendingCommandExecution],
Awaitable[ToolDecision | None] | ToolDecision | None,
]
else:
BuiltinApprovalPolicy = Callable[[Any], Awaitable[Any] | Any]
@dataclass(frozen=True, slots=True)
class BuiltinToolSpec:
tool_name: str
class Tool:
pass
@dataclass(frozen=True, slots=True)
class ConfiguredBuiltinTool(Tool):
tool_type: type["BuiltinTool"]
approval_policy: BuiltinApprovalPolicy | None = None
def builtin_spec(self) -> BuiltinToolSpec:
return self.tool_type.builtin_spec()
class BuiltinTool(Tool):
codex_builtin_tool: ClassVar[str]
@classmethod
def builtin_spec(cls) -> BuiltinToolSpec:
tool_name = getattr(cls, "codex_builtin_tool", None)
if not tool_name:
raise TypeError(f"{cls.__name__} must define codex_builtin_tool")
return BuiltinToolSpec(tool_name=tool_name)
@classmethod
def with_approval_policy(
cls,
*,
policy: BuiltinApprovalPolicy,
) -> ConfiguredBuiltinTool:
return ConfiguredBuiltinTool(tool_type=cls, approval_policy=policy)
class FunctionTool(Tool):
name: ClassVar[str]
description: ClassVar[str]
input_schema: ClassVar[dict[str, Any]]
@classmethod
def dynamic_tool_spec(cls) -> dict[str, Any]:
name = getattr(cls, "name", None)
description = getattr(cls, "description", None)
input_schema = getattr(cls, "input_schema", None)
if not name:
raise TypeError(f"{cls.__name__} must define name")
if not description:
raise TypeError(f"{cls.__name__} must define description")
if not isinstance(input_schema, dict):
raise TypeError(f"{cls.__name__} must define input_schema as a dict")
return {
"name": name,
"description": description,
"inputSchema": input_schema,
}
async def approve(self, call: PendingFunctionToolCall) -> ToolDecision | None:
return None
def instructions(self) -> str | None:
return None
async def run(self, arguments: Mapping[str, Any]) -> Any:
raise NotImplementedError
class ExecCommand(BuiltinTool):
codex_builtin_tool = "exec_command"
class WriteStdin(BuiltinTool):
codex_builtin_tool = "write_stdin"
class Shell(BuiltinTool):
codex_builtin_tool = "shell"
class UpdatePlan(BuiltinTool):
codex_builtin_tool = "update_plan"
class RequestUserInput(BuiltinTool):
codex_builtin_tool = "request_user_input"
class ApplyPatch(BuiltinTool):
codex_builtin_tool = "apply_patch"
class WebSearch(BuiltinTool):
codex_builtin_tool = "web_search"
class ViewImage(BuiltinTool):
codex_builtin_tool = "view_image"
class SearchToolBm25(BuiltinTool):
codex_builtin_tool = "search_tool_bm25"
class ReadFile(BuiltinTool):
codex_builtin_tool = "read_file"
class ListDir(BuiltinTool):
codex_builtin_tool = "list_dir"
class GrepFiles(BuiltinTool):
codex_builtin_tool = "grep_files"
class ListMcpResources(BuiltinTool):
codex_builtin_tool = "list_mcp_resources"
class ListMcpResourceTemplates(BuiltinTool):
codex_builtin_tool = "list_mcp_resource_templates"
class ReadMcpResource(BuiltinTool):
codex_builtin_tool = "read_mcp_resource"
class SpawnAgent(BuiltinTool):
codex_builtin_tool = "spawn_agent"
class SendInput(BuiltinTool):
codex_builtin_tool = "send_input"
class ResumeAgent(BuiltinTool):
codex_builtin_tool = "resume_agent"
class Wait(BuiltinTool):
codex_builtin_tool = "wait"
class CloseAgent(BuiltinTool):
codex_builtin_tool = "close_agent"
class SpawnAgentsOnCsv(BuiltinTool):
codex_builtin_tool = "spawn_agents_on_csv"
class JsRepl(BuiltinTool):
codex_builtin_tool = "js_repl"
class JsReplReset(BuiltinTool):
codex_builtin_tool = "js_repl_reset"
class Artifacts(BuiltinTool):
codex_builtin_tool = "artifacts"
class ReportAgentJobResult(BuiltinTool):
codex_builtin_tool = "report_agent_job_result"
class TestSyncTool(BuiltinTool):
codex_builtin_tool = "test_sync_tool"
ALL_BUILTIN_TOOLS: tuple[type[BuiltinTool], ...] = (
ExecCommand,
WriteStdin,
Shell,
UpdatePlan,
RequestUserInput,
ApplyPatch,
WebSearch,
ViewImage,
SearchToolBm25,
ReadFile,
ListDir,
GrepFiles,
ListMcpResources,
ListMcpResourceTemplates,
ReadMcpResource,
SpawnAgent,
SendInput,
ResumeAgent,
Wait,
CloseAgent,
SpawnAgentsOnCsv,
JsRepl,
JsReplReset,
Artifacts,
ReportAgentJobResult,
TestSyncTool,
)
def builtin_tools(tools: Sequence[Tool | type[Tool]]) -> tuple[list[str], dict[str, BuiltinApprovalPolicy]]:
names: list[str] = []
policies: dict[str, BuiltinApprovalPolicy] = {}
seen: set[str] = set()
for tool in tools:
resolved = tool if isinstance(tool, ConfiguredBuiltinTool) else None
tool_type = resolved.tool_type if resolved is not None else tool if isinstance(tool, type) else type(tool)
if not isinstance(tool_type, type) or not issubclass(tool_type, BuiltinTool):
continue
name = tool_type.builtin_spec().tool_name
if name not in seen:
seen.add(name)
names.append(name)
if resolved is not None and resolved.approval_policy is not None:
policies[name] = resolved.approval_policy
return names, policies
def function_tools(tools: Sequence[Tool | type[Tool]]) -> list[FunctionTool]:
resolved: list[FunctionTool] = []
seen: set[str] = set()
builtin_names = {tool.builtin_spec().tool_name for tool in ALL_BUILTIN_TOOLS}
for tool in tools:
if isinstance(tool, ConfiguredBuiltinTool):
continue
tool_instance = tool() if isinstance(tool, type) else tool
if not isinstance(tool_instance, FunctionTool):
continue
tool_name = type(tool_instance).dynamic_tool_spec()["name"]
if tool_name in builtin_names:
raise ValueError(f"function tool name collides with codex built-in: {tool_name}")
if tool_name in seen:
raise ValueError(f"duplicate function tool name: {tool_name}")
seen.add(tool_name)
resolved.append(tool_instance)
return resolved
def tool_instruction_fragments(tools: Sequence[Tool | type[Tool]]) -> list[str]:
fragments: list[str] = []
seen: set[str] = set()
for tool in tools:
if isinstance(tool, ConfiguredBuiltinTool):
continue
tool_instance = tool() if isinstance(tool, type) else tool
if isinstance(tool_instance, FunctionTool):
fragment = tool_instance.instructions()
key = f"function:{type(tool_instance).dynamic_tool_spec()['name']}"
if fragment and key not in seen:
seen.add(key)
fragments.append(fragment)
return fragments
DEFAULT_TOOLS: tuple[type[BuiltinTool], ...] = (
ExecCommand,
WriteStdin,
)