@elastic.io/mcp 1.0.1-dev10 → 1.0.1-dev11

package/resources/docs/flow-creation-stages.md

@@ -0,0 +1,195 @@
+# Flow Lifecycle (State Machine)
+
+One continuous cycle. After LOGS the flow is RUNNING — any modification request loops back through the modification stages.
+
+```
+INIT → DISCOVERY → SKELETON → METADATA → MAPPERS → PUBLISH_DRAFT → START → RUN_NOW → LOGS → RUNNING
+                                                                                         ↓
+                                                              user requests a change      ↓
+                                                                                         ↓
+                                                    INSPECT → STOP → DISCOVERY(changed) → IMPACT
+                                                                                         ↓
+                                                         re-do affected stages (see below)
+                                                                                         ↓
+                                              PUBLISH_DRAFT → START → RUN_NOW → LOGS → RUNNING
+                                                                                         ↓
+                                                                                        ...
+```
+
+---
+
+## Stage 1: INIT
+
+**Trigger:** `create_flow` — creates an empty flow (no graph).
+
+**What happens:**
+- Flow is registered in the platform
+- State machine initialized for this flow ID
+
+**Gate to next stage:** flow ID exists.
+
+---
+
+## Stage 2: DISCOVERY
+
+**Trigger:** `get_component`, `list_credentials`, `list_secrets` for each component used in the flow.
+
+**What happens:**
+- Component schemas (actions, triggers, fields, dynamicMetadata flags) are fetched and cached
+- Available credentials and secrets are listed
+- Components requiring auth are flagged
+- Components with `dynamicMetadata: true` are recorded — these will need metadata retrieval later
+
+**Gate to next stage:** every `component_id` that will appear in the skeleton must have a corresponding `get_component` call. Every `credentials_id` / `secret_id` must come from `list_credentials` / `list_secrets`.
+
+---
+
+## Stage 3: SKELETON
+
+**Trigger:** `update_flow_draft` with nodes + edges but **no mappers** on edges.
+
+**What happens:**
+- Draft is saved with the flow structure: which steps exist, how they connect
+- No data mapping yet — edges have no `config.mapper`
+- The system analyzes which steps have `dynamicMetadata: true` and builds a list of pending metadata calls
+
+**Gate to next stage:** skeleton must be saved successfully. If any component wasn't discovered in Stage 2, the call is rejected.
+
+---
+
+## Stage 4: METADATA
+
+**Trigger:** `init_dynamic_metadata` for each step that has `dynamicMetadata: true`.
+
+**What happens:**
+- For each step with dynamic metadata, the actual input/output schema is retrieved from the component using live credentials
+- This gives real field names (not guessed ones) for building mappers
+- Each successful call marks that component:action combo as "metadata retrieved"
+
+**Gate to next stage:** all pending metadata combos (identified in Stage 3) must be retrieved. If a step doesn't have `dynamicMetadata: true`, it's skipped automatically.
+
+**Skip condition:** if no steps in the skeleton have `dynamicMetadata: true`, this stage is auto-completed.
+
+---
+
+## Stage 5: MAPPERS
+
+**Trigger:** `update_flow_draft` again, this time with `config.mapper` on edges.
+
+**What happens:**
+- Mappers are built using real field names from Stage 4
+- Mapper values reference upstream steps via `$getPassthrough().step_id.body.fieldName`
+- Mapper keys are the target step's input field names (from metadata)
+
+**Gate to next stage:** draft must be saved with mappers. The system rejects the call if:
+- Skeleton wasn't saved first (Stage 3 skipped)
+- Metadata wasn't retrieved for steps that need it (Stage 4 skipped)
+
+---
+
+## Stage 6: PUBLISH DRAFT
+
+**Trigger:** `update_flow` (PATCH) — publishes the draft, making it the live flow configuration.
+
+**What happens:**
+- Impact analysis is shown (diff between current live flow and the draft)
+- User must confirm with `confirmed: true`
+- Draft becomes the active configuration, draft is deleted
+
+**Gate to next stage:** flow must have completed the MAPPERS stage. Cannot publish from INIT, DISCOVERY, SKELETON, or METADATA phases.
+
+---
+
+## Stage 7: START
+
+**Trigger:** `start_flow`
+
+**What happens:**
+- Pre-start health check runs (credentials valid, required fields set, components accessible)
+- If health check has errors, start is blocked
+- If health check passes, flow begins executing on its cron schedule
+
+---
+
+## Stage 8: RUN NOW
+
+**Trigger:** `run_flow_now`
+
+**What happens:**
+- Forces an immediate execution of the flow (outside of its cron schedule)
+- Useful to verify the flow works end-to-end before waiting for the next scheduled run
+
+**Gate:** flow must be started (Stage 7).
+
+---
+
+## Stage 9: LOGS
+
+**Trigger:** `get_logs` for the flow
+
+**What happens:**
+- Check execution logs to verify the flow ran successfully
+- Identify errors, warnings, or unexpected behavior in the execution
+- If issues found — diagnose and loop back to the appropriate stage to fix
+
+**After this stage:** flow transitions to RUNNING state.
+
+---
+
+## Stage 10: RUNNING
+
+Flow is live and executing on schedule. State machine stays here until the user requests a modification.
+
+**On modification request** → enter the modification cycle below.
+
+---
+
+## Modification Cycle (from RUNNING)
+
+When the user asks to change something in a running flow, the state machine loops back through these stages:
+
+### Step M1: INSPECT
+
+**Trigger:** `get_flow` — fetch the current flow configuration.
+
+**Gate:** must be called before any modification.
+
+### Step M2: STOP
+
+**Trigger:** `stop_flow` — stop the running flow.
+
+**Skip condition:** if flow is already inactive.
+
+### Step M3: DISCOVERY (only for changed components)
+
+Re-run `get_component`, `list_credentials`, `list_secrets` only for:
+- New components being added
+- Components whose credentials are changing
+
+Already-discovered components from the previous cycle are still cached.
+
+### Step M4: IMPACT ANALYSIS
+
+**Trigger:** first call to `update_flow` or `update_flow_draft` (without `confirmed: true`).
+
+**What happens:**
+- The system compares old vs. new graph and shows a domino-effect impact report
+- Lists: added/removed/changed steps, broken passthrough references, stale data samples
+- Identifies which downstream steps are affected
+
+### Step M5: RE-DO AFFECTED STAGES
+
+Based on what changed, repeat only the relevant stages:
+
+| What changed | Stages to repeat |
+|---|---|
+| New step added | DISCOVERY → METADATA (if dynamicMetadata) → SKELETON → MAPPERS |
+| Component replaced in step | DISCOVERY → METADATA → MAPPERS |
+| Credentials changed | DISCOVERY (list_credentials) → verify_credentials |
+| Step fields changed | MAPPERS (if output schema affected) + refresh data samples |
+| Step removed | MAPPERS (fix broken passthrough refs) |
+| Mapper changed | refresh data samples for downstream steps |
+
+### Step M6: PUBLISH DRAFT → START → RUN NOW → LOGS → RUNNING
+
+Same as stages 6–10. The cycle repeats.

package/resources/docs/flow-state-machine-audit.md

@@ -0,0 +1,162 @@
+# Анализ Flow State Machine и план улучшений
+
+Статус: результаты анализа и предложения по реализации.
+
+Сейчас машина состояний не гарантирует соблюдение процесса сборки: часть фаз выставляется по факту вызова инструмента, без подтверждения результата. При этом некоторые корректные последовательности блокируются.
+
+Проверен текущий код и воспроизведены проблемы в 13 локальных сценариях с mock API и валидаторами. TypeScript-сборка проходит. Эти проверки не являются подтверждением успешного выполнения реального flow на платформе.
+
+## 1. Metadata считается готовой слишком рано
+
+`init_dynamic_metadata` сразу отмечает metadata полученной, хотя вернулся только запуск асинхронной операции. Даже последующая ошибка не отменяет эту отметку.
+
+Ключ `componentId:action` смешивает разные настройки: metadata JDBC для таблицы A засчитывается и для таблицы B. Результат также не привязан к версии компонента, credentials и конкретному шагу.
+
+**Изменение:** сохранять подтверждение только после успешного завершения execution и проверки полученной схемы. Связывать результат с шагом, версией компонента, credentials и конфигурацией. Изменение этих параметров должно делать старое подтверждение недействительным.
+
+Код: [handlers/dynamic.ts](../../src/tools/handlers/dynamic.ts), [flow-state-machine.ts](../../src/tools/flow-state-machine.ts).
+
+## 2. Проверка credentials допускает ложный успех
+
+Discovery запрещает только credentials с уже известной ошибкой; отсутствие проверки разрешено. Отдельный health check считает отсутствие execution ID и таймаут успехом. Локально воспроизведено принятие `result.data.verified: false` за `OK`.
+
+**Изменение:** использовать единый механизм проверки со статусами `UNKNOWN / PENDING / VERIFIED / FAILED`. Публикация должна требовать `VERIFIED` для используемой конфигурации, если компонент требует авторизации. Отсутствие результата и таймаут не должны превращаться в успех.
+
+Код: `checkDiscoveryState`, `verifyCredentialForHealthCheck` и `healthCheckFlow` в [validation.ts](../../src/tools/validation.ts); [handlers/auth.ts](../../src/tools/handlers/auth.ts).
+
+## 3. Порядок samples → mappers создаёт зависимость по кругу
+
+Требуются samples всех шагов до добавления мапперов, но action часто получает корректный sample только после подготовки входных данных через mapper. При этом `autoConfirmSamples` запускает каждый шаг с `{}`.
+
+Существующий sample считается подтверждённым только по наличию ID. Новый sample отмечается подтверждённым ещё до успешного сохранения его привязки в draft. Подтверждения, полученные до регистрации skeleton и списка необходимых samples, не приводят к автоматическому пересчёту фазы.
+
+**Изменение:** обрабатывать шаги по связям графа:
+
+1. Получить или проверить выход предыдущего шага.
+2. Подготовить mapper по схемам source и target.
+3. Проверить преобразованный вход следующего шага.
+4. Получить его sample, когда это необходимо.
+5. Сохранить привязку sample в draft и подтвердить результат.
+
+Sample должен соответствовать компоненту, методу, версии и актуальной конфигурации шага. Наличие ID само по себе не подтверждает его пригодность. Выполнение action для получения sample должно быть явной операцией, поскольку оно может изменять данные во внешней системе.
+
+Код: `autoConfirmSamples` и `update_flow_draft` в [handlers/flow.ts](../../src/tools/handlers/flow.ts), [handlers/data-sample.ts](../../src/tools/handlers/data-sample.ts).
+
+## 4. Одна общая фаза плохо описывает готовность flow
+
+`MAPPERS` выставляется при наличии хотя бы одного маппера. Обязательные мапперы остальных рёбер могут отсутствовать. Обратная проблема: flow, которому мапперы вообще не нужны, застревает перед публикацией.
+
+**Изменение:** хранить готовность каждого шага и ребра, включая явное `NOT_REQUIRED`. Готовность к публикации вычислять из всех необходимых условий, а не из наличия одного маппера или истории вызовов инструментов.
+
+Код: `update_flow_draft` в [handlers/flow.ts](../../src/tools/handlers/flow.ts), `validatePublish` в [flow-state-machine.ts](../../src/tools/flow-state-machine.ts).
+
+## 5. Восстановление состояния и переходы дают тупики
+
+Локально подтверждены следующие случаи:
+
+- Опубликованный неактивный flow нельзя перевести в редактирование: draft запрещён в `PUBLISHED`, `stop_flow` также запрещён, а `get_flow` не меняет эту фазу.
+- После переподключения опубликованный неактивный flow определяется как `MAPPERS`, и запуск требует повторной публикации.
+- Отсутствие состояния отключает проверки фаз: валидаторы возвращают пустой список ошибок.
+
+Текущее восстановление по наличию мапперов слишком грубое: оно не различает draft и опубликованную конфигурацию и не восстанавливает доказательства проверок. Изоляция MCP-сессий полезна, но сама по себе не обеспечивает восстановление процесса сборки.
+
+**Изменение:** получать граф и статус из API, а подтверждения проверок восстанавливать из сохранённых данных либо помечать как `UNKNOWN` для повторной проверки. Неизвестное состояние не должно автоматически разрешать переход. Чтение flow должно обновлять факты, а остановка уже неактивного flow не должна быть обязательной для редактирования.
+
+Код: `markInspected`, `validateDraftUpdate`, `validateStart`, `validateStop` в [flow-state-machine.ts](../../src/tools/flow-state-machine.ts).
+
+## 6. Публикация не привязана к проверенной версии draft
+
+`validatePublish` проверяет фазу, затем `update_flow` отправляет переданный `body`. Можно проверить один граф, а публиковать изменённый.
+
+После публикации снова вызывается `autoConfirmSamples`, который способен создать новый draft. Изменения через raw API обходят проверки процесса сборки.
+
+**Изменение:** проверять конкретную ревизию draft, публиковать именно её и читать результат обратно для подтверждения. Подготовку samples завершать до публикации. Все изменения flow через инструменты, включая raw API, должны проходить общий механизм проверок.
+
+Код: `update_flow` в [handlers/flow.ts](../../src/tools/handlers/flow.ts), [handlers/raw.ts](../../src/tools/handlers/raw.ts).
+
+## 7. RUNNING не подтверждает успешное выполнение
+
+`RUNNING` выставляется после принятия `run_now` или чтения логов — даже пустых. Нет подтверждения, что нужное выполнение завершилось успешно и относится к текущей опубликованной версии.
+
+**Изменение:** отдельно хранить факт активности flow и результат конкретного выполнения: `NOT_RUN / PENDING / PASSED / FAILED / NO_DATA`. Чтение логов должно оставаться чтением; успешность устанавливается после анализа результата execution, связанного с опубликованной версией.
+
+Код: `run_flow_now` в [handlers/flow.ts](../../src/tools/handlers/flow.ts), [handlers/log.ts](../../src/tools/handlers/log.ts).
+
+## 8. Инструкции противоречат друг другу
+
+- Playbook требует создавать пустой flow.
+- Prompt предлагает создавать flow сразу с первым шагом.
+- Описание `create_flow` предполагает граф в payload.
+- Обработчики samples ожидают `flowId` и `stepId`, но этих параметров нет в опубликованных схемах соответствующих инструментов.
+
+Агент, следующий разным инструкциям, получает разные последовательности действий.
+
+**Изменение:** определить одну каноническую спецификацию процесса и согласовать с ней prompts, tool descriptions, схемы аргументов и серверные проверки. Инструкции должны учитывать уже принятые пользователем решения и разрешённую степень самостоятельности.
+
+Источники: [system-instructions.md](system-instructions.md), [flow-building-guide.md](flow-building-guide.md), [flow-creation-stages.md](flow-creation-stages.md), [server.ts](../../src/server.ts), [definitions.ts](../../src/tools/definitions.ts).
+
+## Предлагаемая модель
+
+Механизм должен опираться на проверяемые условия готовности конкретного draft.
+
+| Что отслеживаем | Основание |
+|---|---|
+| Сборка | Конфигурация, metadata, credentials, samples и мапперы каждого шага |
+| Публикация | Проверенная ревизия совпадает с публикуемой |
+| Активность | Статус, подтверждённый API |
+| Проверка работы | Результат конкретного execution |
+
+При изменении `fields`, версии компонента или credentials соответствующие проверки становятся устаревшими. Зависимые samples и мапперы должны перепроверяться. Это относится и к замене компонента или credentials при сохранении прежнего `node.id`: сейчас такая замена может пропустить discovery-проверки.
+
+`get_flow` обновляет факты из API. Общая фаза сборки вычисляется по текущим условиям. Валидаторы не должны менять состояние до сохранения: сейчас `validateDraftUpdate` способен перевести flow из `INIT` в `DISCOVERY` ещё до запроса записи.
+
+Для агента нужен `get_flow_build_status`, возвращающий:
+
+- `revision` — проверяемую версию draft;
+- `blockers` — конкретные невыполненные условия по шагам и рёбрам;
+- `nextActions` — разрешённые операции с необходимыми аргументами;
+- `readyToPublish` — итог проверки готовности.
+
+Следующую разрешённую операцию определяет сервер. Получение metadata, polling, проверка результата и запись состояния выполняются одним согласованным процессом. Запуск flow остаётся отдельным действием, соответствующим запросу пользователя.
+
+## Порядок внедрения
+
+1. Устранить ложный успех metadata, credentials и execution; исправить тупики переходов.
+2. Ввести проверки по шагам и ревизиям; согласовать инструкции и схемы tools.
+3. Добавить единый сервис сборки, последовательную запись изменений одного flow и восстановление после прерываний.
+4. Усилить проверку графа. Сейчас локально проходят цикл, дублирующийся node ID и ссылка на несуществующий passthrough. Повторные POST после таймаута также требуют защиты от дублирования.
+
+## Проверенные локальные сценарии
+
+| Сценарий | Наблюдаемое поведение |
+|---|---|
+| Flow отсутствует в хранилище состояния | Проверки фаз draft, publish и start возвращают пустой список ошибок |
+| Редактирование опубликованного неактивного flow | Draft и stop одновременно запрещены |
+| Восстановление опубликованного неактивного flow | Фаза `MAPPERS`, start требует повторной публикации |
+| Flow без необходимости в мапперах | Публикация блокируется в `METADATA` |
+| Metadata execution ещё pending | Metadata уже отмечена полученной |
+| Samples подтверждены до регистрации skeleton | Все samples есть, фаза остаётся `METADATA` |
+| Чтение пустых логов после start | Фаза становится `RUNNING` |
+| Замена компонента и credentials при прежнем node ID | Discovery-проверка не сообщает ошибок |
+| Цикл, повтор node ID и несуществующий passthrough | Проверка графа не сообщает ошибок |
+| Credentials ещё не проверялись | Discovery-проверка допускает их использование |
+| Credential verification возвращает вложенное `verified: false` | Health check сообщает `OK` |
+| Выполнена только валидация draft без записи | Фаза меняется на `DISCOVERY` |
+| Проверка схем инструментов samples | `flowId` и `stepId` не объявлены |
+
+## Критерии приёмки
+
+Главный инвариант: **flow публикуется только тогда, когда выполнены все необходимые проверки именно его текущей ревизии**.
+
+Обязательные сценарии для автоматизированных тестов:
+
+- Полный цикл создания и изменения flow.
+- Flow без мапперов, ветвление через Router, несколько шагов одного компонента с разными настройками.
+- Переподключение или перезапуск на каждом этапе сборки.
+- Pending, ошибка и таймаут metadata, credentials и execution.
+- Смена конфигурации, credentials или версии компонента после успешной проверки.
+- Ошибка сохранения привязки sample после создания sample.
+- Изменение графа между проверкой и публикацией.
+- Два одновременных обновления одного flow.
+- Повтор запроса после неоднозначного результата записи или сетевого таймаута.
+- Отсутствие побочных изменений состояния при валидации и чтении логов.