@deepagents/text2sql 0.36.0 → 0.37.1

package/README.md

@@ -26,8 +26,14 @@ import { groq } from '@ai-sdk/groq';
 import { InMemoryFs } from 'just-bash';
 import pg from 'pg';
 
-import { ContextEngine, InMemoryContextStore } from '@deepagents/context';
-import { Text2Sql } from '@deepagents/text2sql';
+import {
+  ContextEngine,
+  InMemoryContextStore,
+  createBashTool,
+  createRoutingSandbox,
+  createVirtualSandbox,
+} from '@deepagents/context';
+import { Text2Sql, sqlSandboxExtension } from '@deepagents/text2sql';
 import {
   Postgres,
   columnValues,
@@ -59,12 +65,18 @@ const adapter = new Postgres({
     columnValues(),
   ],
 });
+const sandbox = await createBashTool({
+  sandbox: await createRoutingSandbox({
+    backend: await createVirtualSandbox({ fs: new InMemoryFs() }),
+    hostExtensions: [sqlSandboxExtension({ main: adapter })],
+  }),
+});
 
 const text2sql = new Text2Sql({
   version: 'v1',
   model: groq('openai/gpt-oss-20b'),
-  filesystem: new InMemoryFs(),
-  adapter,
+  sandbox,
+  adapters: { main: adapter },
   context: (...fragments) => {
     const engine = new ContextEngine({
       store,
@@ -77,14 +89,36 @@ const text2sql = new Text2Sql({
 });
 
 // Generate SQL
-const sql = await text2sql.toSql('Show me the top 10 customers by revenue');
+const sql = await text2sql.toSql(
+  'Show me the top 10 customers by revenue',
+  'main',
+);
 console.log(sql);
 ```
 
+The adapter-map key (`main` here) is the adapter name. Reuse that same key in
+`text2sql.toSql(..., 'main')` and in any `sql validate <db> "..."` /
+`sql run <db> "..."` sandbox calls.
+
+Adapter names must match `/^[A-Za-z_][A-Za-z0-9_]*$/`. If you build adapter
+maps dynamically, use `isValidAdapterName(name)` to check one key or
+`validateAdapterNames(names)` to fail fast before constructing `Text2Sql` or
+`sqlSandboxExtension`.
+
 ## AI Model Providers
 
 Text2SQL works with any model provider supported by the [Vercel AI SDK](https://sdk.vercel.ai/docs), including OpenAI, Anthropic, Google, Groq, and more.
 
+## Advanced: Composing Sandbox Extensions
+
+`Text2Sql` takes a caller-owned `sandbox`. `sqlSandboxExtension(adaptersMap)`
+returns a `SandboxExtension` that bundles the `sql` subcommand, transform
+plugins, and arg-repair hook. In the simplest case, that map is
+`{ main: adapter }`. Compose it (alongside any of your own extensions) via
+`createBashTool` + `createRoutingSandbox` + `createVirtualSandbox`.
+See [Caller-Owned Sandbox](https://januarylabs.github.io/deepagents/docs/text2sql/sqlv3)
+for composition patterns.
+
 ## Fragments
 
 Inject domain knowledge using fragments from `@deepagents/context` inside the
@@ -170,8 +204,14 @@ const followUp = await text2sql.chat([
 ]);
 ```
 
+`toSql()` is stateless. It reads the current schema fragments, but it does not
+write messages, titles, or usage into your context store.
+
 ## Direct SQL Generation with Extra Fragments
 
+This lower-level helper still takes a single `adapter` because it bypasses the
+multi-adapter `Text2Sql` wrapper entirely.
+
 ```typescript
 import { term } from '@deepagents/context';
 import { toSql } from '@deepagents/text2sql';
@@ -195,6 +235,7 @@ Full documentation available at [januarylabs.github.io/deepagents](https://janua
 
 - [Getting Started](https://januarylabs.github.io/deepagents/docs/text2sql/getting-started)
 - [Generate SQL](https://januarylabs.github.io/deepagents/docs/text2sql/to-sql)
+- [Caller-Owned Sandbox](https://januarylabs.github.io/deepagents/docs/text2sql/sqlv3)
 - [Teach the System](https://januarylabs.github.io/deepagents/docs/text2sql/teach-the-system)
 - [Build Conversations](https://januarylabs.github.io/deepagents/docs/text2sql/build-conversations)
 - [Grounding](https://januarylabs.github.io/deepagents/docs/text2sql/grounding)

package/dist/index.d.ts

@@ -1,6 +1,8 @@
+export { isValidAdapterName, validateAdapterNames, } from './lib/adapter-name.ts';
 export * from './lib/adapters/adapter.ts';
 export * from './lib/agents/exceptions.ts';
-export * from './lib/agents/result-tools.ts';
+export * from './lib/agents/sql-command.ts';
+export * from './lib/agents/sql-transform-plugins.ts';
 export * from './lib/agents/sql.agent.ts';
 export * from './lib/agents/suggestions.agents.ts';
 export * from './lib/checkpoint.ts';
@@ -8,5 +10,6 @@ export * from './lib/file-cache.ts';
 export * from './lib/fragments/schema.ts';
 export * from './lib/fs/index.ts';
 export * from './lib/instructions.ts';
+export * from './lib/sandbox.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,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,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,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC"}