orcaq 1.0.26 → 1.0.28

package/.output/server/chunks/routes/api/ai/agent.mjs

@@ -0,0 +1,1626 @@
+import { tool, generateText, Output, ToolLoopAgent, stepCountIs, createAgentUIStreamResponse, smoothStream } from 'ai';
+import { d as defineEventHandler, r as readBody, c as createError } from '../../../nitro/nitro.mjs';
+import { g as getDatabaseSource, D as DatabaseClientType } from '../../../_/db-connection.mjs';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createXai } from '@ai-sdk/xai';
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { z } from 'zod/v4';
+import Papa from 'papaparse';
+import 'ssh2';
+import 'node:net';
+import 'node:http';
+import 'node:https';
+import 'node:events';
+import 'node:buffer';
+import 'node:fs';
+import 'node:path';
+import 'node:crypto';
+import 'node:url';
+import '@iconify/utils';
+import 'consola';
+import 'knex';
+import 'pg';
+
+function createProviderModel(provider, apiKey, model) {
+  switch (provider) {
+    case "openai": {
+      const openai = createOpenAI({ apiKey });
+      return openai(model);
+    }
+    case "google": {
+      const google = createGoogleGenerativeAI({ apiKey });
+      return google(model);
+    }
+    case "anthropic": {
+      const anthropic = createAnthropic({ apiKey });
+      return anthropic(model);
+    }
+    case "xai": {
+      const xai = createXai({ apiKey });
+      return xai(model);
+    }
+    case "openrouter": {
+      const openrouter = createOpenRouter({
+        apiKey
+      });
+      return openrouter(model);
+    }
+    default:
+      throw new Error(`Unsupported provider: ${provider}`);
+  }
+}
+
+const AGENT_COMMAND_OPTIONS = [
+  {
+    id: "generate-query",
+    label: "Generate Query",
+    toolName: "generate_query",
+    category: "SQL",
+    description: "Turn a natural language request into SQL for the active schema.",
+    insertText: "Generate SQL for ",
+    icon: "hugeicons:ai-brain-03",
+    promptHint: "The user wants help drafting SQL from natural language. Prefer generate_query first and keep the response focused on producing or refining SQL."
+  },
+  {
+    id: "render-table",
+    label: "Render Table",
+    toolName: "render_table",
+    category: "Execution",
+    description: "Run a read-only SQL query and show the result rows as a table.",
+    insertText: "Run this query and show the table result for ",
+    icon: "hugeicons:table-01",
+    promptHint: "The user expects concrete table output. After generating or receiving read-only SQL, prefer render_table and summarize the returned rows briefly."
+  },
+  {
+    id: "visualize-table",
+    label: "Visualize Table",
+    toolName: "visualize_table",
+    category: "Charts",
+    description: "Build a bar, line, pie, or scatter chart from a read-only query.",
+    insertText: "Visualize this data as a bar, line, pie, or scatter chart for ",
+    icon: "hugeicons:chart-line-data-01",
+    promptHint: "The user wants a chart-oriented answer. Prefer visualize_table for read-only SQL, and ask for the chart type only if it is still missing."
+  },
+  {
+    id: "describe-table",
+    label: "Describe Table",
+    toolName: "describe_table",
+    category: "Schema",
+    description: "Inspect columns, keys, relationships, and table structure.",
+    insertText: "Describe the structure of table ",
+    icon: "hugeicons:database",
+    promptHint: "The user is asking about schema shape, keys, or relationships. Prefer describe_table when a specific table is involved."
+  },
+  {
+    id: "explain-query",
+    label: "Explain Query",
+    toolName: "explain_query",
+    category: "Performance",
+    description: "Analyze a query plan and explain possible performance issues.",
+    insertText: "Explain why this query is slow: ",
+    icon: "hugeicons:activity-02",
+    promptHint: "The user is focused on query performance. Prefer explain_query once a concrete SQL statement is available."
+  },
+  {
+    id: "detect-anomaly",
+    label: "Detect Anomaly",
+    toolName: "detect_anomaly",
+    category: "Quality",
+    description: "Scan for nulls, duplicates, orphaned keys, and outlier values.",
+    insertText: "Detect anomalies in table ",
+    icon: "hugeicons:search-list-01",
+    promptHint: "The user wants data quality checks. Prefer detect_anomaly for table-level validation and summarize the findings with severity."
+  }
+];
+const getAgentCommandOptionsByIds = (ids) => {
+  const allowedIds = new Set(ids);
+  return AGENT_COMMAND_OPTIONS.filter((option) => allowedIds.has(option.id));
+};
+
+var FunctionSchemaEnum = /* @__PURE__ */ ((FunctionSchemaEnum2) => {
+  FunctionSchemaEnum2["Function"] = "FUNCTION";
+  FunctionSchemaEnum2["Procedure"] = "PROCEDURE";
+  return FunctionSchemaEnum2;
+})(FunctionSchemaEnum || {});
+var ViewSchemaEnum = /* @__PURE__ */ ((ViewSchemaEnum2) => {
+  ViewSchemaEnum2["View"] = "VIEW";
+  ViewSchemaEnum2["MaterializedView"] = "MATERIALIZED_VIEW";
+  return ViewSchemaEnum2;
+})(ViewSchemaEnum || {});
+
+const DEFAULT_RENDER_LIMIT = 100;
+const MAX_RENDER_LIMIT = 500;
+const MAX_EXPORT_LIMIT = 1e5;
+const SELECT_PATTERN = /^(select|with|values|table)\b/i;
+const MUTATION_PATTERN = /^(insert|update|delete|drop|truncate|alter|create|grant|revoke|comment|refresh|vacuum)\b/i;
+const POSTGRES_OID_TYPE_MAP = {
+  16: "bool",
+  20: "int8",
+  21: "int2",
+  23: "int4",
+  25: "text",
+  114: "json",
+  700: "float4",
+  701: "float8",
+  1043: "varchar",
+  1082: "date",
+  1114: "timestamp",
+  1184: "timestamptz",
+  1700: "numeric",
+  2950: "uuid",
+  3802: "jsonb"
+};
+function stripSqlComments(sql) {
+  return sql.replace(/\/\*[\s\S]*?\*\//g, "").replace(/--.*$/gm, "");
+}
+function stripMarkdownCodeFence(sql) {
+  var _a;
+  const trimmed = sql.trim();
+  const match = trimmed.match(/^```(?:sql)?\s*([\s\S]*?)```$/i);
+  return ((_a = match == null ? void 0 : match[1]) == null ? void 0 : _a.trim()) || trimmed;
+}
+function normalizeSql(sql) {
+  return stripSqlComments(stripMarkdownCodeFence(sql)).trim().replace(/;+\s*$/, "");
+}
+function isSelectLikeSql(sql) {
+  return SELECT_PATTERN.test(normalizeSql(sql));
+}
+function isMutationSql(sql) {
+  return MUTATION_PATTERN.test(normalizeSql(sql));
+}
+function clampLimit(limit) {
+  if (!limit || Number.isNaN(limit)) {
+    return DEFAULT_RENDER_LIMIT;
+  }
+  return Math.max(1, Math.min(limit, MAX_RENDER_LIMIT));
+}
+function quoteIdentifier(identifier) {
+  if (!/^[A-Za-z_][A-Za-z0-9_$]*$/.test(identifier)) {
+    throw new Error(`Invalid SQL identifier: ${identifier}`);
+  }
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+function getQualifiedTableName(schemaName, tableName) {
+  return `${quoteIdentifier(schemaName)}.${quoteIdentifier(tableName)}`;
+}
+function resolveFieldType(field) {
+  const oid = Number(field.dataTypeID);
+  return POSTGRES_OID_TYPE_MAP[oid] || String(field.dataTypeID || "unknown");
+}
+
+const NUMERIC_COLUMN_PATTERN = /(smallint|integer|bigint|decimal|numeric|real|double precision|float|serial)/i;
+function findCanonicalTableName(snapshot, requestedTableName) {
+  const trimmed = requestedTableName.trim();
+  if (!snapshot) {
+    return trimmed;
+  }
+  const exactMatch = snapshot.tables.find((name) => name === trimmed);
+  if (exactMatch) {
+    return exactMatch;
+  }
+  const lowerCaseMatch = snapshot.tables.find(
+    (name) => name.toLowerCase() === trimmed.toLowerCase()
+  );
+  if (!lowerCaseMatch) {
+    throw new Error(
+      `Table "${requestedTableName}" does not exist in schema ${snapshot.name}.`
+    );
+  }
+  return lowerCaseMatch;
+}
+function resolveTableDetail(snapshot, requestedTableName) {
+  if (!(snapshot == null ? void 0 : snapshot.tableDetails)) {
+    throw new Error("Schema metadata is not available for this workspace.");
+  }
+  const tableName = findCanonicalTableName(snapshot, requestedTableName);
+  const detail = snapshot.tableDetails[tableName];
+  if (!detail) {
+    throw new Error(`Missing metadata for table "${tableName}".`);
+  }
+  return { tableName, detail };
+}
+function assertDatabaseAdapter(adapter) {
+  if (!adapter) {
+    throw new Error("A database connection is required for this tool.");
+  }
+}
+function buildColumnDescription(columnName) {
+  const normalized = columnName.toLowerCase();
+  if (normalized === "id") {
+    return "Primary identifier for each row.";
+  }
+  if (normalized.endsWith("_id")) {
+    return "Reference to a related record.";
+  }
+  if (normalized.includes("created_at")) {
+    return "Timestamp when the row was created.";
+  }
+  if (normalized.includes("updated_at")) {
+    return "Timestamp when the row was last updated.";
+  }
+  if (normalized.includes("status")) {
+    return "Lifecycle or state marker for the row.";
+  }
+  return void 0;
+}
+function toColumnsForDescribe(detail) {
+  var _a, _b, _c;
+  const primaryKeys = new Set(
+    ((_a = detail.primary_keys) != null ? _a : []).map((key) => key.column)
+  );
+  const foreignKeys = new Map(
+    ((_b = detail.foreign_keys) != null ? _b : []).map((key) => [key.column, key])
+  );
+  return ((_c = detail.columns) != null ? _c : []).map((column) => {
+    const foreignKey = foreignKeys.get(column.name);
+    return {
+      name: column.name,
+      type: column.short_type_name || column.type,
+      isPrimaryKey: primaryKeys.has(column.name),
+      isForeignKey: !!foreignKey,
+      isNullable: column.is_nullable,
+      referencesTable: foreignKey == null ? void 0 : foreignKey.referenced_table,
+      description: buildColumnDescription(column.name)
+    };
+  });
+}
+function buildTableSummary(tableName, columns, relatedTables) {
+  const readableName = tableName.replace(/_/g, " ");
+  const summaryLines = [`Table ${tableName} stores ${readableName} records.`];
+  if (relatedTables.length > 0) {
+    summaryLines.push(
+      `It is directly related to ${relatedTables.slice(0, 4).join(", ")}.`
+    );
+  }
+  const importantColumns = columns.filter((column) => column.isPrimaryKey || column.isForeignKey).map((column) => column.name);
+  if (importantColumns.length > 0) {
+    summaryLines.push(
+      `Key columns include ${importantColumns.slice(0, 4).join(", ")}.`
+    );
+  }
+  return summaryLines.join(" ");
+}
+function getIssueSeverity(ratio) {
+  if (ratio >= 0.2) {
+    return "high";
+  }
+  if (ratio >= 0.05) {
+    return "medium";
+  }
+  return "low";
+}
+function calculateCleanScore(issues) {
+  const score = issues.reduce((currentScore, issue) => {
+    if (issue.severity === "high") {
+      return currentScore - 25;
+    }
+    if (issue.severity === "medium") {
+      return currentScore - 12;
+    }
+    return currentScore - 5;
+  }, 100);
+  return Math.max(0, score);
+}
+function buildDuplicateCandidates(detail) {
+  var _a, _b;
+  const primaryKeys = new Set(
+    ((_a = detail.primary_keys) != null ? _a : []).map((key) => key.column)
+  );
+  return ((_b = detail.columns) != null ? _b : []).filter((column) => {
+    if (primaryKeys.has(column.name) || column.is_nullable) {
+      return false;
+    }
+    const name = column.name.toLowerCase();
+    return name === "email" || name === "slug" || name === "code" || name.endsWith("_code") || name.endsWith("_number");
+  }).slice(0, 3);
+}
+function getNumericColumns(detail) {
+  var _a;
+  return ((_a = detail.columns) != null ? _a : []).filter((column) => NUMERIC_COLUMN_PATTERN.test(column.type)).slice(0, 4);
+}
+function toQuotedColumnName(columnName) {
+  return quoteIdentifier(columnName);
+}
+function serializeSingleSnapshot(schema) {
+  var _a, _b, _c, _d, _e;
+  const { name, tables, tableDetails, views, viewDetails, functions } = schema;
+  const lines = [];
+  const parts = [`${tables.length} tables`];
+  if (views.length) parts.push(`${views.length} views`);
+  if (functions.length) parts.push(`${functions.length} functions`);
+  lines.push(`Schema: ${name} (${parts.join(", ")})`);
+  if (tables.length && tableDetails) {
+    lines.push("");
+    lines.push("  Tables:");
+    for (const tableName of tables) {
+      const detail = tableDetails[tableName];
+      if (!detail) {
+        lines.push(`    - ${name}.${tableName}`);
+        continue;
+      }
+      lines.push("");
+      lines.push(`    Table: ${name}.${tableName}`);
+      if ((_a = detail.columns) == null ? void 0 : _a.length) {
+        const pkSet = new Set(((_b = detail.primary_keys) != null ? _b : []).map((k) => k.column));
+        const fkSet = new Set(((_c = detail.foreign_keys) != null ? _c : []).map((k) => k.column));
+        for (const c of detail.columns) {
+          const flags = [];
+          if (pkSet.has(c.name)) flags.push("PK");
+          if (fkSet.has(c.name)) flags.push("FK");
+          if (!c.is_nullable) flags.push("NOT NULL");
+          const typeName = c.short_type_name || c.type;
+          const flagStr = flags.length ? ` [${flags.join(", ")}]` : "";
+          lines.push(`      - ${c.name}: ${typeName}${flagStr}`);
+        }
+      }
+      if ((_d = detail.foreign_keys) == null ? void 0 : _d.length) {
+        lines.push("      References:");
+        for (const fk of detail.foreign_keys) {
+          lines.push(
+            `        ${tableName}.${fk.column} \u2192 ${fk.referenced_table_schema}.${fk.referenced_table}.${fk.referenced_column}`
+          );
+        }
+      }
+    }
+  }
+  if (views.length) {
+    lines.push("");
+    lines.push("  Views:");
+    for (const view of views) {
+      const typeLabel = view.type === ViewSchemaEnum.MaterializedView ? "MATERIALIZED VIEW" : "VIEW";
+      const detail = viewDetails == null ? void 0 : viewDetails[view.name];
+      if (!((_e = detail == null ? void 0 : detail.columns) == null ? void 0 : _e.length)) {
+        lines.push(`    - ${name}.${view.name} (${typeLabel})`);
+        continue;
+      }
+      lines.push("");
+      lines.push(`    View: ${name}.${view.name} (${typeLabel})`);
+      for (const c of detail.columns) {
+        const typeName = c.short_type_name || c.type;
+        const nullable = c.is_nullable ? "" : " NOT NULL";
+        lines.push(`      - ${c.name}: ${typeName}${nullable}`);
+      }
+    }
+  }
+  if (functions.length) {
+    lines.push("");
+    lines.push("  Functions:");
+    for (const fn of functions) {
+      const typeLabel = fn.type === FunctionSchemaEnum.Procedure ? "PROCEDURE" : "FUNCTION";
+      const params = fn.parameters || "none";
+      lines.push(`    - ${fn.name} (${typeLabel}) params: ${params}`);
+    }
+  }
+  return lines;
+}
+function buildSchemaContext(schemaSnapshot) {
+  const snapshots = !schemaSnapshot ? [] : Array.isArray(schemaSnapshot) ? schemaSnapshot : [schemaSnapshot];
+  if (snapshots.length === 0) {
+    return "No schema context is currently loaded.";
+  }
+  const lines = [];
+  if (snapshots.length > 0) {
+    lines.push(`Available schemas (${snapshots.length}):`);
+    for (const snapshot of snapshots) {
+      lines.push("");
+      lines.push(...serializeSingleSnapshot(snapshot));
+    }
+  }
+  return lines.join("\n");
+}
+
+function buildAgentSystemPrompt(schemaSnapshots, selectedCommandOptions) {
+  const resolvedSchema = buildSchemaContext(schemaSnapshots);
+  const selectedOptions = (selectedCommandOptions == null ? void 0 : selectedCommandOptions.length) ? getAgentCommandOptionsByIds(selectedCommandOptions) : [];
+  const sectionIdentity = [
+    "# You are Orca Agent.",
+    "",
+    "You help users explore schemas, reason about SQL, explain database structures, and suggest safe next steps for the current database.",
+    "You have DIRECT access to a connected database via tools."
+  ].join("\n");
+  const sectionAvailableTools = [
+    "## Available tools",
+    "Use tools whenever they can produce a structured result:",
+    "- `generate_query` \u2014 convert natural language into SQL.",
+    "- `render_table` \u2014 execute SQL and show structured rows.",
+    "- `export_file` \u2014 package structured rows into CSV, JSON, SQL for download.",
+    "- `visualize_table` \u2014 execute read-only SQL and render a bar, line, pie, or scatter chart.",
+    "- `describe_table` \u2014 schema introspection (columns, keys, relationships).",
+    "- `explain_query` \u2014 performance analysis via EXPLAIN.",
+    "- `detect_anomaly` \u2014 data quality scans (nulls, duplicates, orphan FKs, outliers)."
+  ].join("\n");
+  const sectionConnection = [
+    "## Connection",
+    "NEVER ask the user for connection info, credentials, or database details \u2014 the database is already connected."
+  ].join("\n");
+  const sectionReadQueries = [
+    "## READ queries (SELECT)",
+    "For read-only requests, call tools immediately without asking for confirmation.",
+    "Workflow:",
+    "  1. Call generate_query to convert the request to SQL.",
+    "  2. Call render_table to execute the SQL and return results.",
+    "  3. If the user asks to export, save, download, dump, return JSON, or open the result in Excel/Sheets, call `export_file` using the rows returned from `render_table`.",
+    "  4. Summarize the results clearly for the user.",
+    "",
+    "If the user asks for a chart or visualization, call `visualize_table` instead of `render_table` once you have a read-only SQL query.",
+    "If the user asks to visualize data but is missing ANY of the following, call `askClarification` BEFORE calling `visualize_table`:",
+    "  - Chart type not specified \u2192 ask them to pick: bar, line, pie, scatter",
+    "  - The intended metric/measure column is ambiguous (e.g. table has multiple numeric columns)",
+    "  - The intended dimension/label column is ambiguous",
+    "  - The time range or filter condition is unclear for a line/scatter chart",
+    "Only call `visualize_table` once ALL required inputs (sql + chartType) are unambiguous."
+  ].join("\n");
+  const sectionMutationQueries = [
+    "## MUTATION queries (INSERT / UPDATE / DELETE / DROP / TRUNCATE / ALTER)",
+    "NEVER auto-execute mutation SQL. Always follow this workflow:",
+    "  1. Call generate_query to produce the SQL.",
+    "  2. STOP. Show the generated SQL to the user and explain exactly what it will change.",
+    "  3. Explicitly ask the user to confirm before proceeding.",
+    "  4. Only call render_table after the user gives clear approval.",
+    'Even if the user says "just do it" \u2014 still show the SQL and ask once before executing.'
+  ].join("\n");
+  const sectionRules = [
+    "## Rules",
+    "- Stay grounded in the provided schema context.",
+    "- Never invent tables or columns that are not present in the schema context.",
+    "- If schema context is incomplete, say what is missing before making assumptions.",
+    "- After generating a read-only query, prefer calling `render_table` so the user gets concrete results.",
+    "- For destructive or mutating SQL, explain the plan clearly and let the approval flow gate execution.",
+    "- Only call `export_file` for structured row data. Prefer `render_table` first, then export the returned rows.",
+    "- Keep narration concise and let tool blocks carry the detailed output."
+  ].join("\n");
+  const sectionClarification = [
+    "## Clarification tool",
+    "Use `askClarification` when you cannot safely proceed without more information. Concrete triggers:",
+    '  - User wants a visualization but did not specify chart type \u2192 question type: `single`, suggestions: ["bar","line","pie","scatter"]',
+    "  - User wants a visualization but the table has multiple numeric columns and intent is unclear \u2192 question type: `single`, suggestions: list the column names",
+    "  - User request references an entity that maps to multiple tables in the schema \u2192 question type: `single`",
+    '  - User asks to "update/delete something" without specifying a filter condition \u2192 question type: `open`',
+    "  - User asks for a trend/time-series but no date column is obvious \u2192 question type: `single`, suggestions: list candidate date columns",
+    "",
+    "Rules for calling `askClarification`:",
+    "  - Call it at most ONCE per user turn \u2014 batch all open questions into a single call.",
+    "  - Populate `suggestions` with 3\u20135 concrete options whenever the answer set is bounded (column names, chart types, table names).",
+    "  - Use `type: single` when exactly one answer is needed, `multiple` for multi-select, `open` for free text.",
+    "  - Mark `required: true` for questions that block execution; `required: false` for nice-to-have context.",
+    '  - After the conversation contains a "[Quiz answers]" message, NEVER call `askClarification` again \u2014 use the answers and proceed fully.',
+    "  - Do NOT call `askClarification` to confirm read-only queries \u2014 just execute them."
+  ].join("\n");
+  const sectionUserIntent = selectedOptions.length ? [
+    "## Current user intent focus",
+    "The user explicitly selected these tool intents before sending the message:",
+    ...selectedOptions.map((o) => `- ${o.label}: ${o.promptHint}`),
+    "Honor these hints when they fit the request, but do not invent missing information or bypass any approval rule."
+  ].join("\n") : null;
+  const sectionSchema = [
+    "## Database schema (always loaded)",
+    resolvedSchema
+  ].join("\n");
+  return [
+    sectionIdentity,
+    sectionAvailableTools,
+    sectionConnection,
+    sectionReadQueries,
+    sectionMutationQueries,
+    sectionRules,
+    sectionClarification,
+    ...sectionUserIntent ? [sectionUserIntent] : [],
+    sectionSchema
+  ].join("\n\n");
+}
+
+const AgentToolName = {
+  GenerateQuery: "generate_query",
+  RenderTable: "render_table",
+  VisualizeTable: "visualize_table",
+  ExplainQuery: "explain_query",
+  DetectAnomaly: "detect_anomaly",
+  DescribeTable: "describe_table",
+  /** Re-executes SQL on the server and exports rows — no row data in context window */
+  ExportQueryResult: "export_query_result",
+  /** Exports free-form text (notes, scripts, docs) directly to a file */
+  ExportContent: "export_content",
+  AskClarification: "askClarification"
+};
+
+const getPlanString = (node, key) => {
+  const value = node[key];
+  return typeof value === "string" ? value : "";
+};
+const getPlanNumber = (node, key) => {
+  const value = Number(node[key]);
+  return Number.isFinite(value) ? value : 0;
+};
+function formatPlanTree(node, depth = 0) {
+  const indent = "  ".repeat(depth);
+  const relationName = getPlanString(node, "Relation Name");
+  const relationSuffix = relationName ? ` on ${relationName}` : "";
+  const cost = `${getPlanNumber(node, "Startup Cost").toFixed(2)}..${getPlanNumber(node, "Total Cost").toFixed(2)}`;
+  const actualTotalTime = getPlanNumber(node, "Actual Total Time");
+  const actual = actualTotalTime > 0 ? ` actual=${actualTotalTime.toFixed(2)}ms` : "";
+  const currentLine = `${indent}${getPlanString(node, "Node Type")}${relationSuffix} (cost=${cost}${actual})`;
+  const childLines = Array.isArray(node.Plans) ? node.Plans.flatMap((child) => formatPlanTree(child, depth + 1)) : [];
+  return [currentLine, ...childLines];
+}
+function findSlowestPlanNode(node) {
+  const children = Array.isArray(node.Plans) ? node.Plans : [];
+  return children.reduce((slowest, child) => {
+    const nestedSlowest = findSlowestPlanNode(child);
+    const slowestCost = getPlanNumber(slowest, "Actual Total Time") || getPlanNumber(slowest, "Total Cost");
+    const nestedCost = getPlanNumber(nestedSlowest, "Actual Total Time") || getPlanNumber(nestedSlowest, "Total Cost");
+    return nestedCost > slowestCost ? nestedSlowest : slowest;
+  }, node);
+}
+function buildExplainSuggestions(slowestNode) {
+  const suggestions = [];
+  const nodeType = getPlanString(slowestNode, "Node Type");
+  const relationName = getPlanString(slowestNode, "Relation Name").trim();
+  const filter = getPlanString(slowestNode, "Filter").trim();
+  const sortKey = Array.isArray(slowestNode["Sort Key"]) ? slowestNode["Sort Key"].map((value) => String(value)).join(", ") : "";
+  if (nodeType.includes("Seq Scan") && relationName) {
+    suggestions.push(
+      `Consider an index on ${relationName}${filter ? ` for filter ${filter}` : ""}.`
+    );
+  }
+  if (nodeType.includes("Sort") && sortKey) {
+    suggestions.push(`Consider an index that supports ORDER BY ${sortKey}.`);
+  }
+  if (nodeType.includes("Nested Loop") || nodeType.includes("Hash Join")) {
+    suggestions.push(
+      "Review join predicates and ensure join keys are indexed."
+    );
+  }
+  if (suggestions.length === 0) {
+    suggestions.push(
+      "Review the slowest plan node, filter predicates, and row estimates before tuning."
+    );
+  }
+  return suggestions;
+}
+function buildExplainSummary(slowestNode) {
+  const nodeType = getPlanString(slowestNode, "Node Type") || "Plan node";
+  const relationName = getPlanString(slowestNode, "Relation Name").trim();
+  const cost = getPlanNumber(slowestNode, "Actual Total Time") || getPlanNumber(slowestNode, "Total Cost");
+  if (relationName) {
+    return `${nodeType} on ${relationName} is the dominant cost in this plan (${cost.toFixed(2)}).`;
+  }
+  return `${nodeType} is the dominant cost in this plan (${cost.toFixed(2)}).`;
+}
+
+const PREVIEW_LIMIT = 20;
+const MIME_TYPE_BY_FORMAT = {
+  csv: "text/csv;charset=utf-8",
+  json: "application/json;charset=utf-8",
+  sql: "application/sql;charset=utf-8",
+  markdown: "text/markdown;charset=utf-8",
+  txt: "text/plain;charset=utf-8",
+  tsv: "text/tab-separated-values;charset=utf-8",
+  xml: "application/xml;charset=utf-8",
+  yaml: "application/yaml;charset=utf-8",
+  html: "text/html;charset=utf-8"
+};
+const EXTENSION_BY_FORMAT = {
+  csv: "csv",
+  json: "json",
+  sql: "sql",
+  markdown: "md",
+  txt: "txt",
+  tsv: "tsv",
+  xml: "xml",
+  yaml: "yaml",
+  html: "html"
+};
+const SQL_TYPE_PRIORITY = [
+  "boolean",
+  "integer",
+  "numeric",
+  "timestamp",
+  "jsonb"
+];
+function collectColumns(rows) {
+  const columns = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      if (seen.has(key)) continue;
+      seen.add(key);
+      columns.push(key);
+    }
+  }
+  return columns;
+}
+function sanitizeFilename(filename) {
+  return filename.trim().replace(/\.[a-z0-9]+$/i, "").replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "") || "export";
+}
+function withExtension(filename, format) {
+  const safeName = sanitizeFilename(filename);
+  const extension = EXTENSION_BY_FORMAT[format];
+  return safeName.endsWith(`.${extension}`) ? safeName : `${safeName}.${extension}`;
+}
+function toPreview(rows, columns) {
+  return {
+    columns,
+    rows: rows.slice(0, PREVIEW_LIMIT),
+    truncated: rows.length > PREVIEW_LIMIT
+  };
+}
+function escapeSqlIdentifier(identifier) {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+function escapeSqlValue(value) {
+  if (value === null || typeof value === "undefined") {
+    return "NULL";
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? String(value) : "NULL";
+  }
+  if (typeof value === "boolean") {
+    return value ? "TRUE" : "FALSE";
+  }
+  if (value instanceof Date) {
+    return `'${value.toISOString().replace(/'/g, "''")}'`;
+  }
+  if (typeof value === "object") {
+    return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+  }
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+function inferSqlType(values) {
+  let bestType = "text";
+  for (const value of values) {
+    if (value === null || typeof value === "undefined") continue;
+    const inferredType = (() => {
+      if (typeof value === "boolean") return "boolean";
+      if (typeof value === "number") {
+        return Number.isInteger(value) ? "integer" : "numeric";
+      }
+      if (value instanceof Date) return "timestamp";
+      if (typeof value === "object") return "jsonb";
+      if (typeof value === "string") {
+        const parsedDate = Date.parse(value);
+        if (!Number.isNaN(parsedDate) && /[-:TZ]/.test(value)) {
+          return "timestamp";
+        }
+      }
+      return "text";
+    })();
+    if (SQL_TYPE_PRIORITY.indexOf(inferredType) > SQL_TYPE_PRIORITY.indexOf(bestType)) {
+      bestType = inferredType;
+    }
+  }
+  return bestType;
+}
+function toSqlContent(rows, tableName, columns) {
+  const safeTableName = escapeSqlIdentifier(tableName);
+  const createStatement = columns.length ? `CREATE TABLE ${safeTableName} (
+${columns.map((column) => {
+    const values = rows.map((row) => row[column]);
+    return `  ${escapeSqlIdentifier(column)} ${inferSqlType(values)}`;
+  }).join(",\n")}
+);` : `CREATE TABLE ${safeTableName} ();`;
+  const insertStatements = rows.map((row) => {
+    const columnList = columns.map(escapeSqlIdentifier).join(", ");
+    const values = columns.map((column) => escapeSqlValue(row[column])).join(", ");
+    return `INSERT INTO ${safeTableName} (${columnList}) VALUES (${values});`;
+  });
+  return [createStatement, ...insertStatements].join("\n\n");
+}
+function toMarkdownContent(rows, columns) {
+  if (columns.length === 0) return "";
+  const header = `| ${columns.join(" | ")} |`;
+  const separator = `| ${columns.map(() => "---").join(" | ")} |`;
+  const bodyRows = rows.map((row) => {
+    const cells = columns.map((col) => {
+      const value = row[col];
+      if (value === null || value === void 0) return "";
+      if (typeof value === "object") return JSON.stringify(value);
+      return String(value).replace(/\|/g, "\\|");
+    });
+    return `| ${cells.join(" | ")} |`;
+  });
+  return [header, separator, ...bodyRows].join("\n");
+}
+function toTsvContent(rows, columns) {
+  const header = columns.join("	");
+  const bodyRows = rows.map(
+    (row) => columns.map((col) => {
+      const value = row[col];
+      if (value === null || value === void 0) return "";
+      if (typeof value === "object") return JSON.stringify(value);
+      return String(value).replace(/\t/g, " ").replace(/\n/g, " ");
+    }).join("	")
+  );
+  return [header, ...bodyRows].join("\n");
+}
+function toTxtContent(rows, columns) {
+  if (columns.length === 0 || rows.length === 0) return "";
+  const widths = columns.map((col) => {
+    const max = Math.max(
+      col.length,
+      ...rows.map((row) => {
+        const v = row[col];
+        if (v === null || v === void 0) return 0;
+        return String(typeof v === "object" ? JSON.stringify(v) : v).length;
+      })
+    );
+    return Math.min(max, 50);
+  });
+  const pad = (val, width) => val.padEnd(width).slice(0, width);
+  const divider = widths.map((w) => "-".repeat(w)).join("  ");
+  const header = columns.map((col, i) => pad(col, widths[i])).join("  ");
+  const bodyRows = rows.map(
+    (row) => columns.map((col, i) => {
+      const v = row[col];
+      const str = v === null || v === void 0 ? "" : typeof v === "object" ? JSON.stringify(v) : String(v);
+      return pad(str, widths[i]);
+    }).join("  ")
+  );
+  return [header, divider, ...bodyRows].join("\n");
+}
+function escapeXmlValue(value) {
+  if (value === null || value === void 0) return "";
+  const str = typeof value === "object" ? JSON.stringify(value) : String(value);
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function toXmlContent(rows, columns, tableName) {
+  const tagName = tableName.replace(/[^a-zA-Z0-9_]/g, "_") || "row";
+  const items = rows.map((row) => {
+    const fields = columns.map((col) => {
+      const safeCol = col.replace(/[^a-zA-Z0-9_]/g, "_") || "_col";
+      return `    <${safeCol}>${escapeXmlValue(row[col])}</${safeCol}>`;
+    });
+    return `  <${tagName}>
+${fields.join("\n")}
+  </${tagName}>`;
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<data>
+${items.join("\n")}
+</data>`;
+}
+function yamlScalar(value, indent) {
+  if (value === null || value === void 0) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return String(value);
+  if (typeof value === "object") {
+    if (Array.isArray(value)) {
+      const items = value.map((item) => `${indent}  - ${yamlScalar(item, `${indent}  `)}`).join("\n");
+      return `
+${items}`;
+    }
+    const obj = value;
+    const entries = Object.entries(obj).map(([k, v]) => `${indent}  ${k}: ${yamlScalar(v, `${indent}  `)}`).join("\n");
+    return `
+${entries}`;
+  }
+  const str = String(value);
+  if (/[:#\[\]{}&*!|>'"%@`\n]/.test(str) || str.trim() !== str) {
+    return `"${str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`;
+  }
+  return str;
+}
+function toYamlContent(rows, columns) {
+  const items = rows.map((row) => {
+    const fields = columns.map((col, i) => {
+      const prefix = i === 0 ? "- " : "  ";
+      return `${prefix}${col}: ${yamlScalar(row[col], "  ")}`;
+    });
+    return fields.join("\n");
+  });
+  return items.join("\n") + "\n";
+}
+function toHtmlContent(rows, columns, tableName) {
+  const escapeHtml = (v) => {
+    const str = v === null || v === void 0 ? "" : typeof v === "object" ? JSON.stringify(v) : String(v);
+    return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  };
+  const thead = `<thead>
+    <tr>
+${columns.map((c) => `      <th>${escapeHtml(c)}</th>`).join("\n")}
+    </tr>
+  </thead>`;
+  const tbody = `<tbody>
+${rows.map(
+    (row) => `    <tr>
+${columns.map((col) => `      <td>${escapeHtml(row[col])}</td>`).join("\n")}
+    </tr>`
+  ).join("\n")}
+  </tbody>`;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${tableName}</title>
+  <style>
+    body { font-family: sans-serif; padding: 1rem; }
+    table { border-collapse: collapse; width: 100%; }
+    th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
+    th { background: #f4f4f4; font-weight: 600; }
+    tr:nth-child(even) { background: #fafafa; }
+  </style>
+</head>
+<body>
+  <h2>${tableName}</h2>
+  <table>
+  ${thead}
+  ${tbody}
+  </table>
+</body>
+</html>`;
+}
+function buildExportFileResult({
+  data,
+  content: rawContent,
+  filename,
+  format,
+  tableName
+}) {
+  const resolvedBaseName = filename || tableName || "export";
+  const resolvedFilename = withExtension(resolvedBaseName, format);
+  if (rawContent !== void 0) {
+    const text = rawContent;
+    const preview2 = {
+      columns: [],
+      rows: [],
+      truncated: false
+    };
+    return {
+      filename: resolvedFilename,
+      mimeType: MIME_TYPE_BY_FORMAT[format],
+      content: text,
+      format,
+      encoding: "utf8",
+      fileSize: Buffer.byteLength(text, "utf8"),
+      preview: preview2
+    };
+  }
+  const rows = Array.isArray(data) ? data : [];
+  const columns = collectColumns(rows);
+  if (rows.length === 0) {
+    return {
+      filename: resolvedFilename,
+      mimeType: MIME_TYPE_BY_FORMAT[format],
+      content: "",
+      format,
+      encoding: "utf8",
+      fileSize: 0,
+      preview: toPreview([], columns),
+      error: "No rows available to export."
+    };
+  }
+  const preview = toPreview(rows, columns);
+  let content;
+  switch (format) {
+    case "csv":
+      content = Papa.unparse(rows);
+      break;
+    case "json":
+      content = JSON.stringify(rows, null, 2);
+      break;
+    case "sql":
+      content = toSqlContent(rows, tableName || "export_data", columns);
+      break;
+    case "markdown":
+      content = toMarkdownContent(rows, columns);
+      break;
+    case "txt":
+      content = toTxtContent(rows, columns);
+      break;
+    case "tsv":
+      content = toTsvContent(rows, columns);
+      break;
+    case "xml":
+      content = toXmlContent(rows, columns, tableName || "export_data");
+      break;
+    case "yaml":
+      content = toYamlContent(rows, columns);
+      break;
+    case "html":
+      content = toHtmlContent(rows, columns, tableName || "export_data");
+      break;
+    default:
+      content = Papa.unparse(rows);
+  }
+  return {
+    filename: resolvedFilename,
+    mimeType: MIME_TYPE_BY_FORMAT[format],
+    content,
+    format,
+    encoding: "utf8",
+    fileSize: Buffer.byteLength(content, "utf8"),
+    preview
+  };
+}
+
+function rowsToRecords(rows, fields = []) {
+  return rows.map((row) => {
+    if (Array.isArray(row)) {
+      return row.reduce((record, value, index) => {
+        var _a;
+        const name = ((_a = fields[index]) == null ? void 0 : _a.name) || `column_${index + 1}`;
+        record[name] = value;
+        return record;
+      }, {});
+    }
+    return row || {};
+  });
+}
+function getCountFromRows(rows) {
+  const firstRow = rows[0];
+  if (!firstRow) {
+    return 0;
+  }
+  const countValue = Object.values(firstRow)[0];
+  const parsed = Number(countValue);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+const toFiniteNumber = (value) => {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+};
+const isNumericColumn = (rows, key) => rows.some((row) => toFiniteNumber(row[key]) !== null);
+const inferLabelField = (rows, keys) => keys.find((key) => !isNumericColumn(rows, key)) || keys[0] || null;
+const buildSeriesPoints = (rows, labelField, valueField) => {
+  const points = [];
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index];
+    const value = toFiniteNumber(row[valueField]);
+    if (value === null) {
+      continue;
+    }
+    const rawLabel = row[labelField];
+    const label = rawLabel === null || typeof rawLabel === "undefined" || rawLabel === "" ? `Row ${index + 1}` : String(rawLabel);
+    points.push({
+      label,
+      x: label,
+      y: value
+    });
+  }
+  return points;
+};
+const buildScatterPoints = (rows, xField, yField, labelField) => {
+  const points = [];
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index];
+    const xValue = toFiniteNumber(row[xField]);
+    const yValue = toFiniteNumber(row[yField]);
+    if (xValue === null || yValue === null) {
+      continue;
+    }
+    const rawLabel = labelField ? row[labelField] : null;
+    const label = rawLabel === null || typeof rawLabel === "undefined" || rawLabel === "" ? `Point ${index + 1}` : String(rawLabel);
+    points.push({
+      label,
+      x: xValue,
+      y: yValue
+    });
+  }
+  return points;
+};
+async function visualizeTableResult(adapter, sql, chartType) {
+  const normalizedSql = normalizeSql(sql);
+  if (!normalizedSql) {
+    throw new Error("SQL is required.");
+  }
+  if (!isSelectLikeSql(normalizedSql)) {
+    throw new Error("Only read-only SELECT queries can be visualized.");
+  }
+  const safeLimit = Math.min(MAX_RENDER_LIMIT, 50);
+  const wrappedSql = `SELECT * FROM (${normalizedSql}) AS agent_chart_result LIMIT ${safeLimit + 1}`;
+  const result = await adapter.rawOut(wrappedSql);
+  const rows = rowsToRecords(result.rows || [], result.fields || []);
+  const truncated = rows.length > safeLimit;
+  const visibleRows = truncated ? rows.slice(0, safeLimit) : rows;
+  const keys = (result.fields || []).map((field) => field.name || "unknown");
+  if (visibleRows.length === 0 || keys.length === 0) {
+    throw new Error(
+      "No rows returned. Try a query with grouped or measurable data."
+    );
+  }
+  if (chartType === "scatter") {
+    const numericKeys = keys.filter((key) => isNumericColumn(visibleRows, key));
+    if (numericKeys.length < 2) {
+      throw new Error("Scatter charts require at least two numeric columns.");
+    }
+    const xField = numericKeys[0];
+    const yField = numericKeys[1];
+    const labelField2 = inferLabelField(
+      visibleRows,
+      keys.filter((key) => key !== xField && key !== yField)
+    );
+    const points2 = buildScatterPoints(visibleRows, xField, yField, labelField2);
+    if (points2.length === 0) {
+      throw new Error(
+        "Could not build scatter chart points from the query result."
+      );
+    }
+    return {
+      sql: normalizedSql,
+      chartType,
+      xField,
+      yField,
+      labelField: labelField2 || void 0,
+      points: points2,
+      rowCount: points2.length,
+      truncated
+    };
+  }
+  const labelField = inferLabelField(visibleRows, keys);
+  if (!labelField) {
+    throw new Error("Could not infer a label column for the chart.");
+  }
+  const valueField = keys.find(
+    (key) => key !== labelField && isNumericColumn(visibleRows, key)
+  );
+  if (!valueField) {
+    throw new Error(
+      "This chart needs at least one numeric column in the result."
+    );
+  }
+  const points = buildSeriesPoints(visibleRows, labelField, valueField);
+  if (points.length === 0) {
+    throw new Error("Could not build chart points from the query result.");
+  }
+  return {
+    sql: normalizedSql,
+    chartType,
+    xField: labelField,
+    yField: valueField,
+    labelField,
+    points,
+    rowCount: points.length,
+    truncated
+  };
+}
+async function renderTableResult(adapter, sql, limit) {
+  const normalizedSql = normalizeSql(sql);
+  if (!normalizedSql) {
+    throw new Error("SQL is required.");
+  }
+  if (!isSelectLikeSql(normalizedSql)) {
+    const mutationResult = await adapter.rawOut(
+      normalizedSql
+    );
+    return {
+      sql: normalizedSql,
+      columns: [
+        { name: "operation", type: "text" },
+        { name: "affected_rows", type: "integer" }
+      ],
+      rows: [
+        {
+          operation: mutationResult.command || "MUTATION",
+          affected_rows: mutationResult.rowCount || 0
+        }
+      ],
+      rowCount: 1,
+      truncated: false
+    };
+  }
+  const safeLimit = clampLimit(limit);
+  const wrappedSql = `SELECT * FROM (${normalizedSql}) AS agent_result LIMIT ${safeLimit + 1}`;
+  const result = await adapter.rawOut(wrappedSql);
+  const rows = rowsToRecords(result.rows || [], result.fields || []);
+  const truncated = rows.length > safeLimit;
+  const visibleRows = truncated ? rows.slice(0, safeLimit) : rows;
+  return {
+    sql: normalizedSql,
+    columns: (result.fields || []).map((field) => ({
+      name: field.name || "unknown",
+      type: resolveFieldType(field)
+    })),
+    rows: visibleRows,
+    rowCount: visibleRows.length,
+    truncated
+  };
+}
+
+function findSnapshotForTable(schemaSnapshots, schemaName) {
+  if (!(schemaSnapshots == null ? void 0 : schemaSnapshots.length)) return void 0;
+  const snapshot = schemaSnapshots.find(
+    (s) => s.name.toLowerCase() === schemaName.toLowerCase()
+  ) || schemaSnapshots[0];
+  return snapshot;
+}
+function resolveActiveTools(adapter, schemaSnapshots) {
+  const hasSnapshot = !!(schemaSnapshots == null ? void 0 : schemaSnapshots.length);
+  if (adapter) {
+    return [
+      AgentToolName.GenerateQuery,
+      AgentToolName.RenderTable,
+      AgentToolName.ExportQueryResult,
+      AgentToolName.ExportContent,
+      AgentToolName.VisualizeTable,
+      AgentToolName.ExplainQuery,
+      ...hasSnapshot ? [AgentToolName.DetectAnomaly, AgentToolName.DescribeTable] : [],
+      AgentToolName.AskClarification
+    ];
+  }
+  return hasSnapshot ? [
+    AgentToolName.GenerateQuery,
+    AgentToolName.DescribeTable,
+    AgentToolName.ExportContent,
+    AgentToolName.AskClarification
+  ] : [
+    AgentToolName.GenerateQuery,
+    AgentToolName.ExportContent,
+    AgentToolName.AskClarification
+  ];
+}
+function createDbAgentTools({
+  model,
+  adapter,
+  dialect,
+  schemaSnapshots
+}) {
+  const resolvedSchemaContext = buildSchemaContext(schemaSnapshots);
+  return {
+    generate_query: tool({
+      description: "Convert a natural language request into SQL for the active database schema. Always call this first before render_table.",
+      inputSchema: z.object({
+        prompt: z.string().min(1),
+        // schema override per-call nếu agent muốn pass schema cụ thể
+        schema: z.string().optional(),
+        dialect: z.enum(["postgresql", "mysql", "sqlite"]).default("postgresql")
+      }),
+      execute: async (input) => {
+        const result = await generateText({
+          model,
+          system: [
+            `You convert user requests into ${input.dialect || dialect || "postgresql"} SQL.`,
+            "Return a single SQL statement only.",
+            "Default to SELECT queries. Only generate mutation SQL (INSERT/UPDATE/DELETE/DROP/TRUNCATE/ALTER) when the user EXPLICITLY and clearly requests a data change.",
+            "If the intent is ambiguous, generate a SELECT instead.",
+            "Never reference tables or columns outside the provided schema context.",
+            "Set isMutation: true for ANY statement that modifies data or schema."
+          ].join("\n"),
+          prompt: [
+            // input.schema (per-call override) → full snapshot context → fallback
+            `Schema:
+${input.schema || resolvedSchemaContext}`,
+            `User request: ${input.prompt}`
+          ].join("\n\n"),
+          output: Output.object({
+            schema: z.object({
+              sql: z.string().describe("A single valid SQL statement."),
+              isMutation: z.boolean().describe(
+                "True if the SQL modifies data (INSERT/UPDATE/DELETE/DROP etc)."
+              ),
+              explanation: z.string().describe(
+                "A short plain-English explanation of what the query does."
+              )
+            })
+          })
+        });
+        const parsed = result.output;
+        const sql = normalizeSql(parsed.sql);
+        const isMutation = parsed.isMutation || isMutationSql(sql);
+        return {
+          sql,
+          isMutation,
+          explanation: parsed.explanation
+        };
+      }
+    }),
+    render_table: tool({
+      description: "Execute SQL and return results. For SELECT queries, call immediately after generate_query. For mutation SQL (INSERT/UPDATE/DELETE/DROP/TRUNCATE/ALTER), this tool requires explicit user approval \u2014 NEVER call it with mutation SQL unless the user has confirmed after seeing the SQL.",
+      inputSchema: z.object({
+        sql: z.string().min(1),
+        limit: z.number().int().min(1).max(MAX_RENDER_LIMIT).default(100)
+      }),
+      needsApproval: (input) => isMutationSql(input.sql),
+      execute: async (input) => {
+        assertDatabaseAdapter(adapter);
+        return renderTableResult(adapter, input.sql, input.limit);
+      }
+    }),
+    visualize_table: tool({
+      description: "Execute a read-only SQL query and render a chart. Use this when the user wants a visualization and has chosen one of these chart types: bar, line, pie, or scatter. Ask the user to choose a chart type before calling this tool if they did not specify one.",
+      inputSchema: z.object({
+        sql: z.string().min(1),
+        chartType: z.enum(["bar", "line", "pie", "scatter"])
+      }),
+      execute: async (input) => {
+        assertDatabaseAdapter(adapter);
+        const result = await visualizeTableResult(
+          adapter,
+          input.sql,
+          input.chartType
+        );
+        return result;
+      }
+    }),
+    //TODO: need to enhance this not stable
+    export_query_result: tool({
+      description: [
+        "Re-execute a SQL SELECT query and export the result rows to a downloadable file.",
+        "IMPORTANT: Pass only the `sql` string \u2014 do NOT pass row data from render_table.",
+        "The tool fetches rows fresh from the database, so context window stays small.",
+        "Use this after generate_query when the user asks to download/export query results.",
+        "",
+        "Supported formats:",
+        "  csv \u2014 spreadsheet (Excel, Google Sheets)",
+        "  tsv \u2014 tab-separated (also Excel-compatible)",
+        "  json \u2014 JSON array",
+        "  sql \u2014 INSERT statements for re-importing",
+        "  xml \u2014 XML document"
+      ].join("\n"),
+      inputSchema: z.object({
+        sql: z.string().min(1).describe("The SQL SELECT query to execute and export."),
+        format: z.enum(["csv", "tsv", "json", "sql", "xml"]),
+        filename: z.string().min(1).optional(),
+        limit: z.number().int().min(1).max(MAX_EXPORT_LIMIT).default(MAX_EXPORT_LIMIT).describe("Max rows to export. Defaults to 100 000.")
+      }),
+      needsApproval: (input) => isMutationSql(input.sql),
+      execute: async (input) => {
+        assertDatabaseAdapter(adapter);
+        const sql = normalizeSql(input.sql);
+        const result = await adapter.rawOut(sql);
+        const rows = rowsToRecords(result.rows || [], result.fields || []);
+        const limited = rows.slice(0, input.limit);
+        return buildExportFileResult({
+          data: limited,
+          filename: input.filename,
+          format: input.format
+        });
+      }
+    }),
+    export_content: tool({
+      description: [
+        "Export any free-form text content to a downloadable file.",
+        "Use this when the user wants to save something that is NOT a table result:",
+        "  - Chat knowledge, analysis summaries, or reports \u2192 format: markdown",
+        "  - A SQL query or migration script \u2192 format: sql or txt",
+        "  - Plain notes or output \u2192 format: txt",
+        "  - Hand-crafted YAML config \u2192 format: yaml",
+        "  - An HTML page \u2192 format: html",
+        "The `content` string is written as-is \u2014 no parsing or transformation is applied."
+      ].join("\n"),
+      inputSchema: z.object({
+        content: z.string().min(1).describe("The raw text to write into the file."),
+        format: z.enum([
+          "markdown",
+          "txt",
+          "sql",
+          "json",
+          "yaml",
+          "html",
+          "xml",
+          "csv",
+          "tsv"
+        ]),
+        filename: z.string().min(1).optional()
+      }),
+      execute: async (input) => {
+        return buildExportFileResult({
+          content: input.content,
+          filename: input.filename,
+          format: input.format
+        });
+      }
+    }),
+    explain_query: tool({
+      description: "Run EXPLAIN on a query and return a readable summary of the execution plan. Use this when the user asks about query performance, slow queries, or indexes.",
+      inputSchema: z.object({
+        sql: z.string().min(1)
+      }),
+      execute: async (input) => {
+        var _a;
+        assertDatabaseAdapter(adapter);
+        const normalizedSql = normalizeSql(input.sql);
+        const explainPrefix = isMutationSql(normalizedSql) ? "EXPLAIN (FORMAT JSON)" : "EXPLAIN (ANALYZE, FORMAT JSON)";
+        const result = await adapter.rawOut(
+          `${explainPrefix} ${normalizedSql}`
+        );
+        const rows = rowsToRecords(result.rows || [], result.fields || []);
+        const planValue = (_a = rows[0]) == null ? void 0 : _a["QUERY PLAN"];
+        const planJson = Array.isArray(planValue) ? planValue[0] : planValue;
+        const rootPlan = planJson == null ? void 0 : planJson.Plan;
+        if (!rootPlan) {
+          throw new Error("Could not parse the EXPLAIN plan.");
+        }
+        const slowestNode = findSlowestPlanNode(rootPlan);
+        const rawPlan = formatPlanTree(rootPlan).join("\n");
+        return {
+          rawPlan,
+          summary: buildExplainSummary(slowestNode),
+          slowestNode: String(slowestNode["Node Type"] || "Unknown"),
+          estimatedCost: Number(rootPlan["Total Cost"] || 0),
+          suggestions: buildExplainSuggestions(slowestNode)
+        };
+      }
+    }),
+    detect_anomaly: tool({
+      description: "Scan a table for data quality issues: nulls, duplicate identifiers, orphan foreign keys, and numeric outliers. Use when the user asks about data quality or cleanliness.",
+      inputSchema: z.object({
+        tableName: z.string().min(1),
+        schemaName: z.string().min(1),
+        checks: z.array(z.enum(["nulls", "duplicates", "orphan_fk", "outliers"])).default(["nulls", "duplicates", "orphan_fk"])
+      }),
+      execute: async (input) => {
+        var _a;
+        assertDatabaseAdapter(adapter);
+        const snapshot = findSnapshotForTable(
+          schemaSnapshots,
+          input.schemaName
+        );
+        const { tableName, detail } = resolveTableDetail(
+          snapshot,
+          input.tableName
+        );
+        const qualifiedTable = getQualifiedTableName(
+          (snapshot == null ? void 0 : snapshot.name) || "public",
+          tableName
+        );
+        const issues = [];
+        const countResult = await adapter.rawOut(
+          `SELECT COUNT(*)::int AS total FROM ${qualifiedTable}`
+        );
+        const totalRows = getCountFromRows(
+          rowsToRecords(countResult.rows || [], countResult.fields || [])
+        );
+        if (input.checks.includes("nulls") && totalRows > 0) {
+          const nullableCandidates = detail.columns.filter((column) => column.is_nullable).slice(0, 8);
+          for (const column of nullableCandidates) {
+            const result = await adapter.rawOut(
+              `SELECT COUNT(*)::int AS count FROM ${qualifiedTable} WHERE ${toQuotedColumnName(column.name)} IS NULL`
+            );
+            const nullCount = getCountFromRows(
+              rowsToRecords(result.rows || [], result.fields || [])
+            );
+            if (nullCount <= 0) continue;
+            const ratio = totalRows === 0 ? 0 : nullCount / totalRows;
+            issues.push({
+              type: "nulls",
+              severity: getIssueSeverity(ratio),
+              column: column.name,
+              description: `${column.name} has ${nullCount} NULL values (${(ratio * 100).toFixed(1)}% of scanned rows).`,
+              fixSql: `UPDATE ${qualifiedTable} SET ${toQuotedColumnName(column.name)} = /* default value */ WHERE ${toQuotedColumnName(column.name)} IS NULL;`
+            });
+          }
+        }
+        if (input.checks.includes("duplicates") && totalRows > 0) {
+          for (const column of buildDuplicateCandidates(detail)) {
+            const result = await adapter.rawOut(
+              `SELECT COUNT(*)::int AS duplicate_groups FROM (
+                SELECT ${toQuotedColumnName(column.name)}
+                FROM ${qualifiedTable}
+                WHERE ${toQuotedColumnName(column.name)} IS NOT NULL
+                GROUP BY ${toQuotedColumnName(column.name)}
+                HAVING COUNT(*) > 1
+              ) duplicate_values`
+            );
+            const duplicateGroups = getCountFromRows(
+              rowsToRecords(result.rows || [], result.fields || [])
+            );
+            if (duplicateGroups <= 0) continue;
+            issues.push({
+              type: "duplicates",
+              severity: duplicateGroups > 10 ? "high" : "medium",
+              column: column.name,
+              description: `${duplicateGroups} duplicate value groups were found in ${column.name}.`,
+              fixSql: `SELECT ${toQuotedColumnName(column.name)}, COUNT(*) FROM ${qualifiedTable} GROUP BY ${toQuotedColumnName(column.name)} HAVING COUNT(*) > 1;`
+            });
+          }
+        }
+        if (input.checks.includes("orphan_fk") && totalRows > 0) {
+          for (const foreignKey of (_a = detail.foreign_keys) != null ? _a : []) {
+            const referencedTable = getQualifiedTableName(
+              foreignKey.referenced_table_schema,
+              foreignKey.referenced_table
+            );
+            const result = await adapter.rawOut(
+              `SELECT COUNT(*)::int AS count
+               FROM ${qualifiedTable} source
+               LEFT JOIN ${referencedTable} target
+                 ON source.${toQuotedColumnName(foreignKey.column)} = target.${toQuotedColumnName(foreignKey.referenced_column)}
+               WHERE source.${toQuotedColumnName(foreignKey.column)} IS NOT NULL
+                 AND target.${toQuotedColumnName(foreignKey.referenced_column)} IS NULL`
+            );
+            const orphanCount = getCountFromRows(
+              rowsToRecords(result.rows || [], result.fields || [])
+            );
+            if (orphanCount <= 0) continue;
+            const ratio = totalRows === 0 ? 0 : orphanCount / totalRows;
+            issues.push({
+              type: "orphan_fk",
+              severity: getIssueSeverity(ratio),
+              column: foreignKey.column,
+              description: `${orphanCount} rows in ${tableName}.${foreignKey.column} reference missing ${foreignKey.referenced_table}.${foreignKey.referenced_column} rows.`,
+              fixSql: `DELETE FROM ${qualifiedTable} WHERE ${toQuotedColumnName(foreignKey.column)} IS NOT NULL AND ${toQuotedColumnName(foreignKey.column)} NOT IN (SELECT ${toQuotedColumnName(foreignKey.referenced_column)} FROM ${referencedTable});`
+            });
+          }
+        }
+        if (input.checks.includes("outliers") && totalRows > 0) {
+          for (const column of getNumericColumns(detail)) {
+            const result = await adapter.rawOut(
+              `WITH stats AS (
+                 SELECT
+                   percentile_cont(0.25) WITHIN GROUP (ORDER BY ${toQuotedColumnName(column.name)}) AS q1,
+                   percentile_cont(0.75) WITHIN GROUP (ORDER BY ${toQuotedColumnName(column.name)}) AS q3
+                 FROM ${qualifiedTable}
+                 WHERE ${toQuotedColumnName(column.name)} IS NOT NULL
+               )
+               SELECT COUNT(*)::int AS count
+               FROM ${qualifiedTable}, stats
+               WHERE ${toQuotedColumnName(column.name)} IS NOT NULL
+                 AND (
+                   ${toQuotedColumnName(column.name)} < q1 - 1.5 * (q3 - q1)
+                   OR ${toQuotedColumnName(column.name)} > q3 + 1.5 * (q3 - q1)
+                 )`
+            );
+            const outlierCount = getCountFromRows(
+              rowsToRecords(result.rows || [], result.fields || [])
+            );
+            if (outlierCount <= 0) continue;
+            const ratio = totalRows === 0 ? 0 : outlierCount / totalRows;
+            issues.push({
+              type: "outliers",
+              severity: getIssueSeverity(ratio),
+              column: column.name,
+              description: `${outlierCount} potential outliers were found in ${column.name}.`,
+              fixSql: `SELECT * FROM ${qualifiedTable} ORDER BY ${toQuotedColumnName(column.name)} DESC LIMIT 20;`
+            });
+          }
+        }
+        return {
+          issues,
+          scannedRows: totalRows,
+          cleanScore: calculateCleanScore(issues)
+        };
+      }
+    }),
+    describe_table: tool({
+      description: "Summarize a table, its columns, and its direct relationships using schema metadata. Use this when the user asks about table structure, columns, or relationships.",
+      inputSchema: z.object({
+        tableName: z.string().min(1),
+        schemaName: z.string().min(1)
+      }),
+      execute: async (input) => {
+        var _a;
+        const snapshot = findSnapshotForTable(
+          schemaSnapshots,
+          input.schemaName
+        );
+        const { tableName, detail } = resolveTableDetail(
+          snapshot,
+          input.tableName
+        );
+        const columns = toColumnsForDescribe(detail);
+        const relatedTables = Array.from(
+          new Set(((_a = detail.foreign_keys) != null ? _a : []).map((key) => key.referenced_table))
+        );
+        return {
+          tableName,
+          summary: buildTableSummary(tableName, columns, relatedTables),
+          columns,
+          relatedTables
+        };
+      }
+    }),
+    askClarification: tool({
+      description: 'Ask the user clarifying questions when their request is genuinely ambiguous. Call this tool at most ONCE per user message. Never call it again after the conversation contains a "[Quiz answers]" message.',
+      inputSchema: z.object({
+        context: z.string().describe("One sentence explaining why clarification is needed."),
+        questions: z.array(
+          z.object({
+            id: z.string().describe('Short camelCase identifier, e.g. "lang"'),
+            question: z.string(),
+            type: z.enum(["single", "multiple", "open"]),
+            suggestions: z.array(z.string()).min(0).max(5).describe("3\u20135 suggestion chips shown to the user"),
+            required: z.boolean()
+          })
+        ).min(1).max(5)
+      }),
+      execute: async () => ({ acknowledged: true })
+    })
+  };
+}
+
+function resolveDialect(body) {
+  if (body.dialect) {
+    return body.dialect;
+  }
+  if (body.dbType === DatabaseClientType.MYSQL) {
+    return "mysql";
+  }
+  return "postgresql";
+}
+function resolveDatabaseClientType(body) {
+  if (body.dbType === DatabaseClientType.MYSQL) {
+    return DatabaseClientType.MYSQL;
+  }
+  return DatabaseClientType.POSTGRES;
+}
+function resolveSchemaSnapshots(body) {
+  var _a;
+  if ((_a = body.schemaSnapshots) == null ? void 0 : _a.length) {
+    return body.schemaSnapshots;
+  }
+  if (body.schemaSnapshot) {
+    return [body.schemaSnapshot];
+  }
+  return void 0;
+}
+const agent = defineEventHandler(async (event) => {
+  const body = await readBody(event);
+  const {
+    provider,
+    model,
+    apiKey,
+    messages,
+    dbConnectionString,
+    selectedCommandOptions,
+    sendReasoning
+  } = body;
+  const dialect = resolveDialect(body);
+  const schemaSnapshots = resolveSchemaSnapshots(body);
+  if (!apiKey) {
+    throw createError({ statusCode: 400, message: "API key is required" });
+  }
+  if (!provider || !model) {
+    throw createError({
+      statusCode: 400,
+      message: "Provider and model are required"
+    });
+  }
+  try {
+    const providerModel = createProviderModel(
+      provider,
+      apiKey,
+      model
+    );
+    const adapter = dbConnectionString ? await getDatabaseSource({
+      dbConnectionString,
+      type: resolveDatabaseClientType(body)
+    }) : null;
+    const tools = createDbAgentTools({
+      model: providerModel,
+      adapter,
+      dialect,
+      schemaSnapshots
+    });
+    const agent = new ToolLoopAgent({
+      model: providerModel,
+      instructions: buildAgentSystemPrompt(
+        schemaSnapshots,
+        selectedCommandOptions
+      ),
+      tools,
+      stopWhen: ({ steps }) => steps.some(
+        (s) => {
+          var _a;
+          return (_a = s.toolCalls) == null ? void 0 : _a.some(
+            (tc) => tc.toolName === "askClarification"
+          );
+        }
+      ) || stepCountIs(5)({ steps }),
+      activeTools: resolveActiveTools(adapter, schemaSnapshots)
+    });
+    return await createAgentUIStreamResponse({
+      agent,
+      uiMessages: messages || [],
+      sendReasoning: sendReasoning != null ? sendReasoning : true,
+      experimental_transform: smoothStream(),
+      sendSources: true
+    });
+  } catch (error) {
+    console.error("DB Agent API Error:", error);
+    throw createError({
+      statusCode: 500,
+      message: error instanceof Error ? error.message : "Failed to process DB agent request"
+    });
+  }
+});
+
+export { agent as default };
+//# sourceMappingURL=agent.mjs.map