/**
 * Copyright (c) 2026-present, Goldman Sachs
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import type React from 'react';
import { assertErrorThrown, uuid } from '@finos/legend-shared';
import {
  type TDSServiceSchema,
  type LegendAIConfig,
  type LegendAIAssistantMessage,
  type LegendAIUserMessage,
  type LegendAIMessage,
  type LegendAIConversationTurn,
  type LegendAIProductMetadata,
  classifyQuestionIntentFast,
  LegendAIQuestionIntent,
  LegendAIThinkingStepStatus,
  LegendAIMessageRole,
  LegendAIErrorType,
  LegendAIServiceError,
  TDSServiceSourceType,
  buildColumnDefsFromNames,
  LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID,
  getTodayISO,
} from '../LegendAITypes.js';
import {
  type LegendAI_LegendApplicationPlugin_Extension,
  type LegendAIOrchestratorDataProductCoordinates,
  type LegendAISqlExecutionResultData,
  type LegendAIResolvedEntities,
  LegendAIJudgeVerdict,
} from '../LegendAI_LegendApplicationPlugin_Extension.js';
import {
  type QueryExplicitExecutionContextInfo,
  extractElementNameFromPath,
} from '@finos/legend-graph';

const MAX_ERROR_MESSAGE_LENGTH = 500;
const MAX_THINKING_ERROR_PREVIEW_LENGTH = 200;
const DEFAULT_MAX_JUDGE_ATTEMPTS = 5;
const DEFAULT_MAX_EXECUTION_RETRIES = 3;
const ANALYSIS_TIMEOUT_MS = 15_000;
const ANALYSIS_PREVIEW_ROW_LIMIT = 3;
const ANALYSIS_PREVIEW_VALUE_LIMIT = 40;
const MAX_NON_SQL_PASS_ATTEMPTS = 2;
const ALIAS_DOT_COL_PATTERN = /\b(?<tbl>[a-z]\w*)\s*\.\s*"(?<col>[^"]+)"/gi;
const JOIN_PATTERN = /\bJOIN\b/i;
const ORDER_BY_SPLIT = /\bORDER\s+BY\b/i;
const UNION_ALL_PATTERN = /\bUNION\s+ALL\b/i;
const LITERAL_COL_PATTERN = /,\s*'[^']*'\s+AS\s+(?:"[^"]+"|[a-z]\w*)/gi;
const DEFAULT_SAFETY_LIMIT = 1000;
const HAS_LIMIT_PATTERN = /\bLIMIT\s+\d+/i;
const HAS_AGGREGATION_PATTERN =
  /\bGROUP\s+BY\b|\bCOUNT\s*\(|\bSUM\s*\(|\bAVG\s*\(|\bMIN\s*\(|\bMAX\s*\(/i;
const MAX_SERVICES_FOR_LLM_SELECTION = 30;
const ORCHESTRATOR_FALLBACK_LABEL = 'Try Legend AI Orchestrator';
const SQL_GENERATION_FAILURE_WITH_ORCHESTRATOR =
  'SQL generation could not handle this query. You can try the Legend AI Orchestrator to generate a Pure query instead.';
const SQL_GENERATION_FAILURE_NO_ORCHESTRATOR =
  'SQL generation could not handle this query. Try rephrasing your question.';
const SERVICE_PARAM_DATE_LIKE_PATTERNS: readonly RegExp[] = [
  /date|time|day|month|year|period|asOf|businessDate|processingDate|snapshot/i,
  /effective|valid|settle|trade|maturity|expir|inception|close|open/i,
  /start|end|from|until|begin|report|cutoff|valuation|pricing/i,
];

function isLikelySqlQuery(text: string): boolean {
  const trimmed = text.trim().toLowerCase();
  return (
    trimmed.startsWith('select') ||
    trimmed.startsWith('with') ||
    trimmed.startsWith('(')
  );
}

const SUGGESTED_QUERIES_DELIMITER = '---SUGGESTED_QUERIES---';

export function elapsedSeconds(startTime: number, decimals: 1 | 2 = 1): string {
  return ((Date.now() - startTime) / 1000).toFixed(decimals);
}

function withTimeout<T>(
  promise: Promise<T>,
  ms: number,
): Promise<T | undefined> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  return Promise.race([
    promise.finally(() => {
      if (timer !== undefined) {
        clearTimeout(timer);
      }
    }),
    new Promise<undefined>((resolve) => {
      timer = setTimeout(() => resolve(undefined), ms);
    }),
  ]);
}

function deduplicateColumns(columns: string[]): string[] {
  const seen = new Map<string, number>();
  return columns.map((col) => {
    const count = seen.get(col) ?? 0;
    seen.set(col, count + 1);
    return count === 0 ? col : `${col}_${count + 1}`;
  });
}

export type MessageSetter = React.Dispatch<
  React.SetStateAction<LegendAIMessage[]>
>;

export function createMessagePair(
  text: string,
): [LegendAIUserMessage, LegendAIAssistantMessage] {
  return [
    { id: uuid(), role: LegendAIMessageRole.USER, text },
    {
      id: uuid(),
      role: LegendAIMessageRole.ASSISTANT,
      thinkingSteps: [],
      sql: null,
      textAnswer: null,
      dataContext: null,
      gridData: null,
      error: null,
      errorType: null,
      sqlGenTime: null,
      execTime: null,
      thinkingDuration: null,
      isProcessing: true,
      isExecuting: false,
      suggestedQueries: [],
      fallbackAction: null,
    },
  ];
}

export interface LegendAIOperationContext {
  config: LegendAIConfig;
  plugin: LegendAI_LegendApplicationPlugin_Extension;
  history: LegendAIConversationTurn[];
  setMessages: MessageSetter;
}

interface LegendAIOrchestratorOptionsParam {
  dataProductCoordinates: LegendAIOrchestratorDataProductCoordinates;
  pureExecutionContext?: QueryExplicitExecutionContextInfo;
}

export function updateLastAssistant(
  setMessages: MessageSetter,
  updater: (msg: LegendAIAssistantMessage) => Partial<LegendAIAssistantMessage>,
): void {
  setMessages((prev) => {
    const newMsgs = [...prev];
    const lastIdx = newMsgs.length - 1;
    const last = newMsgs[lastIdx];
    if (last?.role === LegendAIMessageRole.ASSISTANT) {
      newMsgs[lastIdx] = { ...last, ...updater(last) };
    }
    return newMsgs;
  });
}

export function addThinkingStep(
  setMessages: MessageSetter,
  label: string,
): void {
  updateLastAssistant(setMessages, (msg) => ({
    thinkingSteps: [
      ...msg.thinkingSteps.map((s) =>
        s.status === LegendAIThinkingStepStatus.ACTIVE
          ? { ...s, status: LegendAIThinkingStepStatus.DONE }
          : s,
      ),
      { id: uuid(), label, status: LegendAIThinkingStepStatus.ACTIVE },
    ],
  }));
}

export function completeThinkingSteps(setMessages: MessageSetter): void {
  updateLastAssistant(setMessages, (msg) => ({
    thinkingSteps: msg.thinkingSteps.map((s) =>
      s.status === LegendAIThinkingStepStatus.ACTIVE
        ? { ...s, status: LegendAIThinkingStepStatus.DONE }
        : s,
    ),
  }));
}

export function classifyError(error: Error): LegendAIErrorType {
  if (error instanceof LegendAIServiceError) {
    return error.errorType;
  }
  return LegendAIErrorType.GENERAL;
}

export function finishWithThinkingError(
  setMessages: MessageSetter,
  errorMsg: string,
  startTime: number,
  errorType?: LegendAIErrorType,
): void {
  updateLastAssistant(setMessages, (msg) => ({
    thinkingSteps: msg.thinkingSteps.map((s) =>
      s.status === LegendAIThinkingStepStatus.ACTIVE
        ? { ...s, status: LegendAIThinkingStepStatus.ERROR }
        : s,
    ),
    error: errorMsg.slice(0, MAX_ERROR_MESSAGE_LENGTH),
    errorType: errorType ?? null,
    isProcessing: false,
    thinkingDuration: elapsedSeconds(startTime),
  }));
}

function buildTurnFromAssistant(
  userText: string,
  asstMsg: LegendAIAssistantMessage,
): LegendAIConversationTurn | undefined {
  if (asstMsg.sql) {
    const turn: LegendAIConversationTurn = {
      question: userText,
      sql: asstMsg.sql,
      intent: LegendAIQuestionIntent.DATA_QUERY,
    };
    if (asstMsg.gridData) {
      turn.rowCount = asstMsg.gridData.rowData.length;
      const colNames = asstMsg.gridData.columnDefs
        .map((c) => c.headerName ?? c.colId ?? '')
        .filter((n) => n.length > 0);
      if (colNames.length > 0) {
        turn.resultSummary = `Columns: ${colNames.join(', ')}; ${turn.rowCount} row(s) returned`;
      }
    }
    return turn;
  }
  if (asstMsg.textAnswer) {
    return {
      question: userText,
      sql: asstMsg.textAnswer,
      intent: LegendAIQuestionIntent.METADATA,
    };
  }
  return undefined;
}

export function buildConversationHistory(
  messages: LegendAIMessage[],
): LegendAIConversationTurn[] {
  const history: LegendAIConversationTurn[] = [];
  let i = 0;
  while (i < messages.length - 1) {
    const userMsg = messages[i];
    const asstMsg = messages[i + 1];
    if (
      userMsg?.role === LegendAIMessageRole.USER &&
      asstMsg?.role === LegendAIMessageRole.ASSISTANT
    ) {
      const turn = buildTurnFromAssistant(userMsg.text, asstMsg);
      if (turn) {
        history.push(turn);
      }
      i += 2;
    } else {
      i += 1;
    }
  }
  return history;
}

function formatServiceParams(services: TDSServiceSchema[]): string[] {
  return services.flatMap((s) => {
    if (s.parameterSchemas && s.parameterSchemas.length > 0) {
      return [
        `${s.title}: ${s.parameterSchemas
          .map((ps) => {
            const parts = [ps.name];
            if (ps.type) {
              parts.push(`(${ps.type})`);
            }
            return parts.join(' ');
          })
          .join(', ')}`,
      ];
    }
    return s.parameters.length > 0
      ? [`${s.title}: ${s.parameters.join(', ')}`]
      : [];
  });
}

export function buildGenerationFailureMessage(
  failure: string,
  suggestion: string | undefined,
  services: TDSServiceSchema[],
): string {
  const parts = [failure];
  if (suggestion) {
    parts.push(`\nTry instead: "${suggestion}"`);
  }
  const svcNames = services.map((s) => s.title);
  if (svcNames.length > 0) {
    parts.push(`\nAvailable services: ${svcNames.join(', ')}`);
  }
  const allParams = formatServiceParams(services);
  if (allParams.length > 0) {
    parts.push(`\nService parameters: ${allParams.join('; ')}`);
  }
  return parts.join('');
}

function buildFallbackSuggestions(services: TDSServiceSchema[]): string[] {
  return services.slice(0, 3).map((svc) => `Show 10 records from ${svc.title}`);
}

function appendFallbackSuggestions(
  setMessages: MessageSetter,
  services: TDSServiceSchema[],
): void {
  const suggestions = buildFallbackSuggestions(services);
  if (suggestions.length > 0) {
    updateLastAssistant(setMessages, () => ({
      suggestedQueries: suggestions,
    }));
  }
}

export function buildExecutionErrorMessage(
  errStr: string,
  services: TDSServiceSchema[],
): string {
  const errParts: string[] = [];
  const errLower = errStr.toLowerCase();

  const missingParamMatch =
    /missing required parameter values?\s*\[(?<params>[^\]]+)\]/i.exec(errStr);
  if (missingParamMatch) {
    const paramNames = missingParamMatch.groups?.params ?? '';
    const paramList = paramNames.split(',').map((p) => p.trim());
    const hint = paramList
      .map(
        (p) =>
          `a specific ${p.replaceAll(/(?<lower>[a-z])(?<upper>[A-Z])/g, '$<lower> $<upper>').toLowerCase()}`,
      )
      .join(' and ');
    errParts.push(
      `This service requires a value for: ${paramNames}`,
      `\nTry rephrasing your question to include ${hint}.`,
    );
    const svcParams = formatServiceParams(services);
    if (svcParams.length > 0) {
      errParts.push(`\nService parameters:\n${svcParams.join('\n')}`);
    }
    return errParts.join('');
  }

  errParts.push(errStr.slice(0, MAX_ERROR_MESSAGE_LENGTH));
  if (
    errLower.includes('column') &&
    (errLower.includes('not found') ||
      errLower.includes('does not exist') ||
      errLower.includes('unknown'))
  ) {
    const svcCols = services.map(
      (s) => `${s.title}: ${s.columns.map((c) => c.name).join(', ')}`,
    );
    errParts.push(`\nAvailable columns:\n${svcCols.join('\n')}`);
  }
  if (errLower.includes('parameter') || errLower.includes('argument')) {
    const svcParams = formatServiceParams(services);
    if (svcParams.length > 0) {
      errParts.push(`\nRequired parameters:\n${svcParams.join('\n')}`);
    }
  }
  return errParts.join('');
}

function parseSuggestedQueries(rawAnswer: string): {
  answer: string;
  suggestedQueries: string[];
} {
  const delimIndex = rawAnswer.indexOf(SUGGESTED_QUERIES_DELIMITER);
  if (delimIndex === -1) {
    return { answer: rawAnswer.trim(), suggestedQueries: [] };
  }
  const answer = rawAnswer.slice(0, delimIndex).trim();
  const suggestionsBlock = rawAnswer.slice(
    delimIndex + SUGGESTED_QUERIES_DELIMITER.length,
  );
  const suggestedQueries = suggestionsBlock
    .split('\n')
    .map((line) => line.replace(/^\d+[.)]\s*/, '').trim())
    .filter((line) => line.length > 0)
    .slice(0, 3);
  return { answer, suggestedQueries };
}

function tokenizeQuestionForCoverage(question: string): string[] {
  return question
    .toLowerCase()
    .split(/[^a-z0-9]+/)
    .filter((token) => token.length >= 4);
}

function buildQuestionCoverageNote(
  question: string,
  columns: string[],
): string {
  const questionTokens = tokenizeQuestionForCoverage(question);
  if (questionTokens.length === 0 || columns.length === 0) {
    return '';
  }

  const normalizedColumns = columns.map((c) => c.toLowerCase());
  const matchedTokenCount = questionTokens.filter((token) =>
    normalizedColumns.some((column) => column.includes(token)),
  ).length;

  if (matchedTokenCount > 0) {
    return '';
  }

  return 'The retrieved columns do not clearly map to the key terms in your question. Consider refining the question with specific fields, entities, or filters.';
}

function formatPreviewValue(value: unknown): string {
  if (value === null || value === undefined) {
    return 'null';
  }
  const raw = typeof value === 'string' ? value : JSON.stringify(value);
  if (raw.length <= ANALYSIS_PREVIEW_VALUE_LIMIT) {
    return raw;
  }
  return `${raw.slice(0, ANALYSIS_PREVIEW_VALUE_LIMIT)}...`;
}

function buildDeterministicResultSummary(
  question: string,
  _query: string,
  columns: string[],
  rows: unknown[],
): string {
  const selectedColumns = columns.length === 0 ? 'none' : columns.join(', ');
  const rowCount = rows.length;
  const previewRows = rows
    .slice(0, ANALYSIS_PREVIEW_ROW_LIMIT)
    .map((row, index) => {
      if (row && typeof row === 'object' && !Array.isArray(row)) {
        const entries = Object.entries(row as Record<string, unknown>).slice(
          0,
          4,
        );
        const formattedEntries = entries.map(
          ([key, value]) => `${key}: ${formatPreviewValue(value)}`,
        );
        return `${index + 1}. ${formattedEntries.join(', ')}`;
      }
      return `${index + 1}. ${formatPreviewValue(row)}`;
    })
    .join('\n');

  const coverageNote = buildQuestionCoverageNote(question, columns);
  const parts = [
    `I retrieved ${rowCount} row${rowCount === 1 ? '' : 's'} for your question using this query.`,
    `Columns returned: ${selectedColumns}.`,
    `Sample rows:\n${previewRows || 'No sample rows available.'}`,
  ];
  if (coverageNote) {
    parts.push(coverageNote);
  }
  return parts.join('\n\n');
}

export async function buildMetadataOverview(
  question: string,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
): Promise<string> {
  const { plugin, config, history } = context;
  const metadataPromptText = plugin.buildMetadataPrompt(
    question,
    metadata,
    history,
  );
  const rawAnswer = await plugin.callLLM(metadataPromptText, config);
  return parseSuggestedQueries(rawAnswer).answer;
}

function mergeMetadataAndQueryAnalysis(
  metadataOverview: string,
  queryAnalysis: string | null,
): string {
  const metadata = metadataOverview.trim();
  const analysis = queryAnalysis?.trim();
  if (!analysis) {
    return `### Metadata context\n${metadata}`;
  }
  return `### Metadata context\n${metadata}\n\n### Query analysis\n${analysis}`;
}

export function attachMetadataOverview(
  setMessages: MessageSetter,
  metadataOverview: string,
): void {
  const normalized = metadataOverview.trim();
  if (!normalized) {
    return;
  }
  updateLastAssistant(setMessages, (msg) => {
    const existing = msg.textAnswer?.trim() ?? null;
    if (existing?.includes('### Metadata context')) {
      return {};
    }
    return {
      textAnswer: mergeMetadataAndQueryAnalysis(normalized, existing),
    };
  });
}

export async function handleMetadataQuestion(
  question: string,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  startTime: number,
  hasQueryableServices?: boolean,
): Promise<void> {
  const { config, plugin, history, setMessages } = context;
  addThinkingStep(setMessages, 'Answering from product metadata...');
  const metadataPromptText = plugin.buildMetadataPrompt(
    question,
    metadata,
    history,
  );
  const rawAnswer = await plugin.callLLM(metadataPromptText, config);
  const { answer, suggestedQueries: parsedSuggestions } =
    parseSuggestedQueries(rawAnswer);
  const suggestedQueries =
    hasQueryableServices === false && !config.orchestratorUrl
      ? []
      : parsedSuggestions;
  completeThinkingSteps(setMessages);
  updateLastAssistant(setMessages, () => ({
    textAnswer: answer,
    suggestedQueries,
    isProcessing: false,
    thinkingDuration: elapsedSeconds(startTime),
  }));
}

function handleNonSqlPass(
  setMessages: MessageSetter,
  nonSqlPassAttempts: number,
  attempt: number,
  maxAttempts: number,
): 'continue' | 'abort' {
  addThinkingStep(
    setMessages,
    'Judge approved a non-SQL draft, requesting query correction...',
  );
  if (
    attempt === maxAttempts ||
    nonSqlPassAttempts >= MAX_NON_SQL_PASS_ATTEMPTS
  ) {
    addThinkingStep(
      setMessages,
      'Max verification attempts reached without a valid SQL query',
    );
    return 'abort';
  }
  return 'continue';
}

function finalizeJudgeAttempt(
  currentSql: string,
  previousSql: string,
  attempt: number,
  maxAttempts: number,
  setMessages: MessageSetter,
): string | null | undefined {
  if (currentSql !== previousSql && attempt < maxAttempts) {
    return undefined;
  }
  addThinkingStep(
    setMessages,
    isLikelySqlQuery(currentSql)
      ? 'Max verification attempts reached, using best query'
      : 'Max verification attempts reached without a valid SQL query',
  );
  return isLikelySqlQuery(currentSql) ? currentSql : null;
}

async function runJudgeLoop(
  generatedSql: string,
  buildJudgePromptFn: (sql: string) => string,
  context: LegendAIOperationContext,
): Promise<string | null> {
  const { config, plugin, setMessages } = context;
  const maxAttempts = config.maxJudgeAttempts ?? DEFAULT_MAX_JUDGE_ATTEMPTS;
  let currentSql = generatedSql;
  let nonSqlPassAttempts = 0;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    addThinkingStep(
      setMessages,
      `Verifying query correctness (${attempt}/${maxAttempts})...`,
    );
    const judgePrompt = buildJudgePromptFn(currentSql);
    const judgeAnswer = await plugin.callLLM(judgePrompt, config);
    const judgeResult = plugin.extractJudgeResult(judgeAnswer);

    if (judgeResult.verdict === LegendAIJudgeVerdict.PASS) {
      if (!isLikelySqlQuery(currentSql)) {
        nonSqlPassAttempts++;
        const action = handleNonSqlPass(
          setMessages,
          nonSqlPassAttempts,
          attempt,
          maxAttempts,
        );
        if (action === 'abort') {
          return null;
        }
        continue;
      }
      completeThinkingSteps(setMessages);
      return currentSql;
    }

    const previousSql = currentSql;
    const correctedSql = judgeResult.correctedSql?.trim();
    if (correctedSql !== undefined && isLikelySqlQuery(correctedSql)) {
      addThinkingStep(setMessages, `Query corrected (attempt ${attempt})`);
      currentSql = correctedSql;
    }

    const result = finalizeJudgeAttempt(
      currentSql,
      previousSql,
      attempt,
      maxAttempts,
      setMessages,
    );
    if (result !== undefined) {
      return result;
    }
  }

  return null;
}

export async function generateAndJudgeSql(
  question: string,
  services: TDSServiceSchema[],
  coordinates: string,
  context: LegendAIOperationContext,
  startTime: number,
  metadata?: LegendAIProductMetadata,
): Promise<string | null> {
  const { plugin, config, history, setMessages } = context;
  addThinkingStep(setMessages, 'Building context from service schemas...');
  const prompt = plugin.buildGeneratorPrompt(
    question,
    services,
    coordinates,
    history,
    metadata,
  );
  addThinkingStep(setMessages, 'Generating SQL query...');

  const answerText = await plugin.callLLM(prompt, config);
  const {
    sql: generatedSql,
    failure,
    suggestion,
  } = plugin.extractSqlFromResponse(answerText);

  if (failure) {
    addThinkingStep(setMessages, `Generation failed: ${failure}`);
    finishWithThinkingError(
      setMessages,
      buildGenerationFailureMessage(failure, suggestion, services),
      startTime,
      LegendAIErrorType.GENERATION,
    );
    return null;
  }

  if (!generatedSql) {
    addThinkingStep(setMessages, 'Could not extract SQL from response');
    finishWithThinkingError(
      setMessages,
      'Could not extract SQL from LLM response.\nTry rephrasing your question or ask about a specific service.',
      startTime,
      LegendAIErrorType.GENERATION,
    );
    return null;
  }

  return runJudgeLoop(
    generatedSql,
    (sql) =>
      plugin.buildJudgePrompt(sql, question, services, coordinates, history),
    context,
  );
}

/**
 * Dedicated generate-and-judge loop for access point queries.
 * Uses AP-specific prompts that focus on `p()` syntax and omit
 * coordinates, parameters, and service()-related rules.
 */
export async function generateAndJudgeAccessPointSql(
  question: string,
  accessPoints: TDSServiceSchema[],
  context: LegendAIOperationContext,
  startTime: number,
): Promise<string | null> {
  const { plugin, config, history, setMessages } = context;
  addThinkingStep(setMessages, 'Building context from access point schemas...');
  const prompt = plugin.buildAccessPointGeneratorPrompt(
    question,
    accessPoints,
    history,
  );
  addThinkingStep(setMessages, 'Generating SQL query for access points...');

  const answerText = await plugin.callLLM(prompt, config);
  const {
    sql: generatedSql,
    failure,
    suggestion,
  } = plugin.extractSqlFromResponse(answerText);

  if (failure) {
    addThinkingStep(setMessages, `Generation failed: ${failure}`);
    finishWithThinkingError(
      setMessages,
      buildGenerationFailureMessage(failure, suggestion, accessPoints),
      startTime,
      LegendAIErrorType.GENERATION,
    );
    return null;
  }

  if (!generatedSql) {
    addThinkingStep(setMessages, 'Could not extract SQL from response');
    finishWithThinkingError(
      setMessages,
      'Could not extract SQL from LLM response.\nTry rephrasing your question or ask about a specific access point.',
      startTime,
      LegendAIErrorType.GENERATION,
    );
    return null;
  }

  return runJudgeLoop(
    generatedSql,
    (sql) =>
      plugin.buildAccessPointJudgePrompt(sql, question, accessPoints, history),
    context,
  );
}

function reportExecutionResult(
  rawResult: LegendAISqlExecutionResultData,
  setMessages: MessageSetter,
  execStartTime: number,
  startTime: number,
): LegendAISqlExecutionResultData {
  const columns = deduplicateColumns(rawResult.columns);
  const rows = rawResult.rows;
  completeThinkingSteps(setMessages);
  addThinkingStep(
    setMessages,
    `Retrieved ${rows.length} row${rows.length === 1 ? '' : 's'}`,
  );
  completeThinkingSteps(setMessages);

  updateLastAssistant(setMessages, () => ({
    gridData: { columnDefs: buildColumnDefsFromNames(columns), rowData: rows },
    execTime: elapsedSeconds(execStartTime, 2),
    isProcessing: false,
    isExecuting: false,
    thinkingDuration: elapsedSeconds(startTime),
  }));
  return { columns, rows };
}

export async function executeSqlAndReport(
  sql: string,
  services: TDSServiceSchema[],
  config: LegendAIConfig,
  plugin: LegendAI_LegendApplicationPlugin_Extension,
  setMessages: MessageSetter,
  startTime: number,
  dataProductCoordinates?: LegendAIOrchestratorDataProductCoordinates,
): Promise<LegendAISqlExecutionResultData | undefined> {
  const execStartTime = Date.now();
  try {
    const isAccessPoint = services.some(
      (s) => s.sourceType === TDSServiceSourceType.ACCESS_POINT,
    );
    const rawResult =
      isAccessPoint && dataProductCoordinates
        ? await plugin.executeLakehouseSql(sql, dataProductCoordinates, config)
        : await plugin.executeSql(sql, config);
    return reportExecutionResult(
      rawResult,
      setMessages,
      execStartTime,
      startTime,
    );
  } catch (executeError) {
    assertErrorThrown(executeError);
    const execErrorType = classifyError(executeError);
    addThinkingStep(
      setMessages,
      `Execution failed: ${executeError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );
    finishWithThinkingError(
      setMessages,
      buildExecutionErrorMessage(executeError.message, services),
      startTime,
      execErrorType === LegendAIErrorType.GENERAL
        ? LegendAIErrorType.EXECUTION
        : execErrorType,
    );
    updateLastAssistant(setMessages, () => ({
      execTime: elapsedSeconds(execStartTime, 2),
      isExecuting: false,
    }));
    return undefined;
  }
}

export async function executePureQueryAndReport(
  pureQuery: string,
  pureExecutionContext: QueryExplicitExecutionContextInfo,
  dataProductCoordinates: LegendAIOrchestratorDataProductCoordinates,
  config: LegendAIConfig,
  plugin: LegendAI_LegendApplicationPlugin_Extension,
  setMessages: MessageSetter,
  startTime: number,
): Promise<LegendAISqlExecutionResultData> {
  const execStartTime = Date.now();
  try {
    addThinkingStep(setMessages, 'Executing Pure query...');
    const rawResult = await plugin.executePureQuery(
      pureQuery,
      pureExecutionContext,
      dataProductCoordinates,
      config,
    );
    return reportExecutionResult(
      rawResult,
      setMessages,
      execStartTime,
      startTime,
    );
  } catch (executeError) {
    assertErrorThrown(executeError);
    const execErrorType = classifyError(executeError);
    addThinkingStep(
      setMessages,
      `Execution failed: ${executeError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );
    completeThinkingSteps(setMessages);
    updateLastAssistant(setMessages, () => ({
      execTime: elapsedSeconds(execStartTime, 2),
      isExecuting: false,
      isProcessing: false,
      error: `Execution failed: ${executeError.message.slice(0, MAX_ERROR_MESSAGE_LENGTH)}`,
      errorType:
        execErrorType === LegendAIErrorType.GENERAL
          ? LegendAIErrorType.EXECUTION
          : execErrorType,
      thinkingDuration: elapsedSeconds(startTime),
    }));
    return { columns: [], rows: [] };
  }
}

export async function analyzeOrchestratorResults(
  question: string,
  query: string,
  execResult: LegendAISqlExecutionResultData,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  startTime: number,
): Promise<void> {
  const { config, plugin, setMessages } = context;
  addThinkingStep(setMessages, 'Analyzing results...');
  updateLastAssistant(setMessages, () => ({
    isProcessing: true,
  }));
  const analysis = await withTimeout(
    plugin.analyzeQueryResults(
      question,
      query,
      execResult.columns,
      execResult.rows,
      metadata,
      config,
    ),
    ANALYSIS_TIMEOUT_MS,
  );
  addThinkingStep(setMessages, 'Verifying answer coverage...');
  if (analysis) {
    const coverageNote = buildQuestionCoverageNote(
      question,
      execResult.columns,
    );
    const summary = coverageNote
      ? `${analysis.summary}\n\n${coverageNote}`
      : analysis.summary;
    completeThinkingSteps(setMessages);
    updateLastAssistant(setMessages, () => ({
      textAnswer: summary,
      suggestedQueries: analysis.suggestedQueries,
      isProcessing: false,
      thinkingDuration: elapsedSeconds(startTime),
    }));
  } else {
    const fallbackSummary = buildDeterministicResultSummary(
      question,
      query,
      execResult.columns,
      execResult.rows,
    );
    completeThinkingSteps(setMessages);
    updateLastAssistant(setMessages, () => ({
      textAnswer: fallbackSummary,
      suggestedQueries: [],
      isProcessing: false,
      thinkingDuration: elapsedSeconds(startTime),
    }));
  }
}

async function handleEmptyOrchestratorResults(
  question: string,
  legendQuery: string,
  orchestratorOptions: Required<LegendAIOrchestratorOptionsParam>,
  metadata: LegendAIProductMetadata,
  resolvedEntities: LegendAIResolvedEntities,
  context: LegendAIOperationContext,
  startTime: number,
): Promise<void> {
  const { dataProductCoordinates, pureExecutionContext } = orchestratorOptions;
  const { config, plugin, setMessages } = context;

  if (resolvedEntities.relatedEntities.length > 0) {
    const alternateRoot = resolvedEntities.relatedEntities[0];
    if (alternateRoot) {
      addThinkingStep(
        setMessages,
        `No results with ${extractElementNameFromPath(resolvedEntities.rootEntity)}, retrying with ${extractElementNameFromPath(alternateRoot)}...`,
      );

      try {
        const retryResponse = await plugin.generateQueryViaOrchestrator(
          {
            user_question: question,
            semantic_search_resolution_details: {
              data_product_coordinates: dataProductCoordinates,
              root_entity: alternateRoot,
              related_entities: resolvedEntities.relatedEntities.slice(1),
            },
          },
          config,
        );

        updateLastAssistant(setMessages, () => ({
          sql: retryResponse.legend_query,
          sqlGenTime: elapsedSeconds(startTime, 2),
          isExecuting: true,
        }));

        const retryResult = await executePureQueryAndReport(
          retryResponse.legend_query,
          pureExecutionContext,
          dataProductCoordinates,
          config,
          plugin,
          setMessages,
          startTime,
        );

        if (retryResult.rows.length > 0) {
          await analyzeOrchestratorResults(
            question,
            retryResponse.legend_query,
            retryResult,
            metadata,
            context,
            startTime,
          );
          return;
        }
      } catch (retryError) {
        assertErrorThrown(retryError);
        addThinkingStep(
          setMessages,
          `Retry with alternate entity failed: ${retryError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
        );
      }
    }
  }

  addThinkingStep(
    setMessages,
    'No results returned \u2014 building contextual guidance...',
  );
  updateLastAssistant(setMessages, () => ({
    isProcessing: true,
  }));
  const fallback = await withTimeout(
    plugin.buildNoResultsFallback(question, legendQuery, metadata, config),
    ANALYSIS_TIMEOUT_MS,
  );
  if (fallback) {
    completeThinkingSteps(setMessages);
    updateLastAssistant(setMessages, () => ({
      textAnswer: fallback.summary,
      suggestedQueries: fallback.suggestedQueries,
      isProcessing: false,
      thinkingDuration: elapsedSeconds(startTime),
    }));
  }
}

export async function processQuestionViaOrchestrator(
  question: string,
  dataProductCoordinates: LegendAIOrchestratorDataProductCoordinates,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  pureExecutionContext?: QueryExplicitExecutionContextInfo,
  preResolvedEntities?: LegendAIResolvedEntities,
): Promise<void> {
  const { config, plugin, setMessages } = context;
  const startTime = Date.now();

  try {
    let resolvedEntities: LegendAIResolvedEntities;
    if (preResolvedEntities) {
      resolvedEntities = preResolvedEntities;
      addThinkingStep(
        setMessages,
        `Using pre-resolved root entity: ${extractElementNameFromPath(resolvedEntities.rootEntity)}`,
      );
    } else {
      addThinkingStep(setMessages, 'Resolving entities for your query...');
      resolvedEntities = await plugin.resolveEntitiesForQuery(
        question,
        dataProductCoordinates,
        config,
        pureExecutionContext,
      );
      addThinkingStep(
        setMessages,
        `Found root entity: ${extractElementNameFromPath(resolvedEntities.rootEntity)}`,
      );
    }

    if (resolvedEntities.relatedEntities.length > 0) {
      addThinkingStep(
        setMessages,
        `Found ${resolvedEntities.relatedEntities.length} related entities`,
      );
    }

    addThinkingStep(setMessages, 'Generating Legend query via orchestrator...');
    const orchestratorResponse = await plugin.generateQueryViaOrchestrator(
      {
        user_question: question,
        semantic_search_resolution_details: {
          data_product_coordinates: dataProductCoordinates,
          root_entity: resolvedEntities.rootEntity,
          related_entities: resolvedEntities.relatedEntities,
        },
      },
      config,
    );

    const queryGenTime = elapsedSeconds(startTime, 2);
    completeThinkingSteps(setMessages);
    updateLastAssistant(setMessages, () => ({
      sql: orchestratorResponse.legend_query,
      sqlGenTime: queryGenTime,
      isExecuting: true,
      isProcessing: true,
    }));

    if (!pureExecutionContext) {
      updateLastAssistant(setMessages, () => ({
        isProcessing: false,
        isExecuting: false,
        error:
          'No execution context available — cannot execute query via engine.',
        errorType: LegendAIErrorType.EXECUTION,
        thinkingDuration: elapsedSeconds(startTime),
      }));
      return;
    }

    const execResult = await executePureQueryAndReport(
      orchestratorResponse.legend_query,
      pureExecutionContext,
      dataProductCoordinates,
      config,
      plugin,
      setMessages,
      startTime,
    );

    try {
      if (execResult.rows.length > 0) {
        await analyzeOrchestratorResults(
          question,
          orchestratorResponse.legend_query,
          execResult,
          metadata,
          context,
          startTime,
        );
      } else {
        await handleEmptyOrchestratorResults(
          question,
          orchestratorResponse.legend_query,
          { dataProductCoordinates, pureExecutionContext },
          metadata,
          resolvedEntities,
          context,
          startTime,
        );
      }
    } catch (analysisError) {
      assertErrorThrown(analysisError);
      addThinkingStep(
        setMessages,
        `Result analysis failed: ${analysisError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
      );
    } finally {
      completeThinkingSteps(setMessages);
      updateLastAssistant(setMessages, () => ({
        isProcessing: false,
        thinkingDuration: elapsedSeconds(startTime),
      }));
    }
  } catch (error) {
    assertErrorThrown(error);
    const orchErrorType = classifyError(error);
    addThinkingStep(
      setMessages,
      `Error: ${error.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );

    try {
      addThinkingStep(
        setMessages,
        'Building guidance from available metadata...',
      );
      const fallbackText = await withTimeout(
        plugin.buildFailureFallback(question, error.message, metadata, config),
        ANALYSIS_TIMEOUT_MS,
      );
      if (fallbackText) {
        completeThinkingSteps(setMessages);
        updateLastAssistant(setMessages, () => ({
          dataContext: fallbackText,
          isProcessing: false,
          thinkingDuration: elapsedSeconds(startTime),
        }));
        return;
      }
    } catch (fallbackError) {
      assertErrorThrown(fallbackError);
      addThinkingStep(
        setMessages,
        `Fallback guidance failed: ${fallbackError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
      );
    }

    finishWithThinkingError(
      setMessages,
      error.message,
      startTime,
      orchErrorType,
    );
  }
}

export function cleanLlmSqlResponse(raw: string): string {
  return raw
    .trim()
    .replace(/^```\w*\n?/, '')
    .replace(/\n?```$/, '')
    .replace(/;\s*$/, '')
    .trim();
}

export function isValidSqlCorrection(
  trimmed: string,
  currentSql: string,
): boolean {
  return (
    trimmed.length > 0 &&
    trimmed.toLowerCase().startsWith('select') &&
    trimmed !== currentSql
  );
}

export function sanitizeJoinOrderBy(sql: string): string {
  if (!JOIN_PATTERN.test(sql)) {
    return sql;
  }
  const parts = sql.split(ORDER_BY_SPLIT);
  if (parts.length < 2) {
    return sql;
  }

  const beforeOrderBy = parts[0] ?? '';
  const afterOrderBy = parts.slice(1).join('ORDER BY').replace(/^\s+/, '');

  const selectAliases = new Map<string, string>();
  const aliasRegex =
    /\b(?<tbl>[a-z]\w*)\s*\.\s*"(?<col>[^"]+)"\s+AS\s+(?:"(?<qAlias>[^"]+)"|(?<uAlias>\w+))/gi;
  let m: RegExpExecArray | null;
  while ((m = aliasRegex.exec(beforeOrderBy)) !== null) {
    const tableAlias = (m.groups?.tbl ?? '').toLowerCase();
    const colName = (m.groups?.col ?? '').toLowerCase();
    const asAlias = m.groups?.qAlias ?? m.groups?.uAlias ?? '';
    selectAliases.set(`${tableAlias}.${colName}`, asAlias);
  }

  if (selectAliases.size === 0) {
    return sql;
  }

  const rewritten = afterOrderBy.replaceAll(
    ALIAS_DOT_COL_PATTERN,
    (...args) => {
      const groups = args[args.length - 1] as {
        tbl: string;
        col: string;
      };
      const key = `${groups.tbl.toLowerCase()}.${groups.col.toLowerCase()}`;
      const alias = selectAliases.get(key);
      return alias ? `"${alias}"` : String(args[0]);
    },
  );

  if (rewritten === afterOrderBy) {
    return sql;
  }
  return `${beforeOrderBy}ORDER BY ${rewritten}`;
}

export function sanitizeLiteralColumns(sql: string): string {
  if (!UNION_ALL_PATTERN.test(sql)) {
    return sql;
  }
  LITERAL_COL_PATTERN.lastIndex = 0;
  if (!LITERAL_COL_PATTERN.test(sql)) {
    return sql;
  }
  LITERAL_COL_PATTERN.lastIndex = 0;
  return sql.replace(LITERAL_COL_PATTERN, '');
}

function isDateLikeParam(paramName: string): boolean {
  return SERVICE_PARAM_DATE_LIKE_PATTERNS.some((p) => p.test(paramName));
}

function hasUnresolvableParams(service: TDSServiceSchema): boolean {
  return service.parameters.some((p) => !isDateLikeParam(p));
}

function getNonDateParamNames(service: TDSServiceSchema): string[] {
  return service.parameters.filter((p) => !isDateLikeParam(p));
}

/**
 * Strips non-date service parameters whose values were NOT explicitly
 * mentioned by the user in their question. Parameters with values that
 * appear in the question text are kept, since those are user-intended.
 */
export function stripGuessedNonDateServiceParams(
  sql: string,
  question: string,
): string {
  const lowerQuestion = question.toLowerCase();
  return sql.replaceAll(/,\s*\w+\s*=>\s*'[^']*'/g, (match) => {
    const parts = /,\s*(?<param>\w+)\s*=>\s*'(?<value>[^']*)'/.exec(
      match,
    )?.groups;
    if (!parts?.param) {
      return match;
    }
    if (parts.param === 'coordinates' || isDateLikeParam(parts.param)) {
      return match;
    }
    if (parts.value && lowerQuestion.includes(parts.value.toLowerCase())) {
      return match;
    }
    return '';
  });
}

/**
 * Ensures all date-like parameters from the service schemas are present
 * in EVERY service() call in the SQL. If the LLM omitted a mandatory date
 * parameter, this injects it with today's date into each service() call
 * that lacks it. Only applies to service() calls (not p() calls).
 */
export function ensureDateParameters(
  sql: string,
  services: TDSServiceSchema[],
): string {
  const dateParams = new Set<string>();
  for (const svc of services) {
    if (svc.sourceType === TDSServiceSourceType.ACCESS_POINT) {
      continue;
    }
    for (const p of svc.parameters) {
      if (isDateLikeParam(p)) {
        dateParams.add(p);
      }
    }
  }
  if (dateParams.size === 0) {
    return sql;
  }

  const today = getTodayISO();

  const serviceCallPattern = /\bservice\s*\([^()]*\)/gi;
  return sql.replaceAll(serviceCallPattern, (match) => {
    let patched = match;
    for (const param of dateParams) {
      if (new RegExp(String.raw`\b${param}\s*=>`, 'i').test(patched)) {
        continue;
      }
      const lastParen = patched.lastIndexOf(')');
      if (lastParen !== -1) {
        patched = `${patched.slice(
          0,
          lastParen,
        )},\n    ${param} => '${today}'${patched.slice(lastParen)}`;
      }
    }
    return patched;
  });
}

export interface MissingParamInfo {
  name: string;
  hint?: string;
  isDateLike: boolean;
}

function resolveParamHint(
  paramName: string,
  isDateLike: boolean,
  service: TDSServiceSchema,
): string | undefined {
  if (isDateLike) {
    return `today's date: ${getTodayISO()}`;
  }
  const matchingCol = service.columns.find((c) => c.name === paramName);
  return matchingCol?.sampleValues ?? matchingCol?.documentation ?? undefined;
}

/**
 * Detects ALL service parameters required by the schema but missing from
 * the generated SQL. Works for any parameter type — date, identifier, key,
 * or anything else. Each result includes a hint (from schema column docs
 * or sample values) and whether the param is date-like.
 */
export function detectMissingServiceParams(
  sql: string,
  services: TDSServiceSchema[],
): MissingParamInfo[] {
  const missing: MissingParamInfo[] = [];
  const seen = new Set<string>();

  for (const svc of services) {
    if (svc.sourceType === TDSServiceSourceType.ACCESS_POINT) {
      continue;
    }
    for (const p of svc.parameters) {
      if (seen.has(p)) {
        continue;
      }
      seen.add(p);
      if (!new RegExp(String.raw`\b${p}\s*=>`, 'i').test(sql)) {
        const isDateLike = isDateLikeParam(p);
        const hint = resolveParamHint(p, isDateLike, svc);
        missing.push({
          name: p,
          isDateLike,
          ...(hint === undefined ? {} : { hint }),
        });
      }
    }
  }
  return missing;
}

/**
 * Builds a user-facing warning message listing which service parameters
 * are missing from the query and need to be provided by the user.
 */
export function buildMissingParamsWarning(
  missingParams: MissingParamInfo[],
): string {
  const paramDescriptions = missingParams.map((mp) => {
    if (mp.hint) {
      return `- **${mp.name}** (e.g. ${mp.hint})`;
    }
    return `- **${mp.name}**`;
  });
  const exampleValues = missingParams
    .map((mp) => {
      if (mp.isDateLike) {
        return `${mp.name}=${getTodayISO()}`;
      }
      return `${mp.name}=[your value]`;
    })
    .join(', ');
  return [
    `This service requires the following parameter${missingParams.length > 1 ? 's' : ''} to execute:`,
    '',
    ...paramDescriptions,
    '',
    `Please provide ${missingParams.length > 1 ? 'values' : 'a value'} in your question, e.g. "show data where ${exampleValues}".`,
  ].join('\n');
}

/**
 * Appends a safety LIMIT to queries that lack one, preventing unbounded
 * result sets on large services. Skips aggregation queries since those
 * naturally produce bounded output.
 */
export function ensureSafeLimit(
  sql: string,
  limit: number = DEFAULT_SAFETY_LIMIT,
): string {
  if (HAS_LIMIT_PATTERN.test(sql) || HAS_AGGREGATION_PATTERN.test(sql)) {
    return sql;
  }
  return `${sql.trimEnd()}\nLIMIT ${limit}`;
}

async function executeSqlForServices(
  sql: string,
  services: TDSServiceSchema[],
  dataProductCoordinates:
    | LegendAIOrchestratorDataProductCoordinates
    | undefined,
  plugin: LegendAI_LegendApplicationPlugin_Extension,
  config: LegendAIConfig,
): Promise<LegendAISqlExecutionResultData> {
  const safeSql = ensureSafeLimit(
    ensureDateParameters(
      sanitizeLiteralColumns(sanitizeJoinOrderBy(sql)),
      services,
    ),
  );
  const isAccessPoint = services.some(
    (s) => s.sourceType === TDSServiceSourceType.ACCESS_POINT,
  );
  if (isAccessPoint && dataProductCoordinates) {
    return plugin.executeLakehouseSql(safeSql, dataProductCoordinates, config);
  }
  return plugin.executeSql(safeSql, config);
}

interface SqlExecutionOutcome {
  sql: string;
  result?: LegendAISqlExecutionResultData;
  error?: string;
}

async function executeSqlWithRetries(
  initialSql: string,
  question: string,
  services: TDSServiceSchema[],
  coordinates: string,
  dataProductCoordinates:
    | LegendAIOrchestratorDataProductCoordinates
    | undefined,
  context: LegendAIOperationContext,
): Promise<SqlExecutionOutcome> {
  const { plugin, config, setMessages } = context;
  let currentSql = initialSql;

  for (let attempt = 0; attempt <= DEFAULT_MAX_EXECUTION_RETRIES; attempt++) {
    try {
      const result = await executeSqlForServices(
        currentSql,
        services,
        dataProductCoordinates,
        plugin,
        config,
      );
      return { sql: currentSql, result };
    } catch (executeError) {
      assertErrorThrown(executeError);
      if (attempt >= DEFAULT_MAX_EXECUTION_RETRIES) {
        return { sql: currentSql, error: executeError.message };
      }
      addThinkingStep(
        setMessages,
        `Execution failed (attempt ${attempt + 1}/${DEFAULT_MAX_EXECUTION_RETRIES + 1}), correcting query...`,
      );
      const corrected = await attemptErrorCorrection(
        currentSql,
        executeError.message,
        question,
        services,
        coordinates,
        context,
      );
      if (corrected) {
        currentSql = corrected;
        updateLastAssistant(setMessages, () => ({ sql: currentSql }));
        continue;
      }
      return { sql: currentSql, error: executeError.message };
    }
  }
  return { sql: currentSql };
}

async function attemptErrorCorrection(
  currentSql: string,
  errorMessage: string,
  question: string,
  services: TDSServiceSchema[],
  coordinates: string,
  context: LegendAIOperationContext,
): Promise<string | undefined> {
  const { plugin, config, setMessages } = context;

  let availableColumns: string[] | undefined;
  if (/no column found|column.*not.*found/i.test(errorMessage)) {
    const primaryService = services[0];
    if (primaryService) {
      availableColumns = await plugin.probeServiceColumns(
        primaryService,
        coordinates,
        config,
      );
    }
  }

  const prompt = plugin.buildErrorCorrectionPrompt(
    currentSql,
    errorMessage,
    question,
    services,
    coordinates,
    availableColumns,
  );
  if (!prompt) {
    return undefined;
  }
  try {
    const correctedSql = await plugin.callLLM(prompt, config);
    const trimmed = cleanLlmSqlResponse(correctedSql);
    if (isValidSqlCorrection(trimmed, currentSql)) {
      return trimmed;
    }
  } catch (correctionError) {
    assertErrorThrown(correctionError);
    addThinkingStep(
      setMessages,
      `SQL error correction failed: ${correctionError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );
  }
  return undefined;
}

async function attemptZeroRowCorrection(
  currentSql: string,
  question: string,
  services: TDSServiceSchema[],
  coordinates: string,
  dataProductCoordinates:
    | LegendAIOrchestratorDataProductCoordinates
    | undefined,
  context: LegendAIOperationContext,
): Promise<
  { sql: string; result: LegendAISqlExecutionResultData } | undefined
> {
  const { plugin, config, setMessages } = context;
  addThinkingStep(
    setMessages,
    'Query returned 0 rows, attempting filter correction...',
  );
  const prompt = plugin.buildZeroRowCorrectionPrompt(
    currentSql,
    question,
    services,
    coordinates,
  );
  if (!prompt) {
    return undefined;
  }
  try {
    const correctedSql = await plugin.callLLM(prompt, config);
    const trimmed = cleanLlmSqlResponse(correctedSql);
    if (!isValidSqlCorrection(trimmed, currentSql)) {
      return undefined;
    }
    addThinkingStep(setMessages, 'Retrying with corrected filters...');
    updateLastAssistant(setMessages, () => ({ sql: trimmed }));
    try {
      const retryResult = await executeSqlForServices(
        trimmed,
        services,
        dataProductCoordinates,
        plugin,
        config,
      );
      if (retryResult.rows.length > 0) {
        return { sql: trimmed, result: retryResult };
      }
    } catch (retryExecError) {
      assertErrorThrown(retryExecError);
      addThinkingStep(
        setMessages,
        `Corrected query execution failed: ${retryExecError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
      );
    }
  } catch (correctionError) {
    assertErrorThrown(correctionError);
    addThinkingStep(
      setMessages,
      `Zero-row correction failed: ${correctionError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );
  }
  return undefined;
}

function formatUnresolvableParams(services: TDSServiceSchema[]): string[] {
  const parts: string[] = [];
  for (const svc of services) {
    for (const paramName of getNonDateParamNames(svc)) {
      const matchingCol = svc.columns.find((c) => c.name === paramName);
      const docHint = matchingCol?.documentation ?? matchingCol?.sampleValues;
      parts.push(
        docHint ? `**${paramName}** (${docHint})` : `**${paramName}**`,
      );
    }
  }
  return [...new Set(parts)];
}

function buildZeroRowMessage(services: TDSServiceSchema[]): string {
  const withUnresolvable = services.filter((s) => hasUnresolvableParams(s));
  if (withUnresolvable.length > 0) {
    const uniqueParts = formatUnresolvableParams(withUnresolvable);
    const firstSvc = withUnresolvable[0];
    const firstParam = firstSvc
      ? (getNonDateParamNames(firstSvc)[0] ?? 'parameter')
      : 'parameter';
    return `The SQL query executed successfully but returned **0 rows**. This service requires specific values for ${uniqueParts.join(', ')} to return data. Please include ${uniqueParts.length === 1 ? 'a value' : 'values'} in your question, e.g., "show data where ${firstParam} is [your value]".`;
  }

  const withFailedExtraction = services.filter(
    (s) => s.parameterExtractionFailed,
  );
  if (withFailedExtraction.length > 0) {
    const names = withFailedExtraction.map((s) => `**${s.title}**`).join(', ');
    return `The SQL query executed successfully but returned **0 rows**. Note: parameter detection for ${names} was incomplete — this service may require additional parameters not shown in the schema. Try specifying filter values (dates, IDs, etc.) directly in your question.`;
  }

  return 'The SQL query executed successfully but returned **0 rows**. The applied filters may not match any records, or the specific values may not exist in the queried datasets.';
}

function handleSqlGenerationFailure(
  setMessages: MessageSetter,
  startTime: number,
  hasOrchestratorFallback: boolean,
  orchestratorMessage: string,
  errorMessage: string,
  errorType: LegendAIErrorType,
  suggestedQueries?: string[],
): void {
  const suggestions = suggestedQueries ?? [];
  completeThinkingSteps(setMessages);
  if (hasOrchestratorFallback) {
    updateLastAssistant(setMessages, () => ({
      textAnswer: orchestratorMessage,
      suggestedQueries: suggestions,
      fallbackAction: {
        label: ORCHESTRATOR_FALLBACK_LABEL,
        actionId: LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID,
      },
      isProcessing: false,
      thinkingDuration: elapsedSeconds(startTime),
    }));
  } else {
    finishWithThinkingError(setMessages, errorMessage, startTime, errorType);
    if (suggestions.length > 0) {
      updateLastAssistant(setMessages, () => ({
        suggestedQueries: suggestions,
      }));
    }
  }
}

interface QueryResultReport {
  currentSql: string;
  sqlResult: LegendAISqlExecutionResultData;
  question: string;
  services: TDSServiceSchema[];
}

async function reportQueryResults(
  report: QueryResultReport,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  startTime: number,
  hasOrchestratorFallback: boolean,
): Promise<void> {
  const { currentSql, sqlResult, question, services } = report;
  const { setMessages } = context;
  if (sqlResult.rows.length > 0) {
    const columns = deduplicateColumns(sqlResult.columns);
    const rows = sqlResult.rows;
    completeThinkingSteps(setMessages);
    addThinkingStep(
      setMessages,
      `Retrieved ${rows.length} row${rows.length === 1 ? '' : 's'}`,
    );
    completeThinkingSteps(setMessages);
    updateLastAssistant(setMessages, () => ({
      sql: currentSql,
      gridData: {
        columnDefs: buildColumnDefsFromNames(columns),
        rowData: rows,
      },
      execTime: elapsedSeconds(startTime, 2),
      isProcessing: true,
      isExecuting: false,
      thinkingDuration: elapsedSeconds(startTime),
    }));

    try {
      await analyzeOrchestratorResults(
        question,
        currentSql,
        sqlResult,
        metadata,
        context,
        startTime,
      );
    } catch (analysisError) {
      assertErrorThrown(analysisError);
      addThinkingStep(
        setMessages,
        `Result analysis failed: ${analysisError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
      );
    } finally {
      completeThinkingSteps(setMessages);
      updateLastAssistant(setMessages, () => ({
        isProcessing: false,
        thinkingDuration: elapsedSeconds(startTime),
      }));
    }
  } else {
    addThinkingStep(
      setMessages,
      'Query returned 0 rows after correction attempts.',
    );
    completeThinkingSteps(setMessages);
    const fallback = hasOrchestratorFallback
      ? {
          fallbackAction: {
            label: ORCHESTRATOR_FALLBACK_LABEL,
            actionId: LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID,
          },
        }
      : {};
    updateLastAssistant(setMessages, () => ({
      textAnswer: buildZeroRowMessage(services),
      ...fallback,
      isProcessing: false,
      isExecuting: false,
      thinkingDuration: elapsedSeconds(startTime),
    }));
  }
}

/**
 * Scores each service against the user question by counting keyword
 * overlap between the question tokens and the service title, description,
 * column names, and parameter names. Returns services sorted by
 * descending relevance score.
 */
export function preFilterServicesByRelevance(
  question: string,
  services: TDSServiceSchema[],
  limit: number,
): TDSServiceSchema[] {
  const queryTokens = question
    .toLowerCase()
    .split(/[\s,.:;!?'"()\-/]+/)
    .filter((t) => t.length > 2);
  if (queryTokens.length === 0) {
    return services.slice(0, limit);
  }
  const scored = services.map((svc) => {
    const haystack = [
      svc.title,
      svc.description ?? '',
      svc.pattern,
      ...svc.columns.slice(0, 30).map((c) => c.name),
      ...svc.parameters,
      ...(svc.preFilters ?? []).flatMap((pf) => {
        const parts = [pf.property, pf.operator];
        if (pf.value !== undefined) {
          parts.push(String(pf.value));
        }
        return parts;
      }),
    ]
      .join(' ')
      .toLowerCase();
    let score = 0;
    for (const token of queryTokens) {
      if (haystack.includes(token)) {
        score += 1;
      }
    }
    return { svc, score };
  });
  scored.sort((a, b) => b.score - a.score);
  return scored.slice(0, limit).map((s) => s.svc);
}

async function selectBestServices(
  question: string,
  services: TDSServiceSchema[],
  context: LegendAIOperationContext,
): Promise<TDSServiceSchema[]> {
  const { plugin, config, setMessages } = context;
  if (services.length <= 1) {
    return services;
  }

  let candidates = services;
  if (services.length > MAX_SERVICES_FOR_LLM_SELECTION) {
    candidates = preFilterServicesByRelevance(
      question,
      services,
      MAX_SERVICES_FOR_LLM_SELECTION,
    );
    addThinkingStep(
      setMessages,
      `Pre-filtered ${services.length} services to ${candidates.length} candidates`,
    );
  }

  try {
    addThinkingStep(setMessages, 'Selecting best service for your query...');
    return await plugin.selectRelevantServices(question, candidates, config);
  } catch (selectionError) {
    assertErrorThrown(selectionError);
    addThinkingStep(
      setMessages,
      `Service selection failed, using pre-filtered candidates: ${selectionError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );
    return candidates;
  }
}

async function tryRecoverZeroRows(
  currentSql: string,
  sqlResult: LegendAISqlExecutionResultData,
  question: string,
  selectedServices: TDSServiceSchema[],
  coordinates: string,
  dataProductCoordinates:
    | LegendAIOrchestratorDataProductCoordinates
    | undefined,
  context: LegendAIOperationContext,
): Promise<{ sql: string; result: LegendAISqlExecutionResultData }> {
  const { plugin, config, setMessages } = context;
  let recoveredSql = currentSql;
  let recoveredResult = sqlResult;

  const strippedSql = stripGuessedNonDateServiceParams(recoveredSql, question);
  if (strippedSql !== recoveredSql) {
    addThinkingStep(
      setMessages,
      'Trying query without guessed parameter values...',
    );
    try {
      const strippedResult = await executeSqlForServices(
        strippedSql,
        selectedServices,
        dataProductCoordinates,
        plugin,
        config,
      );
      if (strippedResult.rows.length > 0) {
        recoveredSql = strippedSql;
        recoveredResult = strippedResult;
        updateLastAssistant(setMessages, () => ({ sql: strippedSql }));
      }
    } catch (stripError) {
      assertErrorThrown(stripError);
      addThinkingStep(
        setMessages,
        `Parameter stripping recovery failed: ${stripError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
      );
    }
  }

  if (recoveredResult.rows.length === 0) {
    const correction = await attemptZeroRowCorrection(
      recoveredSql,
      question,
      selectedServices,
      coordinates,
      dataProductCoordinates,
      context,
    );
    if (correction) {
      recoveredSql = correction.sql;
      recoveredResult = correction.result;
    }
  }

  return { sql: recoveredSql, result: recoveredResult };
}

/**
 * Dedicated query flow for data product access points.
 * Unlike processDataQuery this:
 * - Uses AP-specific generator/judge prompts (p() syntax, no coordinates/params)
 * - Skips parameter detection (APs have no parameters)
 */
async function processAccessPointQuery(
  question: string,
  accessPoints: TDSServiceSchema[],
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  startTime: number,
  dataProductCoordinates: LegendAIOrchestratorDataProductCoordinates,
): Promise<void> {
  const { config, plugin, setMessages } = context;
  const hasOrchestratorFallback = Boolean(config.orchestratorUrl);

  addThinkingStep(setMessages, 'Found relevant access points to query');

  const selectedAPs = await selectBestServices(question, accessPoints, context);

  const judgedSql = await generateAndJudgeAccessPointSql(
    question,
    selectedAPs,
    context,
    startTime,
  );

  if (!judgedSql) {
    addThinkingStep(
      setMessages,
      'SQL generation could not produce a valid query.',
    );
    handleSqlGenerationFailure(
      setMessages,
      startTime,
      hasOrchestratorFallback,
      SQL_GENERATION_FAILURE_WITH_ORCHESTRATOR,
      SQL_GENERATION_FAILURE_NO_ORCHESTRATOR,
      LegendAIErrorType.GENERATION,
      buildFallbackSuggestions(selectedAPs),
    );
    return;
  }

  const sqlGenTimeValue = elapsedSeconds(startTime, 2);
  completeThinkingSteps(setMessages);
  updateLastAssistant(setMessages, () => ({
    sql: judgedSql,
    sqlGenTime: sqlGenTimeValue,
    isExecuting: true,
  }));

  const execStartTime = Date.now();
  try {
    const safeSql = ensureSafeLimit(judgedSql);
    const rawResult = await plugin.executeLakehouseSql(
      safeSql,
      dataProductCoordinates,
      config,
    );

    await reportQueryResults(
      {
        currentSql: judgedSql,
        sqlResult: rawResult,
        question,
        services: selectedAPs,
      },
      metadata,
      context,
      startTime,
      hasOrchestratorFallback,
    );
  } catch (executeError) {
    assertErrorThrown(executeError);
    const execErrorType = classifyError(executeError);
    addThinkingStep(
      setMessages,
      `Execution failed: ${executeError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );
    finishWithThinkingError(
      setMessages,
      buildExecutionErrorMessage(executeError.message, selectedAPs),
      startTime,
      execErrorType === LegendAIErrorType.GENERAL
        ? LegendAIErrorType.EXECUTION
        : execErrorType,
    );
    updateLastAssistant(setMessages, () => ({
      execTime: elapsedSeconds(execStartTime, 2),
      isExecuting: false,
      suggestedQueries: buildFallbackSuggestions(selectedAPs),
      ...(hasOrchestratorFallback
        ? {
            fallbackAction: {
              label: ORCHESTRATOR_FALLBACK_LABEL,
              actionId: LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID,
            },
          }
        : {}),
    }));
  }
}

async function processDataQuery(
  question: string,
  services: TDSServiceSchema[],
  coordinates: string,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  startTime: number,
  orchestratorOptions?: LegendAIOrchestratorOptionsParam,
): Promise<void> {
  const { config, setMessages } = context;
  const dataProductCoordinates = orchestratorOptions?.dataProductCoordinates;
  const hasOrchestratorFallback = Boolean(
    config.orchestratorUrl && dataProductCoordinates,
  );

  if (services.length === 0) {
    handleSqlGenerationFailure(
      setMessages,
      startTime,
      hasOrchestratorFallback,
      'No TDS services available for SQL querying. You can try the Legend AI Orchestrator to generate a Pure query instead.',
      'No TDS services available for querying',
      LegendAIErrorType.GENERAL,
    );
    return;
  }

  addThinkingStep(setMessages, 'Found relevant services to query');

  const selectedServices = await selectBestServices(
    question,
    services,
    context,
  );

  const judgedSql = await generateAndJudgeSql(
    question,
    selectedServices,
    coordinates,
    context,
    startTime,
    metadata,
  );

  if (!judgedSql) {
    addThinkingStep(
      setMessages,
      'SQL generation could not produce a valid query.',
    );
    handleSqlGenerationFailure(
      setMessages,
      startTime,
      hasOrchestratorFallback,
      SQL_GENERATION_FAILURE_WITH_ORCHESTRATOR,
      SQL_GENERATION_FAILURE_NO_ORCHESTRATOR,
      LegendAIErrorType.GENERATION,
      buildFallbackSuggestions(selectedServices),
    );
    return;
  }

  // Check for any missing service parameters (date, id, key — anything)
  const missingParams = detectMissingServiceParams(judgedSql, selectedServices);
  if (missingParams.length > 0) {
    const sqlGenTimeValue = elapsedSeconds(startTime, 2);
    completeThinkingSteps(setMessages);
    addThinkingStep(
      setMessages,
      `Missing required parameter${missingParams.length > 1 ? 's' : ''}: ${missingParams.map((p) => p.name).join(', ')}`,
    );
    completeThinkingSteps(setMessages);
    updateLastAssistant(setMessages, () => ({
      sql: judgedSql,
      sqlGenTime: sqlGenTimeValue,
      textAnswer: buildMissingParamsWarning(missingParams),
      isProcessing: false,
      isExecuting: false,
      thinkingDuration: elapsedSeconds(startTime),
    }));
    return;
  }

  const sqlGenTimeValue = elapsedSeconds(startTime, 2);
  completeThinkingSteps(setMessages);
  updateLastAssistant(setMessages, () => ({
    sql: judgedSql,
    sqlGenTime: sqlGenTimeValue,
    isExecuting: true,
  }));

  const execOutcome = await executeSqlWithRetries(
    judgedSql,
    question,
    selectedServices,
    coordinates,
    dataProductCoordinates,
    context,
  );

  if (execOutcome.error) {
    const execErrorType = classifyError(new Error(execOutcome.error));
    addThinkingStep(
      setMessages,
      `Execution failed: ${execOutcome.error.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );
    finishWithThinkingError(
      setMessages,
      buildExecutionErrorMessage(execOutcome.error, selectedServices),
      startTime,
      execErrorType === LegendAIErrorType.GENERAL
        ? LegendAIErrorType.EXECUTION
        : execErrorType,
    );
    updateLastAssistant(setMessages, () => ({
      isExecuting: false,
      suggestedQueries: buildFallbackSuggestions(selectedServices),
      ...(hasOrchestratorFallback
        ? {
            fallbackAction: {
              label: ORCHESTRATOR_FALLBACK_LABEL,
              actionId: LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID,
            },
          }
        : {}),
    }));
    return;
  }

  if (!execOutcome.result) {
    return;
  }

  let currentSql = execOutcome.sql;
  let sqlResult = execOutcome.result;

  if (sqlResult.rows.length === 0) {
    const recovered = await tryRecoverZeroRows(
      currentSql,
      sqlResult,
      question,
      selectedServices,
      coordinates,
      dataProductCoordinates,
      context,
    );
    currentSql = recovered.sql;
    sqlResult = recovered.result;
  }

  await reportQueryResults(
    {
      currentSql,
      sqlResult,
      question,
      services: selectedServices,
    },
    metadata,
    context,
    startTime,
    hasOrchestratorFallback,
  );
}

function splitServicesByType(services: TDSServiceSchema[]): {
  tdsServices: TDSServiceSchema[];
  accessPoints: TDSServiceSchema[];
} {
  return {
    tdsServices: services.filter(
      (s) => s.sourceType !== TDSServiceSourceType.ACCESS_POINT,
    ),
    accessPoints: services.filter(
      (s) => s.sourceType === TDSServiceSourceType.ACCESS_POINT,
    ),
  };
}

async function routeToAccessPointOrData(
  question: string,
  services: TDSServiceSchema[],
  coordinates: string,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  startTime: number,
  orchestratorOpts: LegendAIOrchestratorOptionsParam | undefined,
): Promise<void> {
  const dataProductCoordinates = orchestratorOpts?.dataProductCoordinates;
  const { tdsServices, accessPoints } = splitServicesByType(services);
  if (
    tdsServices.length === 0 &&
    accessPoints.length > 0 &&
    dataProductCoordinates
  ) {
    await processAccessPointQuery(
      question,
      accessPoints,
      metadata,
      context,
      startTime,
      dataProductCoordinates,
    );
  } else {
    await processDataQuery(
      question,
      tdsServices,
      coordinates,
      metadata,
      context,
      startTime,
      orchestratorOpts,
    );
  }
}

async function handleAmbiguousIntent(
  question: string,
  services: TDSServiceSchema[],
  coordinates: string,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  startTime: number,
  orchestratorOpts: LegendAIOrchestratorOptionsParam | undefined,
): Promise<void> {
  const { setMessages } = context;
  addThinkingStep(
    setMessages,
    'Intent is ambiguous, providing metadata context and querying data...',
  );
  let metadataOverview: string | undefined;
  try {
    addThinkingStep(setMessages, 'Building metadata context...');
    metadataOverview = await buildMetadataOverview(question, metadata, context);
  } catch (metadataError) {
    assertErrorThrown(metadataError);
    addThinkingStep(
      setMessages,
      `Metadata context failed: ${metadataError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );
  }

  try {
    await routeToAccessPointOrData(
      question,
      services,
      coordinates,
      metadata,
      context,
      startTime,
      orchestratorOpts,
    );
    if (metadataOverview) {
      attachMetadataOverview(setMessages, metadataOverview);
    }
  } catch (queryError) {
    assertErrorThrown(queryError);
    addThinkingStep(
      setMessages,
      'Query failed, answering from product metadata...',
    );
    await handleMetadataQuestion(question, metadata, context, startTime, true);
  }
}

export async function processQuestion(
  question: string,
  services: TDSServiceSchema[],
  coordinates: string,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  dataProductCoordinates?: LegendAIOrchestratorDataProductCoordinates,
  pureExecutionContext?: QueryExplicitExecutionContextInfo,
): Promise<void> {
  const { config, plugin, setMessages } = context;
  const startTime = Date.now();

  try {
    addThinkingStep(setMessages, 'Analyzing your question...');

    const orchestratorOpts = dataProductCoordinates
      ? {
          dataProductCoordinates,
          ...(pureExecutionContext === undefined
            ? {}
            : { pureExecutionContext }),
        }
      : undefined;

    if (services.length === 0) {
      await handleMetadataQuestion(
        question,
        metadata,
        context,
        startTime,
        false,
      );
      if (config.orchestratorUrl && dataProductCoordinates) {
        updateLastAssistant(setMessages, () => ({
          fallbackAction: {
            label: ORCHESTRATOR_FALLBACK_LABEL,
            actionId: LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID,
          },
        }));
      }
      return;
    }

    const fastIntent = classifyQuestionIntentFast(question, true);
    if (
      fastIntent.intent === LegendAIQuestionIntent.METADATA &&
      !fastIntent.ambiguous
    ) {
      await handleMetadataQuestion(
        question,
        metadata,
        context,
        startTime,
        true,
      );
      return;
    }

    if (fastIntent.ambiguous) {
      await handleAmbiguousIntent(
        question,
        services,
        coordinates,
        metadata,
        context,
        startTime,
        orchestratorOpts,
      );
      return;
    }

    const serviceNames = services.map((s) => s.title);
    const intent = await plugin.classifyQuestionIntent(
      question,
      true,
      config,
      serviceNames,
    );

    if (intent === LegendAIQuestionIntent.METADATA) {
      await handleMetadataQuestion(
        question,
        metadata,
        context,
        startTime,
        true,
      );
      return;
    }

    try {
      await routeToAccessPointOrData(
        question,
        services,
        coordinates,
        metadata,
        context,
        startTime,
        orchestratorOpts,
      );
    } catch (sqlError) {
      assertErrorThrown(sqlError);
      addThinkingStep(
        setMessages,
        'SQL generation failed, answering from product metadata...',
      );
      await handleMetadataQuestion(
        question,
        metadata,
        context,
        startTime,
        true,
      );
      appendFallbackSuggestions(setMessages, services);
    }
  } catch (error) {
    assertErrorThrown(error);
    addThinkingStep(
      setMessages,
      `Error: ${error.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );
    finishWithThinkingError(
      setMessages,
      error.message,
      startTime,
      classifyError(error),
    );
    appendFallbackSuggestions(setMessages, services);
  }
}

async function routeDataQueryWithErrorHandling(
  question: string,
  services: TDSServiceSchema[],
  coordinates: string,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  orchestratorOptions: LegendAIOrchestratorOptionsParam | undefined,
): Promise<void> {
  const { setMessages } = context;
  const startTime = Date.now();
  try {
    addThinkingStep(setMessages, 'Preparing data query...');
    await routeToAccessPointOrData(
      question,
      services,
      coordinates,
      metadata,
      context,
      startTime,
      orchestratorOptions,
    );
  } catch (error) {
    assertErrorThrown(error);
    addThinkingStep(
      setMessages,
      `Error: ${error.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
    );
    finishWithThinkingError(
      setMessages,
      error.message,
      startTime,
      classifyError(error),
    );
  }
}

export async function processQuestionWithIntent(
  question: string,
  intent: LegendAIQuestionIntent,
  services: TDSServiceSchema[],
  coordinates: string,
  metadata: LegendAIProductMetadata,
  context: LegendAIOperationContext,
  orchestratorOptions?: LegendAIOrchestratorOptionsParam,
): Promise<void> {
  const { config, setMessages } = context;
  const dataProductCoordinates = orchestratorOptions?.dataProductCoordinates;

  if (intent === LegendAIQuestionIntent.METADATA) {
    const startTime = Date.now();
    try {
      await handleMetadataQuestion(
        question,
        metadata,
        context,
        startTime,
        services.length > 0,
      );
    } catch (error) {
      assertErrorThrown(error);
      addThinkingStep(
        setMessages,
        `Error: ${error.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`,
      );
      finishWithThinkingError(
        setMessages,
        error.message,
        startTime,
        classifyError(error),
      );
    }
    return;
  }

  if (
    intent === LegendAIQuestionIntent.ORCHESTRATOR &&
    config.orchestratorUrl &&
    dataProductCoordinates
  ) {
    if (services.length > 0) {
      await routeDataQueryWithErrorHandling(
        question,
        services,
        coordinates,
        metadata,
        context,
        orchestratorOptions,
      );
      return;
    }
    const startTime = Date.now();
    await handleMetadataQuestion(question, metadata, context, startTime, false);
    updateLastAssistant(setMessages, () => ({
      fallbackAction: {
        label: ORCHESTRATOR_FALLBACK_LABEL,
        actionId: LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID,
      },
    }));
    return;
  }

  await routeDataQueryWithErrorHandling(
    question,
    services,
    coordinates,
    metadata,
    context,
    orchestratorOptions,
  );
}