@yejiming/dsh-data-agent 0.0.6 → 0.0.10

package/lib/types/index.d.ts

@@ -1,37 +1,38 @@
 /**
- * Data Agent server half for the dsh web GUI. The host row provides the
- * `dataAgentConnections` service (session-scoped in-memory store; passwords
- * never leave memory), seeds config connections (`connections`, `'*'` =
- * wildcard default), and installs the `data-agent` agent preset into
- * `$DSH_HOME/.agent-presets/` (idempotent, never overwrites a user-edited
- * directory).
+ * Data Agent profile entry. The host row provides the
+ * `dataAgentConnections` service (shared non-secret profile/binding storage;
+ * temporary passwords stay process-local), seeds config connections (`connections`, `'*'` =
+ * wildcard default), installs the `data-agent` agent preset into
+ * `$DSH_HOME/.agent-presets/`, and preloads the preset-scoped database tools
+ * and command through this profile bundle entry.
  *
  * The HTTP routes live in the separate `./routes` entry
  * (`@yejiming/dsh-data-agent/routes`, cordis row `data-agent-routes`) so
- * this row keeps working in headless profiles without a webserver; the
- * database tools themselves live in the `./tool` entry and are mounted only
- * by the data-agent preset.
+ * this row keeps working in headless profiles without a webserver. The
+ * database implementations still have public `./tool` and `./command`
+ * exports, but the shipped preset does not dynamically import those package
+ * subpaths. Loading them here keeps Desktop on the same profile-startup path
+ * as other UI bundles and avoids Electron ASAR package-resolution drift.
  * @module @yejiming/dsh-data-agent
  */
 import type { Context } from '@deepseek-ai/cordis';
+import type { ScopeKey } from '@deepseek-ai/dsh-scope';
 /** The `dataAgentConnections` service face on the cordis context. */
 declare module '@deepseek-ai/cordis' {
     interface Context {
         dataAgentConnections: DataAgentConnections;
     }
 }
+import z from 'schemastery';
 import { type DataAgentConnections, type DatabaseType } from './connections.ts';
 import { type ClientConfig } from './clients.ts';
+import { type Config as ToolConfig } from './tool.ts';
 /** Cordis plugin name (diagnostics only). */
 export declare const name = "data-agent";
-/** Services required before the store can serve. */
+/** Services required before the profile entry can mount its preset layer. */
 export declare const inject: string[];
 /** Deployment overrides for one database type's CLI client. */
-export interface ClientsConfig {
-    mysql?: ClientConfig;
-    postgres?: ClientConfig;
-    sqlite?: ClientConfig;
-}
+export type ClientsConfig = Partial<Record<DatabaseType, ClientConfig>>;
 /**
  * One config-seeded connection. Deliberately password-free: passwords are a
  * memory-only / connect-time value, so only the /connect route may carry one.
@@ -46,6 +47,9 @@ export interface SeededConnectionConfig {
     database: string;
     /** Optional per-seed read-only guard. */
     readonly?: boolean;
+    /** Safe credential reference. Real passwords are rejected by the schema. */
+    passwordRef?: string;
+    password?: never;
 }
 /** Required plugin configuration (loader schema with deployment defaults). */
 export interface Config {
@@ -61,73 +65,97 @@ export interface Config {
     queryTimeoutMs: number;
     /** In-memory cap on database-tool captured output. */
     maxResultChars: number;
+    /** Maximum structured rows returned by one database read tool call. */
+    maxRows: number;
+    /** Maximum SQL text accepted by the shared Web query adapter. */
+    maxQueryChars: number;
     /** Default read-only guard: true rejects write statements in database tools and /query. */
     readonly: boolean;
+    /** Persist non-secret profiles/bindings through DSH storage-domain. */
+    persistConnections: boolean;
     /** CLI client overrides keyed by database type. */
     clients: ClientsConfig;
     /** Config-seeded connections keyed by session id (`'*'` = wildcard default). */
     connections: Record<string, SeededConnectionConfig>;
 }
 /** Loader schema with deployment defaults (no library defaults). */
-export declare const Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
-    presetId: import("@deepseek-ai/schemastery").default<string, string>;
-    installPreset: import("@deepseek-ai/schemastery").default<boolean, boolean>;
-    connectTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
-    introspectMaxTables: import("@deepseek-ai/schemastery").default<number, number>;
-    queryTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
-    maxResultChars: import("@deepseek-ai/schemastery").default<number, number>;
-    readonly: import("@deepseek-ai/schemastery").default<boolean, boolean>;
-    clients: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/cosmokit").Dict<{
+export declare const Config: z<Schemastery.ObjectS<{
+    presetId: z<string, string>;
+    installPreset: z<boolean, boolean>;
+    connectTimeoutMs: z<number, number>;
+    introspectMaxTables: z<number, number>;
+    queryTimeoutMs: z<number, number>;
+    maxResultChars: z<number, number>;
+    maxRows: z<number, number>;
+    maxQueryChars: z<number, number>;
+    readonly: z<boolean, boolean>;
+    persistConnections: z<boolean, boolean>;
+    clients: z<import("cosmokit").Dict<{
         command?: string | null | undefined;
         args?: string[] | null | undefined;
-    } & import("cosmokit").Dict, string>, import("@deepseek-ai/cosmokit").Dict<Schemastery.ObjectT<{
-        command: import("@deepseek-ai/schemastery").default<string, string>;
-        args: import("@deepseek-ai/schemastery").default<string[], string[]>;
+        searchPaths?: string[] | null | undefined;
+    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+        command: z<string, string>;
+        args: z<string[], string[]>;
+        searchPaths: z<string[], string[]>;
     }>, string>>;
-    connections: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/cosmokit").Dict<{
+    connections: z<import("cosmokit").Dict<{
         type?: "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | null | undefined;
         host?: string | null | undefined;
         port?: number | null | undefined;
         user?: string | null | undefined;
         database?: string | null | undefined;
         readonly?: boolean | null | undefined;
-    } & import("cosmokit").Dict, string>, import("@deepseek-ai/cosmokit").Dict<Schemastery.ObjectT<{
-        type: import("@deepseek-ai/schemastery").default<"mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala", "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala">;
-        host: import("@deepseek-ai/schemastery").default<string, string>;
-        port: import("@deepseek-ai/schemastery").default<number, number>;
-        user: import("@deepseek-ai/schemastery").default<string, string>;
-        database: import("@deepseek-ai/schemastery").default<string, string>;
-        readonly: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        passwordRef?: string | null | undefined;
+        password?: null | undefined;
+    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+        type: z<"mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala", "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala">;
+        host: z<string, string>;
+        port: z<number, number>;
+        user: z<string, string>;
+        database: z<string, string>;
+        readonly: z<boolean, boolean>;
+        passwordRef: z<string, string>;
+        password: z<never, never>;
     }>, string>>;
 }>, Schemastery.ObjectT<{
-    presetId: import("@deepseek-ai/schemastery").default<string, string>;
-    installPreset: import("@deepseek-ai/schemastery").default<boolean, boolean>;
-    connectTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
-    introspectMaxTables: import("@deepseek-ai/schemastery").default<number, number>;
-    queryTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
-    maxResultChars: import("@deepseek-ai/schemastery").default<number, number>;
-    readonly: import("@deepseek-ai/schemastery").default<boolean, boolean>;
-    clients: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/cosmokit").Dict<{
+    presetId: z<string, string>;
+    installPreset: z<boolean, boolean>;
+    connectTimeoutMs: z<number, number>;
+    introspectMaxTables: z<number, number>;
+    queryTimeoutMs: z<number, number>;
+    maxResultChars: z<number, number>;
+    maxRows: z<number, number>;
+    maxQueryChars: z<number, number>;
+    readonly: z<boolean, boolean>;
+    persistConnections: z<boolean, boolean>;
+    clients: z<import("cosmokit").Dict<{
         command?: string | null | undefined;
         args?: string[] | null | undefined;
-    } & import("cosmokit").Dict, string>, import("@deepseek-ai/cosmokit").Dict<Schemastery.ObjectT<{
-        command: import("@deepseek-ai/schemastery").default<string, string>;
-        args: import("@deepseek-ai/schemastery").default<string[], string[]>;
+        searchPaths?: string[] | null | undefined;
+    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+        command: z<string, string>;
+        args: z<string[], string[]>;
+        searchPaths: z<string[], string[]>;
     }>, string>>;
-    connections: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/cosmokit").Dict<{
+    connections: z<import("cosmokit").Dict<{
         type?: "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | null | undefined;
         host?: string | null | undefined;
         port?: number | null | undefined;
         user?: string | null | undefined;
         database?: string | null | undefined;
         readonly?: boolean | null | undefined;
-    } & import("cosmokit").Dict, string>, import("@deepseek-ai/cosmokit").Dict<Schemastery.ObjectT<{
-        type: import("@deepseek-ai/schemastery").default<"mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala", "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala">;
-        host: import("@deepseek-ai/schemastery").default<string, string>;
-        port: import("@deepseek-ai/schemastery").default<number, number>;
-        user: import("@deepseek-ai/schemastery").default<string, string>;
-        database: import("@deepseek-ai/schemastery").default<string, string>;
-        readonly: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        passwordRef?: string | null | undefined;
+        password?: null | undefined;
+    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+        type: z<"mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala", "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala">;
+        host: z<string, string>;
+        port: z<number, number>;
+        user: z<string, string>;
+        database: z<string, string>;
+        readonly: z<boolean, boolean>;
+        passwordRef: z<string, string>;
+        password: z<never, never>;
     }>, string>>;
 }>>;
 /**
@@ -137,17 +165,35 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
 export declare function resolveDshHome(env?: Record<string, string | undefined>): string;
 /**
  * Install the packaged `preset/data-agent/` directory into
- * `$DSH_HOME/.agent-presets/<presetId>/`. Idempotent: an existing target
- * directory is left untouched (user edits survive); `installPreset: false`
- * never calls this. Best-effort — a failure logs a warning with manual
- * install instructions instead of failing the boot.
+ * `$DSH_HOME/.agent-presets/<presetId>/`. Idempotent: an existing target is
+ * normally left untouched. The exact package-owned 0.0.9 composition is
+ * migrated once because its two dynamic package rows are incompatible with
+ * DSH Desktop's unpacked-ASAR loader; user-edited compositions are never
+ * overwritten. `installPreset: false` never calls this. Best-effort — a
+ * failure logs a warning with manual install instructions instead of failing
+ * the boot.
+ */
+export declare function installPreset(ctx: Context, presetId: string): Promise<boolean>;
+/** Public for regression tests of the non-destructive preset migration gate. */
+export declare function isLegacyManagedPreset(source: string): boolean;
+/** Exact profile-local package installation command used by diagnostics/docs. */
+export declare function profileInstallCommand(profile: string): string;
+/** Actionable diagnostic for a roster-visible preset whose profile lacks this package. */
+export declare function missingProfileDependencyMessage(profile: string): string;
+/** Tool configuration inherited by the profile-preloaded preset capabilities. */
+type PresetCapabilitiesConfig = Pick<ToolConfig, 'queryTimeoutMs' | 'maxResultChars' | 'maxRows' | 'maxQueryChars' | 'readonly' | 'clients'>;
+/**
+ * Register the statically imported database tools and command under the exact
+ * standing key owned by the data-agent preset. Selecting the preset performs
+ * no package import and only links the agent scope to this key.
  */
-export declare function installPreset(ctx: Context, presetId: string): Promise<void>;
+export declare function mountPresetCapabilities(ctx: Context, key: ScopeKey, scopeTag: symbol, config: PresetCapabilitiesConfig): Promise<void>;
 /**
- * Mount the data-agent host row: connection store, config-seeded
- * connections, and preset self-install. HTTP routes are the sibling
- * `data-agent-routes` row (`./routes`).
+ * Mount the data-agent profile row: connection store, config-seeded
+ * connections, preset installation, and profile-preloaded preset capabilities.
+ * HTTP routes are the sibling `data-agent-routes` row (`./routes`).
  * @param ctx - host cordis context.
  * @param config - validated loader configuration.
  */
-export declare function apply(ctx: Context, config: Config): void;
+export declare function apply(ctx: Context, config: Config): Promise<void>;
+export {};

package/lib/types/routes.d.ts

@@ -1,112 +1,46 @@
 /**
- * Data Agent routes half (`@yejiming/dsh-data-agent/routes`): the
- * `/plugins/data-agent` HTTP surface. A separate row from the main `data-agent`
- * row so the plugin keeps working in headless profiles (no webserver): the
- * connection store, preset self-install, and config-seeded connections all
- * live on the main row, and this row simply never activates where
- * `webServer` is absent.
+ * Web adapter for the shared data-agent connection service.
  *
- * Routes:
- * - `POST /plugins/data-agent/connect`    — validate and store one session's
- *   database connection, verify connectivity by listing all tables, and
- *   return `{ ok, tables }` (or `{ ok: false, error }` without saving).
- * - `POST /plugins/data-agent/disconnect` — drop one session's connection.
- * - `GET  /plugins/data-agent/status`     — the current connection's
- *   password-stripped summary plus the table list.
- * - `GET  /plugins/data-agent/schemas`    — schema/database list.
- * - `GET  /plugins/data-agent/tables`     — table list of one schema.
- * - `GET  /plugins/data-agent/describe`   — column structure of one table.
- * - `POST /plugins/data-agent/query`      — run one SQL text (the workbench
- *   command box; non-agent channel, same trust as sqlcmd).
+ * This entry owns only HTTP parsing/serialization. Connection validation,
+ * credentials, persistence, metadata, query safety, and error semantics live
+ * in `DataAgentConnections`, which is also consumed by TUI commands/tools.
  * @module @yejiming/dsh-data-agent/routes
  */
-import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Context } from '@deepseek-ai/cordis';
-/**
- * Minimal face of the host webserver service used by this row.
- * The service was renamed from `httpServer` to `webServer` in
- * dsh 0.1.0-rc.6; the nested inject below waits on `webServer`.
- */
-interface WebServerLike {
-    register(route: {
-        kind: 'exact' | 'prefix';
-        path: string;
-        handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
-    }): () => void;
-}
-declare module '@deepseek-ai/cordis' {
-    interface Context {
-        webServer: WebServerLike;
-    }
-}
-import type { DatabaseType } from './connections.ts';
-/** Cordis plugin name (diagnostics only). */
+import z from 'schemastery';
+import type { DatabaseConnectionInput } from './connections.ts';
 export declare const name = "data-agent-routes";
-/**
- * No top-level `inject` export: the row must ACTIVATE even in headless
- * profiles where `webServer` never exists (a permanently pending entry
- * breaks one-shot runs). The routes register through a nested inject fiber
- * the moment the webserver and the connection store are both available.
- */
+/** Headless profiles activate this row without waiting forever for webServer. */
 export declare const inject: string[];
-/** Route prefix owned by this plugin (the browser half calls under it). */
 export declare const DATA_AGENT_PATH = "/plugins/data-agent";
-/** Routes-half configuration (defaults mirror the main row). */
+/** Retained loader surface for backward compatibility; domain options live on the host row. */
 export interface Config {
-    /** Deadline for one /connect connectivity check, milliseconds. */
     connectTimeoutMs: number;
-    /** Cap on metadata lists returned by /connect /status /schemas /tables. */
     introspectMaxTables: number;
-    /** In-memory cap on captured output. */
     maxResultChars: number;
-    /** Deadline for one /query or metadata query, milliseconds. */
     queryTimeoutMs: number;
-    /** Cap on one /query SQL text length. */
     maxQueryChars: number;
-    /** Read-only guard: true rejects write statements in /query. */
     readonly: boolean;
 }
-/** Loader schema with deployment defaults (no library defaults). */
-export declare const Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
-    connectTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
-    introspectMaxTables: import("@deepseek-ai/schemastery").default<number, number>;
-    maxResultChars: import("@deepseek-ai/schemastery").default<number, number>;
-    queryTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
-    maxQueryChars: import("@deepseek-ai/schemastery").default<number, number>;
-    readonly: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+export declare const Config: z<Schemastery.ObjectS<{
+    connectTimeoutMs: z<number, number>;
+    introspectMaxTables: z<number, number>;
+    maxResultChars: z<number, number>;
+    queryTimeoutMs: z<number, number>;
+    maxQueryChars: z<number, number>;
+    readonly: z<boolean, boolean>;
 }>, Schemastery.ObjectT<{
-    connectTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
-    introspectMaxTables: import("@deepseek-ai/schemastery").default<number, number>;
-    maxResultChars: import("@deepseek-ai/schemastery").default<number, number>;
-    queryTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
-    maxQueryChars: import("@deepseek-ai/schemastery").default<number, number>;
-    readonly: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+    connectTimeoutMs: z<number, number>;
+    introspectMaxTables: z<number, number>;
+    maxResultChars: z<number, number>;
+    queryTimeoutMs: z<number, number>;
+    maxQueryChars: z<number, number>;
+    readonly: z<boolean, boolean>;
 }>>;
-/** The connection request wire body (validated in the /connect handler). */
-export interface ConnectRequestBody {
+export interface ConnectRequestBody extends DatabaseConnectionInput {
     sessionId: string;
-    type: DatabaseType;
-    host?: string;
-    port?: number;
-    user?: string;
-    database: string;
-    password?: string;
-    readonly?: boolean;
 }
-/**
- * Validate an untrusted /connect body; sqlite paths resolve to absolute
- * (the client resolves the path relative to its own cwd, so the server pins
- * it at connect time). Oracle/Hive/Impala follow the mysql/postgres shape:
- * host/port/user/database (Oracle database = service name/SID, Hive/Impala
- * database = default schema).
- */
+/** Validate the Web wire shape while retaining temporary-password compatibility. */
 export declare function validateConnectBody(value: unknown, cwd?: string): ConnectRequestBody;
-/**
- * Mount the data-agent routes against the host webserver, when one exists.
- * The registration rides a nested inject fiber so this row activates in every
- * profile; headless profiles simply never get routes.
- * @param ctx - host cordis context.
- * @param config - validated loader configuration.
- */
-export declare function apply(ctx: Context, config: Config): void;
-export {};
+/** Register Web routes only when both the webserver and shared service exist. */
+export declare function apply(ctx: Context, _config: Config): void;

package/lib/types/sql.d.ts

@@ -1,5 +1,5 @@
 /**
- * Lightweight SQL-text scanning helpers shared by the sqlcmd tool half and
+ * Lightweight SQL-text scanning helpers shared by the sql-cmd tool half and
  * the /query route. This is intentionally NOT a SQL parser: the scanner only
  * understands lexical boundaries (strings, quoted identifiers, comments and
  * parenthesis depth) well enough to make the two agent-loop guarantees from

package/lib/types/storage.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Durable, non-secret connection profiles, session bindings, and form drafts.
+ *
+ * The domain intentionally excludes passwords, resolved credentials, SQL,
+ * table metadata, and client output. Form drafts likewise accept no secret
+ * fields. Runtime secrets stay in
+ * {@link DataAgentConnectionService}; durable records only retain enough
+ * information to rebuild a connection description in another DSH surface.
+ * @module @yejiming/dsh-data-agent/storage
+ */
+import { type Domain } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+import type { ConnectionPersistence, PersistedConnectionFormDraft, PersistedConnectionProfile, SessionConnectionBinding } from './connections.ts';
+/** Storage-domain identity. Bump the version only with an explicit migration. */
+export declare const CONNECTION_STORAGE_DOMAIN = "data_agent_connections";
+export declare const CONNECTION_STORAGE_VERSION = 1;
+/** Durable profile schema. There is deliberately no `password` field. */
+export declare const persistedConnectionProfileSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<{
+        mysql: "mysql";
+        postgres: "postgres";
+        sqlite: "sqlite";
+        oracle: "oracle";
+        hive: "hive";
+        impala: "impala";
+    }>;
+    host: z.ZodOptional<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    user: z.ZodOptional<z.ZodString>;
+    database: z.ZodString;
+    readonly: z.ZodOptional<z.ZodBoolean>;
+    passwordRef: z.ZodOptional<z.ZodString>;
+    updatedAt: z.ZodString;
+}, z.core.$strict>;
+/** Durable session-to-profile binding schema. */
+export declare const sessionConnectionBindingSchema: z.ZodObject<{
+    profileId: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strict>;
+/** Session form draft schema. Secret-shaped fields are rejected by strict mode. */
+export declare const persistedConnectionFormDraftSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        mysql: "mysql";
+        postgres: "postgres";
+        sqlite: "sqlite";
+        oracle: "oracle";
+        hive: "hive";
+        impala: "impala";
+    }>;
+    host: z.ZodString;
+    port: z.ZodString;
+    user: z.ZodString;
+    database: z.ZodString;
+    readonly: z.ZodBoolean;
+    updatedAt: z.ZodString;
+}, z.core.$strict>;
+/** Single source of truth for the storage layout and durable validation. */
+export declare const connectionStorageSpec: {
+    name: string;
+    version: number;
+    tables: {
+        profiles: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, PersistedConnectionProfile>;
+        bindings: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, SessionConnectionBinding>;
+        drafts: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, PersistedConnectionFormDraft>;
+    };
+};
+export type ConnectionStorageDomain = Domain<typeof connectionStorageSpec>;
+/** Project a typed DSH domain handle onto the service's persistence seam. */
+export declare function createDomainConnectionPersistence(domain: ConnectionStorageDomain): ConnectionPersistence;

package/lib/types/structured-read.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared structured read-query execution extracted from the sql-query tool
+ * (task 2.1). Both sql-query and render-analysis run every read dataset
+ * through this helper, so connection resolution, single-statement assertion,
+ * read classification, LIMIT/maxRows enforcement, client execution, secret
+ * redaction, timeout/cancellation, non-zero-exit surfacing and structured
+ * parsing share one code path. Existing sql-query behavior and messages stay
+ * unchanged.
+ * @module @yejiming/dsh-data-agent/structured-read
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ClientConfig } from './clients.ts';
+import { type DatabaseConnection } from './connections.ts';
+import { type QueryOptions, type QueryResult } from './query.ts';
+/** Tool-run context face used by the helpers. */
+export interface ToolExecLike {
+    agent?: {
+        id: string;
+    };
+    signal: AbortSignal;
+}
+/** Resolved runner options shared by the database tools. */
+export interface ResolvedRunnerConfig {
+    queryTimeoutMs: number;
+    maxResultChars: number;
+    maxRows: number;
+    maxQueryChars: number;
+    /** Read-only guard: true rejects write statements. */
+    readonly: boolean;
+    clients: Readonly<Partial<Record<string, ClientConfig>>>;
+}
+/** Canonical structured read result (elapsed/truncation metadata included). */
+export interface StructuredReadResult {
+    columns: string[];
+    rows: Record<string, string | null>[];
+    elapsedMs: number;
+    truncated: boolean;
+}
+/** Look up the session connection, failing with the same message for every tool. */
+export declare function requireToolConnection(ctx: Context, exec: ToolExecLike, toolName: string): Promise<DatabaseConnection>;
+/** Run and redact a client result/error before it reaches tool/session output. */
+export declare function runRedactedClientQuery(ctx: Context, connection: DatabaseConnection, sql: string, options: QueryOptions, signal: AbortSignal): Promise<QueryResult>;
+/** Query runner options with the deployment overrides applied. */
+export declare function runnerOptions(resolved: Pick<ResolvedRunnerConfig, 'queryTimeoutMs' | 'maxResultChars' | 'clients'>, mode?: QueryOptions['mode']): QueryOptions;
+/**
+ * Execute one read-only SQL through the structured client template and parse
+ * it into the canonical { columns, rows } shape, with maxRows enforced at both
+ * the SQL level (LIMIT injection) and the parse level.
+ */
+export declare function runStructuredReadQuery(ctx: Context, connection: DatabaseConnection, sql: string, resolved: ResolvedRunnerConfig, toolName: string, signal: AbortSignal): Promise<StructuredReadResult>;

package/lib/types/tool.d.ts

@@ -8,7 +8,7 @@
  * Tool surface:
  * - `sql-query`: read-only statements, structured `{ columns, rows, ... }`;
  * - `sql-write`: one write/management statement per call, explicit autocommit;
- * - `sqlcmd`: the original raw-terminal tool (kept for compatibility).
+ * - `sql-cmd`: the raw-terminal compatibility tool.
  *
  * Execution model (see `src/query.ts`): the SQL text travels on the client's
  * stdin, argv carries flags only, credentials go through environment entries
@@ -18,6 +18,7 @@
  * @module @yejiming/dsh-data-agent/tool
  */
 import type { Context } from '@deepseek-ai/cordis';
+import z from 'schemastery';
 import { type ClientConfig } from './clients.ts';
 /** Cordis plugin name (diagnostics only). */
 export declare const name = "data-agent-tool";
@@ -25,46 +26,54 @@ export declare const name = "data-agent-tool";
 export declare const inject: string[];
 /** Tool-half configuration (loader schema with the same defaults as the host). */
 export interface Config {
-    /** Deadline for one sqlcmd / sql-query / sql-write query, milliseconds. */
+    /** Deadline for one sql-cmd / sql-query / sql-write query, milliseconds. */
     queryTimeoutMs: number;
     /** In-memory cap on captured output. */
     maxResultChars: number;
     /** Enforced read-query row cap (LIMIT injection + structured truncation). */
     maxRows: number;
+    /** Maximum SQL text length accepted per dataset statement. */
+    maxQueryChars: number;
     /** Read-only guard: true rejects write statements. */
     readonly: boolean;
     /** CLI client overrides keyed by database type. */
     clients: Partial<Record<string, ClientConfig>>;
 }
 /** Loader schema with deployment defaults (no library defaults). */
-export declare const Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
-    queryTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
-    maxResultChars: import("@deepseek-ai/schemastery").default<number, number>;
-    maxRows: import("@deepseek-ai/schemastery").default<number, number>;
-    readonly: import("@deepseek-ai/schemastery").default<boolean, boolean>;
-    clients: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/cosmokit").Dict<{
+export declare const Config: z<Schemastery.ObjectS<{
+    queryTimeoutMs: z<number, number>;
+    maxResultChars: z<number, number>;
+    maxRows: z<number, number>;
+    maxQueryChars: z<number, number>;
+    readonly: z<boolean, boolean>;
+    clients: z<import("cosmokit").Dict<{
         command?: string | null | undefined;
         args?: string[] | null | undefined;
-    } & import("cosmokit").Dict, string>, import("@deepseek-ai/cosmokit").Dict<Schemastery.ObjectT<{
-        command: import("@deepseek-ai/schemastery").default<string, string>;
-        args: import("@deepseek-ai/schemastery").default<string[], string[]>;
+        searchPaths?: string[] | null | undefined;
+    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+        command: z<string, string>;
+        args: z<string[], string[]>;
+        searchPaths: z<string[], string[]>;
     }>, string>>;
 }>, Schemastery.ObjectT<{
-    queryTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
-    maxResultChars: import("@deepseek-ai/schemastery").default<number, number>;
-    maxRows: import("@deepseek-ai/schemastery").default<number, number>;
-    readonly: import("@deepseek-ai/schemastery").default<boolean, boolean>;
-    clients: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/cosmokit").Dict<{
+    queryTimeoutMs: z<number, number>;
+    maxResultChars: z<number, number>;
+    maxRows: z<number, number>;
+    maxQueryChars: z<number, number>;
+    readonly: z<boolean, boolean>;
+    clients: z<import("cosmokit").Dict<{
         command?: string | null | undefined;
         args?: string[] | null | undefined;
-    } & import("cosmokit").Dict, string>, import("@deepseek-ai/cosmokit").Dict<Schemastery.ObjectT<{
-        command: import("@deepseek-ai/schemastery").default<string, string>;
-        args: import("@deepseek-ai/schemastery").default<string[], string[]>;
+        searchPaths?: string[] | null | undefined;
+    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+        command: z<string, string>;
+        args: z<string[], string[]>;
+        searchPaths: z<string[], string[]>;
     }>, string>>;
 }>>;
 /**
  * Mount the data-agent database tools: `sql-query` (structured read-only),
- * `sql-write` (explicit write semantics), and `sqlcmd` (raw compatibility).
+ * `sql-write` (explicit write semantics), and `sql-cmd` (raw compatibility).
  * @param ctx - the preset-scoped agent context.
  * @param config - validated loader configuration.
  */