@yejiming/dsh-data-agent 0.0.2 → 0.0.5

package/lib/tool.js

@@ -1,7 +1,169 @@
-import { i as DEFAULT_MAX_RESULT_CHARS, l as classifyStatement, o as DEFAULT_QUERY_TIMEOUT_MS, u as clientsSchema } from "./defaults-Dgu2B2Yq.js";
-import { t as runClientQuery } from "./query-vK9dr7Z6.js";
+import { d as clientsSchema, f as enforceReadRowLimit, i as DEFAULT_MAX_RESULT_CHARS, o as DEFAULT_QUERY_TIMEOUT_MS, u as classifyStatement, y as assertSingleStatement } from "./defaults-Bac6QvNt.js";
+import { t as runClientQuery } from "./query-CmhTFklw.js";
 import z from "schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/structured.ts
+function normalizeNewlines(text) {
+	return text.replace(/\r\n?/g, "\n");
+}
+function splitLine(line, delimiter) {
+	return line.split(delimiter);
+}
+/** Make column names valid unique JSON object keys. */
+function uniqueColumns(columns) {
+	const used = /* @__PURE__ */ new Set();
+	return columns.map((raw, index) => {
+		let name = raw.trim();
+		if (name.length === 0) name = `column_${index + 1}`;
+		if (used.has(name)) {
+			let suffix = 2;
+			while (used.has(`${name}_${suffix}`)) suffix += 1;
+			name = `${name}_${suffix}`;
+		}
+		used.add(name);
+		return name;
+	});
+}
+function rowObject(columns, fields) {
+	const row = {};
+	for (let index = 0; index < columns.length; index += 1) row[columns[index]] = fields[index] ?? null;
+	return row;
+}
+function emptyOutput() {
+	return {
+		columns: [],
+		rows: [],
+		rowLimitExceeded: false
+	};
+}
+function skipLeadingBlank(lines) {
+	let index = 0;
+	while (index < lines.length && lines[index].trim().length === 0) index += 1;
+	return index;
+}
+/** PostgreSQL `-A` appends a `(N rows)` / `(N row)` footer after SELECT output. */
+function isPostgresFooter(line) {
+	return /^\(\d+ rows?\)$/.test(line.trim());
+}
+function parseDelimited(stdout, delimiter, maxRows, skipFooter = false) {
+	const lines = normalizeNewlines(stdout).split("\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	const headerIndex = skipLeadingBlank(lines);
+	if (headerIndex >= lines.length) return emptyOutput();
+	const columns = uniqueColumns(splitLine(lines[headerIndex], delimiter));
+	const rows = [];
+	let rowLimitExceeded = false;
+	for (let index = headerIndex + 1; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (skipFooter && isPostgresFooter(line)) continue;
+		if (rows.length >= maxRows) {
+			rowLimitExceeded = true;
+			break;
+		}
+		rows.push(rowObject(columns, splitLine(line, delimiter)));
+	}
+	return {
+		columns,
+		rows,
+		rowLimitExceeded
+	};
+}
+/** Minimal RFC-4180-style parser for sqlite3 `-csv` output. */
+function parseCsv(text) {
+	const records = [];
+	let record = [];
+	let field = "";
+	let quoted = false;
+	let index = 0;
+	const pushField = () => {
+		record.push(field);
+		field = "";
+	};
+	const pushRecord = () => {
+		pushField();
+		records.push(record);
+		record = [];
+	};
+	while (index < text.length) {
+		const char = text[index];
+		if (quoted) {
+			if (char === "\"") {
+				if (text[index + 1] === "\"") {
+					field += "\"";
+					index += 2;
+					continue;
+				}
+				quoted = false;
+				index += 1;
+				continue;
+			}
+			field += char;
+			index += 1;
+			continue;
+		}
+		if (char === "\"" && field.length === 0) {
+			quoted = true;
+			index += 1;
+			continue;
+		}
+		if (char === ",") {
+			pushField();
+			index += 1;
+			continue;
+		}
+		if (char === "\n") {
+			pushRecord();
+			index += 1;
+			continue;
+		}
+		if (char === "\r") {
+			if (text[index + 1] === "\n") index += 1;
+			pushRecord();
+			index += 1;
+			continue;
+		}
+		field += char;
+		index += 1;
+	}
+	if (field.length > 0 || record.length > 0) pushRecord();
+	return records;
+}
+function parseCsvOutput(stdout, maxRows) {
+	const records = parseCsv(normalizeNewlines(stdout)).filter((record) => !(record.length === 1 && record[0] === ""));
+	if (records.length === 0) return emptyOutput();
+	const columns = uniqueColumns(records[0]);
+	const rows = [];
+	let rowLimitExceeded = false;
+	for (let index = 1; index < records.length; index += 1) {
+		if (rows.length >= maxRows) {
+			rowLimitExceeded = true;
+			break;
+		}
+		rows.push(rowObject(columns, records[index]));
+	}
+	return {
+		columns,
+		rows,
+		rowLimitExceeded
+	};
+}
+/**
+* Parse one database type's structured-query stdout. The matching template is
+* `buildStructuredQueryTemplate`: mysql tab-separated with a header, postgres
+* pipe-separated with a header and row-count footer, sqlite CSV with a header,
+* oracle pipe-separated with heading on, hive/impala tsv with a header.
+*/
+function parseStructuredQueryOutput(type, stdout, maxRows) {
+	switch (type) {
+		case "mysql": return parseDelimited(stdout, "	", maxRows);
+		case "postgres": return parseDelimited(stdout, "|", maxRows, true);
+		case "sqlite": return parseCsvOutput(stdout, maxRows);
+		case "oracle": return parseDelimited(stdout, "|", maxRows);
+		case "hive":
+		case "impala": return parseDelimited(stdout, "	", maxRows);
+	}
+}
+//#endregion
 //#region src/tool.ts
 /** Cordis plugin name (diagnostics only). */
 const name = "data-agent-tool";
@@ -19,12 +181,12 @@ const Config = z.object({
 	readonly: z.boolean().default(false),
 	clients: clientsSchema
 });
-/** One-line sqlcmd label for the terminal card (newlines collapsed). */
+/** One-line tool-call label (newlines collapsed). */
 function oneLine(sql) {
 	const line = sql.replace(/\s+/g, " ").trim();
 	return line.length > 80 ? `${line.slice(0, 77)}...` : line;
 }
-/** Format the canonical result as a monospace text block. */
+/** Format the raw terminal result. */
 function formatResult(value) {
 	const parts = [];
 	if (value.stdout.length > 0) parts.push(value.stdout);
@@ -33,8 +195,35 @@ function formatResult(value) {
 	if (value.exitCode !== 0) parts.push(`[exit code: ${value.exitCode ?? "signal"}]`);
 	return parts.join("\n");
 }
+/** Format the structured result as JSON text (the canonical value stays JSON). */
+function formatStructuredResult(value) {
+	return "```json\n" + JSON.stringify(value, null, 2) + "\n```";
+}
+/** Look up the session connection, failing with the same message for every tool. */
+function requireToolConnection(ctx, exec, toolName) {
+	const sessionId = exec.agent?.id;
+	if (sessionId === void 0) throw new Error(`${toolName}: 缺少会话上下文（agent loop 未注入）`);
+	const connection = ctx.dataAgentConnections.getWithSecret(sessionId);
+	if (connection === void 0) throw new Error(`请先在「数据库」标签页连接数据库，再使用 ${toolName}（未找到当前会话的连接）`);
+	return connection;
+}
+/** Empty and multi-statement checks shared by all three tools. */
+function validateSingleSql(sql, toolName) {
+	if (sql.trim().length === 0) throw new Error(`${toolName}: sql 不能为空`);
+	assertSingleStatement(sql, toolName);
+}
+/** Query runner options with the deployment overrides applied. */
+function runnerOptions(resolved, mode) {
+	return {
+		clients: resolved.clients,
+		timeoutMs: resolved.queryTimeoutMs,
+		maxResultChars: resolved.maxResultChars,
+		...mode !== void 0 ? { mode } : {}
+	};
+}
 /**
-* Mount the sqlcmd tool: register it into the current agent's tool registry.
+* Mount the data-agent database tools: `sql-query` (structured read-only),
+* `sql-write` (explicit write semantics), and `sqlcmd` (raw compatibility).
 * @param ctx - the preset-scoped agent context.
 * @param config - validated loader configuration.
 */
@@ -46,13 +235,146 @@ function apply(ctx, config) {
 		readonly: config.readonly,
 		clients: config.clients
 	};
+	ctx.tools.register(defineTool({
+		name: "sql-query",
+		description: `在已连接数据库上执行一条只读 SQL（SELECT/SHOW/DESCRIBE/EXPLAIN，SQLite 还含查询型 PRAGMA），返回结构化 JSON：{ columns, rows, affectedRows, elapsedMs, truncated }。SELECT 未写 LIMIT 时会自动限制为最多 ${resolved.maxRows} 行；所有结果最多返回 ${resolved.maxRows} 行。只执行单条语句；写操作请使用 sql-write，原始客户端输出请使用 sqlcmd。`,
+		parameters: { sql: {
+			type: "string",
+			required: true,
+			description: "一条只读 SQL，如 \"SELECT * FROM orders LIMIT 5;\"、\"SHOW TABLES;\"、\"DESCRIBE users;\""
+		} },
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					columns: {
+						type: "array",
+						items: { type: "string" },
+						required: true
+					},
+					rows: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {},
+							additionalProperties: true
+						},
+						required: true
+					},
+					affectedRows: {
+						type: "integer",
+						required: true
+					},
+					elapsedMs: {
+						type: "integer",
+						required: true
+					},
+					truncated: {
+						type: "boolean",
+						required: true
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: formatStructuredResult(value)
+			}]
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			kind: "read",
+			title: `sql-query ${oneLine(args.sql)}`,
+			rawInput: args.sql
+		}),
+		presentResult: (args, result) => ({
+			card: "generic",
+			title: `sql-query ${oneLine(args.sql)}`,
+			content: result.content
+		}),
+		async execute(args, exec) {
+			const connection = requireToolConnection(ctx, exec, "sql-query");
+			validateSingleSql(args.sql, "sql-query");
+			if (classifyStatement(args.sql, connection.type) !== "read") throw new Error("sql-query 只执行读语句（SELECT/SHOW/DESCRIBE/EXPLAIN，SQLite 还含查询型 PRAGMA）；写语句请使用 sql-write");
+			const limitedSql = enforceReadRowLimit(args.sql, connection.type, resolved.maxRows);
+			const startedAt = Date.now();
+			const result = await runClientQuery(ctx, connection, limitedSql, runnerOptions(resolved, "structured"), exec.signal);
+			const elapsedMs = Date.now() - startedAt;
+			if (result.exitCode !== 0) {
+				const detail = result.stderr.trim() !== "" ? result.stderr.trim() : result.stdout.trim();
+				throw new Error(`sql-query 执行失败（exit ${result.exitCode}）：${detail}`);
+			}
+			const parsed = parseStructuredQueryOutput(connection.type, result.stdout, resolved.maxRows);
+			return {
+				columns: parsed.columns,
+				rows: parsed.rows,
+				affectedRows: 0,
+				elapsedMs,
+				truncated: result.truncated || parsed.rowLimitExceeded
+			};
+		}
+	}));
+	ctx.tools.register(defineTool({
+		name: "sql-write",
+		description: "在已连接数据库上执行一条写/管理语句（INSERT/UPDATE/DELETE/DDL 等）。每次调用都是独立客户端进程并自动提交，只接受单条语句，不支持跨调用的多语句事务；如需原子性，请改用单条 SQL（如 INSERT ... SELECT）或数据库端脚本/存储过程。只读查询请使用 sql-query。",
+		parameters: { sql: {
+			type: "string",
+			required: true,
+			description: "一条写/管理 SQL，如 \"INSERT INTO t VALUES (1);\"、\"UPDATE t SET x=1;\"、\"CREATE INDEX idx_t_x ON t(x);\""
+		} },
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					exitCode: {
+						oneOf: [{ type: "integer" }, { type: "null" }],
+						required: true
+					},
+					stdout: {
+						type: "string",
+						required: true
+					},
+					stderr: {
+						type: "string",
+						required: true
+					},
+					truncated: {
+						type: "boolean",
+						required: true
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: formatResult(value)
+			}]
+		},
+		presentCall: (args) => ({
+			card: "terminal",
+			title: `sql-write ${oneLine(args.sql)}`,
+			description: "执行一条写/管理 SQL（自动提交）"
+		}),
+		presentResult: (args, result) => ({
+			card: "terminal",
+			title: `sql-write ${oneLine(args.sql)}`,
+			content: result.content
+		}),
+		async execute(args, exec) {
+			const connection = requireToolConnection(ctx, exec, "sql-write");
+			validateSingleSql(args.sql, "sql-write");
+			if (classifyStatement(args.sql, connection.type) === "read") throw new Error("sql-write 只执行写/管理语句；只读查询请使用 sql-query");
+			if (connection.readonly ?? resolved.readonly) throw new Error("当前连接为只读模式，sql-write 拒绝执行写/管理语句（仅放行 SELECT/SHOW/DESCRIBE/EXPLAIN/查询型 PRAGMA 等）");
+			return runClientQuery(ctx, connection, args.sql, runnerOptions(resolved), exec.signal);
+		}
+	}));
 	ctx.tools.register(defineTool({
 		name: "sqlcmd",
-		description: `在已连接的数据库上执行 SQL 或客户端命令（如 SHOW TABLES、DESCRIBE users、SELECT * FROM orders LIMIT ${resolved.maxRows}）。需要先在「数据库」标签页连接数据库；SQL 经 stdin 传给客户端（mysql/psql/sqlite3），无 shell 层。结果包含 exitCode 与 stdout/stderr 文本。`,
+		description: `在已连接数据库上执行一条 SQL 或客户端命令（如 SHOW TABLES、DESCRIBE users），返回原始 exitCode/stdout/stderr 文本。新调用优先使用 sql-query（结构化只读结果）和 sql-write（明确写语义）。一次只执行一条语句；读 SELECT 会自动限制最多 ${resolved.maxRows} 行；每次调用为独立客户端进程并自动提交。`,
 		parameters: { sql: {
 			type: "string",
 			required: true,
-			description: "要执行的 SQL 文本（或客户端命令），如 \"SHOW TABLES;\"、\"DESCRIBE users;\"、\"SELECT * FROM orders LIMIT 5;\""
+			description: "一条 SQL 文本（或客户端命令），如 \"SHOW TABLES;\"、\"DESCRIBE users;\"、\"SELECT * FROM orders LIMIT 5;\""
 		} },
 		output: {
 			schema: {
@@ -85,7 +407,7 @@ function apply(ctx, config) {
 		presentCall: (args) => ({
 			card: "terminal",
 			title: `sqlcmd ${oneLine(args.sql)}`,
-			description: "在数据库客户端执行 SQL"
+			description: "在数据库客户端执行一条 SQL"
 		}),
 		presentResult: (args, result) => ({
 			card: "terminal",
@@ -93,16 +415,11 @@ function apply(ctx, config) {
 			content: result.content
 		}),
 		async execute(args, exec) {
-			const sessionId = exec.agent?.id;
-			if (sessionId === void 0) throw new Error("sqlcmd: 缺少会话上下文（agent loop 未注入）");
-			const connection = ctx.dataAgentConnections.getWithSecret(sessionId);
-			if (connection === void 0) throw new Error("请先在「数据库」标签页连接数据库，再使用 sqlcmd（未找到当前会话的连接）");
-			if ((connection.readonly ?? resolved.readonly) && classifyStatement(args.sql, connection.type) === "write") throw new Error("当前连接为只读模式，sqlcmd 拒绝执行非读语句（仅放行 SELECT/SHOW/DESCRIBE/EXPLAIN/PRAGMA 等）");
-			return runClientQuery(ctx, connection, args.sql, {
-				clients: resolved.clients,
-				timeoutMs: resolved.queryTimeoutMs,
-				maxResultChars: resolved.maxResultChars
-			}, exec.signal);
+			const connection = requireToolConnection(ctx, exec, "sqlcmd");
+			validateSingleSql(args.sql, "sqlcmd");
+			if ((connection.readonly ?? resolved.readonly) && classifyStatement(args.sql, connection.type) === "write") throw new Error("当前连接为只读模式，sqlcmd 拒绝执行非读语句（仅放行 SELECT/SHOW/DESCRIBE/EXPLAIN/查询型 PRAGMA 等）");
+			const sql = classifyStatement(args.sql, connection.type) === "read" ? enforceReadRowLimit(args.sql, connection.type, resolved.maxRows) : args.sql;
+			return runClientQuery(ctx, connection, sql, runnerOptions(resolved), exec.signal);
 		}
 	}));
 }

package/lib/types/client/locales.d.ts

@@ -4,6 +4,8 @@ export declare const NS = "data-agent";
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export declare const zh: {
     'form.title': string;
+    'form.hero.title': string;
+    'form.hero.hint': string;
     'form.type': string;
     'type.mysql': string;
     'type.postgres': string;
@@ -47,7 +49,6 @@ export declare const zh: {
     'action.config': string;
     'action.browse': string;
     'action.close': string;
-    'action.collapse': string;
     'error.title': string;
 };
 /** The data-agent namespace key union. */
@@ -55,6 +56,8 @@ export type DataAgentKey = keyof typeof zh;
 /** English dictionary, checked complete against the zh key set. */
 export declare const en: {
     'form.title': string;
+    'form.hero.title': string;
+    'form.hero.hint': string;
     'form.type': string;
     'type.mysql': string;
     'type.postgres': string;
@@ -98,6 +101,5 @@ export declare const en: {
     'action.config': string;
     'action.browse': string;
     'action.close': string;
-    'action.collapse': string;
     'error.title': string;
 };

package/lib/types/clients.d.ts

@@ -12,12 +12,26 @@
  * @module @yejiming/dsh-data-agent/clients
  */
 import type { DatabaseConnection, DatabaseType } from './connections.ts';
+import { assertSingleStatement, hasTopLevelKeyword, stripTrailingTerminator } from './sql.ts';
+export { assertSingleStatement, hasTopLevelKeyword, stripTrailingTerminator };
 /**
  * Classify a SQL text as a read or write statement by its FIRST effective
  * token (a conservative read whitelist, not a parser). `with` is read only
- * when its body's first token is `select`. `pragma` is read-only for SQLite.
+ * when its body's first token is `select`. SQLite `pragma` is read in its
+ * query form and write when a value is assigned.
  */
 export declare function classifyStatement(sql: string, type: DatabaseType): 'read' | 'write';
+/**
+ * Enforce the configured `maxRows` on a read query instead of relying on the
+ * prompt. SELECT/CTE-read statements get a real top-level LIMIT (Oracle uses
+ * a ROWNUM wrapper because it has no LIMIT); SHOW/DESCRIBE/EXPLAIN/PRAGMA are
+ * left untouched here and are capped while parsing structured output.
+ *
+ * An existing numeric top-level LIMIT is rewritten when it is larger than
+ * `maxRows`; a smaller existing LIMIT is preserved, and a non-numeric or
+ * unparseable LIMIT is left for the client (structured tools still truncate).
+ */
+export declare function enforceReadRowLimit(sql: string, type: DatabaseType, maxRows: number): string;
 /**
  * Validate and quote one schema/table identifier for a safe metadata query.
  * Identifiers are restricted to `[A-Za-z0-9_$]+` and then wrapped per type:
@@ -73,6 +87,12 @@ export interface ClientTemplate {
 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;
+/**
+ * Build one client invocation for the structured `sql-query` tool: every
+ * supported client prints a header row followed by one row per line (mysql
+ * tab, postgres pipe, sqlite csv, oracle pipe, hive/impala tsv).
+ */
+export declare function buildStructuredQueryTemplate(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
@@ -82,7 +102,7 @@ export declare function buildIntrospectTemplate(type: DatabaseType, connection:
 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.
+ * 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;
 /**

package/lib/types/defaults.d.ts

@@ -1,6 +1,6 @@
 /**
  * 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
+ * database 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
  */
@@ -10,9 +10,9 @@ export declare const DEFAULT_PRESET_ID = "data-agent";
 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. */
+/** End-to-end deadline for one database-tool query, milliseconds. */
 export declare const DEFAULT_QUERY_TIMEOUT_MS = 30000;
-/** In-memory cap on sqlcmd captured output (stdout and stderr each). */
+/** In-memory cap on database-tool 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;

package/lib/types/index.d.ts

@@ -8,9 +8,9 @@
  *
  * 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.
+ * this row keeps working in headless profiles without a webserver; the
+ * database tools themselves live in the `./tool` entry and are mounted only
+ * by the data-agent preset.
  * @module @yejiming/dsh-data-agent
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -57,11 +57,11 @@ export interface Config {
     connectTimeoutMs: number;
     /** Cap on the table list returned by /connect and /status. */
     introspectMaxTables: number;
-    /** Deadline for one sqlcmd query, milliseconds. */
+    /** Deadline for one database-tool query, milliseconds. */
     queryTimeoutMs: number;
-    /** In-memory cap on sqlcmd captured output. */
+    /** In-memory cap on database-tool captured output. */
     maxResultChars: number;
-    /** Default read-only guard: true rejects write statements in sqlcmd//query. */
+    /** Default read-only guard: true rejects write statements in database tools and /query. */
     readonly: boolean;
     /** CLI client overrides keyed by database type. */
     clients: ClientsConfig;

package/lib/types/query.d.ts

@@ -1,6 +1,6 @@
 /**
  * The shared client-process runner used by both halves: the /connect
- * connectivity check (server half) and the sqlcmd tool (tool half). All
+ * 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
@@ -15,7 +15,7 @@ export interface CapturedOutput {
     text: string;
     truncated: boolean;
 }
-/** The canonical sqlcmd / connectivity-check result. */
+/** The canonical database-tool / connectivity-check result. */
 export interface QueryResult {
     /** Process exit code; null when the process died from a signal. */
     exitCode: number | null;
@@ -26,6 +26,8 @@ export interface QueryResult {
     /** True when either stream hit the maxResultChars cap. */
     truncated: boolean;
 }
+/** Which CLI flag set to use for one run. */
+export type QueryTemplateMode = 'query' | 'introspect' | 'structured';
 /** Runner options: client overrides, deadlines, output caps. */
 export interface QueryOptions {
     /** Deployment client overrides keyed by database type. */
@@ -36,6 +38,8 @@ export interface QueryOptions {
     maxResultChars: number;
     /** Grace period for the terminate escalation; defaults to 5s. */
     graceMs?: number;
+    /** CLI flag set; overrides the legacy `introspect` parameter when set. */
+    mode?: QueryTemplateMode;
 }
 /**
  * Run one SQL text through the type's CLI client. The SQL is written to the

package/lib/types/sql.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Lightweight SQL-text scanning helpers shared by the sqlcmd 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
+ * 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.
+ *
+ * @module @yejiming/dsh-data-agent/sql
+ */
+/**
+ * Throw unless `sql` contains at most one statement. A single trailing
+ * semicolon (and any number of repeated trailing semicolons / comments) is
+ * accepted; a semicolon followed by real content is rejected.
+ */
+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;
+/**
+ * Strip trailing whitespace, statement terminators and trailing comments so a
+ * limit clause can be appended to the actual statement text. Only comments
+ * that occupy the whole tail are removed; the preceding statement is kept.
+ */
+export declare function stripTrailingTerminator(sql: string): string;

package/lib/types/structured.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Structured result parsing for the `sql-query` tool half. Each supported
+ * database type has a machine-readable query template (see
+ * {@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).
+ *
+ * The parsers are deliberately output-shape based, not grammar based. Values
+ * stay as strings because every client renders SQL values as text (NULL
+ * rendering differs per client), and duplicate column names are made unique
+ * so the row objects are valid lossless JSON maps.
+ * @module @yejiming/dsh-data-agent/structured
+ */
+import type { DatabaseType } from './connections.ts';
+/** Canonical parsed query output before elapsed/affected metadata is added. */
+export interface ParsedQueryOutput {
+    columns: string[];
+    rows: Record<string, string | null>[];
+    /** True when the output contained more rows than `maxRows` and was capped. */
+    rowLimitExceeded: boolean;
+}
+/**
+ * Parse one database type's structured-query stdout. The matching template is
+ * `buildStructuredQueryTemplate`: mysql tab-separated with a header, postgres
+ * pipe-separated with a header and row-count footer, sqlite CSV with a header,
+ * oracle pipe-separated with heading on, hive/impala tsv with a header.
+ */
+export declare function parseStructuredQueryOutput(type: DatabaseType, stdout: string, maxRows: number): ParsedQueryOutput;

package/lib/types/tool.d.ts

@@ -1,10 +1,15 @@
 /**
- * The sqlcmd tool half (`@yejiming/dsh-data-agent/tool`): mounted ONLY by
+ * The data-agent 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).
  *
+ * 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).
+ *
  * 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
@@ -20,11 +25,11 @@ 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 query, milliseconds. */
+    /** Deadline for one sqlcmd / sql-query / sql-write query, milliseconds. */
     queryTimeoutMs: number;
     /** In-memory cap on captured output. */
     maxResultChars: number;
-    /** Row-count guidance injected into the tool description. */
+    /** Enforced read-query row cap (LIMIT injection + structured truncation). */
     maxRows: number;
     /** Read-only guard: true rejects write statements. */
     readonly: boolean;
@@ -58,7 +63,8 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     }>, string>>;
 }>>;
 /**
- * Mount the sqlcmd tool: register it into the current agent's tool registry.
+ * Mount the data-agent database tools: `sql-query` (structured read-only),
+ * `sql-write` (explicit write semantics), and `sqlcmd` (raw compatibility).
  * @param ctx - the preset-scoped agent context.
  * @param config - validated loader configuration.
  */