@yejiming/dsh-data-agent 0.0.12 → 0.1.0

package/lib/types/command.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands';
-import { type ConnectionFormDraft, type ConnectionSummary, type DatabaseConnectionInput } from './connections.ts';
+import { type ConnectionFormDraft, type ConnectionFormInitial, type ConnectionSummary, type DatabaseConnectionInput } from './connections.ts';
 export declare const name = "data-agent-database-command";
 export declare const inject: string[];
 export declare const DATABASE_COMMAND_USAGE: string;
@@ -20,16 +20,27 @@ type DatabaseAction = {
 } | {
     kind: 'disconnect';
 };
-export declare const DATA_AGENT_TOOL_NAMES: readonly ["str_replace_editor", "sql-query", "sql-write", "sql-cmd"];
+export declare const DATA_AGENT_TOOL_NAMES: readonly ["str_replace_editor", "sql-query", "sql-write", "sql-cmd", "catalog-search", "catalog-get", "metric-get"];
 export interface DatabaseCommandInteraction {
     isTuiFormAvailable(): boolean;
     collectTuiConnection(signal: AbortSignal, options: {
-        initialDraft?: ConnectionFormDraft;
+        initialDraft?: ConnectionFormInitial;
         persistDraft(draft: ConnectionFormDraft): Promise<void>;
     }): Promise<DatabaseConnectionInput | undefined>;
 }
-/** Register the command in the calling preset/agent scope. */
-export declare function apply(ctx: Context): void;
+export interface DataAgentCommandAdapterOptions {
+    /** Override only for focused runtime-boundary tests. */
+    isDshTuiPluginLoaded?: (ctx: Context) => boolean;
+}
+/** Official Cordis runtime name exported by `@deepseek-harness-tui/dsh-tui`. */
+export declare const DSH_TUI_PLUGIN_RUNTIME_NAME = "dsh-tui";
+/**
+ * Detect actual plugin usage from Cordis' live registry. Package installation,
+ * argv and profile labels are deliberately irrelevant.
+ */
+export declare function isDshTuiPluginLoaded(ctx: Context): boolean;
+/** Keep the tool boundary everywhere; follow the actual dsh-tui runtime lifecycle for commands. */
+export declare function apply(ctx: Context, options?: DataAgentCommandAdapterOptions): void;
 /** Public for focused command tests and alternate command adapters. */
 export declare function executeDatabaseCommand(ctx: Context, invocation: CommandInvocation, interaction?: DatabaseCommandInteraction): Promise<CommandResult>;
 /** Parse one command's raw input without ever accepting a plaintext password. */

package/lib/types/connections.d.ts

@@ -9,11 +9,11 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { type ClientConfig, type ColumnInfo } from './clients.ts';
+import { type DatabaseType } from './database-types.ts';
 import { type QueryResult } from './query.ts';
+export type { DatabaseType } from './database-types.ts';
 /** Key of the wildcard connection applied to sessions without an exact entry. */
 export declare const WILDCARD_SESSION = "*";
-/** Supported database client kinds. */
-export type DatabaseType = 'mysql' | 'postgres' | 'sqlite' | 'oracle' | 'hive' | 'impala';
 /** How a non-SQLite profile authenticates without ever persisting a secret. */
 export type CredentialMode = 'none' | 'password' | 'reference';
 /** Safe credential facts returned to UI/command surfaces. */
@@ -33,6 +33,8 @@ export interface DatabaseConnectionInput {
     /** Non-secret DSH credential reference, mutually exclusive with password. */
     passwordRef?: string;
     readonly?: boolean;
+    /** ClickHouse HTTP transport uses HTTPS with normal certificate verification. */
+    secure?: boolean;
     /** Optional stable durable profile id. */
     profileId?: string;
     /** Optional human-readable profile label. */
@@ -53,6 +55,7 @@ export interface ConnectionSummary {
     database: string;
     passwordRef?: string;
     readonly?: boolean;
+    secure?: boolean;
     profileId?: string;
     name?: string;
     tables?: string[];
@@ -72,6 +75,7 @@ export interface PersistedConnectionProfile {
     user?: string;
     database: string;
     readonly?: boolean;
+    secure?: boolean;
     passwordRef?: string;
     credentialMode?: CredentialMode;
     updatedAt: string;
@@ -89,14 +93,27 @@ export interface ConnectionFormDraft {
     user: string;
     database: string;
     readonly: boolean;
+    secure?: boolean;
+}
+/** Form initial values may also restore one non-secret credential reference. */
+export interface ConnectionFormInitial extends ConnectionFormDraft {
+    passwordRef?: string;
 }
 /** Durable draft record. Passwords and credential references are forbidden. */
 export interface PersistedConnectionFormDraft extends ConnectionFormDraft {
     updatedAt: string;
 }
+/** Deterministic latest-profile lookup result supplied by durable adapters. */
+export interface PersistedConnectionProfileEntry {
+    profileId: string;
+    profile: PersistedConnectionProfile;
+}
 /** Minimal durable seam; backed by a DSH storage domain in production. */
 export interface ConnectionPersistence {
     getProfile(profileId: string): PersistedConnectionProfile | undefined;
+    getLatestProfile?(): PersistedConnectionProfileEntry | undefined;
+    /** Deterministic profile enumeration used only for exact, non-secret identity reuse. */
+    listProfiles?(): PersistedConnectionProfileEntry[];
     putProfile(profileId: string, profile: PersistedConnectionProfile): Promise<void>;
     deleteProfile(profileId: string): Promise<boolean>;
     getBinding(sessionId: string): SessionConnectionBinding | undefined;
@@ -104,22 +121,39 @@ export interface ConnectionPersistence {
     deleteBinding(sessionId: string): Promise<boolean>;
     getDraft?(sessionId: string): PersistedConnectionFormDraft | undefined;
     putDraft?(sessionId: string, draft: PersistedConnectionFormDraft): Promise<void>;
+    deleteDraft?(sessionId: string): Promise<boolean>;
 }
 /** Shared service configuration supplied by the host plugin. */
 export interface ConnectionServiceOptions {
     connectTimeoutMs: number;
     queryTimeoutMs: number;
+    catalogQueryTimeoutMs?: number;
+    /** Per-stream capture budget for package-owned system-catalog queries. */
+    catalogMaxResultChars?: number;
     maxResultChars: number;
     maxQueryChars?: number;
     introspectMaxTables: number;
     readonly: boolean;
     clients: Partial<Record<string, ClientConfig>>;
     cwd?: string;
+    /** Profile ids already used by durable downstream data, ordered by the owner. */
+    preferredProfileIds?: () => readonly string[];
 }
 export interface ConnectResult {
     tables: string[];
     summary: ConnectionSummary;
 }
+/** Structured read result or raw command message returned to interactive surfaces. */
+export type InteractiveQueryResult = {
+    kind: 'table';
+    columns: string[];
+    rows: Record<string, string | null>[];
+    elapsedMs: number;
+    truncated: boolean;
+    maxRows: number;
+} | ({
+    kind: 'message';
+} & QueryResult);
 /** Host-plane service (`ctx.dataAgentConnections`). */
 export interface DataAgentConnections {
     /** Compatibility setter for config seeds/tests; does not persist. */
@@ -131,8 +165,8 @@ export interface DataAgentConnections {
     has(sessionId: string): boolean;
     /** Compatibility runtime-only clear. Use disconnect() for durable bindings. */
     clear(sessionId: string): void;
-    /** Restore the latest non-secret interactive form values for this session. */
-    getFormDraft(sessionId: string): ConnectionFormDraft | undefined;
+    /** Restore exact or latest-profile non-secret interactive form values. */
+    getFormDraft(sessionId: string): ConnectionFormInitial | undefined;
     /** Save non-secret form values; the implementation never accepts a password. */
     saveFormDraft(sessionId: string, draft: ConnectionFormDraft): Promise<void>;
     status(sessionId: string): Promise<ConnectionSummary | undefined>;
@@ -140,10 +174,13 @@ export interface DataAgentConnections {
     disconnect(sessionId: string): Promise<void>;
     test(sessionId: string, signal: AbortSignal): Promise<ConnectResult>;
     resolveForExecution(sessionId: string): Promise<DatabaseConnection>;
+    /** Execute one package-owned, read-only system-catalog statement. Not exposed as a model tool. */
+    queryMetadata(sessionId: string, sql: string, signal: AbortSignal): Promise<QueryResult>;
     listSchemas(sessionId: string, signal: AbortSignal): Promise<string[]>;
     listTables(sessionId: string, schema: string | undefined, signal: AbortSignal): Promise<string[]>;
     describe(sessionId: string, schema: string | undefined, table: string, signal: AbortSignal): Promise<ColumnInfo[]>;
     query(sessionId: string, sql: string, signal: AbortSignal): Promise<QueryResult>;
+    executeInteractive(sessionId: string, sql: string, signal: AbortSignal): Promise<InteractiveQueryResult>;
 }
 /** Build a password-stripped copy of one connection. */
 export declare function summarize(connection: DatabaseConnection): ConnectionSummary;
@@ -157,3 +194,4 @@ export declare function normalizeConnectionInput(input: DatabaseConnectionInput,
 export declare function createConnectionService(ctx?: Context, options?: ConnectionServiceOptions, persistence?: ConnectionPersistence): DataAgentConnections;
 /** Backward-compatible in-memory store factory used by embedders/tests. */
 export declare function createConnectionStore(): DataAgentConnections;
+export declare function validatePasswordRef(value: string): void;

package/lib/types/database-types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser-safe database type descriptors shared by every DSH surface.
+ * Keep this module dependency-free: server-only client/process details belong
+ * in the database adapters, not in Web or persistence bundles.
+ */
+export declare const DATABASE_TYPES: readonly ["mysql", "postgres", "sqlite", "oracle", "hive", "impala", "clickhouse", "doris", "sqlserver"];
+export type DatabaseType = typeof DATABASE_TYPES[number];
+export interface DatabaseTypeDescriptor {
+    type: DatabaseType;
+    label: string;
+    localeKey: `type.${DatabaseType}`;
+    defaultPort: number;
+    defaultUser: string;
+    fileBased: boolean;
+    /** HTTPS port used when ClickHouse secure transport is selected. */
+    securePort?: number;
+}
+export declare const DATABASE_TYPE_DESCRIPTORS: Readonly<Record<DatabaseType, DatabaseTypeDescriptor>>;
+export declare function isDatabaseType(value: unknown): value is DatabaseType;
+export declare function databaseTypeDescriptor(type: DatabaseType): DatabaseTypeDescriptor;
+export declare function defaultDatabasePort(type: DatabaseType, secure?: boolean): number;
+export declare function defaultDatabaseUser(type: DatabaseType): string;
+export declare function databaseTypeLabel(type: DatabaseType): string;

package/lib/types/defaults.d.ts

@@ -16,7 +16,33 @@ export declare const DEFAULT_QUERY_TIMEOUT_MS = 30000;
 export declare const DEFAULT_MAX_RESULT_CHARS = 20000;
 /** Maximum structured rows returned by one database read tool call. */
 export declare const DEFAULT_MAX_ROWS = 100;
+/** Hard row cap for one structured Web workbench result/export. */
+export declare const WORKBENCH_MAX_EXPORT_ROWS = 50000;
+/** Bounded capture size for the larger structured Web workbench result. */
+export declare const WORKBENCH_MAX_RESULT_CHARS: number;
 /** Cap on one /query SQL text length (abuse guard; the wire body stays small). */
 export declare const DEFAULT_MAX_QUERY_CHARS = 65536;
 /** Grace period for the subprocess terminate escalation. */
 export declare const DEFAULT_GRACE_MS = 5000;
+/** Catalog metadata query deadline. Kept separate from user SQL execution. */
+export declare const DEFAULT_CATALOG_QUERY_TIMEOUT_MS = 30000;
+/**
+ * Per-stream capture budget for one system-catalog query. Catalog metadata is
+ * intentionally independent from the much smaller model/interactive SQL
+ * result budget because a schema snapshot can contain thousands of objects.
+ */
+export declare const DEFAULT_CATALOG_MAX_RESULT_CHARS: number;
+/** Maximum schemas inspected concurrently by one Catalog scan. */
+export declare const DEFAULT_CATALOG_SCHEMA_CONCURRENCY = 2;
+/** Maximum tables/views inspected concurrently by one Catalog scan. */
+export declare const DEFAULT_CATALOG_ASSET_CONCURRENCY = 4;
+/** Hard bound on technical assets (including columns) staged by one run. */
+export declare const DEFAULT_CATALOG_MAX_ASSETS = 50000;
+/** Maximum normalized length of one database or human-authored text field. */
+export declare const DEFAULT_CATALOG_MAX_TEXT_CHARS = 4096;
+/** Default and maximum page sizes for Catalog list/detail reads. */
+export declare const DEFAULT_CATALOG_PAGE_SIZE = 50;
+export declare const MAX_CATALOG_PAGE_SIZE = 200;
+/** Default and maximum result counts exposed to the model. */
+export declare const DEFAULT_CATALOG_TOOL_TOP_K = 10;
+export declare const MAX_CATALOG_TOOL_TOP_K = 25;

package/lib/types/ecosystem.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Community v0.15 host facet.
+ *
+ * This facet intentionally publishes no commands, tools, UI, routes, storage,
+ * credentials, or database effects. The existing Cordis bundle remains the
+ * sole functional runtime so hosts may discover the ecosystem declaration
+ * without double-registering data-agent behavior.
+ */
+import { type FacetProjection } from '@dsh-std/sdk';
+/** Stable degraded snapshot for declaration-only ecosystem discovery. */
+export declare const ECOSYSTEM_SNAPSHOT: FacetProjection;
+declare const ecosystemFacet: import("@dsh-std/sdk").FacetModule;
+export default ecosystemFacet;

package/lib/types/index.d.ts

@@ -2,9 +2,10 @@
  * 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
+ * wildcard default), provides a separate versioned governance Catalog, 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.
+ * on every surface, while registering `/database` and `/catalog` only while
+ * the current Cordis composition actually loads the dsh-tui plugin.
  *
  * The HTTP routes live in the separate `./routes` entry
  * (`@yejiming/dsh-data-agent/routes`, cordis row `data-agent-routes`) so
@@ -21,18 +22,25 @@ import type { ScopeKey } from '@deepseek-ai/dsh-scope';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         dataAgentConnections: DataAgentConnections;
+        dataAgentCatalog: DataAgentCatalog;
+        dataAgentCatalogScanner: DataAgentCatalogScanner;
+        dataAgentCatalogReview: DataAgentCatalogReview;
     }
 }
 import z from 'schemastery';
 import { type DataAgentConnections, type DatabaseType } from './connections.ts';
-import { type ClientConfig } from './clients.ts';
+import { type CliDatabaseType, type ClientConfig } from './clients.ts';
+import { type DataAgentCatalog, type DataAgentCatalogReview, type DataAgentCatalogScanner } from './catalog.ts';
+import { type DataAgentCommandAdapterOptions } from './command.ts';
 import { type Config as ToolConfig } from './tool.ts';
+export type { CatalogServiceBundle, CatalogServiceOptions, CatalogStatusSummary, DataAgentCatalog, DataAgentCatalogReview, DataAgentCatalogScanner, StartCatalogScanInput, } from './catalog.ts';
+export type { CatalogAssetDetail, CatalogAssetHead, CatalogAssetKind, CatalogAssetRevision, CatalogAssetStatus, CatalogCapability, CatalogDiffItem, CatalogDiffKind, CatalogDiffPage, CatalogEnrichment, CatalogEnrichmentStatus, CatalogIdentity, CatalogObservation, CatalogProgress, CatalogRelation, CatalogRun, CatalogRunStatus, CatalogScope, CatalogSearchFilters, CatalogSearchItem, CatalogSearchPage, CatalogSearchRequest, CatalogSemanticEntry, CatalogSemanticKind, CatalogSemanticRevision, CatalogSemanticStatus, CatalogSource, CatalogTechnicalPayload, MetricDefinition, MeaningDefinition, SemanticDefinition, TermDefinition, } from './catalog-types.ts';
 /** Cordis plugin name (diagnostics only). */
 export declare const name = "data-agent";
 /** 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 type ClientsConfig = Partial<Record<DatabaseType, ClientConfig>>;
+export type ClientsConfig = Partial<Record<CliDatabaseType, ClientConfig>>;
 /**
  * One config-seeded connection. Deliberately password-free: passwords are a
  * memory-only / connect-time value, so only the /connect route may carry one.
@@ -47,6 +55,8 @@ export interface SeededConnectionConfig {
     database: string;
     /** Optional per-seed read-only guard. */
     readonly?: boolean;
+    /** ClickHouse only: use HTTPS with certificate verification. */
+    secure?: boolean;
     /** Safe credential reference. Real passwords are rejected by the schema. */
     passwordRef?: string;
     password?: never;
@@ -63,6 +73,20 @@ export interface Config {
     introspectMaxTables: number;
     /** Deadline for one database-tool query, milliseconds. */
     queryTimeoutMs: number;
+    /** Deadline for one package-owned system-catalog metadata query. */
+    catalogQueryTimeoutMs: number;
+    /** Per-stream capture budget for one package-owned system-catalog query. */
+    catalogMaxResultChars: number;
+    /** Maximum schemas and table/view details processed concurrently. */
+    catalogSchemaConcurrency: number;
+    catalogAssetConcurrency: number;
+    /** Hard technical asset bound for one scan. */
+    catalogMaxAssetsPerRun: number;
+    /** Maximum normalized database/human text field length. */
+    catalogMaxTextChars: number;
+    /** Default and maximum Catalog list/detail page sizes. */
+    catalogPageSize: number;
+    catalogMaxPageSize: number;
     /** In-memory cap on database-tool captured output. */
     maxResultChars: number;
     /** Maximum structured rows returned by one database read tool call. */
@@ -85,6 +109,14 @@ export declare const Config: z<Schemastery.ObjectS<{
     connectTimeoutMs: z<number, number>;
     introspectMaxTables: z<number, number>;
     queryTimeoutMs: z<number, number>;
+    catalogQueryTimeoutMs: z<number, number>;
+    catalogMaxResultChars: z<number, number>;
+    catalogSchemaConcurrency: z<number, number>;
+    catalogAssetConcurrency: z<number, number>;
+    catalogMaxAssetsPerRun: z<number, number>;
+    catalogMaxTextChars: z<number, number>;
+    catalogPageSize: z<number, number>;
+    catalogMaxPageSize: z<number, number>;
     maxResultChars: z<number, number>;
     maxRows: z<number, number>;
     maxQueryChars: z<number, number>;
@@ -94,27 +126,29 @@ export declare const Config: z<Schemastery.ObjectS<{
         command?: string | null | undefined;
         args?: string[] | null | undefined;
         searchPaths?: string[] | null | undefined;
-    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+    } & import("@deepseek-ai/cosmokit").Dict, "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "doris" | "sqlserver">, import("cosmokit").Dict<Schemastery.ObjectT<{
         command: z<string, string>;
         args: z<string[], string[]>;
         searchPaths: z<string[], string[]>;
-    }>, string>>;
+    }>, "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "doris" | "sqlserver">>;
     connections: z<import("cosmokit").Dict<{
-        type?: "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | null | undefined;
+        type?: "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "clickhouse" | "doris" | "sqlserver" | null | undefined;
         host?: string | null | undefined;
         port?: number | null | undefined;
         user?: string | null | undefined;
         database?: string | null | undefined;
         readonly?: boolean | null | undefined;
+        secure?: boolean | null | undefined;
         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">;
+        type: z<"mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "clickhouse" | "doris" | "sqlserver", "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "clickhouse" | "doris" | "sqlserver">;
         host: z<string, string>;
         port: z<number, number>;
         user: z<string, string>;
         database: z<string, string>;
         readonly: z<boolean, boolean>;
+        secure: z<boolean, boolean>;
         passwordRef: z<string, string>;
         password: z<never, never>;
     }>, string>>;
@@ -124,6 +158,14 @@ export declare const Config: z<Schemastery.ObjectS<{
     connectTimeoutMs: z<number, number>;
     introspectMaxTables: z<number, number>;
     queryTimeoutMs: z<number, number>;
+    catalogQueryTimeoutMs: z<number, number>;
+    catalogMaxResultChars: z<number, number>;
+    catalogSchemaConcurrency: z<number, number>;
+    catalogAssetConcurrency: z<number, number>;
+    catalogMaxAssetsPerRun: z<number, number>;
+    catalogMaxTextChars: z<number, number>;
+    catalogPageSize: z<number, number>;
+    catalogMaxPageSize: z<number, number>;
     maxResultChars: z<number, number>;
     maxRows: z<number, number>;
     maxQueryChars: z<number, number>;
@@ -133,27 +175,29 @@ export declare const Config: z<Schemastery.ObjectS<{
         command?: string | null | undefined;
         args?: string[] | null | undefined;
         searchPaths?: string[] | null | undefined;
-    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+    } & import("@deepseek-ai/cosmokit").Dict, "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "doris" | "sqlserver">, import("cosmokit").Dict<Schemastery.ObjectT<{
         command: z<string, string>;
         args: z<string[], string[]>;
         searchPaths: z<string[], string[]>;
-    }>, string>>;
+    }>, "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "doris" | "sqlserver">>;
     connections: z<import("cosmokit").Dict<{
-        type?: "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | null | undefined;
+        type?: "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "clickhouse" | "doris" | "sqlserver" | null | undefined;
         host?: string | null | undefined;
         port?: number | null | undefined;
         user?: string | null | undefined;
         database?: string | null | undefined;
         readonly?: boolean | null | undefined;
+        secure?: boolean | null | undefined;
         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">;
+        type: z<"mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "clickhouse" | "doris" | "sqlserver", "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "clickhouse" | "doris" | "sqlserver">;
         host: z<string, string>;
         port: z<number, number>;
         user: z<string, string>;
         database: z<string, string>;
         readonly: z<boolean, boolean>;
+        secure: z<boolean, boolean>;
         passwordRef: z<string, string>;
         password: z<never, never>;
     }>, string>>;
@@ -182,11 +226,11 @@ 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
+ * Register the statically imported database tools and surface adapters 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 mountPresetCapabilities(ctx: Context, key: ScopeKey, scopeTag: symbol, config: PresetCapabilitiesConfig): Promise<void>;
+export declare function mountPresetCapabilities(ctx: Context, key: ScopeKey, scopeTag: symbol, config: PresetCapabilitiesConfig, commandOptions?: DataAgentCommandAdapterOptions): Promise<void>;
 /**
  * Mount the data-agent profile row: connection store, config-seeded
  * connections, preset installation, and profile-preloaded preset capabilities.
@@ -195,4 +239,3 @@ export declare function mountPresetCapabilities(ctx: Context, key: ScopeKey, sco
  * @param config - validated loader configuration.
  */
 export declare function apply(ctx: Context, config: Config): Promise<void>;
-export {};

package/lib/types/query.d.ts

@@ -1,10 +1,10 @@
 /**
- * The shared client-process runner used by both halves: the /connect
- * connectivity check (server half) and the database tools (tool half). All
- * execution goes through `ctx.subprocess` — no shell layer, argv arrays only,
- * SQL on stdin, credentials in env entries — with a caller-owned timeout
- * (AbortController → process-tree terminate escalation) and bounded captured
- * output.
+ * The shared database runner used by both halves: the /connect connectivity
+ * check (server half) and the database tools (tool half). CLI-backed adapters
+ * go through `ctx.subprocess` with argv arrays, SQL on stdin, and credentials
+ * in their dedicated environment/stdin channel. ClickHouse uses the official
+ * Node HTTP client with explicit transport/authentication fields. Both paths
+ * share caller-owned cancellation, deadlines, and bounded captured output.
  * @module @yejiming/dsh-data-agent/query
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -26,11 +26,11 @@ export interface QueryResult {
     /** True when either stream hit the maxResultChars cap. */
     truncated: boolean;
 }
-/** Which CLI flag set to use for one run. */
+/** Which deterministic raw/introspection/structured output mode to use. */
 export type QueryTemplateMode = 'query' | 'introspect' | 'structured';
 /** Runner options: client overrides, deadlines, output caps. */
 export interface QueryOptions {
-    /** Deployment client overrides keyed by database type. */
+    /** Deployment CLI overrides keyed by CLI-backed database type. */
     clients: Readonly<Partial<Record<DatabaseType, ClientConfig>>>;
     /** End-to-end deadline in milliseconds (timeout → terminate the tree). */
     timeoutMs: number;
@@ -41,10 +41,12 @@ export interface QueryOptions {
     /** CLI flag set; overrides the legacy `introspect` parameter when set. */
     mode?: QueryTemplateMode;
 }
+/** ClickHouse endpoint construction never embeds username or password. */
+export declare function clickHouseConnectionUrl(connection: DatabaseConnection): string;
 /**
- * Run one SQL text through the type's CLI client. The SQL is written to the
- * child's stdin (`{ data }` batch disposition) so it never appears in argv;
- * passwords travel in the env entries built by the template.
+ * Run one SQL text through the type's shared adapter. CLI SQL is written to
+ * child stdin (`{ data }` batch disposition), while ClickHouse SQL is an HTTP
+ * request body; neither path puts SQL or credentials in argv.
  *
  * Failure classification:
  * - the caller's external signal (e.g. the tool exec signal) aborts → the

package/lib/types/sql.d.ts

@@ -6,7 +6,7 @@
  * docs/optimization-opportunities.md:
  *
  * - a single tool call carries at most ONE SQL statement;
- * - `maxRows` can be enforced with a real top-level LIMIT, not just a prompt.
+ * - `maxRows` can be enforced with a real dialect-level row bound, not just a prompt.
  *
  * @module @yejiming/dsh-data-agent/sql
  */
@@ -18,6 +18,14 @@
 export declare function assertSingleStatement(sql: string, label?: string): void;
 /** Whether `keyword` appears at top level as a whole word in `sql`. */
 export declare function hasTopLevelKeyword(sql: string, keyword: string): boolean;
+/**
+ * Preserve executable SQL text while replacing strings, quoted identifiers,
+ * dollar/Oracle quoted bodies, and comments with spaces. Newlines are kept so
+ * line-oriented client directives can be checked without false positives.
+ */
+export declare function maskSqlLiteralsAndComments(sql: string): string;
+/** Reject commands interpreted by sqlcmd itself rather than by SQL Server. */
+export declare function assertSqlServerSafeInput(sql: string, label?: string): void;
 /**
  * Strip trailing whitespace, statement terminators and trailing comments so a
  * limit clause can be appended to the actual statement text. Only comments

package/lib/types/storage.d.ts

@@ -10,7 +10,7 @@
  */
 import { type Domain } from '@deepseek-ai/dsh-storage-domain';
 import { z } from 'zod';
-import type { ConnectionPersistence, PersistedConnectionFormDraft, PersistedConnectionProfile, SessionConnectionBinding } from './connections.ts';
+import type { ConnectionPersistence, PersistedConnectionFormDraft, PersistedConnectionProfile, PersistedConnectionProfileEntry, 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;
@@ -24,12 +24,16 @@ export declare const persistedConnectionProfileSchema: z.ZodObject<{
         oracle: "oracle";
         hive: "hive";
         impala: "impala";
+        clickhouse: "clickhouse";
+        doris: "doris";
+        sqlserver: "sqlserver";
     }>;
     host: z.ZodOptional<z.ZodString>;
     port: z.ZodOptional<z.ZodNumber>;
     user: z.ZodOptional<z.ZodString>;
     database: z.ZodString;
     readonly: z.ZodOptional<z.ZodBoolean>;
+    secure: z.ZodOptional<z.ZodBoolean>;
     passwordRef: z.ZodOptional<z.ZodString>;
     credentialMode: z.ZodOptional<z.ZodEnum<{
         none: "none";
@@ -52,12 +56,16 @@ export declare const persistedConnectionFormDraftSchema: z.ZodObject<{
         oracle: "oracle";
         hive: "hive";
         impala: "impala";
+        clickhouse: "clickhouse";
+        doris: "doris";
+        sqlserver: "sqlserver";
     }>;
     host: z.ZodString;
     port: z.ZodString;
     user: z.ZodString;
     database: z.ZodString;
     readonly: z.ZodBoolean;
+    secure: z.ZodOptional<z.ZodBoolean>;
     updatedAt: z.ZodString;
 }, z.core.$strict>;
 /** Single source of truth for the storage layout and durable validation. */
@@ -71,5 +79,7 @@ export declare const connectionStorageSpec: {
     };
 };
 export type ConnectionStorageDomain = Domain<typeof connectionStorageSpec>;
+/** Select the newest successful profile with a deterministic id tie-break. */
+export declare function latestConnectionProfile(entries: Iterable<readonly [string, PersistedConnectionProfile]>): PersistedConnectionProfileEntry | undefined;
 /** 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

@@ -2,7 +2,7 @@
  * 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
+ * read classification, dialect-aware 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.
@@ -45,6 +45,6 @@ export declare function runnerOptions(resolved: Pick<ResolvedRunnerConfig, 'quer
 /**
  * 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.
+ * the SQL level (dialect rewrite) 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/structured.d.ts

@@ -4,7 +4,7 @@
  * {@link buildStructuredQueryTemplate} in `src/clients.ts`); this module turns
  * that captured stdout into the canonical `{ columns, rows }` shape and
  * enforces the row cap a second time (first line of defense is the SQL-level
- * LIMIT injection, second is truncation while parsing).
+ * dialect-aware SQL rewriting, second is truncation while parsing).
  *
  * The parsers are deliberately output-shape based, not grammar based. Values
  * stay as strings because every client renders SQL values as text (NULL

package/lib/types/tool.d.ts

@@ -30,7 +30,7 @@ export interface Config {
     queryTimeoutMs: number;
     /** In-memory cap on captured output. */
     maxResultChars: number;
-    /** Enforced read-query row cap (LIMIT injection + structured truncation). */
+    /** Enforced read-query row cap (dialect rewrite + structured truncation). */
     maxRows: number;
     /** Maximum SQL text length accepted per dataset statement. */
     maxQueryChars: number;
@@ -50,11 +50,11 @@ export declare const Config: z<Schemastery.ObjectS<{
         command?: string | null | undefined;
         args?: string[] | null | undefined;
         searchPaths?: string[] | null | undefined;
-    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+    } & import("@deepseek-ai/cosmokit").Dict, "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "doris" | "sqlserver">, import("cosmokit").Dict<Schemastery.ObjectT<{
         command: z<string, string>;
         args: z<string[], string[]>;
         searchPaths: z<string[], string[]>;
-    }>, string>>;
+    }>, "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "doris" | "sqlserver">>;
 }>, Schemastery.ObjectT<{
     queryTimeoutMs: z<number, number>;
     maxResultChars: z<number, number>;
@@ -65,11 +65,11 @@ export declare const Config: z<Schemastery.ObjectS<{
         command?: string | null | undefined;
         args?: string[] | null | undefined;
         searchPaths?: string[] | null | undefined;
-    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+    } & import("@deepseek-ai/cosmokit").Dict, "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "doris" | "sqlserver">, import("cosmokit").Dict<Schemastery.ObjectT<{
         command: z<string, string>;
         args: z<string[], string[]>;
         searchPaths: z<string[], string[]>;
-    }>, string>>;
+    }>, "mysql" | "postgres" | "sqlite" | "oracle" | "hive" | "impala" | "doris" | "sqlserver">>;
 }>>;
 /**
  * Mount the data-agent database tools: `sql-query` (structured read-only),