nexus-ai-pro 2.1.0 → 2.3.0

package/dist/agent/sandbox.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The sandbox contract: where an agent's commands and code run, and where its files live.
+ *
+ * The package ships the contract and a conformance suite, not the isolation: a container, a VM, a
+ * remote interpreter, or a hosted sandbox fills the `Sandbox` interface. `processSandbox()` is a
+ * reference for development, which runs commands as ordinary processes; it says so in its
+ * `isolation`, and is never a security boundary.
+ */
+import type { ToolDefinition } from '../types/messages.js';
+/** Options for one command. */
+export interface SandboxExecOptions {
+    /** The working directory, inside the sandbox. Defaults to its root. */
+    cwd?: string;
+    /** Environment variables for the command. The host's own are never passed through. */
+    env?: Record<string, string>;
+    /** Sent to the command's standard input. */
+    stdin?: string;
+    /** Stops the command after this many milliseconds. */
+    timeoutMs?: number;
+    /** Stops the command when aborted. */
+    signal?: AbortSignal;
+}
+/** What a command did. */
+export interface SandboxExecResult {
+    /** Its exit code, or `null` when it was stopped. */
+    exitCode: number | null;
+    /** What it wrote to standard output. */
+    stdout: string;
+    /** What it wrote to standard error. */
+    stderr: string;
+    /** True when it was stopped by its timeout. */
+    timedOut: boolean;
+    /** How long it ran, in milliseconds. */
+    durationMs: number;
+}
+/** What a sandbox claims to isolate. The conformance suite checks the claims it can observe. */
+export interface SandboxIsolation {
+    /** Commands cannot read or write the host's files. */
+    filesystem: boolean;
+    /** Commands cannot reach the network, or only what the sandbox allows. */
+    network: boolean;
+    /** Commands cannot see or signal the host's processes. */
+    processes: boolean;
+}
+/** Where an agent's commands, code, and files go. The application provides one. */
+export interface Sandbox {
+    /** Names the sandbox in reports. */
+    readonly name: string;
+    /** What it isolates. */
+    readonly isolation: SandboxIsolation;
+    /** Runs a command line in the sandbox. */
+    exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>;
+    /** Reads a file, by a path inside the sandbox. */
+    readFile(file: string): Promise<string>;
+    /** Writes a file, creating its directory. */
+    writeFile(file: string, content: string): Promise<void>;
+    /** Lists a directory's entries. */
+    listFiles?(directory?: string): Promise<string[]>;
+    /** Removes a file or directory. */
+    removeFile?(file: string): Promise<void>;
+    /** Releases the sandbox. */
+    dispose?(): Promise<void>;
+}
+/** Raised when a path would leave the sandbox. */
+export declare class SandboxPathError extends Error {
+    /** The path that was refused. */
+    readonly path: string;
+    /** Always `SANDBOX_PATH`. */
+    readonly code = "SANDBOX_PATH";
+    constructor(
+    /** The path that was refused. */
+    path: string);
+}
+/** Options for `processSandbox()`. */
+export interface ProcessSandboxOptions {
+    /** The directory commands run in and files live under. Created when missing. */
+    root: string;
+    /** Environment variables every command gets, on top of a minimal `PATH`. */
+    env?: Record<string, string>;
+    /** Timeout for a command that sets none. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /** Output kept per stream, in bytes. Defaults to 1 MB. */
+    maxOutputBytes?: number;
+}
+/**
+ * A sandbox that runs commands as ordinary processes in a directory, for development and tests only.
+ *
+ * Its file methods refuse any path outside `root`, and commands get only `PATH` and the variables
+ * given, never the host's environment. But a command it runs can read and write anything the user
+ * can, and reach any host: `isolation` says so. Use a container or a VM in production.
+ */
+export declare function processSandbox(options: ProcessSandboxOptions): Sandbox;
+/** Options for `sandboxTools()`. */
+export interface SandboxToolsOptions {
+    /** Offer `run_command`. Defaults to true. */
+    shell?: boolean;
+    /** Offer `read_file`, `write_file`, and `list_files`. Defaults to true. */
+    files?: boolean;
+    /**
+     * The path a permission policy sees the sandbox's files under. Defaults to `/workspace`, so a
+     * policy granting `/workspace/**` grants the sandbox.
+     */
+    mount?: string;
+    /** Timeout for each command. */
+    timeoutMs?: number;
+}
+/**
+ * Tools that act through a sandbox, each declaring exactly what one call does: `run_command`
+ * declares `shell:<the command>`, and the file tools declare `filesystem:read` or
+ * `filesystem:write` with the path under `mount`. A permission policy can therefore grant a
+ * workspace, a few commands, and nothing else.
+ */
+export declare function sandboxTools(sandbox: Sandbox, options?: SandboxToolsOptions): ToolDefinition[];
+/** One conformance check's result. */
+export interface SandboxConformanceCheck {
+    /** What was checked. */
+    name: string;
+    /** Whether it held. */
+    ok: boolean;
+    /** What went wrong, when it did not. */
+    detail?: string;
+}
+/** What `runSandboxConformance()` found. */
+export interface SandboxConformanceReport {
+    /** The sandbox's name. */
+    sandbox: string;
+    /** True when every check held. */
+    passed: boolean;
+    /** Every check, in order. */
+    checks: SandboxConformanceCheck[];
+}
+/** Options for `runSandboxConformance()`. */
+export interface SandboxConformanceOptions {
+    /** The command that runs JavaScript inside the sandbox. Defaults to `node`. */
+    node?: string;
+    /** The timeout the timeout check sets, in milliseconds. Defaults to 300. */
+    timeoutMs?: number;
+}
+/**
+ * Checks a sandbox against the contract, without a test framework, so any sandbox — a container
+ * runner, a VM, a hosted service — can prove itself the same way:
+ *
+ * - commands report their output, errors, and exit code, take standard input and the variables
+ *   given, and never see the host's environment;
+ * - a command past its timeout is stopped and reported as timed out;
+ * - commands run where the files are, and files round-trip;
+ * - a path outside the sandbox is refused.
+ *
+ * Every check runs on a fresh sandbox from `create`, which is disposed afterwards.
+ */
+export declare function runSandboxConformance(create: () => Sandbox | Promise<Sandbox>, options?: SandboxConformanceOptions): Promise<SandboxConformanceReport>;

package/dist/agent/sandbox.js

@@ -0,0 +1,257 @@
+export class SandboxPathError extends Error {
+    path;
+    code = 'SANDBOX_PATH';
+    constructor(path) {
+        super(`"${path}" is outside the sandbox`);
+        this.path = path;
+        this.name = 'SandboxPathError';
+    }
+}
+export function processSandbox(options) {
+    const ready = (async () => {
+        const [{ spawn }, fs, { dirname, isAbsolute, relative, resolve }] = await Promise.all([
+            import('node:child_process'),
+            import('node:fs/promises'),
+            import('node:path'),
+        ]);
+        const root = resolve(options.root);
+        await fs.mkdir(root, { recursive: true });
+        const inside = (file) => {
+            const resolved = resolve(root, file);
+            const fromRoot = relative(root, resolved);
+            if (fromRoot.startsWith('..') || isAbsolute(fromRoot))
+                throw new SandboxPathError(file);
+            return resolved;
+        };
+        return { spawn, fs, dirname, root, inside };
+    })();
+    ready.catch(() => undefined);
+    const maxOutput = options.maxOutputBytes ?? 1_048_576;
+    return {
+        name: 'process (development only)',
+        isolation: { filesystem: false, network: false, processes: false },
+        async exec(command, execOptions = {}) {
+            const { spawn, root, inside } = await ready;
+            const started = Date.now();
+            const cwd = inside(execOptions.cwd ?? '.');
+            const env = {
+                PATH: process.env.PATH ?? '',
+                ...(process.platform === 'win32' && process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}),
+                HOME: root,
+                ...options.env,
+                ...execOptions.env,
+            };
+            return new Promise((resolve) => {
+                const child = spawn(command, {
+                    cwd,
+                    env,
+                    shell: true,
+                    windowsHide: true,
+                    detached: process.platform !== 'win32',
+                });
+                let stdout = '';
+                let stderr = '';
+                let timedOut = false;
+                let settled = false;
+                const keep = (current, chunk) => current.length >= maxOutput ? current : (current + chunk.toString('utf8')).slice(0, maxOutput);
+                child.stdout?.on('data', (chunk) => {
+                    stdout = keep(stdout, chunk);
+                });
+                child.stderr?.on('data', (chunk) => {
+                    stderr = keep(stderr, chunk);
+                });
+                const stop = () => killTree(spawn, child.pid);
+                const limit = execOptions.timeoutMs ?? options.timeoutMs ?? 30_000;
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    stop();
+                }, limit);
+                const onAbort = () => stop();
+                execOptions.signal?.addEventListener('abort', onAbort, { once: true });
+                const finish = (exitCode) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    execOptions.signal?.removeEventListener('abort', onAbort);
+                    resolve({ exitCode: timedOut ? null : exitCode, stdout, stderr, timedOut, durationMs: Date.now() - started });
+                };
+                child.on('error', (error) => {
+                    stderr += error.message;
+                    finish(null);
+                });
+                child.on('close', (code) => finish(code));
+                if (execOptions.stdin !== undefined)
+                    child.stdin?.end(execOptions.stdin);
+                else
+                    child.stdin?.end();
+            });
+        },
+        async readFile(file) {
+            const { fs, inside } = await ready;
+            return fs.readFile(inside(file), 'utf8');
+        },
+        async writeFile(file, content) {
+            const { fs, dirname, inside } = await ready;
+            const target = inside(file);
+            await fs.mkdir(dirname(target), { recursive: true });
+            await fs.writeFile(target, content, 'utf8');
+        },
+        async listFiles(directory = '.') {
+            const { fs, inside } = await ready;
+            return (await fs.readdir(inside(directory))).sort();
+        },
+        async removeFile(file) {
+            const { fs, root, inside } = await ready;
+            const target = inside(file);
+            if (target === root)
+                throw new SandboxPathError(file);
+            await fs.rm(target, { recursive: true, force: true });
+        },
+    };
+}
+function killTree(spawn, pid) {
+    if (pid === undefined)
+        return;
+    try {
+        if (process.platform === 'win32') {
+            spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+        }
+        else {
+            process.kill(-pid, 'SIGKILL');
+        }
+    }
+    catch {
+    }
+}
+export function sandboxTools(sandbox, options = {}) {
+    const mount = (options.mount ?? '/workspace').replace(/\/+$/, '');
+    const local = (file) => {
+        const unified = String(file ?? '.').replace(/\\/g, '/');
+        const relative = unified === mount ? '.' : unified.startsWith(`${mount}/`) ? unified.slice(mount.length + 1) : unified;
+        return relative.replace(/^\/+/, '') || '.';
+    };
+    const mounted = (file) => `${mount}/${local(file)}`;
+    const tools = [];
+    if (options.shell !== false) {
+        tools.push({
+            name: 'run_command',
+            description: 'Runs a shell command in the sandbox and returns its exit code and output.',
+            parameters: {
+                type: 'object',
+                properties: { command: { type: 'string', description: 'The command line to run' } },
+                required: ['command'],
+            },
+            capabilities: (args) => [`shell:${String(args.command ?? '')}`],
+            execute: async (args) => {
+                const result = await sandbox.exec(String(args.command ?? ''), {
+                    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+                });
+                return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, timedOut: result.timedOut };
+            },
+        });
+    }
+    if (options.files !== false) {
+        tools.push({
+            name: 'read_file',
+            description: `Reads a text file in the sandbox. Paths are relative to ${mount}.`,
+            parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+            capabilities: (args) => [`filesystem:read:${mounted(args.path)}`],
+            execute: async (args) => sandbox.readFile(local(args.path)),
+        }, {
+            name: 'write_file',
+            description: `Writes a text file in the sandbox, creating its directory. Paths are relative to ${mount}.`,
+            parameters: {
+                type: 'object',
+                properties: { path: { type: 'string' }, content: { type: 'string' } },
+                required: ['path', 'content'],
+            },
+            capabilities: (args) => [`filesystem:write:${mounted(args.path)}`],
+            execute: async (args) => {
+                await sandbox.writeFile(local(args.path), String(args.content ?? ''));
+                return { written: local(args.path) };
+            },
+        });
+        if (sandbox.listFiles) {
+            const list = sandbox.listFiles.bind(sandbox);
+            tools.push({
+                name: 'list_files',
+                description: 'Lists the entries of a directory in the sandbox.',
+                parameters: { type: 'object', properties: { path: { type: 'string' } } },
+                capabilities: (args) => [`filesystem:read:${mounted(args.path)}`],
+                execute: async (args) => list(local(args.path)),
+            });
+        }
+    }
+    return tools;
+}
+export async function runSandboxConformance(create, options = {}) {
+    const node = options.node ?? 'node';
+    const js = (code) => `${node} -e "${code}"`;
+    const checks = [];
+    let name = 'sandbox';
+    const check = async (label, run) => {
+        const sandbox = await create();
+        name = sandbox.name;
+        try {
+            const problem = await run(sandbox);
+            checks.push(problem ? { name: label, ok: false, detail: problem } : { name: label, ok: true });
+        }
+        catch (error) {
+            checks.push({ name: label, ok: false, detail: error instanceof Error ? error.message : String(error) });
+        }
+        finally {
+            await sandbox.dispose?.();
+        }
+    };
+    const expect = (actual, expected, what) => actual === expected ? undefined : `${what}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`;
+    await check('a command reports its output and a zero exit code', async (sandbox) => {
+        const result = await sandbox.exec(js("process.stdout.write('ok')"));
+        return expect(result.stdout, 'ok', 'stdout') ?? expect(result.exitCode, 0, 'exit code');
+    });
+    await check('a failing command reports its exit code and its errors', async (sandbox) => {
+        const result = await sandbox.exec(js("process.stderr.write('bad'); process.exit(3)"));
+        return expect(result.exitCode, 3, 'exit code') ?? expect(result.stderr, 'bad', 'stderr');
+    });
+    await check('a command reads its standard input', async (sandbox) => {
+        const result = await sandbox.exec(js('process.stdin.pipe(process.stdout)'), { stdin: 'piped' });
+        return expect(result.stdout, 'piped', 'stdout');
+    });
+    await check('a command gets the variables it is given, and none of the host', async (sandbox) => {
+        process.env.NEXUS_SANDBOX_HOST_SECRET = 'host-only';
+        try {
+            const result = await sandbox.exec(js("process.stdout.write((process.env.NEXUS_SANDBOX_GIVEN || '') + '|' + (process.env.NEXUS_SANDBOX_HOST_SECRET || ''))"), { env: { NEXUS_SANDBOX_GIVEN: 'given' } });
+            return expect(result.stdout, 'given|', 'environment');
+        }
+        finally {
+            delete process.env.NEXUS_SANDBOX_HOST_SECRET;
+        }
+    });
+    await check('a command past its timeout is stopped', async (sandbox) => {
+        const limit = options.timeoutMs ?? 300;
+        const result = await sandbox.exec(js('setTimeout(() => {}, 20000)'), { timeoutMs: limit });
+        if (!result.timedOut)
+            return 'the command was not reported as timed out';
+        if (result.durationMs > limit + 5_000)
+            return `the command ran ${result.durationMs} ms past a ${limit} ms timeout`;
+        return undefined;
+    });
+    await check('files round-trip, and commands run where they are', async (sandbox) => {
+        await sandbox.writeFile('conformance/note.txt', 'here');
+        const read = await sandbox.readFile('conformance/note.txt');
+        const seen = await sandbox.exec(js("process.stdout.write(require('fs').readFileSync('conformance/note.txt', 'utf8'))"));
+        const listed = sandbox.listFiles ? await sandbox.listFiles('conformance') : ['note.txt'];
+        return (expect(read, 'here', 'readFile') ??
+            expect(seen.stdout, 'here', 'a command reading the file') ??
+            (listed.includes('note.txt') ? undefined : `listFiles did not list note.txt: ${JSON.stringify(listed)}`));
+    });
+    await check('a path outside the sandbox is refused', async (sandbox) => {
+        for (const attempt of ['../outside.txt', 'conformance/../../outside.txt']) {
+            const refused = await sandbox.writeFile(attempt, 'escaped').then(() => false, () => true);
+            if (!refused)
+                return `writeFile("${attempt}") was allowed`;
+        }
+        return undefined;
+    });
+    return { sandbox: name, passed: checks.every((item) => item.ok), checks };
+}

package/dist/agent/tool.d.ts

@@ -1,11 +1,14 @@
-import type { ContentPart, Message, ToolDefinition, ToolOutput } from '../types/messages.js';
+import type { ContentPart, Message, ToolContext, ToolDefinition, ToolOutput } from '../types/messages.js';
 import type { ToolExecutionResult } from '../types/agent.js';
 /** Defines a tool the model can call, typing its arguments. */
 export declare function tool<TArgs extends Record<string, unknown> = Record<string, unknown>>(definition: {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
-    execute: (args: TArgs) => Promise<unknown> | unknown;
+    /** Runs the tool. In an agent, `context` says who the run is for and carries its signal and store. */
+    execute: (args: TArgs, context: ToolContext) => Promise<unknown> | unknown;
+    /** What the tool does to the world, for a permission policy; see `ToolDefinition.capabilities`. */
+    capabilities?: readonly string[] | ((args: TArgs) => readonly string[]);
 }): ToolDefinition;
 /**
  * Builds a tool's result as content: text, images, and asset references, in order. A string becomes
@@ -28,8 +31,10 @@ export declare class ToolExecutor {
     register(toolDefinition: ToolDefinition): this;
     /** Whether a tool is registered. */
     has(name: string): boolean;
+    /** A registered tool, or `undefined`. */
+    get(name: string): ToolDefinition | undefined;
     /** Every registered tool. */
     list(): ToolDefinition[];
     /** Runs a tool. An unknown name or a thrown error comes back as a failed result. */
-    execute(name: string, args: Record<string, unknown>): Promise<ToolExecutionResult>;
+    execute(name: string, args: Record<string, unknown>, context?: ToolContext): Promise<ToolExecutionResult>;
 }

package/dist/agent/tool.js

@@ -1,9 +1,17 @@
 export function tool(definition) {
+    const capabilities = definition.capabilities;
     return {
         name: definition.name,
         description: definition.description,
         parameters: definition.parameters,
-        execute: async (args) => definition.execute(args),
+        execute: async (args, context) => definition.execute(args, context ?? {}),
+        ...(capabilities === undefined
+            ? {}
+            : {
+                capabilities: typeof capabilities === 'function'
+                    ? (args) => capabilities(args)
+                    : capabilities,
+            }),
     };
 }
 export function toolOutput(...content) {
@@ -37,10 +45,13 @@ export class ToolExecutor {
     has(name) {
         return this.tools.has(name);
     }
+    get(name) {
+        return this.tools.get(name);
+    }
     list() {
         return [...this.tools.values()];
     }
-    async execute(name, args) {
+    async execute(name, args, context) {
         const toolDefinition = this.tools.get(name);
         if (!toolDefinition) {
             return { ok: false, error: `Tool "${name}" is not registered` };
@@ -49,7 +60,7 @@ export class ToolExecutor {
             return { ok: false, error: `Tool "${name}" does not have an execute function` };
         }
         try {
-            const result = await toolDefinition.execute(args);
+            const result = await toolDefinition.execute(args, context);
             return { ok: true, result };
         }
         catch (err) {

package/dist/cache/memory-cache.d.ts

@@ -15,6 +15,14 @@ export declare class MemoryCache<T> {
     constructor(maxEntries?: number);
     /** Returns a value, or `undefined` for a miss or an expired entry. A hit counts as recent use. */
     get(key: string): T | undefined;
+    /**
+     * Like `get()`, also saying whether an entry was there but had expired, which a caller can report
+     * as stale rather than missing. The expired entry is removed either way.
+     */
+    lookup(key: string): {
+        value?: T;
+        stale: boolean;
+    };
     /** Stores a value. Defaults to 5 minutes. */
     set(key: string, value: T, ttlSeconds?: number): void;
     /** Removes every entry. */

package/dist/cache/memory-cache.js

@@ -16,6 +16,15 @@ export class MemoryCache {
         this.entries.set(key, entry);
         return entry.value;
     }
+    lookup(key) {
+        const entry = this.entries.get(key);
+        if (entry && entry.expiresAt < Date.now()) {
+            this.entries.delete(key);
+            return { stale: true };
+        }
+        const value = this.get(key);
+        return value === undefined ? { stale: false } : { value, stale: false };
+    }
     set(key, value, ttlSeconds = 300) {
         if (this.entries.size >= this.maxEntries) {
             const oldest = this.entries.keys().next().value;

package/dist/cache/semantic-cache.d.ts

@@ -25,10 +25,13 @@ export declare class SemanticCache {
     constructor(options?: SemanticCacheOptions);
     /**
      * The cached response for the most similar earlier request above the threshold, or `undefined`.
+     * Only entries stored under the same `scope` are compared: the client passes the request's tenant
+     * and cache namespace, so one tenant is never answered from another's entry however alike the
+     * questions are.
      */
-    get(request: CompletionRequest): Promise<NexusResponse | undefined>;
-    /** Caches a response under its request's embedding. */
-    set(key: string, request: CompletionRequest, response: NexusResponse): Promise<void>;
+    get(request: CompletionRequest, scope?: string): Promise<NexusResponse | undefined>;
+    /** Caches a response under its request's embedding, in a `scope` lookups must match. */
+    set(key: string, request: CompletionRequest, response: NexusResponse, scope?: string): Promise<void>;
     /** Removes every entry. */
     clear(): void;
 }

package/dist/cache/semantic-cache.js

@@ -7,7 +7,7 @@ export class SemanticCache {
         this.options = options;
         this.embed = options.embed || createHashEmbeddings;
     }
-    async get(request) {
+    async get(request, scope = '') {
         if (!this.options.enabled)
             return undefined;
         const text = requestToSearchText(request);
@@ -17,6 +17,8 @@ export class SemanticCache {
         let best;
         this.entries = this.entries.filter((entry) => entry.expiresAt > now);
         for (const entry of this.entries) {
+            if (entry.scope !== scope)
+                continue;
             const score = cosineSimilarity(embedding, entry.embedding);
             if (score >= threshold && (!best || score > best.score)) {
                 best = { entry, score };
@@ -37,7 +39,7 @@ export class SemanticCache {
             },
         };
     }
-    async set(key, request, response) {
+    async set(key, request, response, scope = '') {
         if (!this.options.enabled)
             return;
         const text = requestToSearchText(request);
@@ -47,6 +49,7 @@ export class SemanticCache {
             this.entries.shift();
         this.entries.push({
             key,
+            scope,
             text,
             embedding,
             response,

package/dist/cli/args.js

@@ -5,12 +5,15 @@ export const BOOLEAN_FLAGS = new Set([
     'allow-dataset-mismatch',
     'check',
     'densify',
+    'dry-run',
     'fail',
     'fail-on-regression',
     'help',
     'json',
     'print',
+    'record',
     'reveal-values',
+    'strict',
     'write',
 ]);
 export function parseArgs(args) {

package/dist/cli/db.d.ts

@@ -1,8 +1,20 @@
 import { type ParsedArgs } from './args.js';
 /**
- * `nexus db sql` prints the Postgres schema for the chosen adapters.
+ * `nexus db sql | status | migrate`.
  *
- * Printed rather than applied, so the CLI needs no database driver and the schema goes through
- * whatever review and migration tooling the application already has: `nexus db sql | psql "$URL"`.
+ * `sql` prints the Postgres schema, so the CLI needs no driver and the schema can go through the
+ * application's own review and tooling: `nexus db sql | psql "$URL"`. `status` and `migrate` reach
+ * the database through a module the application writes, which exports its own client:
+ *
+ * ```js
+ * // db.mjs
+ * import pg from 'pg';
+ * export const client = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+ * export const close = () => client.end();
+ * ```
+ *
+ * The module may also export `dialect` (`postgres` or `sqlite`), a `transaction` function (see
+ * `PostgresMigrateOptions`), and `migrations`, a list replacing the bundled ones, for stores on
+ * custom tables.
  */
-export declare function runDbCommand(subcommand: string | undefined, { flags }: ParsedArgs): Promise<void>;
+export declare function runDbCommand(subcommand: string | undefined, args: ParsedArgs): Promise<void>;