@deepagents/text2sql 0.25.0 → 0.27.0

package/dist/index.js

@@ -8,7 +8,8 @@ function dialectInfo(input) {
     data: {
       dialect: input.dialect,
       ...input.version && { version: input.version },
-      ...input.database && { database: input.database }
+      ...input.database && { database: input.database },
+      ...input.details && { details: input.details }
     }
   };
 }
@@ -121,14 +122,30 @@ var Adapter = class {
     }
     return this.#toSchemaFragments(ctx);
   }
+  /**
+   * Resolve the allowed entity names (tables + views) from grounding config.
+   * Runs all configured groundings and returns the resolved set of names.
+   * Results are NOT cached — call once and store the result.
+   */
+  async resolveAllowedEntities() {
+    const ctx = createGroundingContext();
+    for (const fn of this.grounding) {
+      const grounding = fn(this);
+      await grounding.execute(ctx);
+    }
+    return [
+      ...ctx.tables.map((t) => t.name),
+      ...ctx.views.map((v) => v.name)
+    ];
+  }
   /**
    * Convert complete grounding context to schema fragments.
    * Called after all groundings have populated ctx with data.
    */
   #toSchemaFragments(ctx) {
-    const fragments2 = [];
+    const fragments = [];
     if (ctx.info) {
-      fragments2.push(
+      fragments.push(
         dialectInfo({
           dialect: ctx.info.dialect,
           version: ctx.info.version,
@@ -137,23 +154,23 @@ var Adapter = class {
       );
     }
     for (const t of ctx.tables) {
-      fragments2.push(this.#tableToFragment(t));
+      fragments.push(this.#tableToFragment(t));
     }
     for (const v of ctx.views) {
-      fragments2.push(this.#viewToFragment(v));
+      fragments.push(this.#viewToFragment(v));
     }
     const tableMap = new Map(ctx.tables.map((t) => [t.name, t]));
     for (const rel of ctx.relationships) {
       const sourceTable = tableMap.get(rel.table);
       const targetTable = tableMap.get(rel.referenced_table);
-      fragments2.push(
+      fragments.push(
         this.#relationshipToFragment(rel, sourceTable, targetTable)
       );
     }
     if (ctx.report) {
-      fragments2.push({ name: "businessContext", data: ctx.report });
+      fragments.push({ name: "businessContext", data: ctx.report });
     }
-    return fragments2;
+    return fragments;
   }
   /**
    * Convert a Table to a table fragment with nested column, index, and constraint fragments.
@@ -396,125 +413,10 @@ function getTablesWithRelated(allTables, relationships, filter) {
   return Array.from(result);
 }
 
-// packages/text2sql/src/lib/agents/developer.agent.ts
-import { tool } from "ai";
-import dedent from "dedent";
-import z2 from "zod";
-import { toState } from "@deepagents/agent";
-import { hint, persona as persona2 } from "@deepagents/context";
-
-// packages/text2sql/src/lib/agents/explainer.agent.ts
-import { groq } from "@ai-sdk/groq";
-import z from "zod";
-import {
-  ContextEngine,
-  InMemoryContextStore,
-  fragment,
-  persona,
-  structuredOutput,
-  user
-} from "@deepagents/context";
-var outputSchema = z.object({
-  explanation: z.string().describe("The explanation of the SQL query.")
-});
-async function explainSql(sql) {
-  const context = new ContextEngine({
-    store: new InMemoryContextStore(),
-    chatId: `explainer-${crypto.randomUUID()}`,
-    userId: "system"
-  });
-  context.set(
-    persona({
-      name: "explainer",
-      role: "You are an expert SQL tutor.",
-      objective: "Explain SQL queries in plain English that non-technical users understand"
-    }),
-    fragment("sql", sql),
-    fragment("task", "Focus on the intent and logic, not the syntax."),
-    user("Explain this SQL query in plain English to a non-technical user.")
-  );
-  const explainerOutput = structuredOutput({
-    model: groq("openai/gpt-oss-20b"),
-    context,
-    schema: outputSchema
-  });
-  return explainerOutput.generate();
-}
-
-// packages/text2sql/src/lib/agents/developer.agent.ts
-var tools = {
-  /**
-   * Validate SQL query syntax before execution.
-   */
-  validate_query: tool({
-    description: `Validate SQL query syntax before execution. Use this to check if your SQL is valid before running db_query. This helps catch errors early and allows you to correct the query if needed.`,
-    inputSchema: z2.object({
-      sql: z2.string().describe("The SQL query to validate.")
-    }),
-    execute: async ({ sql }, options) => {
-      const state = toState(options);
-      const result = await state.adapter.validate(sql);
-      if (typeof result === "string") {
-        return `Validation Error: ${result}`;
-      }
-      return "Query is valid.";
-    }
-  }),
-  /**
-   * Execute SQL query against the database.
-   */
-  db_query: tool({
-    description: `Internal tool to fetch data from the store's database. Write a SQL query to retrieve the information needed to answer the user's question. The results will be returned as data that you can then present to the user in natural language.`,
-    inputSchema: z2.object({
-      reasoning: z2.string().describe(
-        "Your reasoning for why this SQL query is relevant to the user request."
-      ),
-      sql: z2.string().min(1, { message: "SQL query cannot be empty." }).refine(
-        (sql) => sql.trim().toUpperCase().startsWith("SELECT") || sql.trim().toUpperCase().startsWith("WITH"),
-        {
-          message: "Only read-only SELECT or WITH queries are allowed."
-        }
-      ).describe("The SQL query to execute against the database.")
-    }),
-    execute: ({ sql }, options) => {
-      const state = toState(options);
-      return state.adapter.execute(sql);
-    }
-  }),
-  /**
-   * Get plain-English explanation of a SQL query.
-   */
-  explain_sql: tool({
-    description: dedent`
-      Get a plain-English explanation of a SQL query.
-      Use this to help the user understand what a query does.
-
-      The explanation focuses on intent and logic, not syntax.
-    `,
-    inputSchema: z2.object({
-      sql: z2.string().min(1).describe("The SQL query to explain")
-    }),
-    execute: async ({ sql }) => {
-      return explainSql(sql);
-    }
-  })
-};
-var fragments = [
-  persona2({
-    name: "developer_assistant",
-    role: "You are an expert SQL developer assistant helping power users build and refine queries.",
-    objective: "Help power users build and refine SQL queries with precision and clarity"
-  }),
-  hint("Be transparent: show the SQL you generate before explaining it"),
-  hint("Be precise: provide exact column names and table references"),
-  hint("Suggest refinements and alternatives when appropriate"),
-  hint("Support both natural language questions AND raw SQL input"),
-  hint("When validating user SQL, explain any errors clearly")
-];
-
 // packages/text2sql/src/lib/agents/exceptions.ts
 var sqlValidationMarker = Symbol("SQLValidationError");
 var unanswerableSqlMarker = Symbol("UnanswerableSQLError");
+var sqlScopeMarker = Symbol("SQLScopeError");
 var SQLValidationError = class _SQLValidationError extends Error {
   [sqlValidationMarker];
   constructor(message) {
@@ -537,9 +439,24 @@ var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
     return error instanceof _UnanswerableSQLError && error[unanswerableSqlMarker] === true;
   }
 };
+var SQLScopeError = class _SQLScopeError extends Error {
+  [sqlScopeMarker];
+  payload;
+  errorType;
+  constructor(payload) {
+    super(JSON.stringify(payload));
+    this.name = "SQLScopeError";
+    this.payload = payload;
+    this.errorType = payload.error_type;
+    this[sqlScopeMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLScopeError && error[sqlScopeMarker] === true;
+  }
+};
 
 // packages/text2sql/src/lib/agents/result-tools.ts
-import { tool as tool2 } from "ai";
+import { tool } from "ai";
 import { createBashTool } from "bash-tool";
 import chalk from "chalk";
 import {
@@ -552,7 +469,7 @@ import {
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as path from "node:path";
 import { v7 } from "uuid";
-import z3 from "zod";
+import z from "zod";
 function createCommand(name, subcommands) {
   const usageLines = Object.entries(subcommands).map(([, def]) => `  ${name} ${def.usage.padEnd(30)} ${def.description}`).join("\n");
   return defineCommand(name, async (args, ctx) => {
@@ -578,12 +495,17 @@ function validateReadOnly(query) {
   }
   return { valid: true };
 }
+var SQL_VALIDATE_REMINDER = "Always run `sql validate` before `sql run` to catch syntax errors early.";
 function createSqlCommand(adapter, metaStore) {
   return createCommand("sql", {
     run: {
       usage: 'run "SELECT ..."',
       description: "Execute query and store results",
       handler: async (args, ctx) => {
+        const store = metaStore.getStore();
+        if (store) {
+          store.value = { ...store.value, reminder: SQL_VALIDATE_REMINDER };
+        }
         const rawQuery = args.join(" ").trim().replace(/\\n/g, "\n").replace(/\\t/g, "	");
         if (!rawQuery) {
           return {
@@ -601,8 +523,9 @@ function createSqlCommand(adapter, metaStore) {
           };
         }
         const query = adapter.format(rawQuery);
-        const store = metaStore.getStore();
-        if (store) store.value = { formattedSql: query };
+        if (store) {
+          store.value = { ...store.value, formattedSql: query };
+        }
         const syntaxError = await adapter.validate(query);
         if (syntaxError) {
           return {
@@ -660,7 +583,7 @@ function createSqlCommand(adapter, metaStore) {
         }
         const query = adapter.format(rawQuery);
         const store = metaStore.getStore();
-        if (store) store.value = { formattedSql: query };
+        if (store) store.value = { ...store.value, formattedSql: query };
         const syntaxError = await adapter.validate(query);
         if (syntaxError) {
           return {
@@ -1358,7 +1281,7 @@ async function createResultTools(options) {
     customCommands: [sqlCommand],
     fs: filesystem
   });
-  const { sandbox, tools: tools2 } = await createBashTool({
+  const { sandbox, tools } = await createBashTool({
     sandbox: bashInstance,
     destination: "/",
     extraInstructions: 'Every bash tool call must include a brief non-empty "reasoning" input explaining why the command is needed.',
@@ -1383,14 +1306,14 @@ async function createResultTools(options) {
       return sandbox.executeCommand(command);
     }
   };
-  const bash = tool2({
-    ...tools2.bash,
-    inputSchema: z3.object({
-      command: z3.string().describe("The bash command to execute"),
-      reasoning: z3.string().trim().describe("Brief reason for executing this command")
+  const bash = tool({
+    ...tools.bash,
+    inputSchema: z.object({
+      command: z.string().describe("The bash command to execute"),
+      reasoning: z.string().trim().describe("Brief reason for executing this command")
     }),
     execute: async ({ command }, execOptions) => {
-      const execute = tools2.bash.execute;
+      const execute = tools.bash.execute;
       if (!execute) {
         throw new Error("bash tool execution is not available");
       }
@@ -1400,8 +1323,10 @@ async function createResultTools(options) {
       }
       return metaStore.run({}, async () => {
         const result = await execute({ command }, execOptions);
-        const meta = metaStore.getStore()?.value;
-        return meta ? { ...result, meta } : result;
+        const storeValue = metaStore.getStore()?.value;
+        if (!storeValue) return result;
+        const { reminder, ...meta } = storeValue;
+        return { ...result, meta, reminder };
       });
     },
     toModelOutput: ({ output }) => {
@@ -1415,14 +1340,14 @@ async function createResultTools(options) {
   return {
     sandbox: guardedSandbox,
     tools: {
-      ...tools2,
+      ...tools,
       bash
     }
   };
 }
 
 // packages/text2sql/src/lib/agents/sql.agent.ts
-import { groq as groq2 } from "@ai-sdk/groq";
+import { groq } from "@ai-sdk/groq";
 import {
   APICallError,
   JSONParseError,
@@ -1433,35 +1358,35 @@ import {
   defaultSettingsMiddleware,
   wrapLanguageModel
 } from "ai";
-import dedent2 from "dedent";
+import dedent from "dedent";
 import pRetry from "p-retry";
-import z4 from "zod";
+import z2 from "zod";
 import "@deepagents/agent";
 import {
-  ContextEngine as ContextEngine2,
-  InMemoryContextStore as InMemoryContextStore2,
+  ContextEngine,
+  InMemoryContextStore,
   example,
-  fragment as fragment2,
+  fragment,
   guardrail,
-  hint as hint2,
-  persona as persona3,
+  hint,
+  persona,
   policy,
-  structuredOutput as structuredOutput2,
-  user as user2,
+  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 = [
-  fragment2(
+  fragment(
     "schema_mapping",
     policy({
       rule: "Translate natural language into precise SQL grounded in available schema entities."
     }),
-    hint2("Preserve schema spelling exactly, including typos in column names.")
+    hint("Preserve schema spelling exactly, including typos in column names.")
   ),
-  fragment2(
+  fragment(
     "projection_minimality",
     policy({
       rule: "Return only columns requested by the question; do not add helper columns unless explicitly requested."
@@ -1472,17 +1397,17 @@ var SQL_AGENT_POLICIES = [
     policy({
       rule: "Prefer selecting schema columns directly without derived expressions when direct selection answers the request."
     }),
-    hint2(
+    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)."
     }),
-    hint2(
+    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.'
     )
   ),
-  fragment2(
+  fragment(
     "date_transform_safety",
     policy({
       rule: "Do not assume VARCHAR/TEXT values are parseable dates. Avoid date extraction functions on text columns by default."
@@ -1490,14 +1415,14 @@ var SQL_AGENT_POLICIES = [
     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."
     }),
-    hint2(
+    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."
     ),
-    hint2(
+    hint(
       "If a column already represents the requested concept (for example a stored year-like value), use the column as-is."
     )
   ),
-  fragment2(
+  fragment(
     "sql_minimality",
     guardrail({
       rule: "Never hallucinate tables or columns.",
@@ -1510,7 +1435,7 @@ var SQL_AGENT_POLICIES = [
       action: "Do not add date parsing, substring extraction, or derived columns unless explicitly required by the question or schema."
     })
   ),
-  fragment2(
+  fragment(
     "preflight_checklist",
     workflow({
       task: "Final SQL preflight before returning output",
@@ -1523,7 +1448,7 @@ var SQL_AGENT_POLICIES = [
       ]
     })
   ),
-  fragment2(
+  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."
@@ -1531,28 +1456,28 @@ var SQL_AGENT_POLICIES = [
     policy({
       rule: "Do not force the same entity instance to satisfy both conditions unless the question explicitly requests the same person/row/entity."
     }),
-    hint2(
+    hint(
       "Prefer INTERSECT (or logically equivalent set-based shape) over requiring the same physical row/entity to satisfy both conditions unless explicitly requested."
     ),
-    hint2(
+    hint(
       "When two conditions describe different row groups whose shared attribute is requested, build each group separately and intersect the attribute values."
     ),
-    hint2(
+    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."
     })
   ),
-  fragment2(
+  fragment(
     "predicate_column_alignment",
     policy({
       rule: "Match literal values to semantically compatible columns. Do not compare descriptive names to identifier columns."
     }),
-    hint2(
+    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."
     ),
-    hint2(
+    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({
@@ -1561,7 +1486,7 @@ var SQL_AGENT_POLICIES = [
     policy({
       rule: "For hosting/held semantics, prefer host_* relationship columns when available over generic *_id alternatives."
     }),
-    hint2(
+    hint(
       'Interpret wording like "held/hosted a competition or event" as a hosting relationship and map to host_* foreign keys when present.'
     ),
     policy({
@@ -1574,7 +1499,7 @@ var SQL_AGENT_POLICIES = [
       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."
     })
   ),
-  fragment2(
+  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."
@@ -1588,23 +1513,23 @@ var SQL_AGENT_POLICIES = [
     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.'
     }),
-    hint2(
+    hint(
       'Use DESC with LIMIT 1 for "most/highest/largest"; use ASC with LIMIT 1 for "least/lowest/smallest".'
     )
   ),
-  fragment2(
+  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."
     }),
-    hint2(
+    hint(
       "Map role-bearing relationship columns carefully (for example host_* foreign keys for hosting relationships) instead of generic IDs when role wording is explicit."
     ),
-    hint2(
+    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(...)).'
     )
   ),
-  fragment2(
+  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."
@@ -1612,17 +1537,17 @@ var SQL_AGENT_POLICIES = [
     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."
     }),
-    hint2(
+    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."
     ),
-    hint2(
+    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."
     ),
-    hint2(
+    hint(
       "Prefer INNER JOIN by default; use LEFT JOIN only when the question explicitly requests including unmatched rows or zero-related entities."
     )
   ),
-  fragment2(
+  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."
@@ -1630,11 +1555,11 @@ var SQL_AGENT_POLICIES = [
     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."
     }),
-    hint2(
+    hint(
       'For "how many <entities>" questions over relation records, default to COUNT(*) on qualifying rows unless explicit uniqueness language is present.'
     )
   ),
-  fragment2(
+  fragment(
     "query_shape_examples",
     example({
       question: "List categories ordered by how many records belong to each category.",
@@ -1662,13 +1587,13 @@ async function toSql(options) {
   const { maxRetries = 3 } = options;
   return withRetry(
     async (attemptNumber, errors, attempts) => {
-      const context = new ContextEngine2({
-        store: new InMemoryContextStore2(),
+      const context = new ContextEngine({
+        store: new InMemoryContextStore(),
         chatId: `sql-gen-${crypto.randomUUID()}`,
         userId: "system"
       });
       context.set(
-        persona3({
+        persona({
           name: "Freya",
           role: SQL_AGENT_ROLE,
           objective: SQL_AGENT_OBJECTIVE
@@ -1681,21 +1606,21 @@ async function toSql(options) {
       if (errors.length) {
         const lastError = errors.at(-1);
         context.set(
-          user2(dedent2`
+          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) ? user2(
+          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>`
-          ) : user2(
+          ) : user(
             `<validation_error>Your previous SQL query had the following error: ${lastError?.message}. Please fix the query.</validation_error>`
           )
         );
       } else {
         context.set(
-          user2(dedent2`
+          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.
 
@@ -1704,22 +1629,22 @@ Question: ${options.input}
         );
       }
       const temperature = RETRY_TEMPERATURES[attemptNumber - 1] ?? RETRY_TEMPERATURES[RETRY_TEMPERATURES.length - 1];
-      const baseModel = options.model ?? groq2("openai/gpt-oss-20b");
+      const baseModel = options.model ?? groq("openai/gpt-oss-20b");
       const model = wrapLanguageModel({
         model: baseModel,
         middleware: defaultSettingsMiddleware({ settings: { temperature } })
       });
-      const sqlOutput = structuredOutput2({
+      const sqlOutput = structuredOutput({
         model,
         context,
-        schema: z4.object({
-          result: z4.union([
-            z4.object({
-              sql: z4.string().describe("The SQL query that answers the question"),
-              reasoning: z4.string().describe("The reasoning steps taken to generate the SQL")
+        schema: z2.object({
+          result: z2.union([
+            z2.object({
+              sql: z2.string().describe("The SQL query that answers the question"),
+              reasoning: z2.string().describe("The reasoning steps taken to generate the SQL")
             }),
-            z4.object({
-              error: z4.string().describe(
+            z2.object({
+              error: z2.string().describe(
                 "Error message explaining why the question cannot be answered with the given schema"
               )
             })
@@ -1741,18 +1666,18 @@ Question: ${options.input}
       };
       if ("error" in output) {
         context.set(
-          user2(
+          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 = structuredOutput2({
+        const forcedSqlOutput = structuredOutput({
           model,
           context,
-          schema: z4.object({
-            sql: z4.string().describe(
+          schema: z2.object({
+            sql: z2.string().describe(
               "Best-effort SQL query that answers the core intent using only available schema entities."
             ),
-            reasoning: z4.string().describe("Reasoning steps for best-effort schema mapping.")
+            reasoning: z2.string().describe("Reasoning steps for best-effort schema mapping.")
           })
         });
         try {
@@ -1835,24 +1760,24 @@ async function withRetry(computation, options = { retries: 3 }) {
 }
 
 // packages/text2sql/src/lib/agents/suggestions.agents.ts
-import { groq as groq3 } from "@ai-sdk/groq";
-import dedent3 from "dedent";
-import z5 from "zod";
+import { groq as groq2 } from "@ai-sdk/groq";
+import dedent2 from "dedent";
+import z3 from "zod";
 import { agent, thirdPersonPrompt } from "@deepagents/agent";
 var suggestionsAgent = agent({
   name: "text2sql-suggestions",
-  model: groq3("openai/gpt-oss-20b"),
-  output: z5.object({
-    suggestions: z5.array(
-      z5.object({
-        question: z5.string().describe("A complex, high-impact business question."),
-        sql: z5.string().describe("The SQL statement needed to answer the question."),
-        businessValue: z5.string().describe("Why the question matters to stakeholders.")
+  model: groq2("openai/gpt-oss-20b"),
+  output: z3.object({
+    suggestions: z3.array(
+      z3.object({
+        question: z3.string().describe("A complex, high-impact business question."),
+        sql: z3.string().describe("The SQL statement needed to answer the question."),
+        businessValue: z3.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 dedent3`
+    return dedent2`
       ${thirdPersonPrompt()}
 
       <identity>
@@ -4818,9 +4743,9 @@ import {
   clarification,
   example as example2,
   explain,
-  fragment as fragment3,
+  fragment as fragment2,
   guardrail as guardrail2,
-  hint as hint3,
+  hint as hint2,
   policy as policy2,
   principle,
   quirk,
@@ -4833,9 +4758,9 @@ function reasoningFramework() {
     role(
       "You are a very strong reasoner and planner. Use these critical instructions to structure your plans, thoughts, and responses."
     ),
-    fragment3(
-      "meta-cognitive-reasoning-framework",
-      hint3(
+    fragment2(
+      "meta_cognitive_reasoning_framework",
+      hint2(
         "Before taking any action (either tool calls *or* responses to the user), you must proactively, methodically, and independently plan and reason about:"
       ),
       // 1) Logical dependencies and constraints
@@ -4944,13 +4869,12 @@ function reasoningFramework() {
     )
   ];
 }
-function guidelines(options = {}) {
-  const { date = "strict" } = options;
+function guidelines() {
   const baseTeachings = [
     // Include the meta-cognitive reasoning framework
     ...reasoningFramework(),
     // Prerequisite policies (must do X before Y)
-    fragment3(
+    fragment2(
       "prerequisite_policies",
       policy2({
         rule: "YOU MUST inspect schema structure and available tables",
@@ -4960,7 +4884,7 @@ function guidelines(options = {}) {
       policy2({
         rule: "YOU MUST resolve ambiguous business terms with the user",
         before: "making ANY assumptions about terminology meaning",
-        reason: "NEVER guess domain-specific language\u2014ask for clarification"
+        reason: "NEVER guess domain-specific language, instead ask for clarification"
       }),
       policy2({
         rule: "YOU MUST validate SQL syntax",
@@ -4974,8 +4898,8 @@ function guidelines(options = {}) {
       })
     ),
     // Few-shot: Applying reasoning principles
-    fragment3(
-      "reasoning-examples",
+    fragment2(
+      "reasoning_examples",
       example2({
         question: "Show me sales last month",
         answer: `Applying Principle 1 (Logical dependencies):
@@ -5014,17 +4938,21 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       })
     ),
     // Schema adherence - consolidated into clear rules
-    fragment3(
+    fragment2(
       "schema_adherence",
-      hint3(
-        "Use only tables and columns from the schema. For unspecified columns, use SELECT *. When showing related items, include IDs and requested details."
-      ),
-      hint3(
-        '"Show" means list items; "count" or "total" means aggregate. Use canonical values verbatim for filtering.'
-      )
+      guardrail2({
+        rule: "Use only tables and columns that exist in the schema.",
+        reason: "Inventing tables or columns produces invalid SQL and breaks schema grounding.",
+        action: "If the user requests unspecified fields, use SELECT *. When showing related items, include IDs and requested details."
+      }),
+      explain({
+        concept: "query intent words",
+        explanation: '"Show" asks for listing rows, while "count" or "total" asks for aggregation.',
+        therefore: 'Use listing queries for "show" requests, aggregate queries for "count" or "total", and use canonical schema values verbatim in filters.'
+      })
     ),
-    fragment3(
-      "Column statistics",
+    fragment2(
+      "column_statistics",
       explain({
         concept: "nDistinct in column stats",
         explanation: "Positive values are the estimated count of distinct values. Negative values represent the fraction of unique rows (e.g., -1 means all rows are unique, -0.5 means 50% unique)",
@@ -5035,18 +4963,18 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         explanation: "Measures how closely the physical row order matches the logical sort order of the column. Values near 1 or -1 mean the data is well-ordered; near 0 means scattered",
         therefore: "High correlation means range queries (BETWEEN, >, <) on that column benefit from index scans. Low correlation means the index is less effective for ranges"
       }),
-      hint3(
+      hint2(
         "When min/max stats are available, use them to validate filter values. If a user asks for values outside the known range, warn them the query may return no results."
       )
     ),
     // Joins - use relationship metadata
-    hint3(
+    hint2(
       "Use JOINs based on schema relationships. Favor PK/indexed columns; follow relationship metadata for direction and cardinality."
     ),
     // Aggregations - explain the concepts
-    fragment3(
-      "Aggregations",
-      hint3(
+    fragment2(
+      "aggregations",
+      hint2(
         "Apply COUNT, SUM, AVG when the question implies summarization. Use window functions for ranking, running totals, or row comparisons."
       ),
       explain({
@@ -5056,8 +4984,8 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       })
     ),
     // Query semantics - explain concepts and document quirks
-    fragment3(
-      "Query interpretation",
+    fragment2(
+      "query_interpretation",
       explain({
         concept: "threshold language",
         explanation: 'Words like "reach", "hit", "exceed" with a value imply a threshold being met or passed',
@@ -5071,7 +4999,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         issue: "NULL values behave unexpectedly in comparisons and aggregations",
         workaround: "Use IS NULL, IS NOT NULL, or COALESCE() to handle NULLs explicitly"
       }),
-      hint3(
+      hint2(
         "Always include mentioned filters from joined tables in WHERE conditions."
       )
     ),
@@ -5084,8 +5012,8 @@ 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
-    fragment3(
-      "Query safety",
+    fragment2(
+      "query_safety",
       guardrail2({
         rule: "Generate only valid, executable SELECT/WITH statements.",
         reason: "Read-only access prevents data modification.",
@@ -5100,19 +5028,9 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         rule: "Preserve query semantics.",
         reason: "Arbitrary modifications change results.",
         action: 'Only add LIMIT for explicit "top N" requests. Add ORDER BY for deterministic results.'
-      }),
-      guardrail2({
-        rule: "Seek clarification for genuine ambiguity.",
-        reason: "Prevents incorrect assumptions.",
-        action: "Ask a focused question before guessing."
       })
     ),
-    clarification({
-      when: "Ambiguous ranking language (top, best, active) without a metric.",
-      ask: "Clarify the ranking metric or definition.",
-      reason: "Ensures correct aggregation and ordering."
-    }),
-    hint3(
+    hint2(
       'Use sample cell values from schema hints to match exact casing and format in WHERE conditions (e.g., "Male" vs "male" vs "M").'
     ),
     workflow2({
@@ -5170,8 +5088,8 @@ 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."
     }),
-    fragment3(
-      "Bash tool usage",
+    fragment2(
+      "bash_tool_usage",
       workflow2({
         task: "Query execution",
         steps: [
@@ -5181,35 +5099,44 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
           "For large results, slice first: cat <path> | jq '.[:10]'"
         ]
       }),
-      hint3(
-        `You cannot access sql through a tool, it'll fail so the proper way to access it is through the bash tool using "sql run" and "sql validate" commands.`
-      ),
-      hint3(
-        "The sql command outputs: file path, column names (comma-separated), and row count. Use column names to construct precise jq queries."
-      ),
-      hint3(
-        'This is virtual bash environment and "sql" commands proxy to the database hence you cannot access sql files directly.'
-      ),
-      hint3(
-        "If a query fails, the sql command returns an error message in stderr."
-      )
-    )
-  ];
-  if (date === "strict") {
-    baseTeachings.push(
+      guardrail2({
+        rule: "Do not attempt SQL access through non-bash tools.",
+        reason: "SQL access is only available through the virtual bash environment.",
+        action: 'Use "sql run" and "sql validate" through bash.'
+      }),
+      explain({
+        concept: "sql command output format",
+        explanation: "The sql command returns a file path, comma-separated column names, and a row count.",
+        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.",
+        workaround: "Treat the returned result path as the artifact to inspect, rather than trying to access SQL files themselves."
+      }),
+      quirk({
+        issue: "If a query fails, the sql command reports the error on stderr.",
+        workaround: "Read stderr first and classify the failure before retrying or changing the query."
+      })
+    ),
+    fragment2(
+      "clarifications",
+      guardrail2({
+        rule: "Do not invent an answer when the available schema, results, or user request are insufficient to determine it.",
+        reason: "Prevents hallucinations and improves trustworthiness.",
+        action: "State that you do not have enough information to determine the answer and ask a focused clarification question."
+      }),
+      clarification({
+        when: "Ambiguous ranking language (top, best, active) without a metric.",
+        ask: "Clarify the ranking metric or definition.",
+        reason: "Ensures correct aggregation and ordering."
+      }),
       clarification({
         when: "The request targets time-based data without a date range.",
         ask: "Confirm the intended timeframe (e.g., last 30/90 days, YTD, specific year).",
         reason: "Prevents large scans and irrelevant results."
       })
-    );
-  } else {
-    baseTeachings.push(
-      hint3(
-        'When a month, day, or time period is mentioned without a year (e.g., "in August", "on Monday"), assume ALL occurrences of that period in the data. Do not ask for year clarification.'
-      )
-    );
-  }
+    )
+  ];
   return baseTeachings;
 }
 
@@ -5235,7 +5162,6 @@ var Text2Sql = class {
   #config;
   constructor(config) {
     this.#config = {
-      teachingsOptions: config.teachingsOptions,
       adapter: config.adapter,
       context: config.context,
       tools: config.tools ?? {},
@@ -5266,9 +5192,9 @@ var Text2Sql = class {
     if (cached) {
       return cached;
     }
-    const fragments2 = await this.#config.adapter.introspect();
-    await this.#config.introspection.write(fragments2);
-    return fragments2;
+    const fragments = await this.#config.adapter.introspect();
+    await this.#config.introspection.write(fragments);
+    return fragments;
   }
   /**
    * Generate training data pairs using a producer factory.
@@ -5299,7 +5225,7 @@ var Text2Sql = class {
     }
     const trackedFs = new TrackedFs(this.#config.filesystem);
     const context = this.#config.context(
-      ...guidelines(this.#config.teachingsOptions),
+      ...guidelines(),
       ...await this.index()
     );
     const lastItem = messages[messages.length - 1];
@@ -5317,7 +5243,7 @@ var Text2Sql = class {
     }
     const uiMessages = messages.map(chatMessageToUIMessage);
     const { mounts: skillMounts } = context.getSkillMounts();
-    const { tools: tools2 } = await createResultTools({
+    const { tools } = await createResultTools({
       adapter: this.#config.adapter,
       skillMounts,
       filesystem: trackedFs
@@ -5327,7 +5253,7 @@ var Text2Sql = class {
       model: this.#config.model,
       context,
       tools: {
-        ...tools2,
+        ...tools,
         ...this.#config.tools
       },
       guardrails: [errorRecoveryGuardrail],
@@ -5410,6 +5336,7 @@ export {
   MssqlFs,
   Point,
   PostgresFs,
+  SQLScopeError,
   SQLValidationError,
   ScopedFs,
   SqliteFs,