@deepagents/text2sql 4.0.0 → 4.2.0

package/README.md

@@ -114,7 +114,11 @@ import {
   npm,
   user,
 } from '@deepagents/context';
-import { createSqlCommandHooks, instructions } from '@deepagents/text2sql';
+import {
+  createSqlCommandHooks,
+  instructions,
+  sqlValidateReminder,
+} from '@deepagents/text2sql';
 
 const store = new InMemoryContextStore();
 const context = new ContextEngine({
@@ -149,6 +153,7 @@ const fragments = JSON.parse(
   await sandbox.sandbox.readFile(manifest.fragmentsPath),
 ) as ContextFragment[];
 context.set(...instructions(), ...fragments);
+context.set(sqlValidateReminder());
 
 const ai = agent({
   name: 'sql-assistant',
@@ -178,6 +183,11 @@ schema fragments returned by `sql index`. The index output starts with an
 model must pass to `sql validate <db>` and `sql run <db>`. Add or replace the
 instructions with your own domain fragments as needed.
 
+`sqlValidateReminder()` returns a context reminder fragment backed by
+`SQL_VALIDATE_REMINDER`. It adds a tool-output system reminder when the current
+assistant turn calls `sql run <db> "..."` without a prior `sql validate <db>
+"..."` for the same configured adapter name and exact SQL text.
+
 ## Advanced: SQL CLI in Sandboxes
 
 `sql validate <db> "..."` and `sql run <db> "..."` are real commands from the

package/dist/bin/sql.js

@@ -896,6 +896,25 @@ var Text2SqlUnknownAdapterError = class _Text2SqlUnknownAdapterError extends Err
     return error instanceof _Text2SqlUnknownAdapterError && error[text2SqlUnknownAdapterMarker] === true;
   }
 };
+var text2SqlUnknownDatabaseMarker = Symbol("Text2SqlUnknownDatabaseError");
+var Text2SqlUnknownDatabaseError = class _Text2SqlUnknownDatabaseError extends Error {
+  [text2SqlUnknownDatabaseMarker];
+  requested;
+  available;
+  constructor(requested, available) {
+    const list = available.join(", ") || "(none configured)";
+    super(
+      requested ? `unknown database "${requested}". Available: ${list}` : `no database specified. Available: ${list}`
+    );
+    this.name = "Text2SqlUnknownDatabaseError";
+    this.requested = requested;
+    this.available = available;
+    this[text2SqlUnknownDatabaseMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _Text2SqlUnknownDatabaseError && error[text2SqlUnknownDatabaseMarker] === true;
+  }
+};
 var Text2Sql = class {
   #config;
   #indexer;
@@ -932,6 +951,29 @@ var Text2Sql = class {
   hasAdapter(name) {
     return name in this.#config.adapters;
   }
+  /**
+   * Resolve a user-supplied `<db>` token to a configured adapter name for the
+   * surfaces that accept one (CLI, sandbox `sql` command, JSON-RPC daemon, MCP):
+   * - exact match → that name
+   * - no match (or omitted) but exactly one adapter configured → route to it
+   * - otherwise → throw with the user-facing "unknown database" message
+   *
+   * Internal execution paths keep using the strict {@link Text2Sql.run}/
+   * {@link Text2Sql.validate}, which reject an unknown name outright.
+   */
+  resolveAdapterName(db) {
+    if (!db || db.trim() === "") {
+      const names2 = this.adapterNames();
+      if (names2.length === 1) return names2[0];
+      throw new Text2SqlUnknownDatabaseError(db, names2);
+    }
+    if (this.hasAdapter(db)) {
+      return db;
+    }
+    const names = this.adapterNames();
+    if (names.length === 1) return names[0];
+    throw new Text2SqlUnknownDatabaseError(db, names);
+  }
   async validate(name, sql) {
     const adapter = this.#requireAdapter(name);
     const result = this.#validateWith(adapter, sql);
@@ -980,17 +1022,6 @@ var Text2Sql = class {
 
 // packages/text2sql/src/bin/command.ts
 import * as path3 from "node:path";
-
-// packages/text2sql/src/lib/resolve-adapter.ts
-function resolveAdapter(text2Sql, db) {
-  if (text2Sql.hasAdapter(db)) return db;
-  const names = text2Sql.adapterNames();
-  if (names.length === 1) return names[0];
-  const available = names.join(", ") || "(none configured)";
-  throw new Error(`unknown database "${db}". Available: ${available}`);
-}
-
-// packages/text2sql/src/bin/command.ts
 var OUT_DIR_OPTION = {
   flag: "--out-dir <path>",
   description: "Output directory (default: $TEXT2SQL_OUT_DIR or ./sql)"
@@ -1023,14 +1054,8 @@ var SqlCommand = class {
     throw new CommandError(this.name, message, exitCode);
   }
   resolveAdapterName(text2Sql, db) {
-    if (!db) {
-      const available = text2Sql.adapterNames().join(", ") || "(none configured)";
-      this.fail(
-        `missing database name. Usage: sql ${this.name} ${this.usage}. Available: ${available}`
-      );
-    }
     try {
-      return resolveAdapter(text2Sql, db);
+      return text2Sql.resolveAdapterName(db);
     } catch (error) {
       this.fail(errorMessage2(error));
     }

package/dist/index.d.ts

@@ -13,5 +13,6 @@ export * from './lib/fs/index.ts';
 export * from './lib/instructions.ts';
 export * from './lib/sql-hooks.ts';
 export { type CreateSqlCommandOptions, type CreateSqlCommandResult, createSqlCommand, } from './lib/sql-command.ts';
+export { SQL_VALIDATE_REMINDER, sqlValidateReminder, } from './lib/sql-validate-reminder.ts';
 export * from './lib/sql.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,gCAAgC,CAAC;AACxC,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -4684,39 +4684,11 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
 }
 
 // packages/text2sql/src/lib/sql-meta-hook.ts
+import { useBashMeta } from "@deepagents/context";
+
+// packages/text2sql/src/lib/sql-invocation.ts
 import { parse } from "just-bash";
-import { asStaticWordText, useBashMeta } from "@deepagents/context";
-var SQL_VALIDATE_REMINDER = 'Always run `sql validate <db> "..."` before `sql run <db> "..."` to catch syntax errors early.';
-function createSqlMetaHook({ adapters }) {
-  const pendingByCommand = /* @__PURE__ */ new Map();
-  return {
-    track({ repaired, transformed }) {
-      const invocation = parseSqlQueryInvocation(repaired);
-      if (!invocation) return;
-      const pending = pendingByCommand.get(transformed) ?? [];
-      pending.push(invocation);
-      pendingByCommand.set(transformed, pending);
-    },
-    onAfterBashCall({ command }) {
-      const pending = pendingByCommand.get(command);
-      const invocation = pending?.shift();
-      if (pending?.length === 0) pendingByCommand.delete(command);
-      if (!invocation) return void 0;
-      if (invocation.subcommand === "run") {
-        useBashMeta()?.setReminder(SQL_VALIDATE_REMINDER);
-      }
-      const adapter = adapters[invocation.dbName];
-      if (!adapter) return void 0;
-      try {
-        useBashMeta()?.setHidden({
-          formattedSql: adapter.format(invocation.sql)
-        });
-      } catch {
-      }
-      return void 0;
-    }
-  };
-}
+import { asStaticWordText } from "@deepagents/context";
 function parseSqlQueryInvocation(command) {
   const simpleCommand = parseSingleSimpleCommand(command);
   if (!simpleCommand) return null;
@@ -4767,6 +4739,35 @@ function joinSqlWords(words) {
   return sql || null;
 }
 
+// packages/text2sql/src/lib/sql-meta-hook.ts
+function createSqlMetaHook({ adapters }) {
+  const pendingByCommand = /* @__PURE__ */ new Map();
+  return {
+    track({ repaired, transformed }) {
+      const invocation = parseSqlQueryInvocation(repaired);
+      if (!invocation) return;
+      const pending = pendingByCommand.get(transformed) ?? [];
+      pending.push(invocation);
+      pendingByCommand.set(transformed, pending);
+    },
+    onAfterBashCall({ command }) {
+      const pending = pendingByCommand.get(command);
+      const invocation = pending?.shift();
+      if (pending?.length === 0) pendingByCommand.delete(command);
+      if (!invocation) return void 0;
+      const adapter = adapters[invocation.dbName];
+      if (!adapter) return void 0;
+      try {
+        useBashMeta()?.setHidden({
+          formattedSql: adapter.format(invocation.sql)
+        });
+      } catch {
+      }
+      return void 0;
+    }
+  };
+}
+
 // packages/text2sql/src/lib/sql-repair.ts
 import {
   buildSubcommandRepair,
@@ -5617,8 +5618,7 @@ import {
   BashException as BashException2,
   buildSubcommandRepair as buildSubcommandRepair2,
   defineSubcommandGroup,
-  repairQuotedArg as repairQuotedArg2,
-  useBashMeta as useBashMeta2
+  repairQuotedArg as repairQuotedArg2
 } from "@deepagents/context";
 
 // packages/text2sql/src/lib/sql.ts
@@ -5652,6 +5652,25 @@ var Text2SqlUnknownAdapterError = class _Text2SqlUnknownAdapterError extends Err
     return error instanceof _Text2SqlUnknownAdapterError && error[text2SqlUnknownAdapterMarker] === true;
   }
 };
+var text2SqlUnknownDatabaseMarker = Symbol("Text2SqlUnknownDatabaseError");
+var Text2SqlUnknownDatabaseError = class _Text2SqlUnknownDatabaseError extends Error {
+  [text2SqlUnknownDatabaseMarker];
+  requested;
+  available;
+  constructor(requested, available) {
+    const list = available.join(", ") || "(none configured)";
+    super(
+      requested ? `unknown database "${requested}". Available: ${list}` : `no database specified. Available: ${list}`
+    );
+    this.name = "Text2SqlUnknownDatabaseError";
+    this.requested = requested;
+    this.available = available;
+    this[text2SqlUnknownDatabaseMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _Text2SqlUnknownDatabaseError && error[text2SqlUnknownDatabaseMarker] === true;
+  }
+};
 var Text2Sql = class {
   #config;
   #indexer;
@@ -5688,6 +5707,29 @@ var Text2Sql = class {
   hasAdapter(name) {
     return name in this.#config.adapters;
   }
+  /**
+   * Resolve a user-supplied `<db>` token to a configured adapter name for the
+   * surfaces that accept one (CLI, sandbox `sql` command, JSON-RPC daemon, MCP):
+   * - exact match → that name
+   * - no match (or omitted) but exactly one adapter configured → route to it
+   * - otherwise → throw with the user-facing "unknown database" message
+   *
+   * Internal execution paths keep using the strict {@link Text2Sql.run}/
+   * {@link Text2Sql.validate}, which reject an unknown name outright.
+   */
+  resolveAdapterName(db) {
+    if (!db || db.trim() === "") {
+      const names2 = this.adapterNames();
+      if (names2.length === 1) return names2[0];
+      throw new Text2SqlUnknownDatabaseError(db, names2);
+    }
+    if (this.hasAdapter(db)) {
+      return db;
+    }
+    const names = this.adapterNames();
+    if (names.length === 1) return names[0];
+    throw new Text2SqlUnknownDatabaseError(db, names);
+  }
   async validate(name, sql) {
     const adapter = this.#requireAdapter(name);
     const result = this.#validateWith(adapter, sql);
@@ -5734,17 +5776,7 @@ var Text2Sql = class {
   }
 };
 
-// packages/text2sql/src/lib/resolve-adapter.ts
-function resolveAdapter(text2Sql, db) {
-  if (text2Sql.hasAdapter(db)) return db;
-  const names = text2Sql.adapterNames();
-  if (names.length === 1) return names[0];
-  const available = names.join(", ") || "(none configured)";
-  throw new Error(`unknown database "${db}". Available: ${available}`);
-}
-
 // packages/text2sql/src/lib/sql-command.ts
-var SQL_VALIDATE_REMINDER2 = 'Always run `sql validate <db> "..."` before `sql run <db> "..."` to catch syntax errors early.';
 var SqlCommandError = class extends BashException2 {
   #subcommand;
   #exitCode;
@@ -5809,8 +5841,6 @@ function resolveOutputDir(ctx, flags, fallback) {
 async function handleRun(text2Sql, defaultOutputDir, args, ctx) {
   return runHandler("run", async () => {
     const flags = parseFlags("run", args);
-    const meta = useBashMeta2();
-    meta?.setReminder(SQL_VALIDATE_REMINDER2);
     const { name, sql } = takeDbAndSql("run", flags.positional, text2Sql);
     const outputDir = resolveOutputDir(ctx, flags, defaultOutputDir);
     const { rows, columns } = await text2Sql.run(name, sql);
@@ -5849,14 +5879,7 @@ async function runHandler(subcommand, fn) {
 }
 function takeDbAndSql(subcommand, positional, text2Sql) {
   const [db, ...rest] = positional;
-  if (!db) {
-    const available = text2Sql.adapterNames().join(", ");
-    throw new SqlCommandError(
-      subcommand,
-      `missing database name. Usage: sql ${subcommand} <db> "SELECT ...". Available: ${available}`
-    );
-  }
-  const name = resolveAdapter(text2Sql, db);
+  const name = text2Sql.resolveAdapterName(db);
   const sql = rest.join(" ").trim();
   if (!sql) {
     throw new SqlCommandError(subcommand, "no query provided");
@@ -5874,6 +5897,47 @@ function repairDbNameAndQuotedArg(rawArgs) {
   if (repaired == null) return null;
   return `${dbName} ${repaired}`;
 }
+
+// packages/text2sql/src/lib/sql-validate-reminder.ts
+import { isToolUIPart } from "ai";
+import { reminder } from "@deepagents/context";
+var SQL_VALIDATE_REMINDER = 'Always run `sql validate <db> "..."` before `sql run <db> "..."` to catch syntax errors early.';
+function extractSqlInvocation(command) {
+  if (typeof command !== "string") return null;
+  return parseSqlQueryInvocation(repairSqlCommand(command));
+}
+function inputCommand(input) {
+  return input?.command;
+}
+function alreadyValidated(messages, run) {
+  for (const message of messages ?? []) {
+    for (const part of message.parts) {
+      if (!isToolUIPart(part)) continue;
+      const invocation = extractSqlInvocation(
+        inputCommand(part.input)
+      );
+      if (invocation?.subcommand === "validate" && invocation.dbName === run.dbName && invocation.sql === run.sql) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function sqlRunMissingValidate() {
+  return (ctx) => {
+    const call = ctx.executingTool;
+    if (!call || call.name !== "bash") return false;
+    const run = extractSqlInvocation(inputCommand(call.input));
+    if (run?.subcommand !== "run") return false;
+    return !alreadyValidated(ctx.lastAssistantMessages, run);
+  };
+}
+function sqlValidateReminder() {
+  return reminder(SQL_VALIDATE_REMINDER, {
+    target: "tool-output",
+    when: sqlRunMissingValidate()
+  });
+}
 export {
   Adapter,
   AdapterIndexer,
@@ -5888,11 +5952,13 @@ export {
   SQLReadOnlyError,
   SQLScopeError,
   SQLValidationError,
+  SQL_VALIDATE_REMINDER,
   ScopedFs,
   SqliteFs,
   TEXT2SQL_INDEX_PROGRESS_CHUNK,
   Text2Sql,
   Text2SqlUnknownAdapterError,
+  Text2SqlUnknownDatabaseError,
   Text2SqlValidationError,
   UnanswerableSQLError,
   applyTablesFilter,
@@ -5912,6 +5978,7 @@ export {
   matchesFilter,
   relationship,
   repairSqlCommand,
+  sqlValidateReminder,
   suggestionsAgent,
   table,
   toSql,