@hienlh/ppm 0.23.13 → 0.23.15

package/src/services/db-ai-tools/db-ai-run.ts

@@ -0,0 +1,199 @@
+import { commitsByItself } from "../../shared/db-ai-tools.ts";
+import { splitSqlScript, sqlCode } from "../../shared/split-sql-statements.ts";
+import { dialectNameOf, type DbType, type DialectName } from "../../shared/db-types.ts";
+import type { QueryStatementResult } from "../../shared/db-query-script.ts";
+import type { DbQuerySession } from "../../types/database.ts";
+import { QueryStatementError } from "../database/db-errors.ts";
+import { QueryScriptRun, type QueryScriptSummary } from "../database/query-script-runner.ts";
+
+/**
+ * The database tools' runs, on a session the caller opened with the tool's own `readonly`:
+ *
+ * - `db_query` is the Query tab's run (`QueryScriptRun`) on a read-only session, so a write
+ *   hidden in a function call is refused by the database itself, as it is everywhere in PPM.
+ * - `db_execute` runs the script the user approved, once, inside one transaction PPM opens and
+ *   ends itself: committed only when every statement succeeded and the rows changed in all are
+ *   the ones the AI said to expect, rolled back otherwise. MySQL and MariaDB commit a CREATE,
+ *   ALTER, DROP or TRUNCATE by itself, with everything before it, so there the transaction is
+ *   opened again after one, and a run rolled back says which statements were kept all the same.
+ */
+
+export interface AiQueryRun {
+  results: QueryStatementResult[];
+  summary: QueryScriptSummary;
+  /** What the run said about itself rather than a statement: a transaction left open, rolled back. */
+  messages: string[];
+}
+
+/** Runs `sql` statement by statement and closes the session. Never throws. */
+export async function runAiQuery(session: DbQuerySession, opts: { sql: string; dialect: DialectName; maxRows: number; timeoutMs?: number }): Promise<AiQueryRun> {
+  const results: QueryStatementResult[] = [];
+  const messages: string[] = [];
+  const run = new QueryScriptRun({ sql: opts.sql, dialect: opts.dialect, maxRows: opts.maxRows, timeoutMs: opts.timeoutMs });
+  const summary = await run.execute(session, (event) => {
+    if (event.type === "statement") results.push(event.result);
+    else if (event.type === "message") messages.push(event.text);
+    else if (event.type === "done" && event.error !== undefined) messages.push(event.error);
+  });
+  return { results, summary, messages };
+}
+
+/** Statements that begin or end a transaction: PPM opens and ends the one `db_execute` runs in. */
+const TRANSACTION_CONTROL = /^\s*(begin|start\s+transaction|commit|end|rollback|abort|savepoint|release|prepare\s+transaction)\b/i;
+
+/** The first statement of `sql` that controls the transaction, or null. */
+export function transactionControlIn(sql: string, dialect: DialectName): string | null {
+  for (const statement of splitSqlScript(sql, dialect)) {
+    if (TRANSACTION_CONTROL.test(sqlCode(statement.sql, dialect))) return statement.sql.trim().split(/\s+/).slice(0, 3).join(" ");
+  }
+  return null;
+}
+
+export type ApprovedRunReport =
+  | { committed: true; results: QueryStatementResult[]; rowsChanged: number }
+  /**
+   * Rolled back, or never begun. `kept` counts the statements, from the first, that the database
+   * had committed by itself before then — only MySQL and MariaDB do — and is 0 when nothing the
+   * script did was kept. `mayHaveKept`, more than `kept`, is set when the connection went before
+   * the database could say whether the statement then running had ended the transaction: read
+   * from the SQL, statements 1 to it may be in the database too.
+   */
+  | { committed: false; results: QueryStatementResult[]; rowsChanged: number; kept: number; mayHaveKept?: number; reason: string };
+
+const BEGIN: Record<DialectName, string> = { postgres: "BEGIN", sqlite: "BEGIN", mysql: "START TRANSACTION" };
+
+const errorText = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+const COMMITS_BY_ITSELF = "MySQL and MariaDB commit a CREATE, ALTER, DROP or TRUNCATE by itself, with everything before it";
+
+/** `statement 2`, or `statements 1–3`. */
+const statementsLabel = (from: number, to: number): string => (from === to ? `statement ${from}` : `statements ${from}–${to}`);
+
+/**
+ * Runs the approved script inside one transaction on `session` (writable), and closes the
+ * session. `expectedRows`, when given, must equal the rows the statements changed in all.
+ * Never throws: what went wrong is in the report.
+ */
+export async function runApprovedScript(session: DbQuerySession, opts: {
+  sql: string;
+  dbType: DbType;
+  maxRows: number;
+  expectedRows?: number;
+  /** How long one statement may run before it is cancelled. */
+  timeoutMs?: number;
+}): Promise<ApprovedRunReport> {
+  const dialect = dialectNameOf(opts.dbType);
+  const results: QueryStatementResult[] = [];
+  let rowsChanged = 0;
+  let begun = false;
+  /**
+   * Statements, from the first, that are in the database whatever happens next: MySQL and MariaDB
+   * commit a CREATE, ALTER, DROP or TRUNCATE by itself, with everything before it, and end the
+   * transaction there. PPM then opens it again, so that what follows can still be rolled back.
+   */
+  let kept = 0;
+  /**
+   * Set above `kept` when the connection went before the database could say whether the statement
+   * then running had ended the transaction. The SQL says whether it may have (`commitsByItself`),
+   * so the report says what may be in the database instead of claiming that nothing is.
+   */
+  let mayHaveKept = 0;
+  /** False once a statement has ended the transaction, which only MySQL and MariaDB do. */
+  const stillOpen = async (): Promise<boolean> => !session.transactionOpen || await session.transactionOpen();
+  /** `cause`, and what the run left behind: nothing, the first `kept` statements, or maybe more. */
+  const notKept = (cause: string): string => {
+    if (mayHaveKept > kept) {
+      const unsure = `${statementsLabel(kept + 1, mayHaveKept)} may have been kept`;
+      const keptPart = kept === 0 ? unsure : `${statementsLabel(1, kept)} ${kept === 1 ? "was" : "were"} kept, and ${unsure} too`;
+      return `${cause}, and the database could not be asked what it kept: ${keptPart}, because ${COMMITS_BY_ITSELF}.`;
+    }
+    if (kept === 0) return `${cause}, so the transaction was rolled back and nothing changed.`;
+    const ran = results.filter((r) => r.error === undefined).length;
+    const keptPart = `${statementsLabel(1, kept)} ${kept === 1 ? "was" : "were"} kept`;
+    if (ran <= kept) return `${cause}, but nothing could be rolled back: ${keptPart}, because ${COMMITS_BY_ITSELF}.`;
+    return `${cause}, so ${statementsLabel(kept + 1, ran)} ${ran - kept === 1 ? "was" : "were"} rolled back, but ${keptPart}, because ${COMMITS_BY_ITSELF}.`;
+  };
+  /**
+   * Always `return await`ed: a promise returned unawaited from inside `try` does not hold back its
+   * `finally`, which closes the session under the rollback — and on MySQL the rollback then never
+   * answers, so the tool call hung.
+   */
+  const rolledBack = async (reason: string): Promise<ApprovedRunReport> => {
+    let why = reason;
+    if (begun) {
+      try {
+        await session.rollbackOpenTransaction();
+      } catch (e) {
+        why += ` Rolling back failed too (${errorText(e)}); the database ends the transaction when the connection closes.`;
+      }
+    }
+    return { committed: false, results, rowsChanged, kept, ...(mayHaveKept > kept ? { mayHaveKept } : {}), reason: why };
+  };
+  try {
+    const statements = splitSqlScript(opts.sql, dialect, session.splitOptions);
+    if (statements.length === 0) return { committed: false, results, rowsChanged, kept, reason: "The script has no statements to run." };
+    try {
+      await session.run(BEGIN[dialect], 1);
+      begun = true;
+    } catch (e) {
+      return { committed: false, results, rowsChanged, kept, reason: `The transaction could not be started: ${errorText(e)}` };
+    }
+    for (const [index, statement] of statements.entries()) {
+      const started = performance.now();
+      const base = { index, startLine: statement.startLine, endLine: statement.endLine, sql: statement.sql };
+      let timedOut = false;
+      const timer = opts.timeoutMs === undefined ? null : setTimeout(() => {
+        timedOut = true;
+        session.cancel();
+      }, opts.timeoutMs);
+      try {
+        const outcome = await session.run(statement.sql, opts.maxRows);
+        results.push({
+          ...base,
+          ...(outcome.command ? { command: outcome.command } : {}),
+          resultSets: outcome.resultSets.map(({ columns, rows, truncated }) => ({ columns, rows, ...(truncated ? { truncated: true } : {}) })),
+          ...(outcome.rowsAffected !== undefined ? { rowsAffected: outcome.rowsAffected } : {}),
+          ...(outcome.notices.length > 0 ? { notices: outcome.notices } : {}),
+          durationMs: Math.round(performance.now() - started),
+        });
+        rowsChanged += outcome.rowsAffected ?? 0;
+      } catch (e) {
+        const message = e instanceof QueryStatementError || e instanceof Error ? e.message : String(e);
+        const error = timedOut ? `Stopped after ${Math.round(opts.timeoutMs! / 1000)} s: ${message}` : message;
+        results.push({ ...base, resultSets: [], durationMs: Math.round(performance.now() - started), error, ...(timedOut ? { stopped: "timeout" as const } : {}) });
+        // A statement that ends the transaction ends it before it runs, so even one that then fails
+        // keeps what came before it. When the connection went before the database could say, the
+        // SQL tells whether it may have; any other statement leaves the server to roll back.
+        const open = await stillOpen().catch(() => null);
+        if (open === false) kept = index;
+        else if (open === null && commitsByItself(opts.dbType, statement.sql)) mayHaveKept = index;
+        return await rolledBack(notKept(`Statement ${index + 1} failed`));
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+      const open = await stillOpen().catch((e: unknown) => {
+        // It ran, and the connection went before the database could say whether it ended the
+        // transaction: when the SQL says it does, it and everything before it may be in.
+        if (commitsByItself(opts.dbType, statement.sql)) mayHaveKept = index + 1;
+        throw e;
+      });
+      if (!open) {
+        kept = index + 1;
+        if (index < statements.length - 1) await session.run(BEGIN[dialect], 1);
+      }
+    }
+    if (opts.expectedRows !== undefined && rowsChanged !== opts.expectedRows) {
+      return await rolledBack(notKept(`The script changed ${rowsChanged} ${rowsChanged === 1 ? "row" : "rows"} in all, not the ${opts.expectedRows} expected`));
+    }
+    try {
+      await session.run("COMMIT", 1);
+    } catch (e) {
+      return await rolledBack(notKept(`COMMIT failed (${errorText(e)})`));
+    }
+    return { committed: true, results, rowsChanged };
+  } catch (e) {
+    return await rolledBack(notKept(`The run broke off (${errorText(e)})`));
+  } finally {
+    await session.close().catch(() => {});
+  }
+}

package/src/services/db-ai-tools/db-ai-target.ts

@@ -0,0 +1,59 @@
+import { decryptConfig, type ConnectionRow } from "../db.service.ts";
+import { DatabaseTargetError, readDatabaseParam, withDatabase } from "../database/connection-database.ts";
+import { missingLogin } from "../database/connection-login.ts";
+import { driverForEngine } from "../database/drivers/db-driver-catalog.ts";
+import { DbDriverMissingError, loadDbDriver } from "../database/drivers/db-driver-loader.ts";
+import { connConfig } from "../../server/routes/database-route-helpers.ts";
+import type { StoredConnectionConfig } from "../../shared/db-connection-config.ts";
+import type { DbConnectionConfig } from "../../types/database.ts";
+
+/**
+ * Where a database tool's SQL runs: the connection's own database or another on its server
+ * (checked as the CONNECTIONS tree checks one), with its driver loaded and its login held.
+ */
+
+/** The `database` argument, checked the way `?database=` is for the CONNECTIONS tree. */
+export function aiDatabaseArg(conn: ConnectionRow, raw: unknown): { ok: true; database?: string } | { ok: false; error: string } {
+  if (raw === undefined || raw === null || raw === "") return { ok: true };
+  if (typeof raw !== "string") return { ok: false, error: "`database` must be a database name." };
+  try {
+    const database = readDatabaseParam(raw);
+    if (database !== undefined) withDatabase(decryptConfig(conn.connection_config), database);
+    return { ok: true, ...(database !== undefined ? { database } : {}) };
+  } catch (e) {
+    if (e instanceof DatabaseTargetError) return { ok: false, error: e.message };
+    throw e;
+  }
+}
+
+async function ensureDrivers(conn: ConnectionRow, saved: StoredConnectionConfig): Promise<void> {
+  const ids = [driverForEngine(conn.type)?.id, saved.type !== "sqlite" && saved.ssh?.enabled ? "ssh" as const : undefined];
+  for (const id of ids) {
+    if (!id) continue;
+    try {
+      await loadDbDriver(id);
+    } catch (e) {
+      if (e instanceof DbDriverMissingError) {
+        throw new Error(`${e.message} Ask the user to install it from Settings → Database Drivers in PPM.`);
+      }
+      throw e;
+    }
+  }
+}
+
+/**
+ * The adapter config the tools open `conn` with: `readonly` is the tool's, not the row's —
+ * `db_query` always reads inside a read-only transaction, and `db_execute` writes only once the
+ * user approved it. Throws an `Error` whose message is for the AI.
+ */
+export async function aiTargetConfig(conn: ConnectionRow, database: string | undefined, readonly: boolean): Promise<DbConnectionConfig> {
+  const saved = decryptConfig(conn.connection_config);
+  await ensureDrivers(conn, saved);
+  if (missingLogin(conn)) {
+    throw new Error(
+      `Connection "${conn.name}" asks for its password, and nobody has logged in to it since PPM started. `
+      + "Ask the user to open it in PPM's Database panel and log in, then call again.",
+    );
+  }
+  return { ...connConfig(conn, database), readonly };
+}

package/src/services/db-ai-tools/db-ai-tools-endpoint.ts

@@ -0,0 +1,225 @@
+import type { ConnectionRow } from "../db.service.ts";
+import { getAdapter } from "../database/adapter-registry.ts";
+import { isReadOnlyQuery } from "../database/readonly-check.ts";
+import { detectOperation, insertQueryLog, type QueryLogInput, type QueryOperation } from "../query-audit/query-audit.service.ts";
+import { createMcpHttpHandler, textResult, type Json } from "../mcp-http-endpoint.ts";
+import { tabOpenBroker, type TabOpenOutcome } from "../tab-tools-mcp/tab-open-broker.ts";
+import { rowsToRecords } from "../../shared/db-grid.ts";
+import { dialectNameOf, type DialectName } from "../../shared/db-types.ts";
+import { splitSqlScript, sqlCode } from "../../shared/split-sql-statements.ts";
+import { neutralizeFences } from "../../shared/untrusted-text.ts";
+import { isPpmTool, ppmToolOffMessage, ppmToolOn } from "../../shared/ppm-tools.ts";
+import {
+  DB_QUERY_TOOL, MAX_DB_TOOL_REASON_CHARS, MAX_DB_TOOL_SQL_CHARS, OPEN_QUERY_TOOL, type DbExecuteApprovalInput,
+} from "../../shared/db-ai-tools.ts";
+import type { TabOpenAsk } from "../../shared/tab-open-protocol.ts";
+import type { DbQuerySession } from "../../types/database.ts";
+import { configService } from "../config.service.ts";
+import { describeAiConnections, findAiConnection } from "./db-ai-connections.ts";
+import { aiDatabaseArg, aiTargetConfig } from "./db-ai-target.ts";
+import { formatStatementResults } from "./db-ai-format.ts";
+import { runAiQuery, runApprovedScript, transactionControlIn } from "./db-ai-run.ts";
+import { dbApprovalBroker, type DbApprovalOutcome } from "./db-approval-broker.ts";
+import {
+  DB_EXECUTE_RESULT_ROWS, DB_EXECUTE_STATEMENT_TIMEOUT_MS, DB_QUERY_DEFAULT_ROWS, DB_QUERY_MAX_ROWS, DB_QUERY_TIMEOUT_MS,
+  OPEN_QUERY_WAIT_MS, dbChangeHint, dbToolDefinitions,
+} from "./db-ai-tools-tool.ts";
+import { dbToolsMcpTokens, type DbToolsTokenBinding } from "./db-ai-tools-tokens.ts";
+
+/**
+ * `/api/db-tools-mcp` — serves `db_query`, `open_query` and `db_execute` to one chat session's
+ * own agent (the MCP plumbing is `mcp-http-endpoint.ts`). Its token reaches the connections the
+ * AI chat may use (`db-ai-connections.ts`) and nothing else: reads run inside a read-only
+ * transaction, and a write runs only once the user approved it in that session's chat, with
+ * PPM's password, exactly as shown. Every statement is in the query audit log as `source: ai`.
+ */
+
+type Approve = (sessionId: string, input: Omit<DbExecuteApprovalInput, "passwordRequired">, signal: AbortSignal) => Promise<DbApprovalOutcome>;
+
+const isObj = (v: unknown): v is Json => !!v && typeof v === "object" && !Array.isArray(v);
+const errorText = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+/** The connection's own query timeout (Advanced tab) when it is shorter than the tool's, else the tool's. */
+function timeoutFor(config: object, toolMs: number): number {
+  const seconds = (config as { queryTimeoutSec?: unknown }).queryTimeoutSec;
+  return typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0 ? Math.min(seconds * 1000, toolMs) : toolMs;
+}
+
+function operationOf(sql: string, dialect: DialectName): QueryOperation {
+  const statements = splitSqlScript(sql, dialect);
+  return statements.length > 1 ? "script" : detectOperation(sqlCode(statements[0]?.sql ?? sql, dialect).trim());
+}
+
+export function createDbToolsMcpHandler(deps: {
+  resolveToken: (token: string | null) => DbToolsTokenBinding | null;
+  openTab: (sessionId: string, req: TabOpenAsk, waitMs: number) => Promise<TabOpenOutcome>;
+  approve: Approve;
+  /** Whether the user has this tool on (Settings → Tools). */
+  enabled: (tool: string) => boolean;
+  openSession?: (conn: ConnectionRow, config: Awaited<ReturnType<typeof aiTargetConfig>>) => Promise<DbQuerySession>;
+}) {
+  const openSession = deps.openSession ?? ((conn, config) => getAdapter(conn.type).openQuerySession(config));
+
+  function audit(conn: ConnectionRow, fields: Omit<QueryLogInput, "connectionId" | "connectionName" | "dbType" | "source" | "actor" | "callerIp" | "callerUa">): void {
+    try {
+      insertQueryLog({
+        connectionId: conn.id, connectionName: conn.name, dbType: conn.type, source: "ai", actor: "agent",
+        callerIp: null, callerUa: "ppm-db-tools", ...fields,
+      });
+    } catch (e) {
+      console.error("[query-audit] failed to log an AI tool's query:", errorText(e));
+    }
+  }
+
+  async function dbQuery(conn: ConnectionRow, database: string | undefined, sql: string, args: Json): Promise<Json> {
+    const dialect = dialectNameOf(conn.type);
+    let maxRows = DB_QUERY_DEFAULT_ROWS;
+    if (args.max_rows !== undefined && args.max_rows !== null) {
+      if (typeof args.max_rows !== "number" || !Number.isInteger(args.max_rows) || args.max_rows < 1 || args.max_rows > DB_QUERY_MAX_ROWS) {
+        return textResult(`\`max_rows\` must be a whole number from 1 to ${DB_QUERY_MAX_ROWS}.`, true);
+      }
+      maxRows = args.max_rows;
+    }
+    const startedAt = Date.now();
+    const base = { operation: operationOf(sql, dialect), sql, ...(database ? { params: { database } } : {}) };
+    if (!isReadOnlyQuery(sql, dialect)) {
+      const message = `db_query only reads, and this SQL writes (or may). ${dbChangeHint(deps.enabled)}`;
+      audit(conn, { ...base, status: "blocked", error: message, durationMs: 0 });
+      return textResult(message, true);
+    }
+    let session: DbQuerySession;
+    let timeoutMs: number;
+    try {
+      const config = await aiTargetConfig(conn, database, true);
+      timeoutMs = timeoutFor(config, DB_QUERY_TIMEOUT_MS);
+      session = await openSession(conn, config);
+    } catch (e) {
+      audit(conn, { ...base, status: "error", error: errorText(e), durationMs: Date.now() - startedAt });
+      return textResult(`Could not open ${conn.name}: ${errorText(e)}`, true);
+    }
+    const run = await runAiQuery(session, { sql, dialect, maxRows, timeoutMs });
+    const last = run.summary.lastResult;
+    audit(conn, {
+      ...base, status: run.summary.status, ...(run.summary.error !== undefined ? { error: run.summary.error } : {}),
+      ...(last ? { rows: rowsToRecords(last.columns, last.rows).records } : {}),
+      rowCount: run.summary.rowCount, durationMs: Date.now() - startedAt,
+    });
+    const statements = splitSqlScript(sql, dialect).length;
+    const parts = [formatStatementResults(run.results, statements, maxRows), ...run.messages.map((m) => neutralizeFences(m))];
+    if (run.summary.status === "blocked") parts.push(`The database refused a write: db_query only reads. ${dbChangeHint(deps.enabled)}`);
+    return textResult(parts.filter(Boolean).join("\n\n"), run.summary.status !== "ok");
+  }
+
+  async function openQuery(sessionId: string, conn: ConnectionRow, database: string | undefined, sql: string): Promise<Json> {
+    const outcome = await deps.openTab(sessionId, {
+      tool: OPEN_QUERY_TOOL,
+      query: {
+        connectionId: conn.id, connectionName: conn.name, dbType: conn.type, connectionColor: conn.color,
+        ...(database ? { database } : {}), sql,
+      },
+    }, OPEN_QUERY_WAIT_MS);
+    const where = `${conn.name}${database ? ` (database ${database})` : ""}`;
+    if (!outcome.ok) {
+      if (outcome.reason === "no-device") return textResult(`${outcome.message} Give the user the SQL to run in a Query tab on ${where} themselves.`, true);
+      return textResult(outcome.message, true);
+    }
+    if (!outcome.result.opened) {
+      const why = outcome.result.error ? neutralizeFences(outcome.result.error.replace(/[\u0000-\u001f\u007f]/g, " ")) : "it gave no reason";
+      return textResult(`The user's device could not open the Query tab: ${why}`, true);
+    }
+    return textResult(`Opened a Query tab on ${where} on the user's device, holding the SQL. Nothing ran: the user runs it from the tab.`);
+  }
+
+  async function dbExecute(sessionId: string, conn: ConnectionRow, database: string | undefined, sql: string, args: Json, signal: AbortSignal): Promise<Json> {
+    const dialect = dialectNameOf(conn.type);
+    const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+    if (!reason) return textResult("`reason` is required: what the change does and why, for the user to read before approving.", true);
+    if (reason.length > MAX_DB_TOOL_REASON_CHARS) return textResult(`\`reason\` is longer than ${MAX_DB_TOOL_REASON_CHARS} characters; say it in a sentence or two.`, true);
+    let expectedRows: number | undefined;
+    if (args.expected_rows !== undefined && args.expected_rows !== null) {
+      if (typeof args.expected_rows !== "number" || !Number.isInteger(args.expected_rows) || args.expected_rows < 0) {
+        return textResult("`expected_rows` must be a whole number from 0.", true);
+      }
+      expectedRows = args.expected_rows;
+    }
+    const control = transactionControlIn(sql, dialect);
+    if (control) {
+      return textResult(`Take \`${control}\` out of the script: PPM runs the whole script in one transaction it opens and ends itself.`, true);
+    }
+    // Checked before the user is asked: approving something that cannot be opened wastes their time.
+    try {
+      await aiTargetConfig(conn, database, false);
+    } catch (e) {
+      return textResult(`Could not open ${conn.name}: ${errorText(e)}`, true);
+    }
+
+    const operation = operationOf(sql, dialect);
+    const base = { operation, sql, params: { ...(database ? { database } : {}), reason, ...(expectedRows !== undefined ? { expectedRows } : {}) } };
+    const answer = await deps.approve(sessionId, {
+      connectionId: conn.id, connectionName: conn.name, dbType: conn.type, group: conn.group_name, color: conn.color,
+      readonly: !!conn.readonly, ...(database ? { database } : {}), sql, reason, ...(expectedRows !== undefined ? { expectedRows } : {}),
+    }, signal);
+    if (!answer.approved) {
+      if (answer.reason === "declined" || answer.reason === "timeout") {
+        audit(conn, { ...base, status: "blocked", error: answer.message, durationMs: 0 });
+      }
+      return textResult(answer.message, true);
+    }
+
+    const startedAt = Date.now();
+    let session: DbQuerySession;
+    let timeoutMs: number;
+    try {
+      const config = await aiTargetConfig(conn, database, false);
+      timeoutMs = timeoutFor(config, DB_EXECUTE_STATEMENT_TIMEOUT_MS);
+      session = await openSession(conn, config);
+    } catch (e) {
+      audit(conn, { ...base, params: { ...base.params, approved: true }, status: "error", error: errorText(e), durationMs: Date.now() - startedAt });
+      return textResult(`The user approved, but ${conn.name} could not be opened, so nothing ran: ${errorText(e)}`, true);
+    }
+    const report = await runApprovedScript(session, { sql, dbType: conn.type, maxRows: DB_EXECUTE_RESULT_ROWS, expectedRows, timeoutMs });
+    const statements = splitSqlScript(sql, dialect).length;
+    audit(conn, {
+      ...base, params: { ...base.params, approved: true, committed: report.committed },
+      status: report.committed ? "ok" : "error", ...(report.committed ? {} : { error: report.reason }),
+      rowCount: report.rowsChanged, durationMs: Date.now() - startedAt,
+    });
+    const detail = formatStatementResults(report.results, statements, DB_EXECUTE_RESULT_ROWS);
+    if (!report.committed) {
+      const kept = report.kept > 0 ? "only part of it was kept" : report.mayHaveKept ? "part of it may have been kept" : "it was not kept";
+      return textResult(`The user approved the change, but ${kept}. ${report.reason}\n\n${detail}`.trim(), true);
+    }
+    const changed = `${report.rowsChanged} ${report.rowsChanged === 1 ? "row" : "rows"} changed in all`;
+    return textResult(`The user approved the change. It ran on ${conn.name}${database ? ` (database ${database})` : ""} in one transaction and was committed: ${changed}.\n\n${detail}`);
+  }
+
+  return createMcpHttpHandler<DbToolsTokenBinding>({
+    serverName: "ppm-db",
+    tokenRequired: "A chat session token is required",
+    resolveToken: deps.resolveToken,
+    tools: () => dbToolDefinitions(describeAiConnections(), deps.enabled),
+    unavailable: (name) => (deps.enabled(name) ? null : ppmToolOffMessage(name)),
+    callTool: async ({ sessionId }, name, rawArgs, signal) => {
+      const args = isObj(rawArgs) ? rawArgs : {};
+      const found = findAiConnection(args.connection);
+      if (!found.ok) return textResult(found.error, true);
+      const conn = found.conn;
+      const target = aiDatabaseArg(conn, args.database);
+      if (!target.ok) return textResult(target.error, true);
+      const sql = typeof args.sql === "string" ? args.sql : "";
+      if (!sql.trim()) return textResult("`sql` is required.", true);
+      if (sql.length > MAX_DB_TOOL_SQL_CHARS) return textResult(`\`sql\` is longer than ${MAX_DB_TOOL_SQL_CHARS} characters; split it into smaller scripts.`, true);
+      if (splitSqlScript(sql, dialectNameOf(conn.type)).length === 0) return textResult("The SQL has no statements to run: only comments or semicolons.", true);
+      if (name === DB_QUERY_TOOL) return dbQuery(conn, target.database, sql, args);
+      if (name === OPEN_QUERY_TOOL) return openQuery(sessionId, conn, target.database, sql);
+      return dbExecute(sessionId, conn, target.database, sql, args, signal);
+    },
+  });
+}
+
+export const dbToolsMcpHandler = createDbToolsMcpHandler({
+  resolveToken: (token) => dbToolsMcpTokens.resolve(token),
+  openTab: (sessionId, req, waitMs) => tabOpenBroker.request(sessionId, req, waitMs),
+  approve: (sessionId, input, signal) => dbApprovalBroker.request(sessionId, input, undefined, signal),
+  enabled: (tool) => isPpmTool(tool) && ppmToolOn(configService.get("ai"), tool),
+});

package/src/services/db-ai-tools/db-ai-tools-tokens.ts

@@ -0,0 +1,33 @@
+import { localServerBaseUrl } from "../server-listen-address.ts";
+import { createSessionTokenStore } from "../mcp-session-tokens.ts";
+import type { DbToolsMcpAccess } from "./db-ai-tools-tool.ts";
+
+/**
+ * Capability tokens for the database tools' MCP endpoint, one per chat session (see
+ * `mcp-session-tokens.ts`). A token reaches the connections the AI chat may use, and its writes
+ * only through an approval shown in that one session's chat. Like the tab tools' token it names
+ * the session alone, so a warm CLI's token is the one its session's first turn mints.
+ */
+
+export const DB_TOOLS_MCP_PATH = "/api/db-tools-mcp";
+export const MAX_DB_TOOLS_MCP_TOKENS = 256;
+
+export interface DbToolsTokenBinding {
+  sessionId: string;
+}
+
+export function createDbToolsMcpTokenStore(max = MAX_DB_TOOLS_MCP_TOKENS) {
+  return createSessionTokenStore<DbToolsTokenBinding>({ max, sameBinding: () => true });
+}
+
+export const dbToolsMcpTokens = createDbToolsMcpTokenStore();
+
+/**
+ * How one session's agent reaches the database tools, or null when it cannot: a process that
+ * serves no HTTP (the CLI) has no endpoint to point at, and no chat to ask for approval in.
+ */
+export function dbToolsMcpAccessFor(sessionId: string): DbToolsMcpAccess | null {
+  const base = localServerBaseUrl();
+  if (!base) return null;
+  return { url: `${base}${DB_TOOLS_MCP_PATH}`, token: dbToolsMcpTokens.mint({ sessionId }) };
+}

package/src/services/db-ai-tools/db-ai-tools-tool.ts

@@ -0,0 +1,131 @@
+import { DB_EXECUTE_TOOL, DB_QUERY_TOOL, OPEN_QUERY_TOOL } from "../../shared/db-ai-tools.ts";
+import { DB_APPROVAL_WAIT_MS } from "./db-approval-broker.ts";
+
+/**
+ * The three tools the database MCP endpoint serves. Their descriptions end with the connections
+ * the AI may use, read when a chat's agent lists the tools, so it can name one without a call.
+ */
+
+export {
+  DB_QUERY_TOOL, OPEN_QUERY_TOOL, DB_EXECUTE_TOOL, DB_TOOLS, CLAUDE_DB_TOOLS_MCP_SERVER, CODEX_DB_TOOLS_MCP_SERVER,
+} from "../../shared/db-ai-tools.ts";
+
+/** Environment variable the Codex app-server reads the bearer token from. */
+export const CODEX_DB_TOOLS_MCP_TOKEN_ENV = "PPM_DB_TOOLS_MCP_TOKEN";
+
+/** Rows each `db_query` result keeps unless the call asks otherwise, and at most. */
+export const DB_QUERY_DEFAULT_ROWS = 100;
+export const DB_QUERY_MAX_ROWS = 1_000;
+/** Rows of a `RETURNING` result `db_execute` keeps. */
+export const DB_EXECUTE_RESULT_ROWS = 100;
+/** One `db_query` statement's time, when the connection sets no shorter query timeout. */
+export const DB_QUERY_TIMEOUT_MS = 2 * 60_000;
+/** One approved statement's time, when the connection sets no query timeout. */
+export const DB_EXECUTE_STATEMENT_TIMEOUT_MS = 30 * 60_000;
+/** How long `open_query` waits for a device to say the tab is open. */
+export const OPEN_QUERY_WAIT_MS = 8_000;
+/**
+ * The providers' own timeout for a call: it must outlast the user's time to answer an approval
+ * and the approved script's run, or the agent would give up on a change that then commits.
+ */
+export const DB_TOOLS_TIMEOUT_MS = DB_APPROVAL_WAIT_MS + DB_EXECUTE_STATEMENT_TIMEOUT_MS + 5 * 60_000;
+
+/** How a provider reaches the endpoint for one session; built by `chatService` per turn. */
+export interface DbToolsMcpAccess {
+  url: string;
+  token: string;
+}
+
+const CONNECTION = { type: "string", description: "The connection's name, as listed below." };
+const DATABASE = {
+  type: "string",
+  description: "Another database on the same server, when the connection allows it; omit for the connection's own.",
+};
+const SQL = { type: "string", description: "One statement or a script of several, separated by semicolons." };
+
+/** Where `db_query` sends the AI for a change, by which of the other two tools the user has on. */
+export function dbChangeHint(on: (tool: string) => boolean): string {
+  const execute = on(DB_EXECUTE_TOOL), open = on(OPEN_QUERY_TOOL);
+  if (execute && open) return "To change data, call db_execute; to give the user a script to run themselves, call open_query.";
+  if (execute) return "To change data, call db_execute, which asks the user to approve it.";
+  if (open) return "To change data, give the user the script with open_query; they run it themselves.";
+  return "You cannot change data: the user turned PPM's tools for that off. Give them the SQL to run themselves.";
+}
+
+/**
+ * The tools, each description ending with `connections` (see `describeAiConnections`). `on` is
+ * which tools the user has on; `db_query` names only those for a change.
+ */
+export function dbToolDefinitions(connections: string, on: (tool: string) => boolean) {
+  return [
+    {
+      name: DB_QUERY_TOOL,
+      title: "Query a database saved in PPM",
+      description:
+        "Run read-only SQL on a database connection the user saved in PPM. PPM connects with the credentials it keeps, "
+        + "so you never need them, and runs the SQL inside a read-only transaction: it cannot change anything. Use it, "
+        + "rather than `ppm db query`, psql or another client, to look at data and schema (information_schema, "
+        + `pg_catalog, sqlite_master). Each result is cut at max_rows. ${dbChangeHint(on)}\n\n${connections}`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          connection: CONNECTION,
+          sql: SQL,
+          database: DATABASE,
+          max_rows: { type: "integer", minimum: 1, maximum: DB_QUERY_MAX_ROWS, description: `Rows each result keeps (default ${DB_QUERY_DEFAULT_ROWS}).` },
+        },
+        required: ["connection", "sql"],
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+      name: OPEN_QUERY_TOOL,
+      title: "Open a Query tab in PPM",
+      description:
+        "Open a PPM Query tab on the user's device, on a database connection saved in PPM, holding SQL you wrote. "
+        + "Nothing runs: the user reads the script and presses Run themselves. Use it when the user wants to run or "
+        + "review a script on their side. The tab opens beside the chat. On a readonly connection the user can still "
+        + "run a change, with \"Run with write access (once)\" and PPM's password."
+        + `\n\n${connections}`,
+      inputSchema: {
+        type: "object",
+        properties: { connection: CONNECTION, sql: SQL, database: DATABASE },
+        required: ["connection", "sql"],
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+      name: DB_EXECUTE_TOOL,
+      title: "Change a database, once the user approves",
+      description:
+        "Run SQL that changes data or schema on a database connection saved in PPM, after the user approves it. PPM "
+        + "shows the user the connection, your reason and the exact SQL, and runs it only after they type PPM's "
+        + `password; nothing runs if they decline or do not answer within ${Math.round(DB_APPROVAL_WAIT_MS / 60_000)} minutes. `
+        + "An approval covers exactly this SQL, once: a changed script needs a new approval. The script runs in one "
+        + "transaction PPM opens and ends, so do not put BEGIN, COMMIT or ROLLBACK in it; if a statement fails, or the "
+        + "rows changed in all are not expected_rows, everything is rolled back. On MySQL and MariaDB, a CREATE, "
+        + "ALTER, DROP or TRUNCATE commits by itself, with everything before it, so only what follows the last one "
+        + "can be rolled back. Look at what the change will touch with db_query first, and pass "
+        + "expected_rows whenever you know it. Readonly connections can be changed this way too: the approval is what "
+        + `lifts it, for this one script.\n\n${connections}`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          connection: CONNECTION,
+          sql: SQL,
+          reason: { type: "string", description: "What the change does and why, in a sentence or two the user reads before approving." },
+          database: DATABASE,
+          expected_rows: {
+            type: "integer", minimum: 0,
+            description: "Rows the script should insert, update or delete in all; any other count rolls it back.",
+          },
+        },
+        required: ["connection", "sql", "reason"],
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    },
+  ];
+}