@deepagents/text2sql 2.1.0 → 2.3.0

package/README.md

@@ -106,7 +106,8 @@ import {
   InMemoryContextStore,
   agent,
   chat,
-  createContainerTool,
+  createBashTool,
+  createDockerSandbox,
   errorRecoveryGuardrail,
   npm,
   user,
@@ -120,7 +121,7 @@ const context = new ContextEngine({
   userId: 'user-456',
 });
 
-const sandbox = await createContainerTool({
+const backend = await createDockerSandbox({
   installers: [npm('@deepagents/text2sql', { ensureRuntime: true })],
   volumes: [
     {
@@ -133,6 +134,9 @@ const sandbox = await createContainerTool({
   env: {
     TEXT2SQL_ADAPTERS: '/workspace/text2sql-adapters.ts',
   },
+});
+const sandbox = await createBashTool({
+  sandbox: backend,
   ...createSqlCommandHooks({ adapters: { main: adapter } }),
 });
 
@@ -193,8 +197,42 @@ sandbox was not prepared correctly.
 Set `TEXT2SQL_INDEX_VERSION` to manage cache invalidation across runs. Cache
 keys are `index-<version>-<adapter>`, so bump the version when schema changes.
 
-Spread `createSqlCommandHooks({ adapters })` into `createBashTool()` or
-`createContainerTool()` for model-driven bash calls. The before hook preserves
+For in-process or virtual-sandbox usage (without installing the package CLI),
+wrap an existing `Text2Sql` instance as a just-bash custom command:
+
+```typescript
+import { InMemoryFs, createVirtualSandbox } from '@deepagents/context';
+import {
+  type CreateSqlCommandOptions,
+  type CreateSqlCommandResult,
+  Text2Sql,
+  createSqlCommand,
+} from '@deepagents/text2sql';
+
+const text2sql = new Text2Sql({ model, adapters: { main: adapter } });
+
+const commandOptions: CreateSqlCommandOptions = {
+  outputDir: '/sql-artifacts',
+};
+const sqlCommand: CreateSqlCommandResult = createSqlCommand(
+  text2sql,
+  commandOptions,
+);
+
+const sandbox = await createVirtualSandbox({
+  fs: new InMemoryFs(),
+  customCommands: [sqlCommand.command],
+});
+
+await sandbox.executeCommand('sql validate main "SELECT 1"');
+```
+
+`CreateSqlCommandOptions` configures command defaults (currently `outputDir`).
+`CreateSqlCommandResult` returns the command plus a `repair(raw)` helper for
+normalizing model-generated argv before execution.
+
+Spread `createSqlCommandHooks({ adapters })` into `createBashTool()` for
+model-driven bash calls. The before hook preserves
 the old virtual-command tolerance for common LLM quote mistakes, rewrites SQL
 identifier backticks so bash does not run them as command substitutions, and
 blocks raw database access so read-only and scope checks stay behind
@@ -202,6 +240,10 @@ blocks raw database access so read-only and scope checks stay behind
 metadata from the host adapter map without putting that concern into the real
 CLI.
 
+Read-only enforcement accepts a single `SELECT`/`WITH` statement even when it
+starts with whitespace or SQL comments (`-- ...`, `/* ... */`). It still
+rejects comment-only input, multi-statement batches, and write operations.
+
 ## Fragments
 
 Inject domain knowledge by setting fragments on the `ContextEngine` you build