@deepagents/text2sql 0.10.2 → 0.12.0

package/dist/lib/adapters/postgres/index.js

@@ -1,3 +1,94 @@
+// packages/text2sql/src/lib/fragments/schema.ts
+function dialectInfo(input) {
+  return {
+    name: "dialectInfo",
+    data: {
+      dialect: input.dialect,
+      ...input.version && { version: input.version },
+      ...input.database && { database: input.database }
+    }
+  };
+}
+function table(input) {
+  return {
+    name: "table",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      ...input.rowCount != null && { rowCount: input.rowCount },
+      ...input.sizeHint && { sizeHint: input.sizeHint },
+      columns: input.columns,
+      ...input.indexes?.length && { indexes: input.indexes },
+      ...input.constraints?.length && { constraints: input.constraints }
+    }
+  };
+}
+function column(input) {
+  return {
+    name: "column",
+    data: {
+      name: input.name,
+      type: input.type,
+      ...input.pk && { pk: true },
+      ...input.fk && { fk: input.fk },
+      ...input.unique && { unique: true },
+      ...input.notNull && { notNull: true },
+      ...input.default && { default: input.default },
+      ...input.indexed && { indexed: true },
+      ...input.values?.length && { values: input.values },
+      ...input.stats && { stats: input.stats }
+    }
+  };
+}
+function index(input) {
+  return {
+    name: "index",
+    data: {
+      name: input.name,
+      columns: input.columns,
+      ...input.unique && { unique: true },
+      ...input.type && { type: input.type }
+    }
+  };
+}
+function constraint(input) {
+  return {
+    name: "constraint",
+    data: {
+      name: input.name,
+      type: input.type,
+      ...input.columns?.length && { columns: input.columns },
+      ...input.definition && { definition: input.definition },
+      ...input.defaultValue && { defaultValue: input.defaultValue },
+      ...input.referencedTable && { referencedTable: input.referencedTable },
+      ...input.referencedColumns?.length && {
+        referencedColumns: input.referencedColumns
+      }
+    }
+  };
+}
+function view(input) {
+  return {
+    name: "view",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      columns: input.columns,
+      ...input.definition && { definition: input.definition }
+    }
+  };
+}
+function relationship(input) {
+  return {
+    name: "relationship",
+    data: {
+      from: input.from,
+      to: input.to,
+      ...input.cardinality && { cardinality: input.cardinality }
+    }
+  };
+}
+
 // packages/text2sql/src/lib/adapters/groundings/context.ts
 function createGroundingContext() {
   return {
@@ -10,24 +101,169 @@ function createGroundingContext() {
 
 // packages/text2sql/src/lib/adapters/adapter.ts
 var Adapter = class {
+  /**
+   * Introspect the database schema and return context fragments.
+   *
+   * Executes all configured groundings to populate the context, then
+   * generates fragments from the complete context data.
+   *
+   * @param ctx - Optional grounding context for sharing state between groundings
+   * @returns Array of context fragments representing the database schema
+   */
   async introspect(ctx = createGroundingContext()) {
-    const lines = [];
     for (const fn of this.grounding) {
       const grounding = fn(this);
-      lines.push({
-        tag: grounding.tag,
-        fn: await grounding.execute(ctx)
-      });
+      await grounding.execute(ctx);
+    }
+    return this.#toSchemaFragments(ctx);
+  }
+  /**
+   * Convert complete grounding context to schema fragments.
+   * Called after all groundings have populated ctx with data.
+   */
+  #toSchemaFragments(ctx) {
+    const fragments = [];
+    if (ctx.info) {
+      fragments.push(
+        dialectInfo({
+          dialect: ctx.info.dialect,
+          version: ctx.info.version,
+          database: ctx.info.database
+        })
+      );
+    }
+    for (const t of ctx.tables) {
+      fragments.push(this.#tableToFragment(t));
+    }
+    for (const v of ctx.views) {
+      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);
+      fragments.push(
+        this.#relationshipToFragment(rel, sourceTable, targetTable)
+      );
+    }
+    if (ctx.report) {
+      fragments.push({ name: "businessContext", data: ctx.report });
+    }
+    return fragments;
+  }
+  /**
+   * Convert a Table to a table fragment with nested column, index, and constraint fragments.
+   */
+  #tableToFragment(t) {
+    const pkConstraint = t.constraints?.find((c) => c.type === "PRIMARY_KEY");
+    const pkColumns = new Set(pkConstraint?.columns ?? []);
+    const notNullColumns = new Set(
+      t.constraints?.filter((c) => c.type === "NOT_NULL").flatMap((c) => c.columns ?? []) ?? []
+    );
+    const defaultByColumn = /* @__PURE__ */ new Map();
+    for (const c of t.constraints?.filter((c2) => c2.type === "DEFAULT") ?? []) {
+      for (const col of c.columns ?? []) {
+        if (c.defaultValue != null) {
+          defaultByColumn.set(col, c.defaultValue);
+        }
+      }
     }
-    return lines.map(({ fn, tag }) => {
-      const description = fn();
-      if (description === null) {
-        return "";
+    const uniqueColumns = new Set(
+      t.constraints?.filter((c) => c.type === "UNIQUE" && c.columns?.length === 1).flatMap((c) => c.columns ?? []) ?? []
+    );
+    const fkByColumn = /* @__PURE__ */ new Map();
+    for (const c of t.constraints?.filter((c2) => c2.type === "FOREIGN_KEY") ?? []) {
+      const cols = c.columns ?? [];
+      const refCols = c.referencedColumns ?? [];
+      for (let i = 0; i < cols.length; i++) {
+        const refCol = refCols[i] ?? refCols[0] ?? cols[i];
+        fkByColumn.set(cols[i], `${c.referencedTable}.${refCol}`);
       }
-      return `<${tag}>
-${description}
-</${tag}>`;
-    }).join("\n");
+    }
+    const columnFragments = t.columns.map(
+      (col) => column({
+        name: col.name,
+        type: col.type,
+        pk: pkColumns.has(col.name) || void 0,
+        fk: fkByColumn.get(col.name),
+        unique: uniqueColumns.has(col.name) || void 0,
+        notNull: notNullColumns.has(col.name) || void 0,
+        default: defaultByColumn.get(col.name),
+        indexed: col.isIndexed || void 0,
+        values: col.values,
+        stats: col.stats
+      })
+    );
+    const indexFragments = (t.indexes ?? []).map(
+      (idx) => index({
+        name: idx.name,
+        columns: idx.columns,
+        unique: idx.unique,
+        type: idx.type
+      })
+    );
+    const constraintFragments = (t.constraints ?? []).filter(
+      (c) => c.type === "CHECK" || c.type === "UNIQUE" && (c.columns?.length ?? 0) > 1
+    ).map(
+      (c) => constraint({
+        name: c.name,
+        type: c.type,
+        columns: c.columns,
+        definition: c.definition
+      })
+    );
+    return table({
+      name: t.name,
+      schema: t.schema,
+      rowCount: t.rowCount,
+      sizeHint: t.sizeHint,
+      columns: columnFragments,
+      indexes: indexFragments.length > 0 ? indexFragments : void 0,
+      constraints: constraintFragments.length > 0 ? constraintFragments : void 0
+    });
+  }
+  /**
+   * Convert a View to a view fragment with nested column fragments.
+   */
+  #viewToFragment(v) {
+    const columnFragments = v.columns.map(
+      (col) => column({
+        name: col.name,
+        type: col.type,
+        values: col.values,
+        stats: col.stats
+      })
+    );
+    return view({
+      name: v.name,
+      schema: v.schema,
+      columns: columnFragments,
+      definition: v.definition
+    });
+  }
+  /**
+   * Convert a Relationship to a relationship fragment.
+   * Infers cardinality from row counts if available.
+   */
+  #relationshipToFragment(rel, sourceTable, targetTable) {
+    const sourceCount = sourceTable?.rowCount;
+    const targetCount = targetTable?.rowCount;
+    let cardinality;
+    if (sourceCount != null && targetCount != null && targetCount > 0) {
+      const ratio = sourceCount / targetCount;
+      if (ratio > 5) {
+        cardinality = "many-to-one";
+      } else if (ratio < 1.2 && ratio > 0.8) {
+        cardinality = "one-to-one";
+      } else if (ratio < 0.2) {
+        cardinality = "one-to-many";
+      }
+    }
+    return relationship({
+      from: { table: rel.table, columns: rel.from },
+      to: { table: rel.referenced_table, columns: rel.to },
+      cardinality
+    });
   }
   /**
    * Convert unknown database value to number.
@@ -83,16 +319,19 @@ ${description}
 
 // packages/text2sql/src/lib/adapters/groundings/abstract.grounding.ts
 var AbstractGrounding = class {
-  tag;
-  constructor(tag) {
-    this.tag = tag;
+  /**
+   * Grounding identifier for debugging/logging.
+   */
+  name;
+  constructor(name) {
+    this.name = name;
   }
 };
 
 // packages/text2sql/src/lib/adapters/groundings/column-stats.grounding.ts
 var ColumnStatsGrounding = class extends AbstractGrounding {
   constructor(config = {}) {
-    super("column_stats");
+    super("columnStats");
   }
   /**
    * Execute the grounding process.
@@ -101,79 +340,73 @@ var ColumnStatsGrounding = class extends AbstractGrounding {
   async execute(ctx) {
     const allContainers = [...ctx.tables, ...ctx.views];
     for (const container of allContainers) {
-      for (const column of container.columns) {
+      for (const column2 of container.columns) {
         try {
-          const stats = await this.collectStats(container.name, column);
+          const stats = await this.collectStats(container.name, column2);
           if (stats) {
-            column.stats = stats;
+            column2.stats = stats;
           }
         } catch (error) {
           console.warn(
             "Error collecting stats for",
             container.name,
-            column.name,
+            column2.name,
             error
           );
         }
       }
     }
-    return () => this.#describe();
-  }
-  #describe() {
-    return null;
   }
 };
 
 // packages/text2sql/src/lib/adapters/groundings/constraint.grounding.ts
 var ConstraintGrounding = class extends AbstractGrounding {
   constructor(config = {}) {
-    super("constraints");
+    super("constraint");
   }
   /**
    * Execute the grounding process.
    * Annotates tables in ctx.tables with their constraints.
    */
   async execute(ctx) {
-    for (const table of ctx.tables) {
+    for (const table2 of ctx.tables) {
       try {
-        table.constraints = await this.getConstraints(table.name);
+        table2.constraints = await this.getConstraints(table2.name);
       } catch (error) {
-        console.warn("Error collecting constraints for", table.name, error);
+        console.warn("Error collecting constraints for", table2.name, error);
       }
     }
-    return () => null;
   }
 };
 
 // packages/text2sql/src/lib/adapters/groundings/indexes.grounding.ts
 var IndexesGrounding = class extends AbstractGrounding {
   constructor(config = {}) {
-    super("indexes");
+    super("index");
   }
   /**
    * Execute the grounding process.
    * Annotates tables in ctx.tables with their indexes and marks indexed columns.
    */
   async execute(ctx) {
-    for (const table of ctx.tables) {
-      table.indexes = await this.getIndexes(table.name);
-      for (const index of table.indexes ?? []) {
-        for (const colName of index.columns) {
-          const column = table.columns.find((c) => c.name === colName);
-          if (column) {
-            column.isIndexed = true;
+    for (const table2 of ctx.tables) {
+      table2.indexes = await this.getIndexes(table2.name);
+      for (const index2 of table2.indexes ?? []) {
+        for (const colName of index2.columns) {
+          const column2 = table2.columns.find((c) => c.name === colName);
+          if (column2) {
+            column2.isIndexed = true;
           }
         }
       }
     }
-    return () => null;
   }
 };
 
 // packages/text2sql/src/lib/adapters/groundings/info.grounding.ts
 var InfoGrounding = class extends AbstractGrounding {
   constructor(config = {}) {
-    super("dialect_info");
+    super("dialectInfo");
   }
   /**
    * Execute the grounding process.
@@ -181,210 +414,2036 @@ var InfoGrounding = class extends AbstractGrounding {
    */
   async execute(ctx) {
     ctx.info = await this.collectInfo();
-    const lines = [`Dialect: ${ctx.info.dialect ?? "unknown"}`];
-    if (ctx.info.version) {
-      lines.push(`Version: ${ctx.info.version}`);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/column-values.grounding.ts
+var ColumnValuesGrounding = class extends AbstractGrounding {
+  lowCardinalityLimit;
+  constructor(config = {}) {
+    super("columnValues");
+    this.lowCardinalityLimit = config.lowCardinalityLimit ?? 20;
+  }
+  /**
+   * Get values for native ENUM type columns.
+   * Return undefined if column is not an ENUM type.
+   * Default implementation returns undefined (no native ENUM support).
+   */
+  async collectEnumValues(_tableName, _column) {
+    return void 0;
+  }
+  /**
+   * Parse CHECK constraint for enum-like IN clause.
+   * Extracts values from patterns like:
+   * - CHECK (status IN ('active', 'inactive'))
+   * - CHECK ((status)::text = ANY (ARRAY['a'::text, 'b'::text]))
+   * - CHECK (status = 'active' OR status = 'inactive')
+   */
+  parseCheckConstraint(constraint2, columnName) {
+    if (constraint2.type !== "CHECK" || !constraint2.definition) {
+      return void 0;
+    }
+    if (constraint2.columns && !constraint2.columns.includes(columnName)) {
+      return void 0;
+    }
+    const def = constraint2.definition;
+    const escapedCol = this.escapeRegex(columnName);
+    const colPattern = `(?:\\(?\\(?${escapedCol}\\)?(?:::(?:text|varchar|character varying))?\\)?)`;
+    const inMatch = def.match(
+      new RegExp(`${colPattern}\\s+IN\\s*\\(([^)]+)\\)`, "i")
+    );
+    if (inMatch) {
+      return this.extractStringValues(inMatch[1]);
+    }
+    const anyMatch = def.match(
+      new RegExp(
+        `${colPattern}\\s*=\\s*ANY\\s*\\(\\s*(?:ARRAY)?\\s*\\[([^\\]]+)\\]`,
+        "i"
+      )
+    );
+    if (anyMatch) {
+      return this.extractStringValues(anyMatch[1]);
+    }
+    const orPattern = new RegExp(
+      `\\b${this.escapeRegex(columnName)}\\b\\s*=\\s*'([^']*)'`,
+      "gi"
+    );
+    const orMatches = [...def.matchAll(orPattern)];
+    if (orMatches.length >= 2) {
+      return orMatches.map((m) => m[1]);
     }
-    if (ctx.info.database) {
-      lines.push(`Database: ${ctx.info.database}`);
+    return void 0;
+  }
+  /**
+   * Extract string values from a comma-separated list.
+   */
+  extractStringValues(input) {
+    const values = [];
+    const matches = input.matchAll(/'([^']*)'/g);
+    for (const match of matches) {
+      values.push(match[1]);
     }
-    if (ctx.info.details && Object.keys(ctx.info.details).length) {
-      lines.push(`Details: ${JSON.stringify(ctx.info.details)}`);
+    return values.length > 0 ? values : void 0;
+  }
+  /**
+   * Escape special regex characters in a string.
+   */
+  escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  /**
+   * Get the table from context by name.
+   */
+  getTable(ctx, name) {
+    return ctx.tables.find((t) => t.name === name);
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with values.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    for (const container of allContainers) {
+      const table2 = this.getTable(ctx, container.name);
+      for (const column2 of container.columns) {
+        try {
+          const result = await this.resolveColumnValues(
+            container.name,
+            column2,
+            table2?.constraints
+          );
+          if (result) {
+            column2.kind = result.kind;
+            column2.values = result.values;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting column values for",
+            container.name,
+            column2.name,
+            error
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Resolve column values from all sources in priority order.
+   */
+  async resolveColumnValues(tableName, column2, constraints2) {
+    const enumValues = await this.collectEnumValues(tableName, column2);
+    if (enumValues?.length) {
+      return { kind: "Enum", values: enumValues };
+    }
+    if (constraints2) {
+      for (const constraint2 of constraints2) {
+        const checkValues = this.parseCheckConstraint(constraint2, column2.name);
+        if (checkValues?.length) {
+          return { kind: "Enum", values: checkValues };
+        }
+      }
+    }
+    const lowCardValues = await this.collectLowCardinality(tableName, column2);
+    if (lowCardValues?.length) {
+      return { kind: "LowCardinality", values: lowCardValues };
+    }
+    return void 0;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/report.grounding.ts
+import { groq as groq2 } from "@ai-sdk/groq";
+import { tool } from "ai";
+import dedent from "dedent";
+import z from "zod";
+import "@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";
+import spawn2 from "nano-spawn";
+import {
+  createBashTool
+} from "bash-tool";
+import YAML from "yaml";
+import { DatabaseSync } from "node:sqlite";
+import { groq } from "@ai-sdk/groq";
+import {
+  NoSuchToolError,
+  Output,
+  convertToModelMessages,
+  createUIMessageStream,
+  generateId as generateId2,
+  generateText,
+  smoothStream,
+  stepCountIs,
+  streamText
+} from "ai";
+import chalk2 from "chalk";
+import "zod";
+import "@deepagents/agent";
+var defaultTokenizer = {
+  encode(text) {
+    return encode(text);
+  },
+  count(text) {
+    return encode(text).length;
+  }
+};
+var ModelsRegistry = class {
+  #cache = /* @__PURE__ */ new Map();
+  #loaded = false;
+  #tokenizers = /* @__PURE__ */ new Map();
+  #defaultTokenizer = defaultTokenizer;
+  /**
+   * Load models data from models.dev API
+   */
+  async load() {
+    if (this.#loaded) return;
+    const response = await fetch("https://models.dev/api.json");
+    if (!response.ok) {
+      throw new Error(`Failed to fetch models: ${response.statusText}`);
+    }
+    const data = await response.json();
+    for (const [providerId, provider] of Object.entries(data)) {
+      for (const [modelId, model] of Object.entries(provider.models)) {
+        const info2 = {
+          id: model.id,
+          name: model.name,
+          family: model.family,
+          cost: model.cost,
+          limit: model.limit,
+          provider: providerId
+        };
+        this.#cache.set(`${providerId}:${modelId}`, info2);
+      }
+    }
+    this.#loaded = true;
+  }
+  /**
+   * Get model info by ID
+   * @param modelId - Model ID (e.g., "openai:gpt-4o")
+   */
+  get(modelId) {
+    return this.#cache.get(modelId);
+  }
+  /**
+   * Check if a model exists in the registry
+   */
+  has(modelId) {
+    return this.#cache.has(modelId);
+  }
+  /**
+   * List all available model IDs
+   */
+  list() {
+    return [...this.#cache.keys()];
+  }
+  /**
+   * Register a custom tokenizer for specific model families
+   * @param family - Model family name (e.g., "llama", "claude")
+   * @param tokenizer - Tokenizer implementation
+   */
+  registerTokenizer(family, tokenizer) {
+    this.#tokenizers.set(family, tokenizer);
+  }
+  /**
+   * Set the default tokenizer used when no family-specific tokenizer is registered
+   */
+  setDefaultTokenizer(tokenizer) {
+    this.#defaultTokenizer = tokenizer;
+  }
+  /**
+   * Get the appropriate tokenizer for a model
+   */
+  getTokenizer(modelId) {
+    const model = this.get(modelId);
+    if (model) {
+      const familyTokenizer = this.#tokenizers.get(model.family);
+      if (familyTokenizer) {
+        return familyTokenizer;
+      }
+    }
+    return this.#defaultTokenizer;
+  }
+  /**
+   * Estimate token count and cost for given text and model
+   * @param modelId - Model ID to use for pricing (e.g., "openai:gpt-4o")
+   * @param input - Input text (prompt)
+   */
+  estimate(modelId, input) {
+    const model = this.get(modelId);
+    if (!model) {
+      throw new Error(
+        `Model "${modelId}" not found. Call load() first or check model ID.`
+      );
+    }
+    const tokenizer = this.getTokenizer(modelId);
+    const tokens = tokenizer.count(input);
+    const cost = tokens / 1e6 * model.cost.input;
+    return {
+      model: model.id,
+      provider: model.provider,
+      tokens,
+      cost,
+      limits: {
+        context: model.limit.context,
+        output: model.limit.output,
+        exceedsContext: tokens > model.limit.context
+      },
+      fragments: []
+    };
+  }
+};
+var _registry = null;
+function getModelsRegistry() {
+  if (!_registry) {
+    _registry = new ModelsRegistry();
+  }
+  return _registry;
+}
+function isFragment(data) {
+  return typeof data === "object" && data !== null && "name" in data && "data" in data && typeof data.name === "string";
+}
+function isFragmentObject(data) {
+  return typeof data === "object" && data !== null && !Array.isArray(data) && !isFragment(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(),
+    role: "user",
+    parts: [{ type: "text", text: content }]
+  } : content;
+  return {
+    id: message2.id,
+    name: "user",
+    data: "content",
+    type: "message",
+    persist: true,
+    codec: {
+      decode() {
+        return message2;
+      },
+      encode() {
+        return message2;
+      }
+    }
+  };
+}
+function assistant(message2) {
+  return {
+    id: message2.id,
+    name: "assistant",
+    data: "content",
+    type: "message",
+    persist: true,
+    codec: {
+      decode() {
+        return message2;
+      },
+      encode() {
+        return message2;
+      }
+    }
+  };
+}
+function message(content) {
+  const message2 = typeof content === "string" ? {
+    id: generateId(),
+    role: "user",
+    parts: [{ type: "text", text: content }]
+  } : content;
+  return {
+    id: message2.id,
+    name: "message",
+    data: "content",
+    type: "message",
+    persist: true,
+    codec: {
+      decode() {
+        return message2;
+      },
+      encode() {
+        return message2;
+      }
+    }
+  };
+}
+function assistantText(content, options) {
+  const id = options?.id ?? crypto.randomUUID();
+  return assistant({
+    id,
+    role: "assistant",
+    parts: [{ type: "text", text: content }]
+  });
+}
+var ContextRenderer = class {
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  /**
+   * Check if data is a primitive (string, number, boolean).
+   */
+  isPrimitive(data) {
+    return typeof data === "string" || typeof data === "number" || typeof data === "boolean";
+  }
+  /**
+   * Group fragments by name for groupFragments option.
+   */
+  groupByName(fragments) {
+    const groups = /* @__PURE__ */ new Map();
+    for (const fragment2 of fragments) {
+      const existing = groups.get(fragment2.name) ?? [];
+      existing.push(fragment2);
+      groups.set(fragment2.name, existing);
+    }
+    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(fragments) {
+    const sanitized = [];
+    for (const fragment2 of fragments) {
+      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.
+   */
+  renderValue(key, value, ctx) {
+    if (value == null) {
+      return "";
+    }
+    if (isFragment(value)) {
+      return this.renderFragment(value, ctx);
+    }
+    if (Array.isArray(value)) {
+      return this.renderArray(key, value, ctx);
+    }
+    if (isFragmentObject(value)) {
+      return this.renderObject(key, value, ctx);
+    }
+    return this.renderPrimitive(key, String(value), ctx);
+  }
+  /**
+   * Render all entries of an object.
+   */
+  renderEntries(data, ctx) {
+    return Object.entries(data).map(([key, value]) => this.renderValue(key, value, ctx)).filter(Boolean);
+  }
+};
+var XmlRenderer = class extends ContextRenderer {
+  render(fragments) {
+    const sanitized = this.sanitizeFragments(fragments);
+    return sanitized.map((f) => this.#renderTopLevel(f)).filter(Boolean).join("\n");
+  }
+  #renderTopLevel(fragment2) {
+    if (this.isPrimitive(fragment2.data)) {
+      return this.#leafRoot(fragment2.name, String(fragment2.data));
+    }
+    if (Array.isArray(fragment2.data)) {
+      return this.#renderArray(fragment2.name, fragment2.data, 0);
+    }
+    if (isFragment(fragment2.data)) {
+      const child = this.renderFragment(fragment2.data, { depth: 1, path: [] });
+      return this.#wrap(fragment2.name, [child]);
+    }
+    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);
+    const nonFragmentItems = items.filter((item) => !isFragment(item));
+    const children = [];
+    for (const item of nonFragmentItems) {
+      if (item != null) {
+        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) {
+      const groups = this.groupByName(fragmentItems);
+      for (const [groupName, groupFragments] of groups) {
+        const groupChildren = groupFragments.map(
+          (frag) => this.renderFragment(frag, { depth: depth + 2, path: [] })
+        );
+        const pluralName = pluralize.plural(groupName);
+        children.push(this.#wrapIndented(pluralName, groupChildren, depth + 1));
+      }
+    } else {
+      for (const frag of fragmentItems) {
+        children.push(
+          this.renderFragment(frag, { depth: depth + 1, path: [] })
+        );
+      }
+    }
+    return this.#wrap(name, children);
+  }
+  #leafRoot(tag, value) {
+    const safe = this.#escape(value);
+    if (safe.includes("\n")) {
+      return `<${tag}>
+${this.#indent(safe, 2)}
+</${tag}>`;
+    }
+    return `<${tag}>${safe}</${tag}>`;
+  }
+  renderFragment(fragment2, ctx) {
+    const { name, data } = fragment2;
+    if (this.isPrimitive(data)) {
+      return this.#leaf(name, String(data), ctx.depth);
+    }
+    if (isFragment(data)) {
+      const child = this.renderFragment(data, { ...ctx, depth: ctx.depth + 1 });
+      return this.#wrapIndented(name, [child], ctx.depth);
+    }
+    if (Array.isArray(data)) {
+      return this.#renderArrayIndented(name, data, 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);
+    const nonFragmentItems = items.filter((item) => !isFragment(item));
+    const children = [];
+    for (const item of nonFragmentItems) {
+      if (item != null) {
+        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) {
+      const groups = this.groupByName(fragmentItems);
+      for (const [groupName, groupFragments] of groups) {
+        const groupChildren = groupFragments.map(
+          (frag) => this.renderFragment(frag, { depth: depth + 2, path: [] })
+        );
+        const pluralName = pluralize.plural(groupName);
+        children.push(this.#wrapIndented(pluralName, groupChildren, depth + 1));
+      }
+    } else {
+      for (const frag of fragmentItems) {
+        children.push(
+          this.renderFragment(frag, { depth: depth + 1, path: [] })
+        );
+      }
+    }
+    return this.#wrapIndented(name, children, depth);
+  }
+  renderPrimitive(key, value, ctx) {
+    return this.#leaf(key, value, ctx.depth);
+  }
+  renderArray(key, items, ctx) {
+    if (!items.length) {
+      return "";
+    }
+    const itemTag = pluralize.singular(key);
+    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) {
+    const children = this.renderEntries(obj, { ...ctx, depth: ctx.depth + 1 });
+    return this.#wrapIndented(key, children, ctx.depth);
+  }
+  #escape(value) {
+    if (value == null) {
+      return "";
+    }
+    return value.replaceAll(/&/g, "&amp;").replaceAll(/</g, "&lt;").replaceAll(/>/g, "&gt;").replaceAll(/"/g, "&quot;").replaceAll(/'/g, "&apos;");
+  }
+  #indent(text, spaces) {
+    if (!text.trim()) {
+      return "";
+    }
+    const padding = " ".repeat(spaces);
+    return text.split("\n").map((line) => line.length ? padding + line : padding).join("\n");
+  }
+  #leaf(tag, value, depth) {
+    const safe = this.#escape(value);
+    const pad = "  ".repeat(depth);
+    if (safe.includes("\n")) {
+      return `${pad}<${tag}>
+${this.#indent(safe, (depth + 1) * 2)}
+${pad}</${tag}>`;
+    }
+    return `${pad}<${tag}>${safe}</${tag}>`;
+  }
+  #wrap(tag, children) {
+    const content = children.filter(Boolean).join("\n");
+    if (!content) {
+      return "";
+    }
+    return `<${tag}>
+${content}
+</${tag}>`;
+  }
+  #wrapIndented(tag, children, depth) {
+    const content = children.filter(Boolean).join("\n");
+    if (!content) {
+      return "";
+    }
+    const pad = "  ".repeat(depth);
+    return `${pad}<${tag}>
+${content}
+${pad}</${tag}>`;
+  }
+};
+var ContextStore = class {
+};
+var ContextEngine = class {
+  /** Non-message fragments (role, hints, etc.) - not persisted in graph */
+  #fragments = [];
+  /** Pending message fragments to be added to graph */
+  #pendingMessages = [];
+  #store;
+  #chatId;
+  #userId;
+  #branchName;
+  #branch = null;
+  #chatData = null;
+  #initialized = false;
+  constructor(options) {
+    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.#userId = options.userId;
+    this.#branchName = "main";
+  }
+  /**
+   * Initialize the chat and branch if they don't exist.
+   */
+  async #ensureInitialized() {
+    if (this.#initialized) {
+      return;
+    }
+    this.#chatData = await this.#store.upsertChat({
+      id: this.#chatId,
+      userId: this.#userId
+    });
+    this.#branch = await this.#store.getActiveBranch(this.#chatId);
+    this.#initialized = true;
+  }
+  /**
+   * Create a new branch from a specific message.
+   * Shared logic between rewind() and btw().
+   */
+  async #createBranchFrom(messageId, switchTo) {
+    const branches = await this.#store.listBranches(this.#chatId);
+    const samePrefix = branches.filter(
+      (b) => b.name === this.#branchName || b.name.startsWith(`${this.#branchName}-v`)
+    );
+    const newBranchName = `${this.#branchName}-v${samePrefix.length + 1}`;
+    const newBranch = {
+      id: crypto.randomUUID(),
+      chatId: this.#chatId,
+      name: newBranchName,
+      headMessageId: messageId,
+      isActive: false,
+      createdAt: Date.now()
+    };
+    await this.#store.createBranch(newBranch);
+    if (switchTo) {
+      await this.#store.setActiveBranch(this.#chatId, newBranch.id);
+      this.#branch = { ...newBranch, isActive: true };
+      this.#branchName = newBranchName;
+      this.#pendingMessages = [];
+    }
+    const chain = await this.#store.getMessageChain(messageId);
+    return {
+      id: newBranch.id,
+      name: newBranch.name,
+      headMessageId: newBranch.headMessageId,
+      isActive: switchTo,
+      messageCount: chain.length,
+      createdAt: newBranch.createdAt
+    };
+  }
+  /**
+   * Get the current chat ID.
+   */
+  get chatId() {
+    return this.#chatId;
+  }
+  /**
+   * Get the current branch name.
+   */
+  get branch() {
+    return this.#branchName;
+  }
+  /**
+   * Get metadata for the current chat.
+   * Returns null if the chat hasn't been initialized yet.
+   */
+  get chat() {
+    if (!this.#chatData) {
+      return null;
+    }
+    return {
+      id: this.#chatData.id,
+      userId: this.#chatData.userId,
+      createdAt: this.#chatData.createdAt,
+      updatedAt: this.#chatData.updatedAt,
+      title: this.#chatData.title,
+      metadata: this.#chatData.metadata
+    };
+  }
+  /**
+   * Add fragments to the context.
+   *
+   * - Message fragments (user/assistant) are queued for persistence
+   * - Non-message fragments (role/hint) are kept in memory for system prompt
+   */
+  set(...fragments) {
+    for (const fragment2 of fragments) {
+      if (isMessageFragment(fragment2)) {
+        this.#pendingMessages.push(fragment2);
+      } else {
+        this.#fragments.push(fragment2);
+      }
+    }
+    return this;
+  }
+  // Unset a fragment by ID (not implemented yet)
+  unset(fragmentId) {
+  }
+  /**
+   * Render all fragments using the provided renderer.
+   * @internal Use resolve() instead for public API.
+   */
+  render(renderer) {
+    return renderer.render(this.#fragments);
+  }
+  /**
+   * Resolve context into AI SDK-ready format.
+   *
+   * - Initializes chat and branch if needed
+   * - Loads message history from the graph (walking parent chain)
+   * - Separates context fragments for system prompt
+   * - Combines with pending messages
+   *
+   * @example
+   * ```ts
+   * const context = new ContextEngine({ store, chatId: 'chat-1', userId: 'user-1' })
+   *   .set(role('You are helpful'), user('Hello'));
+   *
+   * const { systemPrompt, messages } = await context.resolve();
+   * await generateText({ system: systemPrompt, messages });
+   * ```
+   */
+  async resolve(options) {
+    await this.#ensureInitialized();
+    const systemPrompt = options.renderer.render(this.#fragments);
+    const messages = [];
+    if (this.#branch?.headMessageId) {
+      const chain = await this.#store.getMessageChain(
+        this.#branch.headMessageId
+      );
+      for (const msg of chain) {
+        messages.push(message(msg.data).codec?.decode());
+      }
+    }
+    for (const fragment2 of this.#pendingMessages) {
+      const decoded = fragment2.codec.decode();
+      messages.push(decoded);
+    }
+    return { systemPrompt, messages };
+  }
+  /**
+   * Save pending messages to the graph.
+   *
+   * Each message is added as a node with parentId pointing to the previous message.
+   * The branch head is updated to point to the last message.
+   *
+   * @example
+   * ```ts
+   * context.set(user('Hello'));
+   * // AI responds...
+   * context.set(assistant('Hi there!'));
+   * await context.save(); // Persist to graph
+   * ```
+   */
+  async save() {
+    await this.#ensureInitialized();
+    if (this.#pendingMessages.length === 0) {
+      return;
+    }
+    let parentId = this.#branch.headMessageId;
+    const now = Date.now();
+    for (const fragment2 of this.#pendingMessages) {
+      const messageData = {
+        id: fragment2.id ?? crypto.randomUUID(),
+        chatId: this.#chatId,
+        parentId,
+        name: fragment2.name,
+        type: fragment2.type,
+        data: fragment2.codec.encode(),
+        createdAt: now
+      };
+      await this.#store.addMessage(messageData);
+      parentId = messageData.id;
+    }
+    await this.#store.updateBranchHead(this.#branch.id, parentId);
+    this.#branch.headMessageId = parentId;
+    this.#pendingMessages = [];
+  }
+  /**
+   * Estimate token count and cost for the full context.
+   *
+   * Includes:
+   * - System prompt fragments (role, hints, etc.)
+   * - Persisted chat messages (from store)
+   * - Pending messages (not yet saved)
+   *
+   * @param modelId - Model ID (e.g., "openai:gpt-4o", "anthropic:claude-3-5-sonnet")
+   * @param options - Optional settings
+   * @returns Estimate result with token counts, costs, and per-fragment breakdown
+   */
+  async estimate(modelId, options = {}) {
+    await this.#ensureInitialized();
+    const renderer = options.renderer ?? new XmlRenderer();
+    const registry = getModelsRegistry();
+    await registry.load();
+    const model = registry.get(modelId);
+    if (!model) {
+      throw new Error(
+        `Model "${modelId}" not found. Call load() first or check model ID.`
+      );
+    }
+    const tokenizer = registry.getTokenizer(modelId);
+    const fragmentEstimates = [];
+    for (const fragment2 of this.#fragments) {
+      const rendered = renderer.render([fragment2]);
+      const tokens = tokenizer.count(rendered);
+      const cost = tokens / 1e6 * model.cost.input;
+      fragmentEstimates.push({
+        id: fragment2.id,
+        name: fragment2.name,
+        tokens,
+        cost
+      });
+    }
+    if (this.#branch?.headMessageId) {
+      const chain = await this.#store.getMessageChain(
+        this.#branch.headMessageId
+      );
+      for (const msg of chain) {
+        const content = String(msg.data);
+        const tokens = tokenizer.count(content);
+        const cost = tokens / 1e6 * model.cost.input;
+        fragmentEstimates.push({
+          name: msg.name,
+          id: msg.id,
+          tokens,
+          cost
+        });
+      }
+    }
+    for (const fragment2 of this.#pendingMessages) {
+      const content = String(fragment2.data);
+      const tokens = tokenizer.count(content);
+      const cost = tokens / 1e6 * model.cost.input;
+      fragmentEstimates.push({
+        name: fragment2.name,
+        id: fragment2.id,
+        tokens,
+        cost
+      });
+    }
+    const totalTokens = fragmentEstimates.reduce((sum, f) => sum + f.tokens, 0);
+    const totalCost = fragmentEstimates.reduce((sum, f) => sum + f.cost, 0);
+    return {
+      model: model.id,
+      provider: model.provider,
+      tokens: totalTokens,
+      cost: totalCost,
+      limits: {
+        context: model.limit.context,
+        output: model.limit.output,
+        exceedsContext: totalTokens > model.limit.context
+      },
+      fragments: fragmentEstimates
+    };
+  }
+  /**
+   * Rewind to a specific message by ID.
+   *
+   * Creates a new branch from that message, preserving the original branch.
+   * The new branch becomes active.
+   *
+   * @param messageId - The message ID to rewind to
+   * @returns The new branch info
+   *
+   * @example
+   * ```ts
+   * context.set(user('What is 2 + 2?', { id: 'q1' }));
+   * context.set(assistant('The answer is 5.', { id: 'wrong' })); // Oops!
+   * await context.save();
+   *
+   * // Rewind to the question, creates new branch
+   * const newBranch = await context.rewind('q1');
+   *
+   * // Now add correct answer on new branch
+   * context.set(assistant('The answer is 4.'));
+   * await context.save();
+   * ```
+   */
+  async rewind(messageId) {
+    await this.#ensureInitialized();
+    const message2 = await this.#store.getMessage(messageId);
+    if (!message2) {
+      throw new Error(`Message "${messageId}" not found`);
+    }
+    if (message2.chatId !== this.#chatId) {
+      throw new Error(`Message "${messageId}" belongs to a different chat`);
+    }
+    return this.#createBranchFrom(messageId, true);
+  }
+  /**
+   * Create a checkpoint at the current position.
+   *
+   * A checkpoint is a named pointer to the current branch head.
+   * Use restore() to return to this point later.
+   *
+   * @param name - Name for the checkpoint
+   * @returns The checkpoint info
+   *
+   * @example
+   * ```ts
+   * context.set(user('I want to learn a new skill.'));
+   * context.set(assistant('Would you like coding or cooking?'));
+   * await context.save();
+   *
+   * // Save checkpoint before user's choice
+   * const cp = await context.checkpoint('before-choice');
+   * ```
+   */
+  async checkpoint(name) {
+    await this.#ensureInitialized();
+    if (!this.#branch?.headMessageId) {
+      throw new Error("Cannot create checkpoint: no messages in conversation");
+    }
+    const checkpoint = {
+      id: crypto.randomUUID(),
+      chatId: this.#chatId,
+      name,
+      messageId: this.#branch.headMessageId,
+      createdAt: Date.now()
+    };
+    await this.#store.createCheckpoint(checkpoint);
+    return {
+      id: checkpoint.id,
+      name: checkpoint.name,
+      messageId: checkpoint.messageId,
+      createdAt: checkpoint.createdAt
+    };
+  }
+  /**
+   * Restore to a checkpoint by creating a new branch from that point.
+   *
+   * @param name - Name of the checkpoint to restore
+   * @returns The new branch info
+   *
+   * @example
+   * ```ts
+   * // User chose cooking, but wants to try coding path
+   * await context.restore('before-choice');
+   *
+   * context.set(user('I want to learn coding.'));
+   * context.set(assistant('Python is a great starting language!'));
+   * await context.save();
+   * ```
+   */
+  async restore(name) {
+    await this.#ensureInitialized();
+    const checkpoint = await this.#store.getCheckpoint(this.#chatId, name);
+    if (!checkpoint) {
+      throw new Error(
+        `Checkpoint "${name}" not found in chat "${this.#chatId}"`
+      );
+    }
+    return this.rewind(checkpoint.messageId);
+  }
+  /**
+   * Switch to a different branch by name.
+   *
+   * @param name - Branch name to switch to
+   *
+   * @example
+   * ```ts
+   * // List branches (via store)
+   * const branches = await store.listBranches(context.chatId);
+   * console.log(branches); // [{name: 'main', ...}, {name: 'main-v2', ...}]
+   *
+   * // Switch to original branch
+   * await context.switchBranch('main');
+   * ```
+   */
+  async switchBranch(name) {
+    await this.#ensureInitialized();
+    const branch = await this.#store.getBranch(this.#chatId, name);
+    if (!branch) {
+      throw new Error(`Branch "${name}" not found in chat "${this.#chatId}"`);
+    }
+    await this.#store.setActiveBranch(this.#chatId, branch.id);
+    this.#branch = { ...branch, isActive: true };
+    this.#branchName = name;
+    this.#pendingMessages = [];
+  }
+  /**
+   * Create a parallel branch from the current position ("by the way").
+   *
+   * Use this when you want to fork the conversation without leaving
+   * the current branch. Common use case: user wants to ask another
+   * question while waiting for the model to respond.
+   *
+   * Unlike rewind(), this method:
+   * - Uses the current HEAD (no messageId needed)
+   * - Does NOT switch to the new branch
+   * - Keeps pending messages intact
+   *
+   * @returns The new branch info (does not switch to it)
+   * @throws Error if no messages exist in the conversation
+   *
+   * @example
+   * ```ts
+   * // User asked a question, model is generating...
+   * context.set(user('What is the weather?'));
+   * await context.save();
+   *
+   * // User wants to ask something else without waiting
+   * const newBranch = await context.btw();
+   * // newBranch = { name: 'main-v2', ... }
+   *
+   * // Later, switch to the new branch and add the question
+   * await context.switchBranch(newBranch.name);
+   * context.set(user('Also, what time is it?'));
+   * await context.save();
+   * ```
+   */
+  async btw() {
+    await this.#ensureInitialized();
+    if (!this.#branch?.headMessageId) {
+      throw new Error("Cannot create btw branch: no messages in conversation");
+    }
+    return this.#createBranchFrom(this.#branch.headMessageId, false);
+  }
+  /**
+   * Update metadata for the current chat.
+   *
+   * @param updates - Partial metadata to merge (title, metadata)
+   *
+   * @example
+   * ```ts
+   * await context.updateChat({
+   *   title: 'Coding Help Session',
+   *   metadata: { tags: ['python', 'debugging'] }
+   * });
+   * ```
+   */
+  async updateChat(updates) {
+    await this.#ensureInitialized();
+    const storeUpdates = {};
+    if (updates.title !== void 0) {
+      storeUpdates.title = updates.title;
+    }
+    if (updates.metadata !== void 0) {
+      storeUpdates.metadata = {
+        ...this.#chatData?.metadata,
+        ...updates.metadata
+      };
+    }
+    this.#chatData = await this.#store.updateChat(this.#chatId, storeUpdates);
+  }
+  /**
+   * Consolidate context fragments (no-op for now).
+   *
+   * This is a placeholder for future functionality that merges context fragments
+   * using specific rules. Currently, it does nothing.
+   *
+   * @experimental
+   */
+  consolidate() {
+    return void 0;
+  }
+  /**
+   * Inspect the full context state for debugging.
+   * 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
+   *
+   * @example
+   * ```ts
+   * const inspection = await context.inspect({
+   *   modelId: 'openai:gpt-4o',
+   *   renderer: new XmlRenderer(),
+   * });
+   * console.log(JSON.stringify(inspection, null, 2));
+   *
+   * // Or write to file for analysis
+   * await fs.writeFile('context-debug.json', JSON.stringify(inspection, null, 2));
+   * ```
+   */
+  async inspect(options) {
+    await this.#ensureInitialized();
+    const { renderer } = options;
+    const estimateResult = await this.estimate(options.modelId, { renderer });
+    const rendered = renderer.render(this.#fragments);
+    const persistedMessages = [];
+    if (this.#branch?.headMessageId) {
+      const chain = await this.#store.getMessageChain(
+        this.#branch.headMessageId
+      );
+      persistedMessages.push(...chain);
+    }
+    const graph = await this.#store.getGraph(this.#chatId);
+    return {
+      estimate: estimateResult,
+      rendered,
+      fragments: {
+        context: [...this.#fragments],
+        pending: [...this.#pendingMessages],
+        persisted: persistedMessages
+      },
+      graph,
+      meta: {
+        chatId: this.#chatId,
+        branch: this.#branchName,
+        timestamp: Date.now()
+      }
+    };
+  }
+};
+function persona(input) {
+  return {
+    name: "persona",
+    data: {
+      name: input.name,
+      ...input.role && { role: input.role },
+      ...input.objective && { objective: input.objective },
+      ...input.tone && { tone: input.tone }
+    }
+  };
+}
+function pass(part) {
+  return { type: "pass", part };
+}
+function runGuardrailChain(part, guardrails, context) {
+  let currentPart = part;
+  for (const guardrail2 of guardrails) {
+    const result = guardrail2.handle(currentPart, context);
+    if (result.type === "fail") {
+      return result;
     }
-    return () => lines.join("\n");
+    currentPart = result.part;
   }
-};
+  return pass(currentPart);
+}
+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),
+  updatedAt INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
 
-// packages/text2sql/src/lib/adapters/groundings/column-values.grounding.ts
-var ColumnValuesGrounding = class extends AbstractGrounding {
-  lowCardinalityLimit;
-  constructor(config = {}) {
-    super("column_values");
-    this.lowCardinalityLimit = config.lowCardinalityLimit ?? 20;
+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 (
+  id TEXT PRIMARY KEY,
+  chatId TEXT NOT NULL,
+  parentId TEXT,
+  name TEXT NOT NULL,
+  type TEXT,
+  data TEXT NOT NULL,
+  createdAt INTEGER NOT NULL,
+  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,
+  FOREIGN KEY (parentId) REFERENCES messages(id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_chatId ON messages(chatId);
+CREATE INDEX IF NOT EXISTS idx_messages_parentId ON messages(parentId);
+
+-- Branches table (pointers to head messages)
+CREATE TABLE IF NOT EXISTS branches (
+  id TEXT PRIMARY KEY,
+  chatId TEXT NOT NULL,
+  name TEXT NOT NULL,
+  headMessageId TEXT,
+  isActive INTEGER NOT NULL DEFAULT 0,
+  createdAt INTEGER NOT NULL,
+  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,
+  FOREIGN KEY (headMessageId) REFERENCES messages(id),
+  UNIQUE(chatId, name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_branches_chatId ON branches(chatId);
+
+-- Checkpoints table (pointers to message nodes)
+CREATE TABLE IF NOT EXISTS checkpoints (
+  id TEXT PRIMARY KEY,
+  chatId TEXT NOT NULL,
+  name TEXT NOT NULL,
+  messageId TEXT NOT NULL,
+  createdAt INTEGER NOT NULL,
+  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,
+  FOREIGN KEY (messageId) REFERENCES messages(id),
+  UNIQUE(chatId, name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_checkpoints_chatId ON checkpoints(chatId);
+
+-- FTS5 virtual table for full-text search
+-- messageId/chatId/name are UNINDEXED (stored but not searchable, used for filtering/joining)
+-- Only 'content' is indexed for full-text search
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+  messageId UNINDEXED,
+  chatId UNINDEXED,
+  name UNINDEXED,
+  content,
+  tokenize='porter unicode61'
+);
+`;
+var SqliteContextStore = class extends ContextStore {
+  #db;
+  constructor(path3) {
+    super();
+    this.#db = new DatabaseSync(path3);
+    this.#db.exec("PRAGMA foreign_keys = ON");
+    this.#db.exec(STORE_DDL);
   }
   /**
-   * Get values for native ENUM type columns.
-   * Return undefined if column is not an ENUM type.
-   * Default implementation returns undefined (no native ENUM support).
+   * Execute a function within a transaction.
+   * Automatically commits on success or rolls back on error.
    */
-  async collectEnumValues(_tableName, _column) {
-    return void 0;
+  #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.#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());
+    });
   }
-  /**
-   * Parse CHECK constraint for enum-like IN clause.
-   * Extracts values from patterns like:
-   * - CHECK (status IN ('active', 'inactive'))
-   * - CHECK ((status)::text = ANY (ARRAY['a'::text, 'b'::text]))
-   * - CHECK (status = 'active' OR status = 'inactive')
-   */
-  parseCheckConstraint(constraint, columnName) {
-    if (constraint.type !== "CHECK" || !constraint.definition) {
+  async upsertChat(chat) {
+    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);
+    if (!row) {
       return void 0;
     }
-    if (constraint.columns && !constraint.columns.includes(columnName)) {
-      return void 0;
+    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 updateChat(chatId, updates) {
+    const setClauses = ["updatedAt = strftime('%s', 'now') * 1000"];
+    const params = [];
+    if (updates.title !== void 0) {
+      setClauses.push("title = ?");
+      params.push(updates.title ?? null);
+    }
+    if (updates.metadata !== void 0) {
+      setClauses.push("metadata = ?");
+      params.push(JSON.stringify(updates.metadata));
+    }
+    params.push(chatId);
+    const row = this.#db.prepare(
+      `UPDATE chats SET ${setClauses.join(", ")} WHERE id = ? RETURNING *`
+    ).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(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 def = constraint.definition;
-    const escapedCol = this.escapeRegex(columnName);
-    const colPattern = `(?:\\(?\\(?${escapedCol}\\)?(?:::(?:text|varchar|character varying))?\\)?)`;
-    const inMatch = def.match(
-      new RegExp(`${colPattern}\\s+IN\\s*\\(([^)]+)\\)`, "i")
+    const rows = this.#db.prepare(
+      `SELECT
+          c.id,
+          c.userId,
+          c.title,
+          c.createdAt,
+          c.updatedAt,
+          COUNT(DISTINCT m.id) as messageCount,
+          COUNT(DISTINCT b.id) as branchCount
+        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${limitClause}`
+    ).all(...params);
+    return rows.map((row) => ({
+      id: row.id,
+      userId: row.userId,
+      title: row.title ?? void 0,
+      messageCount: row.messageCount,
+      branchCount: row.branchCount,
+      createdAt: row.createdAt,
+      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)
+  // ==========================================================================
+  async addMessage(message2) {
+    this.#db.prepare(
+      `INSERT INTO messages (id, chatId, parentId, name, type, data, createdAt)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           parentId = excluded.parentId,
+           name = excluded.name,
+           type = excluded.type,
+           data = excluded.data`
+    ).run(
+      message2.id,
+      message2.chatId,
+      message2.parentId,
+      message2.name,
+      message2.type ?? null,
+      JSON.stringify(message2.data),
+      message2.createdAt
     );
-    if (inMatch) {
-      return this.extractStringValues(inMatch[1]);
+    const content = typeof message2.data === "string" ? message2.data : JSON.stringify(message2.data);
+    this.#db.prepare(`DELETE FROM messages_fts WHERE messageId = ?`).run(message2.id);
+    this.#db.prepare(
+      `INSERT INTO messages_fts(messageId, chatId, name, content)
+         VALUES (?, ?, ?, ?)`
+    ).run(message2.id, message2.chatId, message2.name, content);
+  }
+  async getMessage(messageId) {
+    const row = this.#db.prepare("SELECT * FROM messages WHERE id = ?").get(messageId);
+    if (!row) {
+      return void 0;
     }
-    const anyMatch = def.match(
-      new RegExp(
-        `${colPattern}\\s*=\\s*ANY\\s*\\(\\s*(?:ARRAY)?\\s*\\[([^\\]]+)\\]`,
-        "i"
-      )
+    return {
+      id: row.id,
+      chatId: row.chatId,
+      parentId: row.parentId,
+      name: row.name,
+      type: row.type ?? void 0,
+      data: JSON.parse(row.data),
+      createdAt: row.createdAt
+    };
+  }
+  async getMessageChain(headId) {
+    const rows = this.#db.prepare(
+      `WITH RECURSIVE chain AS (
+          SELECT *, 0 as depth FROM messages WHERE id = ?
+          UNION ALL
+          SELECT m.*, c.depth + 1 FROM messages m
+          INNER JOIN chain c ON m.id = c.parentId
+        )
+        SELECT * FROM chain
+        ORDER BY depth DESC`
+    ).all(headId);
+    return rows.map((row) => ({
+      id: row.id,
+      chatId: row.chatId,
+      parentId: row.parentId,
+      name: row.name,
+      type: row.type ?? void 0,
+      data: JSON.parse(row.data),
+      createdAt: row.createdAt
+    }));
+  }
+  async hasChildren(messageId) {
+    const row = this.#db.prepare(
+      "SELECT EXISTS(SELECT 1 FROM messages WHERE parentId = ?) as hasChildren"
+    ).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
+  // ==========================================================================
+  async createBranch(branch) {
+    this.#db.prepare(
+      `INSERT INTO branches (id, chatId, name, headMessageId, isActive, createdAt)
+         VALUES (?, ?, ?, ?, ?, ?)`
+    ).run(
+      branch.id,
+      branch.chatId,
+      branch.name,
+      branch.headMessageId,
+      branch.isActive ? 1 : 0,
+      branch.createdAt
     );
-    if (anyMatch) {
-      return this.extractStringValues(anyMatch[1]);
+  }
+  async getBranch(chatId, name) {
+    const row = this.#db.prepare("SELECT * FROM branches WHERE chatId = ? AND name = ?").get(chatId, name);
+    if (!row) {
+      return void 0;
     }
-    const orPattern = new RegExp(
-      `\\b${this.escapeRegex(columnName)}\\b\\s*=\\s*'([^']*)'`,
-      "gi"
-    );
-    const orMatches = [...def.matchAll(orPattern)];
-    if (orMatches.length >= 2) {
-      return orMatches.map((m) => m[1]);
+    return {
+      id: row.id,
+      chatId: row.chatId,
+      name: row.name,
+      headMessageId: row.headMessageId,
+      isActive: row.isActive === 1,
+      createdAt: row.createdAt
+    };
+  }
+  async getActiveBranch(chatId) {
+    const row = this.#db.prepare("SELECT * FROM branches WHERE chatId = ? AND isActive = 1").get(chatId);
+    if (!row) {
+      return void 0;
     }
-    return void 0;
+    return {
+      id: row.id,
+      chatId: row.chatId,
+      name: row.name,
+      headMessageId: row.headMessageId,
+      isActive: true,
+      createdAt: row.createdAt
+    };
   }
-  /**
-   * Extract string values from a comma-separated list.
-   */
-  extractStringValues(input) {
-    const values = [];
-    const matches = input.matchAll(/'([^']*)'/g);
-    for (const match of matches) {
-      values.push(match[1]);
+  async setActiveBranch(chatId, branchId) {
+    this.#db.prepare("UPDATE branches SET isActive = 0 WHERE chatId = ?").run(chatId);
+    this.#db.prepare("UPDATE branches SET isActive = 1 WHERE id = ?").run(branchId);
+  }
+  async updateBranchHead(branchId, messageId) {
+    this.#db.prepare("UPDATE branches SET headMessageId = ? WHERE id = ?").run(messageId, branchId);
+  }
+  async listBranches(chatId) {
+    const branches = this.#db.prepare(
+      `SELECT
+          b.id,
+          b.name,
+          b.headMessageId,
+          b.isActive,
+          b.createdAt
+        FROM branches b
+        WHERE b.chatId = ?
+        ORDER BY b.createdAt ASC`
+    ).all(chatId);
+    const result = [];
+    for (const branch of branches) {
+      let messageCount = 0;
+      if (branch.headMessageId) {
+        const countRow = this.#db.prepare(
+          `WITH RECURSIVE chain AS (
+              SELECT id, parentId FROM messages WHERE id = ?
+              UNION ALL
+              SELECT m.id, m.parentId FROM messages m
+              INNER JOIN chain c ON m.id = c.parentId
+            )
+            SELECT COUNT(*) as count FROM chain`
+        ).get(branch.headMessageId);
+        messageCount = countRow.count;
+      }
+      result.push({
+        id: branch.id,
+        name: branch.name,
+        headMessageId: branch.headMessageId,
+        isActive: branch.isActive === 1,
+        messageCount,
+        createdAt: branch.createdAt
+      });
     }
-    return values.length > 0 ? values : void 0;
+    return result;
+  }
+  // ==========================================================================
+  // Checkpoint Operations
+  // ==========================================================================
+  async createCheckpoint(checkpoint) {
+    this.#db.prepare(
+      `INSERT INTO checkpoints (id, chatId, name, messageId, createdAt)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(chatId, name) DO UPDATE SET
+           messageId = excluded.messageId,
+           createdAt = excluded.createdAt`
+    ).run(
+      checkpoint.id,
+      checkpoint.chatId,
+      checkpoint.name,
+      checkpoint.messageId,
+      checkpoint.createdAt
+    );
   }
-  /**
-   * Escape special regex characters in a string.
-   */
-  escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  async getCheckpoint(chatId, name) {
+    const row = this.#db.prepare("SELECT * FROM checkpoints WHERE chatId = ? AND name = ?").get(chatId, name);
+    if (!row) {
+      return void 0;
+    }
+    return {
+      id: row.id,
+      chatId: row.chatId,
+      name: row.name,
+      messageId: row.messageId,
+      createdAt: row.createdAt
+    };
+  }
+  async listCheckpoints(chatId) {
+    const rows = this.#db.prepare(
+      `SELECT id, name, messageId, createdAt
+         FROM checkpoints
+         WHERE chatId = ?
+         ORDER BY createdAt DESC`
+    ).all(chatId);
+    return rows.map((row) => ({
+      id: row.id,
+      name: row.name,
+      messageId: row.messageId,
+      createdAt: row.createdAt
+    }));
+  }
+  async deleteCheckpoint(chatId, name) {
+    this.#db.prepare("DELETE FROM checkpoints WHERE chatId = ? AND name = ?").run(chatId, name);
+  }
+  // ==========================================================================
+  // Search Operations
+  // ==========================================================================
+  async searchMessages(chatId, query, options) {
+    const limit = options?.limit ?? 20;
+    const roles = options?.roles;
+    let sql = `
+      SELECT
+        m.id,
+        m.chatId,
+        m.parentId,
+        m.name,
+        m.type,
+        m.data,
+        m.createdAt,
+        fts.rank,
+        snippet(messages_fts, 3, '<mark>', '</mark>', '...', 32) as snippet
+      FROM messages_fts fts
+      JOIN messages m ON m.id = fts.messageId
+      WHERE messages_fts MATCH ?
+        AND fts.chatId = ?
+    `;
+    const params = [query, chatId];
+    if (roles && roles.length > 0) {
+      const placeholders = roles.map(() => "?").join(", ");
+      sql += ` AND fts.name IN (${placeholders})`;
+      params.push(...roles);
+    }
+    sql += " ORDER BY fts.rank LIMIT ?";
+    params.push(limit);
+    const rows = this.#db.prepare(sql).all(...params);
+    return rows.map((row) => ({
+      message: {
+        id: row.id,
+        chatId: row.chatId,
+        parentId: row.parentId,
+        name: row.name,
+        type: row.type ?? void 0,
+        data: JSON.parse(row.data),
+        createdAt: row.createdAt
+      },
+      rank: row.rank,
+      snippet: row.snippet
+    }));
+  }
+  // ==========================================================================
+  // Visualization Operations
+  // ==========================================================================
+  async getGraph(chatId) {
+    const messageRows = this.#db.prepare(
+      `SELECT id, parentId, name, data, createdAt
+         FROM messages
+         WHERE chatId = ?
+         ORDER BY createdAt ASC`
+    ).all(chatId);
+    const nodes = messageRows.map((row) => {
+      const data = JSON.parse(row.data);
+      const content = typeof data === "string" ? data : JSON.stringify(data);
+      return {
+        id: row.id,
+        parentId: row.parentId,
+        role: row.name,
+        content: content.length > 50 ? content.slice(0, 50) + "..." : content,
+        createdAt: row.createdAt
+      };
+    });
+    const branchRows = this.#db.prepare(
+      `SELECT name, headMessageId, isActive
+         FROM branches
+         WHERE chatId = ?
+         ORDER BY createdAt ASC`
+    ).all(chatId);
+    const branches = branchRows.map((row) => ({
+      name: row.name,
+      headMessageId: row.headMessageId,
+      isActive: row.isActive === 1
+    }));
+    const checkpointRows = this.#db.prepare(
+      `SELECT name, messageId
+         FROM checkpoints
+         WHERE chatId = ?
+         ORDER BY createdAt ASC`
+    ).all(chatId);
+    const checkpoints = checkpointRows.map((row) => ({
+      name: row.name,
+      messageId: row.messageId
+    }));
+    return {
+      chatId,
+      nodes,
+      branches,
+      checkpoints
+    };
+  }
+};
+var InMemoryContextStore = class extends SqliteContextStore {
+  constructor() {
+    super(":memory:");
+  }
+};
+var Agent = class _Agent {
+  #options;
+  #guardrails = [];
+  tools;
+  constructor(options) {
+    this.#options = options;
+    this.tools = options.tools || {};
+    this.#guardrails = options.guardrails || [];
+  }
+  async generate(contextVariables, config) {
+    if (!this.#options.context) {
+      throw new Error(`Agent ${this.#options.name} is missing a context.`);
+    }
+    if (!this.#options.model) {
+      throw new Error(`Agent ${this.#options.name} is missing a model.`);
+    }
+    const { messages, systemPrompt } = await this.#options.context.resolve({
+      renderer: new XmlRenderer()
+    });
+    return generateText({
+      abortSignal: config?.abortSignal,
+      providerOptions: this.#options.providerOptions,
+      model: this.#options.model,
+      system: systemPrompt,
+      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: ${chalk2.yellow("ToolCalled")}: ${toolCall.toolName}(${JSON.stringify(toolCall.input)})`
+          );
+        }
+      }
+    });
   }
   /**
-   * Get the table from context by name.
+   * Stream a response from the agent.
+   *
+   * When guardrails are configured, `toUIMessageStream()` is wrapped to provide
+   * self-correction behavior. Direct access to fullStream/textStream bypasses guardrails.
+   *
+   * @example
+   * ```typescript
+   * const stream = await agent.stream({});
+   *
+   * // With guardrails - use toUIMessageStream for protection
+   * await printer.readableStream(stream.toUIMessageStream());
+   *
+   * // Or use printer.stdout which uses toUIMessageStream internally
+   * await printer.stdout(stream);
+   * ```
    */
-  getTable(ctx, name) {
-    return ctx.tables.find((t) => t.name === name);
+  async stream(contextVariables, config) {
+    if (!this.#options.context) {
+      throw new Error(`Agent ${this.#options.name} is missing a context.`);
+    }
+    if (!this.#options.model) {
+      throw new Error(`Agent ${this.#options.name} is missing a model.`);
+    }
+    const result = await this.#createRawStream(contextVariables, config);
+    if (this.#guardrails.length === 0) {
+      return result;
+    }
+    return this.#wrapWithGuardrails(result, contextVariables, config);
   }
   /**
-   * Execute the grounding process.
-   * Annotates columns in ctx.tables and ctx.views with values.
+   * Create a raw stream without guardrail processing.
    */
-  async execute(ctx) {
-    const allContainers = [...ctx.tables, ...ctx.views];
-    for (const container of allContainers) {
-      const table = this.getTable(ctx, container.name);
-      for (const column of container.columns) {
-        try {
-          const result = await this.resolveColumnValues(
-            container.name,
-            column,
-            table?.constraints
-          );
-          if (result) {
-            column.kind = result.kind;
-            column.values = result.values;
-          }
-        } catch (error) {
-          console.warn(
-            "Error collecting column values for",
-            container.name,
-            column.name,
-            error
+  async #createRawStream(contextVariables, config) {
+    const { messages, systemPrompt } = await this.#options.context.resolve({
+      renderer: new XmlRenderer()
+    });
+    const runId = generateId2();
+    return streamText({
+      abortSignal: config?.abortSignal,
+      providerOptions: this.#options.providerOptions,
+      model: this.#options.model,
+      system: systemPrompt,
+      messages: await convertToModelMessages(messages),
+      experimental_repairToolCall: repairToolCall,
+      stopWhen: stepCountIs(50),
+      experimental_transform: config?.transform ?? smoothStream(),
+      tools: this.#options.tools,
+      experimental_context: contextVariables,
+      toolChoice: this.#options.toolChoice,
+      onStepFinish: (step) => {
+        const toolCall = step.toolCalls.at(-1);
+        if (toolCall) {
+          console.log(
+            `Debug: (${runId}) ${chalk2.bold.yellow("ToolCalled")}: ${toolCall.toolName}(${JSON.stringify(toolCall.input)})`
           );
         }
       }
-    }
-    return () => this.#describe();
+    });
   }
   /**
-   * Resolve column values from all sources in priority order.
+   * Wrap a StreamTextResult with guardrail protection on toUIMessageStream().
+   *
+   * When a guardrail fails:
+   * 1. Accumulated text + feedback is appended as the assistant's self-correction
+   * 2. The feedback is written to the output stream (user sees the correction)
+   * 3. A new stream is started and the model continues from the correction
    */
-  async resolveColumnValues(tableName, column, constraints2) {
-    const enumValues = await this.collectEnumValues(tableName, column);
-    if (enumValues?.length) {
-      return { kind: "Enum", values: enumValues };
-    }
-    if (constraints2) {
-      for (const constraint of constraints2) {
-        const checkValues = this.parseCheckConstraint(constraint, column.name);
-        if (checkValues?.length) {
-          return { kind: "Enum", values: checkValues };
+  #wrapWithGuardrails(result, contextVariables, config) {
+    const maxRetries = config?.maxRetries ?? this.#options.maxGuardrailRetries ?? 3;
+    const context = this.#options.context;
+    const originalToUIMessageStream = result.toUIMessageStream.bind(result);
+    result.toUIMessageStream = (options) => {
+      return createUIMessageStream({
+        generateId: generateId2,
+        execute: async ({ writer }) => {
+          let currentResult = result;
+          let attempt = 0;
+          const guardrailContext = {
+            availableTools: Object.keys(this.tools)
+          };
+          while (attempt < maxRetries) {
+            if (config?.abortSignal?.aborted) {
+              writer.write({ type: "finish" });
+              return;
+            }
+            attempt++;
+            let accumulatedText = "";
+            let guardrailFailed = false;
+            let failureFeedback = "";
+            const uiStream = currentResult === result ? originalToUIMessageStream(options) : currentResult.toUIMessageStream(options);
+            for await (const part of uiStream) {
+              const checkResult = runGuardrailChain(
+                part,
+                this.#guardrails,
+                guardrailContext
+              );
+              if (checkResult.type === "fail") {
+                guardrailFailed = true;
+                failureFeedback = checkResult.feedback;
+                console.log(
+                  chalk2.yellow(
+                    `[${this.#options.name}] Guardrail triggered (attempt ${attempt}/${maxRetries}): ${failureFeedback.slice(0, 50)}...`
+                  )
+                );
+                break;
+              }
+              if (checkResult.part.type === "text-delta") {
+                accumulatedText += checkResult.part.delta;
+              }
+              writer.write(checkResult.part);
+            }
+            if (!guardrailFailed) {
+              writer.write({ type: "finish" });
+              return;
+            }
+            if (attempt >= maxRetries) {
+              console.error(
+                chalk2.red(
+                  `[${this.#options.name}] Guardrail retry limit (${maxRetries}) exceeded.`
+                )
+              );
+              writer.write({ type: "finish" });
+              return;
+            }
+            writer.write({
+              type: "text-delta",
+              id: generateId2(),
+              delta: ` ${failureFeedback}`
+            });
+            const selfCorrectionText = accumulatedText + " " + failureFeedback;
+            context.set(assistantText(selfCorrectionText));
+            await context.save();
+            currentResult = await this.#createRawStream(
+              contextVariables,
+              config
+            );
+          }
+        },
+        onError: (error) => {
+          const message2 = error instanceof Error ? error.message : String(error);
+          return `Stream failed: ${message2}`;
         }
-      }
-    }
-    const lowCardValues = await this.collectLowCardinality(tableName, column);
-    if (lowCardValues?.length) {
-      return { kind: "LowCardinality", values: lowCardValues };
-    }
-    return void 0;
+      });
+    };
+    return result;
+  }
+  clone(overrides) {
+    return new _Agent({
+      ...this.#options,
+      ...overrides
+    });
   }
-  #describe() {
+};
+function agent(options) {
+  return new Agent(options);
+}
+var repairToolCall = async ({
+  toolCall,
+  tools,
+  inputSchema,
+  error
+}) => {
+  console.log(
+    `Debug: ${chalk2.yellow("RepairingToolCall")}: ${toolCall.toolName}`,
+    error.name
+  );
+  if (NoSuchToolError.isInstance(error)) {
     return null;
   }
+  const tool2 = tools[toolCall.toolName];
+  const { output } = await generateText({
+    model: groq("openai/gpt-oss-20b"),
+    output: Output.object({ schema: tool2.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/adapters/groundings/report.grounding.ts
-import { groq } from "@ai-sdk/groq";
-import { tool } from "ai";
-import dedent from "dedent";
-import z from "zod";
-import {
-  agent,
-  generate,
-  toState,
-  user
-} from "@deepagents/agent";
-var reportAgent = agent({
-  name: "db-report-agent",
-  model: groq("openai/gpt-oss-20b"),
-  prompt: () => dedent`
-        <identity>
-          You are a database analyst expert. Your job is to understand what
-          a database represents and provide business context about it.
-          You have READ-ONLY access to the database.
-        </identity>
-
-        <instructions>
-          Write a business context that helps another agent answer questions accurately.
-
-          For EACH table, do queries ONE AT A TIME:
-          1. SELECT COUNT(*) to get row count
-          2. SELECT * LIMIT 3 to see sample data
-
-          Then write a report with:
-          - What business this database is for
-          - For each table: purpose, row count, and example of what the data looks like
-
-          Include concrete examples like "Track prices are $0.99",
-          "Customer names like 'Luís Gonçalves'", etc.
-
-          Keep it 400-600 words, conversational style.
-        </instructions>
-      `,
-  tools: {
-    query_database: tool({
-      description: "Execute a SELECT query to explore the database and gather insights.",
-      inputSchema: z.object({
-        sql: z.string().describe("The SELECT query to execute"),
-        purpose: z.string().describe("What insight you are trying to gather with this query")
-      }),
-      execute: ({ sql }, options) => {
-        const state = toState(options);
-        return state.adapter.execute(sql);
-      }
-    })
-  }
-});
 var ReportGrounding = class extends AbstractGrounding {
   #adapter;
   #model;
@@ -393,7 +2452,7 @@ var ReportGrounding = class extends AbstractGrounding {
   constructor(adapter, config = {}) {
     super("business_context");
     this.#adapter = adapter;
-    this.#model = config.model ?? groq("openai/gpt-oss-20b");
+    this.#model = config.model ?? groq2("openai/gpt-oss-20b");
     this.#cache = config.cache;
     this.#forceRefresh = config.forceRefresh ?? false;
   }
@@ -402,7 +2461,7 @@ var ReportGrounding = class extends AbstractGrounding {
       const cached = await this.#cache.get();
       if (cached) {
         ctx.report = cached;
-        return () => cached;
+        return;
       }
     }
     const report2 = await this.#generateReport();
@@ -410,40 +2469,84 @@ var ReportGrounding = class extends AbstractGrounding {
     if (this.#cache) {
       await this.#cache.set(report2);
     }
-    return () => report2;
   }
   async #generateReport() {
-    const { text } = await generate(
-      reportAgent.clone({ model: this.#model }),
-      [
-        user(
-          "Please analyze the database and write a contextual report about what this database represents."
-        )
-      ],
-      { adapter: this.#adapter }
+    const context = new ContextEngine({
+      store: new InMemoryContextStore(),
+      chatId: `report-gen-${crypto.randomUUID()}`,
+      userId: "system"
+    });
+    context.set(
+      persona({
+        name: "db-report-agent",
+        role: "Database analyst",
+        objective: "Analyze the database and write a contextual report about what it represents"
+      }),
+      fragment(
+        "instructions",
+        dedent`
+          Write a business context that helps another agent answer questions accurately.
+
+          For EACH table, do queries ONE AT A TIME:
+          1. SELECT COUNT(*) to get row count
+          2. SELECT * LIMIT 3 to see sample data
+
+          Then write a report with:
+          - What business this database is for
+          - For each table: purpose, row count, and example of what the data looks like
+
+          Include concrete examples like "Track prices are $0.99",
+          "Customer names like 'Luís Gonçalves'", etc.
+
+          Keep it 400-600 words, conversational style.
+        `
+      ),
+      user(
+        "Please analyze the database and write a contextual report about what this database represents."
+      )
     );
-    return text;
+    const adapter = this.#adapter;
+    const reportAgent = agent({
+      name: "db-report-agent",
+      model: this.#model,
+      context,
+      tools: {
+        query_database: tool({
+          description: "Execute a SELECT query to explore the database and gather insights.",
+          inputSchema: z.object({
+            sql: z.string().describe("The SELECT query to execute"),
+            purpose: z.string().describe(
+              "What insight you are trying to gather with this query"
+            )
+          }),
+          execute: ({ sql }) => {
+            return adapter.execute(sql);
+          }
+        })
+      }
+    });
+    const result = await reportAgent.generate({});
+    return result.text;
   }
 };
 
 // packages/text2sql/src/lib/adapters/groundings/row-count.grounding.ts
 var RowCountGrounding = class extends AbstractGrounding {
   constructor(config = {}) {
-    super("row_counts");
+    super("rowCount");
   }
   /**
    * Execute the grounding process.
    * Annotates tables in ctx.tables with row counts and size hints.
    */
   async execute(ctx) {
-    for (const table of ctx.tables) {
-      const count = await this.getRowCount(table.name);
+    for (const table2 of ctx.tables) {
+      const count = await this.getRowCount(table2.name);
       if (count != null) {
-        table.rowCount = count;
-        table.sizeHint = this.#classifyRowCount(count);
+        table2.rowCount = count;
+        table2.sizeHint = this.#classifyRowCount(count);
       }
     }
-    return () => null;
   }
   /**
    * Classify row count into a size hint category.
@@ -458,13 +2561,12 @@ var RowCountGrounding = class extends AbstractGrounding {
 };
 
 // packages/text2sql/src/lib/adapters/groundings/table.grounding.ts
-import pluralize from "pluralize";
 var TableGrounding = class extends AbstractGrounding {
   #filter;
   #forward;
   #backward;
   constructor(config = {}) {
-    super("tables");
+    super("table");
     this.#filter = config.filter;
     this.#forward = config.forward;
     this.#backward = config.backward;
@@ -482,7 +2584,7 @@ var TableGrounding = class extends AbstractGrounding {
         seedTables.map((name) => this.getTable(name))
       );
       ctx.tables.push(...tables3);
-      return () => this.#describeTables(tables3);
+      return;
     }
     const tables2 = {};
     const allRelationships = [];
@@ -538,7 +2640,6 @@ var TableGrounding = class extends AbstractGrounding {
     const tablesList = Object.values(tables2);
     ctx.tables.push(...tablesList);
     ctx.relationships.push(...allRelationships);
-    return () => this.#describeTables(tablesList);
   }
   /**
    * Apply the filter to get seed table names.
@@ -568,156 +2669,6 @@ var TableGrounding = class extends AbstractGrounding {
       all.push(rel);
     }
   }
-  #describeTables(tables2) {
-    if (!tables2.length) {
-      return "Schema unavailable.";
-    }
-    return tables2.map((table) => {
-      const rowCountInfo = table.rowCount != null ? ` [rows: ${table.rowCount}${table.sizeHint ? `, size: ${table.sizeHint}` : ""}]` : "";
-      const pkConstraint = table.constraints?.find(
-        (c) => c.type === "PRIMARY_KEY"
-      );
-      const pkColumns = new Set(pkConstraint?.columns ?? []);
-      const notNullColumns = new Set(
-        table.constraints?.filter((c) => c.type === "NOT_NULL").flatMap((c) => c.columns ?? []) ?? []
-      );
-      const defaultByColumn = /* @__PURE__ */ new Map();
-      for (const c of table.constraints?.filter(
-        (c2) => c2.type === "DEFAULT"
-      ) ?? []) {
-        for (const col of c.columns ?? []) {
-          if (c.defaultValue != null) {
-            defaultByColumn.set(col, c.defaultValue);
-          }
-        }
-      }
-      const uniqueColumns = new Set(
-        table.constraints?.filter((c) => c.type === "UNIQUE" && c.columns?.length === 1).flatMap((c) => c.columns ?? []) ?? []
-      );
-      const fkByColumn = /* @__PURE__ */ new Map();
-      for (const c of table.constraints?.filter(
-        (c2) => c2.type === "FOREIGN_KEY"
-      ) ?? []) {
-        const cols = c.columns ?? [];
-        const refCols = c.referencedColumns ?? [];
-        for (let i = 0; i < cols.length; i++) {
-          const refCol = refCols[i] ?? refCols[0] ?? cols[i];
-          fkByColumn.set(cols[i], `${c.referencedTable}.${refCol}`);
-        }
-      }
-      const columns = table.columns.map((column) => {
-        const annotations = [];
-        const isPrimaryKey = pkColumns.has(column.name);
-        if (isPrimaryKey) {
-          annotations.push("PK");
-        }
-        if (fkByColumn.has(column.name)) {
-          annotations.push(`FK -> ${fkByColumn.get(column.name)}`);
-        }
-        if (uniqueColumns.has(column.name)) {
-          annotations.push("UNIQUE");
-        }
-        if (notNullColumns.has(column.name)) {
-          annotations.push("NOT NULL");
-        }
-        if (defaultByColumn.has(column.name)) {
-          annotations.push(`DEFAULT: ${defaultByColumn.get(column.name)}`);
-        }
-        if (column.isIndexed && !isPrimaryKey) {
-          annotations.push("Indexed");
-        }
-        if (column.kind === "Enum" && column.values?.length) {
-          annotations.push(`Enum: ${column.values.join(", ")}`);
-        } else if (column.kind === "LowCardinality" && column.values?.length) {
-          annotations.push(`LowCardinality: ${column.values.join(", ")}`);
-        }
-        if (column.stats) {
-          const statParts = [];
-          if (column.stats.min != null || column.stats.max != null) {
-            const minText = column.stats.min ?? "n/a";
-            const maxText = column.stats.max ?? "n/a";
-            statParts.push(`range ${minText} \u2192 ${maxText}`);
-          }
-          if (column.stats.nullFraction != null && Number.isFinite(column.stats.nullFraction)) {
-            const percent = Math.round(column.stats.nullFraction * 1e3) / 10;
-            statParts.push(`null\u2248${percent}%`);
-          }
-          if (statParts.length) {
-            annotations.push(statParts.join(", "));
-          }
-        }
-        const annotationText = annotations.length ? ` [${annotations.join(", ")}]` : "";
-        return `    - ${column.name} (${column.type})${annotationText}`;
-      }).join("\n");
-      const indexes2 = table.indexes?.length ? `
-  Indexes:
-${table.indexes.map((index) => {
-        const props = [];
-        if (index.unique) {
-          props.push("UNIQUE");
-        }
-        if (index.type) {
-          props.push(index.type);
-        }
-        const propsText = props.length ? ` (${props.join(", ")})` : "";
-        const columnsText = index.columns?.length ? index.columns.join(", ") : "expression";
-        return `    - ${index.name}${propsText}: ${columnsText}`;
-      }).join("\n")}` : "";
-      const multiColumnUniques = table.constraints?.filter(
-        (c) => c.type === "UNIQUE" && (c.columns?.length ?? 0) > 1
-      ) ?? [];
-      const uniqueConstraints = multiColumnUniques.length ? `
-  Unique Constraints:
-${multiColumnUniques.map((c) => `    - ${c.name}: (${c.columns?.join(", ")})`).join("\n")}` : "";
-      const checkConstraints = table.constraints?.filter((c) => c.type === "CHECK") ?? [];
-      const checks = checkConstraints.length ? `
-  Check Constraints:
-${checkConstraints.map((c) => `    - ${c.name}: ${c.definition}`).join("\n")}` : "";
-      return `- Table: ${table.name}${rowCountInfo}
-  Columns:
-${columns}${indexes2}${uniqueConstraints}${checks}`;
-    }).join("\n\n");
-  }
-  #formatTableLabel = (tableName) => {
-    const base = tableName.split(".").pop() ?? tableName;
-    return base.replace(/_/g, " ");
-  };
-  #describeRelationships = (tables2, relationships) => {
-    if (!relationships.length) {
-      return "None detected";
-    }
-    const tableMap = new Map(tables2.map((table) => [table.name, table]));
-    return relationships.map((relationship) => {
-      const sourceLabel = this.#formatTableLabel(relationship.table);
-      const targetLabel = this.#formatTableLabel(
-        relationship.referenced_table
-      );
-      const singularSource = pluralize.singular(sourceLabel);
-      const pluralSource = pluralize.plural(sourceLabel);
-      const singularTarget = pluralize.singular(targetLabel);
-      const pluralTarget = pluralize.plural(targetLabel);
-      const sourceTable = tableMap.get(relationship.table);
-      const targetTable = tableMap.get(relationship.referenced_table);
-      const sourceCount = sourceTable?.rowCount;
-      const targetCount = targetTable?.rowCount;
-      const ratio = sourceCount != null && targetCount != null && targetCount > 0 ? sourceCount / targetCount : null;
-      let cardinality = "each";
-      if (ratio != null) {
-        if (ratio > 5) {
-          cardinality = `many-to-one (\u2248${sourceCount} vs ${targetCount})`;
-        } else if (ratio < 1.2 && ratio > 0.8) {
-          cardinality = `roughly 1:1 (${sourceCount} vs ${targetCount})`;
-        } else if (ratio < 0.2) {
-          cardinality = `one-to-many (${sourceCount} vs ${targetCount})`;
-        }
-      }
-      const mappings = relationship.from.map((fromCol, idx) => {
-        const targetCol = relationship.to[idx] ?? relationship.to[0] ?? fromCol;
-        return `${relationship.table}.${fromCol} -> ${relationship.referenced_table}.${targetCol}`;
-      }).join(", ");
-      return `- ${relationship.table} (${relationship.from.join(", ")}) -> ${relationship.referenced_table} (${relationship.to.join(", ")}) [${cardinality}]`;
-    }).join("\n");
-  };
 };
 
 // packages/text2sql/src/lib/adapters/postgres/column-stats.postgres.grounding.ts
@@ -727,13 +2678,13 @@ var PostgresColumnStatsGrounding = class extends ColumnStatsGrounding {
     super(config);
     this.#adapter = adapter;
   }
-  async collectStats(tableName, column) {
-    if (!this.#shouldCollectStats(column.type)) {
+  async collectStats(tableName, column2) {
+    if (!this.#shouldCollectStats(column2.type)) {
       return void 0;
     }
-    const { schema, table } = this.#adapter.parseTableName(tableName);
-    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table)}`;
-    const columnIdentifier = this.#adapter.quoteIdentifier(column.name);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table2)}`;
+    const columnIdentifier = this.#adapter.quoteIdentifier(column2.name);
     const sql = `
       SELECT
         MIN(${columnIdentifier})::text AS min_value,
@@ -776,7 +2727,7 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
     this.#adapter = adapter;
   }
   async getConstraints(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const constraints2 = [];
     const constraintRows = await this.#adapter.runQuery(`
       SELECT
@@ -797,7 +2748,7 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
       LEFT JOIN LATERAL unnest(con.confkey) WITH ORDINALITY AS ref_key(attnum, ord) ON key.ord = ref_key.ord
       LEFT JOIN pg_attribute ref_a ON ref_a.attrelid = ref_rel.oid AND ref_a.attnum = ref_key.attnum
       WHERE nsp.nspname = '${this.#adapter.escapeString(schema)}'
-        AND rel.relname = '${this.#adapter.escapeString(table)}'
+        AND rel.relname = '${this.#adapter.escapeString(table2)}'
         AND con.contype IN ('p', 'f', 'c', 'u')
       ORDER BY con.conname, key.ord
     `);
@@ -860,21 +2811,21 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
         is_nullable
       FROM information_schema.columns
       WHERE table_schema = '${this.#adapter.escapeString(schema)}'
-        AND table_name = '${this.#adapter.escapeString(table)}'
+        AND table_name = '${this.#adapter.escapeString(table2)}'
     `);
     for (const col of columnRows) {
       const pkConstraint = constraints2.find((c) => c.type === "PRIMARY_KEY");
       const isPkColumn = pkConstraint?.columns?.includes(col.column_name);
       if (col.is_nullable === "NO" && !isPkColumn) {
         constraints2.push({
-          name: `${table}_${col.column_name}_notnull`,
+          name: `${table2}_${col.column_name}_notnull`,
           type: "NOT_NULL",
           columns: [col.column_name]
         });
       }
       if (col.column_default != null) {
         constraints2.push({
-          name: `${table}_${col.column_name}_default`,
+          name: `${table2}_${col.column_name}_default`,
           type: "DEFAULT",
           columns: [col.column_name],
           defaultValue: col.column_default
@@ -895,7 +2846,7 @@ var PostgresIndexesGrounding = class extends IndexesGrounding {
     this.#schemas = config.schemas;
   }
   async getIndexes(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const rows = await this.#adapter.runQuery(`
       SELECT
         i.relname AS index_name,
@@ -910,7 +2861,7 @@ var PostgresIndexesGrounding = class extends IndexesGrounding {
       JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
       JOIN pg_am am ON am.oid = i.relam
       WHERE n.nspname = '${this.#adapter.escapeString(schema)}'
-        AND t.relname = '${this.#adapter.escapeString(table)}'
+        AND t.relname = '${this.#adapter.escapeString(table2)}'
       ORDER BY i.relname, array_position(ix.indkey, a.attnum)
     `);
     return this.#groupIndexes(rows);
@@ -999,18 +2950,18 @@ var PostgresColumnValuesGrounding = class extends ColumnValuesGrounding {
     }
     this.#enumCacheLoaded = true;
   }
-  async collectEnumValues(tableName, column) {
-    if (column.type.toLowerCase() !== "user-defined") {
+  async collectEnumValues(tableName, column2) {
+    if (column2.type.toLowerCase() !== "user-defined") {
       return void 0;
     }
     await this.#loadEnumCache();
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const rows = await this.#adapter.runQuery(`
       SELECT udt_name, udt_schema
       FROM information_schema.columns
       WHERE table_schema = '${this.#adapter.escapeString(schema)}'
-        AND table_name = '${this.#adapter.escapeString(table)}'
-        AND column_name = '${this.#adapter.escapeString(column.name)}'
+        AND table_name = '${this.#adapter.escapeString(table2)}'
+        AND column_name = '${this.#adapter.escapeString(column2.name)}'
     `);
     if (!rows.length) {
       return void 0;
@@ -1020,10 +2971,10 @@ var PostgresColumnValuesGrounding = class extends ColumnValuesGrounding {
     const values = this.#enumCache.get(fullKey) ?? this.#enumCache.get(udt_name);
     return values?.length ? values : void 0;
   }
-  async collectLowCardinality(tableName, column) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
-    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table)}`;
-    const columnIdentifier = this.#adapter.quoteIdentifier(column.name);
+  async collectLowCardinality(tableName, column2) {
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table2)}`;
+    const columnIdentifier = this.#adapter.quoteIdentifier(column2.name);
     const limit = this.lowCardinalityLimit + 1;
     const sql = `
       SELECT DISTINCT ${columnIdentifier}::text AS value
@@ -1132,8 +3083,8 @@ var Postgres = class extends Adapter {
     return value.replace(/"/g, '""');
   }
   buildSampleRowsQuery(tableName, columns, limit) {
-    const { schema, table } = this.parseTableName(tableName);
-    const tableIdentifier = schema ? `${this.quoteIdentifier(schema)}.${this.quoteIdentifier(table)}` : this.quoteIdentifier(table);
+    const { schema, table: table2 } = this.parseTableName(tableName);
+    const tableIdentifier = schema ? `${this.quoteIdentifier(schema)}.${this.quoteIdentifier(table2)}` : this.quoteIdentifier(table2);
     const columnList = columns?.length ? columns.map((c) => this.quoteIdentifier(c)).join(", ") : "*";
     return `SELECT ${columnList} FROM ${tableIdentifier} LIMIT ${limit}`;
   }
@@ -1160,17 +3111,17 @@ var Postgres = class extends Adapter {
       const schema = row.table_schema ?? "public";
       const tableName = row.table_name;
       const qualifiedName = `${schema}.${tableName}`;
-      const table = tables2.get(qualifiedName) ?? {
+      const table2 = tables2.get(qualifiedName) ?? {
         name: qualifiedName,
         schema,
         rawName: tableName,
         columns: []
       };
-      table.columns.push({
+      table2.columns.push({
         name: row.column_name ?? "unknown",
         type: row.data_type ?? "unknown"
       });
-      tables2.set(qualifiedName, table);
+      tables2.set(qualifiedName, table2);
     }
     return Array.from(tables2.values());
   }
@@ -1205,26 +3156,26 @@ var Postgres = class extends Adapter {
       const schema = row.table_schema ?? "public";
       const referencedSchema = row.foreign_table_schema ?? "public";
       const key = `${schema}.${row.table_name}:${row.constraint_name}`;
-      const relationship = relationships.get(key) ?? {
+      const relationship2 = relationships.get(key) ?? {
         table: `${schema}.${row.table_name}`,
         from: [],
         referenced_table: `${referencedSchema}.${row.foreign_table_name}`,
         to: []
       };
-      relationship.from.push(row.column_name ?? "unknown");
-      relationship.to.push(row.foreign_column_name ?? "unknown");
-      relationships.set(key, relationship);
+      relationship2.from.push(row.column_name ?? "unknown");
+      relationship2.to.push(row.foreign_column_name ?? "unknown");
+      relationships.set(key, relationship2);
     }
     return Array.from(relationships.values());
   }
   async #annotateRowCounts(tables2, onProgress) {
     const total = tables2.length;
     for (let i = 0; i < tables2.length; i++) {
-      const table = tables2[i];
-      const tableIdentifier = this.#formatQualifiedTableName(table);
+      const table2 = tables2[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table2);
       onProgress?.({
         phase: "row_counts",
-        message: `Counting rows in ${table.name}...`,
+        message: `Counting rows in ${table2.name}...`,
         current: i + 1,
         total
       });
@@ -1232,8 +3183,8 @@ var Postgres = class extends Adapter {
         const rows = await this.#runIntrospectionQuery(`SELECT COUNT(*) as count FROM ${tableIdentifier}`);
         const rowCount2 = this.#toNumber(rows[0]?.count);
         if (rowCount2 != null) {
-          table.rowCount = rowCount2;
-          table.sizeHint = this.#classifyRowCount(rowCount2);
+          table2.rowCount = rowCount2;
+          table2.sizeHint = this.#classifyRowCount(rowCount2);
         }
       } catch {
         continue;
@@ -1250,7 +3201,7 @@ var Postgres = class extends Adapter {
     if (!tables2.length) {
       return;
     }
-    const tableMap = new Map(tables2.map((table) => [table.name, table]));
+    const tableMap = new Map(tables2.map((table2) => [table2.name, table2]));
     const rows = await this.#runIntrospectionQuery(`
       SELECT
         n.nspname AS table_schema,
@@ -1279,32 +3230,32 @@ var Postgres = class extends Adapter {
       }
       const schema = row.table_schema ?? "public";
       const tableKey = `${schema}.${row.table_name}`;
-      const table = tableMap.get(tableKey);
-      if (!table) {
+      const table2 = tableMap.get(tableKey);
+      if (!table2) {
         continue;
       }
       const indexKey = `${tableKey}:${row.index_name}`;
-      let index = indexMap.get(indexKey);
-      if (!index) {
-        index = {
+      let index2 = indexMap.get(indexKey);
+      if (!index2) {
+        index2 = {
           name: row.index_name,
           columns: [],
           unique: Boolean(row.indisunique ?? false),
           type: row.indisclustered ? "clustered" : row.method ?? void 0
         };
-        indexMap.set(indexKey, index);
-        if (!table.indexes) {
-          table.indexes = [];
+        indexMap.set(indexKey, index2);
+        if (!table2.indexes) {
+          table2.indexes = [];
         }
-        table.indexes.push(index);
+        table2.indexes.push(index2);
       }
       if (row.column_name) {
-        index.columns.push(row.column_name);
-        const column = table.columns.find(
+        index2.columns.push(row.column_name);
+        const column2 = table2.columns.find(
           (col) => col.name === row.column_name
         );
-        if (column) {
-          column.isIndexed = true;
+        if (column2) {
+          column2.isIndexed = true;
         }
       }
     }
@@ -1315,19 +3266,19 @@ var Postgres = class extends Adapter {
     }
     const total = tables2.length;
     for (let i = 0; i < tables2.length; i++) {
-      const table = tables2[i];
-      const tableIdentifier = this.#formatQualifiedTableName(table);
+      const table2 = tables2[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table2);
       onProgress?.({
         phase: "column_stats",
-        message: `Collecting stats for ${table.name}...`,
+        message: `Collecting stats for ${table2.name}...`,
         current: i + 1,
         total
       });
-      for (const column of table.columns) {
-        if (!this.#shouldCollectStats(column.type)) {
+      for (const column2 of table2.columns) {
+        if (!this.#shouldCollectStats(column2.type)) {
           continue;
         }
-        const columnIdentifier = this.#quoteIdentifier(column.name);
+        const columnIdentifier = this.#quoteIdentifier(column2.name);
         const sql = `
           SELECT
             MIN(${columnIdentifier})::text AS min_value,
@@ -1344,7 +3295,7 @@ var Postgres = class extends Adapter {
           const max = rows[0]?.max_value ?? void 0;
           const nullFraction = this.#toNumber(rows[0]?.null_fraction);
           if (min != null || max != null || nullFraction != null) {
-            column.stats = {
+            column2.stats = {
               min,
               max,
               nullFraction: nullFraction != null && Number.isFinite(nullFraction) ? Math.max(0, Math.min(1, nullFraction)) : void 0
@@ -1359,16 +3310,16 @@ var Postgres = class extends Adapter {
   async #annotateLowCardinalityColumns(tables2, onProgress) {
     const total = tables2.length;
     for (let i = 0; i < tables2.length; i++) {
-      const table = tables2[i];
-      const tableIdentifier = this.#formatQualifiedTableName(table);
+      const table2 = tables2[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table2);
       onProgress?.({
         phase: "low_cardinality",
-        message: `Analyzing cardinality in ${table.name}...`,
+        message: `Analyzing cardinality in ${table2.name}...`,
         current: i + 1,
         total
       });
-      for (const column of table.columns) {
-        const columnIdentifier = this.#quoteIdentifier(column.name);
+      for (const column2 of table2.columns) {
+        const columnIdentifier = this.#quoteIdentifier(column2.name);
         const limit = LOW_CARDINALITY_LIMIT + 1;
         const sql = `
           SELECT DISTINCT ${columnIdentifier} AS value
@@ -1398,8 +3349,8 @@ var Postgres = class extends Adapter {
         if (shouldSkip || !values.length) {
           continue;
         }
-        column.kind = "LowCardinality";
-        column.values = values;
+        column2.kind = "LowCardinality";
+        column2.values = values;
       }
     }
   }
@@ -1454,19 +3405,19 @@ var Postgres = class extends Adapter {
   #quoteIdentifier(name) {
     return `"${name.replace(/"/g, '""')}"`;
   }
-  #formatQualifiedTableName(table) {
-    if (table.schema && table.rawName) {
-      return `${this.#quoteIdentifier(table.schema)}.${this.#quoteIdentifier(table.rawName)}`;
+  #formatQualifiedTableName(table2) {
+    if (table2.schema && table2.rawName) {
+      return `${this.#quoteIdentifier(table2.schema)}.${this.#quoteIdentifier(table2.rawName)}`;
     }
-    if (table.name.includes(".")) {
-      const [schemaPart, ...rest] = table.name.split(".");
+    if (table2.name.includes(".")) {
+      const [schemaPart, ...rest] = table2.name.split(".");
       const tablePart = rest.join(".") || schemaPart;
       if (rest.length === 0) {
         return this.#quoteIdentifier(schemaPart);
       }
       return `${this.#quoteIdentifier(schemaPart)}.${this.#quoteIdentifier(tablePart)}`;
     }
-    return this.#quoteIdentifier(table.name);
+    return this.#quoteIdentifier(table2.name);
   }
   #toNumber(value) {
     if (typeof value === "number" && Number.isFinite(value)) {
@@ -1536,8 +3487,8 @@ var PostgresRowCountGrounding = class extends RowCountGrounding {
     this.#adapter = adapter;
   }
   async getRowCount(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
-    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table)}`;
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table2)}`;
     const rows = await this.#adapter.runQuery(
       `SELECT COUNT(*) as count FROM ${tableIdentifier}`
     );
@@ -1565,18 +3516,18 @@ var PostgresTableGrounding = class extends TableGrounding {
     return rows.map((r) => r.name);
   }
   async getTable(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const columns = await this.#adapter.runQuery(`
       SELECT column_name, data_type
       FROM information_schema.columns
       WHERE table_schema = '${this.#adapter.escapeString(schema)}'
-        AND table_name = '${this.#adapter.escapeString(table)}'
+        AND table_name = '${this.#adapter.escapeString(table2)}'
       ORDER BY ordinal_position
     `);
     return {
       name: tableName,
       schema,
-      rawName: table,
+      rawName: table2,
       columns: columns.map((col) => ({
         name: col.column_name ?? "unknown",
         type: col.data_type ?? "unknown"
@@ -1584,7 +3535,7 @@ var PostgresTableGrounding = class extends TableGrounding {
     };
   }
   async findOutgoingRelations(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const rows = await this.#adapter.runQuery(`
       SELECT
         tc.constraint_name,
@@ -1603,13 +3554,13 @@ var PostgresTableGrounding = class extends TableGrounding {
         AND ccu.table_schema = tc.table_schema
       WHERE tc.constraint_type = 'FOREIGN KEY'
         AND tc.table_schema = '${this.#adapter.escapeString(schema)}'
-        AND tc.table_name = '${this.#adapter.escapeString(table)}'
+        AND tc.table_name = '${this.#adapter.escapeString(table2)}'
       ORDER BY tc.constraint_name, kcu.ordinal_position
     `);
     return this.#groupRelationships(rows);
   }
   async findIncomingRelations(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const rows = await this.#adapter.runQuery(`
       SELECT
         tc.constraint_name,
@@ -1628,7 +3579,7 @@ var PostgresTableGrounding = class extends TableGrounding {
         AND ccu.table_schema = tc.table_schema
       WHERE tc.constraint_type = 'FOREIGN KEY'
         AND ccu.table_schema = '${this.#adapter.escapeString(schema)}'
-        AND ccu.table_name = '${this.#adapter.escapeString(table)}'
+        AND ccu.table_name = '${this.#adapter.escapeString(table2)}'
       ORDER BY tc.constraint_name, kcu.ordinal_position
     `);
     return this.#groupRelationships(rows);
@@ -1643,15 +3594,15 @@ var PostgresTableGrounding = class extends TableGrounding {
       const schema = row.table_schema ?? defaultSchema;
       const referencedSchema = row.foreign_table_schema ?? defaultSchema;
       const key = `${schema}.${row.table_name}:${row.constraint_name}`;
-      const relationship = relationships.get(key) ?? {
+      const relationship2 = relationships.get(key) ?? {
         table: `${schema}.${row.table_name}`,
         from: [],
         referenced_table: `${referencedSchema}.${row.foreign_table_name}`,
         to: []
       };
-      relationship.from.push(row.column_name ?? "unknown");
-      relationship.to.push(row.foreign_column_name ?? "unknown");
-      relationships.set(key, relationship);
+      relationship2.from.push(row.column_name ?? "unknown");
+      relationship2.to.push(row.foreign_column_name ?? "unknown");
+      relationships.set(key, relationship2);
     }
     return Array.from(relationships.values());
   }
@@ -1661,7 +3612,7 @@ var PostgresTableGrounding = class extends TableGrounding {
 var ViewGrounding = class extends AbstractGrounding {
   #filter;
   constructor(config = {}) {
-    super("views");
+    super("view");
     this.#filter = config.filter;
   }
   /**
@@ -1674,42 +3625,6 @@ var ViewGrounding = class extends AbstractGrounding {
       viewNames.map((name) => this.getView(name))
     );
     ctx.views.push(...views2);
-    return () => this.#describe(views2);
-  }
-  #describe(views2) {
-    if (!views2.length) {
-      return "No views available.";
-    }
-    return views2.map((view) => {
-      const columns = view.columns.map((column) => {
-        const annotations = [];
-        if (column.kind === "LowCardinality" && column.values?.length) {
-          annotations.push(`LowCardinality: ${column.values.join(", ")}`);
-        }
-        if (column.stats) {
-          const statParts = [];
-          if (column.stats.min != null || column.stats.max != null) {
-            const minText = column.stats.min ?? "n/a";
-            const maxText = column.stats.max ?? "n/a";
-            statParts.push(`range ${minText} \u2192 ${maxText}`);
-          }
-          if (column.stats.nullFraction != null && Number.isFinite(column.stats.nullFraction)) {
-            const percent = Math.round(column.stats.nullFraction * 1e3) / 10;
-            statParts.push(`null\u2248${percent}%`);
-          }
-          if (statParts.length) {
-            annotations.push(statParts.join(", "));
-          }
-        }
-        const annotationText = annotations.length ? ` [${annotations.join(", ")}]` : "";
-        return `    - ${column.name} (${column.type})${annotationText}`;
-      }).join("\n");
-      const definition = view.definition ? `
-  Definition: ${view.definition.length > 200 ? view.definition.slice(0, 200) + "..." : view.definition}` : "";
-      return `- View: ${view.name}${definition}
-  Columns:
-${columns}`;
-    }).join("\n\n");
   }
   /**
    * Apply the filter to get view names.
@@ -1751,24 +3666,24 @@ var PostgresViewGrounding = class extends ViewGrounding {
     return rows.map((r) => r.name);
   }
   async getView(viewName) {
-    const { schema, table: view } = this.#adapter.parseTableName(viewName);
+    const { schema, table: view2 } = this.#adapter.parseTableName(viewName);
     const defRows = await this.#adapter.runQuery(`
       SELECT definition
       FROM pg_views
       WHERE schemaname = '${this.#adapter.escapeString(schema)}'
-        AND viewname = '${this.#adapter.escapeString(view)}'
+        AND viewname = '${this.#adapter.escapeString(view2)}'
     `);
     const columns = await this.#adapter.runQuery(`
       SELECT column_name, data_type
       FROM information_schema.columns
       WHERE table_schema = '${this.#adapter.escapeString(schema)}'
-        AND table_name = '${this.#adapter.escapeString(view)}'
+        AND table_name = '${this.#adapter.escapeString(view2)}'
       ORDER BY ordinal_position
     `);
     return {
       name: viewName,
       schema,
-      rawName: view,
+      rawName: view2,
       definition: defRows[0]?.definition ?? void 0,
       columns: columns.map((col) => ({
         name: col.column_name ?? "unknown",