[ES|QL] Code completion driven by AI (#256857)

## Summary

LLM support from the editor

Ghost placeholder when moving to a new empty line

<img width="531" height="104" alt="image"
src="https://github.com/user-attachments/assets/eb854d84-d6c5-4585-b473-b0c03a32f8a0"
/>


Placeholder when there is no query

<img width="1071" height="219" alt="image"
src="https://github.com/user-attachments/assets/f3ec9c7b-250f-442f-b287-67c1c7452f6a"
/>

Ghost hint when there is a comment

<img width="756" height="237" alt="image"
src="https://github.com/user-attachments/assets/632fe85c-6d03-48b0-a9da-dce6efe7bf14"
/>

Ghost hint while generating

<img width="579" height="313" alt="image"
src="https://github.com/user-attachments/assets/2beafc56-99de-4e6c-b8f7-034434ee38da"
/>


Undo / Keep functionality (only addition, no replacement)

<img width="781" height="224" alt="image"
src="https://github.com/user-attachments/assets/d742b876-fc0e-4ba9-ad19-c11ae9c72c18"
/>

Undo / Replace functionality (with replacement)

<img width="1386" height="204" alt="image"
src="https://github.com/user-attachments/assets/1149c428-7751-4f0f-bcd1-1c7be86dcc58"
/>


### Checklist

- [ ] Any text added follows [EUI's writing
guidelines](https://elastic.github.io/eui/#/guidelines/writing), uses
sentence case text and includes [i18n
support](https://github.com/elastic/kibana/blob/main/src/platform/packages/shared/kbn-i18n/README.md)
- [ ]
[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)
was added for features that require explanation or tutorials
- [ ] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

Author: stratoula

src/platform/packages/private/kbn-esql-editor/src/comment_to_esql/README.md

@@ -0,0 +1,114 @@
+# Comment-to-ES|QL
+
+Generates ES|QL code from natural-language comments in the editor using an LLM.
+
+## How it works
+
+1. The user writes a `//` comment on its own line describing what they want
+2. Presses **⌘+J** (Mac) / **Ctrl+J** (Windows/Linux)
+3. The comment is sent to the `/internal/esql/nl_to_esql` route
+4. Generated code appears below the comment highlighted in green or orange
+5. The user keeps or undoes the change via buttons or keyboard shortcuts
+
+## License gating
+
+The whole feature is gated behind an **active Enterprise license** via `useNlToEsqlCheck`. When the check fails:
+
+- The editor placeholder falls back to the basic `Start typing ES|QL` text instead of advertising **⌘+J**.
+- The ghost-line hints (see below) never appear.
+- Pressing **⌘+J** is a no-op — `generateFromComment` returns early.
+
+## Ghost-line hints
+
+After a short pause (400 ms), an inline italic dimmed hint appears next to the cursor:
+
+| When the cursor is on… | Hint shown |
+| --- | --- |
+| an empty line in a non-empty editor | `Type // and press ⌘+J to ask AI to add a step` |
+| a `//` line | `Press ⌘+J to generate` |
+
+Hints disappear on cursor move or edit, and stay hidden while a review is open or a generation is running. The empty-editor case is excluded — the editor's own placeholder covers it.
+
+## Generating indicator
+
+Between **⌘+J** and the LLM response, an inline `Generating…` text shows at the end of the comment line, italic, dimmed, gently pulsing. It follows the comment line if the user edits content above during the wait, and is cleared on success, abort, error, or retrigger.
+
+## Cancellation and retrigger
+
+Pressing **⌘+J** while a request is in flight or a review is pending discards the previous state — the in-flight request is aborted, decorations are cleared, the review widget is dismissed. The user can iterate freely.
+
+## Completion vs full-query generation
+
+The route picks one of two LLM paths based on whether the editor already has ES|QL code. In both cases the comment stays in place and the generated code is inserted on a new line below it.
+
+### Full-query generation
+
+When the editor contains **only** a comment (no existing ES|QL code), the LLM receives the comment as a free-form instruction and produces a complete ES|QL query from scratch.
+
+Example — editor contains:
+
+```
+// Show the top 10 destinations by flight count
+```
+
+The full generated query is inserted below the comment.
+
+### Completion
+
+When the editor already contains ES|QL code alongside the comment, the system operates in **completion** mode:
+
+- Only the comment line is sent as the instruction; the full query is sent as context
+- The target comment is marked with `>>>` / `<<<` delimiters so the LLM knows which comment to act on (other comments are treated as documentation)
+- The LLM generates only the pipe(s) that should replace the comment, not the full query
+- The generated code is inserted on a new line below the comment
+
+Example — editor contains:
+
+```
+FROM kibana_sample_data_flights
+// Filter for delayed flights
+| STATS avg_delay = AVG(FlightDelayMin) BY Dest
+```
+
+The LLM receives:
+
+```
+FROM kibana_sample_data_flights
+>>> // Filter for delayed flights <<<
+| STATS avg_delay = AVG(FlightDelayMin) BY Dest
+```
+
+And outputs only: `| WHERE FlightDelay == true`
+
+## LLM-signaled replacement
+
+The LLM decides whether its output should **replace** the pipe immediately after the comment or be **inserted** alongside it. It signals this via a `REPLACES_NEXT: true/false` flag in its response.
+
+- `REPLACES_NEXT: true` — the generated code is a modified version of the next pipe (e.g., `// Group by host` modifying an existing `| STATS count = COUNT(*)`). On accept, the original pipe is removed.
+- `REPLACES_NEXT: false` — the generated code is new and should be inserted without touching existing pipes (e.g., `// filter for delayed flights` adding a new `| WHERE`).
+
+This avoids both problems: no silent deletion of unrelated pipes (like WHERE), and no duplicate pipes left behind when the intent is clearly a modification.
+
+## Review flow
+
+A ViewZone + ContentWidget hybrid renders action buttons between editor lines without overlapping content.
+
+### Insert mode (`REPLACES_NEXT: false`)
+
+- **Generated code**: green background
+- **Comment**: no decoration (stays as-is for iteration)
+- Buttons: **Undo** (white, grey outline) / **Keep** (soft green pill)
+
+### Replace mode (`REPLACES_NEXT: true`)
+
+- **Generated code**: green background
+- **Replaced line**: amber/warning background with strikethrough
+- **Comment**: no decoration
+- Buttons: **Undo** (white, grey outline) / **Replace** (soft green pill)
+
+Both buttons fill into a stronger color on hover. They sit ~8 px below the inserted code so they don't crowd the line above.
+
+### Actions
+
+- **Keep / Replace** (⌘⇧↵ / Ctrl+Shift+Enter): keeps the generated code. In replace mode, also removes the original pipe. The comment stays in place so the user can iterate — tweak the instruction and press ⌘+J again.
+- **Undo** (⌘⇧⌫ / Ctrl+Shift+Backspace): removes the generated code and restores the original state.

src/platform/packages/private/kbn-esql-editor/src/comment_to_esql/comment_to_esql.styles.ts

@@ -0,0 +1,57 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { css } from '@emotion/react';
+import { useEuiTheme } from '@elastic/eui';
+import { useMemo } from 'react';
+import { i18n } from '@kbn/i18n';
+
+export const CODE_ADDED_CLASS = 'esqlCodeAdded';
+export const LINE_REPLACED_CLASS = 'esqlLineReplaced';
+export const GENERATING_HINT_CLASS = 'esqlGeneratingHint';
+
+const GENERATING_TEXT = i18n.translate('esqlEditor.commentToEsql.generating', {
+  defaultMessage: 'Generating...',
+});
+
+export const useCommentToEsqlStyle = () => {
+  const { euiTheme } = useEuiTheme();
+
+  return useMemo(
+    () => css`
+      .${CODE_ADDED_CLASS} {
+        background-color: ${euiTheme.colors.backgroundLightSuccess};
+      }
+      .${LINE_REPLACED_CLASS} {
+        background-color: ${euiTheme.colors.backgroundLightWarning};
+        text-decoration: line-through;
+      }
+      @keyframes esqlGeneratingPulse {
+        0%,
+        100% {
+          opacity: 0.4;
+        }
+        50% {
+          opacity: 0.75;
+        }
+      }
+      .${GENERATING_HINT_CLASS}::after {
+        content: ${JSON.stringify(' ' + GENERATING_TEXT)};
+        font-style: italic;
+        color: ${euiTheme.colors.textSubdued};
+        animation: esqlGeneratingPulse 1.4s ease-in-out infinite;
+      }
+    `,
+    [
+      euiTheme.colors.backgroundLightSuccess,
+      euiTheme.colors.backgroundLightWarning,
+      euiTheme.colors.textSubdued,
+    ]
+  );
+};

src/platform/packages/private/kbn-esql-editor/src/comment_to_esql/index.ts

@@ -0,0 +1,11 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+export { useCommentToEsql } from './use_comment_to_esql';
+export { useGhostLineHint } from './use_ghost_line_hint';

src/platform/packages/private/kbn-esql-editor/src/comment_to_esql/review_actions_widget.test.ts

@@ -0,0 +1,62 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { useEuiTheme } from '@elastic/eui';
+import { renderHook } from '@testing-library/react';
+import type { monaco } from '@kbn/code-editor';
+import { ReviewActionsWidget } from './review_actions_widget';
+
+const buildEditor = () =>
+  ({
+    changeViewZones: jest.fn((cb: (accessor: monaco.editor.IViewZoneChangeAccessor) => void) => {
+      cb({
+        addZone: jest.fn(() => 'zone-id'),
+        removeZone: jest.fn(),
+        layoutZone: jest.fn(),
+      });
+    }),
+    addContentWidget: jest.fn(),
+    removeContentWidget: jest.fn(),
+  } as unknown as monaco.editor.ICodeEditor);
+
+describe('ReviewActionsWidget', () => {
+  // Outside an EuiProvider, useEuiTheme returns the Amsterdam defaults — enough
+  // for the widget's constructor to build its DOM without us hand-rolling tokens.
+  const { result } = renderHook(() => useEuiTheme());
+  const euiTheme = result.current.euiTheme;
+
+  it('invokes the matching callback when each button is clicked', () => {
+    const onAccept = jest.fn();
+    const onReject = jest.fn();
+
+    const widget = new ReviewActionsWidget(euiTheme, buildEditor(), 1, { onAccept, onReject });
+    const dom = widget.getDomNode();
+    const [rejectBtn, acceptBtn] = Array.from(dom.querySelectorAll('button'));
+
+    rejectBtn.click();
+    expect(onReject).toHaveBeenCalledTimes(1);
+    expect(onAccept).not.toHaveBeenCalled();
+
+    acceptBtn.click();
+    expect(onAccept).toHaveBeenCalledTimes(1);
+    expect(onReject).toHaveBeenCalledTimes(1);
+  });
+
+  it('labels the accept button "Replace" when isReplaceMode is true and "Keep" otherwise', () => {
+    const callbacks = { onAccept: jest.fn(), onReject: jest.fn() };
+
+    const keepWidget = new ReviewActionsWidget(euiTheme, buildEditor(), 1, callbacks, false);
+    const keepButtons = Array.from(keepWidget.getDomNode().querySelectorAll('button'));
+    expect(keepButtons[1].textContent).toMatch(/^Keep/);
+
+    const replaceWidget = new ReviewActionsWidget(euiTheme, buildEditor(), 1, callbacks, true);
+    const replaceButtons = Array.from(replaceWidget.getDomNode().querySelectorAll('button'));
+    expect(replaceButtons[1].textContent).toMatch(/^Replace/);
+  });
+});