@elizaos/autonomous 2.0.0-alpha.71 → 2.0.0-alpha.72

package/src/api/database.ts

@@ -1,1357 +0,0 @@
-/**
- * Database management API handlers for the Eliza Control UI.
- *
- * Provides endpoints for:
- * - Database provider configuration (PGLite vs Postgres)
- * - Connection testing for remote Postgres
- * - Table browsing and introspection
- * - Row-level CRUD operations
- * - Raw SQL query execution
- * - Database status and health
- *
- * All data endpoints use the active runtime's database adapter (Drizzle ORM)
- * so they work identically for both PGLite and Postgres.
- */
-
-import dns from "node:dns";
-import type http from "node:http";
-import net from "node:net";
-import { promisify } from "node:util";
-import { type AgentRuntime, logger } from "@elizaos/core";
-import { loadElizaConfig, saveElizaConfig } from "../config/config";
-import type {
-  DatabaseConfig,
-  DatabaseProviderType,
-  PostgresCredentials,
-} from "../config/types.eliza";
-import {
-  isLoopbackHost,
-  normalizeHostLike,
-  normalizeIpForPolicy,
-} from "../security/network-policy";
-import {
-  readJsonBody as parseJsonBody,
-  sendJson,
-  sendJsonError,
-} from "./http-helpers";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-interface DatabaseStatus {
-  provider: DatabaseProviderType;
-  connected: boolean;
-  serverVersion: string | null;
-  tableCount: number;
-  pgliteDataDir: string | null;
-  postgresHost: string | null;
-}
-
-interface TableInfo {
-  name: string;
-  schema: string;
-  rowCount: number;
-  columns: ColumnInfo[];
-}
-
-interface ColumnInfo {
-  name: string;
-  type: string;
-  nullable: boolean;
-  defaultValue: string | null;
-  isPrimaryKey: boolean;
-}
-
-interface QueryResult {
-  columns: string[];
-  rows: Record<string, unknown>[];
-  rowCount: number;
-  durationMs: number;
-}
-
-interface ConnectionTestResult {
-  success: boolean;
-  serverVersion: string | null;
-  error: string | null;
-  durationMs: number;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-async function readJsonBody<T = Record<string, unknown>>(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-): Promise<T | null> {
-  return parseJsonBody(req, res, {
-    maxBytes: 2 * 1024 * 1024,
-  });
-}
-
-/**
- * Safely quote a SQL identifier (table or column name).
- * Postgres uses double-quote escaping: embedded " becomes "".
- */
-function quoteIdent(name: string): string {
-  return `"${name.replace(/"/g, '""')}"`;
-}
-
-/**
- * Build a Postgres connection string from individual credential fields.
- */
-function buildConnectionString(creds: PostgresCredentials): string {
-  if (creds.connectionString) return creds.connectionString;
-  const host = creds.host ?? "localhost";
-  const port = creds.port ?? 5432;
-  const user = encodeURIComponent(creds.user ?? "postgres");
-  const password = creds.password ? encodeURIComponent(creds.password) : "";
-  const database = creds.database ?? "postgres";
-  const auth = password ? `${user}:${password}` : user;
-  const sslParam = creds.ssl ? "?sslmode=require" : "";
-  return `postgresql://${auth}@${host}:${port}/${database}${sslParam}`;
-}
-
-/**
- * Return a copy of credentials with host pinned to a validated IP address.
- * For connection strings, rewrites URL hostname to avoid re-resolution later.
- */
-function withPinnedHost(
-  creds: PostgresCredentials,
-  pinnedHost: string,
-): PostgresCredentials {
-  const normalizedPinned = pinnedHost.replace(/^::ffff:/i, "");
-  const next: PostgresCredentials = { ...creds, host: normalizedPinned };
-  if (next.connectionString) {
-    try {
-      const parsed = new URL(next.connectionString);
-      parsed.hostname = normalizedPinned;
-      // Preserve DNS pinning even when libpq-style query params are present.
-      // `host` / `hostaddr` can override URI hostname; force both to pinned IP.
-      parsed.searchParams.set("host", normalizedPinned);
-      parsed.searchParams.set("hostaddr", normalizedPinned);
-      next.connectionString = parsed.toString();
-    } catch {
-      // Validation has already parsed this once, but if URL rewriting fails,
-      // force builder path to use the pinned host.
-      delete next.connectionString;
-    }
-  }
-  return next;
-}
-
-// ---------------------------------------------------------------------------
-// Host validation — prevent SSRF via database connection endpoints
-// ---------------------------------------------------------------------------
-
-const dnsLookupAll = promisify(dns.lookup);
-
-/**
- * IP ranges that are ALWAYS blocked regardless of bind address.
- * Cloud metadata and "this" network are never legitimate Postgres targets.
- */
-const ALWAYS_BLOCKED_IP_PATTERNS: RegExp[] = [
-  /^169\.254\./, // Link-local / cloud metadata (AWS, GCP, Azure)
-  /^0\./, // "This" network
-  /^fe[89ab][0-9a-f]:/i, // IPv6 link-local fe80::/10
-];
-
-/**
- * Private/internal IP ranges — blocked only when the API is bound to a
- * non-loopback address (i.e. remotely reachable).  When bound to 127.0.0.1
- * (the default), these are allowed since local Postgres is the most common
- * setup and an attacker who can reach the loopback API already has local
- * network access.
- */
-const PRIVATE_IP_PATTERNS: RegExp[] = [
-  /^127\./, // IPv4 loopback
-  /^10\./, // RFC 1918 Class A
-  /^172\.(1[6-9]|2\d|3[01])\./, // RFC 1918 Class B
-  /^192\.168\./, // RFC 1918 Class C
-  /^::1$/, // IPv6 loopback
-  /^f[cd][0-9a-f]{2}:/i, // IPv6 ULA (fc00::/7 includes fc00::–fdff::)
-];
-
-/**
- * Returns true when the API server is bound to a loopback-only address.
- * In that case, private/internal IP ranges are allowed for DB connections
- * since only local processes can reach the API.
- */
-function isApiLoopbackOnly(): boolean {
-  let bind = (process.env.ELIZA_API_BIND ?? "127.0.0.1").trim().toLowerCase();
-  if (!bind) bind = "127.0.0.1";
-
-  // Accept accidental URL-shaped bind values.
-  if (bind.startsWith("http://") || bind.startsWith("https://")) {
-    try {
-      const parsed = new URL(bind);
-      bind = parsed.hostname.toLowerCase();
-    } catch {
-      // Fall through and treat as raw host value.
-    }
-  }
-
-  // [::1]:2138 -> ::1
-  const bracketedIpv6 = /^\[([^\]]+)\](?::\d+)?$/.exec(bind);
-  if (bracketedIpv6?.[1]) {
-    bind = bracketedIpv6[1];
-  } else {
-    // localhost:2138 -> localhost, 127.0.0.1:2138 -> 127.0.0.1
-    const singleColonHostPort = /^([^:]+):(\d+)$/.exec(bind);
-    if (singleColonHostPort?.[1]) {
-      bind = singleColonHostPort[1];
-    }
-  }
-
-  bind = bind.replace(/^\[|\]$/g, "");
-
-  // Reuse the strict loopback classifier to avoid hostname prefix bypasses
-  // such as "127.evil.com" that are not literal 127.0.0.0/8 IPs.
-  return isLoopbackHost(bind);
-}
-
-/**
- * Extract all potential hosts from a Postgres connection string or credentials object.
- * Includes query params like ?host= and ?hostaddr= which Postgres clients honor.
- * Returns empty array if no host can be determined.
- */
-function extractHosts(creds: PostgresCredentials): string[] {
-  if (creds.connectionString) {
-    try {
-      const url = new URL(creds.connectionString);
-      const hosts: string[] = [];
-
-      // PostgreSQL connection strings can have ?host= param that overrides URI hostname
-      const hostParam = url.searchParams.get("host");
-      if (hostParam) {
-        hosts.push(
-          ...hostParam
-            .split(",")
-            .map((h) => normalizeHostLike(h))
-            .filter(Boolean),
-        );
-      }
-
-      // Also check hostaddr param
-      const hostAddrParam = url.searchParams.get("hostaddr");
-      if (hostAddrParam) {
-        hosts.push(
-          ...hostAddrParam
-            .split(",")
-            .map((h) => normalizeHostLike(h))
-            .filter(Boolean),
-        );
-      }
-
-      // Include URI hostname
-      if (url.hostname) {
-        hosts.push(normalizeHostLike(url.hostname));
-      }
-
-      return [...new Set(hosts)];
-    } catch {
-      return []; // Unparseable — will be rejected
-    }
-  }
-  if (creds.host) {
-    const host = normalizeHostLike(creds.host);
-    return host ? [host] : [];
-  }
-  return [];
-}
-
-/**
- * Check whether an IP address falls in a blocked range.
- * When the API is remotely reachable, private ranges are also blocked.
- */
-function isBlockedIp(ip: string): boolean {
-  const normalized = normalizeIpForPolicy(ip);
-  if (ALWAYS_BLOCKED_IP_PATTERNS.some((p) => p.test(normalized))) return true;
-  if (
-    !isApiLoopbackOnly() &&
-    PRIVATE_IP_PATTERNS.some((p) => p.test(normalized))
-  )
-    return true;
-  return false;
-}
-
-/**
- * Validate that all target hosts do not resolve to blocked addresses.
- *
- * Performs DNS resolution to catch hostnames like `metadata.google.internal`
- * or `169.254.169.254.nip.io` that resolve to link-local / cloud metadata
- * IPs.  Also handles IPv6-mapped IPv4 addresses (e.g. `::ffff:169.254.x.y`).
- *
- * Returns a validation result including a pinned host IP when successful.
- */
-async function validateDbHost(
-  creds: PostgresCredentials,
-  opts: { allowUnresolvedHostnames?: boolean } = {},
-): Promise<{ error: string | null; pinnedHost: string | null }> {
-  const hosts = extractHosts(creds);
-  if (hosts.length === 0) {
-    return {
-      error: "Could not determine target host from the provided credentials.",
-      pinnedHost: null,
-    };
-  }
-
-  let pinnedHost: string | null = null;
-
-  for (const host of hosts) {
-    const literalNormalized = normalizeIpForPolicy(host);
-
-    // First check the literal host string (catches raw IPs without DNS lookup)
-    if (isBlockedIp(literalNormalized)) {
-      return {
-        error: `Connection to "${host}" is blocked: link-local and metadata addresses are not allowed.`,
-        pinnedHost: null,
-      };
-    }
-
-    // Literal IPs are already pinned and do not require DNS.
-    if (net.isIP(literalNormalized)) {
-      if (!pinnedHost) pinnedHost = literalNormalized;
-      continue;
-    }
-
-    // Resolve DNS and check all resulting IPs
-    try {
-      const results = await dnsLookupAll(host, { all: true });
-      const addresses = Array.isArray(results) ? results : [results];
-      for (const entry of addresses) {
-        const ip =
-          typeof entry === "string"
-            ? entry
-            : (entry as { address: string }).address;
-        const normalized = normalizeIpForPolicy(ip);
-        if (isBlockedIp(normalized)) {
-          return {
-            error:
-              `Connection to "${host}" is blocked: it resolves to ${ip} ` +
-              `which is a link-local or metadata address.`,
-            pinnedHost: null,
-          };
-        }
-        if (!pinnedHost) pinnedHost = normalized;
-      }
-    } catch {
-      // For "save config" flows we allow unresolved hostnames so users can
-      // persist remote endpoints that are only resolvable from their runtime
-      // network. For "test connection" flows we keep strict DNS requirements.
-      if (!opts.allowUnresolvedHostnames) {
-        return {
-          error:
-            `Connection to "${host}" failed DNS resolution during validation. ` +
-            "Use a resolvable hostname or a literal IP address.",
-          pinnedHost: null,
-        };
-      }
-    }
-  }
-
-  if (!pinnedHost) {
-    if (opts.allowUnresolvedHostnames) {
-      return { error: null, pinnedHost: null };
-    }
-    return {
-      error: "Could not validate any host to a concrete IP address.",
-      pinnedHost: null,
-    };
-  }
-  return { error: null, pinnedHost };
-}
-
-/** Convert a JS value to a SQL literal for use in raw queries. */
-function sqlLiteral(v: unknown): string {
-  if (v === null || v === undefined) return "NULL";
-  if (typeof v === "number") return String(v);
-  if (typeof v === "boolean") return v ? "TRUE" : "FALSE";
-  if (typeof v === "object")
-    return `'${JSON.stringify(v).replace(/'/g, "''")}'::jsonb`;
-  return `'${String(v).replace(/'/g, "''")}'`;
-}
-
-/** Build a "col = val" SQL assignment clause. */
-function sqlAssign(col: string, val: unknown): string {
-  if (val === null || val === undefined) return `${quoteIdent(col)} = NULL`;
-  return `${quoteIdent(col)} = ${sqlLiteral(val)}`;
-}
-
-/** Build a "col = val" or "col IS NULL" SQL WHERE predicate. */
-function sqlPredicate(col: string, val: unknown): string {
-  if (val === null || val === undefined) return `${quoteIdent(col)} IS NULL`;
-  return `${quoteIdent(col)} = ${sqlLiteral(val)}`;
-}
-
-// Cached drizzle-orm sql helper; resolved once on first call.
-let _sqlHelper: { raw: (query: string) => { queryChunks: unknown[] } } | null =
-  null;
-async function getDrizzleSql(): Promise<typeof _sqlHelper> {
-  if (!_sqlHelper) {
-    const drizzle = await import("drizzle-orm");
-    _sqlHelper = drizzle.sql;
-  }
-  return _sqlHelper;
-}
-
-/** Execute raw SQL via the runtime's Drizzle adapter. */
-async function executeRawSql(
-  runtime: AgentRuntime,
-  sqlText: string,
-): Promise<{ rows: Record<string, unknown>[]; columns: string[] }> {
-  const drizzleSql = await getDrizzleSql();
-  const db = runtime.adapter.db as {
-    execute(query: { queryChunks: unknown[] }): Promise<{
-      rows: Record<string, unknown>[];
-      fields?: Array<{ name: string }>;
-    }>;
-  };
-  const rawQuery = drizzleSql?.raw(sqlText);
-  if (!rawQuery) throw new Error("SQL module not available");
-  const result = await db.execute(rawQuery);
-  const rows = Array.isArray(result.rows)
-    ? result.rows
-    : (result as unknown as Record<string, unknown>[]);
-
-  let columns: string[] = [];
-  if (result.fields && Array.isArray(result.fields)) {
-    columns = result.fields.map((f: { name: string }) => f.name);
-  } else if (rows.length > 0) {
-    columns = Object.keys(rows[0]);
-  }
-
-  return { rows, columns };
-}
-
-/**
- * Detect the current database provider from environment / runtime state.
- */
-function detectCurrentProvider(): DatabaseProviderType {
-  return process.env.POSTGRES_URL ? "postgres" : "pglite";
-}
-
-/** Verify a table name refers to a real user table. */
-async function assertTableExists(
-  runtime: AgentRuntime,
-  tableName: string,
-): Promise<boolean> {
-  const safe = tableName.replace(/'/g, "''");
-  const { rows } = await executeRawSql(
-    runtime,
-    `SELECT 1 FROM information_schema.tables
-     WHERE table_name = '${safe}'
-       AND table_schema NOT IN ('pg_catalog', 'information_schema')
-       AND table_type = 'BASE TABLE'
-     LIMIT 1`,
-  );
-  return rows.length > 0;
-}
-
-// ---------------------------------------------------------------------------
-// Route handlers
-// ---------------------------------------------------------------------------
-
-/**
- * GET /api/database/status
- * Returns current connection status, provider, table count, version.
- */
-async function handleGetStatus(
-  _req: http.IncomingMessage,
-  res: http.ServerResponse,
-  runtime: AgentRuntime | null,
-): Promise<void> {
-  const provider = detectCurrentProvider();
-  if (!runtime?.adapter) {
-    sendJson(res, {
-      provider,
-      connected: false,
-      serverVersion: null,
-      tableCount: 0,
-      pgliteDataDir: process.env.PGLITE_DATA_DIR ?? null,
-      postgresHost: null,
-    } satisfies DatabaseStatus);
-    return;
-  }
-
-  const { rows } = await executeRawSql(runtime, "SELECT version()");
-  const serverVersion =
-    rows.length > 0
-      ? String((rows[0] as Record<string, unknown>).version ?? "")
-      : null;
-
-  const tableResult = await executeRawSql(
-    runtime,
-    `SELECT count(*) AS cnt
-       FROM information_schema.tables
-      WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
-        AND table_type = 'BASE TABLE'`,
-  );
-  const tableCount =
-    tableResult.rows.length > 0
-      ? Number((tableResult.rows[0] as Record<string, unknown>).cnt ?? 0)
-      : 0;
-
-  const status: DatabaseStatus = {
-    provider,
-    connected: true,
-    serverVersion,
-    tableCount,
-    pgliteDataDir:
-      provider === "pglite" ? (process.env.PGLITE_DATA_DIR ?? null) : null,
-    postgresHost:
-      provider === "postgres"
-        ? (process.env.POSTGRES_URL?.replace(
-            /^postgresql:\/\/[^@]*@/,
-            "",
-          ).replace(/\/.*$/, "") ?? null)
-        : null,
-  };
-
-  sendJson(res, status);
-}
-
-/**
- * GET /api/database/config
- * Returns the persisted database configuration from eliza.json.
- */
-function handleGetConfig(
-  _req: http.IncomingMessage,
-  res: http.ServerResponse,
-): void {
-  const config = loadElizaConfig();
-  const dbConfig: DatabaseConfig = config.database ?? { provider: "pglite" };
-  // Mask the password in the response
-  const sanitized = { ...dbConfig };
-  if (sanitized.postgres?.password) {
-    sanitized.postgres = {
-      ...sanitized.postgres,
-      password: "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022",
-    };
-  }
-  if (sanitized.postgres?.connectionString) {
-    // Mask password in connection string
-    sanitized.postgres = {
-      ...sanitized.postgres,
-      connectionString: sanitized.postgres.connectionString.replace(
-        /:([^@]+)@/,
-        ":\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022@",
-      ),
-    };
-  }
-  sendJson(res, {
-    config: sanitized,
-    activeProvider: detectCurrentProvider(),
-    needsRestart: (dbConfig.provider ?? "pglite") !== detectCurrentProvider(),
-  });
-}
-
-/**
- * PUT /api/database/config
- * Saves new database configuration. Does NOT restart the agent automatically;
- * the UI prompts the user to restart.
- */
-async function handlePutConfig(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-): Promise<void> {
-  const body = await readJsonBody<DatabaseConfig>(req, res);
-  if (!body) return;
-
-  // Validate
-  if (
-    body.provider &&
-    body.provider !== "pglite" &&
-    body.provider !== "postgres"
-  ) {
-    sendJsonError(
-      res,
-      `Invalid provider: ${String(body.provider)}. Must be "pglite" or "postgres".`,
-    );
-    return;
-  }
-
-  // Load current config so validation can account for unchanged provider.
-  const config = loadElizaConfig();
-  const existingDb = config.database ?? {};
-  const effectiveProvider =
-    body.provider ?? existingDb.provider ?? ("pglite" as DatabaseProviderType);
-  let validatedPostgres: PostgresCredentials | null = null;
-
-  if (body.postgres) {
-    const pg = body.postgres;
-    if (effectiveProvider === "postgres" && !pg.connectionString && !pg.host) {
-      sendJsonError(
-        res,
-        "Postgres configuration requires either a connectionString or at least a host.",
-      );
-      return;
-    }
-
-    const validation = await validateDbHost(pg, {
-      allowUnresolvedHostnames: Boolean(pg.connectionString),
-    });
-    if (validation.error) {
-      sendJsonError(res, validation.error);
-      return;
-    }
-    validatedPostgres = validation.pinnedHost
-      ? withPinnedHost(pg, validation.pinnedHost)
-      : pg;
-  }
-
-  // Merge: keep existing postgres/pglite sub-configs unless explicitly provided
-  const merged: DatabaseConfig = {
-    ...existingDb,
-    ...body,
-  };
-
-  // If switching to postgres, ensure postgres config is present
-  if (merged.provider === "postgres" && body.postgres) {
-    merged.postgres = {
-      ...existingDb.postgres,
-      ...(validatedPostgres ?? body.postgres),
-    };
-  }
-  // If switching to pglite, ensure pglite config is present
-  if (merged.provider === "pglite" && body.pglite) {
-    merged.pglite = { ...existingDb.pglite, ...body.pglite };
-  }
-
-  config.database = merged;
-  saveElizaConfig(config);
-
-  logger.info(
-    { src: "database-api", provider: merged.provider },
-    "Database configuration saved",
-  );
-
-  sendJson(res, {
-    saved: true,
-    config: merged,
-    needsRestart: (merged.provider ?? "pglite") !== detectCurrentProvider(),
-  });
-}
-
-/**
- * POST /api/database/test
- * Tests a Postgres connection without persisting anything.
- * Body: { connectionString?, host?, port?, user?, password?, database?, ssl? }
- */
-async function handleTestConnection(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-): Promise<void> {
-  const body = await readJsonBody<PostgresCredentials>(req, res);
-  if (!body) return;
-
-  const validation = await validateDbHost(body);
-  if (validation.error) {
-    sendJsonError(res, validation.error);
-    return;
-  }
-
-  const pinnedCreds = validation.pinnedHost
-    ? withPinnedHost(body, validation.pinnedHost)
-    : body;
-  const connectionString = buildConnectionString(pinnedCreds);
-  const start = Date.now();
-
-  // Dynamically import pg to avoid hard-coupling (it is a peer dep via plugin-sql)
-  let Pool: typeof import("pg").Pool;
-  try {
-    const pgModule = await import("pg");
-    Pool = pgModule.default?.Pool ?? pgModule.Pool;
-  } catch {
-    sendJson(res, {
-      success: false,
-      serverVersion: null,
-      error:
-        "PostgreSQL client library (pg) is not available. Ensure @elizaos/plugin-sql is installed.",
-      durationMs: Date.now() - start,
-    } satisfies ConnectionTestResult);
-    return;
-  }
-
-  const pool = new Pool({
-    connectionString,
-    max: 1,
-    connectionTimeoutMillis: 10000,
-    idleTimeoutMillis: 5000,
-  });
-
-  let client: import("pg").PoolClient | null = null;
-  try {
-    client = await pool.connect();
-    const versionResult = await client.query("SELECT version()");
-    const serverVersion = String(versionResult.rows[0]?.version ?? "");
-    const durationMs = Date.now() - start;
-
-    sendJson(res, {
-      success: true,
-      serverVersion,
-      error: null,
-      durationMs,
-    } satisfies ConnectionTestResult);
-  } catch (err) {
-    const durationMs = Date.now() - start;
-    const message = err instanceof Error ? err.message : String(err);
-    sendJson(res, {
-      success: false,
-      serverVersion: null,
-      error: message,
-      durationMs,
-    } satisfies ConnectionTestResult);
-  } finally {
-    if (client) client.release();
-    await pool.end();
-  }
-}
-
-/**
- * GET /api/database/tables
- * Lists all user tables with column metadata and approximate row counts.
- */
-async function handleGetTables(
-  _req: http.IncomingMessage,
-  res: http.ServerResponse,
-  runtime: AgentRuntime,
-): Promise<void> {
-  // Get all user tables
-  const tablesResult = await executeRawSql(
-    runtime,
-    `SELECT
-       t.table_schema AS schema,
-       t.table_name AS name,
-       COALESCE(s.n_live_tup, 0) AS row_count
-     FROM information_schema.tables t
-     LEFT JOIN pg_stat_user_tables s
-       ON s.schemaname = t.table_schema
-       AND s.relname = t.table_name
-     WHERE t.table_schema NOT IN ('pg_catalog', 'information_schema')
-       AND t.table_type = 'BASE TABLE'
-     ORDER BY t.table_schema, t.table_name`,
-  );
-
-  // Get columns for all tables in one query
-  const columnsResult = await executeRawSql(
-    runtime,
-    `SELECT
-       c.table_schema AS schema,
-       c.table_name AS table_name,
-       c.column_name AS name,
-       c.data_type AS type,
-       (c.is_nullable = 'YES') AS nullable,
-       c.column_default AS default_value,
-       COALESCE(
-         (SELECT true
-          FROM information_schema.table_constraints tc
-          JOIN information_schema.key_column_usage kcu
-            ON tc.constraint_name = kcu.constraint_name
-           AND tc.table_schema = kcu.table_schema
-          WHERE tc.constraint_type = 'PRIMARY KEY'
-            AND tc.table_schema = c.table_schema
-            AND tc.table_name = c.table_name
-            AND kcu.column_name = c.column_name),
-         false
-       ) AS is_primary_key
-     FROM information_schema.columns c
-     WHERE c.table_schema NOT IN ('pg_catalog', 'information_schema')
-     ORDER BY c.table_schema, c.table_name, c.ordinal_position`,
-  );
-
-  // Group columns by table
-  const columnsByTable = new Map<string, ColumnInfo[]>();
-  for (const row of columnsResult.rows) {
-    const key = `${String(row.schema)}.${String(row.table_name)}`;
-    const cols = columnsByTable.get(key) ?? [];
-    cols.push({
-      name: String(row.name),
-      type: String(row.type),
-      nullable: Boolean(row.nullable),
-      defaultValue:
-        row.default_value != null ? String(row.default_value) : null,
-      isPrimaryKey: Boolean(row.is_primary_key),
-    });
-    columnsByTable.set(key, cols);
-  }
-
-  const tables: TableInfo[] = tablesResult.rows.map((row) => {
-    const key = `${String(row.schema)}.${String(row.name)}`;
-    return {
-      name: String(row.name),
-      schema: String(row.schema),
-      rowCount: Number(row.row_count ?? 0),
-      columns: columnsByTable.get(key) ?? [],
-    };
-  });
-
-  sendJson(res, { tables });
-}
-
-/**
- * GET /api/database/tables/:table/rows?offset=0&limit=50&sort=col&order=asc&search=term
- * Paginated row retrieval for a specific table.
- */
-async function handleGetRows(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  runtime: AgentRuntime,
-  tableName: string,
-): Promise<void> {
-  const url = new URL(
-    req.url ?? "/",
-    `http://${req.headers.host ?? "localhost"}`,
-  );
-  const offset = Math.max(0, Number(url.searchParams.get("offset") ?? "0"));
-  const limit = Math.min(
-    500,
-    Math.max(1, Number(url.searchParams.get("limit") ?? "50")),
-  );
-  const sortCol = url.searchParams.get("sort") ?? "";
-  const sortOrder = url.searchParams.get("order") === "desc" ? "DESC" : "ASC";
-  const search = url.searchParams.get("search") ?? "";
-
-  if (!(await assertTableExists(runtime, tableName))) {
-    sendJsonError(res, `Table "${tableName}" not found`, 404);
-    return;
-  }
-
-  // Get column names for this table (for search and sort validation)
-  const safeTableName = tableName.replace(/'/g, "''");
-  const colResult = await executeRawSql(
-    runtime,
-    `SELECT column_name, data_type
-     FROM information_schema.columns
-     WHERE table_name = '${safeTableName}'
-       AND table_schema NOT IN ('pg_catalog', 'information_schema')
-     ORDER BY ordinal_position`,
-  );
-  const columnNames = colResult.rows.map((r) => String(r.column_name));
-  const columnTypes = new Map(
-    colResult.rows.map((r) => [String(r.column_name), String(r.data_type)]),
-  );
-
-  // Validate sort column
-  const validSort = sortCol && columnNames.includes(sortCol) ? sortCol : "";
-
-  // Build search clause: search across all text-castable columns
-  let whereClause = "";
-  if (search.trim()) {
-    // Escape ILIKE special characters: backslash first (since it becomes
-    // the escape character), then the ILIKE wildcards % and _.
-    const escapedSearch = search
-      .replace(/'/g, "''")
-      .replace(/\\/g, "\\\\")
-      .replace(/%/g, "\\%")
-      .replace(/_/g, "\\_");
-    const textColumns = columnNames.filter((col) => {
-      const t = columnTypes.get(col) ?? "";
-      return (
-        t.includes("char") ||
-        t.includes("text") ||
-        t === "uuid" ||
-        t === "jsonb" ||
-        t === "json" ||
-        t === "integer" ||
-        t === "bigint" ||
-        t === "numeric" ||
-        t === "timestamp" ||
-        t.includes("timestamp")
-      );
-    });
-    if (textColumns.length > 0) {
-      const conditions = textColumns.map(
-        (col) =>
-          `${quoteIdent(col)}::text ILIKE '%${escapedSearch}%' ESCAPE '\\'`,
-      );
-      whereClause = `WHERE (${conditions.join(" OR ")})`;
-    }
-  }
-
-  // Count total (with search filter)
-  const countResult = await executeRawSql(
-    runtime,
-    `SELECT count(*) AS total FROM ${quoteIdent(tableName)} ${whereClause}`,
-  );
-  const total = Number(
-    (countResult.rows[0] as Record<string, unknown>)?.total ?? 0,
-  );
-
-  // Fetch rows
-  const orderClause = validSort
-    ? `ORDER BY ${quoteIdent(validSort)} ${sortOrder}`
-    : "";
-  const query = `SELECT * FROM ${quoteIdent(tableName)} ${whereClause} ${orderClause} LIMIT ${limit} OFFSET ${offset}`;
-
-  const result = await executeRawSql(runtime, query);
-
-  sendJson(res, {
-    table: tableName,
-    rows: result.rows,
-    columns: result.columns,
-    total,
-    offset,
-    limit,
-  });
-}
-
-/**
- * POST /api/database/tables/:table/rows
- * Insert a new row. Body: { data: Record<string, unknown> }
- */
-async function handleInsertRow(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  runtime: AgentRuntime,
-  tableName: string,
-): Promise<void> {
-  const body = await readJsonBody<{
-    data: Record<string, unknown>;
-  }>(req, res);
-  if (!body) return;
-
-  if (
-    !body.data ||
-    typeof body.data !== "object" ||
-    Object.keys(body.data).length === 0
-  ) {
-    sendJsonError(res, "Request body must include a non-empty 'data' object.");
-    return;
-  }
-
-  if (!(await assertTableExists(runtime, tableName))) {
-    sendJsonError(res, `Table "${tableName}" not found`, 404);
-    return;
-  }
-
-  const columns = Object.keys(body.data);
-  const values = Object.values(body.data);
-  const colList = columns.map((c) => quoteIdent(c)).join(", ");
-  const valList = values.map(sqlLiteral).join(", ");
-
-  const result = await executeRawSql(
-    runtime,
-    `INSERT INTO ${quoteIdent(tableName)} (${colList}) VALUES (${valList}) RETURNING *`,
-  );
-
-  sendJson(res, { inserted: true, row: result.rows[0] ?? null }, 201);
-}
-
-/**
- * PUT /api/database/tables/:table/rows
- * Update a row. Body: { where: Record<string, unknown>, data: Record<string, unknown> }
- */
-async function handleUpdateRow(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  runtime: AgentRuntime,
-  tableName: string,
-): Promise<void> {
-  const body = await readJsonBody<{
-    where: Record<string, unknown>;
-    data: Record<string, unknown>;
-  }>(req, res);
-  if (!body) return;
-
-  if (!body.where || Object.keys(body.where).length === 0) {
-    sendJsonError(
-      res,
-      "Request body must include a non-empty 'where' object for row identification.",
-    );
-    return;
-  }
-  if (!body.data || Object.keys(body.data).length === 0) {
-    sendJsonError(
-      res,
-      "Request body must include a non-empty 'data' object with fields to update.",
-    );
-    return;
-  }
-
-  const setClauses = Object.entries(body.data).map(([col, val]) =>
-    sqlAssign(col, val),
-  );
-  const whereClauses = Object.entries(body.where).map(([col, val]) =>
-    sqlPredicate(col, val),
-  );
-
-  const result = await executeRawSql(
-    runtime,
-    `UPDATE ${quoteIdent(tableName)}
-        SET ${setClauses.join(", ")}
-      WHERE ${whereClauses.join(" AND ")}
-      RETURNING *`,
-  );
-
-  if (result.rows.length === 0) {
-    sendJsonError(res, "No matching row found to update.", 404);
-    return;
-  }
-
-  sendJson(res, { updated: true, row: result.rows[0] });
-}
-
-/**
- * DELETE /api/database/tables/:table/rows
- * Delete a row. Body: { where: Record<string, unknown> }
- */
-async function handleDeleteRow(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  runtime: AgentRuntime,
-  tableName: string,
-): Promise<void> {
-  const body = await readJsonBody<{
-    where: Record<string, unknown>;
-  }>(req, res);
-  if (!body) return;
-
-  if (!body.where || Object.keys(body.where).length === 0) {
-    sendJsonError(
-      res,
-      "Request body must include a non-empty 'where' object for row identification.",
-    );
-    return;
-  }
-
-  const whereClauses = Object.entries(body.where).map(([col, val]) =>
-    sqlPredicate(col, val),
-  );
-
-  const result = await executeRawSql(
-    runtime,
-    `DELETE FROM ${quoteIdent(tableName)}
-      WHERE ${whereClauses.join(" AND ")}
-      RETURNING *`,
-  );
-
-  if (result.rows.length === 0) {
-    sendJsonError(res, "No matching row found to delete.", 404);
-    return;
-  }
-
-  sendJson(res, { deleted: true, row: result.rows[0] });
-}
-
-/**
- * POST /api/database/query
- * Execute a raw SQL query. Body: { sql: string, readOnly?: boolean }
- */
-async function handleQuery(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  runtime: AgentRuntime,
-): Promise<void> {
-  const body = await readJsonBody<{
-    sql: string;
-    readOnly?: boolean;
-  }>(req, res);
-  if (!body) return;
-
-  if (
-    !body.sql ||
-    typeof body.sql !== "string" ||
-    body.sql.trim().length === 0
-  ) {
-    sendJsonError(res, "Request body must include a non-empty 'sql' string.");
-    return;
-  }
-
-  const sqlText = body.sql.trim();
-
-  // If readOnly mode, reject mutation statements.
-  // Strip SQL comments, then scan for mutation keywords *anywhere* in the
-  // query — not just the leading keyword. This prevents bypass via CTEs
-  // (WITH ... AS (DELETE ...)) and other SQL constructs that nest mutations.
-  if (body.readOnly !== false) {
-    // Strip block comments (/* ... */) and line comments (-- ...).
-    // Use empty-string replacement (not space) to mirror how PostgreSQL
-    // concatenates tokens across comments — e.g. DE/* */LETE → DELETE.
-    // A space replacement would turn it into "DE LETE", hiding the keyword.
-    const stripped = sqlText
-      .replace(/\/\*[\s\S]*?\*\//g, "")
-      .replace(/--.*$/gm, "")
-      .trim();
-
-    // Strip string literals so that mutation keywords/functions inside quoted
-    // strings are ignored. Handles single-quoted ('...'), dollar-quoted
-    // ($$...$$), and tagged dollar-quoted ($tag$...$tag$) strings.
-    const noLiterals = stripped
-      .replace(/\$([A-Za-z0-9_]*)\$[\s\S]*?\$\1\$/g, " ")
-      .replace(/'(?:[^']|'')*'/g, " ");
-
-    // For keyword checks, also strip double-quoted identifiers to avoid
-    // matching words inside quoted table/column names.
-    const noStrings = noLiterals.replace(/"(?:[^"]|"")*"/g, " ");
-
-    const mutationKeywords = [
-      // ── DML ────────────────────────────────────────────────────────────
-      "INSERT",
-      "UPDATE",
-      "DELETE",
-      "INTO",
-      "COPY",
-      "MERGE",
-      // ── DDL ────────────────────────────────────────────────────────────
-      "DROP",
-      "ALTER",
-      "TRUNCATE",
-      "CREATE",
-      "COMMENT",
-      // ── Admin / privilege ──────────────────────────────────────────────
-      "GRANT",
-      "REVOKE",
-      "SET",
-      "RESET",
-      "LOAD",
-      // ── Maintenance ────────────────────────────────────────────────────
-      "VACUUM",
-      "REINDEX",
-      "CLUSTER",
-      "REFRESH",
-      "DISCARD",
-      // ── Procedural ─────────────────────────────────────────────────────
-      "CALL",
-      "DO",
-      // ── Async notifications (side-effects) ─────────────────────────────
-      "LISTEN",
-      "UNLISTEN",
-      "NOTIFY",
-      // ── Prepared statements (can wrap mutations) ───────────────────────
-      "PREPARE",
-      "EXECUTE",
-      "DEALLOCATE",
-      // ── Locking ────────────────────────────────────────────────────────
-      "LOCK",
-    ];
-    // Match mutation keywords as whole words (word boundary) anywhere in the
-    // query, catching them inside CTEs, subqueries, etc.
-    const mutationPattern = new RegExp(
-      `\\b(${mutationKeywords.join("|")})\\b`,
-      "i",
-    );
-    const match = mutationPattern.exec(noStrings);
-    if (match) {
-      sendJsonError(
-        res,
-        `Query rejected: "${match[1].toUpperCase()}" is a mutation keyword. Set readOnly: false to execute mutations.`,
-      );
-      return;
-    }
-
-    // PostgreSQL built-in functions that can read/write server files, mutate
-    // server state, or cause denial of service.  These appear inside otherwise
-    // valid SELECT expressions, so keyword checks alone won't catch them.
-    //
-    // ── File I/O (arbitrary file read/write on the DB server) ─────────
-    //   lo_import('/etc/passwd')        — load file into large object
-    //   lo_export(oid, '/tmp/evil')     — write large object to file
-    //   lo_unlink(oid)                  — delete large object
-    //   pg_read_file('/etc/passwd')     — read server file (superuser)
-    //   pg_read_binary_file(...)        — same, binary
-    //   pg_write_file(...)              — write to server files (ext. module)
-    //   pg_stat_file(...)               — stat a server file
-    //   pg_ls_dir(...)                  — list server directory
-    //
-    // ── Sequence / state mutation ────────────────────────────────────
-    //   nextval('seq'), setval('seq', n)
-    //
-    // ── Denial of service ────────────────────────────────────────────
-    //   pg_sleep(n)                     — block connection for n seconds
-    //   pg_sleep_for(interval)          — same, interval version
-    //   pg_sleep_until(timestamp)       — same, deadline version
-    //
-    // ── Session / backend control ────────────────────────────────────
-    //   pg_terminate_backend(pid)       — kill another connection
-    //   pg_cancel_backend(pid)          — cancel a running query
-    //   pg_reload_conf()                — reload server configuration
-    //   pg_rotate_logfile()             — rotate the server log
-    //   set_config(name, value, local)  — SET equivalent as function
-    //
-    // ── Advisory locks (can deadlock other connections) ───────────────
-    //   pg_advisory_lock(key)           — session-level advisory lock
-    //   pg_advisory_lock_shared(key)
-    //   pg_try_advisory_lock(key)
-    const dangerousFunctions = [
-      // File I/O
-      "lo_import",
-      "lo_export",
-      "lo_unlink",
-      "lo_put",
-      "lo_from_bytea",
-      "pg_read_file",
-      "pg_read_binary_file",
-      "pg_write_file",
-      "pg_stat_file",
-      "pg_ls_dir",
-      "pg_ls_logdir",
-      "pg_ls_waldir",
-      "pg_ls_tmpdir",
-      "pg_ls_archive_statusdir",
-      // Sequence / state mutation
-      "nextval",
-      "setval",
-      // Denial of service
-      "pg_sleep",
-      "pg_sleep_for",
-      "pg_sleep_until",
-      // Session / backend control
-      "pg_terminate_backend",
-      "pg_cancel_backend",
-      "pg_reload_conf",
-      "pg_rotate_logfile",
-      "set_config",
-      // Advisory locks
-      "pg_advisory_lock",
-      "pg_advisory_lock_shared",
-      "pg_try_advisory_lock",
-      "pg_try_advisory_lock_shared",
-      "pg_advisory_xact_lock",
-      "pg_advisory_xact_lock_shared",
-      "pg_advisory_unlock",
-      "pg_advisory_unlock_shared",
-      "pg_advisory_unlock_all",
-    ];
-    const dangerousFnPattern = new RegExp(
-      `(?:^|[^\\w$])"?(?:${dangerousFunctions.join("|")})"?\\s*\\(`,
-      "i",
-    );
-    const fnMatch = dangerousFnPattern.exec(noLiterals);
-    if (fnMatch) {
-      // Extract the function name from the match for the error message.
-      const fnNameMatch = fnMatch[0].match(
-        new RegExp(`(${dangerousFunctions.join("|")})`, "i"),
-      );
-      const fnName = fnNameMatch ? fnNameMatch[1].toUpperCase() : "UNKNOWN";
-      sendJsonError(
-        res,
-        `Query rejected: "${fnName}" is a dangerous function that can modify server state. Set readOnly: false to execute this query.`,
-      );
-      return;
-    }
-
-    // Reject multi-statement queries (naive: any semicolon not at the very end)
-    const trimmedForSemicolon = stripped.replace(/;\s*$/, "");
-    if (trimmedForSemicolon.includes(";")) {
-      sendJsonError(
-        res,
-        "Query rejected: multi-statement queries are not allowed in read-only mode.",
-      );
-      return;
-    }
-  }
-
-  const start = Date.now();
-  const result = await executeRawSql(runtime, sqlText);
-  const durationMs = Date.now() - start;
-
-  const queryResult: QueryResult = {
-    columns: result.columns,
-    rows: result.rows,
-    rowCount: result.rows.length,
-    durationMs,
-  };
-
-  sendJson(res, queryResult);
-}
-
-// ---------------------------------------------------------------------------
-// Router
-// ---------------------------------------------------------------------------
-
-/**
- * Route a database API request. Returns true if handled, false if not matched.
- *
- * Expected URL patterns:
- *   GET    /api/database/status
- *   GET    /api/database/config
- *   PUT    /api/database/config
- *   POST   /api/database/test
- *   GET    /api/database/tables
- *   GET    /api/database/tables/:table/rows
- *   POST   /api/database/tables/:table/rows
- *   PUT    /api/database/tables/:table/rows
- *   DELETE /api/database/tables/:table/rows
- *   POST   /api/database/query
- */
-export async function handleDatabaseRoute(
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-  runtime: AgentRuntime | null,
-  pathname: string,
-): Promise<boolean> {
-  const method = req.method ?? "GET";
-
-  // ── GET /api/database/status ──────────────────────────────────────────
-  if (method === "GET" && pathname === "/api/database/status") {
-    await handleGetStatus(req, res, runtime);
-    return true;
-  }
-
-  // ── GET /api/database/config ──────────────────────────────────────────
-  if (method === "GET" && pathname === "/api/database/config") {
-    handleGetConfig(req, res);
-    return true;
-  }
-
-  // ── PUT /api/database/config ──────────────────────────────────────────
-  if (method === "PUT" && pathname === "/api/database/config") {
-    await handlePutConfig(req, res);
-    return true;
-  }
-
-  // ── POST /api/database/test ───────────────────────────────────────────
-  if (method === "POST" && pathname === "/api/database/test") {
-    await handleTestConnection(req, res);
-    return true;
-  }
-
-  // Routes below require a live runtime with a database adapter
-  if (!runtime?.adapter) {
-    sendJsonError(
-      res,
-      "Database not available. The agent may not be running or the database adapter is not initialized.",
-      503,
-    );
-    return true;
-  }
-
-  // ── GET /api/database/tables ──────────────────────────────────────────
-  if (method === "GET" && pathname === "/api/database/tables") {
-    await handleGetTables(req, res, runtime);
-    return true;
-  }
-
-  // ── POST /api/database/query ──────────────────────────────────────────
-  if (method === "POST" && pathname === "/api/database/query") {
-    await handleQuery(req, res, runtime);
-    return true;
-  }
-
-  // ── Table row operations: /api/database/tables/:table/rows ────────────
-  const rowsMatch = pathname.match(/^\/api\/database\/tables\/([^/]+)\/rows$/);
-  if (rowsMatch) {
-    const tableNameDecoded = decodeURIComponent(rowsMatch[1]);
-
-    if (method === "GET") {
-      await handleGetRows(req, res, runtime, tableNameDecoded);
-      return true;
-    }
-    if (method === "POST") {
-      await handleInsertRow(req, res, runtime, tableNameDecoded);
-      return true;
-    }
-    if (method === "PUT") {
-      await handleUpdateRow(req, res, runtime, tableNameDecoded);
-      return true;
-    }
-    if (method === "DELETE") {
-      await handleDeleteRow(req, res, runtime, tableNameDecoded);
-      return true;
-    }
-  }
-
-  return false;
-}