Timelix Tools

Timelix Tools — модуль, который отвечает за выдачу инструментов агенту и их исполнение в правильном контексте (userId, agentId, todoListId, timezone).

Два слоя инструментов

1. Built-in system tools

Встроенные инструменты описаны в features/TimelixTools/definitions/*, а source of truth для UI, debug-панелей и MCP runtime — features/TimelixTools/registry.ts.

В built-in слой сейчас входят:

• system tools
• todo tools
• epics
• metrics
• integrations
• navigation и chatUI tools
• docs-инструменты getDoc, appendDoc, searchDocs

revertDoc и listDocVersions тоже встроены в Timelix, но доступны только в chatUI, не через MCP.

2. Company / Store tools

Второй слой — инструменты компании и Store-модули. Они подключаются к роли по данным из content блока role:

• linkedToolIds — привязанные company tools
• disabledToolIds — отключённые среди привязанных
• disabledSystemTools — скрытые built-in инструменты

При runtime-загрузке итоговый набор собирается через loadToolsForAgentById(): built-in слой фильтруется по disabledSystemTools, а company tools берутся как linkedToolIds - disabledToolIds.

Где используются contexts

У built-in tools есть два основных контекста:

• mcp — инструмент может уехать во внешний MCP runtime
• chatUI — инструмент доступен в UI-режиме чата и локальных debug flows

Это важно, потому что список в debug UI и список в агентском MCP-потоке не обязаны совпадать один в один.

Как агент получает инструменты

В чате

При запросе в Timelix Chat backend поднимает роль агента, считывает её конфигурацию и загружает инструменты через loadToolsForAgentById(agentId).

Этот набор затем:

• передаётся в Agent Server или Codex как tool definitions
• или исполняется локально в TanStack AI
• или используется для сборки mcpServerUrl, если backend работает через MCP

В MCP

Маршрут /api/agent/mcp использует тот же принцип: если есть agentId, сервер отдаёт агенту только разрешённый набор built-in и company tools. Если agentId не передан, MCP регистрирует общий built-in набор из registry.

Debug-поверхности модуля

/[id]/tools

Страница-обозреватель built-in инструментов из registry. Показывает категории, contexts и параметры, но не учитывает company tools конкретного агента.

/[id]/timelix-tools

Debug-страница для просмотра и ручного запуска инструментов. Может работать в двух режимах:

• все built-in system tools
• агент-специфичный набор через /api/timelix-tools/tools?agentId=...

ToolsDebugPanel

Встроенная панель в role chat. Позволяет вручную вызвать инструмент через /api/timelix-tools/execute, подставив userId, agentId и todoListId.

/api/timelix-tools/execute

Прямой debug endpoint для выполнения built-in registry tool по имени.

/api/timelix-tools/tools

Возвращает:

• все built-in tools, если agentId не задан
• agent-specific MCP-набор, если agentId передан

Это главный endpoint для диагностики вопроса «что реально доступно именно этому агенту».

Типичные проблемы

Инструмент есть в коде, но его не видно агенту

Проверьте по порядку:

1. Экспортирован ли built-in tool из features/TimelixTools/registry.ts.
2. Не попал ли он в disabledSystemTools.
3. Если это company/store tool — есть ли он в linkedToolIds и не отключён ли через disabledToolIds.
4. Передаётся ли agentId в /api/agent/chat или /api/agent/mcp.

Инструмент есть в debug UI, но не уезжает во внешний runtime

Чаще всего это расхождение между chatUI и mcp contexts. Смотрите tool.contexts и проверяйте, какой именно поток используется для конкретного агента.

Инструмент падает на данных

Проверьте ToolExecutionContext:

• userId обязателен
• agentId нужен для agent-scoped операций
• todoListId нужен для todo tools
• timezone нужен для корректной работы дат и календаря

Связанные разделы

• Timelix Chat — как tools добавляются в chat payload
• MCP-сервер Timelix — как tools отдаются по MCP
• Задачи и MCP — зачем инструментам нужен todoListId