@yejiming/dsh-data-agent 0.0.1

package/lib/types/clients.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure CLI-client template construction for the supported database types.
+ * Everything here is a function of (type, connection, optional overrides) —
+ * no process, no I/O — so the injection-safety surface is unit-testable:
+ * argv stays an array (never shell-interpreted), the SQL itself always
+ * travels on stdin, and passwords only ever appear in the environment
+ * entries (`MYSQL_PWD` / `PGPASSWORD`) or in a stdin connect prefix
+ * (Oracle `connect`, Hive `!connect`) — never in argv, logs, or returns.
+ *
+ * Metadata (schemas / tables / describe) queries and their per-type output
+ * parsers live here too, so the /schemas /tables /describe routes stay thin.
+ * @module @yejiming/dsh-data-agent/clients
+ */
+import type { DatabaseConnection, DatabaseType } from './connections.ts';
+/** One deployment override for a database type's CLI client. */
+export interface ClientConfig {
+    /** Executable name (resolved through PATH) or absolute path. */
+    command: string;
+    /** Extra flag arguments prepended before the built-in flags. */
+    args?: readonly string[];
+}
+/** Loader schema for one client override (all fields optional at input). */
+export declare const clientConfigSchema: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+    command: import("@deepseek-ai/schemastery").default<string, string>;
+    args: import("@deepseek-ai/schemastery").default<string[], string[]>;
+}>, Schemastery.ObjectT<{
+    command: import("@deepseek-ai/schemastery").default<string, string>;
+    args: import("@deepseek-ai/schemastery").default<string[], string[]>;
+}>>;
+/** Loader schema for the whole `clients` config object (any type key). */
+export declare const clientsSchema: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/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[]>;
+}>, string>>;
+/**
+ * A fully constructed client invocation: argv (command + flags, no SQL),
+ * the credential env entries, and the stdin prefix (Oracle/Hive connect
+ * lines) the runner writes before the SQL text.
+ */
+export interface ClientTemplate {
+    /** Executable to resolve through {@link SubprocessService.resolveExecutable}. */
+    command: string;
+    /** Flag arguments only; the SQL text is written to stdin by the runner. */
+    args: readonly string[];
+    /** Credential env entries (e.g. `{ MYSQL_PWD }`), never argv. */
+    env: Readonly<Record<string, string>>;
+    /** stdin text written BEFORE the SQL (Oracle SET/connect, Hive !connect); '' otherwise. */
+    stdinPrefix: string;
+}
+/**
+ * Build one client invocation for a query execution (plain output). Flags
+ * come BEFORE the connection arguments everywhere: sqlite3 takes
+ * `[options] <database>`, and putting flags first is harmless for the others.
+ */
+export declare function buildClientTemplate(type: DatabaseType, connection: DatabaseConnection, override?: ClientConfig): ClientTemplate;
+/** Build one client invocation for metadata runs (machine-readable flags). */
+export declare function buildIntrospectTemplate(type: DatabaseType, connection: DatabaseConnection, override?: ClientConfig): ClientTemplate;
+/**
+ * The table-listing SQL per type, run at /connect time to verify
+ * connectivity: the connected database's own tables (mysql uses the
+ * connection's database as the schema; postgres lists `public`; oracle lists
+ * the connected user's tables; hive/impala list the default database).
+ */
+export declare function tableListingSql(type: DatabaseType, connection?: DatabaseConnection): string;
+/**
+ * Metadata query per kind × type. `schema`/`table` are identifier whitelist
+ * validated by the caller (`[A-Za-z0-9_$#.-]`) before they reach here.
+ */
+export declare function metadataQuery(kind: 'schemas' | 'tables' | 'describe', type: DatabaseType, schema?: string, table?: string): string;
+/**
+ * Split one type's machine-readable listing output into trimmed lines.
+ * Header lines are stripped per type: mysql `--batch` prints a header row
+ * (skip 1); postgres `-t`, sqlite `-noheader`, oracle `SET HEADING OFF`,
+ * hive/impala batch modes print none (skip 0).
+ */
+export declare function parseListing(type: DatabaseType, stdout: string): string[];
+/** Parse one type's table-listing output (the /connect connectivity check). */
+export declare function parseTableListing(type: DatabaseType, stdout: string): string[];
+/** One described column (nullable absent when the client reports none). */
+export interface ColumnInfo {
+    name: string;
+    type: string;
+    nullable?: boolean;
+}
+/**
+ * Parse one type's describe output into columns. Formats:
+ * - mysql `--batch`: `Field\tType\tNull\tKey\t...` (skip header);
+ * - postgres `-t -A`: `name|type|is_nullable`;
+ * - sqlite `-noheader -list`: `cid|name|type|notnull|dflt|pk` (name is part 1);
+ * - oracle (`SET COLSEP '|'`, heading off): `NAME|TYPE|NULLABLE`;
+ * - hive/impala batch: `name\ttype\tcomment`.
+ */
+export declare function parseColumns(type: DatabaseType, stdout: string): ColumnInfo[];

package/lib/types/connections.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The `dataAgentConnections` connection store: one in-memory connection per
+ * session id, host-plane provided by the server half (`src/index.ts`) and
+ * consumed by the sqlcmd tool half (`src/tool.ts`) inside the data-agent
+ * preset.
+ *
+ * Security contract:
+ * - passwords live in memory only — never written to session logs, settings,
+ *   config, or disk;
+ * - `get()` returns a password-stripped COPY, so UI/status consumers never
+ *   see the secret;
+ * - `getWithSecret()` is the process-internal read used ONLY by the sqlcmd
+ *   tool half (same package), which forwards the password to the database
+ *   client through an environment variable.
+ *
+ * Wildcard: a connection stored under the key `'*'` acts as the fallback for
+ * every session without its own entry (a deployment seeding a default
+ * database, or a headless/keyless run). Config-seeded entries cannot carry
+ * passwords, so the wildcard is always password-free.
+ * @module @yejiming/dsh-data-agent/connections
+ */
+/** Key of the wildcard (default) connection applied to any session without its own. */
+export declare const WILDCARD_SESSION = "*";
+/** Supported database client kinds. */
+export type DatabaseType = 'mysql' | 'postgres' | 'sqlite' | 'oracle' | 'hive' | 'impala';
+/**
+ * One session's database connection. `host`/`port`/`user` are empty for
+ * SQLite, whose `database` is a file path (resolved to absolute at connect).
+ * `tables` is the connectivity check's table listing, retained so the
+ * browser half can restore it after a tab switch without re-querying.
+ */
+export interface DatabaseConnection {
+    type: DatabaseType;
+    host?: string;
+    port?: number;
+    user?: string;
+    database: string;
+    /** In-memory only; never exposed through {@link DataAgentConnections.get}. */
+    password?: string;
+    tables?: string[];
+}
+/** Password-free view of one connection (the wire/UI face). */
+export interface ConnectionSummary {
+    type: DatabaseType;
+    host?: string;
+    port?: number;
+    user?: string;
+    database: string;
+    tables?: string[];
+}
+/** The host-plane connection store service (`ctx.dataAgentConnections`). */
+export interface DataAgentConnections {
+    /** Save (replace) one session's connection, password included. */
+    set(sessionId: string, connection: DatabaseConnection): void;
+    /** Read one session's connection WITHOUT the password (a fresh copy). */
+    get(sessionId: string): ConnectionSummary | undefined;
+    /**
+     * Read one session's connection INCLUDING the password. Process-internal
+     * only (the sqlcmd tool half); never hand this to a wire/UI consumer.
+     */
+    getWithSecret(sessionId: string): DatabaseConnection | undefined;
+    /** Whether a session currently has a connection. */
+    has(sessionId: string): boolean;
+    /** Drop one session's connection. */
+    clear(sessionId: string): void;
+}
+/** Build the password-stripped copy of one connection. */
+export declare function summarize(connection: DatabaseConnection): ConnectionSummary;
+/** Create a fresh connection store (per-process singleton, one per plugin instance). */
+export declare function createConnectionStore(): DataAgentConnections;

package/lib/types/defaults.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Package-wide defaults shared by the server half (`src/index.ts`) and the
+ * sqlcmd tool half (`src/tool.ts`). Loader schemas carry these as their
+ * defaults so a deployment may override every one of them in cordis.yml.
+ * @module @yejiming/dsh-data-agent/defaults
+ */
+/** Preset directory name installed into `$DSH_HOME/.agent-presets/`. */
+export declare const DEFAULT_PRESET_ID = "data-agent";
+/** End-to-end deadline for one `/connect` connectivity check, milliseconds. */
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 10000;
+/** Cap on the table list returned by `/connect` and `/status`. */
+export declare const DEFAULT_INTROSPECT_MAX_TABLES = 500;
+/** End-to-end deadline for one sqlcmd query, milliseconds. */
+export declare const DEFAULT_QUERY_TIMEOUT_MS = 30000;
+/** In-memory cap on sqlcmd captured output (stdout and stderr each). */
+export declare const DEFAULT_MAX_RESULT_CHARS = 20000;
+/** 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;

package/lib/types/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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).
+ *
+ * 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 sqlcmd
+ * tool itself lives in the `./tool` entry and is mounted only by the
+ * data-agent preset.
+ * @module @yejiming/dsh-data-agent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** The `dataAgentConnections` service face on the cordis context. */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        dataAgentConnections: DataAgentConnections;
+    }
+}
+import { type DataAgentConnections, type DatabaseType } from './connections.ts';
+import { type ClientConfig } from './clients.ts';
+/** Cordis plugin name (diagnostics only). */
+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;
+}
+/**
+ * One config-seeded connection. Deliberately password-free: passwords are a
+ * memory-only / connect-time value, so only the /connect route may carry one.
+ * The key `'*'` seeds the wildcard default used by any session without its
+ * own connection (headless/keyless runs, deployments pinning one database).
+ */
+export interface SeededConnectionConfig {
+    type: DatabaseType;
+    host?: string;
+    port?: number;
+    user?: string;
+    database: string;
+}
+/** Required plugin configuration (loader schema with deployment defaults). */
+export interface Config {
+    /** Preset directory name installed under `$DSH_HOME/.agent-presets/`. */
+    presetId: string;
+    /** Whether to self-install the preset on startup (idempotent). */
+    installPreset: boolean;
+    /** Deadline for one /connect connectivity check, milliseconds. */
+    connectTimeoutMs: number;
+    /** Cap on the table list returned by /connect and /status. */
+    introspectMaxTables: number;
+    /** Deadline for one sqlcmd query, milliseconds. */
+    queryTimeoutMs: number;
+    /** In-memory cap on sqlcmd captured output. */
+    maxResultChars: number;
+    /** 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>;
+    clients: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/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[]>;
+    }>, string>>;
+    connections: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/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;
+    } & 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>;
+    }>, 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>;
+    clients: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/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[]>;
+    }>, string>>;
+    connections: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/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;
+    } & 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>;
+    }>, string>>;
+}>>;
+/**
+ * Resolve the harness home the same way `@deepseek-ai/dsh-paths` does:
+ * `$DSH_HOME` (non-blank) else `~/.dsh`, normalized absolute.
+ */
+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.
+ */
+export declare function installPreset(ctx: Context, presetId: string): 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`).
+ * @param ctx - host cordis context.
+ * @param config - validated loader configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `@yejiming/dsh-data-agent`.
+ * @module @yejiming/dsh-data-agent/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "data-agent-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/types/query.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The shared client-process runner used by both halves: the /connect
+ * connectivity check (server half) and the sqlcmd tool (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.
+ * @module @yejiming/dsh-data-agent/query
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { DatabaseConnection, DatabaseType } from './connections.ts';
+import { type ClientConfig } from './clients.ts';
+/** One bounded captured-output read (the tail when truncated). */
+export interface CapturedOutput {
+    text: string;
+    truncated: boolean;
+}
+/** The canonical sqlcmd / connectivity-check result. */
+export interface QueryResult {
+    /** Process exit code; null when the process died from a signal. */
+    exitCode: number | null;
+    /** Captured stdout (tail when truncated). */
+    stdout: string;
+    /** Captured stderr (tail when truncated). */
+    stderr: string;
+    /** True when either stream hit the maxResultChars cap. */
+    truncated: boolean;
+}
+/** Runner options: client overrides, deadlines, output caps. */
+export interface QueryOptions {
+    /** Deployment client overrides keyed by database type. */
+    clients: Readonly<Partial<Record<DatabaseType, ClientConfig>>>;
+    /** End-to-end deadline in milliseconds (timeout → terminate the tree). */
+    timeoutMs: number;
+    /** In-memory cap per captured stream. */
+    maxResultChars: number;
+    /** Grace period for the terminate escalation; defaults to 5s. */
+    graceMs?: number;
+}
+/**
+ * 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.
+ *
+ * Failure classification:
+ * - the caller's external signal (e.g. the tool exec signal) aborts → the
+ *   abort reason propagates;
+ * - the internal timeout fires → an Error naming the deadline is thrown;
+ * - the executable cannot be resolved → an Error naming the command is thrown;
+ * - the process runs to completion → `{ exitCode, stdout, stderr, truncated }`
+ *   is returned even for a non-zero exit (the caller decides what that means).
+ * @param ctx - context exposing the subprocess service.
+ * @param connection - the stored connection (password included).
+ * @param sql - the SQL text (or client command) to run.
+ * @param options - timeouts, caps, client overrides.
+ * @param externalSignal - caller-owned cancellation (the tool exec signal).
+ * @param introspect - use the machine-readable introspection flag set.
+ * @returns the captured outcome.
+ */
+export declare function runClientQuery(ctx: Context, connection: DatabaseConnection, sql: string, options: QueryOptions, externalSignal: AbortSignal, introspect?: boolean): Promise<QueryResult>;

package/lib/types/routes.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ *
+ * 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).
+ * @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). */
+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.
+ */
+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). */
+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;
+}
+/** 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>;
+}>, 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>;
+}>>;
+/** The connection request wire body (validated in the /connect handler). */
+export interface ConnectRequestBody {
+    sessionId: string;
+    type: DatabaseType;
+    host?: string;
+    port?: number;
+    user?: string;
+    database: string;
+    password?: string;
+}
+/**
+ * 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).
+ */
+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 {};

package/lib/types/tool.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The sqlcmd tool half (`@yejiming/dsh-data-agent/tool`): mounted ONLY by
+ * the data-agent agent preset (`preset/data-agent/agent.cordis.yml`), never
+ * by the host composition. It consumes the host's `subprocess` service and
+ * the host-provided `dataAgentConnections` connection store, so it needs no
+ * realm and satisfies the preset guard (a preset row that only consumes).
+ *
+ * Execution model (see `src/query.ts`): the SQL text travels on the client's
+ * stdin, argv carries flags only, credentials go through environment entries
+ * (`MYSQL_PWD` / `PGPASSWORD`), and the caller's signal plus an internal
+ * deadline share one AbortController that drives the process-tree terminate
+ * escalation. Output is bounded per stream and marked `truncated`.
+ * @module @yejiming/dsh-data-agent/tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ClientConfig } from './clients.ts';
+/** Cordis plugin name (diagnostics only). */
+export declare const name = "data-agent-tool";
+/** Services required before the tool can register. */
+export declare const inject: string[];
+/** Tool-half configuration (loader schema with the same defaults as the host). */
+export interface Config {
+    /** Deadline for one sqlcmd query, milliseconds. */
+    queryTimeoutMs: number;
+    /** In-memory cap on captured output. */
+    maxResultChars: number;
+    /** Row-count guidance injected into the tool description. */
+    maxRows: number;
+    /** 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>;
+    clients: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/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[]>;
+    }>, 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>;
+    clients: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/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[]>;
+    }>, string>>;
+}>>;
+/**
+ * Mount the sqlcmd tool: register it into the current agent's tool registry.
+ * @param ctx - the preset-scoped agent context.
+ * @param config - validated loader configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;