[Design] Redesign SQL editor AI interaction and result workflow

[openai0229]

Context

The Community SQL editor has used / at the start of an empty line to open an inline AI composer. This intercepts ordinary SQL input and couples AI invocation to duplicated Monaco overlay, view-zone, focus, and global keyboard lifecycle code. Issue #2255 tracks removing that legacy behavior while preserving the right-side AI panel and other explicit AI actions.

This Discussion is not only about choosing a new button or shortcut. It should define the complete editor AI experience: interaction, runtime logic, performance, compatibility, result presentation, result acceptance, failure recovery, and verification. No replacement should be implemented until these contracts are clear.

User workflow to support

A user writing or reviewing SQL should be able to ask AI about the current selection, statement, or database context without losing typed text, changing focus unexpectedly, hiding the editor, or applying unreviewed output. The flow should be discoverable for a first-time user and efficient for repeated use.

A complete workflow is:

1. Choose the SQL or context to work with.
2. Invoke AI deliberately.
3. Understand exactly what context will be sent.
4. Enter or select an intent.
5. Follow request, tool, streaming, cancellation, and error states.
6. Inspect the result in a stable presentation.
7. Accept all, accept part, insert elsewhere, retry, or reject.
8. Undo accepted changes and recover safely if the editor changed during generation.

1. Interaction model

Questions to resolve:

• Where is the primary entry: editor toolbar, command palette, context action, selection action, right rail, or a combination?
• Is there an optional configurable shortcut, and how is it discovered without reserving a printable SQL character?
• Does invocation operate on the selection, current statement, cursor position, full editor, or an explicit scope chosen by the user?
• How are database, schema, table, dialect, and read-only context shown before sending?
• What are the exact keyboard and focus rules for open, submit, cancel, Escape, Tab, editor switching, and modal interaction?
• How does the flow work with mouse, keyboard-only use, screen readers, and IME composition?
• Should repeated use stay in the editor, hand off to the existing right rail, or remember the last chosen surface?

Required interaction constraints:

• / and every other normal SQL character remain normal editor input.
• Invocation is explicit and never depends on keyboard-layout-specific punctuation.
• The editor remains visible and usable while AI is open.
• Every state has a visible close or cancel action and deterministic focus restoration.
• Existing right-side AI, SQL optimizer, AI table creation, and other explicit AI actions continue to work.

2. Runtime and state logic

The design should define one state machine shared by all entry points, for example: idle, composing, preparing context, requesting, streaming, awaiting review, applying, completed, cancelled, and failed.

Questions to resolve:

• When is editor and database context snapshotted, and can the user inspect or edit that context before sending?
• Is one request allowed per editor, per workspace, or globally? What happens when another tab starts a request?
• Do requests continue in the background when the user changes tabs, and where can they be found again?
• How do cancel, timeout, retry, provider fallback, model reconfiguration, and network recovery change state?
• How are stale responses rejected when the editor, selection, datasource, schema, or active tab changes?
• How are tool calls represented, permissioned, cancelled, and associated with the originating editor?
• What state is ephemeral, what may persist across tabs, and what must never be stored?
• Which existing AI store, chat service, model configuration, and right-rail contracts can be reused instead of creating a parallel editor-specific stack?

The implementation should have one editor integration path, editor-owned cleanup, request ownership identifiers, and no global document keyboard handler.

3. Performance expectations

The AI feature must not slow normal SQL editing when it is unused. The design should include measurable budgets and profiling steps for:

• Initial editor load and AI code splitting.
• Typing latency and Monaco render work while AI is idle, composing, and streaming.
• Store subscriptions and React re-renders caused by streaming chunks.
• Context extraction for large SQL files and large schemas.
• Request startup latency, first visible feedback, first token, and completion.
• Streaming update batching so frequent chunks do not block the main thread.
• Memory retained by results, tool traces, editor models, listeners, overlays, and abandoned requests.
• Cancellation latency and cleanup after tab close or editor unmount.
• Large-result truncation, pagination, artifact storage, or deferred rendering.

At minimum, no AI bundle or network request should be required for ordinary SQL typing, and closing the flow must release listeners, views, timers, subscriptions, and active requests.

4. Compatibility matrix

The selected design should be reviewed against:

• Community Web and Desktop/JCEF behavior.
• macOS, Windows, and Linux keyboard conventions.
• US and non-US layouts, full-width punctuation, and IME composition.
• Chrome-family browser behavior and JCEF-supported browser APIs.
• Light/dark themes, zoom, narrow windows, split panes, and accessibility scaling.
• Read-only editors, routine editors, saved SQL files, multiple consoles, and inactive tabs.
• SQL dialects where slash has valid meaning, including operators, comments, commands, paths, and procedural syntax.
• Model providers with different streaming formats, tool support, context limits, cancellation behavior, and error payloads.
• Online, slow, intermittent, offline, and model-not-configured states.
• Large SQL, large schemas, multilingual prompts, and Unicode results.

Compatibility should be expressed as an explicit test matrix rather than inferred from one browser and one database.

5. Result presentation

Result presentation should distinguish explanation, generated SQL, proposed edits, tool activity, warnings, and errors instead of rendering every response as one text block.

Questions to resolve:

• Should results appear in the right rail, an editor-owned panel, an anchored popover, a full inline diff, or different surfaces by result type?
• How are streaming and completed states visually separated?
• How are the original request, context scope, model, database dialect, and generated result kept inspectable?
• How are multiple SQL alternatives, explanations, warnings, and tool outputs organized?
• How are long results, large tool outputs, tables, code blocks, and partial failures handled without covering the editor?
• Should a result survive tab switches, and how does the user return to the originating editor and selection?
• What progress should be visible before the first token and during slow tool calls?

The presentation must remain stable while streaming and must not continuously resize or shift the SQL editor.

6. Accepting and applying results

Generated output must never execute or overwrite SQL automatically. The design should define explicit operations such as:

• Insert at cursor.
• Replace the captured selection.
• Replace the current statement.
• Open in a new SQL console or saved draft.
• Apply selected hunks from a diff.
• Copy without changing the editor.
• Reject, regenerate, or refine with follow-up instructions.

Questions to resolve:

• Is a diff preview required before replacement?
• Can the user accept only one statement or one hunk?
• How are syntax and database-dialect validation shown before apply?
• What happens if the editor changed after the request context was captured?
• How are conflicts detected: model version, content hash, selection range, or another contract?
• Is every apply operation a single Monaco undo step?
• Can accepted output be reverted after tab switching or saving?
• How do read-only connections and restricted operations affect available actions?
• Should execution always remain a separate explicit user action after apply?

A safe default is review before mutation, one-step undo, stale-context detection, and no automatic execution.

7. Errors, cancellation, and recovery

The experience should define visible behavior for missing model configuration, authentication failure, rate limits, timeout, provider errors, malformed streaming chunks, tool failure, tab closure, datasource change, and user cancellation. Error states should preserve the prompt and source SQL when safe, explain whether any result was applied, and offer only valid recovery actions.

Candidate directions

1. An explicit AI action in the SQL editor toolbar that opens the existing right rail with captured editor context.
2. A command-palette action with an optional configurable shortcut and no printable-character binding.
3. A selection-scoped action that opens a review surface and returns a structured diff.
4. A redesigned inline experience only if it uses one editor-owned lifecycle, never intercepts typing, stays layout-stable, and provides explicit review/apply/reject controls.

These directions can be combined. We should compare them using the same workflow and test matrix rather than selecting from screenshots alone.

Proposed design process

1. Agree on the primary workflows and non-goals.
2. Prototype two or three entry and result-surface combinations.
3. Test keyboard/focus behavior and result acceptance with realistic SQL tasks.
4. Profile idle, streaming, large-context, cancellation, and tab-switch behavior.
5. Run the compatibility matrix across Web/Desktop, operating systems, layouts, and representative databases/providers.
6. Record the chosen state machine, context contract, result model, apply semantics, and measurable acceptance criteria in a follow-up implementation Issue.

Decision criteria

The accepted design should prioritize safe SQL typing, discoverability, predictable focus, explicit context, responsive performance, compatibility, review before mutation, reversible acceptance, implementation reuse, and consistent behavior across editions.

Related removal and redesign Issue: #2255