@deepagents/text2sql 0.38.1 → 1.0.0

package/dist/index.js

@@ -163,6 +163,17 @@ function relationship(input) {
 }
 
 // packages/text2sql/src/lib/adapters/groundings/context.ts
+var noopProgress = () => {
+};
+function timestampProgress(onProgress) {
+  if (!onProgress) return noopProgress;
+  return (progress) => {
+    onProgress({
+      ...progress,
+      timestampMs: progress.timestampMs ?? Date.now()
+    });
+  };
+}
 function createGroundingContext(options = {}) {
   return {
     tables: [],
@@ -170,7 +181,7 @@ function createGroundingContext(options = {}) {
     relationships: [],
     info: void 0,
     cache: /* @__PURE__ */ new Map(),
-    onProgress: options.onProgress
+    onProgress: timestampProgress(options.onProgress)
   };
 }
 
@@ -317,7 +328,7 @@ var Adapter = class {
     for (const fn of this.grounding) {
       const grounding = fn(this);
       if (grounding.phase) {
-        ctx.onProgress?.({
+        ctx.onProgress({
           type: "phase:start",
           phase: grounding.phase,
           message: `Starting ${grounding.name} introspection...`
@@ -327,7 +338,7 @@ var Adapter = class {
         await grounding.execute(ctx);
       } finally {
         if (grounding.phase) {
-          ctx.onProgress?.({
+          ctx.onProgress({
             type: "phase:end",
             phase: grounding.phase,
             message: `Finished ${grounding.name} introspection.`
@@ -735,1748 +746,1074 @@ function getTablesWithRelated(allTables, relationships, filter) {
   return Array.from(result);
 }
 
-// packages/text2sql/src/lib/agents/sql-command.ts
-import { v7 } from "uuid";
+// packages/text2sql/src/lib/agents/sql.agent.ts
+import { groq } from "@ai-sdk/groq";
 import {
-  buildSubcommandRepair,
-  defineSubcommandGroup,
-  repairQuotedArg,
-  useBashMeta
+  APICallError,
+  JSONParseError,
+  NoContentGeneratedError,
+  NoObjectGeneratedError,
+  NoOutputGeneratedError,
+  TypeValidationError,
+  defaultSettingsMiddleware,
+  wrapLanguageModel
+} from "ai";
+import dedent from "dedent";
+import pRetry from "p-retry";
+import z from "zod";
+import "@deepagents/agent";
+import {
+  ContextEngine,
+  InMemoryContextStore,
+  example,
+  fragment,
+  guardrail,
+  hint,
+  persona,
+  policy,
+  structuredOutput,
+  user,
+  workflow
 } from "@deepagents/context";
-var SQL_VALIDATE_REMINDER = 'Always run `sql validate <db> "..."` before `sql run <db> "..."` to catch syntax errors early.';
-function repairDbNameAndQuotedArg(rawArgs) {
-  const trimmed = rawArgs.trim();
-  if (!trimmed) return null;
-  const firstSpace = trimmed.search(/\s/);
-  if (firstSpace === -1) return null;
-  const dbName = trimmed.slice(0, firstSpace);
-  const rest = trimmed.slice(firstSpace + 1);
-  const repaired = repairQuotedArg(rest);
-  if (repaired == null) return null;
-  return `${dbName} ${repaired}`;
+var RETRY_TEMPERATURES = [0, 0.2, 0.3];
+var SQL_AGENT_ROLE = "Expert SQL query generator.";
+var SQL_AGENT_OBJECTIVE = "Generate precise SQL grounded in provided schema.";
+var FORMATTER_SCOPE_DIALECTS = /* @__PURE__ */ new Map([
+  ["sqlite", "sqlite"],
+  ["postgresql", "postgresql"],
+  ["bigquery", "bigquery"],
+  ["transactsql", "transactsql"],
+  ["mysql", "mysql"]
+]);
+var SQL_AGENT_POLICIES = [
+  fragment(
+    "schema_mapping",
+    policy({
+      rule: "Translate natural language into precise SQL grounded in available schema entities."
+    }),
+    hint("Preserve schema spelling exactly, including typos in column names.")
+  ),
+  fragment(
+    "projection_minimality",
+    policy({
+      rule: "Return only columns requested by the question; do not add helper columns unless explicitly requested."
+    }),
+    policy({
+      rule: 'For requests of the form "X sorted/ordered by Y", project X only unless Y is explicitly requested as an output field.'
+    }),
+    policy({
+      rule: "Prefer selecting schema columns directly without derived expressions when direct selection answers the request."
+    }),
+    hint(
+      "Do not include ORDER BY, GROUP BY, or JOIN helper columns in SELECT output unless the question explicitly asks for them."
+    ),
+    policy({
+      rule: "Use DISTINCT only when uniqueness is explicitly requested (for example distinct/unique/different/no duplicates)."
+    }),
+    hint(
+      'Do not infer DISTINCT from generic wording such as "some", plural nouns, or entity-set phrasing; for transactional/attendance-style tables, default to raw rows unless uniqueness is explicitly requested.'
+    )
+  ),
+  fragment(
+    "date_transform_safety",
+    policy({
+      rule: "Do not assume VARCHAR/TEXT values are parseable dates. Avoid date extraction functions on text columns by default."
+    }),
+    policy({
+      rule: "Use date-part extraction only when both conditions hold: the question explicitly asks for transformation and schema values require transformation to produce that unit."
+    }),
+    hint(
+      "Do not apply SUBSTR, STRFTIME, DATE_PART, YEAR, or similar extraction functions unless the question explicitly asks for transformation and schema values require it."
+    ),
+    hint(
+      "If a column already represents the requested concept (for example a stored year-like value), use the column as-is."
+    )
+  ),
+  fragment(
+    "sql_minimality",
+    guardrail({
+      rule: "Never hallucinate tables or columns.",
+      reason: "Schema fidelity is required.",
+      action: "Use only available schema entities."
+    }),
+    guardrail({
+      rule: "Avoid unnecessary transformations and derived projections.",
+      reason: "Extra transformations frequently change semantics and reduce correctness.",
+      action: "Do not add date parsing, substring extraction, or derived columns unless explicitly required by the question or schema."
+    })
+  ),
+  fragment(
+    "preflight_checklist",
+    workflow({
+      task: "Final SQL preflight before returning output",
+      steps: [
+        "Verify selected columns match the question and remove unrequested helper projections.",
+        "If aggregate values are used only for ranking/filtering, keep them out of SELECT unless explicitly requested.",
+        "Prefer raw schema columns over derived expressions when raw columns already satisfy the request.",
+        "If a candidate query uses STRFTIME, SUBSTR, DATE_PART, YEAR, or similar extraction on text-like columns, remove that transformation unless explicitly required by the question.",
+        "Return only schema-grounded SQL using existing tables and columns."
+      ]
+    })
+  ),
+  fragment(
+    "set_semantics",
+    policy({
+      rule: "For questions asking where both condition A and condition B hold over an attribute, compute the intersection of qualifying sets for that attribute."
+    }),
+    policy({
+      rule: "Do not force the same entity instance to satisfy both conditions unless the question explicitly requests the same person/row/entity."
+    }),
+    hint(
+      "Prefer INTERSECT (or logically equivalent set-based shape) over requiring the same physical row/entity to satisfy both conditions unless explicitly requested."
+    ),
+    hint(
+      "When two conditions describe different row groups whose shared attribute is requested, build each group separately and intersect the attribute values."
+    ),
+    hint(
+      "Do not collapse cross-group conditions into a single-row AND predicate when the intent is shared values across groups."
+    ),
+    policy({
+      rule: "If two predicates on the same field cannot both be true for one row, do not combine them with AND; use set operations across separate filtered subsets when shared values are requested."
+    })
+  ),
+  fragment(
+    "predicate_column_alignment",
+    policy({
+      rule: "Match literal values to semantically compatible columns. Do not compare descriptive names to identifier columns."
+    }),
+    hint(
+      "When a filter value is a descriptive label (for example a department name), join through the lookup table and filter on its name/title column, not on *_id columns."
+    ),
+    hint(
+      "When relation roles are explicit in wording (for example host/home/source/destination), prefer foreign keys with matching role qualifiers over generic similarly named columns."
+    ),
+    policy({
+      rule: "When multiple foreign-key candidates exist, select the column whose qualifier best matches the relationship described in the question."
+    }),
+    policy({
+      rule: "For hosting/held semantics, prefer host_* relationship columns when available over generic *_id alternatives."
+    }),
+    hint(
+      'Interpret wording like "held/hosted a competition or event" as a hosting relationship and map to host_* foreign keys when present.'
+    ),
+    policy({
+      rule: "Do not compare descriptive labels or names to *_id columns; join to the table containing the descriptive field and filter there."
+    }),
+    policy({
+      rule: "Keep numeric identifiers unquoted when used as numeric equality filters unless schema indicates text identifiers."
+    }),
+    policy({
+      rule: "When filtering by a descriptive label value and a related table exposes a corresponding *_name or title column, join to that table and filter on the descriptive column."
+    })
+  ),
+  fragment(
+    "ordering_semantics",
+    policy({
+      rule: "Respect explicit sort direction terms. If direction is not specified, use ascending order unless a superlative intent (most/least/highest/lowest) implies direction."
+    }),
+    policy({
+      rule: "When ranking categories by frequency, use COUNT for ordering but keep output focused on requested category fields unless counts are explicitly requested."
+    }),
+    policy({
+      rule: "Do not use DESC unless descending direction is explicit or a superlative intent requires descending ranking."
+    }),
+    policy({
+      rule: 'For "most common/frequent <attribute>" requests, return the attribute value(s) only; use counts only for ordering/filtering unless the question explicitly asks to return counts.'
+    }),
+    hint(
+      'Use DESC with LIMIT 1 for "most/highest/largest"; use ASC with LIMIT 1 for "least/lowest/smallest".'
+    )
+  ),
+  fragment(
+    "negative_membership_queries",
+    policy({
+      rule: "For requests asking entities that did not participate/host/appear in related records, prefer NOT IN or NOT EXISTS against the related foreign-key set."
+    }),
+    hint(
+      "Map role-bearing relationship columns carefully (for example host_* foreign keys for hosting relationships) instead of generic IDs when role wording is explicit."
+    ),
+    hint(
+      'For "never had/never exceeded" conditions over history tables, exclude entities via NOT IN/NOT EXISTS against the disqualifying entity-id set (often built with GROUP BY/HAVING MAX(...)).'
+    )
+  ),
+  fragment(
+    "join_completeness",
+    policy({
+      rule: "Preserve entity-restricting joins implied by the question. Do not widen results by querying only a broader attribute table when a subset entity table is available."
+    }),
+    policy({
+      rule: "If an entity term in the question maps to a table, keep that table in query scope and join to attribute tables rather than dropping the entity table."
+    }),
+    hint(
+      "If the question targets a specific entity group, include that entity table and its join conditions even when selected columns come from a related table."
+    ),
+    hint(
+      "When the question names an entity type and a relation table links to that entity via *_id, include the entity table in scope instead of counting only relation rows."
+    ),
+    hint(
+      "Prefer INNER JOIN by default; use LEFT JOIN only when the question explicitly requests including unmatched rows or zero-related entities."
+    )
+  ),
+  fragment(
+    "aggregation_exactness",
+    policy({
+      rule: "Preserve requested aggregation semantics exactly: use COUNT(*) by default for total rows, use COUNT(DISTINCT ...) only when uniqueness is explicitly requested, and group by stable entity keys when computing per-entity aggregates."
+    }),
+    policy({
+      rule: "For questions asking which entity has lowest/highest average of a metric, compute AVG(metric) per entity (GROUP BY entity) and rank those aggregates."
+    }),
+    hint(
+      'For "how many <entities>" questions over relation records, default to COUNT(*) on qualifying rows unless explicit uniqueness language is present.'
+    )
+  ),
+  fragment(
+    "query_shape_examples",
+    example({
+      question: "List categories ordered by how many records belong to each category.",
+      answer: "SELECT category FROM records GROUP BY category ORDER BY COUNT(*)"
+    }),
+    example({
+      question: "Show labels shared by rows with metric > 100 and rows with metric < 10.",
+      answer: "SELECT label FROM records WHERE metric > 100 INTERSECT SELECT label FROM records WHERE metric < 10"
+    }),
+    example({
+      question: "List locations that have not hosted any event.",
+      answer: "SELECT location_name FROM locations WHERE location_id NOT IN (SELECT host_location_id FROM events)"
+    }),
+    example({
+      question: "List the most common category across records.",
+      answer: "SELECT category FROM records GROUP BY category ORDER BY COUNT(*) DESC LIMIT 1"
+    })
+  )
+];
+function extractSql(output) {
+  const match = output.match(/```sql\n?([\s\S]*?)```/);
+  return match ? match[1].trim() : output.trim();
 }
-function resolveAdapter(adapters, subcommand, args) {
-  const [name, ...rest] = args;
-  const available = Object.keys(adapters).join(", ");
-  if (!name) {
-    return {
-      error: `sql ${subcommand}: missing database name. Usage: sql ${subcommand} <db> "SELECT ...". Available: ${available}`
-    };
+function scopeDialectFor(adapter) {
+  const dialect = FORMATTER_SCOPE_DIALECTS.get(adapter.formatterLanguage);
+  if (!dialect) {
+    throw new TypeError(
+      `No scope dialect mapping for formatter language "${adapter.formatterLanguage}".`
+    );
   }
-  const adapter = adapters[name];
-  if (!adapter) {
-    return {
-      error: `sql ${subcommand}: unknown database "${name}". Available: ${available}`
-    };
-  }
-  const sql = rest.join(" ").trim();
-  if (!sql) {
-    return { error: `sql ${subcommand}: no query provided` };
-  }
-  return { adapter, sql };
+  return dialect;
 }
-function createSqlCommand(adapters, { outputDir = "/sql" } = {}) {
-  const subcommands = {
-    run: {
-      usage: 'run <db> "SELECT ..."',
-      description: "Execute query against <db> and store results",
-      repair: repairDbNameAndQuotedArg,
-      handler: async (args, ctx) => {
-        const meta = useBashMeta();
-        meta?.setReminder(SQL_VALIDATE_REMINDER);
-        const resolved = resolveAdapter(adapters, "run", args);
-        if ("error" in resolved) {
-          return { stdout: "", stderr: resolved.error, exitCode: 1 };
-        }
-        const { adapter, sql: rawQuery } = resolved;
-        const query = adapter.format(rawQuery);
-        meta?.setHidden({ formattedSql: query });
-        const syntaxError = await adapter.validate(query);
-        if (syntaxError) {
-          return {
-            stdout: "",
-            stderr: `sql run: ${syntaxError}`,
-            exitCode: 1
-          };
-        }
-        try {
-          const rows = await adapter.execute(query);
-          if (!Array.isArray(rows)) {
-            throw new Error("adapter.execute must return an array of rows");
-          }
-          const rowsArray = rows;
-          const content = JSON.stringify(rowsArray, null, 2);
-          const filename = `${v7()}.json`;
-          const sqlPath = `${outputDir}/${filename}`;
-          const mkdir = await ctx.sandbox.executeCommand(
-            `mkdir -p ${outputDir}`
-          );
-          if (mkdir.exitCode !== 0) {
-            return {
-              stdout: "",
-              stderr: `sql run: failed to create ${outputDir}: ${mkdir.stderr}`,
-              exitCode: 1
-            };
-          }
-          await ctx.sandbox.writeFiles([{ path: sqlPath, content }]);
-          const columns = rowsArray.length > 0 ? Object.keys(rowsArray[0]) : [];
-          return {
-            stdout: [
-              `results stored in ${sqlPath}`,
-              `columns: ${columns.join(", ") || "(none)"}`,
-              `rows: ${rowsArray.length}`
-            ].join("\n") + "\n",
-            stderr: "",
-            exitCode: 0
-          };
-        } catch (error) {
+function fencedMarkdownParseError(sql, adapter) {
+  return new SQLValidationError(
+    JSON.stringify(
+      buildScopeParseErrorPayload(
+        sql,
+        scopeDialectFor(adapter),
+        new Error("SQL response was fenced markdown, not executable SQL.")
+      )
+    )
+  );
+}
+async function toSql(options) {
+  const { maxRetries = 3 } = options;
+  return withRetry(
+    async (attemptNumber, errors, attempts) => {
+      const context = new ContextEngine({
+        store: new InMemoryContextStore(),
+        chatId: `sql-gen-${crypto.randomUUID()}`,
+        userId: "system"
+      });
+      context.set(
+        persona({
+          name: "Freya",
+          role: SQL_AGENT_ROLE,
+          objective: SQL_AGENT_OBJECTIVE
+          // role: `You are a data science expert that provides well-reasoned and detailed responses.`,
+          // objective: `Your task is to understand the schema and generate a valid SQL query to answer the question. You first think about the reasoning process as an internal monologue and then provide the user with the answer.`,
+        }),
+        ...SQL_AGENT_POLICIES,
+        ...options.fragments
+      );
+      if (errors.length) {
+        const lastError = errors.at(-1);
+        context.set(
+          user(dedent`
+            Answer the following question with the SQL code. Use the piece of evidence and base your answer on the database schema.
+Given the question, the evidence and the database schema, return the SQL script that addresses the question.
+
+Question: ${options.input}
+`),
+          UnanswerableSQLError.isInstance(lastError) ? user(
+            `<retry_instruction>Your previous response marked the task as unanswerable. Re-evaluate using best-effort schema mapping. If the core intent is answerable with existing tables/columns, return SQL. Return error only when required core intent cannot be mapped without inventing schema elements.</retry_instruction>`
+          ) : user(
+            `<validation_error>Your previous SQL query had the following error: ${lastError?.message}. Please fix the query.</validation_error>`
+          )
+        );
+      } else {
+        context.set(
+          user(dedent`
+            Answer the following question with the SQL code. Use the piece of evidence and base your answer on the database schema.
+Given the question, the evidence and the database schema, return the SQL script that addresses the question.
+
+Question: ${options.input}
+`)
+        );
+      }
+      const temperature = RETRY_TEMPERATURES[attemptNumber - 1] ?? RETRY_TEMPERATURES[RETRY_TEMPERATURES.length - 1];
+      const baseModel = options.model ?? groq("openai/gpt-oss-20b");
+      const model = wrapLanguageModel({
+        model: baseModel,
+        middleware: defaultSettingsMiddleware({ settings: { temperature } })
+      });
+      const sqlOutput = structuredOutput({
+        model,
+        context,
+        schema: z.object({
+          result: z.union([
+            z.object({
+              sql: z.string().describe("The SQL query that answers the question"),
+              reasoning: z.string().describe("The reasoning steps taken to generate the SQL")
+            }),
+            z.object({
+              error: z.string().describe(
+                "Error message explaining why the question cannot be answered with the given schema"
+              )
+            })
+          ])
+        })
+      });
+      const { result: output } = await sqlOutput.generate();
+      const finalizeSql = async (rawSql) => {
+        const extractedSql = extractSql(rawSql);
+        const errorsOrUndefined = errors.length ? errors.map(formatErrorMessage) : void 0;
+        if (extractedSql === "") {
           return {
-            stdout: "",
-            stderr: `sql run: ${error instanceof Error ? error.message : String(error)}`,
-            exitCode: 1
+            attempts,
+            sql: "",
+            errors: errorsOrUndefined
           };
         }
-      }
-    },
-    validate: {
-      usage: 'validate <db> "SELECT ..."',
-      description: "Validate query syntax against <db>",
-      repair: repairDbNameAndQuotedArg,
-      handler: async (args) => {
-        const meta = useBashMeta();
-        const resolved = resolveAdapter(adapters, "validate", args);
-        if ("error" in resolved) {
-          return { stdout: "", stderr: resolved.error, exitCode: 1 };
+        const sql = options.adapter.format(extractedSql);
+        if (rawSql.trimStart().startsWith("```") && extractedSql === rawSql.trim()) {
+          throw fencedMarkdownParseError(sql, options.adapter);
         }
-        const { adapter, sql: rawQuery } = resolved;
-        const query = adapter.format(rawQuery);
-        meta?.setHidden({ formattedSql: query });
-        const syntaxError = await adapter.validate(query);
-        if (syntaxError) {
-          return {
-            stdout: "",
-            stderr: `sql validate: ${syntaxError}`,
-            exitCode: 1
-          };
+        const validationError = await options.adapter.validate(sql);
+        if (validationError) {
+          throw new SQLValidationError(validationError);
         }
         return {
-          stdout: "valid\n",
-          stderr: "",
-          exitCode: 0
+          attempts,
+          sql,
+          errors: errorsOrUndefined
         };
+      };
+      if ("error" in output) {
+        context.set(
+          user(
+            "<best_effort_fallback>Do not return unanswerable. Produce the best valid SQL query that answers the core intent using only available schema entities.</best_effort_fallback>"
+          )
+        );
+        const forcedSqlOutput = structuredOutput({
+          model,
+          context,
+          schema: z.object({
+            sql: z.string().describe(
+              "Best-effort SQL query that answers the core intent using only available schema entities."
+            ),
+            reasoning: z.string().describe("Reasoning steps for best-effort schema mapping.")
+          })
+        });
+        try {
+          const forced = await forcedSqlOutput.generate();
+          return await finalizeSql(forced.sql);
+        } catch (error) {
+          if (SQLValidationError.isInstance(error) || APICallError.isInstance(error) || JSONParseError.isInstance(error) || TypeValidationError.isInstance(error) || NoObjectGeneratedError.isInstance(error) || NoOutputGeneratedError.isInstance(error) || NoContentGeneratedError.isInstance(error)) {
+            throw error;
+          }
+          throw new UnanswerableSQLError(output.error);
+        }
       }
-    }
-  };
-  const command = defineSubcommandGroup("sql", subcommands);
-  const repair = buildSubcommandRepair("sql", subcommands);
-  return { command, repair };
-}
-
-// packages/text2sql/src/lib/agents/sql-transform-plugins.ts
-import { parse, serialize } from "just-bash";
-import { createHash } from "node:crypto";
-import * as path from "node:path";
-import { BashException, asStaticWordText } from "@deepagents/context";
-function isScriptNode(value) {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-  const node = value;
-  return node.type === "Script" && Array.isArray(node.statements);
-}
-var BLOCKED_DB_CLIENT_COMMANDS = /* @__PURE__ */ new Set([
-  "psql",
-  "sqlite3",
-  "mysql",
-  "duckdb"
-]);
-var BLOCKED_RAW_SQL_COMMANDS = /* @__PURE__ */ new Set(["select", "with"]);
-var ALLOWED_SQL_PROXY_SUBCOMMANDS = /* @__PURE__ */ new Set(["run", "validate"]);
-var SHELL_INTERPRETER_COMMANDS = /* @__PURE__ */ new Set([
-  "bash",
-  "sh",
-  "zsh",
-  "dash",
-  "ksh"
-]);
-var WRAPPER_COMMANDS = /* @__PURE__ */ new Set(["env", "command", "eval"]);
-var SQL_PROXY_ENFORCEMENT_MESSAGE = [
-  "Direct database querying through bash is blocked.",
-  "Use SQL proxy commands in this order:",
-  '1) sql validate <db> "SELECT ..."',
-  '2) sql run <db> "SELECT ..."'
-].join("\n");
-var SqlProxyViolationError = class extends BashException {
-  constructor() {
-    super(SQL_PROXY_ENFORCEMENT_MESSAGE);
-    this.name = "SqlProxyViolationError";
-  }
-  format() {
-    return { stdout: "", stderr: `${this.message}
-`, exitCode: 1 };
-  }
-};
-function cloneInspectionContext(context) {
-  return {
-    functionDefinitions: new Map(context.functionDefinitions),
-    callStack: new Set(context.callStack)
-  };
-}
-function scriptContainsBlockedCommand(script, context, mode = "blocked-only") {
-  return statementsContainBlockedCommand(script.statements, context, mode);
-}
-function statementsContainBlockedCommand(statements, context, mode) {
-  for (const statement of statements) {
-    if (statementContainsBlockedCommand(statement, context, mode)) {
-      return true;
-    }
-  }
-  return false;
-}
-function statementContainsBlockedCommand(statement, context, mode) {
-  for (const pipeline of statement.pipelines) {
-    if (pipelineContainsBlockedCommand(pipeline, context, mode)) {
-      return true;
-    }
-  }
-  return false;
+      return await finalizeSql(output.sql);
+    },
+    { retries: maxRetries - 1 }
+  );
 }
-function pipelineContainsBlockedCommand(pipeline, context, mode) {
-  for (const [index2, command] of pipeline.commands.entries()) {
-    if (command.type === "FunctionDef") {
-      context.functionDefinitions.set(command.name, command);
-      continue;
-    }
-    if (commandContainsBlockedCommand(command, context, mode, {
-      stdinFromPipe: index2 > 0
-    })) {
-      return true;
+function formatErrorMessage(error) {
+  if (APICallError.isInstance(error)) {
+    if (error.message.startsWith("Failed to validate JSON")) {
+      return `Schema validation failed: ${error.message}`;
     }
+    return error.message;
   }
-  return false;
-}
-function stringCommandContainsBlockedCommand(command, context, mode = "blocked-only") {
-  let script;
-  try {
-    script = parse(command);
-  } catch {
-    return false;
+  if (SQLValidationError.isInstance(error)) {
+    return `SQL Validation Error: ${error.message}`;
   }
-  return scriptContainsBlockedCommand(
-    script,
-    cloneInspectionContext(context),
-    mode
-  );
+  return error.message;
 }
-function wordContainsBlockedCommand(word, context, mode) {
-  if (!word) {
+function isModelUnavailableError(error) {
+  if (!APICallError.isInstance(error)) {
     return false;
   }
-  return wordPartContainsBlockedCommand(
-    word.parts,
-    context,
-    mode
-  );
-}
-function wordPartContainsBlockedCommand(parts, context, mode) {
-  for (const part of parts) {
-    if (partContainsBlockedCommand(part, context, mode)) {
-      return true;
-    }
-  }
-  return false;
+  const message = error.message.toLowerCase();
+  const responseBody = (error.responseBody ?? "").toLowerCase();
+  const is404ModelError = error.statusCode === 404 && (message.includes("model") || responseBody.includes("model_not_found"));
+  const errorCode = typeof error.data === "object" && error.data !== null && "error" in error.data && typeof error.data.error === "object" && error.data.error !== null && "code" in error.data.error && typeof error.data.error.code === "string" ? error.data.error.code.toLowerCase() : void 0;
+  return is404ModelError || errorCode === "model_not_found" || responseBody.includes('"code":"model_not_found"') || message.includes("model") && message.includes("does not exist or you do not have access to it");
 }
-function partContainsBlockedCommand(node, context, mode) {
-  const type = node.type;
-  if (type === "CommandSubstitution" || type === "ProcessSubstitution") {
-    if (isScriptNode(node.body)) {
-      return scriptContainsBlockedCommand(
-        node.body,
-        cloneInspectionContext(context),
-        mode
-      );
-    }
-    return false;
-  }
-  if (type === "ArithCommandSubst" && typeof node.command === "string") {
-    return stringCommandContainsBlockedCommand(node.command, context, mode);
-  }
-  for (const value of Object.values(node)) {
-    if (Array.isArray(value)) {
-      for (const item of value) {
-        if (typeof item === "object" && item !== null) {
-          if (partContainsBlockedCommand(
-            item,
-            context,
-            mode
-          )) {
-            return true;
-          }
+async function withRetry(computation, options = { retries: 3 }) {
+  const errors = [];
+  let attempts = 0;
+  return pRetry(
+    (attemptNumber) => {
+      return computation(attemptNumber, errors, ++attempts);
+    },
+    {
+      retries: options.retries,
+      shouldRetry: (context) => {
+        if (UnanswerableSQLError.isInstance(context.error)) {
+          return false;
         }
-      }
-      continue;
-    }
-    if (typeof value === "object" && value !== null) {
-      if (partContainsBlockedCommand(
-        value,
-        context,
-        mode
-      )) {
-        return true;
+        if (isModelUnavailableError(context.error)) {
+          return false;
+        }
+        if (SQLValidationError.isInstance(context.error)) {
+          return true;
+        }
+        console.log({
+          NoObjectGeneratedError: NoObjectGeneratedError.isInstance(
+            context.error
+          ),
+          NoOutputGeneratedError: NoOutputGeneratedError.isInstance(
+            context.error
+          ),
+          APICallError: APICallError.isInstance(context.error),
+          JSONParseError: JSONParseError.isInstance(context.error),
+          TypeValidationError: TypeValidationError.isInstance(context.error),
+          NoContentGeneratedError: NoContentGeneratedError.isInstance(
+            context.error
+          )
+        });
+        return APICallError.isInstance(context.error) || JSONParseError.isInstance(context.error) || TypeValidationError.isInstance(context.error) || NoObjectGeneratedError.isInstance(context.error) || NoOutputGeneratedError.isInstance(context.error) || NoContentGeneratedError.isInstance(context.error);
+      },
+      onFailedAttempt(context) {
+        errors.push(context.error);
       }
     }
-  }
-  return false;
-}
-function functionInvocationContainsBlockedCommand(functionName, context, mode) {
-  const definition = context.functionDefinitions.get(functionName);
-  if (!definition) {
-    return false;
-  }
-  if (context.callStack.has(functionName)) {
-    return false;
-  }
-  const invocationContext = cloneInspectionContext(context);
-  invocationContext.callStack.add(functionName);
-  return commandContainsBlockedCommand(
-    definition.body,
-    invocationContext,
-    mode,
-    { stdinFromPipe: false }
   );
 }
-function isAsciiLetter(character) {
-  const charCode = character.charCodeAt(0);
-  return charCode >= 65 && charCode <= 90 || charCode >= 97 && charCode <= 122;
-}
-function isAsciiDigit(character) {
-  const charCode = character.charCodeAt(0);
-  return charCode >= 48 && charCode <= 57;
-}
-function isValidEnvVariableName(name) {
-  if (!name) {
-    return false;
+
+// packages/text2sql/src/lib/agents/suggestions.agents.ts
+import { groq as groq2 } from "@ai-sdk/groq";
+import dedent2 from "dedent";
+import z2 from "zod";
+import { agent, thirdPersonPrompt } from "@deepagents/agent";
+var suggestionsAgent = agent({
+  name: "text2sql-suggestions",
+  model: groq2("openai/gpt-oss-20b"),
+  output: z2.object({
+    suggestions: z2.array(
+      z2.object({
+        question: z2.string().describe("A complex, high-impact business question."),
+        sql: z2.string().describe("The SQL statement needed to answer the question."),
+        businessValue: z2.string().describe("Why the question matters to stakeholders.")
+      })
+    ).min(1).max(5).describe("A set of up to two advanced question + SQL pairs.")
+  }),
+  prompt: (state) => {
+    return dedent2`
+      ${thirdPersonPrompt()}
+
+      <identity>
+        You are a senior analytics strategist who proposes ambitious business questions
+        and drafts the SQL needed to answer them. You specialize in identifying ideas
+        that combine multiple tables, apply segmentation or time analysis, and surface
+        metrics that drive executive decisions.
+      </identity>
+
+
+      <instructions>
+        - Recommend one or two UNIQUE questions that go beyond simple counts or listings.
+        - Favor questions that require joins, aggregates, time comparisons, cohort analysis,
+          or window functions.
+        - For each question, explain the business reason stakeholders care about it.
+        - Provide the complete SQL query that could answer the question in the given schema.
+        - Keep result sets scoped with LIMIT clauses (max 50 rows) when returning raw rows.
+        - Ensure table/column names match the provided schema exactly.
+        - Use columns marked [LowCardinality: ...] to identify meaningful categorical filters or segmentations.
+        - Leverage table [rows / size] hints to determine whether to aggregate (large tables) or inspect detailed data (tiny tables).
+        - Reference PK/Indexed annotations and the Indexes list to recommend queries that use efficient join/filter paths.
+        - Column annotations may expose ranges/null percentages—use them to suggest realistic thresholds or quality checks.
+        - Consult <relationship_examples> to anchor your recommendations in the actual join paths between tables.
+        - Output only information grounded in the schema/context provided.
+      </instructions>
+
+      <response-format>
+        Return valid JSON that satisfies the defined output schema.
+      </response-format>
+    `;
   }
-  const firstChar = name[0];
-  if (!(isAsciiLetter(firstChar) || firstChar === "_")) {
-    return false;
+});
+
+// packages/text2sql/src/lib/adapter-index.ts
+import { fragment as fragment2 } from "@deepagents/context";
+
+// packages/text2sql/src/lib/file-cache.ts
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+var FileCache = class {
+  path;
+  constructor(watermark, extension = ".txt") {
+    const hash2 = createHash("md5").update(watermark).digest("hex");
+    this.path = path.join(tmpdir(), `text2sql-${hash2}${extension}`);
   }
-  for (let index2 = 1; index2 < name.length; index2 += 1) {
-    const char = name[index2];
-    if (!(isAsciiLetter(char) || isAsciiDigit(char) || char === "_")) {
-      return false;
+  async get() {
+    if (existsSync(this.path)) {
+      return readFile(this.path, "utf-8");
     }
+    return null;
   }
-  return true;
-}
-function isEnvAssignmentToken(token) {
-  const separatorIndex = token.indexOf("=");
-  if (separatorIndex <= 0) {
-    return false;
+  set(content) {
+    return writeFile(this.path, content, "utf-8");
   }
-  return isValidEnvVariableName(token.slice(0, separatorIndex));
-}
-function parseShortOptionCluster(option) {
-  if (!option.startsWith("-") || option.startsWith("--") || option.length <= 1) {
-    return {
-      valid: false,
-      hasCommandFlag: false,
-      hasStdinFlag: false,
-      consumesNextArg: false
-    };
+};
+var JsonCache = class extends FileCache {
+  constructor(watermark) {
+    super(watermark, ".json");
   }
-  let hasCommandFlag = false;
-  let hasStdinFlag = false;
-  let consumesNextArg = false;
-  for (let index2 = 1; index2 < option.length; index2 += 1) {
-    const char = option[index2];
-    if (!isAsciiLetter(char)) {
-      return {
-        valid: false,
-        hasCommandFlag: false,
-        hasStdinFlag: false,
-        consumesNextArg: false
-      };
-    }
-    if (char === "c") {
-      hasCommandFlag = true;
-    } else if (char === "s") {
-      hasStdinFlag = true;
-    } else if (char === "O" || char === "o") {
-      consumesNextArg = true;
+  async read() {
+    const content = await this.get();
+    if (content) {
+      return JSON.parse(content);
     }
+    return null;
   }
-  return { valid: true, hasCommandFlag, hasStdinFlag, consumesNextArg };
+  write(data) {
+    return this.set(JSON.stringify(data));
+  }
+};
+
+// packages/text2sql/src/lib/adapter-index.ts
+var TEXT2SQL_INDEX_PROGRESS_CHUNK = "data-text2sql-index-progress";
+var noopProgressHandler = () => {
+};
+function timestampProgressHandler(onProgress) {
+  if (!onProgress) return noopProgressHandler;
+  return (event) => {
+    onProgress({
+      ...event,
+      timestampMs: event.timestampMs ?? Date.now()
+    });
+  };
 }
-function getShellInvocationDescriptor(args) {
-  let readsFromStdin = false;
-  const longOptionsWithValue = /* @__PURE__ */ new Set(["--rcfile", "--init-file"]);
-  for (let index2 = 0; index2 < args.length; index2 += 1) {
-    const token = asStaticWordText(args[index2]);
-    if (token == null) {
-      return { kind: "unknown", payload: null };
-    }
-    if (token === "--") {
-      if (index2 + 1 >= args.length) {
-        break;
-      }
-      return {
-        kind: "script",
-        payload: asStaticWordText(args[index2 + 1])
-      };
+var AdapterIndexer = class {
+  #adapters;
+  #version;
+  #cacheKey;
+  constructor(options) {
+    const adapterNames = Object.keys(options.adapters);
+    if (adapterNames.length === 0) {
+      throw new Error("AdapterIndexer requires at least one adapter");
     }
-    if (token === "--command") {
-      return {
-        kind: "command",
-        payload: asStaticWordText(args[index2 + 1])
-      };
+    validateAdapterNames(adapterNames);
+    this.#adapters = options.adapters;
+    this.#version = options.version;
+    this.#cacheKey = options.cacheKey;
+  }
+  async index(options = {}) {
+    const progress = timestampProgressHandler(options.onProgress);
+    const entries = this.#resolveIndexEntries(options.adapterNames);
+    progress({
+      type: "index:start",
+      message: `Indexing ${entries.length} adapter${entries.length === 1 ? "" : "s"}...`,
+      current: 0,
+      total: entries.length
+    });
+    const settled = await Promise.allSettled(
+      entries.map(async ([name, adapter]) => {
+        const schema = await this.#indexAdapter(name, adapter, progress);
+        return fragment2(name, ...schema);
+      })
+    );
+    const failed = settled.find((result) => result.status === "rejected");
+    if (failed) {
+      progress({
+        type: "index:error",
+        message: failed.reason instanceof Error ? failed.reason.message : String(failed.reason)
+      });
+      throw failed.reason;
     }
-    if (token.startsWith("--command=")) {
-      return {
-        kind: "command",
-        payload: token.slice("--command=".length)
-      };
-    }
-    if (token.startsWith("--")) {
-      if (token.includes("=")) {
-        continue;
-      }
-      if (longOptionsWithValue.has(token)) {
-        if (index2 + 1 >= args.length) {
-          return { kind: "unknown", payload: null };
-        }
-        index2 += 1;
+    const wrapped = settled.map((result) => {
+      if (result.status === "rejected") {
+        throw result.reason;
       }
-      continue;
+      return result.value;
+    });
+    progress({
+      type: "index:end",
+      message: "Finished indexing adapters.",
+      current: entries.length,
+      total: entries.length
+    });
+    return wrapped;
+  }
+  async indexAdapter(name, options = {}) {
+    const adapter = this.#adapters[name];
+    if (!adapter) {
+      const available = Object.keys(this.#adapters).join(", ");
+      throw new Error(`unknown adapter "${name}". Available: ${available}`);
     }
-    if (token.startsWith("-") && !token.startsWith("--")) {
-      const parsed = parseShortOptionCluster(token);
-      if (!parsed.valid) {
-        return { kind: "unknown", payload: null };
-      }
-      if (parsed.hasCommandFlag) {
-        return {
-          kind: "command",
-          payload: asStaticWordText(args[index2 + 1])
-        };
-      }
-      if (parsed.hasStdinFlag) {
-        readsFromStdin = true;
+    return this.#indexAdapter(
+      name,
+      adapter,
+      timestampProgressHandler(options.onProgress)
+    );
+  }
+  async #indexAdapter(name, adapter, progress) {
+    progress({
+      type: "adapter:start",
+      adapter: name,
+      message: `Indexing adapter "${name}"...`
+    });
+    const cacheKey = this.#adapterCacheKey(name);
+    const cache = cacheKey ? new JsonCache(cacheKey) : void 0;
+    try {
+      const cached = await cache?.read();
+      if (cached) {
+        progress({
+          type: "adapter:cache-hit",
+          adapter: name,
+          message: `Using cached index for adapter "${name}".`,
+          cached: true
+        });
+        progress({
+          type: "adapter:end",
+          adapter: name,
+          message: `Finished indexing adapter "${name}".`,
+          cached: true
+        });
+        return cached;
       }
-      if (parsed.consumesNextArg) {
-        if (index2 + 1 >= args.length) {
-          return { kind: "unknown", payload: null };
-        }
-        index2 += 1;
+      if (cache) {
+        progress({
+          type: "adapter:cache-miss",
+          adapter: name,
+          message: `No cached index for adapter "${name}".`,
+          cached: false
+        });
       }
-      continue;
+      const ctx = createGroundingContext({
+        onProgress: (event) => progress(adapterProgressEvent(name, event))
+      });
+      const fragments = await adapter.introspect(ctx);
+      await cache?.write(fragments);
+      progress({
+        type: "adapter:end",
+        adapter: name,
+        message: `Finished indexing adapter "${name}".`,
+        cached: false
+      });
+      return fragments;
+    } catch (error) {
+      const reason = errorMessage(error);
+      progress({
+        type: "adapter:error",
+        adapter: name,
+        message: `Failed indexing adapter "${name}": ${reason}`
+      });
+      throw new Error(`introspecting adapter "${name}": ${reason}`, {
+        cause: error
+      });
     }
-    return {
-      kind: "script",
-      payload: token
-    };
   }
-  if (readsFromStdin) {
-    return { kind: "stdin", payload: null };
+  #resolveIndexEntries(adapterNames) {
+    const availableNames = Object.keys(this.#adapters);
+    const requestedNames = adapterNames && adapterNames.length > 0 ? [...new Set(adapterNames)] : availableNames;
+    const available = availableNames.join(", ");
+    return requestedNames.map((name) => {
+      const adapter = this.#adapters[name];
+      if (!adapter) {
+        throw new Error(`unknown adapter "${name}". Available: ${available}`);
+      }
+      return [name, adapter];
+    });
   }
-  return { kind: "none", payload: null };
-}
-function getHereDocPayload(redirections) {
-  const payloads = [];
-  for (const redirection of redirections) {
-    if (redirection.target.type !== "HereDoc") {
-      continue;
-    }
-    if (!redirection.target.content) {
-      payloads.push("");
-      continue;
+  #adapterCacheKey(name) {
+    const configured = this.#cacheKey?.(name);
+    if (configured !== void 0) {
+      return configured;
     }
-    const payload = asStaticWordText(redirection.target.content);
-    if (payload == null) {
-      return { hasHereDoc: true, payload: null };
+    if (this.#version) {
+      return `introspection-${this.#version}-${name}`;
     }
-    payloads.push(payload);
-  }
-  if (payloads.length === 0) {
-    return { hasHereDoc: false, payload: null };
+    return void 0;
   }
-  return { hasHereDoc: true, payload: payloads.join("\n") };
+};
+function adapterProgressEvent(adapter, progress) {
+  return {
+    type: progress.type,
+    adapter,
+    phase: progress.phase,
+    table: progress.table,
+    message: progress.message,
+    current: progress.current,
+    total: progress.total,
+    cached: false,
+    timestampMs: progress.timestampMs
+  };
 }
-function joinStaticWords(words) {
-  const tokens = [];
-  for (const word of words) {
-    const token = asStaticWordText(word);
-    if (token == null) {
-      return null;
-    }
-    tokens.push(token);
-  }
-  return tokens.join(" ");
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
 }
-function resolveEnvWrapperCommand(args) {
-  let index2 = 0;
-  while (index2 < args.length) {
-    const token = asStaticWordText(args[index2]);
-    if (token == null) {
-      return { kind: "unknown" };
-    }
-    if (token === "--") {
-      index2 += 1;
-      break;
-    }
-    if (token === "-u" || token === "--unset" || token === "--chdir") {
-      if (index2 + 1 >= args.length) {
-        return { kind: "unknown" };
+
+// packages/text2sql/src/lib/checkpoint.ts
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync as existsSync2, readFileSync, renameSync, writeFileSync } from "node:fs";
+import pLimit from "p-limit";
+var Checkpoint = class _Checkpoint {
+  points;
+  path;
+  configHash;
+  constructor(path6, configHash, points) {
+    this.points = points;
+    this.path = path6;
+    this.configHash = configHash;
+  }
+  /**
+   * Load checkpoint from file, or return empty checkpoint if none exists.
+   * Handles corrupted files and config changes gracefully.
+   */
+  static async load(options) {
+    const { path: path6, configHash } = options;
+    if (existsSync2(path6)) {
+      try {
+        const content = readFileSync(path6, "utf-8");
+        const file = JSON.parse(content);
+        if (configHash && file.configHash && file.configHash !== configHash) {
+          console.log("\u26A0 Config changed, starting fresh");
+          return new _Checkpoint(path6, configHash, {});
+        }
+        const points = file.points ?? {};
+        const totalEntries = Object.values(points).reduce(
+          (sum, p) => sum + p.entries.length,
+          0
+        );
+        console.log(`\u2713 Resuming from checkpoint (${totalEntries} entries)`);
+        return new _Checkpoint(path6, configHash, points);
+      } catch {
+        console.log("\u26A0 Checkpoint corrupted, starting fresh");
+        return new _Checkpoint(path6, configHash, {});
       }
-      index2 += 2;
-      continue;
-    }
-    if (token.startsWith("--unset=") || token.startsWith("--chdir=")) {
-      index2 += 1;
-      continue;
-    }
-    if (token.startsWith("-") && token !== "-" && !isEnvAssignmentToken(token)) {
-      index2 += 1;
-      continue;
-    }
-    if (isEnvAssignmentToken(token)) {
-      index2 += 1;
-      continue;
     }
-    break;
-  }
-  if (index2 >= args.length) {
-    return { kind: "none" };
+    console.log("Starting new checkpoint");
+    return new _Checkpoint(path6, configHash, {});
   }
-  return {
-    kind: "resolved",
-    name: args[index2],
-    args: args.slice(index2 + 1)
-  };
-}
-function resolveCommandWrapperCommand(args) {
-  let index2 = 0;
-  let lookupOnly = false;
-  while (index2 < args.length) {
-    const token = asStaticWordText(args[index2]);
-    if (token == null) {
-      return { kind: "unknown" };
-    }
-    if (token === "--") {
-      index2 += 1;
-      break;
-    }
-    if (token === "-v" || token === "-V") {
-      lookupOnly = true;
-      index2 += 1;
-      continue;
-    }
-    if (token.startsWith("-") && token !== "-") {
-      index2 += 1;
-      continue;
-    }
-    break;
+  /**
+   * Run a single computation with checkpointing.
+   * If already completed, returns cached value.
+   *
+   * @param key - Unique identifier for this computation
+   * @param computation - Async function that produces the value
+   * @param codec - Optional codec for encoding/decoding non-primitive values
+   */
+  async run(key, computation, codec) {
+    const point = this.point(key);
+    return point.through(
+      "single",
+      async () => {
+        const result = await computation();
+        return codec ? codec.encode(result) : result;
+      },
+      codec
+    );
   }
-  if (lookupOnly || index2 >= args.length) {
-    return { kind: "none" };
+  /**
+   * Create a resumable checkpoint point for iterative operations.
+   *
+   * @param step - Unique identifier for this checkpoint point
+   */
+  point(step) {
+    this.points[step] ??= { committed: false, entries: [] };
+    return new Point(this.points[step], () => this.save());
   }
-  return {
-    kind: "resolved",
-    name: args[index2],
-    args: args.slice(index2 + 1)
-  };
-}
-function commandContainsBlockedCommand(command, context, mode, options = { stdinFromPipe: false }) {
-  switch (command.type) {
-    case "SimpleCommand":
-      return isBlockedSimpleCommand(command, context, mode, options);
-    case "If":
-      return command.clauses.some(
-        (clause) => statementsContainBlockedCommand(
-          clause.condition,
-          cloneInspectionContext(context),
-          mode
-        ) || statementsContainBlockedCommand(
-          clause.body,
-          cloneInspectionContext(context),
-          mode
-        )
-      ) || (command.elseBody ? statementsContainBlockedCommand(
-        command.elseBody,
-        cloneInspectionContext(context),
-        mode
-      ) : false);
-    case "For":
-    case "CStyleFor":
-      return statementsContainBlockedCommand(
-        command.body,
-        cloneInspectionContext(context),
-        mode
-      );
-    case "While":
-    case "Until":
-      return statementsContainBlockedCommand(
-        command.condition,
-        cloneInspectionContext(context),
-        mode
-      ) || statementsContainBlockedCommand(
-        command.body,
-        cloneInspectionContext(context),
-        mode
-      );
-    case "Case":
-      return command.items.some(
-        (item) => statementsContainBlockedCommand(
-          item.body,
-          cloneInspectionContext(context),
-          mode
-        )
-      );
-    case "Subshell":
-    case "Group":
-      return statementsContainBlockedCommand(
-        command.body,
-        cloneInspectionContext(context),
-        mode
-      );
-    case "FunctionDef":
-      return false;
-    case "ArithmeticCommand":
-    case "ConditionalCommand":
-      return false;
-    default: {
-      const _unreachable = command;
-      return _unreachable;
+  /**
+   * Process each input with automatic checkpointing and concurrency.
+   *
+   * @param step - Unique identifier for this checkpoint
+   * @param inputs - Items to process
+   * @param process - Function to process each input
+   * @param options - Optional settings like concurrency
+   * @returns All outputs (use `.flat()` if outputs are arrays)
+   */
+  async each(step, inputs, process, options) {
+    const point = this.point(step);
+    const limit = pLimit(options?.concurrency ?? 1);
+    const inputArray = Array.from(inputs);
+    await Promise.all(
+      inputArray.map(
+        (input) => limit(() => point.through(input, () => process(input)))
+      )
+    );
+    await point.commit();
+    return point.values();
+  }
+  /**
+   * Get clean output from all completed points.
+   * Single-entry points return the value directly, multi-entry return arrays.
+   */
+  getOutput() {
+    const output = {};
+    for (const [key, pointData] of Object.entries(this.points)) {
+      if (pointData.entries.length === 1) {
+        output[key] = pointData.entries[0].output;
+      } else {
+        output[key] = pointData.entries.map((e) => e.output);
+      }
     }
+    return output;
   }
-}
-function isBlockedSimpleCommand(command, context, mode, options) {
-  if (wordContainsBlockedCommand(command.name, context, mode)) {
-    return true;
+  /** Get the file path where checkpoint is stored */
+  getPath() {
+    return this.path;
   }
-  if (command.args.some((arg) => wordContainsBlockedCommand(arg, context, mode))) {
-    return true;
+  async save() {
+    const file = {
+      configHash: this.configHash,
+      points: this.points
+    };
+    const content = JSON.stringify(file, null, 2);
+    const tempPath = `${this.path}.tmp`;
+    writeFileSync(tempPath, content);
+    renameSync(tempPath, this.path);
   }
-  if (command.assignments.some(
-    (assignment) => wordContainsBlockedCommand(assignment.value, context, mode) || (assignment.array?.some(
-      (value) => wordContainsBlockedCommand(value, context, mode)
-    ) ?? false)
-  )) {
-    return true;
+};
+function hash(value) {
+  return createHash2("md5").update(JSON.stringify(value)).digest("hex");
+}
+var Point = class {
+  #cache;
+  data;
+  persist;
+  constructor(data, persist) {
+    this.#cache = new Map(
+      data.entries.map((e) => [e.inputHash, e.output])
+    );
+    this.data = data;
+    this.persist = persist;
   }
-  if (command.redirections.some((redirection) => {
-    if (redirection.target.type === "Word") {
-      return wordContainsBlockedCommand(
-        redirection.target,
-        context,
-        mode
-      );
-    }
-    if (redirection.target.type === "HereDoc" && redirection.target.content) {
-      return wordContainsBlockedCommand(
-        redirection.target.content,
-        context,
-        mode
-      );
+  /**
+   * Execute computation if input wasn't processed before.
+   * Returns cached output if input hash exists, otherwise executes, saves, and returns.
+   */
+  async through(input, compute, codec) {
+    const inputHash = hash(input);
+    if (this.#cache.has(inputHash)) {
+      const cached = this.#cache.get(inputHash);
+      return codec ? codec.decode(cached) : cached;
     }
-    return false;
-  })) {
-    return true;
+    const output = await compute();
+    this.data.entries.push({ inputHash, output });
+    this.#cache.set(inputHash, output);
+    await this.persist();
+    return codec ? codec.decode(output) : output;
   }
-  const commandName = asStaticWordText(command.name);
-  if (!commandName) {
-    return false;
+  /** Mark this point as complete. */
+  async commit() {
+    this.data.committed = true;
+    await this.persist();
   }
-  const normalizedName = path.posix.basename(commandName).toLowerCase();
-  if (BLOCKED_DB_CLIENT_COMMANDS.has(normalizedName)) {
-    return true;
+  /** Check if this point has been committed. */
+  isCommitted() {
+    return this.data.committed;
   }
-  if (BLOCKED_RAW_SQL_COMMANDS.has(normalizedName)) {
-    return true;
+  /** Get all outputs from this point. */
+  values() {
+    return this.data.entries.map((e) => e.output);
   }
-  if (normalizedName === "sql") {
-    const subcommand = asStaticWordText(command.args[0])?.toLowerCase();
-    if (!subcommand) {
-      return true;
+};
+function hashConfig(config) {
+  return createHash2("md5").update(JSON.stringify(config)).digest("hex");
+}
+
+// packages/text2sql/src/lib/fs/sqlite/sqlite-fs.ts
+import * as path2 from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+// packages/text2sql/src/lib/fs/sqlite/ddl.sqlite-fs.sql
+var ddl_sqlite_fs_default = "-- SQLite-based filesystem schema for artifact storage\n-- Tables: fs_entries (file/directory metadata), fs_chunks (file content)\n\n-- Performance PRAGMAs (session-level, run on each connection)\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA cache_size = -64000;\nPRAGMA temp_store = MEMORY;\nPRAGMA mmap_size = 268435456;\n\n-- Integrity\nPRAGMA foreign_keys = ON;\n\n-- Filesystem entries table (files, directories, symlinks)\nCREATE TABLE IF NOT EXISTS fs_entries (\n  path TEXT PRIMARY KEY,            -- Normalized absolute path (e.g., '/results/uuid.json')\n  type TEXT NOT NULL,               -- 'file' | 'directory' | 'symlink'\n  mode INTEGER NOT NULL,            -- Unix permissions (e.g., 0o644 = 420)\n  size INTEGER NOT NULL,            -- File size in bytes (0 for directories)\n  mtime INTEGER NOT NULL,           -- Modified time (milliseconds since epoch)\n  symlinkTarget TEXT                -- Target path for symlinks (NULL for files/dirs)\n);\n\nCREATE INDEX IF NOT EXISTS idx_fs_entries_type ON fs_entries(type);\n\n-- File content chunks table (for handling large files)\n-- Files are split into 1MB chunks to avoid SQLite BLOB performance issues\nCREATE TABLE IF NOT EXISTS fs_chunks (\n  path TEXT NOT NULL,               -- Reference to fs_entries.path\n  chunkIndex INTEGER NOT NULL,      -- 0-based chunk sequence\n  data BLOB NOT NULL,               -- Chunk content (up to 1MB default)\n  PRIMARY KEY (path, chunkIndex),\n  FOREIGN KEY (path) REFERENCES fs_entries(path) ON DELETE CASCADE ON UPDATE CASCADE\n);\n";
+
+// packages/text2sql/src/lib/fs/sqlite/sqlite-fs.ts
+var SqliteFs = class {
+  #db;
+  #statements = /* @__PURE__ */ new Map();
+  #chunkSize;
+  #root;
+  constructor(options) {
+    this.#chunkSize = options.chunkSize ?? 1024 * 1024;
+    const normalizedRoot = this.#normalizeRoot(options.root);
+    this.#root = normalizedRoot === "/" ? "" : normalizedRoot;
+    this.#db = new DatabaseSync(options.dbPath);
+    this.#db.exec(ddl_sqlite_fs_default);
+    const rootSlashExists = this.#stmt(
+      "SELECT 1 FROM fs_entries WHERE path = ?"
+    ).get("/");
+    if (!rootSlashExists) {
+      this.#stmt(
+        `INSERT INTO fs_entries (path, type, mode, size, mtime)
+         VALUES ('/', 'directory', 493, 0, ?)`
+      ).run(Date.now());
     }
-    if (mode === "block-all-sql") {
-      return true;
+    if (this.#root) {
+      this.#createParentDirs(this.#root);
+      const rootExists = this.#stmt(
+        "SELECT 1 FROM fs_entries WHERE path = ?"
+      ).get(this.#root);
+      if (!rootExists) {
+        this.#stmt(
+          `INSERT INTO fs_entries (path, type, mode, size, mtime)
+           VALUES (?, 'directory', 493, 0, ?)`
+        ).run(this.#root, Date.now());
+      }
     }
-    return !ALLOWED_SQL_PROXY_SUBCOMMANDS.has(subcommand);
   }
-  const inspectWrappedCommand = (resolved) => {
-    if (resolved.kind === "none") {
-      return false;
+  /**
+   * Create parent directories for a path (used during initialization).
+   * Creates all segments EXCEPT the last one (the path itself).
+   */
+  #createParentDirs(p) {
+    const segments = p.split("/").filter(Boolean);
+    let currentPath = "/";
+    for (let i = 0; i < segments.length - 1; i++) {
+      currentPath = path2.posix.join(currentPath, segments[i]);
+      const exists = this.#stmt("SELECT 1 FROM fs_entries WHERE path = ?").get(
+        currentPath
+      );
+      if (!exists) {
+        this.#stmt(
+          `INSERT INTO fs_entries (path, type, mode, size, mtime)
+           VALUES (?, 'directory', 493, 0, ?)`
+        ).run(currentPath, Date.now());
+      }
     }
-    if (resolved.kind === "unknown" || !resolved.name || !resolved.args) {
-      return true;
+  }
+  #stmt(sql) {
+    let stmt = this.#statements.get(sql);
+    if (!stmt) {
+      stmt = this.#db.prepare(sql);
+      this.#statements.set(sql, stmt);
     }
-    return isBlockedSimpleCommand(
-      {
-        name: resolved.name,
-        args: resolved.args,
-        assignments: [],
-        redirections: []
-      },
-      context,
-      "block-all-sql",
-      options
-    );
-  };
-  if (WRAPPER_COMMANDS.has(normalizedName)) {
-    if (normalizedName === "env") {
-      return inspectWrappedCommand(resolveEnvWrapperCommand(command.args));
-    }
-    if (normalizedName === "command") {
-      return inspectWrappedCommand(resolveCommandWrapperCommand(command.args));
-    }
-    const evalScript = joinStaticWords(command.args);
-    if (evalScript == null) {
-      return true;
+    return stmt;
+  }
+  #normalizeRoot(root) {
+    return path2.posix.resolve("/", root.trim());
+  }
+  #prefixPath(p) {
+    if (!this.#root) {
+      return p;
     }
-    if (!evalScript.trim()) {
-      return false;
+    if (p === "/") {
+      return this.#root;
     }
-    return stringCommandContainsBlockedCommand(
-      evalScript,
-      context,
-      "block-all-sql"
-    );
+    return path2.posix.join(this.#root, p);
   }
-  if (SHELL_INTERPRETER_COMMANDS.has(normalizedName)) {
-    const shellInvocation = getShellInvocationDescriptor(command.args);
-    if (shellInvocation.kind === "unknown") {
-      return true;
-    }
-    if (shellInvocation.kind === "command") {
-      if (!shellInvocation.payload) {
-        return true;
-      }
-      if (stringCommandContainsBlockedCommand(
-        shellInvocation.payload,
-        context,
-        "block-all-sql"
-      )) {
-        return true;
-      }
-      return false;
+  #unprefixPath(p) {
+    if (!this.#root) {
+      return p;
     }
-    const hereDoc = getHereDocPayload(command.redirections);
-    if (hereDoc.hasHereDoc) {
-      if (hereDoc.payload == null) {
-        return true;
-      }
-      if (hereDoc.payload.trim().length > 0 && stringCommandContainsBlockedCommand(
-        hereDoc.payload,
-        context,
-        "block-all-sql"
-      )) {
-        return true;
-      }
+    if (p === this.#root) {
+      return "/";
     }
-    if (shellInvocation.kind === "script") {
-      return true;
+    if (p.startsWith(this.#root + "/")) {
+      return p.slice(this.#root.length) || "/";
     }
-    if (options.stdinFromPipe || shellInvocation.kind === "stdin") {
-      return !hereDoc.hasHereDoc;
+    return p;
+  }
+  #useTransaction(fn) {
+    this.#db.exec("BEGIN TRANSACTION");
+    try {
+      const result = fn();
+      this.#db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      this.#db.exec("ROLLBACK");
+      throw error;
     }
   }
-  if (functionInvocationContainsBlockedCommand(commandName, context, mode)) {
-    return true;
+  #normalizePath(p) {
+    return path2.posix.resolve("/", p);
   }
-  return false;
-}
-var SqlProxyEnforcementPlugin = class {
-  name = "sql-proxy-enforcement";
-  transform(context) {
-    const blocked = scriptContainsBlockedCommand(context.ast, {
-      functionDefinitions: /* @__PURE__ */ new Map(),
-      callStack: /* @__PURE__ */ new Set()
-    });
-    if (blocked) {
-      throw new SqlProxyViolationError();
-    }
-    return {
-      ast: context.ast,
-      metadata: { inspected: true }
-    };
+  #dirname(p) {
+    const dir = path2.posix.dirname(p);
+    return dir === "" ? "/" : dir;
   }
-};
-function wordPartsContainBacktickSubstitution(parts) {
-  for (const part of parts) {
-    if (part.type === "CommandSubstitution" && part.legacy === true) {
-      return true;
-    }
-    if (part.type === "DoubleQuoted" && Array.isArray(part.parts)) {
-      if (wordPartsContainBacktickSubstitution(
-        part.parts
-      )) {
-        return true;
-      }
+  #ensureParentExists(filePath) {
+    const parent = this.#dirname(filePath);
+    const rootPath = this.#root || "/";
+    if (parent === rootPath || parent === "/") return;
+    const entry = this.#stmt("SELECT type FROM fs_entries WHERE path = ?").get(
+      parent
+    );
+    if (!entry) {
+      this.#ensureParentExists(parent);
+      this.#stmt(
+        `INSERT INTO fs_entries (path, type, mode, size, mtime)
+         VALUES (?, 'directory', 493, 0, ?)`
+      ).run(parent, Date.now());
+    } else if (entry.type !== "directory") {
+      throw new Error(`mkdir: parent is not a directory: ${parent}`);
     }
   }
-  return false;
-}
-function isSqlBacktickCommand(cmd) {
-  if (cmd.type !== "SimpleCommand") return false;
-  if (cmd.assignments.length > 0 || cmd.redirections.length > 0) return false;
-  if (asStaticWordText(cmd.name) !== "sql") return false;
-  if (cmd.args.length < 3) return false;
-  const subcommand = asStaticWordText(cmd.args[0]);
-  if (subcommand !== "validate" && subcommand !== "run") return false;
-  const dbName = asStaticWordText(cmd.args[1]);
-  if (!isValidAdapterName(dbName)) return false;
-  const sqlArgs = cmd.args.slice(2);
-  return sqlArgs.some(
-    (arg) => wordPartsContainBacktickSubstitution(
-      arg.parts
-    )
-  );
-}
-function extractWordPartText(parts) {
-  let text = "";
-  for (const part of parts) {
-    const type = part.type;
-    if (type === "Literal" || type === "SingleQuoted" || type === "Escaped") {
-      text += part.value;
-    } else if (type === "DoubleQuoted" && Array.isArray(part.parts)) {
-      text += extractWordPartText(part.parts);
-    } else if (type === "CommandSubstitution" && part.legacy === true) {
-      text += "`" + serialize(part.body).trim() + "`";
+  #writeChunks(filePath, content) {
+    this.#stmt("DELETE FROM fs_chunks WHERE path = ?").run(filePath);
+    for (let i = 0; i < content.length; i += this.#chunkSize) {
+      const chunk = content.slice(
+        i,
+        Math.min(i + this.#chunkSize, content.length)
+      );
+      this.#stmt(
+        "INSERT INTO fs_chunks (path, chunkIndex, data) VALUES (?, ?, ?)"
+      ).run(filePath, Math.floor(i / this.#chunkSize), chunk);
     }
   }
-  return text;
-}
-function extractSqlText(args) {
-  return args.map(
-    (arg) => extractWordPartText(
-      arg.parts
-    )
-  ).join(" ");
-}
-function rewriteSqlBacktickCommand(cmd, ast) {
-  const subcommand = asStaticWordText(cmd.args[0]);
-  const dbName = asStaticWordText(cmd.args[1]);
-  const sqlArgs = cmd.args.slice(2);
-  const unquotedSql = extractSqlText(sqlArgs);
-  const hash2 = createHash("sha256").update(serialize(ast)).digest("hex").slice(0, 12);
-  const sqlPath = `/tmp/sql-inline-${subcommand}-${hash2}.sql`;
-  const heredocTag = `SQL_${hash2.toUpperCase()}`;
-  const groupScript = [
-    `{ cat > ${sqlPath} <<'${heredocTag}'`,
-    unquotedSql,
-    heredocTag,
-    `sql ${subcommand} ${dbName} "$(cat ${sqlPath})"; }`
-  ].join("\n");
-  const groupAst = parse(groupScript);
-  return groupAst.statements[0].pipelines[0].commands[0];
-}
-function rewriteBackticksInCommands(commands, ast) {
-  let rewritten = false;
-  for (let i = 0; i < commands.length; i++) {
-    const cmd = commands[i];
-    if (isSqlBacktickCommand(cmd)) {
-      commands[i] = rewriteSqlBacktickCommand(cmd, ast);
-      rewritten = true;
-      continue;
+  #readChunks(filePath) {
+    const rows = this.#stmt(
+      "SELECT data FROM fs_chunks WHERE path = ? ORDER BY chunkIndex"
+    ).all(filePath);
+    if (rows.length === 0) {
+      return new Uint8Array(0);
     }
-    if (cmd.type === "If") {
-      for (const clause of cmd.clauses) {
-        if (rewriteBackticksInStatements(clause.condition, ast))
-          rewritten = true;
-        if (rewriteBackticksInStatements(clause.body, ast)) rewritten = true;
-      }
-      if (cmd.elseBody && rewriteBackticksInStatements(cmd.elseBody, ast)) {
-        rewritten = true;
-      }
-    } else if (cmd.type === "While" || cmd.type === "Until") {
-      if (rewriteBackticksInStatements(cmd.condition, ast)) rewritten = true;
-      if (rewriteBackticksInStatements(cmd.body, ast)) rewritten = true;
-    } else if (cmd.type === "For" || cmd.type === "CStyleFor") {
-      if (rewriteBackticksInStatements(cmd.body, ast)) rewritten = true;
-    } else if (cmd.type === "Case") {
-      for (const item of cmd.items) {
-        if (rewriteBackticksInStatements(item.body, ast)) rewritten = true;
-      }
-    } else if (cmd.type === "Subshell" || cmd.type === "Group") {
-      if (rewriteBackticksInStatements(cmd.body, ast)) rewritten = true;
+    const totalSize = rows.reduce((sum, row) => sum + row.data.length, 0);
+    const result = new Uint8Array(totalSize);
+    let offset = 0;
+    for (const row of rows) {
+      result.set(row.data, offset);
+      offset += row.data.length;
     }
+    return result;
   }
-  return rewritten;
-}
-function rewriteBackticksInStatements(statements, ast) {
-  let rewritten = false;
-  for (const statement of statements) {
-    for (const pipeline of statement.pipelines) {
-      if (rewriteBackticksInCommands(pipeline.commands, ast)) {
-        rewritten = true;
-      }
+  #resolveSymlink(p, seen = /* @__PURE__ */ new Set()) {
+    if (seen.has(p)) {
+      throw new Error(`readFile: circular symlink: ${p}`);
+    }
+    const entry = this.#stmt(
+      "SELECT type, symlinkTarget FROM fs_entries WHERE path = ?"
+    ).get(p);
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory: ${p}`);
+    }
+    if (entry.type !== "symlink") {
+      return p;
     }
+    seen.add(p);
+    const target = this.#normalizePath(
+      path2.posix.resolve(this.#dirname(p), entry.symlinkTarget)
+    );
+    return this.#resolveSymlink(target, seen);
   }
-  return rewritten;
-}
-var SqlBacktickRewritePlugin = class {
-  name = "sql-backtick-rewrite";
-  transform(context) {
-    const ast = context.ast;
-    const rewritten = rewriteBackticksInStatements(ast.statements, ast);
-    return { ast, metadata: { rewritten } };
-  }
-};
-
-// packages/text2sql/src/lib/agents/sql.agent.ts
-import { groq } from "@ai-sdk/groq";
-import {
-  APICallError,
-  JSONParseError,
-  NoContentGeneratedError,
-  NoObjectGeneratedError,
-  NoOutputGeneratedError,
-  TypeValidationError,
-  defaultSettingsMiddleware,
-  wrapLanguageModel
-} from "ai";
-import dedent from "dedent";
-import pRetry from "p-retry";
-import z from "zod";
-import "@deepagents/agent";
-import {
-  ContextEngine,
-  InMemoryContextStore,
-  example,
-  fragment,
-  guardrail,
-  hint,
-  persona,
-  policy,
-  structuredOutput,
-  user,
-  workflow
-} from "@deepagents/context";
-var RETRY_TEMPERATURES = [0, 0.2, 0.3];
-var SQL_AGENT_ROLE = "Expert SQL query generator.";
-var SQL_AGENT_OBJECTIVE = "Generate precise SQL grounded in provided schema.";
-var SQL_AGENT_POLICIES = [
-  fragment(
-    "schema_mapping",
-    policy({
-      rule: "Translate natural language into precise SQL grounded in available schema entities."
-    }),
-    hint("Preserve schema spelling exactly, including typos in column names.")
-  ),
-  fragment(
-    "projection_minimality",
-    policy({
-      rule: "Return only columns requested by the question; do not add helper columns unless explicitly requested."
-    }),
-    policy({
-      rule: 'For requests of the form "X sorted/ordered by Y", project X only unless Y is explicitly requested as an output field.'
-    }),
-    policy({
-      rule: "Prefer selecting schema columns directly without derived expressions when direct selection answers the request."
-    }),
-    hint(
-      "Do not include ORDER BY, GROUP BY, or JOIN helper columns in SELECT output unless the question explicitly asks for them."
-    ),
-    policy({
-      rule: "Use DISTINCT only when uniqueness is explicitly requested (for example distinct/unique/different/no duplicates)."
-    }),
-    hint(
-      'Do not infer DISTINCT from generic wording such as "some", plural nouns, or entity-set phrasing; for transactional/attendance-style tables, default to raw rows unless uniqueness is explicitly requested.'
-    )
-  ),
-  fragment(
-    "date_transform_safety",
-    policy({
-      rule: "Do not assume VARCHAR/TEXT values are parseable dates. Avoid date extraction functions on text columns by default."
-    }),
-    policy({
-      rule: "Use date-part extraction only when both conditions hold: the question explicitly asks for transformation and schema values require transformation to produce that unit."
-    }),
-    hint(
-      "Do not apply SUBSTR, STRFTIME, DATE_PART, YEAR, or similar extraction functions unless the question explicitly asks for transformation and schema values require it."
-    ),
-    hint(
-      "If a column already represents the requested concept (for example a stored year-like value), use the column as-is."
-    )
-  ),
-  fragment(
-    "sql_minimality",
-    guardrail({
-      rule: "Never hallucinate tables or columns.",
-      reason: "Schema fidelity is required.",
-      action: "Use only available schema entities."
-    }),
-    guardrail({
-      rule: "Avoid unnecessary transformations and derived projections.",
-      reason: "Extra transformations frequently change semantics and reduce correctness.",
-      action: "Do not add date parsing, substring extraction, or derived columns unless explicitly required by the question or schema."
-    })
-  ),
-  fragment(
-    "preflight_checklist",
-    workflow({
-      task: "Final SQL preflight before returning output",
-      steps: [
-        "Verify selected columns match the question and remove unrequested helper projections.",
-        "If aggregate values are used only for ranking/filtering, keep them out of SELECT unless explicitly requested.",
-        "Prefer raw schema columns over derived expressions when raw columns already satisfy the request.",
-        "If a candidate query uses STRFTIME, SUBSTR, DATE_PART, YEAR, or similar extraction on text-like columns, remove that transformation unless explicitly required by the question.",
-        "Return only schema-grounded SQL using existing tables and columns."
-      ]
-    })
-  ),
-  fragment(
-    "set_semantics",
-    policy({
-      rule: "For questions asking where both condition A and condition B hold over an attribute, compute the intersection of qualifying sets for that attribute."
-    }),
-    policy({
-      rule: "Do not force the same entity instance to satisfy both conditions unless the question explicitly requests the same person/row/entity."
-    }),
-    hint(
-      "Prefer INTERSECT (or logically equivalent set-based shape) over requiring the same physical row/entity to satisfy both conditions unless explicitly requested."
-    ),
-    hint(
-      "When two conditions describe different row groups whose shared attribute is requested, build each group separately and intersect the attribute values."
-    ),
-    hint(
-      "Do not collapse cross-group conditions into a single-row AND predicate when the intent is shared values across groups."
-    ),
-    policy({
-      rule: "If two predicates on the same field cannot both be true for one row, do not combine them with AND; use set operations across separate filtered subsets when shared values are requested."
-    })
-  ),
-  fragment(
-    "predicate_column_alignment",
-    policy({
-      rule: "Match literal values to semantically compatible columns. Do not compare descriptive names to identifier columns."
-    }),
-    hint(
-      "When a filter value is a descriptive label (for example a department name), join through the lookup table and filter on its name/title column, not on *_id columns."
-    ),
-    hint(
-      "When relation roles are explicit in wording (for example host/home/source/destination), prefer foreign keys with matching role qualifiers over generic similarly named columns."
-    ),
-    policy({
-      rule: "When multiple foreign-key candidates exist, select the column whose qualifier best matches the relationship described in the question."
-    }),
-    policy({
-      rule: "For hosting/held semantics, prefer host_* relationship columns when available over generic *_id alternatives."
-    }),
-    hint(
-      'Interpret wording like "held/hosted a competition or event" as a hosting relationship and map to host_* foreign keys when present.'
-    ),
-    policy({
-      rule: "Do not compare descriptive labels or names to *_id columns; join to the table containing the descriptive field and filter there."
-    }),
-    policy({
-      rule: "Keep numeric identifiers unquoted when used as numeric equality filters unless schema indicates text identifiers."
-    }),
-    policy({
-      rule: "When filtering by a descriptive label value and a related table exposes a corresponding *_name or title column, join to that table and filter on the descriptive column."
-    })
-  ),
-  fragment(
-    "ordering_semantics",
-    policy({
-      rule: "Respect explicit sort direction terms. If direction is not specified, use ascending order unless a superlative intent (most/least/highest/lowest) implies direction."
-    }),
-    policy({
-      rule: "When ranking categories by frequency, use COUNT for ordering but keep output focused on requested category fields unless counts are explicitly requested."
-    }),
-    policy({
-      rule: "Do not use DESC unless descending direction is explicit or a superlative intent requires descending ranking."
-    }),
-    policy({
-      rule: 'For "most common/frequent <attribute>" requests, return the attribute value(s) only; use counts only for ordering/filtering unless the question explicitly asks to return counts.'
-    }),
-    hint(
-      'Use DESC with LIMIT 1 for "most/highest/largest"; use ASC with LIMIT 1 for "least/lowest/smallest".'
-    )
-  ),
-  fragment(
-    "negative_membership_queries",
-    policy({
-      rule: "For requests asking entities that did not participate/host/appear in related records, prefer NOT IN or NOT EXISTS against the related foreign-key set."
-    }),
-    hint(
-      "Map role-bearing relationship columns carefully (for example host_* foreign keys for hosting relationships) instead of generic IDs when role wording is explicit."
-    ),
-    hint(
-      'For "never had/never exceeded" conditions over history tables, exclude entities via NOT IN/NOT EXISTS against the disqualifying entity-id set (often built with GROUP BY/HAVING MAX(...)).'
-    )
-  ),
-  fragment(
-    "join_completeness",
-    policy({
-      rule: "Preserve entity-restricting joins implied by the question. Do not widen results by querying only a broader attribute table when a subset entity table is available."
-    }),
-    policy({
-      rule: "If an entity term in the question maps to a table, keep that table in query scope and join to attribute tables rather than dropping the entity table."
-    }),
-    hint(
-      "If the question targets a specific entity group, include that entity table and its join conditions even when selected columns come from a related table."
-    ),
-    hint(
-      "When the question names an entity type and a relation table links to that entity via *_id, include the entity table in scope instead of counting only relation rows."
-    ),
-    hint(
-      "Prefer INNER JOIN by default; use LEFT JOIN only when the question explicitly requests including unmatched rows or zero-related entities."
-    )
-  ),
-  fragment(
-    "aggregation_exactness",
-    policy({
-      rule: "Preserve requested aggregation semantics exactly: use COUNT(*) by default for total rows, use COUNT(DISTINCT ...) only when uniqueness is explicitly requested, and group by stable entity keys when computing per-entity aggregates."
-    }),
-    policy({
-      rule: "For questions asking which entity has lowest/highest average of a metric, compute AVG(metric) per entity (GROUP BY entity) and rank those aggregates."
-    }),
-    hint(
-      'For "how many <entities>" questions over relation records, default to COUNT(*) on qualifying rows unless explicit uniqueness language is present.'
-    )
-  ),
-  fragment(
-    "query_shape_examples",
-    example({
-      question: "List categories ordered by how many records belong to each category.",
-      answer: "SELECT category FROM records GROUP BY category ORDER BY COUNT(*)"
-    }),
-    example({
-      question: "Show labels shared by rows with metric > 100 and rows with metric < 10.",
-      answer: "SELECT label FROM records WHERE metric > 100 INTERSECT SELECT label FROM records WHERE metric < 10"
-    }),
-    example({
-      question: "List locations that have not hosted any event.",
-      answer: "SELECT location_name FROM locations WHERE location_id NOT IN (SELECT host_location_id FROM events)"
-    }),
-    example({
-      question: "List the most common category across records.",
-      answer: "SELECT category FROM records GROUP BY category ORDER BY COUNT(*) DESC LIMIT 1"
-    })
-  )
-];
-function extractSql(output) {
-  const match = output.match(/```sql\n?([\s\S]*?)```/);
-  return match ? match[1].trim() : output.trim();
-}
-async function toSql(options) {
-  const { maxRetries = 3 } = options;
-  return withRetry(
-    async (attemptNumber, errors, attempts) => {
-      const context = new ContextEngine({
-        store: new InMemoryContextStore(),
-        chatId: `sql-gen-${crypto.randomUUID()}`,
-        userId: "system"
-      });
-      context.set(
-        persona({
-          name: "Freya",
-          role: SQL_AGENT_ROLE,
-          objective: SQL_AGENT_OBJECTIVE
-          // role: `You are a data science expert that provides well-reasoned and detailed responses.`,
-          // objective: `Your task is to understand the schema and generate a valid SQL query to answer the question. You first think about the reasoning process as an internal monologue and then provide the user with the answer.`,
-        }),
-        ...SQL_AGENT_POLICIES,
-        ...options.fragments
-      );
-      if (errors.length) {
-        const lastError = errors.at(-1);
-        context.set(
-          user(dedent`
-            Answer the following question with the SQL code. Use the piece of evidence and base your answer on the database schema.
-Given the question, the evidence and the database schema, return the SQL script that addresses the question.
-
-Question: ${options.input}
-`),
-          UnanswerableSQLError.isInstance(lastError) ? user(
-            `<retry_instruction>Your previous response marked the task as unanswerable. Re-evaluate using best-effort schema mapping. If the core intent is answerable with existing tables/columns, return SQL. Return error only when required core intent cannot be mapped without inventing schema elements.</retry_instruction>`
-          ) : user(
-            `<validation_error>Your previous SQL query had the following error: ${lastError?.message}. Please fix the query.</validation_error>`
-          )
-        );
-      } else {
-        context.set(
-          user(dedent`
-            Answer the following question with the SQL code. Use the piece of evidence and base your answer on the database schema.
-Given the question, the evidence and the database schema, return the SQL script that addresses the question.
-
-Question: ${options.input}
-`)
-        );
-      }
-      const temperature = RETRY_TEMPERATURES[attemptNumber - 1] ?? RETRY_TEMPERATURES[RETRY_TEMPERATURES.length - 1];
-      const baseModel = options.model ?? groq("openai/gpt-oss-20b");
-      const model = wrapLanguageModel({
-        model: baseModel,
-        middleware: defaultSettingsMiddleware({ settings: { temperature } })
-      });
-      const sqlOutput = structuredOutput({
-        model,
-        context,
-        schema: z.object({
-          result: z.union([
-            z.object({
-              sql: z.string().describe("The SQL query that answers the question"),
-              reasoning: z.string().describe("The reasoning steps taken to generate the SQL")
-            }),
-            z.object({
-              error: z.string().describe(
-                "Error message explaining why the question cannot be answered with the given schema"
-              )
-            })
-          ])
-        })
-      });
-      const { result: output } = await sqlOutput.generate();
-      const finalizeSql = async (rawSql) => {
-        const sql = options.adapter.format(extractSql(rawSql));
-        const validationError = await options.adapter.validate(sql);
-        if (validationError) {
-          throw new SQLValidationError(validationError);
-        }
-        return {
-          attempts,
-          sql,
-          errors: errors.length ? errors.map(formatErrorMessage) : void 0
-        };
-      };
-      if ("error" in output) {
-        context.set(
-          user(
-            "<best_effort_fallback>Do not return unanswerable. Produce the best valid SQL query that answers the core intent using only available schema entities.</best_effort_fallback>"
-          )
-        );
-        const forcedSqlOutput = structuredOutput({
-          model,
-          context,
-          schema: z.object({
-            sql: z.string().describe(
-              "Best-effort SQL query that answers the core intent using only available schema entities."
-            ),
-            reasoning: z.string().describe("Reasoning steps for best-effort schema mapping.")
-          })
-        });
-        try {
-          const forced = await forcedSqlOutput.generate();
-          return await finalizeSql(forced.sql);
-        } catch (error) {
-          if (SQLValidationError.isInstance(error) || APICallError.isInstance(error) || JSONParseError.isInstance(error) || TypeValidationError.isInstance(error) || NoObjectGeneratedError.isInstance(error) || NoOutputGeneratedError.isInstance(error) || NoContentGeneratedError.isInstance(error)) {
-            throw error;
-          }
-          throw new UnanswerableSQLError(output.error);
-        }
-      }
-      return await finalizeSql(output.sql);
-    },
-    { retries: maxRetries - 1 }
-  );
-}
-function formatErrorMessage(error) {
-  if (APICallError.isInstance(error)) {
-    if (error.message.startsWith("Failed to validate JSON")) {
-      return `Schema validation failed: ${error.message}`;
-    }
-    return error.message;
-  }
-  if (SQLValidationError.isInstance(error)) {
-    return `SQL Validation Error: ${error.message}`;
-  }
-  return error.message;
-}
-function isModelUnavailableError(error) {
-  if (!APICallError.isInstance(error)) {
-    return false;
-  }
-  const message = error.message.toLowerCase();
-  const responseBody = (error.responseBody ?? "").toLowerCase();
-  const is404ModelError = error.statusCode === 404 && (message.includes("model") || responseBody.includes("model_not_found"));
-  const errorCode = typeof error.data === "object" && error.data !== null && "error" in error.data && typeof error.data.error === "object" && error.data.error !== null && "code" in error.data.error && typeof error.data.error.code === "string" ? error.data.error.code.toLowerCase() : void 0;
-  return is404ModelError || errorCode === "model_not_found" || responseBody.includes('"code":"model_not_found"') || message.includes("model") && message.includes("does not exist or you do not have access to it");
-}
-async function withRetry(computation, options = { retries: 3 }) {
-  const errors = [];
-  let attempts = 0;
-  return pRetry(
-    (attemptNumber) => {
-      return computation(attemptNumber, errors, ++attempts);
-    },
-    {
-      retries: options.retries,
-      shouldRetry: (context) => {
-        if (UnanswerableSQLError.isInstance(context.error)) {
-          return false;
-        }
-        if (isModelUnavailableError(context.error)) {
-          return false;
-        }
-        if (SQLValidationError.isInstance(context.error)) {
-          return true;
-        }
-        console.log({
-          NoObjectGeneratedError: NoObjectGeneratedError.isInstance(
-            context.error
-          ),
-          NoOutputGeneratedError: NoOutputGeneratedError.isInstance(
-            context.error
-          ),
-          APICallError: APICallError.isInstance(context.error),
-          JSONParseError: JSONParseError.isInstance(context.error),
-          TypeValidationError: TypeValidationError.isInstance(context.error),
-          NoContentGeneratedError: NoContentGeneratedError.isInstance(
-            context.error
-          )
-        });
-        return APICallError.isInstance(context.error) || JSONParseError.isInstance(context.error) || TypeValidationError.isInstance(context.error) || NoObjectGeneratedError.isInstance(context.error) || NoOutputGeneratedError.isInstance(context.error) || NoContentGeneratedError.isInstance(context.error);
-      },
-      onFailedAttempt(context) {
-        errors.push(context.error);
-      }
-    }
-  );
-}
-
-// packages/text2sql/src/lib/agents/suggestions.agents.ts
-import { groq as groq2 } from "@ai-sdk/groq";
-import dedent2 from "dedent";
-import z2 from "zod";
-import { agent, thirdPersonPrompt } from "@deepagents/agent";
-var suggestionsAgent = agent({
-  name: "text2sql-suggestions",
-  model: groq2("openai/gpt-oss-20b"),
-  output: z2.object({
-    suggestions: z2.array(
-      z2.object({
-        question: z2.string().describe("A complex, high-impact business question."),
-        sql: z2.string().describe("The SQL statement needed to answer the question."),
-        businessValue: z2.string().describe("Why the question matters to stakeholders.")
-      })
-    ).min(1).max(5).describe("A set of up to two advanced question + SQL pairs.")
-  }),
-  prompt: (state) => {
-    return dedent2`
-      ${thirdPersonPrompt()}
-
-      <identity>
-        You are a senior analytics strategist who proposes ambitious business questions
-        and drafts the SQL needed to answer them. You specialize in identifying ideas
-        that combine multiple tables, apply segmentation or time analysis, and surface
-        metrics that drive executive decisions.
-      </identity>
-
-
-      <instructions>
-        - Recommend one or two UNIQUE questions that go beyond simple counts or listings.
-        - Favor questions that require joins, aggregates, time comparisons, cohort analysis,
-          or window functions.
-        - For each question, explain the business reason stakeholders care about it.
-        - Provide the complete SQL query that could answer the question in the given schema.
-        - Keep result sets scoped with LIMIT clauses (max 50 rows) when returning raw rows.
-        - Ensure table/column names match the provided schema exactly.
-        - Use columns marked [LowCardinality: ...] to identify meaningful categorical filters or segmentations.
-        - Leverage table [rows / size] hints to determine whether to aggregate (large tables) or inspect detailed data (tiny tables).
-        - Reference PK/Indexed annotations and the Indexes list to recommend queries that use efficient join/filter paths.
-        - Column annotations may expose ranges/null percentages—use them to suggest realistic thresholds or quality checks.
-        - Consult <relationship_examples> to anchor your recommendations in the actual join paths between tables.
-        - Output only information grounded in the schema/context provided.
-      </instructions>
-
-      <response-format>
-        Return valid JSON that satisfies the defined output schema.
-      </response-format>
-    `;
-  }
-});
-
-// packages/text2sql/src/lib/checkpoint.ts
-import { createHash as createHash2 } from "node:crypto";
-import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import pLimit from "p-limit";
-var Checkpoint = class _Checkpoint {
-  points;
-  path;
-  configHash;
-  constructor(path6, configHash, points) {
-    this.points = points;
-    this.path = path6;
-    this.configHash = configHash;
-  }
-  /**
-   * Load checkpoint from file, or return empty checkpoint if none exists.
-   * Handles corrupted files and config changes gracefully.
-   */
-  static async load(options) {
-    const { path: path6, configHash } = options;
-    if (existsSync(path6)) {
-      try {
-        const content = readFileSync(path6, "utf-8");
-        const file = JSON.parse(content);
-        if (configHash && file.configHash && file.configHash !== configHash) {
-          console.log("\u26A0 Config changed, starting fresh");
-          return new _Checkpoint(path6, configHash, {});
-        }
-        const points = file.points ?? {};
-        const totalEntries = Object.values(points).reduce(
-          (sum, p) => sum + p.entries.length,
-          0
-        );
-        console.log(`\u2713 Resuming from checkpoint (${totalEntries} entries)`);
-        return new _Checkpoint(path6, configHash, points);
-      } catch {
-        console.log("\u26A0 Checkpoint corrupted, starting fresh");
-        return new _Checkpoint(path6, configHash, {});
-      }
-    }
-    console.log("Starting new checkpoint");
-    return new _Checkpoint(path6, configHash, {});
-  }
-  /**
-   * Run a single computation with checkpointing.
-   * If already completed, returns cached value.
-   *
-   * @param key - Unique identifier for this computation
-   * @param computation - Async function that produces the value
-   * @param codec - Optional codec for encoding/decoding non-primitive values
-   */
-  async run(key, computation, codec) {
-    const point = this.point(key);
-    return point.through(
-      "single",
-      async () => {
-        const result = await computation();
-        return codec ? codec.encode(result) : result;
-      },
-      codec
-    );
-  }
-  /**
-   * Create a resumable checkpoint point for iterative operations.
-   *
-   * @param step - Unique identifier for this checkpoint point
-   */
-  point(step) {
-    this.points[step] ??= { committed: false, entries: [] };
-    return new Point(this.points[step], () => this.save());
-  }
-  /**
-   * Process each input with automatic checkpointing and concurrency.
-   *
-   * @param step - Unique identifier for this checkpoint
-   * @param inputs - Items to process
-   * @param process - Function to process each input
-   * @param options - Optional settings like concurrency
-   * @returns All outputs (use `.flat()` if outputs are arrays)
-   */
-  async each(step, inputs, process, options) {
-    const point = this.point(step);
-    const limit = pLimit(options?.concurrency ?? 1);
-    const inputArray = Array.from(inputs);
-    await Promise.all(
-      inputArray.map(
-        (input) => limit(() => point.through(input, () => process(input)))
-      )
-    );
-    await point.commit();
-    return point.values();
-  }
-  /**
-   * Get clean output from all completed points.
-   * Single-entry points return the value directly, multi-entry return arrays.
-   */
-  getOutput() {
-    const output = {};
-    for (const [key, pointData] of Object.entries(this.points)) {
-      if (pointData.entries.length === 1) {
-        output[key] = pointData.entries[0].output;
-      } else {
-        output[key] = pointData.entries.map((e) => e.output);
-      }
-    }
-    return output;
-  }
-  /** Get the file path where checkpoint is stored */
-  getPath() {
-    return this.path;
-  }
-  async save() {
-    const file = {
-      configHash: this.configHash,
-      points: this.points
-    };
-    const content = JSON.stringify(file, null, 2);
-    const tempPath = `${this.path}.tmp`;
-    writeFileSync(tempPath, content);
-    renameSync(tempPath, this.path);
-  }
-};
-function hash(value) {
-  return createHash2("md5").update(JSON.stringify(value)).digest("hex");
-}
-var Point = class {
-  #cache;
-  data;
-  persist;
-  constructor(data, persist) {
-    this.#cache = new Map(
-      data.entries.map((e) => [e.inputHash, e.output])
-    );
-    this.data = data;
-    this.persist = persist;
-  }
-  /**
-   * Execute computation if input wasn't processed before.
-   * Returns cached output if input hash exists, otherwise executes, saves, and returns.
-   */
-  async through(input, compute, codec) {
-    const inputHash = hash(input);
-    if (this.#cache.has(inputHash)) {
-      const cached = this.#cache.get(inputHash);
-      return codec ? codec.decode(cached) : cached;
-    }
-    const output = await compute();
-    this.data.entries.push({ inputHash, output });
-    this.#cache.set(inputHash, output);
-    await this.persist();
-    return codec ? codec.decode(output) : output;
-  }
-  /** Mark this point as complete. */
-  async commit() {
-    this.data.committed = true;
-    await this.persist();
-  }
-  /** Check if this point has been committed. */
-  isCommitted() {
-    return this.data.committed;
-  }
-  /** Get all outputs from this point. */
-  values() {
-    return this.data.entries.map((e) => e.output);
-  }
-};
-function hashConfig(config) {
-  return createHash2("md5").update(JSON.stringify(config)).digest("hex");
-}
-
-// packages/text2sql/src/lib/file-cache.ts
-import { createHash as createHash3 } from "node:crypto";
-import { existsSync as existsSync2 } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path2 from "node:path";
-var FileCache = class {
-  path;
-  constructor(watermark, extension = ".txt") {
-    const hash2 = createHash3("md5").update(watermark).digest("hex");
-    this.path = path2.join(tmpdir(), `text2sql-${hash2}${extension}`);
-  }
-  async get() {
-    if (existsSync2(this.path)) {
-      return readFile(this.path, "utf-8");
-    }
-    return null;
-  }
-  set(content) {
-    return writeFile(this.path, content, "utf-8");
-  }
-};
-var JsonCache = class extends FileCache {
-  constructor(watermark) {
-    super(watermark, ".json");
-  }
-  async read() {
-    const content = await this.get();
-    if (content) {
-      return JSON.parse(content);
-    }
-    return null;
-  }
-  write(data) {
-    return this.set(JSON.stringify(data));
-  }
-};
-
-// packages/text2sql/src/lib/fs/sqlite/sqlite-fs.ts
-import * as path3 from "node:path";
-import { DatabaseSync } from "node:sqlite";
-
-// packages/text2sql/src/lib/fs/sqlite/ddl.sqlite-fs.sql
-var ddl_sqlite_fs_default = "-- SQLite-based filesystem schema for artifact storage\n-- Tables: fs_entries (file/directory metadata), fs_chunks (file content)\n\n-- Performance PRAGMAs (session-level, run on each connection)\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA cache_size = -64000;\nPRAGMA temp_store = MEMORY;\nPRAGMA mmap_size = 268435456;\n\n-- Integrity\nPRAGMA foreign_keys = ON;\n\n-- Filesystem entries table (files, directories, symlinks)\nCREATE TABLE IF NOT EXISTS fs_entries (\n  path TEXT PRIMARY KEY,            -- Normalized absolute path (e.g., '/results/uuid.json')\n  type TEXT NOT NULL,               -- 'file' | 'directory' | 'symlink'\n  mode INTEGER NOT NULL,            -- Unix permissions (e.g., 0o644 = 420)\n  size INTEGER NOT NULL,            -- File size in bytes (0 for directories)\n  mtime INTEGER NOT NULL,           -- Modified time (milliseconds since epoch)\n  symlinkTarget TEXT                -- Target path for symlinks (NULL for files/dirs)\n);\n\nCREATE INDEX IF NOT EXISTS idx_fs_entries_type ON fs_entries(type);\n\n-- File content chunks table (for handling large files)\n-- Files are split into 1MB chunks to avoid SQLite BLOB performance issues\nCREATE TABLE IF NOT EXISTS fs_chunks (\n  path TEXT NOT NULL,               -- Reference to fs_entries.path\n  chunkIndex INTEGER NOT NULL,      -- 0-based chunk sequence\n  data BLOB NOT NULL,               -- Chunk content (up to 1MB default)\n  PRIMARY KEY (path, chunkIndex),\n  FOREIGN KEY (path) REFERENCES fs_entries(path) ON DELETE CASCADE ON UPDATE CASCADE\n);\n";
-
-// packages/text2sql/src/lib/fs/sqlite/sqlite-fs.ts
-var SqliteFs = class {
-  #db;
-  #statements = /* @__PURE__ */ new Map();
-  #chunkSize;
-  #root;
-  constructor(options) {
-    this.#chunkSize = options.chunkSize ?? 1024 * 1024;
-    const normalizedRoot = this.#normalizeRoot(options.root);
-    this.#root = normalizedRoot === "/" ? "" : normalizedRoot;
-    this.#db = new DatabaseSync(options.dbPath);
-    this.#db.exec(ddl_sqlite_fs_default);
-    const rootSlashExists = this.#stmt(
-      "SELECT 1 FROM fs_entries WHERE path = ?"
-    ).get("/");
-    if (!rootSlashExists) {
-      this.#stmt(
-        `INSERT INTO fs_entries (path, type, mode, size, mtime)
-         VALUES ('/', 'directory', 493, 0, ?)`
-      ).run(Date.now());
-    }
-    if (this.#root) {
-      this.#createParentDirs(this.#root);
-      const rootExists = this.#stmt(
-        "SELECT 1 FROM fs_entries WHERE path = ?"
-      ).get(this.#root);
-      if (!rootExists) {
-        this.#stmt(
-          `INSERT INTO fs_entries (path, type, mode, size, mtime)
-           VALUES (?, 'directory', 493, 0, ?)`
-        ).run(this.#root, Date.now());
-      }
-    }
-  }
-  /**
-   * Create parent directories for a path (used during initialization).
-   * Creates all segments EXCEPT the last one (the path itself).
-   */
-  #createParentDirs(p) {
-    const segments = p.split("/").filter(Boolean);
-    let currentPath = "/";
-    for (let i = 0; i < segments.length - 1; i++) {
-      currentPath = path3.posix.join(currentPath, segments[i]);
-      const exists = this.#stmt("SELECT 1 FROM fs_entries WHERE path = ?").get(
-        currentPath
-      );
-      if (!exists) {
-        this.#stmt(
-          `INSERT INTO fs_entries (path, type, mode, size, mtime)
-           VALUES (?, 'directory', 493, 0, ?)`
-        ).run(currentPath, Date.now());
-      }
-    }
-  }
-  #stmt(sql) {
-    let stmt = this.#statements.get(sql);
-    if (!stmt) {
-      stmt = this.#db.prepare(sql);
-      this.#statements.set(sql, stmt);
-    }
-    return stmt;
-  }
-  #normalizeRoot(root) {
-    return path3.posix.resolve("/", root.trim());
-  }
-  #prefixPath(p) {
-    if (!this.#root) {
-      return p;
-    }
-    if (p === "/") {
-      return this.#root;
-    }
-    return path3.posix.join(this.#root, p);
-  }
-  #unprefixPath(p) {
-    if (!this.#root) {
-      return p;
-    }
-    if (p === this.#root) {
-      return "/";
-    }
-    if (p.startsWith(this.#root + "/")) {
-      return p.slice(this.#root.length) || "/";
-    }
-    return p;
-  }
-  #useTransaction(fn) {
-    this.#db.exec("BEGIN TRANSACTION");
-    try {
-      const result = fn();
-      this.#db.exec("COMMIT");
-      return result;
-    } catch (error) {
-      this.#db.exec("ROLLBACK");
-      throw error;
-    }
-  }
-  #normalizePath(p) {
-    return path3.posix.resolve("/", p);
-  }
-  #dirname(p) {
-    const dir = path3.posix.dirname(p);
-    return dir === "" ? "/" : dir;
-  }
-  #ensureParentExists(filePath) {
-    const parent = this.#dirname(filePath);
-    const rootPath = this.#root || "/";
-    if (parent === rootPath || parent === "/") return;
-    const entry = this.#stmt("SELECT type FROM fs_entries WHERE path = ?").get(
-      parent
-    );
-    if (!entry) {
-      this.#ensureParentExists(parent);
-      this.#stmt(
-        `INSERT INTO fs_entries (path, type, mode, size, mtime)
-         VALUES (?, 'directory', 493, 0, ?)`
-      ).run(parent, Date.now());
-    } else if (entry.type !== "directory") {
-      throw new Error(`mkdir: parent is not a directory: ${parent}`);
-    }
-  }
-  #writeChunks(filePath, content) {
-    this.#stmt("DELETE FROM fs_chunks WHERE path = ?").run(filePath);
-    for (let i = 0; i < content.length; i += this.#chunkSize) {
-      const chunk = content.slice(
-        i,
-        Math.min(i + this.#chunkSize, content.length)
-      );
-      this.#stmt(
-        "INSERT INTO fs_chunks (path, chunkIndex, data) VALUES (?, ?, ?)"
-      ).run(filePath, Math.floor(i / this.#chunkSize), chunk);
-    }
-  }
-  #readChunks(filePath) {
-    const rows = this.#stmt(
-      "SELECT data FROM fs_chunks WHERE path = ? ORDER BY chunkIndex"
-    ).all(filePath);
-    if (rows.length === 0) {
-      return new Uint8Array(0);
-    }
-    const totalSize = rows.reduce((sum, row) => sum + row.data.length, 0);
-    const result = new Uint8Array(totalSize);
-    let offset = 0;
-    for (const row of rows) {
-      result.set(row.data, offset);
-      offset += row.data.length;
-    }
-    return result;
-  }
-  #resolveSymlink(p, seen = /* @__PURE__ */ new Set()) {
-    if (seen.has(p)) {
-      throw new Error(`readFile: circular symlink: ${p}`);
-    }
-    const entry = this.#stmt(
-      "SELECT type, symlinkTarget FROM fs_entries WHERE path = ?"
-    ).get(p);
-    if (!entry) {
-      throw new Error(`ENOENT: no such file or directory: ${p}`);
-    }
-    if (entry.type !== "symlink") {
-      return p;
-    }
-    seen.add(p);
-    const target = this.#normalizePath(
-      path3.posix.resolve(this.#dirname(p), entry.symlinkTarget)
-    );
-    return this.#resolveSymlink(target, seen);
-  }
-  #toUint8Array(content, encoding) {
-    if (content instanceof Uint8Array) {
-      return content;
-    }
-    const enc = encoding ?? "utf8";
-    return new Uint8Array(Buffer.from(content, enc));
+  #toUint8Array(content, encoding) {
+    if (content instanceof Uint8Array) {
+      return content;
+    }
+    const enc = encoding ?? "utf8";
+    return new Uint8Array(Buffer.from(content, enc));
   }
   // ============================================================================
   // IFileSystem Implementation
@@ -2619,11 +1956,11 @@ var SqliteFs = class {
     this.#useTransaction(() => {
       if (options?.recursive) {
         const rootPath = this.#root || "/";
-        const relativePath = path3.posix.relative(rootPath, prefixed);
+        const relativePath = path2.posix.relative(rootPath, prefixed);
         const segments = relativePath.split("/").filter(Boolean);
         let currentPath = rootPath;
         for (const segment of segments) {
-          currentPath = path3.posix.join(currentPath, segment);
+          currentPath = path2.posix.join(currentPath, segment);
           const exists = this.#stmt(
             "SELECT type FROM fs_entries WHERE path = ?"
           ).get(currentPath);
@@ -2674,7 +2011,7 @@ var SqliteFs = class {
          AND path != ?
          AND path NOT LIKE ? || '%/%'`
     ).all(prefix, resolved, prefix);
-    return rows.map((row) => path3.posix.basename(row.path));
+    return rows.map((row) => path2.posix.basename(row.path));
   }
   async readdirWithFileTypes(dirPath) {
     const normalized = this.#normalizePath(dirPath);
@@ -2697,7 +2034,7 @@ var SqliteFs = class {
          AND path NOT LIKE ? || '%/%'`
     ).all(prefix, resolved, prefix);
     return rows.map((row) => ({
-      name: path3.posix.basename(row.path),
+      name: path2.posix.basename(row.path),
       isFile: row.type === "file",
       isDirectory: row.type === "directory",
       isSymbolicLink: row.type === "symlink"
@@ -2752,8 +2089,8 @@ var SqliteFs = class {
           `SELECT * FROM fs_entries WHERE path = ? OR path LIKE ? || '/%'`
         ).all(srcPrefixed, srcPrefixed);
         for (const entry of allEntries) {
-          const relativePath = path3.posix.relative(srcPrefixed, entry.path);
-          const newPath = path3.posix.join(destPrefixed, relativePath);
+          const relativePath = path2.posix.relative(srcPrefixed, entry.path);
+          const newPath = path2.posix.join(destPrefixed, relativePath);
           this.#stmt(
             `INSERT OR REPLACE INTO fs_entries (path, type, mode, size, mtime, symlinkTarget)
              VALUES (?, ?, ?, ?, ?, ?)`
@@ -2820,8 +2157,8 @@ var SqliteFs = class {
           `SELECT * FROM fs_entries WHERE path = ? OR path LIKE ? || '/%' ORDER BY path DESC`
         ).all(srcPrefixed, srcPrefixed);
         for (const entry of [...allEntries].reverse()) {
-          const relativePath = path3.posix.relative(srcPrefixed, entry.path);
-          const newPath = path3.posix.join(destPrefixed, relativePath);
+          const relativePath = path2.posix.relative(srcPrefixed, entry.path);
+          const newPath = path2.posix.join(destPrefixed, relativePath);
           this.#stmt(
             `INSERT INTO fs_entries (path, type, mode, size, mtime, symlinkTarget)
              VALUES (?, ?, ?, ?, ?, ?)`
@@ -2874,7 +2211,7 @@ var SqliteFs = class {
     });
   }
   resolvePath(base, relativePath) {
-    return path3.posix.resolve(base, relativePath);
+    return path2.posix.resolve(base, relativePath);
   }
   getAllPaths() {
     const rows = this.#stmt(
@@ -2986,7 +2323,7 @@ var SqliteFs = class {
 
 // packages/text2sql/src/lib/fs/mssql/mssql-fs.ts
 import { createRequire } from "node:module";
-import * as path4 from "node:path";
+import * as path3 from "node:path";
 
 // packages/text2sql/src/lib/fs/mssql/ddl.mssql-fs.ts
 function mssqlFsDDL(schema) {
@@ -3112,7 +2449,7 @@ var MssqlFs = class _MssqlFs {
     const segments = p.split("/").filter(Boolean);
     let currentPath = "/";
     for (let i = 0; i < segments.length - 1; i++) {
-      currentPath = path4.posix.join(currentPath, segments[i]);
+      currentPath = path3.posix.join(currentPath, segments[i]);
       const exists = await this.#rawQuery(
         `SELECT CASE WHEN EXISTS(SELECT 1 FROM ${this.#t("fs_entries")} WHERE path = @p0) THEN 1 ELSE 0 END as [exists]`,
         [currentPath]
@@ -3164,7 +2501,7 @@ var MssqlFs = class _MssqlFs {
     }
   }
   #normalizeRoot(root) {
-    return path4.posix.resolve("/", root.trim());
+    return path3.posix.resolve("/", root.trim());
   }
   #prefixPath(p) {
     if (!this.#root) {
@@ -3173,7 +2510,7 @@ var MssqlFs = class _MssqlFs {
     if (p === "/") {
       return this.#root;
     }
-    return path4.posix.join(this.#root, p);
+    return path3.posix.join(this.#root, p);
   }
   #unprefixPath(p) {
     if (!this.#root) {
@@ -3188,10 +2525,10 @@ var MssqlFs = class _MssqlFs {
     return p;
   }
   #normalizePath(p) {
-    return path4.posix.resolve("/", p);
+    return path3.posix.resolve("/", p);
   }
   #dirname(p) {
-    const dir = path4.posix.dirname(p);
+    const dir = path3.posix.dirname(p);
     return dir === "" ? "/" : dir;
   }
   async #ensureParentExists(filePath, transaction) {
@@ -3280,7 +2617,7 @@ var MssqlFs = class _MssqlFs {
     }
     seen.add(p);
     const target = this.#normalizePath(
-      path4.posix.resolve(this.#dirname(p), entry.symlinkTarget)
+      path3.posix.resolve(this.#dirname(p), entry.symlinkTarget)
     );
     return this.#resolveSymlink(target, seen);
   }
@@ -3463,11 +2800,11 @@ var MssqlFs = class _MssqlFs {
     await this.#useTransaction(async (transaction) => {
       if (options?.recursive) {
         const rootPath = this.#root || "/";
-        const relativePath = path4.posix.relative(rootPath, prefixed);
+        const relativePath = path3.posix.relative(rootPath, prefixed);
         const segments = relativePath.split("/").filter(Boolean);
         let currentPath = rootPath;
         for (const segment of segments) {
-          currentPath = path4.posix.join(currentPath, segment);
+          currentPath = path3.posix.join(currentPath, segment);
           const checkReq = transaction.request();
           checkReq.input("p0", currentPath);
           const result = await checkReq.query(
@@ -3531,7 +2868,7 @@ var MssqlFs = class _MssqlFs {
          AND path NOT LIKE @p0 + '%/%'`,
       [prefix, resolved]
     );
-    return rows.map((row) => path4.posix.basename(row.path));
+    return rows.map((row) => path3.posix.basename(row.path));
   }
   async readdirWithFileTypes(dirPath) {
     const normalized = this.#normalizePath(dirPath);
@@ -3557,7 +2894,7 @@ var MssqlFs = class _MssqlFs {
       [prefix, resolved]
     );
     return rows.map((row) => ({
-      name: path4.posix.basename(row.path),
+      name: path3.posix.basename(row.path),
       isFile: row.type === "file",
       isDirectory: row.type === "directory",
       isSymbolicLink: row.type === "symlink"
@@ -3626,8 +2963,8 @@ var MssqlFs = class _MssqlFs {
           `SELECT * FROM ${this.#t("fs_entries")} WHERE path = @p0 OR path LIKE @p0 + '/%'`
         );
         for (const entry of allEntriesResult.recordset) {
-          const relativePath = path4.posix.relative(srcPrefixed, entry.path);
-          const newPath = path4.posix.join(destPrefixed, relativePath);
+          const relativePath = path3.posix.relative(srcPrefixed, entry.path);
+          const newPath = path3.posix.join(destPrefixed, relativePath);
           const insertReq = transaction.request();
           insertReq.input("p0", newPath);
           insertReq.input("p1", entry.type);
@@ -3736,8 +3073,8 @@ var MssqlFs = class _MssqlFs {
           `DELETE FROM ${this.#t("fs_entries")} WHERE path = @dp0 OR path LIKE @dp0 + '/%'`
         );
         for (const entry of [...allEntriesResult.recordset].reverse()) {
-          const relativePath = path4.posix.relative(srcPrefixed, entry.path);
-          const newPath = path4.posix.join(destPrefixed, relativePath);
+          const relativePath = path3.posix.relative(srcPrefixed, entry.path);
+          const newPath = path3.posix.join(destPrefixed, relativePath);
           const insertReq = transaction.request();
           insertReq.input("p0", newPath);
           insertReq.input("p1", entry.type);
@@ -3830,7 +3167,7 @@ var MssqlFs = class _MssqlFs {
     });
   }
   resolvePath(base, relativePath) {
-    return path4.posix.resolve(base, relativePath);
+    return path3.posix.resolve(base, relativePath);
   }
   getAllPaths() {
     throw new Error(
@@ -3971,7 +3308,7 @@ var MssqlFs = class _MssqlFs {
 
 // packages/text2sql/src/lib/fs/postgres/postgres-fs.ts
 import { createRequire as createRequire2 } from "node:module";
-import * as path5 from "node:path";
+import * as path4 from "node:path";
 
 // packages/text2sql/src/lib/fs/postgres/ddl.postgres-fs.ts
 function postgresFsDDL(schema) {
@@ -4076,7 +3413,7 @@ var PostgresFs = class _PostgresFs {
     const segments = p.split("/").filter(Boolean);
     let currentPath = "/";
     for (let i = 0; i < segments.length - 1; i++) {
-      currentPath = path5.posix.join(currentPath, segments[i]);
+      currentPath = path4.posix.join(currentPath, segments[i]);
       const exists = await this.#rawQuery(
         `SELECT EXISTS(SELECT 1 FROM ${this.#t("fs_entries")} WHERE path = $1) AS exists`,
         [currentPath]
@@ -4121,7 +3458,7 @@ var PostgresFs = class _PostgresFs {
     }
   }
   #normalizeRoot(root) {
-    return path5.posix.resolve("/", root.trim());
+    return path4.posix.resolve("/", root.trim());
   }
   #prefixPath(p) {
     if (!this.#root) {
@@ -4130,7 +3467,7 @@ var PostgresFs = class _PostgresFs {
     if (p === "/") {
       return this.#root;
     }
-    return path5.posix.join(this.#root, p);
+    return path4.posix.join(this.#root, p);
   }
   #unprefixPath(p) {
     if (!this.#root) {
@@ -4145,10 +3482,10 @@ var PostgresFs = class _PostgresFs {
     return p;
   }
   #normalizePath(p) {
-    return path5.posix.resolve("/", p);
+    return path4.posix.resolve("/", p);
   }
   #dirname(p) {
-    const dir = path5.posix.dirname(p);
+    const dir = path4.posix.dirname(p);
     return dir === "" ? "/" : dir;
   }
   async #ensureParentExists(filePath, client) {
@@ -4228,7 +3565,7 @@ var PostgresFs = class _PostgresFs {
     }
     seen.add(p);
     const target = this.#normalizePath(
-      path5.posix.resolve(this.#dirname(p), entry.symlink_target)
+      path4.posix.resolve(this.#dirname(p), entry.symlink_target)
     );
     return this.#resolveSymlink(target, seen);
   }
@@ -4394,11 +3731,11 @@ var PostgresFs = class _PostgresFs {
     await this.#useTransaction(async (client) => {
       if (options?.recursive) {
         const rootPath = this.#root || "/";
-        const relativePath = path5.posix.relative(rootPath, prefixed);
+        const relativePath = path4.posix.relative(rootPath, prefixed);
         const segments = relativePath.split("/").filter(Boolean);
         let currentPath = rootPath;
         for (const segment of segments) {
-          currentPath = path5.posix.join(currentPath, segment);
+          currentPath = path4.posix.join(currentPath, segment);
           const result = await client.query(
             `SELECT type FROM ${this.#t("fs_entries")} WHERE path = $1`,
             [currentPath]
@@ -4456,7 +3793,7 @@ var PostgresFs = class _PostgresFs {
          AND path NOT LIKE $1 || '%/%'`,
       [prefix, resolved]
     );
-    return rows.map((row) => path5.posix.basename(row.path));
+    return rows.map((row) => path4.posix.basename(row.path));
   }
   async readdirWithFileTypes(dirPath) {
     const normalized = this.#normalizePath(dirPath);
@@ -4482,7 +3819,7 @@ var PostgresFs = class _PostgresFs {
       [prefix, resolved]
     );
     return rows.map((row) => ({
-      name: path5.posix.basename(row.path),
+      name: path4.posix.basename(row.path),
       isFile: row.type === "file",
       isDirectory: row.type === "directory",
       isSymbolicLink: row.type === "symlink"
@@ -4547,8 +3884,8 @@ var PostgresFs = class _PostgresFs {
           [srcPrefixed]
         );
         for (const entry of allEntriesResult.rows) {
-          const relativePath = path5.posix.relative(srcPrefixed, entry.path);
-          const newPath = path5.posix.join(destPrefixed, relativePath);
+          const relativePath = path4.posix.relative(srcPrefixed, entry.path);
+          const newPath = path4.posix.join(destPrefixed, relativePath);
           await client.query(
             `INSERT INTO ${this.#t("fs_entries")} (path, type, mode, size, mtime, symlink_target)
              VALUES ($1, $2, $3, $4, $5, $6)
@@ -4637,8 +3974,8 @@ var PostgresFs = class _PostgresFs {
           [destPrefixed]
         );
         for (const entry of [...allEntriesResult.rows].reverse()) {
-          const relativePath = path5.posix.relative(srcPrefixed, entry.path);
-          const newPath = path5.posix.join(destPrefixed, relativePath);
+          const relativePath = path4.posix.relative(srcPrefixed, entry.path);
+          const newPath = path4.posix.join(destPrefixed, relativePath);
           await client.query(
             `INSERT INTO ${this.#t("fs_entries")} (path, type, mode, size, mtime, symlink_target)
              VALUES ($1, $2, $3, $4, $5, $6)
@@ -4711,7 +4048,7 @@ var PostgresFs = class _PostgresFs {
     });
   }
   resolvePath(base, relativePath) {
-    return path5.posix.resolve(base, relativePath);
+    return path4.posix.resolve(base, relativePath);
   }
   getAllPaths() {
     throw new Error(
@@ -4930,7 +4267,7 @@ import {
   clarification,
   example as example2,
   explain,
-  fragment as fragment2,
+  fragment as fragment3,
   guardrail as guardrail2,
   hint as hint2,
   policy as policy2,
@@ -4939,12 +4276,12 @@ import {
   styleGuide,
   workflow as workflow2
 } from "@deepagents/context";
-function guidelines() {
+function instructions() {
   const baseTeachings = [
     // Include the meta-cognitive reasoning framework
     ...reasoningFramework(),
     // Prerequisite policies (must do X before Y)
-    fragment2(
+    fragment3(
       "prerequisite_policies",
       policy2({
         rule: "YOU MUST inspect schema structure and available tables",
@@ -4968,7 +4305,7 @@ function guidelines() {
       })
     ),
     // Few-shot: Applying reasoning principles
-    fragment2(
+    fragment3(
       "reasoning_examples",
       example2({
         question: "Show me sales last month",
@@ -5008,7 +4345,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       })
     ),
     // Schema adherence - consolidated into clear rules
-    fragment2(
+    fragment3(
       "schema_adherence",
       guardrail2({
         rule: "Use only tables and columns that exist in the schema.",
@@ -5021,7 +4358,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         therefore: 'Use listing queries for "show" requests, aggregate queries for "count" or "total", and use canonical schema values verbatim in filters.'
       })
     ),
-    fragment2(
+    fragment3(
       "column_statistics",
       explain({
         concept: "nDistinct in column stats",
@@ -5042,7 +4379,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       "Use JOINs based on schema relationships. Favor PK/indexed columns; follow relationship metadata for direction and cardinality."
     ),
     // Aggregations - explain the concepts
-    fragment2(
+    fragment3(
       "aggregations",
       hint2(
         "Apply COUNT, SUM, AVG when the question implies summarization. Use window functions for ranking, running totals, or row comparisons."
@@ -5054,7 +4391,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       })
     ),
     // Query semantics - explain concepts and document quirks
-    fragment2(
+    fragment3(
       "query_interpretation",
       explain({
         concept: "threshold language",
@@ -5082,7 +4419,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       prefer: "Concise, business-friendly summaries with key comparisons and helpful follow-ups."
     }),
     // Safety guardrails - consolidated
-    fragment2(
+    fragment3(
       "query_safety",
       guardrail2({
         rule: "Generate only valid, executable SELECT/WITH statements.",
@@ -5158,7 +4495,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       ],
       notes: "If reference is ambiguous, ask which previous result or entity the user means."
     }),
-    fragment2(
+    fragment3(
       "bash_tool_usage",
       workflow2({
         task: "Query execution",
@@ -5172,7 +4509,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       }),
       guardrail2({
         rule: "Do not attempt SQL access through non-bash tools.",
-        reason: "SQL access is only available through the virtual bash environment.",
+        reason: "SQL access is only available through the bash tool.",
         action: 'Use `sql run <db> "SELECT ..."` and `sql validate <db> "SELECT ..."` through bash, where `<db>` is the configured database name.'
       }),
       explain({
@@ -5181,7 +4518,11 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         therefore: "Use the returned column names to build precise jq queries against the output file."
       }),
       quirk({
-        issue: "This is a virtual bash environment, so you cannot access underlying SQL files directly.",
+        issue: "The SQL command is a real CLI installed inside the sandbox, so shell quoting rules apply before SQL validation runs.",
+        workaround: 'Keep the whole SQL query in one quoted argument. If quoting is difficult, write the query to a file and call `sql validate <db> "$(cat query.sql)"` or `sql run <db> "$(cat query.sql)"`.'
+      }),
+      quirk({
+        issue: "SQL result artifacts live inside the sandbox, so you cannot access underlying SQL files directly.",
         workaround: "Treat the returned result path as the artifact to inspect, rather than trying to access SQL files themselves."
       }),
       quirk({
@@ -5189,7 +4530,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         workaround: "Read stderr first and classify the failure before retrying or changing the query."
       })
     ),
-    fragment2(
+    fragment3(
       "clarifications",
       guardrail2({
         rule: "Do not invent an answer when the available schema, results, or user request are insufficient to determine it.",
@@ -5207,58 +4548,952 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         reason: "Prevents large scans and irrelevant results."
       })
     )
-  ];
-  return baseTeachings;
+  ];
+  return baseTeachings;
+}
+
+// packages/text2sql/src/lib/sql-meta-hook.ts
+import { parse } from "just-bash";
+import { asStaticWordText, useBashMeta } from "@deepagents/context";
+var SQL_VALIDATE_REMINDER = 'Always run `sql validate <db> "..."` before `sql run <db> "..."` to catch syntax errors early.';
+function createSqlMetaHook({ adapters }) {
+  const pendingByCommand = /* @__PURE__ */ new Map();
+  return {
+    track({ repaired, transformed }) {
+      const invocation = parseSqlQueryInvocation(repaired);
+      if (!invocation) return;
+      const pending = pendingByCommand.get(transformed) ?? [];
+      pending.push(invocation);
+      pendingByCommand.set(transformed, pending);
+    },
+    onAfterBashCall({ command }) {
+      const pending = pendingByCommand.get(command);
+      const invocation = pending?.shift();
+      if (pending?.length === 0) pendingByCommand.delete(command);
+      if (!invocation) return void 0;
+      if (invocation.subcommand === "run") {
+        useBashMeta()?.setReminder(SQL_VALIDATE_REMINDER);
+      }
+      const adapter = adapters[invocation.dbName];
+      if (!adapter) return void 0;
+      try {
+        useBashMeta()?.setHidden({
+          formattedSql: adapter.format(invocation.sql)
+        });
+      } catch {
+      }
+      return void 0;
+    }
+  };
+}
+function parseSqlQueryInvocation(command) {
+  const simpleCommand = parseSingleSimpleCommand(command);
+  if (!simpleCommand) return null;
+  if (asStaticWordText(simpleCommand.name) !== "sql") return null;
+  if (simpleCommand.args.length < 3) return null;
+  const subcommand = asStaticWordText(simpleCommand.args[0]);
+  if (subcommand !== "run" && subcommand !== "validate") return null;
+  const dbName = asStaticWordText(simpleCommand.args[1]);
+  if (!dbName) return null;
+  const sql = joinSqlWords(simpleCommand.args.slice(2));
+  if (!sql) return null;
+  return { subcommand, dbName, sql };
+}
+function parseSingleSimpleCommand(command) {
+  const normalized = command.trim();
+  if (!normalized) return null;
+  try {
+    const script = parse(normalized);
+    if (script.statements.length !== 1) return null;
+    const statement = script.statements[0];
+    if (statement.background || statement.operators.length > 0 || statement.pipelines.length !== 1) {
+      return null;
+    }
+    const pipeline = statement.pipelines[0];
+    if (pipeline.negated || pipeline.timed || pipeline.commands.length !== 1) {
+      return null;
+    }
+    const commandNode = pipeline.commands[0];
+    if (commandNode.type !== "SimpleCommand") return null;
+    if (commandNode.assignments.length > 0 || commandNode.redirections.length > 0 || !commandNode.name) {
+      return null;
+    }
+    return commandNode;
+  } catch {
+    return null;
+  }
+}
+function joinSqlWords(words) {
+  const values = [];
+  for (const word of words) {
+    const value = asStaticWordText(word, {
+      preserveLegacyBackticks: true
+    });
+    if (value == null) return null;
+    values.push(value);
+  }
+  const sql = values.join(" ").trim();
+  return sql || null;
+}
+
+// packages/text2sql/src/lib/sql-repair.ts
+import {
+  buildSubcommandRepair,
+  repairQuotedArg
+} from "@deepagents/context";
+function repairDbNameAndQuery(rawArgs) {
+  const trimmed = rawArgs.trim();
+  if (!trimmed) return null;
+  const firstSpace = trimmed.search(/\s/);
+  if (firstSpace === -1) return null;
+  const dbName = trimmed.slice(0, firstSpace);
+  const rest = trimmed.slice(firstSpace + 1);
+  const repaired = repairQuotedArg(rest);
+  if (repaired == null) return null;
+  return `${dbName} ${repaired}`;
+}
+var inertHandler = () => ({ stdout: "", stderr: "", exitCode: 0 });
+var repair = buildSubcommandRepair("sql", {
+  run: {
+    usage: 'run <db> "SELECT ..."',
+    description: "Execute query against <db> and store results",
+    repair: repairDbNameAndQuery,
+    handler: inertHandler
+  },
+  validate: {
+    usage: 'validate <db> "SELECT ..."',
+    description: "Validate query syntax against <db>",
+    repair: repairDbNameAndQuery,
+    handler: inertHandler
+  }
+});
+function repairSqlCommand(command) {
+  return repair(command);
+}
+
+// packages/text2sql/src/lib/sql-transform.ts
+import { BashTransformPipeline } from "just-bash";
+
+// packages/text2sql/src/lib/agents/sql-transform-plugins.ts
+import { parse as parse2, serialize } from "just-bash";
+import { createHash as createHash3 } from "node:crypto";
+import * as path5 from "node:path";
+import { BashException, asStaticWordText as asStaticWordText2 } from "@deepagents/context";
+function isScriptNode(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const node = value;
+  return node.type === "Script" && Array.isArray(node.statements);
+}
+var BLOCKED_DB_CLIENT_COMMANDS = /* @__PURE__ */ new Set([
+  "psql",
+  "sqlite3",
+  "mysql",
+  "duckdb"
+]);
+var BLOCKED_RAW_SQL_COMMANDS = /* @__PURE__ */ new Set(["select", "with"]);
+var ALLOWED_SQL_PROXY_SUBCOMMANDS = /* @__PURE__ */ new Set(["run", "validate"]);
+var SHELL_INTERPRETER_COMMANDS = /* @__PURE__ */ new Set([
+  "bash",
+  "sh",
+  "zsh",
+  "dash",
+  "ksh"
+]);
+var WRAPPER_COMMANDS = /* @__PURE__ */ new Set(["env", "command", "eval"]);
+var SQL_PROXY_ENFORCEMENT_MESSAGE = [
+  "Direct database querying through bash is blocked.",
+  "Use SQL proxy commands in this order:",
+  '1) sql validate <db> "SELECT ..."',
+  '2) sql run <db> "SELECT ..."'
+].join("\n");
+var SqlProxyViolationError = class extends BashException {
+  constructor() {
+    super(SQL_PROXY_ENFORCEMENT_MESSAGE);
+    this.name = "SqlProxyViolationError";
+  }
+  format() {
+    return { stdout: "", stderr: `${this.message}
+`, exitCode: 1 };
+  }
+};
+function cloneInspectionContext(context) {
+  return {
+    functionDefinitions: new Map(context.functionDefinitions),
+    callStack: new Set(context.callStack)
+  };
+}
+function scriptContainsBlockedCommand(script, context, mode = "blocked-only") {
+  return statementsContainBlockedCommand(script.statements, context, mode);
+}
+function statementsContainBlockedCommand(statements, context, mode) {
+  for (const statement of statements) {
+    if (statementContainsBlockedCommand(statement, context, mode)) {
+      return true;
+    }
+  }
+  return false;
+}
+function statementContainsBlockedCommand(statement, context, mode) {
+  for (const pipeline of statement.pipelines) {
+    if (pipelineContainsBlockedCommand(pipeline, context, mode)) {
+      return true;
+    }
+  }
+  return false;
+}
+function pipelineContainsBlockedCommand(pipeline, context, mode) {
+  for (const [index2, command] of pipeline.commands.entries()) {
+    if (command.type === "FunctionDef") {
+      context.functionDefinitions.set(command.name, command);
+      continue;
+    }
+    if (commandContainsBlockedCommand(command, context, mode, {
+      stdinFromPipe: index2 > 0
+    })) {
+      return true;
+    }
+  }
+  return false;
+}
+function stringCommandContainsBlockedCommand(command, context, mode = "blocked-only") {
+  let script;
+  try {
+    script = parse2(command);
+  } catch {
+    return false;
+  }
+  return scriptContainsBlockedCommand(
+    script,
+    cloneInspectionContext(context),
+    mode
+  );
+}
+function wordContainsBlockedCommand(word, context, mode) {
+  if (!word) {
+    return false;
+  }
+  return wordPartContainsBlockedCommand(
+    word.parts,
+    context,
+    mode
+  );
+}
+function wordPartContainsBlockedCommand(parts, context, mode) {
+  for (const part of parts) {
+    if (partContainsBlockedCommand(part, context, mode)) {
+      return true;
+    }
+  }
+  return false;
+}
+function partContainsBlockedCommand(node, context, mode) {
+  const type = node.type;
+  if (type === "CommandSubstitution" || type === "ProcessSubstitution") {
+    if (isScriptNode(node.body)) {
+      return scriptContainsBlockedCommand(
+        node.body,
+        cloneInspectionContext(context),
+        mode
+      );
+    }
+    return false;
+  }
+  if (type === "ArithCommandSubst" && typeof node.command === "string") {
+    return stringCommandContainsBlockedCommand(node.command, context, mode);
+  }
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (typeof item === "object" && item !== null) {
+          if (partContainsBlockedCommand(
+            item,
+            context,
+            mode
+          )) {
+            return true;
+          }
+        }
+      }
+      continue;
+    }
+    if (typeof value === "object" && value !== null) {
+      if (partContainsBlockedCommand(
+        value,
+        context,
+        mode
+      )) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function functionInvocationContainsBlockedCommand(functionName, context, mode) {
+  const definition = context.functionDefinitions.get(functionName);
+  if (!definition) {
+    return false;
+  }
+  if (context.callStack.has(functionName)) {
+    return false;
+  }
+  const invocationContext = cloneInspectionContext(context);
+  invocationContext.callStack.add(functionName);
+  return commandContainsBlockedCommand(
+    definition.body,
+    invocationContext,
+    mode,
+    { stdinFromPipe: false }
+  );
+}
+function isAsciiLetter(character) {
+  const charCode = character.charCodeAt(0);
+  return charCode >= 65 && charCode <= 90 || charCode >= 97 && charCode <= 122;
+}
+function isAsciiDigit(character) {
+  const charCode = character.charCodeAt(0);
+  return charCode >= 48 && charCode <= 57;
+}
+function isValidEnvVariableName(name) {
+  if (!name) {
+    return false;
+  }
+  const firstChar = name[0];
+  if (!(isAsciiLetter(firstChar) || firstChar === "_")) {
+    return false;
+  }
+  for (let index2 = 1; index2 < name.length; index2 += 1) {
+    const char = name[index2];
+    if (!(isAsciiLetter(char) || isAsciiDigit(char) || char === "_")) {
+      return false;
+    }
+  }
+  return true;
+}
+function isEnvAssignmentToken(token) {
+  const separatorIndex = token.indexOf("=");
+  if (separatorIndex <= 0) {
+    return false;
+  }
+  return isValidEnvVariableName(token.slice(0, separatorIndex));
+}
+function parseShortOptionCluster(option) {
+  if (!option.startsWith("-") || option.startsWith("--") || option.length <= 1) {
+    return {
+      valid: false,
+      hasCommandFlag: false,
+      hasStdinFlag: false,
+      consumesNextArg: false
+    };
+  }
+  let hasCommandFlag = false;
+  let hasStdinFlag = false;
+  let consumesNextArg = false;
+  for (let index2 = 1; index2 < option.length; index2 += 1) {
+    const char = option[index2];
+    if (!isAsciiLetter(char)) {
+      return {
+        valid: false,
+        hasCommandFlag: false,
+        hasStdinFlag: false,
+        consumesNextArg: false
+      };
+    }
+    if (char === "c") {
+      hasCommandFlag = true;
+    } else if (char === "s") {
+      hasStdinFlag = true;
+    } else if (char === "O" || char === "o") {
+      consumesNextArg = true;
+    }
+  }
+  return { valid: true, hasCommandFlag, hasStdinFlag, consumesNextArg };
+}
+function getShellInvocationDescriptor(args) {
+  let readsFromStdin = false;
+  const longOptionsWithValue = /* @__PURE__ */ new Set(["--rcfile", "--init-file"]);
+  for (let index2 = 0; index2 < args.length; index2 += 1) {
+    const token = asStaticWordText2(args[index2]);
+    if (token == null) {
+      return { kind: "unknown", payload: null };
+    }
+    if (token === "--") {
+      if (index2 + 1 >= args.length) {
+        break;
+      }
+      return {
+        kind: "script",
+        payload: asStaticWordText2(args[index2 + 1])
+      };
+    }
+    if (token === "--command") {
+      return {
+        kind: "command",
+        payload: asStaticWordText2(args[index2 + 1])
+      };
+    }
+    if (token.startsWith("--command=")) {
+      return {
+        kind: "command",
+        payload: token.slice("--command=".length)
+      };
+    }
+    if (token.startsWith("--")) {
+      if (token.includes("=")) {
+        continue;
+      }
+      if (longOptionsWithValue.has(token)) {
+        if (index2 + 1 >= args.length) {
+          return { kind: "unknown", payload: null };
+        }
+        index2 += 1;
+      }
+      continue;
+    }
+    if (token.startsWith("-") && !token.startsWith("--")) {
+      const parsed = parseShortOptionCluster(token);
+      if (!parsed.valid) {
+        return { kind: "unknown", payload: null };
+      }
+      if (parsed.hasCommandFlag) {
+        return {
+          kind: "command",
+          payload: asStaticWordText2(args[index2 + 1])
+        };
+      }
+      if (parsed.hasStdinFlag) {
+        readsFromStdin = true;
+      }
+      if (parsed.consumesNextArg) {
+        if (index2 + 1 >= args.length) {
+          return { kind: "unknown", payload: null };
+        }
+        index2 += 1;
+      }
+      continue;
+    }
+    return {
+      kind: "script",
+      payload: token
+    };
+  }
+  if (readsFromStdin) {
+    return { kind: "stdin", payload: null };
+  }
+  return { kind: "none", payload: null };
+}
+function getHereDocPayload(redirections) {
+  const payloads = [];
+  for (const redirection of redirections) {
+    if (redirection.target.type !== "HereDoc") {
+      continue;
+    }
+    if (!redirection.target.content) {
+      payloads.push("");
+      continue;
+    }
+    const payload = asStaticWordText2(redirection.target.content);
+    if (payload == null) {
+      return { hasHereDoc: true, payload: null };
+    }
+    payloads.push(payload);
+  }
+  if (payloads.length === 0) {
+    return { hasHereDoc: false, payload: null };
+  }
+  return { hasHereDoc: true, payload: payloads.join("\n") };
+}
+function joinStaticWords(words) {
+  const tokens = [];
+  for (const word of words) {
+    const token = asStaticWordText2(word);
+    if (token == null) {
+      return null;
+    }
+    tokens.push(token);
+  }
+  return tokens.join(" ");
+}
+function resolveEnvWrapperCommand(args) {
+  let index2 = 0;
+  while (index2 < args.length) {
+    const token = asStaticWordText2(args[index2]);
+    if (token == null) {
+      return { kind: "unknown" };
+    }
+    if (token === "--") {
+      index2 += 1;
+      break;
+    }
+    if (token === "-u" || token === "--unset" || token === "--chdir") {
+      if (index2 + 1 >= args.length) {
+        return { kind: "unknown" };
+      }
+      index2 += 2;
+      continue;
+    }
+    if (token.startsWith("--unset=") || token.startsWith("--chdir=")) {
+      index2 += 1;
+      continue;
+    }
+    if (token.startsWith("-") && token !== "-" && !isEnvAssignmentToken(token)) {
+      index2 += 1;
+      continue;
+    }
+    if (isEnvAssignmentToken(token)) {
+      index2 += 1;
+      continue;
+    }
+    break;
+  }
+  if (index2 >= args.length) {
+    return { kind: "none" };
+  }
+  return {
+    kind: "resolved",
+    name: args[index2],
+    args: args.slice(index2 + 1)
+  };
+}
+function resolveCommandWrapperCommand(args) {
+  let index2 = 0;
+  let lookupOnly = false;
+  while (index2 < args.length) {
+    const token = asStaticWordText2(args[index2]);
+    if (token == null) {
+      return { kind: "unknown" };
+    }
+    if (token === "--") {
+      index2 += 1;
+      break;
+    }
+    if (token === "-v" || token === "-V") {
+      lookupOnly = true;
+      index2 += 1;
+      continue;
+    }
+    if (token.startsWith("-") && token !== "-") {
+      index2 += 1;
+      continue;
+    }
+    break;
+  }
+  if (lookupOnly || index2 >= args.length) {
+    return { kind: "none" };
+  }
+  return {
+    kind: "resolved",
+    name: args[index2],
+    args: args.slice(index2 + 1)
+  };
+}
+function commandContainsBlockedCommand(command, context, mode, options = { stdinFromPipe: false }) {
+  switch (command.type) {
+    case "SimpleCommand":
+      return isBlockedSimpleCommand(command, context, mode, options);
+    case "If":
+      return command.clauses.some(
+        (clause) => statementsContainBlockedCommand(
+          clause.condition,
+          cloneInspectionContext(context),
+          mode
+        ) || statementsContainBlockedCommand(
+          clause.body,
+          cloneInspectionContext(context),
+          mode
+        )
+      ) || (command.elseBody ? statementsContainBlockedCommand(
+        command.elseBody,
+        cloneInspectionContext(context),
+        mode
+      ) : false);
+    case "For":
+    case "CStyleFor":
+      return statementsContainBlockedCommand(
+        command.body,
+        cloneInspectionContext(context),
+        mode
+      );
+    case "While":
+    case "Until":
+      return statementsContainBlockedCommand(
+        command.condition,
+        cloneInspectionContext(context),
+        mode
+      ) || statementsContainBlockedCommand(
+        command.body,
+        cloneInspectionContext(context),
+        mode
+      );
+    case "Case":
+      return command.items.some(
+        (item) => statementsContainBlockedCommand(
+          item.body,
+          cloneInspectionContext(context),
+          mode
+        )
+      );
+    case "Subshell":
+    case "Group":
+      return statementsContainBlockedCommand(
+        command.body,
+        cloneInspectionContext(context),
+        mode
+      );
+    case "FunctionDef":
+      return false;
+    case "ArithmeticCommand":
+    case "ConditionalCommand":
+      return false;
+    default: {
+      const _unreachable = command;
+      return _unreachable;
+    }
+  }
+}
+function isBlockedSimpleCommand(command, context, mode, options) {
+  if (wordContainsBlockedCommand(command.name, context, mode)) {
+    return true;
+  }
+  if (command.args.some((arg) => wordContainsBlockedCommand(arg, context, mode))) {
+    return true;
+  }
+  if (command.assignments.some(
+    (assignment) => wordContainsBlockedCommand(assignment.value, context, mode) || (assignment.array?.some(
+      (value) => wordContainsBlockedCommand(value, context, mode)
+    ) ?? false)
+  )) {
+    return true;
+  }
+  if (command.redirections.some((redirection) => {
+    if (redirection.target.type === "Word") {
+      return wordContainsBlockedCommand(
+        redirection.target,
+        context,
+        mode
+      );
+    }
+    if (redirection.target.type === "HereDoc" && redirection.target.content) {
+      return wordContainsBlockedCommand(
+        redirection.target.content,
+        context,
+        mode
+      );
+    }
+    return false;
+  })) {
+    return true;
+  }
+  const commandName = asStaticWordText2(command.name);
+  if (!commandName) {
+    return false;
+  }
+  const normalizedName = path5.posix.basename(commandName).toLowerCase();
+  if (BLOCKED_DB_CLIENT_COMMANDS.has(normalizedName)) {
+    return true;
+  }
+  if (BLOCKED_RAW_SQL_COMMANDS.has(normalizedName)) {
+    return true;
+  }
+  if (normalizedName === "sql") {
+    const subcommand = asStaticWordText2(command.args[0])?.toLowerCase();
+    if (!subcommand) {
+      return true;
+    }
+    if (mode === "block-all-sql") {
+      return true;
+    }
+    return !ALLOWED_SQL_PROXY_SUBCOMMANDS.has(subcommand);
+  }
+  const inspectWrappedCommand = (resolved) => {
+    if (resolved.kind === "none") {
+      return false;
+    }
+    if (resolved.kind === "unknown" || !resolved.name || !resolved.args) {
+      return true;
+    }
+    return isBlockedSimpleCommand(
+      {
+        name: resolved.name,
+        args: resolved.args,
+        assignments: [],
+        redirections: []
+      },
+      context,
+      "block-all-sql",
+      options
+    );
+  };
+  if (WRAPPER_COMMANDS.has(normalizedName)) {
+    if (normalizedName === "env") {
+      return inspectWrappedCommand(resolveEnvWrapperCommand(command.args));
+    }
+    if (normalizedName === "command") {
+      return inspectWrappedCommand(resolveCommandWrapperCommand(command.args));
+    }
+    const evalScript = joinStaticWords(command.args);
+    if (evalScript == null) {
+      return true;
+    }
+    if (!evalScript.trim()) {
+      return false;
+    }
+    return stringCommandContainsBlockedCommand(
+      evalScript,
+      context,
+      "block-all-sql"
+    );
+  }
+  if (SHELL_INTERPRETER_COMMANDS.has(normalizedName)) {
+    const shellInvocation = getShellInvocationDescriptor(command.args);
+    if (shellInvocation.kind === "unknown") {
+      return true;
+    }
+    if (shellInvocation.kind === "command") {
+      if (!shellInvocation.payload) {
+        return true;
+      }
+      if (stringCommandContainsBlockedCommand(
+        shellInvocation.payload,
+        context,
+        "block-all-sql"
+      )) {
+        return true;
+      }
+      return false;
+    }
+    const hereDoc = getHereDocPayload(command.redirections);
+    if (hereDoc.hasHereDoc) {
+      if (hereDoc.payload == null) {
+        return true;
+      }
+      if (hereDoc.payload.trim().length > 0 && stringCommandContainsBlockedCommand(
+        hereDoc.payload,
+        context,
+        "block-all-sql"
+      )) {
+        return true;
+      }
+    }
+    if (shellInvocation.kind === "script") {
+      return true;
+    }
+    if (options.stdinFromPipe || shellInvocation.kind === "stdin") {
+      return !hereDoc.hasHereDoc;
+    }
+  }
+  if (functionInvocationContainsBlockedCommand(commandName, context, mode)) {
+    return true;
+  }
+  return false;
+}
+var SqlProxyEnforcementPlugin = class {
+  name = "sql-proxy-enforcement";
+  transform(context) {
+    const blocked = scriptContainsBlockedCommand(context.ast, {
+      functionDefinitions: /* @__PURE__ */ new Map(),
+      callStack: /* @__PURE__ */ new Set()
+    });
+    if (blocked) {
+      throw new SqlProxyViolationError();
+    }
+    return {
+      ast: context.ast,
+      metadata: { inspected: true }
+    };
+  }
+};
+function wordPartsContainExpansion(parts) {
+  for (const part of parts) {
+    if (part.type === "CommandSubstitution" || part.type === "ParameterExpansion" || part.type === "ArithmeticExpansion") {
+      return true;
+    }
+    if (part.type === "DoubleQuoted" && Array.isArray(part.parts)) {
+      if (wordPartsContainExpansion(part.parts)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function isSqlCommandRequiringRewrite(cmd) {
+  if (cmd.type !== "SimpleCommand") return false;
+  if (cmd.assignments.length > 0 || cmd.redirections.length > 0) return false;
+  if (asStaticWordText2(cmd.name) !== "sql") return false;
+  if (cmd.args.length < 3) return false;
+  const subcommand = asStaticWordText2(cmd.args[0]);
+  if (subcommand !== "validate" && subcommand !== "run") return false;
+  const dbName = asStaticWordText2(cmd.args[1]);
+  if (!isValidAdapterName(dbName)) return false;
+  const sqlArgs = cmd.args.slice(2);
+  if (sqlArgs.length > 1) return true;
+  return sqlArgs.some(
+    (arg) => wordPartsContainExpansion(
+      arg.parts
+    )
+  );
+}
+function extractWordPartText(parts) {
+  let text = "";
+  for (const part of parts) {
+    const type = part.type;
+    if (type === "Literal" || type === "SingleQuoted" || type === "Escaped") {
+      text += part.value;
+    } else if (type === "DoubleQuoted" && Array.isArray(part.parts)) {
+      text += extractWordPartText(part.parts);
+    } else if (type === "CommandSubstitution" && part.legacy === true) {
+      text += "`" + serialize(part.body).trim() + "`";
+    } else if (type === "CommandSubstitution") {
+      text += "$(" + serialize(part.body).trim() + ")";
+    } else if (type === "ParameterExpansion") {
+      text += emitParameterExpansion(part);
+    } else if (type === "ArithmeticExpansion") {
+      const expression = part.expression;
+      text += "$((" + (expression?.originalText ?? "") + "))";
+    }
+  }
+  return text;
+}
+function emitParameterExpansion(part) {
+  const parameter = part.parameter;
+  const operation = part.operation;
+  if (!operation) return "$" + parameter;
+  if (operation.type === "DefaultValue" && operation.word) {
+    const fallback = extractWordPartText(operation.word.parts);
+    const separator = operation.checkEmpty ? ":-" : "-";
+    return "${" + parameter + separator + fallback + "}";
+  }
+  return "${" + parameter + "}";
+}
+function extractSqlText(args) {
+  return args.map(
+    (arg) => extractWordPartText(
+      arg.parts
+    )
+  ).join(" ");
+}
+function rewriteSqlCommand(cmd, ast) {
+  const subcommand = asStaticWordText2(cmd.args[0]);
+  const dbName = asStaticWordText2(cmd.args[1]);
+  const sqlArgs = cmd.args.slice(2);
+  const unquotedSql = extractSqlText(sqlArgs);
+  const hash2 = createHash3("sha256").update(serialize(ast)).digest("hex").slice(0, 12);
+  const sqlPath = `/tmp/sql-inline-${subcommand}-${hash2}.sql`;
+  const heredocTag = `SQL_${hash2.toUpperCase()}`;
+  const groupScript = [
+    `{ cat > ${sqlPath} <<'${heredocTag}'`,
+    unquotedSql,
+    heredocTag,
+    `sql ${subcommand} ${dbName} "$(cat ${sqlPath})"; }`
+  ].join("\n");
+  const groupAst = parse2(groupScript);
+  return groupAst.statements[0].pipelines[0].commands[0];
+}
+function rewriteSqlCommandsInList(commands, ast) {
+  let rewritten = false;
+  for (let i = 0; i < commands.length; i++) {
+    const cmd = commands[i];
+    if (isSqlCommandRequiringRewrite(cmd)) {
+      commands[i] = rewriteSqlCommand(cmd, ast);
+      rewritten = true;
+      continue;
+    }
+    if (cmd.type === "If") {
+      for (const clause of cmd.clauses) {
+        if (rewriteSqlCommandsInStatements(clause.condition, ast))
+          rewritten = true;
+        if (rewriteSqlCommandsInStatements(clause.body, ast)) rewritten = true;
+      }
+      if (cmd.elseBody && rewriteSqlCommandsInStatements(cmd.elseBody, ast)) {
+        rewritten = true;
+      }
+    } else if (cmd.type === "While" || cmd.type === "Until") {
+      if (rewriteSqlCommandsInStatements(cmd.condition, ast)) rewritten = true;
+      if (rewriteSqlCommandsInStatements(cmd.body, ast)) rewritten = true;
+    } else if (cmd.type === "For" || cmd.type === "CStyleFor") {
+      if (rewriteSqlCommandsInStatements(cmd.body, ast)) rewritten = true;
+    } else if (cmd.type === "Case") {
+      for (const item of cmd.items) {
+        if (rewriteSqlCommandsInStatements(item.body, ast)) rewritten = true;
+      }
+    } else if (cmd.type === "Subshell" || cmd.type === "Group") {
+      if (rewriteSqlCommandsInStatements(cmd.body, ast)) rewritten = true;
+    }
+  }
+  return rewritten;
+}
+function rewriteSqlCommandsInStatements(statements, ast) {
+  let rewritten = false;
+  for (const statement of statements) {
+    for (const pipeline of statement.pipelines) {
+      if (rewriteSqlCommandsInList(pipeline.commands, ast)) {
+        rewritten = true;
+      }
+    }
+  }
+  return rewritten;
+}
+var SqlCommandRewritePlugin = class {
+  name = "sql-command-rewrite";
+  transform(context) {
+    const ast = context.ast;
+    const rewritten = rewriteSqlCommandsInStatements(ast.statements, ast);
+    return { ast, metadata: { rewritten } };
+  }
+};
+
+// packages/text2sql/src/lib/sql-transform.ts
+var sqlTransformPipeline = new BashTransformPipeline().use(new SqlCommandRewritePlugin()).use(new SqlProxyEnforcementPlugin());
+function transformSqlCommand(command) {
+  try {
+    return sqlTransformPipeline.transform(command).script;
+  } catch (error) {
+    if (error instanceof SqlProxyViolationError) {
+      return blockedSqlProxyCommand(error.message);
+    }
+    return command;
+  }
+}
+function blockedSqlProxyCommand(message) {
+  return `{ printf '%s\\n' ${shellQuote(message)} >&2; exit 1; }`;
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
-// packages/text2sql/src/lib/sandbox.ts
-function sqlSandboxExtension(adapters, options = {}) {
-  const adapterNames = Object.keys(adapters);
-  if (adapterNames.length === 0) {
-    throw new Error("sqlSandboxExtension requires at least one adapter");
-  }
-  validateAdapterNames(adapterNames);
-  const { command, repair } = createSqlCommand(adapters, options);
+// packages/text2sql/src/lib/sql-hooks.ts
+function createSqlCommandHooks({
+  adapters
+}) {
+  const meta = createSqlMetaHook({ adapters });
   return {
-    commands: [command],
-    plugins: [new SqlBacktickRewritePlugin(), new SqlProxyEnforcementPlugin()],
-    onBeforeBashCall: ({ command: c }) => ({ command: repair(c) })
+    onBeforeBashCall: ({ command }) => {
+      const repaired = repairSqlCommand(command);
+      const transformed = transformSqlCommand(repaired);
+      meta.track({ repaired, transformed });
+      return { command: transformed };
+    },
+    onAfterBashCall: meta.onAfterBashCall
   };
 }
 
 // packages/text2sql/src/lib/sql.ts
-import {
-  createUIMessageStream
-} from "ai";
 import "@deepagents/agent";
-import {
-  agent as agent2,
-  chat,
-  errorRecoveryGuardrail,
-  fragment as fragment3
-} from "@deepagents/context";
-var TEXT2SQL_INDEX_PROGRESS_CHUNK = "data-text2sql-index-progress";
 var Text2Sql = class {
   #config;
-  #introspection;
+  #indexer;
   constructor(config) {
     const adapterNames = Object.keys(config.adapters);
     if (adapterNames.length === 0) {
       throw new Error("Text2Sql requires at least one adapter");
     }
     validateAdapterNames(adapterNames);
-    this.#config = {
-      ...config,
-      tools: config.tools ?? {}
-    };
-    this.#introspection = new Map(
-      Object.keys(config.adapters).map((name) => [
-        name,
-        new JsonCache(
-          `introspection-${config.version}-${name}`
-        )
-      ])
-    );
+    this.#config = config;
+    this.#indexer = new AdapterIndexer({
+      adapters: config.adapters,
+      version: config.version
+    });
   }
   #requireAdapter(name) {
     const adapter = this.#config.adapters[name];
@@ -5270,7 +5505,7 @@ var Text2Sql = class {
   }
   async toSql(input, adapterName) {
     const adapter = this.#requireAdapter(adapterName);
-    const fragments = await this.#indexAdapter(adapterName, adapter);
+    const fragments = await this.#indexer.indexAdapter(adapterName);
     const result = await toSql({
       input,
       adapter,
@@ -5279,158 +5514,15 @@ var Text2Sql = class {
     });
     return result.sql;
   }
-  async index() {
-    return this.#index();
-  }
-  async #index(onProgress) {
-    const entries = Object.entries(this.#config.adapters);
-    onProgress?.({
-      type: "index:start",
-      message: `Indexing ${entries.length} adapter${entries.length === 1 ? "" : "s"}...`,
-      current: 0,
-      total: entries.length
-    });
-    const settled = await Promise.allSettled(
-      entries.map(async ([name, adapter]) => {
-        const schema = await this.#indexAdapter(name, adapter, onProgress);
-        return fragment3(name, ...schema);
-      })
-    );
-    const failed = settled.find((result) => result.status === "rejected");
-    if (failed) {
-      onProgress?.({
-        type: "index:error",
-        message: failed.reason instanceof Error ? failed.reason.message : String(failed.reason)
-      });
-      throw failed.reason;
-    }
-    const wrapped = settled.map((result) => {
-      if (result.status === "rejected") {
-        throw result.reason;
-      }
-      return result.value;
-    });
-    onProgress?.({
-      type: "index:end",
-      message: "Finished indexing adapters.",
-      current: entries.length,
-      total: entries.length
-    });
-    return wrapped;
-  }
-  async #indexAdapter(name, adapter, onProgress) {
-    onProgress?.({
-      type: "adapter:start",
-      adapter: name,
-      message: `Indexing adapter "${name}"...`
-    });
-    const cache = this.#introspection.get(name);
-    if (!cache) {
-      throw new Error(`no introspection cache registered for "${name}"`);
-    }
-    try {
-      const cached = await cache.read();
-      if (cached) {
-        onProgress?.({
-          type: "adapter:cache-hit",
-          adapter: name,
-          message: `Using cached index for adapter "${name}".`,
-          cached: true
-        });
-        onProgress?.({
-          type: "adapter:end",
-          adapter: name,
-          message: `Finished indexing adapter "${name}".`,
-          cached: true
-        });
-        return cached;
-      }
-      onProgress?.({
-        type: "adapter:cache-miss",
-        adapter: name,
-        message: `No cached index for adapter "${name}".`,
-        cached: false
-      });
-      const ctx = createGroundingContext({
-        onProgress: (progress) => onProgress?.(this.#adapterProgressEvent(name, progress))
-      });
-      const fragments = await adapter.introspect(ctx);
-      await cache.write(fragments);
-      onProgress?.({
-        type: "adapter:end",
-        adapter: name,
-        message: `Finished indexing adapter "${name}".`,
-        cached: false
-      });
-      return fragments;
-    } catch (error) {
-      const reason = error instanceof Error ? error.message : String(error);
-      onProgress?.({
-        type: "adapter:error",
-        adapter: name,
-        message: `Failed indexing adapter "${name}": ${reason}`
-      });
-      throw new Error(`introspecting adapter "${name}": ${reason}`, {
-        cause: error
-      });
-    }
-  }
-  #adapterProgressEvent(adapter, progress) {
-    return {
-      type: progress.type,
-      adapter,
-      phase: progress.phase,
-      table: progress.table,
-      message: progress.message,
-      current: progress.current,
-      total: progress.total,
-      cached: false
-    };
-  }
   async toPairs(adapterName, factory) {
     const adapter = this.#requireAdapter(adapterName);
     const producer = factory(adapter);
     return producer.toPairs();
   }
-  async chat(options) {
-    return createUIMessageStream({
-      execute: async ({ writer }) => {
-        const context = this.#config.context;
-        const head = await context.headMessage();
-        if (!head || head.name !== "assistant") {
-          throw new Error(
-            "text2sql.chat: expected head to be an assistant message \u2014 call context.continue() before chat()"
-          );
-        }
-        writer.write({ type: "start", messageId: head.id });
-        const progress = (event) => {
-          writer.write({
-            type: TEXT2SQL_INDEX_PROGRESS_CHUNK,
-            data: event
-          });
-        };
-        context.set(...guidelines(), ...await this.#index(progress));
-        const chatAgent = agent2({
-          name: "text2sql",
-          sandbox: this.#config.sandbox,
-          model: this.#config.model,
-          context,
-          tools: this.#config.tools,
-          guardrails: [errorRecoveryGuardrail],
-          maxGuardrailRetries: 3
-        });
-        const chatStream = await chat(chatAgent, {
-          abortSignal: options?.abortSignal,
-          generateTitle: options?.generateTitle,
-          transform: this.#config.transform
-        });
-        writer.merge(chatStream);
-      }
-    });
-  }
 };
 export {
   Adapter,
+  AdapterIndexer,
   Checkpoint,
   FileCache,
   JsonCache,
@@ -5441,9 +5533,6 @@ export {
   SQLScopeError,
   SQLValidationError,
   ScopedFs,
-  SqlBacktickRewritePlugin,
-  SqlProxyEnforcementPlugin,
-  SqlProxyViolationError,
   SqliteFs,
   TEXT2SQL_INDEX_PROGRESS_CHUNK,
   Text2Sql,
@@ -5451,21 +5540,23 @@ export {
   applyTablesFilter,
   column,
   constraint,
-  createSqlCommand,
+  createSqlCommandHooks,
+  createSqlMetaHook,
   dialectInfo,
   filterRelationshipsByTables,
   filterTablesByName,
   getTablesWithRelated,
-  guidelines,
   hashConfig,
   index,
+  instructions,
   isValidAdapterName,
   matchesFilter,
   relationship,
-  sqlSandboxExtension,
+  repairSqlCommand,
   suggestionsAgent,
   table,
   toSql,
+  transformSqlCommand,
   validateAdapterNames,
   view
 };