18. Каталог встроенных инструментов

Инструмент (tool) — это функция, которую модель может вызвать в ходе своего ответа (через function_call в OpenAI API / tool_use в Anthropic API). AstraCode имеет ~30 встроенных инструментов плюс динамические (MCP, custom).

Реализация — крейт tools/. Реестр и диспетчеризация — core::tools (см. 19-agent-loop.md).

1. Архитектура

Типы спецификаций

В tools/src/tool_spec.rs:

pub enum ToolSpec {
    Function(ResponsesApiTool),     // обычный function-call (name/description/parameters/strict/...)
    Namespace(ResponsesApiNamespace), // группа инструментов под одним именем
    LocalShell {},                  // OpenAI built-in local_shell
    Freeform(FreeformTool),         // grammar-based (например, apply_patch)
}

Это tuple-варианты enum'а, а не struct с полями (схема выше — концептуальная). Флаг supports_parallel_tool_calls живёт не в самом ToolSpec, а в обёртке ConfiguredToolSpec { spec, supports_parallel_tool_calls }.

Реестр и handlers

Регистрация — build_tool_registry_plan() в tools/src/tool_registry_plan.rs. Возвращает ToolRegistryPlan — список ConfiguredToolSpec (имя + JSON schema + флаг supports_parallel_tool_calls) и соответствующий ToolHandlerSpec для маршрутизации в core.

Enum ToolHandlerKind (tool_registry_plan_types.rs) перечисляет 29 типов handler'ов: Shell, ShellCommand, UnifiedExec, ApplyPatch, Goal, Plan, Mcp, McpResource, SpawnAgentV1/V2, WaitAgentV1/V2, CloseAgentV1/V2, SendInputV1, SendMessageV2, ResumeAgentV1, ListAgentsV2, FollowupTaskV2, AgentJobs, CodeModeExecute, CodeModeWait, RequestUserInput, RequestPermissions, ListDir, ViewImage, DynamicTool, TestSync, ToolSuggest.

Sandbox и approvals

Каждый инструмент маршрутизируется в core::tools::router (см. 19-agent-loop.md) — там применяются permission_profile и approval_policy сессии. Подробнее — 09-security.md.

2. Выполнение команд

exec_command

Файл: tools/src/local_tool.rs:19-89.

Выполнение команды в PTY (unified exec). Может удерживать долгоиграющую сессию.

Возвращает текст output + опционально session_id (если процесс продолжает работать).

Sandbox: проходит через permission_profile (read/write/shell/network). Approval: по политике (untrusted/on-failure/never).

Parallel calls: ✓ (если sandbox разрешает).

write_stdin

Файл: tools/src/local_tool.rs:92-133.

Запись в stdin активной unified-exec сессии. Использует session_id от предыдущего exec_command.

Parallel calls: ✗ (serial по своей природе).

shell (legacy)

Файл: tools/src/local_tool.rs:136+.

Простой однократный shell: получает command: ["arg0", "arg1", ...] массивом и опциональный workdir. Не использует PTY, не держит сессии. Parallel calls: ✓.

shell_command

Альтернативная форма exec_command для legacy провайдеров. Handler: ToolHandlerKind::ShellCommand.

Прим.: ниже «инструмент» и tool используются как синонимы; имена конкретных инструментов и типов (exec_command, ToolHandlerKind и т.п.) не переводятся.

3. Редактирование файлов

apply_patch

Файл: tools/src/apply_patch_tool.rs:89-98.

Freeform-инструмент с grammar (Lark) — не JSON, а специальный формат патчей:

*** Begin Patch
*** Update File: path/to/file.rs
@@ context line
- old line
+ new line
*** End Patch

Поддерживает операции: - *** Add File: — создать файл (с содержимым). - *** Update File: — изменить (с контекстом). - *** Delete File: — удалить.

Approval: по политике; в workspace-write патч в .git/.astracode блокируется sandbox'ом.

Реализация применения — крейт apply-patch/. Поддерживает многосекционные патчи.

Parallel calls: ✗ (изменения файлов сериализуются).

4. Multi-agent (v1 и v2)

Agent — это вложенный AstraCode-поток, который parent может запустить как worker. Используется для декомпозиции задач (один агент координирует, sub-agents выполняют части параллельно).

v2 API (актуальный)

spawn_agent (agent_tool.rs:54-87)

Обязательны task_name и message. Возвращает task_name (канонический). Parallel calls: ✗.

send_message (agent_tool.rs:124-150) — non-blocking сообщение запущенному агенту. Параметры: target, message.

followup_task — последующая задача в той же агентной сессии. Handler: FollowupTaskV2.

wait_agent — блокирующее ожидание обновления mailbox любого живого агента. Параметр: timeout_ms. Handler: WaitAgentV2.

close_agent — корректное завершение sub-agent'а. Handler: CloseAgentV2.

list_agents — список активных sub-agents с их статусом. Handler: ListAgentsV2.

v1 API (legacy)

Сохранён для совместимости. Имена методов те же, но spawn_agent не требует task_name, есть send_input (с поддержкой interrupt) и resume_agent. Handler kinds: SpawnAgentV1, SendInputV1, WaitAgentV1, CloseAgentV1, ResumeAgentV1.

5. Пакетная обработка (Agent Jobs)

Запуск одного и того же агента над CSV-строками с параллелизмом — для batch-задач (массовая обработка тикетов, миграция кода в N файлах, и т.п.).

spawn_agents_on_csv

Файл: tools/src/agent_job_tool.rs:6-63.

Блокирующий вызов — возвращается только когда все workers завершились.

report_agent_job_result

Файл: tools/src/agent_job_tool.rs:66-100.

Worker-only инструмент: внутри sub-agent'а вызывается с job_id, item_id, result, stop, чтобы записать строку в output_csv_path. Parent его не вызывает.

6. Планирование и цели

update_plan

Файл: tools/src/plan_tool.rs:6-49.

Обновление плана задачи. Используется в режиме /plan (см. 13-goal-and-modes.md) и в обычных turn'ах для подачи прогресса в UI.

Статусы: pending, in_progress, completed. Parallel: ✗.

get_goal / create_goal / update_goal

Файл: tools/src/goal_tool.rs.

Управление долгоиграющей целью треда (см. 13-goal-and-modes.md):

• get_goal — вернуть текущую цель (если есть).
• create_goal — параметры objective (текст), token_budget (опционально, в токенах).
• update_goal — status: complete | blocked. Только эти два перехода доступны модели (paused/cleared только через UI).

Parallel: ✗.

7. Запросы к пользователю

request_user_input

Файл: tools/src/request_user_input_tool.rs:11-84.

Запрос интерактивного решения у пользователя — TUI рендерит inline-форму с вариантами.

Возвращает массив ответов. Используется, когда модель упирается в неоднозначность и просит уточнить.

request_permissions

Расположение: local_tool.rs:create_request_permissions_tool.

Явный запрос на расширение sandbox-разрешений в текущей сессии. Не обязателен — обычно модель просто пробует команду и реагирует на approval-диалог.

8. MCP (Model Context Protocol)

См. также 06-mcp.md.

list_mcp_resources

Файл: tools/src/mcp_resource_tool.rs:6-32.

Параметры: server (id), cursor (для пагинации). Возвращает список ресурсов.

list_mcp_resource_templates

Файл: tools/src/mcp_resource_tool.rs:34-60.

То же, но для параметризованных ресурсов (с placeholder'ами в URI).

read_mcp_resource

Файл: tools/src/mcp_resource_tool.rs:62-94.

Параметры: server, uri. Возвращает содержимое ресурса (text/json/blob).

Динамические MCP-инструменты

Каждый MCP-сервер регистрирует свои функции — они автоматически попадают в реестр как Namespace { name: "<server_id>", tools: [...] }. См. tools/src/mcp_tool.rs:6-36. Handler — ToolHandlerKind::Mcp.

9. Вспомогательные

list_dir

Файл: tools/src/utility_tool.rs:6-40.

Перечисление содержимого директории.

Parallel: ✓.

view_image

Файл: tools/src/view_image.rs:14-36.

Подгрузить локальное изображение в контекст модели (если она multi-modal).

Parallel: ✓.

tool_suggest

Файл: tools/src/tool_discovery.rs. Инструмент обнаружения: возвращает список доступных инструментов с описаниями. Используется агентом для «осмотреться, что я умею». Parallel: ✓.

10. Code Mode (встроенный JavaScript-движок)

Экспериментальная функция. Включается feature-флагом code_mode (Stage::UnderDevelopment, default_enabled: false — features/src/lib.rs:602-606); по умолчанию выключена.

code-mode/ крейт — встроенный движок для запуска JavaScript (модель оркестрирует вызовы инструментов кодом). Поддерживается только JavaScript, исполняемый в изолированном V8 isolate (code-mode/src/description.rs:14-20): без Node.js, без файловой системы, без сети, без console. Python не поддерживается. Полезен для оркестрации/композиции tool-вызовов, вычислений, обработки данных.

code_mode (execute)

Файл: tools/src/code_mode.rs:93-120.

Возвращает stdout/stderr/result. Parallel: ✗.

wait

Wait на завершение асинхронной cell. Handler: CodeModeWait.

11. Тестовые / служебные

test_sync_tool

Файл: tools/src/utility_tool.rs:42-96.

Для интеграционных тестов: позволяет синхронизировать параллельные вызовы инструментов через barrier.

Не используется моделью в продакшене — только в тестах LLM-режимов.

Dynamic tools

DynamicToolSpec (dynamic_tool.rs:5-13) — зарегистрированные в runtime инструменты (например, от плагинов). Handler: DynamicTool.

Deferred tools — отложенная загрузка: схема инструмента отправляется модели только по запросу (ToolSearch в Claude), чтобы не раздувать system prompt. См. 19-agent-loop.md.

12. Поведение в sandbox и approval

Каждый инструмент маршрутизируется через permission_profile:

Approval-диалоги — см. 09-security.md.

13. Что НЕ инструмент

В отличие от инструментов, скиллы — это markdown-инструкции, которые подгружаются в контекст; они не имеют JSON-schema, не вызываются как функции. Скилл может использовать инструменты (например, skill-installer использует exec_command для git clone). См. 05-skills.md.

Хуки — это event-listeners на pre/post-tool, не сами инструменты. См. 08-hooks.md.

14. Как добавить свой инструмент

См. подробный recipe в 22-cookbook.md.