@deepagents/text2sql 0.20.0 → 0.23.0

package/dist/index.js

@@ -98,7 +98,8 @@ function createGroundingContext() {
     tables: [],
     views: [],
     relationships: [],
-    info: void 0
+    info: void 0,
+    cache: /* @__PURE__ */ new Map()
   };
 }
 
@@ -516,8 +517,8 @@ var sqlValidationMarker = Symbol("SQLValidationError");
 var unanswerableSqlMarker = Symbol("UnanswerableSQLError");
 var SQLValidationError = class _SQLValidationError extends Error {
   [sqlValidationMarker];
-  constructor(message2) {
-    super(message2);
+  constructor(message) {
+    super(message);
     this.name = "SQLValidationError";
     this[sqlValidationMarker] = true;
   }
@@ -527,8 +528,8 @@ var SQLValidationError = class _SQLValidationError extends Error {
 };
 var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
   [unanswerableSqlMarker];
-  constructor(message2) {
-    super(message2);
+  constructor(message) {
+    super(message);
     this.name = "UnanswerableSQLError";
     this[unanswerableSqlMarker] = true;
   }
@@ -685,6 +686,14 @@ var BLOCKED_DB_CLIENT_COMMANDS = /* @__PURE__ */ new Set([
 ]);
 var BLOCKED_RAW_SQL_COMMANDS = /* @__PURE__ */ new Set(["select", "with"]);
 var ALLOWED_SQL_PROXY_SUBCOMMANDS = /* @__PURE__ */ new Set(["run", "validate"]);
+var SHELL_INTERPRETER_COMMANDS = /* @__PURE__ */ new Set([
+  "bash",
+  "sh",
+  "zsh",
+  "dash",
+  "ksh"
+]);
+var WRAPPER_COMMANDS = /* @__PURE__ */ new Set(["env", "command", "eval"]);
 var SQL_PROXY_ENFORCEMENT_MESSAGE = [
   "Direct database querying through bash is blocked.",
   "Use SQL proxy commands in this order:",
@@ -740,82 +749,94 @@ function isScriptNode(value) {
   const node = value;
   return node.type === "Script" && Array.isArray(node.statements);
 }
-function scriptContainsBlockedCommand(script, context) {
-  return statementsContainBlockedCommand(script.statements, context);
+function scriptContainsBlockedCommand(script, context, mode = "blocked-only") {
+  return statementsContainBlockedCommand(script.statements, context, mode);
 }
-function statementsContainBlockedCommand(statements, context) {
+function statementsContainBlockedCommand(statements, context, mode) {
   for (const statement of statements) {
-    if (statementContainsBlockedCommand(statement, context)) {
+    if (statementContainsBlockedCommand(statement, context, mode)) {
       return true;
     }
   }
   return false;
 }
-function statementContainsBlockedCommand(statement, context) {
+function statementContainsBlockedCommand(statement, context, mode) {
   for (const pipeline of statement.pipelines) {
-    if (pipelineContainsBlockedCommand(pipeline, context)) {
+    if (pipelineContainsBlockedCommand(pipeline, context, mode)) {
       return true;
     }
   }
   return false;
 }
-function pipelineContainsBlockedCommand(pipeline, context) {
-  for (const command of pipeline.commands) {
+function pipelineContainsBlockedCommand(pipeline, context, mode) {
+  for (const [index2, command] of pipeline.commands.entries()) {
     if (command.type === "FunctionDef") {
       context.functionDefinitions.set(command.name, command);
       continue;
     }
-    if (commandContainsBlockedCommand(command, context)) {
+    if (commandContainsBlockedCommand(command, context, mode, {
+      stdinFromPipe: index2 > 0
+    })) {
       return true;
     }
   }
   return false;
 }
-function stringCommandContainsBlockedCommand(command, context) {
+function stringCommandContainsBlockedCommand(command, context, mode = "blocked-only") {
   let script;
   try {
     script = parse(command);
   } catch {
     return false;
   }
-  return scriptContainsBlockedCommand(script, cloneInspectionContext(context));
+  return scriptContainsBlockedCommand(
+    script,
+    cloneInspectionContext(context),
+    mode
+  );
 }
-function wordContainsBlockedCommand(word, context) {
+function wordContainsBlockedCommand(word, context, mode) {
   if (!word) {
     return false;
   }
   return wordPartContainsBlockedCommand(
     word.parts,
-    context
+    context,
+    mode
   );
 }
-function wordPartContainsBlockedCommand(parts, context) {
+function wordPartContainsBlockedCommand(parts, context, mode) {
   for (const part of parts) {
-    if (partContainsBlockedCommand(part, context)) {
+    if (partContainsBlockedCommand(part, context, mode)) {
       return true;
     }
   }
   return false;
 }
-function partContainsBlockedCommand(node, context) {
+function partContainsBlockedCommand(node, context, mode) {
   const type = node.type;
   if (type === "CommandSubstitution" || type === "ProcessSubstitution") {
     if (isScriptNode(node.body)) {
       return scriptContainsBlockedCommand(
         node.body,
-        cloneInspectionContext(context)
+        cloneInspectionContext(context),
+        mode
       );
     }
     return false;
   }
   if (type === "ArithCommandSubst" && typeof node.command === "string") {
-    return stringCommandContainsBlockedCommand(node.command, context);
+    return stringCommandContainsBlockedCommand(node.command, context, mode);
   }
   for (const value of Object.values(node)) {
     if (Array.isArray(value)) {
       for (const item of value) {
         if (typeof item === "object" && item !== null) {
-          if (partContainsBlockedCommand(item, context)) {
+          if (partContainsBlockedCommand(
+            item,
+            context,
+            mode
+          )) {
             return true;
           }
         }
@@ -823,14 +844,18 @@ function partContainsBlockedCommand(node, context) {
       continue;
     }
     if (typeof value === "object" && value !== null) {
-      if (partContainsBlockedCommand(value, context)) {
+      if (partContainsBlockedCommand(
+        value,
+        context,
+        mode
+      )) {
         return true;
       }
     }
   }
   return false;
 }
-function functionInvocationContainsBlockedCommand(functionName, context) {
+function functionInvocationContainsBlockedCommand(functionName, context, mode) {
   const definition = context.functionDefinitions.get(functionName);
   if (!definition) {
     return false;
@@ -840,52 +865,306 @@ function functionInvocationContainsBlockedCommand(functionName, context) {
   }
   const invocationContext = cloneInspectionContext(context);
   invocationContext.callStack.add(functionName);
-  return commandContainsBlockedCommand(definition.body, invocationContext);
+  return commandContainsBlockedCommand(
+    definition.body,
+    invocationContext,
+    mode,
+    { stdinFromPipe: false }
+  );
+}
+function isAsciiLetter(character) {
+  const charCode = character.charCodeAt(0);
+  return charCode >= 65 && charCode <= 90 || charCode >= 97 && charCode <= 122;
+}
+function isAsciiDigit(character) {
+  const charCode = character.charCodeAt(0);
+  return charCode >= 48 && charCode <= 57;
+}
+function isValidEnvVariableName(name) {
+  if (!name) {
+    return false;
+  }
+  const firstChar = name[0];
+  if (!(isAsciiLetter(firstChar) || firstChar === "_")) {
+    return false;
+  }
+  for (let index2 = 1; index2 < name.length; index2 += 1) {
+    const char = name[index2];
+    if (!(isAsciiLetter(char) || isAsciiDigit(char) || char === "_")) {
+      return false;
+    }
+  }
+  return true;
+}
+function isEnvAssignmentToken(token) {
+  const separatorIndex = token.indexOf("=");
+  if (separatorIndex <= 0) {
+    return false;
+  }
+  return isValidEnvVariableName(token.slice(0, separatorIndex));
+}
+function parseShortOptionCluster(option) {
+  if (!option.startsWith("-") || option.startsWith("--") || option.length <= 1) {
+    return {
+      valid: false,
+      hasCommandFlag: false,
+      hasStdinFlag: false,
+      consumesNextArg: false
+    };
+  }
+  let hasCommandFlag = false;
+  let hasStdinFlag = false;
+  let consumesNextArg = false;
+  for (let index2 = 1; index2 < option.length; index2 += 1) {
+    const char = option[index2];
+    if (!isAsciiLetter(char)) {
+      return {
+        valid: false,
+        hasCommandFlag: false,
+        hasStdinFlag: false,
+        consumesNextArg: false
+      };
+    }
+    if (char === "c") {
+      hasCommandFlag = true;
+    } else if (char === "s") {
+      hasStdinFlag = true;
+    } else if (char === "O" || char === "o") {
+      consumesNextArg = true;
+    }
+  }
+  return { valid: true, hasCommandFlag, hasStdinFlag, consumesNextArg };
+}
+function getShellInvocationDescriptor(args) {
+  let readsFromStdin = false;
+  const longOptionsWithValue = /* @__PURE__ */ new Set(["--rcfile", "--init-file"]);
+  for (let index2 = 0; index2 < args.length; index2 += 1) {
+    const token = asStaticWordText(args[index2]);
+    if (token == null) {
+      return { kind: "unknown", payload: null };
+    }
+    if (token === "--") {
+      if (index2 + 1 >= args.length) {
+        break;
+      }
+      return {
+        kind: "script",
+        payload: asStaticWordText(args[index2 + 1])
+      };
+    }
+    if (token === "--command") {
+      return {
+        kind: "command",
+        payload: asStaticWordText(args[index2 + 1])
+      };
+    }
+    if (token.startsWith("--command=")) {
+      return {
+        kind: "command",
+        payload: token.slice("--command=".length)
+      };
+    }
+    if (token.startsWith("--")) {
+      if (token.includes("=")) {
+        continue;
+      }
+      if (longOptionsWithValue.has(token)) {
+        if (index2 + 1 >= args.length) {
+          return { kind: "unknown", payload: null };
+        }
+        index2 += 1;
+      }
+      continue;
+    }
+    if (token.startsWith("-") && !token.startsWith("--")) {
+      const parsed = parseShortOptionCluster(token);
+      if (!parsed.valid) {
+        return { kind: "unknown", payload: null };
+      }
+      if (parsed.hasCommandFlag) {
+        return {
+          kind: "command",
+          payload: asStaticWordText(args[index2 + 1])
+        };
+      }
+      if (parsed.hasStdinFlag) {
+        readsFromStdin = true;
+      }
+      if (parsed.consumesNextArg) {
+        if (index2 + 1 >= args.length) {
+          return { kind: "unknown", payload: null };
+        }
+        index2 += 1;
+      }
+      continue;
+    }
+    return {
+      kind: "script",
+      payload: token
+    };
+  }
+  if (readsFromStdin) {
+    return { kind: "stdin", payload: null };
+  }
+  return { kind: "none", payload: null };
+}
+function getHereDocPayload(redirections) {
+  const payloads = [];
+  for (const redirection of redirections) {
+    if (redirection.target.type !== "HereDoc") {
+      continue;
+    }
+    if (!redirection.target.content) {
+      payloads.push("");
+      continue;
+    }
+    const payload = asStaticWordText(redirection.target.content);
+    if (payload == null) {
+      return { hasHereDoc: true, payload: null };
+    }
+    payloads.push(payload);
+  }
+  if (payloads.length === 0) {
+    return { hasHereDoc: false, payload: null };
+  }
+  return { hasHereDoc: true, payload: payloads.join("\n") };
+}
+function joinStaticWords(words) {
+  const tokens = [];
+  for (const word of words) {
+    const token = asStaticWordText(word);
+    if (token == null) {
+      return null;
+    }
+    tokens.push(token);
+  }
+  return tokens.join(" ");
+}
+function resolveEnvWrapperCommand(args) {
+  let index2 = 0;
+  while (index2 < args.length) {
+    const token = asStaticWordText(args[index2]);
+    if (token == null) {
+      return { kind: "unknown" };
+    }
+    if (token === "--") {
+      index2 += 1;
+      break;
+    }
+    if (token === "-u" || token === "--unset" || token === "--chdir") {
+      if (index2 + 1 >= args.length) {
+        return { kind: "unknown" };
+      }
+      index2 += 2;
+      continue;
+    }
+    if (token.startsWith("--unset=") || token.startsWith("--chdir=")) {
+      index2 += 1;
+      continue;
+    }
+    if (token.startsWith("-") && token !== "-" && !isEnvAssignmentToken(token)) {
+      index2 += 1;
+      continue;
+    }
+    if (isEnvAssignmentToken(token)) {
+      index2 += 1;
+      continue;
+    }
+    break;
+  }
+  if (index2 >= args.length) {
+    return { kind: "none" };
+  }
+  return {
+    kind: "resolved",
+    name: args[index2],
+    args: args.slice(index2 + 1)
+  };
 }
-function commandContainsBlockedCommand(command, context) {
+function resolveCommandWrapperCommand(args) {
+  let index2 = 0;
+  let lookupOnly = false;
+  while (index2 < args.length) {
+    const token = asStaticWordText(args[index2]);
+    if (token == null) {
+      return { kind: "unknown" };
+    }
+    if (token === "--") {
+      index2 += 1;
+      break;
+    }
+    if (token === "-v" || token === "-V") {
+      lookupOnly = true;
+      index2 += 1;
+      continue;
+    }
+    if (token.startsWith("-") && token !== "-") {
+      index2 += 1;
+      continue;
+    }
+    break;
+  }
+  if (lookupOnly || index2 >= args.length) {
+    return { kind: "none" };
+  }
+  return {
+    kind: "resolved",
+    name: args[index2],
+    args: args.slice(index2 + 1)
+  };
+}
+function commandContainsBlockedCommand(command, context, mode, options = { stdinFromPipe: false }) {
   switch (command.type) {
     case "SimpleCommand":
-      return isBlockedSimpleCommand(command, context);
+      return isBlockedSimpleCommand(command, context, mode, options);
     case "If":
       return command.clauses.some(
         (clause) => statementsContainBlockedCommand(
           clause.condition,
-          cloneInspectionContext(context)
+          cloneInspectionContext(context),
+          mode
         ) || statementsContainBlockedCommand(
           clause.body,
-          cloneInspectionContext(context)
+          cloneInspectionContext(context),
+          mode
         )
       ) || (command.elseBody ? statementsContainBlockedCommand(
         command.elseBody,
-        cloneInspectionContext(context)
+        cloneInspectionContext(context),
+        mode
       ) : false);
     case "For":
     case "CStyleFor":
       return statementsContainBlockedCommand(
         command.body,
-        cloneInspectionContext(context)
+        cloneInspectionContext(context),
+        mode
       );
     case "While":
     case "Until":
       return statementsContainBlockedCommand(
         command.condition,
-        cloneInspectionContext(context)
+        cloneInspectionContext(context),
+        mode
       ) || statementsContainBlockedCommand(
         command.body,
-        cloneInspectionContext(context)
+        cloneInspectionContext(context),
+        mode
       );
     case "Case":
       return command.items.some(
         (item) => statementsContainBlockedCommand(
           item.body,
-          cloneInspectionContext(context)
+          cloneInspectionContext(context),
+          mode
         )
       );
     case "Subshell":
     case "Group":
       return statementsContainBlockedCommand(
         command.body,
-        cloneInspectionContext(context)
+        cloneInspectionContext(context),
+        mode
       );
     case "FunctionDef":
       return false;
@@ -898,16 +1177,16 @@ function commandContainsBlockedCommand(command, context) {
     }
   }
 }
-function isBlockedSimpleCommand(command, context) {
-  if (wordContainsBlockedCommand(command.name, context)) {
+function isBlockedSimpleCommand(command, context, mode, options) {
+  if (wordContainsBlockedCommand(command.name, context, mode)) {
     return true;
   }
-  if (command.args.some((arg) => wordContainsBlockedCommand(arg, context))) {
+  if (command.args.some((arg) => wordContainsBlockedCommand(arg, context, mode))) {
     return true;
   }
   if (command.assignments.some(
-    (assignment) => wordContainsBlockedCommand(assignment.value, context) || (assignment.array?.some(
-      (value) => wordContainsBlockedCommand(value, context)
+    (assignment) => wordContainsBlockedCommand(assignment.value, context, mode) || (assignment.array?.some(
+      (value) => wordContainsBlockedCommand(value, context, mode)
     ) ?? false)
   )) {
     return true;
@@ -916,11 +1195,16 @@ function isBlockedSimpleCommand(command, context) {
     if (redirection.target.type === "Word") {
       return wordContainsBlockedCommand(
         redirection.target,
-        context
+        context,
+        mode
       );
     }
     if (redirection.target.type === "HereDoc" && redirection.target.content) {
-      return wordContainsBlockedCommand(redirection.target.content, context);
+      return wordContainsBlockedCommand(
+        redirection.target.content,
+        context,
+        mode
+      );
     }
     return false;
   })) {
@@ -939,9 +1223,92 @@ function isBlockedSimpleCommand(command, context) {
   }
   if (normalizedName === "sql") {
     const subcommand = asStaticWordText(command.args[0])?.toLowerCase();
-    return !subcommand || !ALLOWED_SQL_PROXY_SUBCOMMANDS.has(subcommand);
+    if (!subcommand) {
+      return true;
+    }
+    if (mode === "block-all-sql") {
+      return true;
+    }
+    return !ALLOWED_SQL_PROXY_SUBCOMMANDS.has(subcommand);
   }
-  if (functionInvocationContainsBlockedCommand(commandName, context)) {
+  const inspectWrappedCommand = (resolved) => {
+    if (resolved.kind === "none") {
+      return false;
+    }
+    if (resolved.kind === "unknown" || !resolved.name || !resolved.args) {
+      return true;
+    }
+    return isBlockedSimpleCommand(
+      {
+        name: resolved.name,
+        args: resolved.args,
+        assignments: [],
+        redirections: []
+      },
+      context,
+      "block-all-sql",
+      options
+    );
+  };
+  if (WRAPPER_COMMANDS.has(normalizedName)) {
+    if (normalizedName === "env") {
+      return inspectWrappedCommand(resolveEnvWrapperCommand(command.args));
+    }
+    if (normalizedName === "command") {
+      return inspectWrappedCommand(resolveCommandWrapperCommand(command.args));
+    }
+    const evalScript = joinStaticWords(command.args);
+    if (evalScript == null) {
+      return true;
+    }
+    if (!evalScript.trim()) {
+      return false;
+    }
+    return stringCommandContainsBlockedCommand(
+      evalScript,
+      context,
+      "block-all-sql"
+    );
+  }
+  if (SHELL_INTERPRETER_COMMANDS.has(normalizedName)) {
+    const shellInvocation = getShellInvocationDescriptor(command.args);
+    if (shellInvocation.kind === "unknown") {
+      return true;
+    }
+    if (shellInvocation.kind === "command") {
+      if (!shellInvocation.payload) {
+        return true;
+      }
+      if (stringCommandContainsBlockedCommand(
+        shellInvocation.payload,
+        context,
+        "block-all-sql"
+      )) {
+        return true;
+      }
+      return false;
+    }
+    const hereDoc = getHereDocPayload(command.redirections);
+    if (hereDoc.hasHereDoc) {
+      if (hereDoc.payload == null) {
+        return true;
+      }
+      if (hereDoc.payload.trim().length > 0 && stringCommandContainsBlockedCommand(
+        hereDoc.payload,
+        context,
+        "block-all-sql"
+      )) {
+        return true;
+      }
+    }
+    if (shellInvocation.kind === "script") {
+      return true;
+    }
+    if (options.stdinFromPipe || shellInvocation.kind === "stdin") {
+      return !hereDoc.hasHereDoc;
+    }
+  }
+  if (functionInvocationContainsBlockedCommand(commandName, context, mode)) {
     return true;
   }
   return false;
@@ -1073,11 +1440,15 @@ import "@deepagents/agent";
 import {
   ContextEngine as ContextEngine2,
   InMemoryContextStore as InMemoryContextStore2,
+  example,
   fragment as fragment2,
+  guardrail,
+  hint as hint2,
   persona as persona3,
   policy,
   structuredOutput as structuredOutput2,
-  user as user2
+  user as user2,
+  workflow
 } from "@deepagents/context";
 var RETRY_TEMPERATURES = [0, 0.2, 0.3];
 var SQL_AGENT_ROLE = "Expert SQL query generator.";
@@ -1087,94 +1458,201 @@ var SQL_AGENT_POLICIES = [
     "schema_mapping",
     policy({
       rule: "Translate natural language into precise SQL grounded in available schema entities."
+    }),
+    hint2("Preserve schema spelling exactly, including typos in column names.")
+  ),
+  fragment2(
+    "projection_minimality",
+    policy({
+      rule: "Return only columns requested by the question; do not add helper columns unless explicitly requested."
+    }),
+    policy({
+      rule: 'For requests of the form "X sorted/ordered by Y", project X only unless Y is explicitly requested as an output field.'
+    }),
+    policy({
+      rule: "Prefer selecting schema columns directly without derived expressions when direct selection answers the request."
+    }),
+    hint2(
+      "Do not include ORDER BY, GROUP BY, or JOIN helper columns in SELECT output unless the question explicitly asks for them."
+    ),
+    policy({
+      rule: "Use DISTINCT only when uniqueness is explicitly requested (for example distinct/unique/different/no duplicates)."
+    }),
+    hint2(
+      'Do not infer DISTINCT from generic wording such as "some", plural nouns, or entity-set phrasing; for transactional/attendance-style tables, default to raw rows unless uniqueness is explicitly requested.'
+    )
+  ),
+  fragment2(
+    "date_transform_safety",
+    policy({
+      rule: "Do not assume VARCHAR/TEXT values are parseable dates. Avoid date extraction functions on text columns by default."
+    }),
+    policy({
+      rule: "Use date-part extraction only when both conditions hold: the question explicitly asks for transformation and schema values require transformation to produce that unit."
+    }),
+    hint2(
+      "Do not apply SUBSTR, STRFTIME, DATE_PART, YEAR, or similar extraction functions unless the question explicitly asks for transformation and schema values require it."
+    ),
+    hint2(
+      "If a column already represents the requested concept (for example a stored year-like value), use the column as-is."
+    )
+  ),
+  fragment2(
+    "sql_minimality",
+    guardrail({
+      rule: "Never hallucinate tables or columns.",
+      reason: "Schema fidelity is required.",
+      action: "Use only available schema entities."
+    }),
+    guardrail({
+      rule: "Avoid unnecessary transformations and derived projections.",
+      reason: "Extra transformations frequently change semantics and reduce correctness.",
+      action: "Do not add date parsing, substring extraction, or derived columns unless explicitly required by the question or schema."
+    })
+  ),
+  fragment2(
+    "preflight_checklist",
+    workflow({
+      task: "Final SQL preflight before returning output",
+      steps: [
+        "Verify selected columns match the question and remove unrequested helper projections.",
+        "If aggregate values are used only for ranking/filtering, keep them out of SELECT unless explicitly requested.",
+        "Prefer raw schema columns over derived expressions when raw columns already satisfy the request.",
+        "If a candidate query uses STRFTIME, SUBSTR, DATE_PART, YEAR, or similar extraction on text-like columns, remove that transformation unless explicitly required by the question.",
+        "Return only schema-grounded SQL using existing tables and columns."
+      ]
+    })
+  ),
+  fragment2(
+    "set_semantics",
+    policy({
+      rule: "For questions asking where both condition A and condition B hold over an attribute, compute the intersection of qualifying sets for that attribute."
+    }),
+    policy({
+      rule: "Do not force the same entity instance to satisfy both conditions unless the question explicitly requests the same person/row/entity."
+    }),
+    hint2(
+      "Prefer INTERSECT (or logically equivalent set-based shape) over requiring the same physical row/entity to satisfy both conditions unless explicitly requested."
+    ),
+    hint2(
+      "When two conditions describe different row groups whose shared attribute is requested, build each group separately and intersect the attribute values."
+    ),
+    hint2(
+      "Do not collapse cross-group conditions into a single-row AND predicate when the intent is shared values across groups."
+    ),
+    policy({
+      rule: "If two predicates on the same field cannot both be true for one row, do not combine them with AND; use set operations across separate filtered subsets when shared values are requested."
+    })
+  ),
+  fragment2(
+    "predicate_column_alignment",
+    policy({
+      rule: "Match literal values to semantically compatible columns. Do not compare descriptive names to identifier columns."
+    }),
+    hint2(
+      "When a filter value is a descriptive label (for example a department name), join through the lookup table and filter on its name/title column, not on *_id columns."
+    ),
+    hint2(
+      "When relation roles are explicit in wording (for example host/home/source/destination), prefer foreign keys with matching role qualifiers over generic similarly named columns."
+    ),
+    policy({
+      rule: "When multiple foreign-key candidates exist, select the column whose qualifier best matches the relationship described in the question."
+    }),
+    policy({
+      rule: "For hosting/held semantics, prefer host_* relationship columns when available over generic *_id alternatives."
+    }),
+    hint2(
+      'Interpret wording like "held/hosted a competition or event" as a hosting relationship and map to host_* foreign keys when present.'
+    ),
+    policy({
+      rule: "Do not compare descriptive labels or names to *_id columns; join to the table containing the descriptive field and filter there."
+    }),
+    policy({
+      rule: "Keep numeric identifiers unquoted when used as numeric equality filters unless schema indicates text identifiers."
+    }),
+    policy({
+      rule: "When filtering by a descriptive label value and a related table exposes a corresponding *_name or title column, join to that table and filter on the descriptive column."
+    })
+  ),
+  fragment2(
+    "ordering_semantics",
+    policy({
+      rule: "Respect explicit sort direction terms. If direction is not specified, use ascending order unless a superlative intent (most/least/highest/lowest) implies direction."
+    }),
+    policy({
+      rule: "When ranking categories by frequency, use COUNT for ordering but keep output focused on requested category fields unless counts are explicitly requested."
+    }),
+    policy({
+      rule: "Do not use DESC unless descending direction is explicit or a superlative intent requires descending ranking."
+    }),
+    policy({
+      rule: 'For "most common/frequent <attribute>" requests, return the attribute value(s) only; use counts only for ordering/filtering unless the question explicitly asks to return counts.'
+    }),
+    hint2(
+      'Use DESC with LIMIT 1 for "most/highest/largest"; use ASC with LIMIT 1 for "least/lowest/smallest".'
+    )
+  ),
+  fragment2(
+    "negative_membership_queries",
+    policy({
+      rule: "For requests asking entities that did not participate/host/appear in related records, prefer NOT IN or NOT EXISTS against the related foreign-key set."
+    }),
+    hint2(
+      "Map role-bearing relationship columns carefully (for example host_* foreign keys for hosting relationships) instead of generic IDs when role wording is explicit."
+    ),
+    hint2(
+      'For "never had/never exceeded" conditions over history tables, exclude entities via NOT IN/NOT EXISTS against the disqualifying entity-id set (often built with GROUP BY/HAVING MAX(...)).'
+    )
+  ),
+  fragment2(
+    "join_completeness",
+    policy({
+      rule: "Preserve entity-restricting joins implied by the question. Do not widen results by querying only a broader attribute table when a subset entity table is available."
+    }),
+    policy({
+      rule: "If an entity term in the question maps to a table, keep that table in query scope and join to attribute tables rather than dropping the entity table."
+    }),
+    hint2(
+      "If the question targets a specific entity group, include that entity table and its join conditions even when selected columns come from a related table."
+    ),
+    hint2(
+      "When the question names an entity type and a relation table links to that entity via *_id, include the entity table in scope instead of counting only relation rows."
+    ),
+    hint2(
+      "Prefer INNER JOIN by default; use LEFT JOIN only when the question explicitly requests including unmatched rows or zero-related entities."
+    )
+  ),
+  fragment2(
+    "aggregation_exactness",
+    policy({
+      rule: "Preserve requested aggregation semantics exactly: use COUNT(*) by default for total rows, use COUNT(DISTINCT ...) only when uniqueness is explicitly requested, and group by stable entity keys when computing per-entity aggregates."
+    }),
+    policy({
+      rule: "For questions asking which entity has lowest/highest average of a metric, compute AVG(metric) per entity (GROUP BY entity) and rank those aggregates."
+    }),
+    hint2(
+      'For "how many <entities>" questions over relation records, default to COUNT(*) on qualifying rows unless explicit uniqueness language is present.'
+    )
+  ),
+  fragment2(
+    "query_shape_examples",
+    example({
+      question: "List categories ordered by how many records belong to each category.",
+      answer: "SELECT category FROM records GROUP BY category ORDER BY COUNT(*)"
+    }),
+    example({
+      question: "Show labels shared by rows with metric > 100 and rows with metric < 10.",
+      answer: "SELECT label FROM records WHERE metric > 100 INTERSECT SELECT label FROM records WHERE metric < 10"
+    }),
+    example({
+      question: "List locations that have not hosted any event.",
+      answer: "SELECT location_name FROM locations WHERE location_id NOT IN (SELECT host_location_id FROM events)"
+    }),
+    example({
+      question: "List the most common category across records.",
+      answer: "SELECT category FROM records GROUP BY category ORDER BY COUNT(*) DESC LIMIT 1"
     })
-    // policy({
-    //   rule: 'Before returning an error, perform a schema-grounded self-check: identify core intent, draft best-effort SQL, then verify it uses only existing tables/columns.',
-    // }),
-    // policy({
-    //   rule: 'Return unanswerable only if that self-check confirms no valid SQL can express the required intent without inventing schema elements.',
-    // }),
-    // policy({
-    //   rule: 'Prefer a best-effort valid SQL query when entities can be reasonably inferred from table or column names.',
-    // }),
-    // policy({
-    //   rule: 'Use lexical normalization (singular/plural, paraphrases, role synonyms, and minor wording differences) to align question terms with schema names.',
-    // }),
-    // policy({
-    //   rule: 'Decompose noun phrases into core entity and qualifiers, and map the core entity first.',
-    // }),
-    // policy({
-    //   rule: 'Do not require every descriptive word to map to a separate schema field when the core entity match is unambiguous.',
-    // }),
-    // policy({
-    //   rule: 'For phrases like "X of Y", treat Y as contextual (non-blocking) when Y has no mapped schema field and the question does not ask to filter/group/select by Y explicitly.',
-    // }),
-    // policy({
-    //   rule: 'Treat unmatched qualifiers as blockers only when they are restrictive constraints (specific values, comparisons, or conditions that change row eligibility).',
-    // }),
-    // hint('Preserve schema spelling exactly, including typos in column names.'),
   )
-  // fragment(
-  //   'unanswerable_gate',
-  //   workflow({
-  //     task: 'Unanswerable decision',
-  //     steps: [
-  //       'Identify the core intent (metric/projection and required filters).',
-  //       'Attempt schema-grounded mapping for the core intent before considering error.',
-  //       'If a valid SELECT can answer the core intent without inventing schema entities, return SQL.',
-  //       'Return unanswerable only when required information cannot be mapped to any available table or column.',
-  //     ],
-  //   }),
-  //   policy({
-  //     rule: 'Do not reject a question as unanswerable when requested information can be derived by filtering, joining, grouping, counting, set operations, or sorting on available columns.',
-  //   }),
-  // ),
-  // fragment(
-  //   'query_shape_preferences',
-  //   hint(
-  //     'Prefer explicit INNER JOINs over LEFT JOINs unless the question requires unmatched rows.',
-  //   ),
-  //   hint(
-  //     'Prefer direct joins over dropping join constraints or using weaker alternatives.',
-  //   ),
-  //   hint('Use DISTINCT only when uniqueness is explicitly requested.'),
-  //   hint(
-  //     'For superlatives over grouped entities (most/least/highest/lowest by group), prefer GROUP BY with ORDER BY aggregate and LIMIT 1.',
-  //   ),
-  //   hint(
-  //     'For average/count conditions per entity, prefer GROUP BY with HAVING aggregate predicates over row-level WHERE predicates.',
-  //   ),
-  //   hint(
-  //     'For "both" conditions across two criteria, prefer INTERSECT when selecting shared values.',
-  //   ),
-  //   hint(
-  //     'For "A or B" retrieval across criteria, prefer UNION when combining two qualifying sets.',
-  //   ),
-  //   hint(
-  //     'For "never" constraints against related records, prefer NOT IN or EXCEPT against the disqualifying set.',
-  //   ),
-  //   hint(
-  //     'Use equality predicates for exact values unless the question asks for pattern matching.',
-  //   ),
-  //   hint(
-  //     'Keep numeric literals unquoted when they are purely numeric tokens in the question.',
-  //   ),
-  // ),
-  // fragment(
-  //   'sql_minimality',
-  //   guardrail({
-  //     rule: 'Never hallucinate tables or columns.',
-  //     reason: 'Schema fidelity is required.',
-  //     action: 'Use only available schema entities.',
-  //   }),
-  //   guardrail({
-  //     rule: 'Prefer the minimal query over transformed expressions.',
-  //     reason:
-  //       'Unnecessary transformations reduce correctness and add avoidable complexity.',
-  //     action:
-  //       'Do not add date parsing, substring extraction, derived projections, or extra selected columns unless explicitly requested or required by schema mismatch.',
-  //   }),
-  // ),
 ];
 function extractSql(output) {
   const match = output.match(/```sql\n?([\s\S]*?)```/);
@@ -1308,11 +1786,11 @@ function isModelUnavailableError(error) {
   if (!APICallError.isInstance(error)) {
     return false;
   }
-  const message2 = error.message.toLowerCase();
+  const message = error.message.toLowerCase();
   const responseBody = (error.responseBody ?? "").toLowerCase();
-  const is404ModelError = error.statusCode === 404 && (message2.includes("model") || responseBody.includes("model_not_found"));
+  const is404ModelError = error.statusCode === 404 && (message.includes("model") || responseBody.includes("model_not_found"));
   const errorCode = typeof error.data === "object" && error.data !== null && "error" in error.data && typeof error.data.error === "object" && error.data.error !== null && "code" in error.data.error && typeof error.data.error.code === "string" ? error.data.error.code.toLowerCase() : void 0;
-  return is404ModelError || errorCode === "model_not_found" || responseBody.includes('"code":"model_not_found"') || message2.includes("model") && message2.includes("does not exist or you do not have access to it");
+  return is404ModelError || errorCode === "model_not_found" || responseBody.includes('"code":"model_not_found"') || message.includes("model") && message.includes("does not exist or you do not have access to it");
 }
 async function withRetry(computation, options = { retries: 3 }) {
   const errors = [];
@@ -4338,17 +4816,17 @@ var TrackedFs = class {
 // packages/text2sql/src/lib/instructions.ts
 import {
   clarification,
-  example,
+  example as example2,
   explain,
   fragment as fragment3,
-  guardrail,
-  hint as hint2,
+  guardrail as guardrail2,
+  hint as hint3,
   policy as policy2,
   principle,
   quirk,
   role,
   styleGuide,
-  workflow
+  workflow as workflow2
 } from "@deepagents/context";
 function reasoningFramework() {
   return [
@@ -4357,7 +4835,7 @@ function reasoningFramework() {
     ),
     fragment3(
       "meta-cognitive-reasoning-framework",
-      hint2(
+      hint3(
         "Before taking any action (either tool calls *or* responses to the user), you must proactively, methodically, and independently plan and reason about:"
       ),
       // 1) Logical dependencies and constraints
@@ -4498,7 +4976,7 @@ function guidelines(options = {}) {
     // Few-shot: Applying reasoning principles
     fragment3(
       "reasoning-examples",
-      example({
+      example2({
         question: "Show me sales last month",
         answer: `Applying Principle 1 (Logical dependencies):
 - Need: schema to know which table has sales data
@@ -4510,7 +4988,7 @@ Applying Principle 5 (Information availability):
 
 Action: Ask user for date range clarification BEFORE generating SQL.`
       }),
-      example({
+      example2({
         question: "Why did my query return no results?",
         answer: `Applying Principle 3 (Abductive reasoning):
 - Hypothesis 1 (most likely): Filter too restrictive
@@ -4524,7 +5002,7 @@ Testing hypotheses:
 
 Action: Start with most likely hypothesis, test incrementally. NEVER guess.`
       }),
-      example({
+      example2({
         question: "Get me the top customers",
         answer: `Applying Principle 1 (Logical dependencies):
 - "Top" is ambiguous\u2014by revenue? by order count? by recency?
@@ -4538,10 +5016,10 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
     // Schema adherence - consolidated into clear rules
     fragment3(
       "schema_adherence",
-      hint2(
+      hint3(
         "Use only tables and columns from the schema. For unspecified columns, use SELECT *. When showing related items, include IDs and requested details."
       ),
-      hint2(
+      hint3(
         '"Show" means list items; "count" or "total" means aggregate. Use canonical values verbatim for filtering.'
       )
     ),
@@ -4557,18 +5035,18 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         explanation: "Measures how closely the physical row order matches the logical sort order of the column. Values near 1 or -1 mean the data is well-ordered; near 0 means scattered",
         therefore: "High correlation means range queries (BETWEEN, >, <) on that column benefit from index scans. Low correlation means the index is less effective for ranges"
       }),
-      hint2(
+      hint3(
         "When min/max stats are available, use them to validate filter values. If a user asks for values outside the known range, warn them the query may return no results."
       )
     ),
     // Joins - use relationship metadata
-    hint2(
+    hint3(
       "Use JOINs based on schema relationships. Favor PK/indexed columns; follow relationship metadata for direction and cardinality."
     ),
     // Aggregations - explain the concepts
     fragment3(
       "Aggregations",
-      hint2(
+      hint3(
         "Apply COUNT, SUM, AVG when the question implies summarization. Use window functions for ranking, running totals, or row comparisons."
       ),
       explain({
@@ -4593,7 +5071,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         issue: "NULL values behave unexpectedly in comparisons and aggregations",
         workaround: "Use IS NULL, IS NOT NULL, or COALESCE() to handle NULLs explicitly"
       }),
-      hint2(
+      hint3(
         "Always include mentioned filters from joined tables in WHERE conditions."
       )
     ),
@@ -4608,22 +5086,22 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
     // Safety guardrails - consolidated
     fragment3(
       "Query safety",
-      guardrail({
+      guardrail2({
         rule: "Generate only valid, executable SELECT/WITH statements.",
         reason: "Read-only access prevents data modification.",
         action: "Never generate INSERT, UPDATE, DELETE, DROP, or DDL statements."
       }),
-      guardrail({
+      guardrail2({
         rule: "Avoid unbounded scans and cartesian joins.",
         reason: "Protects performance and correctness.",
         action: "Apply filters on indexed columns. If join keys are unclear, ask for clarification."
       }),
-      guardrail({
+      guardrail2({
         rule: "Preserve query semantics.",
         reason: "Arbitrary modifications change results.",
         action: 'Only add LIMIT for explicit "top N" requests. Add ORDER BY for deterministic results.'
       }),
-      guardrail({
+      guardrail2({
         rule: "Seek clarification for genuine ambiguity.",
         reason: "Prevents incorrect assumptions.",
         action: "Ask a focused question before guessing."
@@ -4634,10 +5112,10 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       ask: "Clarify the ranking metric or definition.",
       reason: "Ensures correct aggregation and ordering."
     }),
-    hint2(
+    hint3(
       'Use sample cell values from schema hints to match exact casing and format in WHERE conditions (e.g., "Male" vs "male" vs "M").'
     ),
-    workflow({
+    workflow2({
       task: "SQL generation",
       steps: [
         "Schema linking: identify which tables and columns are mentioned or implied by the question.",
@@ -4649,7 +5127,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         "Verify: mentally translate SQL back to natural language. Does it match the original question?"
       ]
     }),
-    workflow({
+    workflow2({
       task: "Error recovery",
       triggers: ["SQL error", "query failed", "execution error"],
       steps: [
@@ -4662,7 +5140,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       ],
       notes: "Maximum 3 retry attempts. If still failing, explain the issue to the user."
     }),
-    workflow({
+    workflow2({
       task: "Complex query decomposition",
       triggers: [
         "multiple conditions",
@@ -4679,7 +5157,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       ],
       notes: "Complex questions often need CTEs (WITH clauses) for clarity and reusability."
     }),
-    workflow({
+    workflow2({
       task: "Multi-turn context",
       triggers: ["follow-up", "and also", "what about", "same but", "instead"],
       steps: [
@@ -4694,7 +5172,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
     }),
     fragment3(
       "Bash tool usage",
-      workflow({
+      workflow2({
         task: "Query execution",
         steps: [
           'Execute SQL through bash tool: sql run "SELECT ..."',
@@ -4703,16 +5181,16 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
           "For large results, slice first: cat <path> | jq '.[:10]'"
         ]
       }),
-      hint2(
+      hint3(
         `You cannot access sql through a tool, it'll fail so the proper way to access it is through the bash tool using "sql run" and "sql validate" commands.`
       ),
-      hint2(
+      hint3(
         "The sql command outputs: file path, column names (comma-separated), and row count. Use column names to construct precise jq queries."
       ),
-      hint2(
+      hint3(
         'This is virtual bash environment and "sql" commands proxy to the database hence you cannot access sql files directly.'
       ),
-      hint2(
+      hint3(
         "If a query fails, the sql command returns an error message in stderr."
       )
     )
@@ -4727,7 +5205,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
     );
   } else {
     baseTeachings.push(
-      hint2(
+      hint3(
         'When a month, day, or time period is mentioned without a year (e.g., "in August", "on Monday"), assume ALL occurrences of that period in the data. Do not ask for year clarification.'
       )
     );
@@ -4749,8 +5227,9 @@ import "@deepagents/agent";
 import {
   agent as agent2,
   assistant,
+  chatMessageToUIMessage,
   errorRecoveryGuardrail,
-  message
+  toMessageFragment
 } from "@deepagents/context";
 var Text2Sql = class {
   #config;
@@ -4823,17 +5302,20 @@ var Text2Sql = class {
       ...guidelines(this.#config.teachingsOptions),
       ...await this.index()
     );
-    const lastMessage = messages[messages.length - 1];
+    const lastItem = messages[messages.length - 1];
+    const lastFragment = toMessageFragment(lastItem);
+    const lastUIMessage = chatMessageToUIMessage(lastItem);
     let assistantMsgId;
-    if (lastMessage.role === "assistant") {
-      context.set(message(lastMessage));
+    if (lastUIMessage.role === "assistant") {
+      context.set(lastFragment);
       await context.save({ branch: false });
-      assistantMsgId = lastMessage.id;
+      assistantMsgId = lastUIMessage.id;
     } else {
-      context.set(message(lastMessage));
+      context.set(lastFragment);
       await context.save();
       assistantMsgId = generateId();
     }
+    const uiMessages = messages.map(chatMessageToUIMessage);
     const { mounts: skillMounts } = context.getSkillMounts();
     const { tools: tools2 } = await createResultTools({
       adapter: this.#config.adapter,
@@ -4861,7 +5343,7 @@ var Text2Sql = class {
       sendFinish: true,
       sendReasoning: true,
       sendSources: true,
-      originalMessages: messages,
+      originalMessages: uiMessages,
       generateMessageId: () => assistantMsgId,
       messageMetadata: ({ part }) => {
         if (part.type === "finish-step") {
@@ -4880,7 +5362,7 @@ var Text2Sql = class {
       }
     });
     return createUIMessageStream({
-      originalMessages: messages,
+      originalMessages: uiMessages,
       generateId: () => assistantMsgId,
       onStepFinish: async ({ responseMessage }) => {
         context.set(assistant({ ...responseMessage, id: assistantMsgId }));