@tea-agent/loop-agent 0.44.0-next.1 → 0.44.0-next.3

package/dist/worker/console/chat/pi-runtime/custom-tools/operator-tools.js

@@ -80,7 +80,7 @@ export async function buildCustomOperatorTools(options) {
                 }
                 // Defer require to avoid circular import at module load.
                 const { dispatchChatToolCall } = await import("../../session-store.js");
-                const result = await dispatchChatToolCall(ctx, decision.toolId, params, toolCallId, options.sessionMode);
+                const result = await dispatchChatToolCall({ ...ctx, chatSessionRef: options.sessionId }, decision.toolId, params, toolCallId, options.sessionMode);
                 const payload = result.ok
                     ? result.result
                     : { error: result.message, code: result.errorCode };

package/dist/worker/console/chat/pi-runtime/custom-tools/sql-tools.js

@@ -0,0 +1,627 @@
+/**
+ * Operator Chat — governed SQL tools (2026-09-12).
+ *
+ * Six model-callable custom tools over DbConnectionRegistry:
+ *   sql_query        read-only (SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH),
+ *                    lexically enforced, multi-statement rejected
+ *   sql_exec         permanently disabled: Console database access is read-only
+ *                    regardless of confirmation
+ *   sql_schema       list tables / describe one table's columns
+ *   sql_stats        table count, per-table row counts, db size
+ *   sql_health       per-connection SELECT 1 + governance summary
+ *   sql_connections  list/add/remove/test connection configs (sanitized)
+ *
+ * Envelope: success { ok: true, ... } / failure { ok: false, error: { code,
+ * message } } with stable DB_* error codes. Credentials (DSN values) are
+ * never echoed — postgres/mysql configs carry only the env var NAME.
+ */
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { isSqliteHandle, } from "../../db-connections.js";
+export const SQL_QUERY_TIMEOUT_MS = 30_000;
+export const SQL_EXEC_TIMEOUT_MS = 60_000;
+export const SQL_MAX_ROWS_DEFAULT = 200;
+export const SQL_MAX_ROWS_LIMIT = 1_000;
+const READ_ONLY_LEADING_TOKENS = new Set([
+    "SELECT",
+    "PRAGMA",
+    "EXPLAIN",
+    "SHOW",
+    "DESCRIBE",
+    "WITH",
+]);
+const WRITE_LEADING_TOKENS = new Set([
+    "INSERT",
+    "UPDATE",
+    "DELETE",
+    "REPLACE",
+    "CREATE",
+    "DROP",
+    "ALTER",
+    "TRUNCATE",
+    "VACUUM",
+    "REINDEX",
+    "ATTACH",
+    "DETACH",
+    "BEGIN",
+    "COMMIT",
+    "ROLLBACK",
+    "SAVEPOINT",
+    "RELEASE",
+    "ANALYZE",
+    "GRANT",
+    "REVOKE",
+    "MERGE",
+    "CALL",
+    "EXECUTE",
+    "SET",
+    "USE",
+    "LOAD",
+    "IMPORT",
+    "COPY",
+    "OPTIMIZE",
+    "RENAME",
+]);
+const SQL_TOOLS_DESCRIPTION = "Governed SQL access over named database connections (sqlite via node:sqlite; PostgreSQL via pg; MySQL via mysql2). " +
+    "sql_query is READ-ONLY (SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH; single statement). " +
+    "Before writing any SQL, call sql_schema to inspect real table/column names — never guess identifiers. " +
+    "sql_exec is permanently disabled: DELETE, DROP, INSERT, UPDATE, DDL, permission changes, and every other mutation are rejected even after confirmation. " +
+    "sql_stats counts rows per table (can be expensive on large tables). sql_health probes connectivity. " +
+    "sql_connections manages configs: adding a connection is low-risk, but run action=\"test\" before first real use.";
+class SqlToolError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "SqlToolError";
+    }
+}
+/**
+ * Strip SQL comments (`-- line`, `/* block *\/`) outside string literals so
+ * lexical checks see the executable tokens only.
+ */
+function stripSqlComments(sql) {
+    let out = "";
+    let i = 0;
+    let inSingle = false;
+    let inDouble = false;
+    while (i < sql.length) {
+        const ch = sql[i];
+        const next = sql[i + 1];
+        if (!inSingle && !inDouble) {
+            if (ch === "-" && next === "-") {
+                const end = sql.indexOf("\n", i);
+                i = end === -1 ? sql.length : end;
+                continue;
+            }
+            if (ch === "/" && next === "*") {
+                const end = sql.indexOf("*/", i + 2);
+                i = end === -1 ? sql.length : end + 2;
+                continue;
+            }
+            if (ch === "'")
+                inSingle = true;
+            else if (ch === '"')
+                inDouble = true;
+        }
+        else {
+            if (inSingle) {
+                if (ch === "'") {
+                    if (next === "'") {
+                        out += "''";
+                        i += 2;
+                        continue;
+                    }
+                    inSingle = false;
+                }
+            }
+            else if (inDouble && ch === '"')
+                inDouble = false;
+        }
+        out += ch;
+        i += 1;
+    }
+    return out;
+}
+/**
+ * Split a SQL script into top-level statements on `;`, respecting string
+ * literals ('...', "...") and comments. Empty/whitespace-only parts are
+ * dropped. Returns [] for a blank script.
+ */
+function splitStatements(sql) {
+    const parts = [];
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    let i = 0;
+    while (i < sql.length) {
+        const ch = sql[i];
+        const next = sql[i + 1];
+        if (!inSingle && !inDouble) {
+            if (ch === "-" && next === "-") {
+                const end = sql.indexOf("\n", i);
+                const stop = end === -1 ? sql.length : end;
+                current += sql.slice(i, stop);
+                i = stop;
+                continue;
+            }
+            if (ch === "/" && next === "*") {
+                const end = sql.indexOf("*/", i + 2);
+                const stop = end === -1 ? sql.length : end + 2;
+                current += sql.slice(i, stop);
+                i = stop;
+                continue;
+            }
+            if (ch === "'") {
+                inSingle = true;
+                current += ch;
+                i += 1;
+                continue;
+            }
+            if (ch === '"') {
+                inDouble = true;
+                current += ch;
+                i += 1;
+                continue;
+            }
+            if (ch === ";") {
+                parts.push(current);
+                current = "";
+                i += 1;
+                continue;
+            }
+            current += ch;
+            i += 1;
+            continue;
+        }
+        // inside a literal
+        if (inSingle) {
+            if (ch === "'") {
+                if (next === "'") {
+                    current += "''";
+                    i += 2;
+                    continue;
+                }
+                inSingle = false;
+            }
+        }
+        else if (inDouble && ch === '"') {
+            inDouble = false;
+        }
+        current += ch;
+        i += 1;
+    }
+    parts.push(current);
+    return parts.map((p) => p.trim()).filter(Boolean);
+}
+function leadingToken(statement) {
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)/.exec(statement);
+    return match?.[1]?.toUpperCase() ?? "";
+}
+/** Throw DB_MULTI_STATEMENT_REJECTED when >1 top-level statement is present. */
+function assertSingleStatement(statements) {
+    if (statements.length > 1) {
+        throw new SqlToolError("DB_MULTI_STATEMENT_REJECTED", `sql_query accepts exactly one statement (got ${statements.length}); use sql_exec with a confirmation token for multi-statement writes`);
+    }
+}
+/** Lexical read-only gate for sql_query (statement must already be single). */
+function assertReadOnlyStatement(statement) {
+    const bare = stripSqlComments(statement);
+    const token = leadingToken(bare);
+    if (READ_ONLY_LEADING_TOKENS.has(token)) {
+        // allowed root — now reject write-capable constructs inside it
+    }
+    else if (WRITE_LEADING_TOKENS.has(token)) {
+        throw new SqlToolError("DB_READ_ONLY_VIOLATION", `sql_query rejected: leading token ${token} is not read-only`);
+    }
+    else {
+        throw new SqlToolError("DB_READ_ONLY_VIOLATION", `sql_query rejected: statement must start with SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH (got ${token || "nothing"})`);
+    }
+    const folded = bare.toUpperCase();
+    if (/\bFOR\s+UPDATE\b/.test(folded) || /\bFOR\s+SHARE\b/.test(folded)) {
+        throw new SqlToolError("DB_READ_ONLY_VIOLATION", "sql_query rejected: FOR UPDATE / FOR SHARE locking clauses are not read-only");
+    }
+    if (/\bSELECT\b[^;]*\bINTO\b/.test(folded)) {
+        throw new SqlToolError("DB_READ_ONLY_VIOLATION", "sql_query rejected: SELECT ... INTO creates a table");
+    }
+    if (token === "WITH") {
+        // data-modifying CTE: WITH ... (INSERT|UPDATE|DELETE|MERGE|REPLACE)
+        if (/\)\s*(INSERT|UPDATE|DELETE|MERGE|REPLACE)\b/.test(folded) ||
+            /\bAS\s*\(\s*(INSERT|UPDATE|DELETE|MERGE|REPLACE)\b/.test(folded)) {
+            throw new SqlToolError("DB_READ_ONLY_VIOLATION", "sql_query rejected: data-modifying CTE (WITH ... INSERT/UPDATE/DELETE)");
+        }
+        if (/\b(INSERT|UPDATE|DELETE|MERGE|REPLACE)\b/.test(folded)) {
+            throw new SqlToolError("DB_READ_ONLY_VIOLATION", "sql_query rejected: data-modifying statement inside WITH");
+        }
+    }
+    if (token === "PRAGMA") {
+        // PRAGMA assignment forms: `PRAGMA x = y` or `PRAGMA x(y)`
+        if (/^PRAGMA\s+[A-Za-z0-9_.]+\s*=/.test(bare.trim().toUpperCase())) {
+            throw new SqlToolError("DB_READ_ONLY_VIOLATION", "sql_query rejected: PRAGMA assignment writes configuration");
+        }
+        if (/^PRAGMA\s+[A-Za-z0-9_.]+\s*\(/.test(bare.trim())) {
+            throw new SqlToolError("DB_READ_ONLY_VIOLATION", "sql_query rejected: PRAGMA call-form assignment writes configuration");
+        }
+    }
+}
+/** Identifier guard for interpolated table names (schema/stats). */
+function assertSafeIdentifier(name) {
+    const trimmed = name.trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(trimmed)) {
+        throw new SqlToolError("DB_INVALID_CONFIG", `invalid SQL identifier: ${JSON.stringify(trimmed)}`);
+    }
+    return trimmed;
+}
+function formatTable(columns, rows) {
+    const cell = (v) => (v === null || v === undefined ? "" : String(v));
+    const header = columns.join(" | ");
+    const divider = columns.map(() => "---").join(" | ");
+    const body = rows.map((r) => columns.map((c) => cell(r[c])).join(" | ")).join("\n");
+    return [header, divider, body].join("\n");
+}
+function toCsv(columns, rows) {
+    const esc = (v) => {
+        const s = v === null || v === undefined ? "" : String(v);
+        return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+    };
+    return [columns.join(","), ...rows.map((r) => columns.map((c) => esc(r[c])).join(","))].join("\n");
+}
+export async function buildSqlTools(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const registry = options.registry;
+    /** resolved confirmations: questionId → { sessionId, rejected } (one-shot). */
+    const resolvedConfirmations = new Map();
+    let unsubscribe;
+    if (options.questionRegistry) {
+        unsubscribe = options.questionRegistry.subscribe((change) => {
+            if (change.type !== "resolved")
+                return;
+            const question = change.question;
+            if (question.sessionId !== options.sessionId)
+                return;
+            const rejected = question.answer?.answers.some((a) => a.selected.some((label) => /reject|cancel|deny|拒绝|取消|否/i.test(label)));
+            for (const q of question.questions) {
+                resolvedConfirmations.set(q.id, {
+                    sessionId: question.sessionId,
+                    rejected: Boolean(rejected),
+                });
+            }
+        });
+    }
+    /** Validate and consume a one-shot confirmation token. */
+    function consumeConfirmationToken(token) {
+        if (!options.questionRegistry) {
+            throw new SqlToolError("DB_CONFIRMATION_REQUIRED", "sql_exec requires the ask_user_question confirmation gate, which is unavailable in this session");
+        }
+        const id = typeof token === "string" ? token.trim() : "";
+        if (!id) {
+            throw new SqlToolError("DB_CONFIRMATION_REQUIRED", "sql_exec requires confirmationToken: first call ask_user_question with the full SQL and Approve/Reject options, then pass its question id");
+        }
+        const entry = resolvedConfirmations.get(id);
+        if (!entry || entry.sessionId !== options.sessionId) {
+            throw new SqlToolError("DB_CONFIRMATION_REQUIRED", `confirmation token "${id}" was not approved in this session; ask the user via ask_user_question first`);
+        }
+        resolvedConfirmations.delete(id); // one-shot: burn even when rejected below
+        if (entry.rejected) {
+            throw new SqlToolError("DB_CONFIRMATION_REQUIRED", `the user rejected the confirmation for "${id}"`);
+        }
+    }
+    async function envelope(operation, timeoutMs) {
+        let result;
+        try {
+            result = await withTimeout(operation(), timeoutMs);
+        }
+        catch (error) {
+            const code = error instanceof SqlToolError
+                ? error.code
+                : error instanceof Error && "code" in error
+                    ? mapRegistryCode(String(error.code))
+                    : "DB_ENGINE_ERROR";
+            const message = error instanceof Error ? error.message : String(error);
+            result = { ok: false, error: { code, message } };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result) }],
+            details: result,
+        };
+    }
+    function mapRegistryCode(code) {
+        switch (code) {
+            case "DB_CONNECTION_NOT_FOUND":
+            case "DB_ENV_MISSING":
+            case "DB_ENGINE_UNAVAILABLE":
+            case "DB_ENGINE_ERROR":
+            case "DB_INVALID_CONFIG":
+                return code;
+            default:
+                return "DB_ENGINE_ERROR";
+        }
+    }
+    async function withTimeout(promise, timeoutMs) {
+        let timer;
+        try {
+            return await Promise.race([
+                promise,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new SqlToolError("DB_TIMEOUT", `operation exceeded ${timeoutMs}ms`)), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    const connectionParameter = Type.String({
+        description: "Named connection from sql_connections list.",
+    });
+    return [
+        defineTool({
+            name: "sql_query",
+            label: "SQL query (read-only)",
+            description: SQL_TOOLS_DESCRIPTION,
+            promptSnippet: SQL_TOOLS_DESCRIPTION,
+            parameters: Type.Object({
+                connection: connectionParameter,
+                sql: Type.String({ description: "Single read-only statement (SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH)." }),
+                format: Type.Optional(Type.Union([Type.Literal("table"), Type.Literal("csv"), Type.Literal("json")])),
+                maxRows: Type.Optional(Type.Integer({ minimum: 1, maximum: SQL_MAX_ROWS_LIMIT })),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return envelope(async () => {
+                    const statements = splitStatements(params.sql ?? "");
+                    if (statements.length === 0) {
+                        throw new SqlToolError("DB_INVALID_CONFIG", "sql is empty");
+                    }
+                    assertSingleStatement(statements);
+                    assertReadOnlyStatement(statements[0]);
+                    const handle = await registry.connect(params.connection);
+                    const limit = Math.min(Math.max(params.maxRows ?? SQL_MAX_ROWS_DEFAULT, 1), SQL_MAX_ROWS_LIMIT);
+                    // sqlite exposes column metadata via prepare(); pg/mysql derive it
+                    // from the first result row.
+                    let columns;
+                    let all;
+                    if (isSqliteHandle(handle)) {
+                        const stmt = handle.prepare(params.sql.trim());
+                        columns = stmt.columns().map((c) => c.name);
+                        all = stmt.all();
+                    }
+                    else {
+                        all = await handle.query(params.sql.trim());
+                        columns = all.length > 0 ? Object.keys(all[0]) : [];
+                    }
+                    const truncated = all.length > limit;
+                    const rows = truncated ? all.slice(0, limit) : all;
+                    const format = params.format ?? "json";
+                    let text;
+                    if (format === "table")
+                        text = formatTable(columns, rows);
+                    else if (format === "csv")
+                        text = toCsv(columns, rows);
+                    else
+                        text = JSON.stringify(rows);
+                    return {
+                        ok: true,
+                        connection: params.connection,
+                        columns,
+                        rows,
+                        rowCount: rows.length,
+                        truncated,
+                        ...(text !== undefined ? { text } : {}),
+                    };
+                }, SQL_QUERY_TIMEOUT_MS);
+            },
+        }),
+        defineTool({
+            name: "sql_exec",
+            label: "SQL exec (disabled: read-only policy)",
+            description: SQL_TOOLS_DESCRIPTION,
+            promptSnippet: SQL_TOOLS_DESCRIPTION,
+            parameters: Type.Object({
+                connection: connectionParameter,
+                sql: Type.String({ description: "Write/DDL script; multiple statements separated by ';'." }),
+                confirmationToken: Type.String({
+                    description: "Question id of the APPROVED ask_user_question confirmation (single use).",
+                }),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return envelope(async () => {
+                    void params;
+                    throw new SqlToolError("DB_READ_ONLY_VIOLATION", "sql_exec is disabled: database connections are permanently read-only; DELETE, DROP, and all other mutations are forbidden");
+                }, SQL_EXEC_TIMEOUT_MS);
+            },
+        }),
+        defineTool({
+            name: "sql_schema",
+            label: "SQL schema",
+            description: SQL_TOOLS_DESCRIPTION,
+            promptSnippet: SQL_TOOLS_DESCRIPTION,
+            parameters: Type.Object({
+                connection: connectionParameter,
+                table: Type.Optional(Type.String({ description: "Table name to describe; omit to list all tables/views." })),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return envelope(async () => {
+                    const handle = await registry.connect(params.connection);
+                    if (params.table === undefined || params.table.trim() === "") {
+                        const rows = (await handle.query("SELECT name, type FROM sqlite_master WHERE type IN ('table','view') ORDER BY name"));
+                        return { ok: true, connection: params.connection, tables: rows };
+                    }
+                    const table = assertSafeIdentifier(params.table);
+                    const rows = await handle.query(`PRAGMA table_info(${table})`);
+                    return {
+                        ok: true,
+                        connection: params.connection,
+                        table,
+                        columns: rows.map((r) => ({
+                            name: String(r.name),
+                            type: r.type === null || r.type === undefined ? "" : String(r.type),
+                            notNull: Number(r.notnull ?? r.notNull ?? 0) === 1,
+                            pk: Number(r.pk ?? 0) > 0,
+                        })),
+                    };
+                }, SQL_QUERY_TIMEOUT_MS);
+            },
+        }),
+        defineTool({
+            name: "sql_stats",
+            label: "SQL stats",
+            description: SQL_TOOLS_DESCRIPTION,
+            promptSnippet: SQL_TOOLS_DESCRIPTION,
+            parameters: Type.Object({ connection: connectionParameter }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return envelope(async () => {
+                    const handle = await registry.connect(params.connection);
+                    const tables = (await handle.query("SELECT name FROM sqlite_master WHERE type IN ('table','view') ORDER BY name"));
+                    const rowsByTable = {};
+                    for (const t of tables) {
+                        const name = assertSafeIdentifier(t.name);
+                        const countRows = await handle.query(`SELECT COUNT(*) AS n FROM ${name}`);
+                        rowsByTable[name] = Number(countRows[0]?.n ?? 0);
+                    }
+                    const config = registry.get(params.connection);
+                    let sizeBytes;
+                    if (config?.path) {
+                        try {
+                            sizeBytes = (await stat(path.resolve(config.path))).size;
+                        }
+                        catch {
+                            sizeBytes = undefined;
+                        }
+                    }
+                    return {
+                        ok: true,
+                        connection: params.connection,
+                        tableCount: tables.length,
+                        tables: rowsByTable,
+                        ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+                    };
+                }, SQL_EXEC_TIMEOUT_MS);
+            },
+        }),
+        defineTool({
+            name: "sql_health",
+            label: "SQL health",
+            description: SQL_TOOLS_DESCRIPTION,
+            promptSnippet: SQL_TOOLS_DESCRIPTION,
+            parameters: Type.Object({}, { additionalProperties: false }),
+            async execute() {
+                return envelope(async () => {
+                    const results = [];
+                    for (const summary of registry.list()) {
+                        try {
+                            const probe = await registry.test(summary.name);
+                            results.push({
+                                name: summary.name,
+                                engine: summary.engine,
+                                ok: true,
+                                elapsedMs: probe.elapsedMs,
+                            });
+                        }
+                        catch (error) {
+                            results.push({
+                                name: summary.name,
+                                engine: summary.engine,
+                                ok: false,
+                                code: mapRegistryCode(error instanceof Error && "code" in error
+                                    ? String(error.code)
+                                    : ""),
+                                message: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                    }
+                    return {
+                        ok: true,
+                        connections: results,
+                        readOnlyMode: true,
+                        writeGate: "ask_user_question",
+                        maxRowsDefault: SQL_MAX_ROWS_DEFAULT,
+                        maxRowsLimit: SQL_MAX_ROWS_LIMIT,
+                        queryTimeoutMs: SQL_QUERY_TIMEOUT_MS,
+                        execTimeoutMs: SQL_EXEC_TIMEOUT_MS,
+                    };
+                }, SQL_EXEC_TIMEOUT_MS);
+            },
+        }),
+        defineTool({
+            name: "sql_connections",
+            label: "SQL connections",
+            description: SQL_TOOLS_DESCRIPTION,
+            promptSnippet: SQL_TOOLS_DESCRIPTION,
+            parameters: Type.Object({
+                action: Type.Union([
+                    Type.Literal("list"),
+                    Type.Literal("add"),
+                    Type.Literal("remove"),
+                    Type.Literal("test"),
+                ]),
+                name: Type.Optional(Type.String()),
+                engine: Type.Optional(Type.Union([
+                    Type.Literal("sqlite"),
+                    Type.Literal("postgres"),
+                    Type.Literal("mysql"),
+                ])),
+                path: Type.Optional(Type.String({ description: "sqlite only: ABSOLUTE database file path." })),
+                mode: Type.Optional(Type.Union([Type.Literal("parameters"), Type.Literal("url-env")])),
+                urlEnv: Type.Optional(Type.String({ description: "advanced postgres/mysql mode: env var NAME holding the full DSN." })),
+                host: Type.Optional(Type.String({ description: "postgres/mysql host name or IP address." })),
+                port: Type.Optional(Type.Number({ description: "optional port; defaults to 5432 for PostgreSQL or 3306 for MySQL." })),
+                database: Type.Optional(Type.String({ description: "postgres/mysql database name." })),
+                username: Type.Optional(Type.String({ description: "postgres/mysql user name." })),
+                passwordEnv: Type.Optional(Type.String({ description: "env var NAME holding the password; never ask for a password in chat." })),
+                ssl: Type.Optional(Type.Boolean({ description: "enable a TLS/SSL connection." })),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return envelope(async () => {
+                    if (params.action === "list") {
+                        return { ok: true, connections: registry.list() };
+                    }
+                    if (params.action === "add") {
+                        if (!params.name || !params.engine) {
+                            throw new SqlToolError("DB_INVALID_CONFIG", "action=add requires name and engine");
+                        }
+                        const summary = await registry.add({
+                            name: params.name,
+                            engine: params.engine,
+                            ...(params.path ? { path: params.path } : {}),
+                            ...(params.mode ? { mode: params.mode } : {}),
+                            ...(params.urlEnv ? { urlEnv: params.urlEnv } : {}),
+                            ...(params.host ? { host: params.host } : {}),
+                            ...(params.port !== undefined ? { port: params.port } : {}),
+                            ...(params.database ? { database: params.database } : {}),
+                            ...(params.username ? { username: params.username } : {}),
+                            ...(params.passwordEnv ? { passwordMode: "environment", passwordEnv: params.passwordEnv } : {}),
+                            ...(params.ssl !== undefined ? { ssl: params.ssl } : {}),
+                        });
+                        return {
+                            ok: true,
+                            added: { name: summary.name, engine: summary.engine },
+                            note: "connection registered; run action=\"test\" before first real use",
+                        };
+                    }
+                    if (params.action === "remove") {
+                        if (!params.name) {
+                            throw new SqlToolError("DB_INVALID_CONFIG", "action=remove requires name");
+                        }
+                        await registry.remove(params.name);
+                        return { ok: true, removed: params.name };
+                    }
+                    // action === "test"
+                    if (!params.name) {
+                        throw new SqlToolError("DB_INVALID_CONFIG", "action=test requires name");
+                    }
+                    const probe = await registry.test(params.name);
+                    return {
+                        ok: true,
+                        name: probe.name,
+                        engine: probe.engine,
+                        elapsedMs: probe.elapsedMs,
+                    };
+                }, SQL_QUERY_TIMEOUT_MS);
+            },
+        }),
+    ];
+}