@yejiming/dsh-data-agent 0.0.6 → 0.0.9

package/lib/types/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * 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`, `'*'` =
+ * `dataAgentConnections` service (shared non-secret profile/binding storage;
+ * temporary passwords stay process-local), 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).
@@ -20,6 +20,7 @@ declare module '@deepseek-ai/cordis' {
         dataAgentConnections: DataAgentConnections;
     }
 }
+import z from 'schemastery';
 import { type DataAgentConnections, type DatabaseType } from './connections.ts';
 import { type ClientConfig } from './clients.ts';
 /** Cordis plugin name (diagnostics only). */
@@ -27,11 +28,7 @@ export declare const name = "data-agent";
 /** Services required before the store can serve. */
 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 +43,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 +61,89 @@ export interface Config {
     queryTimeoutMs: number;
     /** In-memory cap on database-tool captured output. */
     maxResultChars: 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>;
+    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[]>;
+    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+        command: z<string, string>;
+        args: 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>;
+    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[]>;
+    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+        command: z<string, string>;
+        args: 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>>;
 }>>;
 /**
@@ -143,6 +159,10 @@ export declare function resolveDshHome(env?: Record<string, string | undefined>)
  * install instructions instead of failing the boot.
  */
 export declare function installPreset(ctx: Context, presetId: string): Promise<void>;
+/** 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;
 /**
  * Mount the data-agent host row: connection store, config-seeded
  * connections, and preset self-install. HTTP routes are the sibling
@@ -150,4 +170,4 @@ export declare function installPreset(ctx: Context, presetId: string): Promise<v
  * @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>;

package/lib/types/routes.d.ts

@@ -1,32 +1,15 @@
 /**
- * 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`.
- */
+import z from 'schemastery';
+import type { DatabaseConnectionInput } from './connections.ts';
 interface WebServerLike {
     register(route: {
         kind: 'exact' | 'prefix';
@@ -39,74 +22,39 @@ declare module '@deepseek-ai/cordis' {
         webServer: WebServerLike;
     }
 }
-import type { DatabaseType } from './connections.ts';
-/** Cordis plugin name (diagnostics only). */
 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;
+/** Register Web routes only when both the webserver and shared service exist. */
+export declare function apply(ctx: Context, _config: Config): void;
 export {};

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,50 @@ 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[]>;
+    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+        command: z<string, string>;
+        args: 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[]>;
+    } & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+        command: z<string, string>;
+        args: 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.
  */

package/lib/types/tui-connection-form.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Short-lived ANSI connection form used by `/database connect` in dsh-tui.
+ *
+ * dsh-tui 0.6.x exposes commands but no public custom-form/sensitive-input
+ * slot. This adapter therefore owns a small terminal form and only activates
+ * for an interactive `dsh-tui` profile. It snapshots the host's `readable`
+ * listeners, consumes input for the lifetime of the form, then restores the
+ * listeners exactly. It never imports dsh-tui, React, or Ink.
+ * @module @yejiming/dsh-data-agent/tui-connection-form
+ */
+import type { ConnectionFormDraft, DatabaseConnectionInput, DatabaseType } from './connections.ts';
+export declare const TUI_DATABASE_TYPES: readonly ["mysql", "postgres", "sqlite", "oracle", "hive", "impala"];
+export type TuiConnectionField = 'type' | 'host' | 'port' | 'user' | 'database' | 'password' | 'readonly' | 'confirm' | 'cancel';
+export interface TuiConnectionFormState {
+    type: DatabaseType;
+    host: string;
+    port: string;
+    user: string;
+    database: string;
+    password: string;
+    readonly: boolean;
+    focus: TuiConnectionField;
+    cursor: number;
+    selector?: {
+        field: 'type' | 'readonly';
+        index: number;
+    };
+    error?: string;
+}
+export type TuiFormKey = {
+    name: 'text';
+    text: string;
+} | {
+    name: 'tab' | 'backtab' | 'enter' | 'escape' | 'backspace' | 'delete';
+} | {
+    name: 'left' | 'right' | 'up' | 'down' | 'home' | 'end' | 'space';
+};
+export type TuiFormTransition = {
+    kind: 'editing';
+    state: TuiConnectionFormState;
+} | {
+    kind: 'submitted';
+    state: TuiConnectionFormState;
+    input: DatabaseConnectionInput;
+} | {
+    kind: 'cancelled';
+    state: TuiConnectionFormState;
+};
+type StreamListener = (...args: unknown[]) => void;
+export interface TuiFormInput {
+    isTTY?: boolean;
+    isRaw?: boolean;
+    read(): unknown;
+    listeners(event: string): Function[];
+    on(event: string, listener: StreamListener): unknown;
+    emit?(event: string): unknown;
+    push?(value: string): unknown;
+    removeListener(event: string, listener: StreamListener): unknown;
+    setRawMode?(mode: boolean): unknown;
+    ref?(): unknown;
+}
+export interface TuiFormOutput {
+    isTTY?: boolean;
+    columns?: number;
+    write(value: string): unknown;
+    on?(event: string, listener: StreamListener): unknown;
+    removeListener?(event: string, listener: StreamListener): unknown;
+    emit?(event: string): unknown;
+}
+export interface RunTuiConnectionFormOptions {
+    input?: TuiFormInput;
+    output?: TuiFormOutput;
+    signal?: AbortSignal;
+    initialDraft?: ConnectionFormDraft;
+    persistDraft?: (draft: ConnectionFormDraft) => void | Promise<void>;
+}
+/** Initial form intentionally leaves host/port empty so placeholders are real defaults. */
+export declare function createTuiConnectionFormState(initialDraft?: ConnectionFormDraft): TuiConnectionFormState;
+/** Project form state onto the only values allowed to cross the durable seam. */
+export declare function connectionFormDraft(state: TuiConnectionFormState): ConnectionFormDraft;
+/** Relevant focus order for the selected database kind. */
+export declare function tuiConnectionFields(type: DatabaseType): readonly TuiConnectionField[];
+/** Default network port shown as a placeholder and applied only at submit time. */
+export declare function defaultDatabasePort(type: Exclude<DatabaseType, 'sqlite'>): number;
+/** Detect the supported host without coupling to dsh-tui modules. */
+export declare function isDshTuiTerminal(argv?: readonly string[], input?: Pick<TuiFormInput, 'isTTY'>, output?: Pick<TuiFormOutput, 'isTTY'>): boolean;
+/** Pure keyboard reducer, kept separate from terminal ownership for regression tests. */
+export declare function updateTuiConnectionForm(current: TuiConnectionFormState, key: TuiFormKey): TuiFormTransition;
+/** Rendered value is masked before it reaches the ANSI string. */
+export declare function renderTuiConnectionForm(state: TuiConnectionFormState, columns?: number): string;
+/**
+ * Own the terminal only for the form lifetime. `undefined` means user cancel.
+ * The returned password has never crossed stdout, argv, env, or a DSH event.
+ */
+export declare function runTuiConnectionForm(options?: RunTuiConnectionFormOptions): Promise<DatabaseConnectionInput | undefined>;
+/** Decode the keyboard subset owned by the form; unknown terminal reports are ignored. */
+export declare function decodeTuiFormInput(value: string): TuiFormKey[];
+export {};