@deepagents/text2sql 0.11.0 → 0.12.0

package/dist/index.js

@@ -387,15 +387,16 @@ function getTablesWithRelated(allTables, relationships, filter) {
 
 // packages/text2sql/src/lib/agents/developer.agent.ts
 import { tool } from "ai";
-import dedent2 from "dedent";
+import dedent from "dedent";
 import z2 from "zod";
-import { generate, toState } from "@deepagents/agent";
+import { toState } from "@deepagents/agent";
 
 // packages/context/dist/index.js
 import { encode } from "gpt-tokenizer";
 import { generateId } from "ai";
 import pluralize from "pluralize";
 import { titlecase } from "stringcase";
+import chalk from "chalk";
 import { defineCommand } from "just-bash";
 import spawn from "nano-spawn";
 import "bash-tool";
@@ -405,7 +406,9 @@ import {
 } from "bash-tool";
 import YAML from "yaml";
 import { DatabaseSync } from "node:sqlite";
+import { groq } from "@ai-sdk/groq";
 import {
+  NoSuchToolError,
   Output,
   convertToModelMessages,
   createUIMessageStream,
@@ -415,7 +418,7 @@ import {
   stepCountIs,
   streamText
 } from "ai";
-import chalk from "chalk";
+import chalk2 from "chalk";
 import "zod";
 import "@deepagents/agent";
 var defaultTokenizer = {
@@ -547,6 +550,12 @@ function isFragmentObject(data) {
 function isMessageFragment(fragment2) {
   return fragment2.type === "message";
 }
+function fragment(name, ...children) {
+  return {
+    name,
+    data: children
+  };
+}
 function user(content) {
   const message2 = typeof content === "string" ? {
     id: generateId(),
@@ -639,6 +648,68 @@ var ContextRenderer = class {
     }
     return groups;
   }
+  /**
+   * Remove null/undefined from fragments and fragment data recursively.
+   * This protects renderers from nullish values and ensures they are ignored
+   * consistently across all output formats.
+   */
+  sanitizeFragments(fragments2) {
+    const sanitized = [];
+    for (const fragment2 of fragments2) {
+      const cleaned = this.sanitizeFragment(fragment2, /* @__PURE__ */ new WeakSet());
+      if (cleaned) {
+        sanitized.push(cleaned);
+      }
+    }
+    return sanitized;
+  }
+  sanitizeFragment(fragment2, seen) {
+    const data = this.sanitizeData(fragment2.data, seen);
+    if (data == null) {
+      return null;
+    }
+    return {
+      ...fragment2,
+      data
+    };
+  }
+  sanitizeData(data, seen) {
+    if (data == null) {
+      return void 0;
+    }
+    if (isFragment(data)) {
+      return this.sanitizeFragment(data, seen) ?? void 0;
+    }
+    if (Array.isArray(data)) {
+      if (seen.has(data)) {
+        return void 0;
+      }
+      seen.add(data);
+      const cleaned = [];
+      for (const item of data) {
+        const sanitizedItem = this.sanitizeData(item, seen);
+        if (sanitizedItem != null) {
+          cleaned.push(sanitizedItem);
+        }
+      }
+      return cleaned;
+    }
+    if (isFragmentObject(data)) {
+      if (seen.has(data)) {
+        return void 0;
+      }
+      seen.add(data);
+      const cleaned = {};
+      for (const [key, value] of Object.entries(data)) {
+        const sanitizedValue = this.sanitizeData(value, seen);
+        if (sanitizedValue != null) {
+          cleaned[key] = sanitizedValue;
+        }
+      }
+      return cleaned;
+    }
+    return data;
+  }
   /**
    * Template method - dispatches value to appropriate handler.
    */
@@ -666,7 +737,8 @@ var ContextRenderer = class {
 };
 var XmlRenderer = class extends ContextRenderer {
   render(fragments2) {
-    return fragments2.map((f) => this.#renderTopLevel(f)).filter(Boolean).join("\n");
+    const sanitized = this.sanitizeFragments(fragments2);
+    return sanitized.map((f) => this.#renderTopLevel(f)).filter(Boolean).join("\n");
   }
   #renderTopLevel(fragment2) {
     if (this.isPrimitive(fragment2.data)) {
@@ -679,10 +751,13 @@ var XmlRenderer = class extends ContextRenderer {
       const child = this.renderFragment(fragment2.data, { depth: 1, path: [] });
       return this.#wrap(fragment2.name, [child]);
     }
-    return this.#wrap(
-      fragment2.name,
-      this.renderEntries(fragment2.data, { depth: 1, path: [] })
-    );
+    if (isFragmentObject(fragment2.data)) {
+      return this.#wrap(
+        fragment2.name,
+        this.renderEntries(fragment2.data, { depth: 1, path: [] })
+      );
+    }
+    return "";
   }
   #renderArray(name, items, depth) {
     const fragmentItems = items.filter(isFragment);
@@ -690,9 +765,19 @@ var XmlRenderer = class extends ContextRenderer {
     const children = [];
     for (const item of nonFragmentItems) {
       if (item != null) {
-        children.push(
-          this.#leaf(pluralize.singular(name), String(item), depth + 1)
-        );
+        if (isFragmentObject(item)) {
+          children.push(
+            this.#wrapIndented(
+              pluralize.singular(name),
+              this.renderEntries(item, { depth: depth + 2, path: [] }),
+              depth + 1
+            )
+          );
+        } else {
+          children.push(
+            this.#leaf(pluralize.singular(name), String(item), depth + 1)
+          );
+        }
       }
     }
     if (this.options.groupFragments && fragmentItems.length > 0) {
@@ -734,8 +819,14 @@ ${this.#indent(safe, 2)}
     if (Array.isArray(data)) {
       return this.#renderArrayIndented(name, data, ctx.depth);
     }
-    const children = this.renderEntries(data, { ...ctx, depth: ctx.depth + 1 });
-    return this.#wrapIndented(name, children, ctx.depth);
+    if (isFragmentObject(data)) {
+      const children = this.renderEntries(data, {
+        ...ctx,
+        depth: ctx.depth + 1
+      });
+      return this.#wrapIndented(name, children, ctx.depth);
+    }
+    return "";
   }
   #renderArrayIndented(name, items, depth) {
     const fragmentItems = items.filter(isFragment);
@@ -743,9 +834,19 @@ ${this.#indent(safe, 2)}
     const children = [];
     for (const item of nonFragmentItems) {
       if (item != null) {
-        children.push(
-          this.#leaf(pluralize.singular(name), String(item), depth + 1)
-        );
+        if (isFragmentObject(item)) {
+          children.push(
+            this.#wrapIndented(
+              pluralize.singular(name),
+              this.renderEntries(item, { depth: depth + 2, path: [] }),
+              depth + 1
+            )
+          );
+        } else {
+          children.push(
+            this.#leaf(pluralize.singular(name), String(item), depth + 1)
+          );
+        }
       }
     }
     if (this.options.groupFragments && fragmentItems.length > 0) {
@@ -774,7 +875,19 @@ ${this.#indent(safe, 2)}
       return "";
     }
     const itemTag = pluralize.singular(key);
-    const children = items.filter((item) => item != null).map((item) => this.#leaf(itemTag, String(item), ctx.depth + 1));
+    const children = items.filter((item) => item != null).map((item) => {
+      if (isFragment(item)) {
+        return this.renderFragment(item, { ...ctx, depth: ctx.depth + 1 });
+      }
+      if (isFragmentObject(item)) {
+        return this.#wrapIndented(
+          itemTag,
+          this.renderEntries(item, { ...ctx, depth: ctx.depth + 2 }),
+          ctx.depth + 1
+        );
+      }
+      return this.#leaf(itemTag, String(item), ctx.depth + 1);
+    });
     return this.#wrapIndented(key, children, ctx.depth);
   }
   renderObject(key, obj, ctx) {
@@ -833,6 +946,7 @@ var ContextEngine = class {
   #pendingMessages = [];
   #store;
   #chatId;
+  #userId;
   #branchName;
   #branch = null;
   #chatData = null;
@@ -841,9 +955,13 @@ var ContextEngine = class {
     if (!options.chatId) {
       throw new Error("chatId is required");
     }
+    if (!options.userId) {
+      throw new Error("userId is required");
+    }
     this.#store = options.store;
     this.#chatId = options.chatId;
-    this.#branchName = options.branch ?? "main";
+    this.#userId = options.userId;
+    this.#branchName = "main";
   }
   /**
    * Initialize the chat and branch if they don't exist.
@@ -852,24 +970,11 @@ var ContextEngine = class {
     if (this.#initialized) {
       return;
     }
-    this.#chatData = await this.#store.upsertChat({ id: this.#chatId });
-    const existingBranch = await this.#store.getBranch(
-      this.#chatId,
-      this.#branchName
-    );
-    if (existingBranch) {
-      this.#branch = existingBranch;
-    } else {
-      this.#branch = {
-        id: crypto.randomUUID(),
-        chatId: this.#chatId,
-        name: this.#branchName,
-        headMessageId: null,
-        isActive: true,
-        createdAt: Date.now()
-      };
-      await this.#store.createBranch(this.#branch);
-    }
+    this.#chatData = await this.#store.upsertChat({
+      id: this.#chatId,
+      userId: this.#userId
+    });
+    this.#branch = await this.#store.getActiveBranch(this.#chatId);
     this.#initialized = true;
   }
   /**
@@ -929,6 +1034,7 @@ var ContextEngine = class {
     }
     return {
       id: this.#chatData.id,
+      userId: this.#chatData.userId,
       createdAt: this.#chatData.createdAt,
       updatedAt: this.#chatData.updatedAt,
       title: this.#chatData.title,
@@ -971,7 +1077,7 @@ var ContextEngine = class {
    *
    * @example
    * ```ts
-   * const context = new ContextEngine({ store, chatId: 'chat-1' })
+   * const context = new ContextEngine({ store, chatId: 'chat-1', userId: 'user-1' })
    *   .set(role('You are helpful'), user('Hello'));
    *
    * const { systemPrompt, messages } = await context.resolve();
@@ -1315,7 +1421,7 @@ var ContextEngine = class {
   }
   /**
    * Inspect the full context state for debugging.
-   * Returns a comprehensive JSON-serializable object with all context information.
+   * Returns a JSON-serializable object with context information.
    *
    * @param options - Inspection options (modelId and renderer required)
    * @returns Complete inspection data including estimates, rendered output, fragments, and graph
@@ -1378,6 +1484,26 @@ function guardrail(input) {
     }
   };
 }
+function explain(input) {
+  return {
+    name: "explain",
+    data: {
+      concept: input.concept,
+      explanation: input.explanation,
+      ...input.therefore && { therefore: input.therefore }
+    }
+  };
+}
+function example(input) {
+  return {
+    name: "example",
+    data: {
+      question: input.question,
+      answer: input.answer,
+      ...input.note && { note: input.note }
+    }
+  };
+}
 function clarification(input) {
   return {
     name: "clarification",
@@ -1399,6 +1525,15 @@ function workflow(input) {
     }
   };
 }
+function quirk(input) {
+  return {
+    name: "quirk",
+    data: {
+      issue: input.issue,
+      workaround: input.workaround
+    }
+  };
+}
 function styleGuide(input) {
   return {
     name: "styleGuide",
@@ -1409,12 +1544,40 @@ function styleGuide(input) {
     }
   };
 }
+function role(content) {
+  return {
+    name: "role",
+    data: content
+  };
+}
+function principle(input) {
+  return {
+    name: "principle",
+    data: {
+      title: input.title,
+      description: input.description,
+      ...input.policies?.length && { policies: input.policies }
+    }
+  };
+}
+function policy(input) {
+  return {
+    name: "policy",
+    data: {
+      rule: input.rule,
+      ...input.before && { before: input.before },
+      ...input.reason && { reason: input.reason },
+      ...input.policies?.length && { policies: input.policies }
+    }
+  };
+}
 function persona(input) {
   return {
     name: "persona",
     data: {
       name: input.name,
-      role: input.role,
+      ...input.role && { role: input.role },
+      ...input.objective && { objective: input.objective },
       ...input.tone && { tone: input.tone }
     }
   };
@@ -1422,6 +1585,9 @@ function persona(input) {
 function pass(part) {
   return { type: "pass", part };
 }
+function fail(feedback) {
+  return { type: "fail", feedback };
+}
 function runGuardrailChain(part, guardrails, context) {
   let currentPart = part;
   for (const guardrail2 of guardrails) {
@@ -1433,11 +1599,77 @@ function runGuardrailChain(part, guardrails, context) {
   }
   return pass(currentPart);
 }
+var errorRecoveryGuardrail = {
+  id: "error-recovery",
+  name: "API Error Recovery",
+  handle: (part, context) => {
+    if (part.type !== "error") {
+      return pass(part);
+    }
+    const errorText = part.errorText || "";
+    const prefix = chalk.bold.magenta("[ErrorRecovery]");
+    console.log(
+      `${prefix} ${chalk.red("Caught error:")} ${chalk.dim(errorText.slice(0, 150))}`
+    );
+    const logAndFail = (pattern, feedback) => {
+      console.log(
+        `${prefix} ${chalk.yellow("Pattern:")} ${chalk.cyan(pattern)}`
+      );
+      console.log(
+        `${prefix} ${chalk.green("Feedback:")} ${chalk.dim(feedback.slice(0, 80))}...`
+      );
+      return fail(feedback);
+    };
+    if (errorText.includes("Tool choice is none")) {
+      if (context.availableTools.length > 0) {
+        return logAndFail(
+          "Tool choice is none",
+          `I tried to call a tool that doesn't exist. Available tools: ${context.availableTools.join(", ")}. Let me use one of these instead.`
+        );
+      }
+      return logAndFail(
+        "Tool choice is none (no tools)",
+        "I tried to call a tool, but no tools are available. Let me respond with plain text instead."
+      );
+    }
+    if (errorText.includes("not in request.tools") || errorText.includes("tool") && errorText.includes("not found")) {
+      const toolMatch = errorText.match(/tool '([^']+)'/);
+      const toolName = toolMatch ? toolMatch[1] : "unknown";
+      if (context.availableTools.length > 0) {
+        return logAndFail(
+          `Unregistered tool: ${toolName}`,
+          `I tried to call "${toolName}" but it doesn't exist. Available tools: ${context.availableTools.join(", ")}. Let me use one of these instead.`
+        );
+      }
+      return logAndFail(
+        `Unregistered tool: ${toolName} (no tools)`,
+        `I tried to call "${toolName}" but no tools are available. Let me respond with plain text instead.`
+      );
+    }
+    if (errorText.includes("Failed to parse tool call arguments") || errorText.includes("parse tool call") || errorText.includes("invalid JSON")) {
+      return logAndFail(
+        "Malformed JSON arguments",
+        "I generated malformed JSON for the tool arguments. Let me format my tool call properly with valid JSON."
+      );
+    }
+    if (errorText.includes("Parsing failed")) {
+      return logAndFail(
+        "Parsing failed",
+        "My response format was invalid. Let me try again with a properly formatted response."
+      );
+    }
+    return logAndFail(
+      "Unknown error",
+      `An error occurred: ${errorText.slice(0, 100)}. Let me try a different approach.`
+    );
+  }
+};
 var STORE_DDL = `
 -- Chats table
 -- createdAt/updatedAt: DEFAULT for insert, inline SET for updates
 CREATE TABLE IF NOT EXISTS chats (
   id TEXT PRIMARY KEY,
+  userId TEXT NOT NULL,
   title TEXT,
   metadata TEXT,
   createdAt INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
@@ -1445,6 +1677,7 @@ CREATE TABLE IF NOT EXISTS chats (
 );
 
 CREATE INDEX IF NOT EXISTS idx_chats_updatedAt ON chats(updatedAt);
+CREATE INDEX IF NOT EXISTS idx_chats_userId ON chats(userId);
 
 -- Messages table (nodes in the DAG)
 CREATE TABLE IF NOT EXISTS messages (
@@ -1510,37 +1743,67 @@ var SqliteContextStore = class extends ContextStore {
     this.#db.exec("PRAGMA foreign_keys = ON");
     this.#db.exec(STORE_DDL);
   }
+  /**
+   * Execute a function within a transaction.
+   * Automatically commits on success or rolls back on error.
+   */
+  #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;
+    }
+  }
   // ==========================================================================
   // Chat Operations
   // ==========================================================================
   async createChat(chat) {
-    this.#db.prepare(
-      `INSERT INTO chats (id, title, metadata)
-         VALUES (?, ?, ?)`
-    ).run(
-      chat.id,
-      chat.title ?? null,
-      chat.metadata ? JSON.stringify(chat.metadata) : null
-    );
+    this.#useTransaction(() => {
+      this.#db.prepare(
+        `INSERT INTO chats (id, userId, title, metadata)
+           VALUES (?, ?, ?, ?)`
+      ).run(
+        chat.id,
+        chat.userId,
+        chat.title ?? null,
+        chat.metadata ? JSON.stringify(chat.metadata) : null
+      );
+      this.#db.prepare(
+        `INSERT INTO branches (id, chatId, name, headMessageId, isActive, createdAt)
+           VALUES (?, ?, 'main', NULL, 1, ?)`
+      ).run(crypto.randomUUID(), chat.id, Date.now());
+    });
   }
   async upsertChat(chat) {
-    const row = this.#db.prepare(
-      `INSERT INTO chats (id, title, metadata)
-         VALUES (?, ?, ?)
-         ON CONFLICT(id) DO UPDATE SET id = excluded.id
-         RETURNING *`
-    ).get(
-      chat.id,
-      chat.title ?? null,
-      chat.metadata ? JSON.stringify(chat.metadata) : null
-    );
-    return {
-      id: row.id,
-      title: row.title ?? void 0,
-      metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
-      createdAt: row.createdAt,
-      updatedAt: row.updatedAt
-    };
+    return this.#useTransaction(() => {
+      const row = this.#db.prepare(
+        `INSERT INTO chats (id, userId, title, metadata)
+           VALUES (?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET id = excluded.id
+           RETURNING *`
+      ).get(
+        chat.id,
+        chat.userId,
+        chat.title ?? null,
+        chat.metadata ? JSON.stringify(chat.metadata) : null
+      );
+      this.#db.prepare(
+        `INSERT OR IGNORE INTO branches (id, chatId, name, headMessageId, isActive, createdAt)
+           VALUES (?, ?, 'main', NULL, 1, ?)`
+      ).run(crypto.randomUUID(), chat.id, Date.now());
+      return {
+        id: row.id,
+        userId: row.userId,
+        title: row.title ?? void 0,
+        metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt
+      };
+    });
   }
   async getChat(chatId) {
     const row = this.#db.prepare("SELECT * FROM chats WHERE id = ?").get(chatId);
@@ -1549,6 +1812,7 @@ var SqliteContextStore = class extends ContextStore {
     }
     return {
       id: row.id,
+      userId: row.userId,
       title: row.title ?? void 0,
       metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
       createdAt: row.createdAt,
@@ -1572,16 +1836,33 @@ var SqliteContextStore = class extends ContextStore {
     ).get(...params);
     return {
       id: row.id,
+      userId: row.userId,
       title: row.title ?? void 0,
       metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
       createdAt: row.createdAt,
       updatedAt: row.updatedAt
     };
   }
-  async listChats() {
+  async listChats(options) {
+    const params = [];
+    let whereClause = "";
+    let limitClause = "";
+    if (options?.userId) {
+      whereClause = "WHERE c.userId = ?";
+      params.push(options.userId);
+    }
+    if (options?.limit !== void 0) {
+      limitClause = " LIMIT ?";
+      params.push(options.limit);
+      if (options.offset !== void 0) {
+        limitClause += " OFFSET ?";
+        params.push(options.offset);
+      }
+    }
     const rows = this.#db.prepare(
       `SELECT
           c.id,
+          c.userId,
           c.title,
           c.createdAt,
           c.updatedAt,
@@ -1590,11 +1871,13 @@ var SqliteContextStore = class extends ContextStore {
         FROM chats c
         LEFT JOIN messages m ON m.chatId = c.id
         LEFT JOIN branches b ON b.chatId = c.id
+        ${whereClause}
         GROUP BY c.id
-        ORDER BY c.updatedAt DESC`
-    ).all();
+        ORDER BY c.updatedAt DESC${limitClause}`
+    ).all(...params);
     return rows.map((row) => ({
       id: row.id,
+      userId: row.userId,
       title: row.title ?? void 0,
       messageCount: row.messageCount,
       branchCount: row.branchCount,
@@ -1602,6 +1885,25 @@ var SqliteContextStore = class extends ContextStore {
       updatedAt: row.updatedAt
     }));
   }
+  async deleteChat(chatId, options) {
+    return this.#useTransaction(() => {
+      const messageIds = this.#db.prepare("SELECT id FROM messages WHERE chatId = ?").all(chatId);
+      let sql = "DELETE FROM chats WHERE id = ?";
+      const params = [chatId];
+      if (options?.userId !== void 0) {
+        sql += " AND userId = ?";
+        params.push(options.userId);
+      }
+      const result = this.#db.prepare(sql).run(...params);
+      if (result.changes > 0 && messageIds.length > 0) {
+        const placeholders = messageIds.map(() => "?").join(", ");
+        this.#db.prepare(
+          `DELETE FROM messages_fts WHERE messageId IN (${placeholders})`
+        ).run(...messageIds.map((m) => m.id));
+      }
+      return result.changes > 0;
+    });
+  }
   // ==========================================================================
   // Message Operations (Graph Nodes)
   // ==========================================================================
@@ -1672,6 +1974,17 @@ var SqliteContextStore = class extends ContextStore {
     ).get(messageId);
     return row.hasChildren === 1;
   }
+  async getMessages(chatId) {
+    const chat = await this.getChat(chatId);
+    if (!chat) {
+      throw new Error(`Chat "${chatId}" not found`);
+    }
+    const activeBranch = await this.getActiveBranch(chatId);
+    if (!activeBranch?.headMessageId) {
+      return [];
+    }
+    return this.getMessageChain(activeBranch.headMessageId);
+  }
   // ==========================================================================
   // Branch Operations
   // ==========================================================================
@@ -1933,16 +2246,17 @@ var Agent = class _Agent {
       providerOptions: this.#options.providerOptions,
       model: this.#options.model,
       system: systemPrompt,
-      messages: convertToModelMessages(messages),
+      messages: await convertToModelMessages(messages),
       stopWhen: stepCountIs(25),
       tools: this.#options.tools,
       experimental_context: contextVariables,
+      experimental_repairToolCall: repairToolCall,
       toolChoice: this.#options.toolChoice,
       onStepFinish: (step) => {
         const toolCall = step.toolCalls.at(-1);
         if (toolCall) {
           console.log(
-            `Debug: ${chalk.yellow("ToolCalled")}: ${toolCall.toolName}(${JSON.stringify(toolCall.input)})`
+            `Debug: ${chalk2.yellow("ToolCalled")}: ${toolCall.toolName}(${JSON.stringify(toolCall.input)})`
           );
         }
       }
@@ -1991,8 +2305,9 @@ var Agent = class _Agent {
       providerOptions: this.#options.providerOptions,
       model: this.#options.model,
       system: systemPrompt,
-      messages: convertToModelMessages(messages),
-      stopWhen: stepCountIs(25),
+      messages: await convertToModelMessages(messages),
+      experimental_repairToolCall: repairToolCall,
+      stopWhen: stepCountIs(50),
       experimental_transform: config?.transform ?? smoothStream(),
       tools: this.#options.tools,
       experimental_context: contextVariables,
@@ -2001,7 +2316,7 @@ var Agent = class _Agent {
         const toolCall = step.toolCalls.at(-1);
         if (toolCall) {
           console.log(
-            `Debug: (${runId}) ${chalk.bold.yellow("ToolCalled")}: ${toolCall.toolName}(${JSON.stringify(toolCall.input)})`
+            `Debug: (${runId}) ${chalk2.bold.yellow("ToolCalled")}: ${toolCall.toolName}(${JSON.stringify(toolCall.input)})`
           );
         }
       }
@@ -2048,7 +2363,7 @@ var Agent = class _Agent {
                 guardrailFailed = true;
                 failureFeedback = checkResult.feedback;
                 console.log(
-                  chalk.yellow(
+                  chalk2.yellow(
                     `[${this.#options.name}] Guardrail triggered (attempt ${attempt}/${maxRetries}): ${failureFeedback.slice(0, 50)}...`
                   )
                 );
@@ -2065,7 +2380,7 @@ var Agent = class _Agent {
             }
             if (attempt >= maxRetries) {
               console.error(
-                chalk.red(
+                chalk2.red(
                   `[${this.#options.name}] Guardrail retry limit (${maxRetries}) exceeded.`
                 )
               );
@@ -2108,14 +2423,10 @@ function structuredOutput(options) {
   return {
     async generate(contextVariables, config) {
       if (!options.context) {
-        throw new Error(
-          `structuredOutput "${options.name}" is missing a context.`
-        );
+        throw new Error(`structuredOutput is missing a context.`);
       }
       if (!options.model) {
-        throw new Error(
-          `structuredOutput "${options.name}" is missing a model.`
-        );
+        throw new Error(`structuredOutput is missing a model.`);
       }
       const { messages, systemPrompt } = await options.context.resolve({
         renderer: new XmlRenderer()
@@ -2125,23 +2436,21 @@ function structuredOutput(options) {
         providerOptions: options.providerOptions,
         model: options.model,
         system: systemPrompt,
-        messages: convertToModelMessages(messages),
+        messages: await convertToModelMessages(messages),
         stopWhen: stepCountIs(25),
+        experimental_repairToolCall: repairToolCall,
         experimental_context: contextVariables,
-        experimental_output: Output.object({ schema: options.schema })
+        output: Output.object({ schema: options.schema }),
+        tools: options.tools
       });
-      return result.experimental_output;
+      return result.output;
     },
     async stream(contextVariables, config) {
       if (!options.context) {
-        throw new Error(
-          `structuredOutput "${options.name}" is missing a context.`
-        );
+        throw new Error(`structuredOutput is missing a context.`);
       }
       if (!options.model) {
-        throw new Error(
-          `structuredOutput "${options.name}" is missing a model.`
-        );
+        throw new Error(`structuredOutput is missing a model.`);
       }
       const { messages, systemPrompt } = await options.context.resolve({
         renderer: new XmlRenderer()
@@ -2151,37 +2460,74 @@ function structuredOutput(options) {
         providerOptions: options.providerOptions,
         model: options.model,
         system: systemPrompt,
-        messages: convertToModelMessages(messages),
-        stopWhen: stepCountIs(25),
+        experimental_repairToolCall: repairToolCall,
+        messages: await convertToModelMessages(messages),
+        stopWhen: stepCountIs(50),
         experimental_transform: config?.transform ?? smoothStream(),
         experimental_context: contextVariables,
-        experimental_output: Output.object({ schema: options.schema })
+        output: Output.object({ schema: options.schema }),
+        tools: options.tools
       });
     }
   };
 }
+var repairToolCall = async ({
+  toolCall,
+  tools: tools3,
+  inputSchema,
+  error
+}) => {
+  console.log(
+    `Debug: ${chalk2.yellow("RepairingToolCall")}: ${toolCall.toolName}`,
+    error.name
+  );
+  if (NoSuchToolError.isInstance(error)) {
+    return null;
+  }
+  const tool3 = tools3[toolCall.toolName];
+  const { output } = await generateText({
+    model: groq("openai/gpt-oss-20b"),
+    output: Output.object({ schema: tool3.inputSchema }),
+    prompt: [
+      `The model tried to call the tool "${toolCall.toolName}" with the following inputs:`,
+      JSON.stringify(toolCall.input),
+      `The tool accepts the following schema:`,
+      JSON.stringify(inputSchema(toolCall)),
+      "Please fix the inputs."
+    ].join("\n")
+  });
+  return { ...toolCall, input: JSON.stringify(output) };
+};
 
 // packages/text2sql/src/lib/agents/explainer.agent.ts
-import { groq } from "@ai-sdk/groq";
-import dedent from "dedent";
+import { groq as groq2 } from "@ai-sdk/groq";
 import z from "zod";
-import { agent as agent2 } from "@deepagents/agent";
-var explainerAgent = agent2({
-  name: "explainer",
-  model: groq("openai/gpt-oss-20b"),
-  prompt: (state) => dedent`
-    You are an expert SQL tutor.
-    Explain the following SQL query in plain English to a non-technical user.
-    Focus on the intent and logic, not the syntax.
-
-    <sql>
-    ${state?.sql}
-    </sql>
-  `,
-  output: z.object({
-    explanation: z.string().describe("The explanation of the SQL query.")
-  })
+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: groq2("openai/gpt-oss-20b"),
+    context,
+    schema: outputSchema
+  });
+  return explainerOutput.generate();
+}
 
 // packages/text2sql/src/lib/agents/developer.agent.ts
 var tools = {
@@ -2227,7 +2573,7 @@ var tools = {
    * Get plain-English explanation of a SQL query.
    */
   explain_sql: tool({
-    description: dedent2`
+    description: dedent`
       Get a plain-English explanation of a SQL query.
       Use this to help the user understand what a query does.
 
@@ -2237,17 +2583,15 @@ var tools = {
       sql: z2.string().min(1).describe("The SQL query to explain")
     }),
     execute: async ({ sql }) => {
-      const { experimental_output } = await generate(explainerAgent, [], {
-        sql
-      });
-      return { explanation: experimental_output.explanation };
+      return explainSql(sql);
     }
   })
 };
 var fragments = [
   persona({
     name: "developer_assistant",
-    role: "You are an expert SQL developer assistant helping power users build and refine queries."
+    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"),
@@ -2257,137 +2601,442 @@ var fragments = [
 ];
 var developer_agent_default = { tools, fragments };
 
-// packages/text2sql/src/lib/agents/suggestions.agents.ts
-import { groq as groq2 } from "@ai-sdk/groq";
-import dedent3 from "dedent";
-import z3 from "zod";
-import { agent as agent3, thirdPersonPrompt } from "@deepagents/agent";
-var suggestionsAgent = agent3({
-  name: "text2sql-suggestions",
-  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`
-      ${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>
+// packages/text2sql/src/lib/agents/result-tools.ts
+import { createBashTool as createBashTool2 } from "bash-tool";
+import chalk3 from "chalk";
+import {
+  Bash,
+  MountableFs,
+  OverlayFs,
+  ReadWriteFs,
+  defineCommand as defineCommand2
+} from "just-bash";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+function createCommand(name, subcommands) {
+  const usageLines = Object.entries(subcommands).map(([, def]) => `  ${name} ${def.usage.padEnd(30)} ${def.description}`).join("\n");
+  return defineCommand2(name, async (args, ctx) => {
+    const subcommand = args[0];
+    const restArgs = args.slice(1);
+    if (subcommand && subcommand in subcommands) {
+      return subcommands[subcommand].handler(restArgs, ctx);
+    }
+    return {
+      stdout: "",
+      stderr: `${name}: ${subcommand ? `unknown subcommand '${subcommand}'` : "missing subcommand"}
 
-      <response-format>
-        Return valid JSON that satisfies the defined output schema.
-      </response-format>
-    `;
+Usage:
+${usageLines}`,
+      exitCode: 1
+    };
+  });
+}
+function validateReadOnly(query) {
+  const upper = query.toUpperCase().trim();
+  if (!upper.startsWith("SELECT") && !upper.startsWith("WITH")) {
+    return { valid: false, error: "only SELECT or WITH queries allowed" };
   }
-});
-
-// packages/text2sql/src/lib/agents/text2sql.agent.ts
-import { groq as groq3 } from "@ai-sdk/groq";
-import { tool as tool2 } from "ai";
-import z4 from "zod";
-import { toState as toState2 } from "@deepagents/agent";
-import { scratchpad_tool } from "@deepagents/toolbox";
-var tools2 = {
-  validate_query: tool2({
-    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: z4.object({
-      sql: z4.string().describe("The SQL query to validate.")
-    }),
-    execute: async ({ sql }, options) => {
-      const state = toState2(options);
-      const result = await state.adapter.validate(sql);
-      if (typeof result === "string") {
-        return `Validation Error: ${result}`;
+  return { valid: true };
+}
+function createSqlCommand(adapter) {
+  return createCommand("sql", {
+    run: {
+      usage: 'run "SELECT ..."',
+      description: "Execute query and store results",
+      handler: async (args, ctx) => {
+        const query = args.join(" ").trim();
+        if (!query) {
+          return {
+            stdout: "",
+            stderr: "sql run: no query provided",
+            exitCode: 1
+          };
+        }
+        const validation = validateReadOnly(query);
+        if (!validation.valid) {
+          return {
+            stdout: "",
+            stderr: `sql run: ${validation.error}`,
+            exitCode: 1
+          };
+        }
+        try {
+          const rows = await adapter.execute(query);
+          const rowsArray = Array.isArray(rows) ? rows : [];
+          const filePath = `/results/${crypto.randomUUID()}.json`;
+          await ctx.fs.writeFile(filePath, JSON.stringify(rowsArray, null, 2));
+          const columns = rowsArray.length > 0 ? Object.keys(rowsArray[0]) : [];
+          return {
+            stdout: [
+              filePath,
+              `columns: ${columns.join(", ") || "(none)"}`,
+              `rows: ${rowsArray.length}`
+            ].join("\n") + "\n",
+            stderr: "",
+            exitCode: 0
+          };
+        } catch (error) {
+          return {
+            stdout: "",
+            stderr: `sql run: ${error instanceof Error ? error.message : String(error)}`,
+            exitCode: 1
+          };
+        }
       }
-      return "Query is valid.";
-    }
-  }),
-  db_query: tool2({
-    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: z4.object({
-      reasoning: z4.string().describe(
-        "Your reasoning for why this SQL query is relevant to the user request."
-      ),
-      sql: z4.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."
+    },
+    validate: {
+      usage: 'validate "SELECT ..."',
+      description: "Validate query syntax",
+      handler: (args) => {
+        const query = args.join(" ").trim();
+        if (!query) {
+          return {
+            stdout: "",
+            stderr: "sql validate: no query provided",
+            exitCode: 1
+          };
         }
-      ).describe("The SQL query to execute against the database.")
-    }),
-    execute: ({ sql }, options) => {
-      const state = toState2(options);
-      return state.adapter.execute(sql);
+        const validation = validateReadOnly(query);
+        if (!validation.valid) {
+          return {
+            stdout: "",
+            stderr: `sql validate: ${validation.error}`,
+            exitCode: 1
+          };
+        }
+        return {
+          stdout: "valid\n",
+          stderr: "",
+          exitCode: 0
+        };
+      }
+    }
+  });
+}
+async function createResultTools(options) {
+  const { adapter, chatId, messageId } = options;
+  const sqlCommand = createSqlCommand(adapter);
+  const chatDir = path.join(process.cwd(), "artifacts", chatId);
+  const resultsDir = path.join(chatDir, messageId, "results");
+  await fs.mkdir(resultsDir, { recursive: true });
+  const filesystem = new MountableFs({
+    base: new OverlayFs({ root: process.cwd() }),
+    mounts: [
+      {
+        mountPoint: "/results",
+        filesystem: new ReadWriteFs({ root: resultsDir })
+      },
+      {
+        mountPoint: "/artifacts",
+        filesystem: new ReadWriteFs({ root: chatDir })
+      }
+    ]
+  });
+  const bashInstance = new Bash({
+    customCommands: [sqlCommand],
+    fs: filesystem
+  });
+  const { bash, sandbox } = await createBashTool2({
+    sandbox: bashInstance,
+    destination: "/",
+    uploadDirectory: {
+      source: process.cwd(),
+      include: "packages/text2sql/src/skills/**/*.md"
+    },
+    onBeforeBashCall: ({ command }) => {
+      console.log(chalk3.cyan(`[onBeforeBashCall]: ${command}`));
+      return { command };
+    },
+    onAfterBashCall: ({ result }) => {
+      if (result.exitCode !== 0) {
+        console.log(chalk3.yellow(`[onAfterBashCall]: ${result.exitCode}`));
+      }
+      return { result };
+    }
+  });
+  return { bash, sandbox };
+}
+
+// packages/text2sql/src/lib/agents/sql.agent.ts
+import { groq as groq3 } from "@ai-sdk/groq";
+import {
+  APICallError,
+  JSONParseError,
+  NoContentGeneratedError,
+  NoObjectGeneratedError,
+  NoOutputGeneratedError,
+  TypeValidationError
+} from "ai";
+import { Console } from "node:console";
+import { createWriteStream } from "node:fs";
+import pRetry from "p-retry";
+import z3 from "zod";
+import "@deepagents/agent";
+var logger = new Console({
+  stdout: createWriteStream("./sql-agent.log", { flags: "a" }),
+  stderr: createWriteStream("./sql-agent-error.log", { flags: "a" }),
+  inspectOptions: { depth: null }
+});
+function extractSql(output) {
+  const match = output.match(/```sql\n?([\s\S]*?)```/);
+  return match ? match[1].trim() : output.trim();
+}
+var marker = Symbol("SQLValidationError");
+var SQLValidationError = class _SQLValidationError extends Error {
+  [marker];
+  constructor(message2) {
+    super(message2);
+    this.name = "SQLValidationError";
+    this[marker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLValidationError && error[marker] === true;
+  }
+};
+var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
+  constructor(message2) {
+    super(message2);
+    this.name = "UnanswerableSQLError";
+  }
+  static isInstance(error) {
+    return error instanceof _UnanswerableSQLError;
+  }
+};
+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: "You are an expert SQL query generator. You translate natural language questions into precise, efficient SQL queries based on the provided database schema.",
+          objective: "Translate natural language questions into precise, efficient SQL queries"
+        }),
+        ...options.instructions,
+        ...options.schemaFragments
+      );
+      if (errors.length) {
+        context.set(
+          user(options.input),
+          user(
+            `<validation_error>Your previous SQL query had the following error: ${errors.at(-1)?.message}. Please fix the query.</validation_error>`
+          )
+        );
+      } else {
+        context.set(user(options.input));
+      }
+      const sqlOutput = structuredOutput({
+        model: options.model ?? groq3("openai/gpt-oss-20b"),
+        context,
+        schema: z3.union([
+          z3.object({
+            sql: z3.string().describe("The SQL query that answers the question"),
+            reasoning: z3.string().optional().describe("The reasoning steps taken to generate the SQL")
+          }),
+          z3.object({
+            error: z3.string().describe(
+              "Error message explaining why the question cannot be answered with the given schema"
+            )
+          })
+        ])
+      });
+      const output = await sqlOutput.generate();
+      if ("error" in output) {
+        throw new UnanswerableSQLError(output.error);
+      }
+      const sql = extractSql(output.sql);
+      const validationError = await options.adapter.validate(sql);
+      if (validationError) {
+        throw new SQLValidationError(validationError);
+      }
+      return {
+        attempts,
+        sql,
+        errors: errors.length ? errors.map(formatErrorMessage) : void 0
+      };
+    },
+    { 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;
+}
+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 (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) {
+        logger.error(`toSQL`, context.error);
+        console.log(
+          `Attempt ${context.attemptNumber} failed. There are ${context.retriesLeft} retries left.`
+        );
+        errors.push(context.error);
+      }
+    }
+  );
+}
+
+// packages/text2sql/src/lib/agents/suggestions.agents.ts
+import { groq as groq4 } from "@ai-sdk/groq";
+import dedent2 from "dedent";
+import z4 from "zod";
+import { agent as agent2, thirdPersonPrompt } from "@deepagents/agent";
+var suggestionsAgent = agent2({
+  name: "text2sql-suggestions",
+  model: groq4("openai/gpt-oss-20b"),
+  output: z4.object({
+    suggestions: z4.array(
+      z4.object({
+        question: z4.string().describe("A complex, high-impact business question."),
+        sql: z4.string().describe("The SQL statement needed to answer the question."),
+        businessValue: z4.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/agents/text2sql.agent.ts
+import { tool as tool2 } from "ai";
+import z5 from "zod";
+import { toState as toState2 } from "@deepagents/agent";
+import { scratchpad_tool } from "@deepagents/toolbox";
+var tools2 = {
+  validate_query: tool2({
+    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: z5.object({
+      sql: z5.string().describe("The SQL query to validate.")
+    }),
+    execute: async ({ sql }, options) => {
+      const state = toState2(options);
+      const result = await state.adapter.validate(sql);
+      if (typeof result === "string") {
+        return `Validation Error: ${result}`;
+      }
+      return "Query is valid.";
+    }
+  }),
+  db_query: tool2({
+    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: z5.object({
+      reasoning: z5.string().describe(
+        "Your reasoning for why this SQL query is relevant to the user request."
+      ),
+      sql: z5.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 = toState2(options);
+      return state.adapter.execute(sql);
     }
   }),
   scratchpad: scratchpad_tool
 };
-var t_a_g = agent({
-  model: groq3("openai/gpt-oss-20b"),
-  tools: tools2,
-  name: "text2sql"
-  // prompt: (state) => {
-  //   return `
-  //   ${state?.teachings || ''}
-  //   ${state?.introspection || ''}
-  //   ${chainOfThoughtPrompt}
-  //   ${fewShotExamples}
-  // `;
-  // },
-});
 
 // packages/text2sql/src/lib/checkpoint.ts
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import pLimit from "p-limit";
 var Checkpoint = class _Checkpoint {
-  constructor(path2, configHash, points) {
-    this.path = path2;
-    this.configHash = configHash;
+  points;
+  path;
+  configHash;
+  constructor(path3, configHash, points) {
     this.points = points;
+    this.path = path3;
+    this.configHash = configHash;
   }
-  points;
   /**
    * Load checkpoint from file, or return empty checkpoint if none exists.
    * Handles corrupted files and config changes gracefully.
    */
   static async load(options) {
-    const { path: path2, configHash } = options;
-    if (existsSync(path2)) {
+    const { path: path3, configHash } = options;
+    if (existsSync(path3)) {
       try {
-        const content = readFileSync(path2, "utf-8");
+        const content = readFileSync(path3, "utf-8");
         const file = JSON.parse(content);
         if (configHash && file.configHash && file.configHash !== configHash) {
           console.log("\u26A0 Config changed, starting fresh");
-          return new _Checkpoint(path2, configHash, {});
+          return new _Checkpoint(path3, configHash, {});
         }
         const points = file.points ?? {};
         const totalEntries = Object.values(points).reduce(
@@ -2395,14 +3044,14 @@ var Checkpoint = class _Checkpoint {
           0
         );
         console.log(`\u2713 Resuming from checkpoint (${totalEntries} entries)`);
-        return new _Checkpoint(path2, configHash, points);
+        return new _Checkpoint(path3, configHash, points);
       } catch {
         console.log("\u26A0 Checkpoint corrupted, starting fresh");
-        return new _Checkpoint(path2, configHash, {});
+        return new _Checkpoint(path3, configHash, {});
       }
     }
     console.log("Starting new checkpoint");
-    return new _Checkpoint(path2, configHash, {});
+    return new _Checkpoint(path3, configHash, {});
   }
   /**
    * Run a single computation with checkpointing.
@@ -2487,14 +3136,16 @@ function hash(value) {
   return createHash("md5").update(JSON.stringify(value)).digest("hex");
 }
 var Point = class {
+  #cache;
+  data;
+  persist;
   constructor(data, persist) {
-    this.data = data;
-    this.persist = persist;
     this.#cache = new Map(
       data.entries.map((e) => [e.inputHash, e.output])
     );
+    this.data = data;
+    this.persist = persist;
   }
-  #cache;
   /**
    * Execute computation if input wasn't processed before.
    * Returns cached output if input hash exists, otherwise executes, saves, and returns.
@@ -2534,12 +3185,12 @@ import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync2 } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import path from "node:path";
+import path2 from "node:path";
 var FileCache = class {
   path;
   constructor(watermark, extension = ".txt") {
     const hash2 = createHash2("md5").update(watermark).digest("hex");
-    this.path = path.join(tmpdir(), `text2sql-${hash2}${extension}`);
+    this.path = path2.join(tmpdir(), `text2sql-${hash2}${extension}`);
   }
   async get() {
     if (existsSync2(this.path)) {
@@ -2567,302 +3218,328 @@ var JsonCache = class extends FileCache {
   }
 };
 
-// packages/text2sql/src/lib/sql.ts
-import {
-  APICallError as APICallError2,
-  InvalidToolInputError,
-  NoSuchToolError,
-  ToolCallRepairError,
-  generateId as generateId3
-} from "ai";
-import "@deepagents/agent";
-
-// packages/text2sql/src/lib/agents/sql.agent.ts
-import { groq as groq4 } from "@ai-sdk/groq";
-import {
-  APICallError,
-  JSONParseError,
-  NoContentGeneratedError,
-  NoObjectGeneratedError,
-  NoOutputGeneratedError,
-  TypeValidationError,
-  defaultSettingsMiddleware,
-  wrapLanguageModel
-} from "ai";
-import { Console } from "node:console";
-import { createWriteStream } from "node:fs";
-import pRetry from "p-retry";
-import z5 from "zod";
-import "@deepagents/agent";
-var logger = new Console({
-  stdout: createWriteStream("./sql-agent.log", { flags: "a" }),
-  stderr: createWriteStream("./sql-agent-error.log", { flags: "a" }),
-  inspectOptions: { depth: null }
-});
-var RETRY_TEMPERATURES = [0, 0.2, 0.3];
-function extractSql(output) {
-  const match = output.match(/```sql\n?([\s\S]*?)```/);
-  return match ? match[1].trim() : output.trim();
-}
-var marker = Symbol("SQLValidationError");
-var SQLValidationError = class _SQLValidationError extends Error {
-  [marker];
-  constructor(message2) {
-    super(message2);
-    this.name = "SQLValidationError";
-    this[marker] = true;
-  }
-  static isInstance(error) {
-    return error instanceof _SQLValidationError && error[marker] === true;
-  }
-};
-var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
-  constructor(message2) {
-    super(message2);
-    this.name = "UnanswerableSQLError";
-  }
-  static isInstance(error) {
-    return error instanceof _UnanswerableSQLError;
-  }
-};
-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()}`
-      });
-      context.set(
-        persona({
-          name: "Freya",
-          role: "You are an expert SQL query generator. You translate natural language questions into precise, efficient SQL queries based on the provided database schema."
-        }),
-        ...options.instructions,
-        ...options.schemaFragments
-      );
-      if (errors.length) {
-        context.set(
-          user(options.input),
-          user(
-            `<validation_error>Your previous SQL query had the following error: ${errors.at(-1)?.message}. Please fix the query.</validation_error>`
-          )
-        );
-      } else {
-        context.set(user(options.input));
-      }
-      const sqlOutput = structuredOutput({
-        name: "text2sql",
-        model: wrapLanguageModel({
-          model: options.model ?? groq4("openai/gpt-oss-20b"),
-          middleware: defaultSettingsMiddleware({
-            settings: {
-              temperature: RETRY_TEMPERATURES[attemptNumber - 1] ?? 0.3,
-              topP: 1
-            }
-          })
-        }),
-        context,
-        schema: z5.union([
-          z5.object({
-            sql: z5.string().describe("The SQL query that answers the question"),
-            reasoning: z5.string().optional().describe("The reasoning steps taken to generate the SQL")
+// packages/text2sql/src/lib/instructions.ts
+function reasoningFramework() {
+  return [
+    role(
+      "You are a very strong reasoner and planner. Use these critical instructions to structure your plans, thoughts, and responses."
+    ),
+    fragment(
+      "Meta-cognitive reasoning framework",
+      hint(
+        "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
+      principle({
+        title: "Logical dependencies and constraints",
+        description: "Analyze the intended action against the following factors. Resolve conflicts in order of importance:",
+        policies: [
+          policy({
+            rule: "Policy-based rules, mandatory prerequisites, and constraints."
           }),
-          z5.object({
-            error: z5.string().describe(
-              "Error message explaining why the question cannot be answered with the given schema"
-            )
+          policy({
+            rule: "Order of operations: Ensure taking an action does not prevent a subsequent necessary action.",
+            policies: [
+              "The user may request actions in a random order, but you may need to reorder operations to maximize successful completion of the task."
+            ]
+          }),
+          policy({
+            rule: "Other prerequisites (information and/or actions needed)."
+          }),
+          policy({ rule: "Explicit user constraints or preferences." })
+        ]
+      }),
+      // 2) Risk assessment
+      principle({
+        title: "Risk assessment",
+        description: "What are the consequences of taking the action? Will the new state cause any future issues?",
+        policies: [
+          "For exploratory tasks (like searches), missing *optional* parameters is a LOW risk. **Prefer calling the tool with the available information over asking the user, unless** your Rule 1 (Logical Dependencies) reasoning determines that optional information is required for a later step in your plan."
+        ]
+      }),
+      // 3) Abductive reasoning and hypothesis exploration
+      principle({
+        title: "Abductive reasoning and hypothesis exploration",
+        description: "At each step, identify the most logical and likely reason for any problem encountered.",
+        policies: [
+          "Look beyond immediate or obvious causes. The most likely reason may not be the simplest and may require deeper inference.",
+          "Hypotheses may require additional research. Each hypothesis may take multiple steps to test.",
+          "Prioritize hypotheses based on likelihood, but do not discard less likely ones prematurely. A low-probability event may still be the root cause."
+        ]
+      }),
+      // 4) Outcome evaluation and adaptability
+      principle({
+        title: "Outcome evaluation and adaptability",
+        description: "Does the previous observation require any changes to your plan?",
+        policies: [
+          "If your initial hypotheses are disproven, actively generate new ones based on the gathered information."
+        ]
+      }),
+      // 5) Information availability
+      principle({
+        title: "Information availability",
+        description: "Incorporate all applicable and alternative sources of information, including:",
+        policies: [
+          "Using available tools and their capabilities",
+          "All policies, rules, checklists, and constraints",
+          "Previous observations and conversation history",
+          "Information only available by asking the user"
+        ]
+      }),
+      // 6) Precision and Grounding
+      principle({
+        title: "Precision and Grounding",
+        description: "Ensure your reasoning is extremely precise and relevant to each exact ongoing situation.",
+        policies: [
+          "Verify your claims by quoting the exact applicable information (including policies) when referring to them."
+        ]
+      }),
+      // 7) Completeness
+      principle({
+        title: "Completeness",
+        description: "Ensure that all requirements, constraints, options, and preferences are exhaustively incorporated into your plan.",
+        policies: [
+          policy({
+            rule: "Resolve conflicts using the order of importance in #1."
+          }),
+          policy({
+            rule: "Avoid premature conclusions: There may be multiple relevant options for a given situation.",
+            policies: [
+              "To check for whether an option is relevant, reason about all information sources from #5.",
+              "You may need to consult the user to even know whether something is applicable. Do not assume it is not applicable without checking."
+            ]
+          }),
+          policy({
+            rule: "Review applicable sources of information from #5 to confirm which are relevant to the current state."
           })
-        ])
-      });
-      const output = await sqlOutput.generate();
-      if ("error" in output) {
-        throw new UnanswerableSQLError(output.error);
-      }
-      const sql = extractSql(output.sql);
-      const validationError = await options.adapter.validate(sql);
-      if (validationError) {
-        throw new SQLValidationError(validationError);
-      }
-      return {
-        attempts,
-        sql,
-        errors: errors.length ? errors.map(formatErrorMessage) : void 0
-      };
-    },
-    { 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;
-}
-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 (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) {
-        logger.error(`toSQL`, context.error);
-        console.log(
-          `Attempt ${context.attemptNumber} failed. There are ${context.retriesLeft} retries left.`
-        );
-        errors.push(context.error);
-      }
-    }
-  );
+        ]
+      }),
+      // 8) Persistence and patience
+      principle({
+        title: "Persistence and patience",
+        description: "Do not give up unless all the reasoning above is exhausted.",
+        policies: [
+          "Don't be dissuaded by time taken or user frustration.",
+          "This persistence must be intelligent: On *transient* errors (e.g. please try again), you *must* retry **unless an explicit retry limit (e.g., max x tries) has been reached**. If such a limit is hit, you *must* stop. On *other* errors, you must change your strategy or arguments, not repeat the same failed call."
+        ]
+      }),
+      // 9) Inhibit your response
+      principle({
+        title: "Inhibit your response",
+        description: "Only take an action after all the above reasoning is completed. Once you've taken an action, you cannot take it back."
+      })
+    )
+  ];
 }
-
-// packages/text2sql/src/lib/teach/teachings.ts
 function guidelines(options = {}) {
   const { date = "strict" } = options;
   const baseTeachings = [
-    // Schema adherence
-    hint(
-      "Use only tables and columns that exist in the schema. Never reference non-existent entities."
-    ),
-    hint(
-      "If the user asks to show a table or entity without specifying columns, use SELECT *."
-    ),
-    hint(
-      "When showing items associated with another entity, include the item ID and the related details requested."
-    ),
-    hint(
-      'When asked to "show" items, list them unless the user explicitly asks to count or total.'
-    ),
-    hint(
-      "Use canonical/LowCardinality values verbatim for filtering; [rows/size] hints suggest when to aggregate instead of listing."
-    ),
-    // Joins and relationships
-    hint(
-      "Use appropriate JOINs based on the relationships defined in the schema."
-    ),
-    hint(
-      "Favor PK/indexed columns for joins and filters; follow relationship metadata for join direction and cardinality."
-    ),
-    // Aggregations and calculations
-    hint(
-      "Apply proper aggregations (COUNT, SUM, AVG, etc.) when the question implies summarization."
-    ),
-    hint(
-      'When asked "how many X are there" about types/categories/statuses (e.g., "how many statuses are there?"), use COUNT(DISTINCT column). This asks about variety, not row count.'
+    // Include the meta-cognitive reasoning framework
+    ...reasoningFramework(),
+    // Prerequisite policies (must do X before Y)
+    fragment(
+      "Prerequisite policies",
+      policy({
+        rule: "YOU MUST inspect schema structure and available tables",
+        before: "generating ANY SQL query",
+        reason: "NEVER generate SQL without knowing valid tables, columns, and relationships"
+      }),
+      policy({
+        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"
+      }),
+      policy({
+        rule: "YOU MUST validate SQL syntax",
+        before: "executing ANY query against the database",
+        reason: "NEVER execute unvalidated queries"
+      }),
+      policy({
+        rule: "YOU MUST complete ALL reasoning steps",
+        before: "taking ANY tool call or response action",
+        reason: "Once an action is taken, it CANNOT be undone. NO EXCEPTIONS."
+      })
     ),
-    hint(
-      "Use window functions when the question requires ranking, running totals, or comparisons across rows."
+    // Few-shot: Applying reasoning principles
+    fragment(
+      "Reasoning examples",
+      example({
+        question: "Show me sales last month",
+        answer: `Applying Principle 1 (Logical dependencies):
+- Need: schema to know which table has sales data
+- Need: clarify "last month" = calendar month or rolling 30 days?
+
+Applying Principle 5 (Information availability):
+- Schema shows: orders table with created_at, total columns
+- Missing: user's definition of "last month"
+
+Action: Ask user for date range clarification BEFORE generating SQL.`
+      }),
+      example({
+        question: "Why did my query return no results?",
+        answer: `Applying Principle 3 (Abductive reasoning):
+- Hypothesis 1 (most likely): Filter too restrictive
+- Hypothesis 2: Data doesn't exist for that period
+- Hypothesis 3: JOIN eliminated matching rows
+
+Testing hypotheses:
+1. Remove filters one by one to isolate the issue
+2. Check date range actually has data
+3. Run subqueries separately to verify each table
+
+Action: Start with most likely hypothesis, test incrementally. NEVER guess.`
+      }),
+      example({
+        question: "Get me the top customers",
+        answer: `Applying Principle 1 (Logical dependencies):
+- "Top" is ambiguous\u2014by revenue? by order count? by recency?
+
+Applying Principle 9 (Inhibition):
+- MUST NOT generate SQL until "top" is defined
+
+Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or most recent activity?"`
+      })
     ),
-    // Query semantics
-    hint(
-      'Words like "reach", "reached", "hit" with a value (e.g., "temperature reach 80") mean >= (greater than or equal), not = (exact match).'
+    // Schema adherence - consolidated into clear rules
+    fragment(
+      "Schema adherence",
+      hint(
+        "Use only tables and columns from the schema. For unspecified columns, use SELECT *. When showing related items, include IDs and requested details."
+      ),
+      hint(
+        '"Show" means list items; "count" or "total" means aggregate. Use canonical values verbatim for filtering.'
+      )
     ),
+    // Joins - use relationship metadata
     hint(
-      'For "shared by" two groups or mutually exclusive conditions (e.g., population > 1500 AND < 500), use INTERSECT between separate queries. A single WHERE with contradictory AND returns nothing.'
+      "Use JOINs based on schema relationships. Favor PK/indexed columns; follow relationship metadata for direction and cardinality."
     ),
-    hint(
-      'When filtering by a specific value from a joined table (e.g., "students who registered course statistics"), always include that WHERE condition. Do not omit mentioned filters.'
+    // Aggregations - explain the concepts
+    fragment(
+      "Aggregations",
+      hint(
+        "Apply COUNT, SUM, AVG when the question implies summarization. Use window functions for ranking, running totals, or row comparisons."
+      ),
+      explain({
+        concept: "counting variety vs counting rows",
+        explanation: '"How many types/categories/statuses exist?" asks about variety (unique values), not total row count',
+        therefore: "Use COUNT(DISTINCT column) for variety questions"
+      })
     ),
-    hint(
-      "Handle NULL values appropriately using IS NULL, IS NOT NULL, or COALESCE."
+    // Query semantics - explain concepts and document quirks
+    fragment(
+      "Query interpretation",
+      explain({
+        concept: "threshold language",
+        explanation: 'Words like "reach", "hit", "exceed" with a value imply a threshold being met or passed',
+        therefore: "Translate to >= (greater than or equal), not = (exact match)"
+      }),
+      quirk({
+        issue: "Contradictory WHERE conditions (e.g., value > 100 AND value < 50) return empty results",
+        workaround: 'Use INTERSECT between separate queries when finding items "shared by" groups with mutually exclusive conditions'
+      }),
+      quirk({
+        issue: "NULL values behave unexpectedly in comparisons and aggregations",
+        workaround: "Use IS NULL, IS NOT NULL, or COALESCE() to handle NULLs explicitly"
+      }),
+      hint(
+        "Always include mentioned filters from joined tables in WHERE conditions."
+      )
     ),
-    // Style and readability
+    // Style preferences
     styleGuide({
-      prefer: 'For table aliases, use the full table name (e.g., "FROM users AS users", "JOIN order_items AS order_items"). For column aliases, use descriptive names that reflect the data (e.g., "COUNT(*) AS total_orders").',
-      never: "Use abbreviated table aliases (u, oi, ca) or generic positional aliases (t1, t2, a, b)."
+      prefer: "Full table names as aliases (users AS users). Descriptive column aliases (COUNT(*) AS total_count).",
+      never: "Abbreviated aliases (u, oi) or positional aliases (t1, t2, a, b)."
     }),
     styleGuide({
-      prefer: "Summaries should be concise, business-friendly, highlight key comparisons, and add a short helpful follow-up when useful."
+      prefer: "Concise, business-friendly summaries with key comparisons and helpful follow-ups."
     }),
-    // Guardrails - Query safety
-    guardrail({
-      rule: "Generate ONLY valid, executable SQL.",
-      reason: "Invalid SQL wastes resources and confuses users.",
-      action: "Validate syntax and schema references before returning."
-    }),
-    guardrail({
-      rule: "Only generate SELECT/WITH statements (read-only queries).",
-      reason: "Prevents accidental data modification.",
-      action: "Never generate INSERT, UPDATE, DELETE, DROP, or other DDL/DML statements."
-    }),
-    guardrail({
-      rule: "Avoid unbounded scans on large tables.",
-      reason: "Protects performance and prevents runaway queries.",
-      action: "Ensure filters are applied on indexed columns before querying broad fact tables."
-    }),
-    guardrail({
-      rule: "Do not add LIMIT unless explicitly requested.",
-      action: 'Only add LIMIT when user explicitly asks for "top N", "first N", or similar. Do NOT add LIMIT for "list all", "show all", or simple "list" queries.',
-      reason: "Adding arbitrary limits changes query semantics."
-    }),
-    guardrail({
-      rule: "Add ORDER BY where appropriate for deterministic results.",
-      reason: "Ensures consistent query output.",
-      action: "Include ORDER BY when results have a natural ordering or when combined with LIMIT."
-    }),
-    guardrail({
-      rule: "Prevent cartesian or guesswork joins.",
-      reason: "Protect correctness and performance.",
-      action: "If join keys are missing or unclear, inspect relationships and ask for the intended join path before executing."
+    // Safety guardrails - consolidated
+    fragment(
+      "Query safety",
+      guardrail({
+        rule: "Generate only valid, executable SELECT/WITH statements.",
+        reason: "Read-only access prevents data modification.",
+        action: "Never generate INSERT, UPDATE, DELETE, DROP, or DDL statements."
+      }),
+      guardrail({
+        rule: "Avoid unbounded scans and cartesian joins.",
+        reason: "Protects performance and correctness.",
+        action: "Apply filters on indexed columns. If join keys are unclear, ask for clarification."
+      }),
+      guardrail({
+        rule: "Preserve query semantics.",
+        reason: "Arbitrary modifications change results.",
+        action: 'Only add LIMIT for explicit "top N" requests. Add ORDER BY for deterministic results.'
+      }),
+      guardrail({
+        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."
     }),
-    guardrail({
-      rule: "Ensure the query is optimized for the schema.",
-      reason: "Better performance and resource usage.",
-      action: "Use indexed columns for filtering, avoid SELECT * on large joins, prefer specific column selection when appropriate."
+    hint(
+      'Use sample cell values from schema hints to match exact casing and format in WHERE conditions (e.g., "Male" vs "male" vs "M").'
+    ),
+    workflow({
+      task: "SQL generation",
+      steps: [
+        "Schema linking: identify which tables and columns are mentioned or implied by the question.",
+        "Check if column names match question terms (e.g., Total_X). Select directly if match found.",
+        "Identify SQL patterns needed: aggregation, segmentation, time range, ranking.",
+        "Select tables and relationships. Note lookup tables and filter values from schema.",
+        "Plan join/filter/aggregation order based on table sizes and indexes.",
+        "Generate SQL that answers the question.",
+        "Verify: mentally translate SQL back to natural language. Does it match the original question?"
+      ]
     }),
-    guardrail({
-      rule: "When facing genuine ambiguity with multiple valid interpretations, seek clarification.",
-      reason: "Prevents incorrect assumptions in edge cases.",
-      action: "Ask a focused clarifying question before proceeding with a guess."
+    workflow({
+      task: "Error recovery",
+      triggers: ["SQL error", "query failed", "execution error"],
+      steps: [
+        "Classify the error type: syntax error, missing join, wrong aggregation, invalid column, type mismatch.",
+        "For syntax errors: check SQL keywords, quotes, parentheses balance.",
+        "For missing join: identify unlinked tables and add appropriate JOIN clause.",
+        "For wrong aggregation: verify GROUP BY includes all non-aggregated SELECT columns.",
+        "For invalid column: re-check schema for correct column name and table.",
+        "Apply targeted fix based on error classification. Avoid blind regeneration."
+      ],
+      notes: "Maximum 3 retry attempts. If still failing, explain the issue to the user."
     }),
-    // Clarifications
-    clarification({
-      when: 'The request uses ambiguous scoring or ranking language (e.g., "top", "best", "active") without a metric.',
-      ask: "Clarify the ranking metric or definition before writing the query.",
-      reason: "Ensures the correct aggregation/ordering is used."
+    workflow({
+      task: "Complex query decomposition",
+      triggers: [
+        "multiple conditions",
+        "nested requirements",
+        "compare across",
+        "for each"
+      ],
+      steps: [
+        "Identify if question has multiple independent parts or nested dependencies.",
+        "For independent parts: break into sub-questions, solve each, then combine with UNION or JOIN.",
+        "For nested dependencies: solve inner requirement first, use result in outer query (subquery or CTE).",
+        "For comparisons across groups: use window functions or self-joins.",
+        "Combine sub-results into final answer. Verify completeness."
+      ],
+      notes: "Complex questions often need CTEs (WITH clauses) for clarity and reusability."
     }),
-    // Workflow
     workflow({
-      task: "SQL generation plan",
+      task: "Multi-turn context",
+      triggers: ["follow-up", "and also", "what about", "same but", "instead"],
       steps: [
-        'Scan column names for terms matching the question. If a phrase like "total X" or "number of Y" matches a column name (e.g., Total_X, Num_Y), select that column directly instead of aggregating.',
-        "Translate the question into SQL patterns (aggregation, segmentation, time range, ranking) only if no column name match.",
-        "Choose tables/relations that satisfy those patterns; note lookup tables and filter values implied by schema hints.",
-        "Sketch join/filter/aggregation order considering table sizes, indexes, and stats.",
-        "Generate precise, validated SQL that answers the question."
-      ]
+        'Identify references to previous context: "it", "that", "those", "the same".',
+        "Resolve references using conversation history: which tables, filters, or results were mentioned.",
+        'For refinements ("but only X"): add filter to previous query.',
+        'For extensions ("and also Y"): expand SELECT or add JOIN.',
+        'For pivots ("what about Z instead"): replace the changed element, keep unchanged parts.',
+        "Maintain consistency with previous query structure when possible."
+      ],
+      notes: "If reference is ambiguous, ask which previous result or entity the user means."
     })
   ];
   if (date === "strict") {
@@ -2884,6 +3561,14 @@ function guidelines(options = {}) {
 }
 
 // packages/text2sql/src/lib/sql.ts
+import {
+  APICallError as APICallError2,
+  InvalidToolInputError,
+  NoSuchToolError as NoSuchToolError2,
+  ToolCallRepairError,
+  generateId as generateId3
+} from "ai";
+import "@deepagents/agent";
 var Text2Sql = class {
   #config;
   constructor(config) {
@@ -2971,21 +3656,52 @@ var Text2Sql = class {
     const schemaFragments = await this.index();
     const context = new ContextEngine({
       store: this.#config.store,
-      chatId: params.chatId
+      chatId: params.chatId,
+      userId: params.userId
     }).set(
-      ...this.#config.instructions,
+      ...schemaFragments,
       ...this.#buildRenderingInstructions(),
-      ...schemaFragments
+      fragment(
+        "Bash tool usage",
+        workflow({
+          task: "Query execution",
+          steps: [
+            'Execute SQL through bash tool: sql run "SELECT ..."',
+            "Read the output: file path, column names, and row count.",
+            "Use column names to construct jq filters: cat <path> | jq '.[] | {col1, col2}'",
+            "For large results, slice first: cat <path> | jq '.[:10]'"
+          ]
+        }),
+        hint(
+          "The sql command outputs: file path, column names (comma-separated), and row count. Use column names to construct precise jq queries."
+        ),
+        hint(
+          "If a query fails, the sql command returns an error message in stderr."
+        )
+      ),
+      ...this.#config.instructions
     );
     const userMsg = messages.at(-1);
     if (userMsg) {
       context.set(user(userMsg));
       await context.save();
     }
-    const chatAgent = t_a_g.clone({
+    const messageId = userMsg?.id ?? generateId3();
+    const { bash } = await createResultTools({
+      adapter: this.#config.adapter,
+      chatId: params.chatId,
+      messageId
+    });
+    const chatAgent = agent({
+      name: "text2sql",
       model: this.#config.model,
       context,
-      tools: { ...t_a_g.tools, ...this.#config.tools }
+      tools: {
+        bash,
+        ...this.#config.tools
+      },
+      guardrails: [errorRecoveryGuardrail],
+      maxGuardrailRetries: 3
     });
     const result = await chatAgent.stream({});
     return result.toUIMessageStream({
@@ -3009,7 +3725,8 @@ var Text2Sql = class {
     const schemaFragments = await this.index();
     const context = new ContextEngine({
       store: this.#config.store,
-      chatId: params.chatId
+      chatId: params.chatId,
+      userId: params.userId
     }).set(
       ...developer_agent_default.fragments,
       ...this.#config.instructions,
@@ -3043,7 +3760,7 @@ var Text2Sql = class {
     });
   }
   #formatError(error) {
-    if (NoSuchToolError.isInstance(error)) {
+    if (NoSuchToolError2.isInstance(error)) {
       return "The model tried to call an unknown tool.";
     } else if (InvalidToolInputError.isInstance(error)) {
       return "The model called a tool with invalid arguments.";
@@ -3062,10 +3779,13 @@ export {
   FileCache,
   JsonCache,
   Point,
+  SQLValidationError,
   Text2Sql,
+  UnanswerableSQLError,
   applyTablesFilter,
   column,
   constraint,
+  createResultTools,
   dialectInfo,
   filterRelationshipsByTables,
   filterTablesByName,
@@ -3076,8 +3796,8 @@ export {
   matchesFilter,
   relationship,
   suggestionsAgent,
-  t_a_g,
   table,
+  toSql,
   view
 };
 //# sourceMappingURL=index.js.map