Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

45.3 KB
Raw Blame
use serde::de::DeserializeOwned;
use std::time::{Duration, Instant};

use crate::agent_manager::{AgentManager, DEFAULT_JRE_KEY};
use crate::agent_recovery::{RecoveryPolicy, RecoveryScope};
use crate::database_capabilities;
use crate::db::agent_driver::{AgentCallError, AgentDriverClient, AgentLaunchSpec, AgentMethod, AgentRuntimeClient};
use crate::models::connection::DatabaseType;
pub use crate::pl_debug_channel::PlDebugAgentChannel;
use crate::startup_cleanup::StartupReservationCleanup;
pub use crate::startup_cleanup::{StartupCleanup, StartupCleanupGuard, StartupCleanupSnapshot};

type SharedRuntimeCell = std::sync::Arc<tokio::sync::OnceCell<std::sync::Arc<AgentRuntimeClient>>>;
type SharedRuntimeMap = std::sync::Arc<tokio::sync::Mutex<std::collections::HashMap<String, SharedRuntimeCell>>>;

struct DedicatedStartupReservation {
    runtimes: SharedRuntimeMap,
    key: String,
    cell: SharedRuntimeCell,
    transferred: bool,
    cleanup: Option<StartupReservationCleanup>,
}

impl Drop for DedicatedStartupReservation {
    fn drop(&mut self) {
        if self.transferred {
            return;
        }
        if let Some(runtime) = self.cell.get() {
            runtime.kill();
        }
        let cleanup = self.cleanup.take();
        let remove = |runtimes: &mut std::collections::HashMap<String, SharedRuntimeCell>| {
            if runtimes.get(&self.key).is_some_and(|cell| std::sync::Arc::ptr_eq(cell, &self.cell)) {
                runtimes.remove(&self.key);
            }
        };
        if let Ok(mut runtimes) = self.runtimes.try_lock() {
            remove(&mut runtimes);
            if let Some(cleanup) = cleanup {
                cleanup.removed();
            }
        } else {
            let runtimes = self.runtimes.clone();
            let key = self.key.clone();
            let cell = self.cell.clone();
            std::thread::spawn(move || {
                let mut runtimes = runtimes.blocking_lock();
                if runtimes.get(&key).is_some_and(|current| std::sync::Arc::ptr_eq(current, &cell)) {
                    runtimes.remove(&key);
                }
                if let Some(cleanup) = cleanup {
                    cleanup.removed();
                }
            });
        }
    }
}

struct ReservedSharedRuntime {
    key: String,
    cell: SharedRuntimeCell,
    runtime: std::sync::Arc<AgentRuntimeClient>,
}

pub struct SharedConnectionOpenError {
    pub message: String,
    pub runtime: Option<std::sync::Arc<AgentRuntimeClient>>,
}

impl From<String> for SharedConnectionOpenError {
    fn from(message: String) -> Self {
        Self { message, runtime: None }
    }
}

pub fn db_type_to_agent_key(db_type: &DatabaseType, driver_profile: Option<&str>) -> Option<&'static str> {
    database_capabilities::agent_key(db_type, driver_profile)
}

pub fn is_agent_type(db_type: &DatabaseType) -> bool {
    database_capabilities::is_agent_type(db_type)
}

pub async fn stop_daemons(manager: &AgentManager) {
    manager.daemons.lock().await.clear();
    let runtimes = std::mem::take(&mut *manager.connection_runtimes.lock().await);
    for runtime in runtimes.into_values().filter_map(|cell| cell.get().cloned()) {
        runtime.kill_and_wait().await;
    }
}

pub async fn stop_daemon_by_key(manager: &AgentManager, agent_key: &str) {
    manager.daemons.lock().await.remove(agent_key);
    let runtimes = {
        let mut runtimes = manager.connection_runtimes.lock().await;
        let matching =
            runtimes.keys().filter(|key| key.starts_with(&format!("{agent_key}|"))).cloned().collect::<Vec<_>>();
        matching
            .into_iter()
            .filter_map(|key| runtimes.remove(&key).and_then(|cell| cell.get().cloned()))
            .collect::<Vec<_>>()
    };
    for runtime in runtimes {
        runtime.kill_and_wait().await;
    }
}

pub async fn restart_daemon_by_key(manager: &AgentManager, agent_key: &str) -> Result<(), String> {
    manager.daemons.lock().await.remove(agent_key);
    let client = spawn_client_for_key(manager, agent_key, &[], &[]).await?;
    manager.daemons.lock().await.insert(agent_key.to_string(), client);
    Ok(())
}

pub async fn spawn_connection_client(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    extra_java_args: &[String],
) -> Result<AgentDriverClient, String> {
    spawn_connection_client_with_env(manager, db_type, driver_profile, extra_java_args, &[]).await
}

/// Spawns a dedicated agent process whose environment carries `env`.
///
/// Oracle OCI ("thick") connections use this to hand process-scoped client
/// settings (`NLS_LANG`, the Instant Client loader directory) to the agent:
/// those cannot travel as connection parameters, and two connections that
/// disagree about them must never share one process.
pub async fn spawn_connection_client_with_env(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    extra_java_args: &[String],
    env: &[(String, String)],
) -> Result<AgentDriverClient, String> {
    let keys = runtime_agent_key_candidates(db_type, driver_profile)
        .ok_or_else(|| format!("{:?} is not an agent-driven database type", db_type))?;
    spawn_first_available_client(manager, &keys, extra_java_args, env).await
}

pub async fn spawn_shared_connection_client(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    extra_java_args: &[String],
    agent_env: &[(String, String)],
    agent_session_id: String,
    connect_params: serde_json::Value,
    connect_timeout: Duration,
) -> Result<AgentDriverClient, SharedConnectionOpenError> {
    let mut session_params = connect_params;
    session_params
        .as_object_mut()
        .ok_or_else(|| "Agent connect parameters must be an object".to_string())?
        .insert("agentSessionId".to_string(), serde_json::Value::String(agent_session_id.clone()));
    let ReservedSharedRuntime { key, cell, runtime } =
        reserve_shared_connection_runtime(manager, db_type, driver_profile, extra_java_args, agent_env).await?;
    let connect_result = match runtime
        .call_typed::<serde_json::Value>(AgentMethod::OpenSession.as_str(), session_params, Some(connect_timeout), None)
        .await
    {
        Ok(result) => result,
        Err(err) => {
            let open_error = shared_connection_open_error(err, runtime.clone());
            forget_unused_runtime_after_failed_open(manager, &key, &cell, &runtime).await;
            return Err(open_error);
        }
    };
    let mut client = AgentDriverClient::shared_session(runtime, agent_session_id);
    client.apply_connect_result(&connect_result);
    Ok(client)
}

/// Reserve the original process before any OpenSession RPC. `scope` is generated
/// by Core once per registered debug generation, never supplied by the browser.
pub async fn prepare_pl_debug_channel(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    extra_java_args: &[String],
    agent_env: &[(String, String)],
    agent_session_id: String,
    scope: uuid::Uuid,
) -> Result<PlDebugAgentChannel, String> {
    let mut env = agent_env.iter().filter(|(key, _)| key != "DBX_PL_DEBUG_RUNTIME_SCOPE").cloned().collect::<Vec<_>>();
    env.push(("DBX_PL_DEBUG_RUNTIME_SCOPE".into(), scope.to_string()));
    let ReservedSharedRuntime { key, runtime, .. } =
        reserve_shared_connection_runtime(manager, db_type, driver_profile, extra_java_args, &env).await?;
    Ok(PlDebugAgentChannel::from_reserved(runtime, agent_session_id, scope, key))
}

#[allow(clippy::too_many_arguments)]
pub async fn prepare_pl_debug_channel_before(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    extra_java_args: &[String],
    agent_env: &[(String, String)],
    agent_session_id: String,
    scope: uuid::Uuid,
    deadline: Instant,
) -> Result<PlDebugAgentChannel, String> {
    prepare_pl_debug_channel_before_internal(
        manager,
        db_type,
        driver_profile,
        extra_java_args,
        agent_env,
        agent_session_id,
        scope,
        deadline,
        None,
    )
    .await
}

#[allow(clippy::too_many_arguments)]
pub async fn prepare_pl_debug_channel_before_observed(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    extra_java_args: &[String],
    agent_env: &[(String, String)],
    agent_session_id: String,
    scope: uuid::Uuid,
    deadline: Instant,
    startup: StartupCleanupGuard,
) -> Result<PlDebugAgentChannel, String> {
    prepare_pl_debug_channel_before_internal(
        manager,
        db_type,
        driver_profile,
        extra_java_args,
        agent_env,
        agent_session_id,
        scope,
        deadline,
        Some(&startup),
    )
    .await
}

#[allow(clippy::too_many_arguments)]
async fn prepare_pl_debug_channel_before_internal(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    extra_java_args: &[String],
    agent_env: &[(String, String)],
    agent_session_id: String,
    scope: uuid::Uuid,
    deadline: Instant,
    startup: Option<&StartupCleanupGuard>,
) -> Result<PlDebugAgentChannel, String> {
    let timeout = || "PL debug channel preparation deadline exceeded".to_string();
    if Instant::now() >= deadline {
        return Err(timeout());
    }
    let mut env = agent_env.iter().filter(|(key, _)| key != "DBX_PL_DEBUG_RUNTIME_SCOPE").cloned().collect::<Vec<_>>();
    env.push(("DBX_PL_DEBUG_RUNTIME_SCOPE".into(), scope.to_string()));
    let (key, launch) = resolve_shared_runtime_launch(manager, db_type, driver_profile, extra_java_args, &env)?;
    let cell = std::sync::Arc::new(tokio::sync::OnceCell::new());
    let mut runtimes =
        tokio::time::timeout_at(deadline.into(), manager.connection_runtimes.lock()).await.map_err(|_| timeout())?;
    if Instant::now() >= deadline {
        return Err(timeout());
    }
    if runtimes.contains_key(&key) {
        return Err("The original PL debug runtime scope is already reserved".into());
    }
    runtimes.insert(key.clone(), cell.clone());
    let mut reservation = DedicatedStartupReservation {
        runtimes: manager.connection_runtimes.clone(),
        key: key.clone(),
        cell: cell.clone(),
        transferred: false,
        cleanup: startup.map(StartupCleanupGuard::reservation_started),
    };
    drop(runtimes);
    let runtime = cell
        .get_or_try_init(|| async {
            match startup {
                Some(startup) => {
                    AgentRuntimeClient::spawn_before_observed(launch, manager.agent_app_version(), deadline, startup)
                        .await
                }
                None => AgentRuntimeClient::spawn_before(launch, manager.agent_app_version(), deadline).await,
            }
        })
        .await?
        .clone();
    let mut runtimes =
        tokio::time::timeout_at(deadline.into(), manager.connection_runtimes.lock()).await.map_err(|_| timeout())?;
    if Instant::now() >= deadline {
        return Err(timeout());
    }
    if !reserve_runtime_locked(&mut runtimes, &key, &cell, &runtime) {
        return Err("The original PL debug runtime reservation changed during startup".into());
    }
    reservation.transferred = true;
    if let Some(cleanup) = reservation.cleanup.take() {
        cleanup.transferred();
    }
    Ok(PlDebugAgentChannel::from_reserved(runtime, agent_session_id, scope, key))
}

fn resolve_shared_runtime_launch(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    extra_java_args: &[String],
    agent_env: &[(String, String)],
) -> Result<(String, AgentLaunchSpec), String> {
    let keys = runtime_agent_key_candidates(db_type, driver_profile)
        .ok_or_else(|| format!("{:?} is not an agent-driven database type", db_type))?;
    let key = first_installed_agent_key(manager, &keys).unwrap_or(keys[0]);
    let state = manager.load_state();
    let jre_key = state.installed_drivers.get(key).map(|driver| driver.jre.as_str()).unwrap_or(DEFAULT_JRE_KEY);
    let launch = manager.resolve_agent_launch_spec_with_launch_env(&state, key, jre_key, extra_java_args, agent_env)?;
    Ok((shared_runtime_key(key, &launch), launch))
}

async fn reserve_shared_connection_runtime(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    extra_java_args: &[String],
    agent_env: &[(String, String)],
) -> Result<ReservedSharedRuntime, String> {
    let (runtime_key, launch) =
        resolve_shared_runtime_launch(manager, db_type, driver_profile, extra_java_args, agent_env)?;
    let (runtime_cell, runtime) = loop {
        let runtime_cell = {
            let mut runtimes = manager.connection_runtimes.lock().await;
            if runtimes.get(&runtime_key).and_then(|cell| cell.get()).is_some_and(|runtime| runtime.is_failed()) {
                runtimes.remove(&runtime_key);
            }
            runtimes
                .entry(runtime_key.clone())
                .or_insert_with(|| std::sync::Arc::new(tokio::sync::OnceCell::new()))
                .clone()
        };
        let runtime = runtime_cell
            .get_or_try_init(|| AgentRuntimeClient::spawn(launch.clone(), manager.agent_app_version()))
            .await?
            .clone();

        let mut runtimes = manager.connection_runtimes.lock().await;
        if reserve_runtime_locked(&mut runtimes, &runtime_key, &runtime_cell, &runtime) {
            break (runtime_cell, runtime);
        }
    };
    Ok(ReservedSharedRuntime { key: runtime_key, cell: runtime_cell, runtime })
}

fn shared_connection_open_error(
    error: AgentCallError,
    runtime: std::sync::Arc<AgentRuntimeClient>,
) -> SharedConnectionOpenError {
    let runtime = RecoveryPolicy::decide(&error, RecoveryScope::ConnectionOpen).replaces_runtime().then_some(runtime);
    SharedConnectionOpenError { message: error.into_legacy_string(), runtime }
}

async fn forget_unused_runtime_after_failed_open(
    manager: &AgentManager,
    runtime_key: &str,
    runtime_cell: &std::sync::Arc<tokio::sync::OnceCell<std::sync::Arc<AgentRuntimeClient>>>,
    runtime: &std::sync::Arc<AgentRuntimeClient>,
) {
    if AgentRuntimeClient::decrement_session_count(runtime) != 0 {
        return;
    }

    remove_unused_runtime_if_current(manager, runtime_key, runtime_cell, runtime).await;
}

async fn remove_unused_runtime_if_current(
    manager: &AgentManager,
    runtime_key: &str,
    runtime_cell: &std::sync::Arc<tokio::sync::OnceCell<std::sync::Arc<AgentRuntimeClient>>>,
    runtime: &std::sync::Arc<AgentRuntimeClient>,
) {
    // Keep reservation and map-entry validation under the same lock as openers.
    let mut runtimes = manager.connection_runtimes.lock().await;
    if runtime.active_session_count() == 0
        && runtimes.get(runtime_key).is_some_and(|current| std::sync::Arc::ptr_eq(current, runtime_cell))
    {
        runtimes.remove(runtime_key);
    }
}

fn reserve_runtime_locked(
    runtimes: &mut std::collections::HashMap<
        String,
        std::sync::Arc<tokio::sync::OnceCell<std::sync::Arc<AgentRuntimeClient>>>,
    >,
    runtime_key: &str,
    runtime_cell: &std::sync::Arc<tokio::sync::OnceCell<std::sync::Arc<AgentRuntimeClient>>>,
    runtime: &std::sync::Arc<AgentRuntimeClient>,
) -> bool {
    if runtimes.get(runtime_key).is_some_and(|current| std::sync::Arc::ptr_eq(current, runtime_cell))
        && !runtime.is_failed()
    {
        runtime.increment_session_count();
        true
    } else {
        false
    }
}

fn shared_runtime_key(agent_key: &str, launch: &crate::db::agent_driver::AgentLaunchSpec) -> String {
    // `env` is part of the fingerprint on purpose: Oracle Client settings such
    // as `NLS_LANG` are process-scoped, so a connection that declares one must
    // not reuse a process started without it (or with a different value).
    let env = launch.env.iter().map(|(key, value)| format!("{key}={value}")).collect::<Vec<_>>().join("\u{1f}");
    format!(
        "{}|{}|{}|{}|{}",
        agent_key,
        launch.program.display(),
        launch.args.join("\u{1f}"),
        launch.working_dir.as_ref().map(|path| path.display().to_string()).unwrap_or_default(),
        env
    )
}

pub async fn call_daemon<T: DeserializeOwned + Send + 'static>(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    method: &str,
    params: serde_json::Value,
) -> Result<T, String> {
    let keys = runtime_agent_key_candidates(db_type, driver_profile)
        .ok_or_else(|| format!("{:?} is not an agent-driven database type", db_type))?;
    let key = first_installed_agent_key(manager, &keys).unwrap_or(keys[0]).to_string();

    let mut daemons = manager.daemons.lock().await;

    if !daemons.contains_key(&key) {
        let client = spawn_client_for_key(manager, &key, &[], &[]).await?;
        daemons.insert(key.clone(), client);
    }

    let client = daemons.get_mut(&key).unwrap();
    match client.call::<T>(method, params.clone()).await {
        Ok(result) => Ok(result),
        Err(err) => {
            log::warn!("[agent] daemon call failed, respawning: {err}");
            daemons.remove(&key);
            let mut new_client = spawn_client_for_key(manager, &key, &[], &[]).await?;
            let result = new_client.call::<T>(method, params).await?;
            daemons.insert(key, new_client);
            Ok(result)
        }
    }
}

pub async fn call_daemon_with_timeout<T: DeserializeOwned + Send + 'static>(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    method: &str,
    params: serde_json::Value,
    timeout_duration: Option<Duration>,
) -> Result<T, String> {
    let keys = runtime_agent_key_candidates(db_type, driver_profile)
        .ok_or_else(|| format!("{:?} is not an agent-driven database type", db_type))?;
    let key = first_installed_agent_key(manager, &keys).unwrap_or(keys[0]).to_string();

    let mut daemons = manager.daemons.lock().await;

    if !daemons.contains_key(&key) {
        let client = spawn_client_for_key(manager, &key, &[], &[]).await?;
        daemons.insert(key.clone(), client);
    }

    let client = daemons.get_mut(&key).unwrap();
    match client.call_with_timeout::<T>(method, params.clone(), timeout_duration).await {
        Ok(result) => Ok(result),
        Err(err) => {
            log::warn!("[agent] daemon call failed, respawning: {err}");
            daemons.remove(&key);
            let mut new_client = spawn_client_for_key(manager, &key, &[], &[]).await?;
            let result = new_client.call_with_timeout::<T>(method, params, timeout_duration).await?;
            daemons.insert(key, new_client);
            Ok(result)
        }
    }
}

pub async fn call_daemon_method<T: DeserializeOwned + Send + 'static>(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    method: AgentMethod,
    params: serde_json::Value,
) -> Result<T, String> {
    call_daemon(manager, db_type, driver_profile, method.as_str(), params).await
}

pub async fn call_daemon_method_with_timeout<T: DeserializeOwned + Send + 'static>(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    method: AgentMethod,
    params: serde_json::Value,
    timeout_duration: Option<Duration>,
) -> Result<T, String> {
    call_daemon_with_timeout(manager, db_type, driver_profile, method.as_str(), params, timeout_duration).await
}

/// Environment-aware sibling of [`call_daemon_method_with_timeout`].
///
/// A non-empty `env` gets a dedicated, short-lived process instead of the
/// shared per-key daemon: process-scoped Oracle OCI settings (`NLS_LANG`, the
/// Instant Client loader directory) must not leak into a process another
/// connection is already using.
pub async fn call_daemon_method_with_timeout_and_env<T: DeserializeOwned + Send + 'static>(
    manager: &AgentManager,
    db_type: &DatabaseType,
    driver_profile: Option<&str>,
    method: AgentMethod,
    params: serde_json::Value,
    timeout_duration: Option<Duration>,
    env: &[(String, String)],
) -> Result<T, String> {
    if env.is_empty() {
        return call_daemon_with_timeout(manager, db_type, driver_profile, method.as_str(), params, timeout_duration)
            .await;
    }
    let keys = runtime_agent_key_candidates(db_type, driver_profile)
        .ok_or_else(|| format!("{:?} is not an agent-driven database type", db_type))?;
    let key = first_installed_agent_key(manager, &keys).unwrap_or(keys[0]).to_string();
    let mut client = spawn_client_for_key(manager, &key, &[], env).await?;
    client.call_with_timeout::<T>(method.as_str(), params, timeout_duration).await
}

fn runtime_agent_key_candidates(db_type: &DatabaseType, driver_profile: Option<&str>) -> Option<Vec<&'static str>> {
    let primary = db_type_to_agent_key(db_type, driver_profile)?;
    Some(vec![primary])
}

fn first_installed_agent_key<'a>(manager: &AgentManager, keys: &'a [&'static str]) -> Option<&'a str> {
    keys.iter().copied().find(|key| manager.is_driver_installed(key))
}

async fn spawn_first_available_client(
    manager: &AgentManager,
    keys: &[&str],
    extra_java_args: &[String],
    env: &[(String, String)],
) -> Result<AgentDriverClient, String> {
    let mut last_error = None;
    for key in keys {
        match spawn_client_for_key(manager, key, extra_java_args, env).await {
            Ok(client) => return Ok(client),
            Err(err) => last_error = Some(err),
        }
    }
    Err(last_error.unwrap_or_else(|| "No agent driver candidates available".to_string()))
}

async fn spawn_client_for_key(
    manager: &AgentManager,
    key: &str,
    extra_java_args: &[String],
    env: &[(String, String)],
) -> Result<AgentDriverClient, String> {
    let state = manager.load_state();
    let jre_key = state.installed_drivers.get(key).map(|driver| driver.jre.as_str()).unwrap_or(DEFAULT_JRE_KEY);

    let launch = manager
        .resolve_agent_launch_spec_with_extra_args(&state, key, jre_key, extra_java_args)?
        .with_env(env.iter().cloned());
    let mut client = AgentDriverClient::spawn(launch).await?;
    client.try_optional_handshake(manager.agent_app_version()).await;
    Ok(client)
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::PathBuf;

    async fn test_shared_runtime(
        name: &str,
    ) -> (
        AgentManager,
        std::sync::Arc<tokio::sync::OnceCell<std::sync::Arc<AgentRuntimeClient>>>,
        std::sync::Arc<AgentRuntimeClient>,
        PathBuf,
    ) {
        let test_id = uuid::Uuid::new_v4();
        let script_path = std::env::temp_dir().join(format!("dbx-agent-runtime-{name}-{test_id}.py"));
        std::fs::write(
            &script_path,
            r#"import json, sys
print(json.dumps({'ready': True}), flush=True)
for line in sys.stdin:
    req = json.loads(line)
    result = {'protocolVersion': 2, 'agentProtocolVersion': 2, 'capabilities': ['multi_session']} if req['method'] == 'handshake' else {'ok': True}
    print(json.dumps({'jsonrpc': '2.0', 'id': req['id'], 'result': result}), flush=True)
"#,
        )
        .unwrap();
        let python = if cfg!(windows) { "python" } else { "python3" };
        let runtime = AgentRuntimeClient::spawn(
            crate::db::agent_driver::AgentLaunchSpec::new(python)
                .with_args([script_path.to_string_lossy().to_string()]),
            "test",
        )
        .await
        .unwrap();
        let cell = std::sync::Arc::new(tokio::sync::OnceCell::new());
        assert!(cell.set(runtime.clone()).is_ok());
        let manager_dir = std::env::temp_dir().join(format!("dbx-agent-manager-{name}-{test_id}"));
        let manager = AgentManager::new_with_base_dir_and_app_version(manager_dir, "test");
        (manager, cell, runtime, script_path)
    }

    #[test]
    fn prestosql_does_not_use_agent_driver() {
        assert_eq!(runtime_agent_key_candidates(&DatabaseType::PrestoSql, None), None);
    }

    #[tokio::test]
    async fn dedicated_reservation_drop_reaps_original_and_removes_only_its_cell() {
        for replace in [false, true] {
            let (manager, cell, runtime, script) = test_shared_runtime("dedicated-reservation-drop").await;
            let key = "oracle|test-scope".to_string();
            manager.connection_runtimes.lock().await.insert(key.clone(), cell.clone());
            let (startup, cleanup) = StartupCleanup::new_pair();
            let guard = DedicatedStartupReservation {
                runtimes: manager.connection_runtimes.clone(),
                key: key.clone(),
                cell,
                transferred: false,
                cleanup: Some(startup.reservation_started()),
            };
            drop(startup);
            let mut locked = manager.connection_runtimes.lock().await;
            let replacement = std::sync::Arc::new(tokio::sync::OnceCell::new());
            if replace {
                locked.insert(key.clone(), replacement.clone());
            }
            drop(guard);
            assert_eq!(cleanup.snapshot().reservations_pending, 1);
            assert!(!cleanup.snapshot().is_settled());
            drop(locked);
            tokio::time::timeout(Duration::from_secs(3), cleanup.wait_until_settled()).await.unwrap();
            assert!(runtime.wait_for_exit(Duration::from_secs(3)).await);
            if replace {
                assert!(std::sync::Arc::ptr_eq(
                    manager.connection_runtimes.lock().await.get(&key).unwrap(),
                    &replacement
                ));
            } else {
                tokio::time::timeout(Duration::from_secs(3), async {
                    while manager.connection_runtimes.lock().await.contains_key(&key) {
                        tokio::time::sleep(Duration::from_millis(10)).await;
                    }
                })
                .await
                .unwrap();
            }
            runtime.kill_and_wait().await;
            let _ = std::fs::remove_file(script);
        }
    }

    #[tokio::test]
    async fn dedicated_channel_observer_closes_if_entry_future_is_never_polled() {
        let directory = tempfile::tempdir().unwrap();
        let manager = AgentManager::new_with_base_dir(directory.path().join("agents"));
        let (startup, cleanup) = StartupCleanup::new_pair();
        let future = prepare_pl_debug_channel_before_observed(
            &manager,
            &DatabaseType::Oracle,
            None,
            &[],
            &[],
            "inspect".into(),
            uuid::Uuid::new_v4(),
            Instant::now() + Duration::from_secs(5),
            startup,
        );
        assert!(!cleanup.snapshot().producer_closed);
        drop(future);
        assert!(cleanup.snapshot().is_settled());
        assert_eq!(cleanup.snapshot().children_started, 0);
        assert!(manager.connection_runtimes.lock().await.is_empty());
    }

    #[tokio::test]
    async fn dedicated_channel_expired_deadline_does_not_reserve_or_resolve_driver() {
        let directory = tempfile::tempdir().unwrap();
        let manager = AgentManager::new_with_base_dir(directory.path().join("agents"));
        let result = prepare_pl_debug_channel_before(
            &manager,
            &DatabaseType::Oracle,
            None,
            &[],
            &[],
            "inspect".into(),
            uuid::Uuid::new_v4(),
            Instant::now(),
        )
        .await;
        assert!(matches!(result, Err(error) if error.contains("deadline exceeded")));
        assert!(manager.connection_runtimes.lock().await.is_empty());
    }

    #[tokio::test]
    async fn dedicated_channel_startup_cancel_and_timeout_leave_no_runtime_reservation() {
        use std::io::Read;
        for cancel in [false, true] {
            let directory = tempfile::tempdir().unwrap();
            let manager = std::sync::Arc::new(AgentManager::new_with_base_dir(directory.path().join("agents")));
            let driver_dir = manager.driver_dir("oracle");
            std::fs::create_dir_all(&driver_dir).unwrap();
            let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
            listener.set_nonblocking(true).unwrap();
            let port = listener.local_addr().unwrap().port();
            std::fs::write(
                driver_dir.join("agent.py"),
                "import socket,sys,time\ns=socket.create_connection(('127.0.0.1',int(sys.argv[1])))\ntime.sleep(30)\n",
            )
            .unwrap();
            std::fs::write(
                manager.driver_launch_config_path("oracle"),
                serde_json::json!({
                    "command": if cfg!(windows) {"python"} else {"python3"},
                    "args":["{driver_dir}/agent.py",port.to_string()],"working_dir":"{driver_dir}"
                })
                .to_string(),
            )
            .unwrap();
            let own_manager = manager.clone();
            let (startup, cleanup) = StartupCleanup::new_pair();
            let task = tokio::spawn(async move {
                prepare_pl_debug_channel_before_observed(
                    &own_manager,
                    &DatabaseType::Oracle,
                    None,
                    &[],
                    &[],
                    "inspect".into(),
                    uuid::Uuid::new_v4(),
                    Instant::now() + Duration::from_secs(2),
                    startup,
                )
                .await
            });
            let connected = tokio::time::timeout(Duration::from_secs(5), async {
                loop {
                    match listener.accept() {
                        Ok((stream, _)) => break stream,
                        Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
                            tokio::time::sleep(Duration::from_millis(10)).await;
                        }
                        Err(error) => panic!("startup witness accept failed: {error}"),
                    }
                }
            })
            .await;
            if connected.is_err() {
                task.abort();
                panic!("dedicated channel did not launch the test Agent");
            }
            let mut stream = connected.unwrap();
            stream.set_nonblocking(false).unwrap();
            assert_eq!(manager.connection_runtimes.lock().await.len(), 1);
            if cancel {
                task.abort();
                assert!(matches!(task.await, Err(error) if error.is_cancelled()));
            } else {
                assert!(tokio::time::timeout(Duration::from_secs(5), task).await.unwrap().unwrap().is_err());
            }
            assert!(manager.connection_runtimes.lock().await.is_empty());
            tokio::time::timeout(Duration::from_secs(3), cleanup.wait_until_settled()).await.unwrap();
            assert_eq!(cleanup.snapshot().children_started, 1);
            assert_eq!(cleanup.snapshot().children_exited, 1);
            assert_eq!(cleanup.snapshot().reservations_pending, 0);
            stream.set_read_timeout(Some(Duration::from_secs(3))).unwrap();
            let closed = tokio::task::spawn_blocking(move || stream.read(&mut [0u8; 1])).await.unwrap();
            assert!(
                matches!(closed, Ok(0))
                    || matches!(closed, Err(error) if matches!(error.kind(),
                std::io::ErrorKind::ConnectionReset | std::io::ErrorKind::ConnectionAborted))
            );
        }
    }

    #[test]
    fn trino_uses_only_trino_agent_driver() {
        assert_eq!(runtime_agent_key_candidates(&DatabaseType::Trino, None).unwrap(), vec!["trino"]);
    }

    #[test]
    fn shared_runtime_key_includes_launch_fingerprint() {
        let base = crate::db::agent_driver::AgentLaunchSpec::new(PathBuf::from("oracle-agent"))
            .with_args(["--mode", "stdio"])
            .with_working_dir(PathBuf::from("/tmp/oracle"));
        let different_args = crate::db::agent_driver::AgentLaunchSpec::new(PathBuf::from("oracle-agent"))
            .with_args(["--mode", "debug"])
            .with_working_dir(PathBuf::from("/tmp/oracle"));

        assert_eq!(shared_runtime_key("oracle", &base), shared_runtime_key("oracle", &base));
        assert_ne!(shared_runtime_key("oracle", &base), shared_runtime_key("oracle", &different_args));
    }

    #[test]
    fn shared_runtime_key_isolates_process_scoped_env() {
        let base = crate::db::agent_driver::AgentLaunchSpec::new(PathBuf::from("oracle-agent"));
        let with_nls =
            base.clone().with_env([("NLS_LANG".to_string(), "SIMPLIFIED CHINESE_CHINA.AL32UTF8".to_string())]);
        let with_other_nls = base.clone().with_env([("NLS_LANG".to_string(), "AMERICAN_AMERICA.AL32UTF8".to_string())]);

        // Setting a process-scoped variable must route to a dedicated process …
        assert_ne!(shared_runtime_key("oracle", &base), shared_runtime_key("oracle", &with_nls));
        // … and two different values must never share one process either.
        assert_ne!(shared_runtime_key("oracle", &with_nls), shared_runtime_key("oracle", &with_other_nls));
        // Identical env still reuses the same process.
        assert_eq!(shared_runtime_key("oracle", &with_nls), shared_runtime_key("oracle", &with_nls.clone()));
    }

    #[tokio::test]
    async fn shared_connection_entry_applies_each_database_exact_identity_result() {
        use crate::db::agent_driver::AgentCapability;
        let directory = tempfile::tempdir().unwrap();
        let manager = AgentManager::new_with_base_dir_and_app_version(directory.path().join("agents"), "test");
        let driver_dir = manager.driver_dir("oracle");
        std::fs::create_dir_all(&driver_dir).unwrap();
        std::fs::write(driver_dir.join("agent.py"), r#"import json, sys
print(json.dumps({'ready': True}), flush=True)
for line in sys.stdin:
    req = json.loads(line); params = req.get('params', {})
    if req['method'] == 'open_session' and params.get('database') == 'failed':
        print(json.dumps({'jsonrpc':'2.0','id':req['id'],'error':{'code':-1,'message':'open refused'}}), flush=True)
        continue
    if req['method'] == 'handshake':
        result = {'protocolVersion':2,'agentProtocolVersion':2,'capabilities':['multi_session','exact_metadata_identity_v1']}
    else:
        result = {'ok':True}
        if params.get('database') in ('legacy', 'modern'):
            result['exactMetadataIdentity'] = params['database'] == 'modern'
    print(json.dumps({'jsonrpc':'2.0','id':req['id'],'result':result}), flush=True)
"#).unwrap();
        let python = if cfg!(windows) { "python" } else { "python3" };
        std::fs::write(
            manager.driver_launch_config_path("oracle"),
            serde_json::json!({
                "command":python,"args":["{driver_dir}/agent.py"],"working_dir":"{driver_dir}"
            })
            .to_string(),
        )
        .unwrap();
        let failed = spawn_shared_connection_client(
            &manager,
            &DatabaseType::Oracle,
            None,
            &[],
            &[],
            "failed".into(),
            serde_json::json!({"database":"failed"}),
            Duration::from_secs(3),
        )
        .await;
        assert!(failed.is_err());
        assert!(manager.connection_runtimes.lock().await.is_empty());
        for (database, supported) in [("legacy", false), ("modern", true), ("old-response", true)] {
            let mut client = spawn_shared_connection_client(
                &manager,
                &DatabaseType::Oracle,
                None,
                &[],
                &[],
                database.into(),
                serde_json::json!({"database":database}),
                Duration::from_secs(3),
            )
            .await
            .unwrap_or_else(|error| panic!("{}", error.message));
            assert_eq!(client.supports_capability(AgentCapability::ExactMetadataIdentityV1), supported, "{database}");
            let result: serde_json::Value = client.call("get_tables", serde_json::json!({})).await.unwrap();
            assert_eq!(result["ok"], true);
            client.shutdown().await;
        }
    }

    #[tokio::test]
    async fn pl_debug_scopes_isolate_real_processes_and_keep_ordinary_runtime_sharing() {
        let directory = tempfile::tempdir().unwrap();
        let manager = AgentManager::new_with_base_dir_and_app_version(directory.path().join("agents"), "test");
        let driver_dir = manager.driver_dir("oracle");
        std::fs::create_dir_all(&driver_dir).unwrap();
        std::fs::write(
            driver_dir.join("agent.py"),
            r#"import json, os, pathlib, sys
scope = os.environ.get('DBX_PL_DEBUG_RUNTIME_SCOPE', 'ordinary')
marker = pathlib.Path(__file__).parent/('opens-'+scope)
opens = 0; marker.write_text('0')
print(json.dumps({'ready': True}), flush=True)
for line in sys.stdin:
    req = json.loads(line); method = req['method']
    if method == 'handshake':
        result = {'protocolVersion':2,'agentProtocolVersion':2,'capabilities':['multi_session']}
    else:
        if method == 'open_session': opens += 1; marker.write_text(str(opens))
        result = {'pid':os.getpid(),'scope':scope,'nls':os.environ.get('NLS_LANG'),'opens':opens,
                  'agentSessionId':req.get('params',{}).get('agentSessionId')}
    print(json.dumps({'jsonrpc':'2.0','id':req['id'],'result':result}),flush=True)
"#,
        )
        .unwrap();
        let python = if cfg!(windows) { "python" } else { "python3" };
        std::fs::write(
            manager.driver_launch_config_path("oracle"),
            serde_json::json!({
                "command":python,"args":["{driver_dir}/agent.py"],"working_dir":"{driver_dir}"
            })
            .to_string(),
        )
        .unwrap();
        let env = vec![("NLS_LANG".to_string(), "AMERICAN_AMERICA.AL32UTF8".to_string())];
        let mut ordinary_a = spawn_shared_connection_client(
            &manager,
            &DatabaseType::Oracle,
            None,
            &[],
            &env,
            "ordinary-a".into(),
            serde_json::json!({"role":"metadata"}),
            Duration::from_secs(3),
        )
        .await
        .unwrap_or_else(|error| panic!("{}", error.message));
        let mut ordinary_b = spawn_shared_connection_client(
            &manager,
            &DatabaseType::Oracle,
            None,
            &[],
            &env,
            "ordinary-b".into(),
            serde_json::json!({"role":"metadata"}),
            Duration::from_secs(3),
        )
        .await
        .unwrap_or_else(|error| panic!("{}", error.message));
        let a: serde_json::Value = ordinary_a.call("probe", serde_json::json!({})).await.unwrap();
        let b: serde_json::Value = ordinary_b.call("probe", serde_json::json!({})).await.unwrap();
        let mut scoped_env = env.clone();
        scoped_env.push(("DBX_PL_DEBUG_RUNTIME_SCOPE".into(), "not-the-core-scope".into()));
        let first_scope = uuid::Uuid::new_v4();
        let second_scope = uuid::Uuid::new_v4();
        let (startup, cleanup) = StartupCleanup::new_pair();
        let first = prepare_pl_debug_channel_before_observed(
            &manager,
            &DatabaseType::Oracle,
            None,
            &[],
            &scoped_env,
            "debug-first".into(),
            first_scope,
            Instant::now() + Duration::from_secs(5),
            startup,
        )
        .await
        .unwrap();
        assert_eq!(cleanup.snapshot().children_started, 1);
        assert_eq!(cleanup.snapshot().reservations_transferred, 1);
        assert!(!cleanup.snapshot().is_settled());
        let second = prepare_pl_debug_channel(
            &manager,
            &DatabaseType::Oracle,
            None,
            &[],
            &scoped_env,
            "debug-second".into(),
            second_scope,
        )
        .await
        .unwrap();
        assert_eq!(std::fs::read_to_string(driver_dir.join(format!("opens-{first_scope}"))).unwrap(), "0");
        assert_eq!(std::fs::read_to_string(driver_dir.join(format!("opens-{second_scope}"))).unwrap(), "0");
        let one = first.open_session(serde_json::json!({"role":"metadata"}), Duration::from_secs(3)).await.unwrap();
        let two = second.open_session(serde_json::json!({"role":"metadata"}), Duration::from_secs(3)).await.unwrap();
        let first_status: serde_json::Value =
            first.call("pl_debug_status", serde_json::json!({}), Duration::from_secs(3), None).await.unwrap();
        assert!(!first.retire_after_exit(&manager).await);
        first.fail_stop();
        assert!(first.wait_for_exit(Duration::from_secs(3)).await);
        assert!(first.retire_after_exit(&manager).await);
        assert!(first.retire_after_exit(&manager).await);
        tokio::time::timeout(Duration::from_secs(3), cleanup.wait_until_settled()).await.unwrap();
        assert_eq!(manager.connection_runtimes.lock().await.len(), 2);
        let sibling_status: serde_json::Value =
            second.call("pl_debug_status", serde_json::json!({}), Duration::from_secs(3), None).await.unwrap();
        let ordinary_status: serde_json::Value = ordinary_b.call("probe", serde_json::json!({})).await.unwrap();
        stop_daemons(&manager).await;

        assert_eq!(a["pid"], b["pid"]);
        assert_eq!(a["opens"], 2);
        assert_ne!(one["pid"], a["pid"]);
        assert_ne!(two["pid"], a["pid"]);
        assert_ne!(one["pid"], two["pid"]);
        assert_eq!(one["scope"], first_scope.to_string());
        assert_eq!(two["scope"], second_scope.to_string());
        assert_eq!(first_status["nls"], "AMERICAN_AMERICA.AL32UTF8");
        assert_eq!(first_status["agentSessionId"], "debug-first");
        assert_eq!(first_status["opens"], 1);
        assert_eq!(sibling_status["pid"], two["pid"]);
        assert_eq!(ordinary_status["pid"], a["pid"]);
    }

    #[tokio::test]
    async fn failed_open_forgets_runtime_when_no_other_session_uses_it() {
        let (manager, cell, runtime, script_path) = test_shared_runtime("failed-open-unused").await;
        let runtime_key = "kingbase|test";
        manager.connection_runtimes.lock().await.insert(runtime_key.to_string(), cell.clone());
        runtime.increment_session_count();

        forget_unused_runtime_after_failed_open(&manager, runtime_key, &cell, &runtime).await;

        assert!(!manager.connection_runtimes.lock().await.contains_key(runtime_key));
        assert_eq!(runtime.active_session_count(), 0);
        runtime.kill();
        let _ = std::fs::remove_file(script_path);
    }

    #[tokio::test]
    async fn failed_open_keeps_runtime_while_another_session_is_reserved() {
        let (manager, cell, runtime, script_path) = test_shared_runtime("failed-open-in-use").await;
        let runtime_key = "oracle|test";
        manager.connection_runtimes.lock().await.insert(runtime_key.to_string(), cell.clone());
        runtime.increment_session_count();
        runtime.increment_session_count();

        forget_unused_runtime_after_failed_open(&manager, runtime_key, &cell, &runtime).await;

        assert!(manager.connection_runtimes.lock().await.contains_key(runtime_key));
        assert_eq!(runtime.active_session_count(), 1);
        AgentRuntimeClient::decrement_session_count(&runtime);
        runtime.kill();
        let _ = std::fs::remove_file(script_path);
    }

    #[tokio::test]
    async fn replace_runtime_open_error_reports_runtime_without_killing_it_directly() {
        let (manager, _cell, runtime, script_path) = test_shared_runtime("replace-runtime-open-error").await;
        let error = AgentCallError::Legacy {
            rpc_code: Some(-1),
            message: "capacity exhausted".to_string(),
            hints: crate::db::agent_driver::LegacyAgentHints {
                category: Some(crate::db::agent_driver::AgentErrorCategory::Resource),
                session_disposition: Some(crate::db::agent_driver::AgentSessionDisposition::ReplaceRuntime),
                ..Default::default()
            },
        };

        let open_error = shared_connection_open_error(error, runtime.clone());

        assert!(open_error.runtime.as_ref().is_some_and(|failed| std::sync::Arc::ptr_eq(failed, &runtime)));
        assert!(!runtime.is_failed());

        runtime.kill();
        drop(manager);
        let _ = std::fs::remove_file(script_path);
    }

    #[tokio::test]
    async fn failed_open_cleanup_cannot_remove_runtime_after_reservation() {
        let (manager, cell, runtime, script_path) = test_shared_runtime("failed-open-race").await;
        let runtime_key = "oracle|test";
        manager.connection_runtimes.lock().await.insert(runtime_key.to_string(), cell.clone());
        runtime.increment_session_count();

        assert_eq!(AgentRuntimeClient::decrement_session_count(&runtime), 0);
        let mut runtimes = manager.connection_runtimes.lock().await;
        assert!(reserve_runtime_locked(&mut runtimes, runtime_key, &cell, &runtime));
        drop(runtimes);

        remove_unused_runtime_if_current(&manager, runtime_key, &cell, &runtime).await;

        assert!(manager.connection_runtimes.lock().await.contains_key(runtime_key));
        assert_eq!(runtime.active_session_count(), 1);
        AgentRuntimeClient::decrement_session_count(&runtime);
        runtime.kill();
        let _ = std::fs::remove_file(script_path);
    }

    #[tokio::test]
    async fn stopping_driver_runtime_removes_and_terminates_shared_process() {
        let (manager, cell, runtime, script_path) = test_shared_runtime("stop-driver-runtime").await;
        let runtime_key = "dameng|test";
        manager.connection_runtimes.lock().await.insert(runtime_key.to_string(), cell);

        stop_daemon_by_key(&manager, "dameng").await;

        assert!(!manager.connection_runtimes.lock().await.contains_key(runtime_key));
        assert!(runtime.is_failed());
        let call_result =
            runtime.call::<serde_json::Value>("ping", serde_json::json!({}), Some(Duration::from_secs(1)), None).await;
        assert_eq!(call_result.unwrap_err(), "Agent runtime is unavailable");
        let _ = std::fs::remove_file(script_path);
    }
}