@elizaos/agent 2.0.0-alpha.97 → 2.0.0-beta.1

package/packages/agent/src/api/database.js

@@ -1,1019 +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 net from "node:net";
-import { promisify } from "node:util";
-import { logger } from "@elizaos/core";
-import { loadElizaConfig, saveElizaConfig } from "../config/config";
-import { isLoopbackHost, normalizeHostLike, normalizeIpForPolicy, } from "../security/network-policy";
-import { readJsonBody as parseJsonBody, sendJson, sendJsonError, } from "./http-helpers";
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-async function readJsonBody(req, res) {
-    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) {
-    return `"${name.replace(/"/g, '""')}"`;
-}
-/**
- * Build a Postgres connection string from individual credential fields.
- */
-function buildConnectionString(creds) {
-    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, pinnedHost) {
-    const normalizedPinned = pinnedHost.replace(/^::ffff:/i, "");
-    const next = { ...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 = [
-    /^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 = [
-    /^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() {
-    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) {
-    if (creds.connectionString) {
-        try {
-            const url = new URL(creds.connectionString);
-            const hosts = [];
-            // 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) {
-    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, opts = {}) {
-    const hosts = extractHosts(creds);
-    if (hosts.length === 0) {
-        return {
-            error: "Could not determine target host from the provided credentials.",
-            pinnedHost: null,
-        };
-    }
-    let pinnedHost = 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.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) {
-    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, val) {
-    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, val) {
-    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 = null;
-async function getDrizzleSql() {
-    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, sqlText) {
-    const drizzleSql = await getDrizzleSql();
-    const db = runtime.adapter.db;
-    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;
-    let columns = [];
-    if (result.fields && Array.isArray(result.fields)) {
-        columns = result.fields.map((f) => 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() {
-    return process.env.POSTGRES_URL ? "postgres" : "pglite";
-}
-/** Verify a table name refers to a real user table. */
-async function assertTableExists(runtime, tableName) {
-    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, res, runtime) {
-    const provider = detectCurrentProvider();
-    if (!runtime?.adapter) {
-        sendJson(res, {
-            provider,
-            connected: false,
-            serverVersion: null,
-            tableCount: 0,
-            pgliteDataDir: process.env.PGLITE_DATA_DIR ?? null,
-            postgresHost: null,
-        });
-        return;
-    }
-    const { rows } = await executeRawSql(runtime, "SELECT version()");
-    const serverVersion = rows.length > 0
-        ? String(rows[0].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].cnt ?? 0)
-        : 0;
-    const status = {
-        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, res) {
-    const config = loadElizaConfig();
-    const dbConfig = 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, res) {
-    const body = await readJsonBody(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";
-    let validatedPostgres = 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 = {
-        ...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, res) {
-    const body = await readJsonBody(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;
-    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,
-        });
-        return;
-    }
-    const pool = new Pool({
-        connectionString,
-        max: 1,
-        connectionTimeoutMillis: 10000,
-        idleTimeoutMillis: 5000,
-    });
-    let client = 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,
-        });
-    }
-    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,
-        });
-    }
-    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, res, runtime) {
-    // 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();
-    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 = 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, res, runtime, tableName) {
-    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]?.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, res, runtime, tableName) {
-    const body = await readJsonBody(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, res, runtime, tableName) {
-    const body = await readJsonBody(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, res, runtime, tableName) {
-    const body = await readJsonBody(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, res, runtime) {
-    const body = await readJsonBody(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 = {
-        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, res, runtime, pathname) {
-    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;
-}