mcp.rs

mod app_registry;
mod cli;
#[cfg(test)]
pub(crate) use cli::parse_call_line_for_test;
mod discovery;
mod execution_control;
mod http_metadata;
mod presentation;
mod protocol;
mod request_policy;
mod resources;
mod response;
pub(crate) mod tool_exposure;
mod tools;
mod workbench;

#[cfg(test)]
pub(crate) use tools::adaptive_runtime_gateway_input_schema_for_test;

use crate::action_audit::{ActionAudit, ActionAuditRecord};
use crate::auth::AuthContext;
use crate::json_error;
use crate::json_measurement::serialized_json_len;
use crate::tool_request_trace::{
    estimate_json_bytes, jsonrpc_id_safe, new_trace_id, scope_active_trace,
    RequestCompletionTiming, ToolRequestLifecycle,
};
use crate::tool_runtime::kernel::HostFileImportTrust;
use crate::tool_runtime::model_ergonomics_telemetry::{
    ModelErgonomicsRecord, ModelErgonomicsTimer,
};
#[cfg(test)]
use crate::tool_runtime::registered_tool_specs;
#[cfg(test)]
use crate::tool_runtime::ToolResult;
use crate::tool_runtime::ToolRuntime;
#[cfg(test)]
use crate::tool_runtime::MAX_PROJECT_ARTIFACT_BYTES;
#[cfg(test)]
use crate::tool_runtime::{
    validate_project_artifact_export_snapshot, ProjectArtifactExportSnapshot,
    INTERNAL_ARTIFACT_TRANSFER_CHUNK_BYTES, MAX_PROJECT_ARTIFACT_EXPORT_BYTES,
};
#[cfg(test)]
use base64::Engine as _;
use futures_util::stream;
use http_metadata::{request_header, validate_http_protocol, MCP_PROTOCOL_VERSION_HEADER};
#[cfg(test)]
use http_metadata::{
    MCP_HEADER_MISMATCH, MCP_METHOD_HEADER, MCP_NAME_HEADER, MCP_UNSUPPORTED_PROTOCOL_VERSION,
};
#[cfg(test)]
use protocol::{
    inferred_protocol_era, request_protocol_version, MCP_CHATGPT_PROTOCOL_VERSION,
    MCP_SUPPORTED_PROTOCOL_VERSIONS,
};
use protocol::{
    JsonRpcRequest, McpProtocolEra, MCP_INFO_METHODS, MCP_PROTOCOL_VERSION,
    MCP_STATELESS_PROTOCOL_VERSION,
};
use response::{rpc_error, rpc_result};
use salvo::prelude::*;
use serde_json::{json, Value};
use std::sync::Arc;
#[cfg(test)]
use std::time::{Duration, Instant};
#[cfg(test)]
use tokio::sync::Semaphore;

#[cfg(test)]
use app_registry::*;
#[cfg(test)]
use resources::*;
#[cfg(test)]
use tools::{
    add_stateless_workflow_recorder_metadata, mcp_host_file_import_trust_decision_from_state,
    mcp_host_file_import_trust_from_state, mcp_tools_list_payload_with_compact,
    mcp_tools_list_payload_with_compact_and_app, mcp_tools_list_payload_with_features_for_auth,
    parse_mcp_invocation_envelope, take_last_mcp_host_file_import_trust_decision,
    HostFileImportTrustReason, McpToolCallParams,
};

/// Hard upper bound on a single MCP JSON-RPC dispatch, applied in `mcp_post`.
///
/// Chosen above every per-tool wait (sync agent waits are clamped to
/// `wait_timeout_secs <= 120` plus a few seconds of margin), so it can only
/// fire when a dispatch path hangs without its own bound. Its job is to turn
/// an otherwise-permanently-silent HTTP request into an explicit JSON-RPC
/// error the client can surface.
const MCP_DISPATCH_HARD_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(150);

fn runtime(depot: &Depot) -> Option<Arc<ToolRuntime>> {
    depot.obtain::<Arc<ToolRuntime>>().ok().cloned()
}

// Retain only the exact Goal selector for successful Goal Plan polls. This is
// observation correlation, not client liveness evidence or authority. No other
// arguments, Goal body, or Host binding are copied into the activity ledger.
fn goal_plan_observation_id(tool_name: Option<&str>, params: &Value) -> Option<String> {
    if tool_name != Some("sync_goal_plan") {
        return None;
    }
    let id = params.pointer("/arguments/goal_id")?.as_str()?;
    let suffix = id.strip_prefix("wc_goal_")?;
    (suffix.len() == 16
        && suffix
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-')))
    .then(|| id.to_string())
}

fn work_result_app_internal_tool(tool_name: Option<&str>) -> bool {
    matches!(
        tool_name,
        Some(
            "search_mentions"
                | "open_webcodex_workbench"
                | "search_webcodex_resources"
                | "read_webcodex_resource"
                | "list_sessions"
                | "present_work_result"
                | "work_result_thread_panel"
                | "get_work_result_state"
                | "read_work_result_activity_detail"
                | "send_work_result_message"
                | "read_changed_file_diff"
        )
    )
}

fn finalize_mcp_tool_observability(
    trace: &ToolRequestLifecycle,
    runtime: &ToolRuntime,
    audit: Option<&ActionAudit>,
    audit_event: Option<(
        ActionAuditRecord,
        crate::action_audit::ActionAuditRecordTiming,
    )>,
    model_ergonomics: Option<&ModelErgonomicsRecord>,
    live_window_request: &mut Option<crate::tool_runtime::WindowActivityGuard>,
    timing: RequestCompletionTiming,
    streaming: bool,
    continuity_eligible: bool,
    outcome_class: &'static str,
) {
    let finalize_started = std::time::Instant::now();
    let transition = live_window_request
        .as_ref()
        .map(crate::tool_runtime::WindowActivityGuard::transition);
    let meaningful = audit_event
        .as_ref()
        .is_some_and(|(event, _)| event.window_meaningful);

    if let Some(record) = model_ergonomics {
        if let Some(target) = live_window_request
            .as_ref()
            .and_then(|active| active.instruction_read_after_complete_bootstrap(record))
        {
            crate::tool_runtime::runtime_metrics::observe_instruction_read_after_complete_bootstrap(
                runtime.metrics.as_ref(),
                target,
            );
        }
        crate::tool_runtime::runtime_metrics::observe_tool_call(runtime.metrics.as_ref(), record);
    }
    if audit_event.is_some() {
        crate::tool_runtime::runtime_metrics::observe_mcp_call(
            runtime.metrics.as_ref(),
            crate::tool_runtime::runtime_metrics::McpCallMetricObservation {
                elapsed_ms: timing.elapsed_ms,
                outcome_class,
                meaningful,
                streaming,
            },
        );
        if meaningful {
            if let Some(transition) = transition {
                crate::tool_runtime::runtime_metrics::observe_window_transition(
                    runtime.metrics.as_ref(),
                    transition,
                );
            }
        }
    }

    // Keep the request active until its completed observation is durable. A
    // detector must never see neither the active call nor its completed work.
    let evidence_recorded =
        if let (Some(audit), Some((mut event, audit_timing))) = (audit, audit_event) {
            if let Some(previous) = live_window_request
                .as_ref()
                .and_then(|guard| guard.previous_meaningful_call())
            {
                event.summary["previous_meaningful_call"] = json!(previous);
            }
            audit.record_with_completion(
                event,
                audit_timing,
                timing,
                transition,
                streaming,
                continuity_eligible,
            )
        } else {
            false
        };
    if let Some(active) = live_window_request.take() {
        active.complete(timing, continuity_eligible, evidence_recorded);
    }
    crate::tool_request_trace::record_phase_latency_for(
        Some(&trace.correlation_trace_id()),
        "request_finalize",
        finalize_started,
        "completed",
    );
}

#[cfg(test)]
pub(crate) fn mcp_runtime_tool_result(
    tool_name: &str,
    as_image_requested: bool,
    result: ToolResult,
) -> Value {
    tools::mcp_runtime_tool_result(tool_name, as_image_requested, result)
}

/// Outcome of handling a single MCP JSON-RPC request.
///
/// Carries the JSON-RPC response body alongside the HTTP status the HTTP
/// wrapper should render. Keeping this separate from `Response` makes the
/// core protocol logic testable without a live server.
#[derive(Debug)]
enum McpOutcome {
    /// A normal JSON-RPC result. HTTP 200 with the body.
    Ok(Value),
    /// A preflighted artifact resource read whose JSON-RPC body is emitted
    /// incrementally by the HTTP wrapper without whole-file aggregation.
    ArtifactExportStream {
        id: Value,
        plan: resources::McpArtifactExportStreamPlan,
    },
    /// A JSON-RPC protocol error. HTTP 400 with the error body.
    BadRequest(Value),
    /// A modern MCP method is not implemented. HTTP 404 with JSON-RPC -32601.
    NotFound(Value),
    /// A JSON-RPC notification (request without an `id` member). Per the
    /// JSON-RPC 2.0 and MCP specs the server MUST NOT reply with a
    /// JSON-RPC response body. The HTTP wrapper acknowledges with 202 and
    /// an empty body.
    Notification,
    /// The HTTP request authenticated, but the OAuth2 bearer token lacks the
    /// delegated scope needed by this JSON-RPC method or tool.
    Forbidden {
        body: Value,
        required_scope: Option<&'static str>,
    },
}

fn log_mcp_computer_app_resource_delivery(
    uri: &str,
    protocol_era: &str,
    ui_capability_present: bool,
    http_status: u16,
    mcp_error_code: Option<i64>,
) {
    tracing::info!(
        target: "webcodex::mcp",
        uri,
        protocol_era,
        ui_capability_present,
        http_status,
        mcp_error_code = mcp_error_code.unwrap_or(-1),
        "mcp_computer_app_resource_delivery"
    );
}

fn log_mcp_computer_app_resource_outcome(
    uri: &str,
    protocol_era: McpProtocolEra,
    ui_capability_present: bool,
    outcome: &McpOutcome,
) {
    let (http_status, mcp_error_code) = match outcome {
        McpOutcome::Ok(_) | McpOutcome::ArtifactExportStream { .. } => (200, None),
        McpOutcome::BadRequest(body) => (400, body["error"]["code"].as_i64()),
        McpOutcome::NotFound(body) => (404, body["error"]["code"].as_i64()),
        McpOutcome::Notification => (202, None),
        McpOutcome::Forbidden { .. } => (403, None),
    };
    log_mcp_computer_app_resource_delivery(
        uri,
        protocol::era_label(protocol_era),
        ui_capability_present,
        http_status,
        mcp_error_code,
    );
}

/// Payload-free measurements of the final MCP tool result, after surface
/// projection. UTF-8 text bytes and JSON bytes are proxies, never Host tokens.
/// The existing model_ergonomics metric continues to measure structured results.
fn mcp_tool_response_audit_summary(
    result: &Value,
    surface: request_policy::McpSurface,
) -> Option<Value> {
    let content = result.get("content")?.as_array()?;
    let mut text_utf8_bytes = 0_u64;
    let mut text_blocks = 0_u64;
    let mut non_text_blocks = 0_u64;
    for block in content {
        if block.get("type")?.as_str()? == "text" {
            text_utf8_bytes = text_utf8_bytes
                .checked_add(u64::try_from(block.get("text")?.as_str()?.len()).ok()?)?;
            text_blocks = text_blocks.checked_add(1)?;
        } else {
            non_text_blocks = non_text_blocks.checked_add(1)?;
        }
    }
    let structured_json_bytes = result
        .get("structuredContent")
        .map(serialized_json_len)
        .transpose()
        .ok()?;
    Some(json!({
        "schema_version": 1,
        "surface": match surface {
            request_policy::McpSurface::Adaptive => "adaptive",
            request_policy::McpSurface::Cli => "cli",
        },
        "result_json_bytes": serialized_json_len(result).ok()?,
        "text_utf8_bytes": text_utf8_bytes,
        "structured_json_bytes": structured_json_bytes,
        "text_blocks": text_blocks,
        "non_text_blocks": non_text_blocks,
    }))
}

fn mcp_tools_list_audit_summary(
    result: &Value,
    protocol_era: McpProtocolEra,
    compact_schemas: bool,
) -> Option<Value> {
    let tools = result.get("tools")?.as_array()?;
    let serialized_tools_bytes = serialized_json_len(&result["tools"]).ok()? as u64;
    let serialized_result_bytes = serialized_json_len(result).ok()? as u64;
    let gateway_tool_included = tools.iter().any(|tool| {
        tool.get("name").and_then(Value::as_str) == Some(crate::mcp_gateway::MCP_TOOL_NAME)
    });
    Some(json!({
        "transport": "mcp",
        "tool_surface": {
            "schema_version": 1,
            "protocol_era": protocol::era_label(protocol_era),
            "compact_schemas": compact_schemas,
            "tool_count": tools.len() as u64,
            "serialized_tools_bytes": serialized_tools_bytes,
            "serialized_result_bytes": serialized_result_bytes,
            "gateway_tool_included": gateway_tool_included
        }
    }))
}

#[handler]
pub async fn mcp_info(req: &mut Request, depot: &mut Depot, res: &mut Response) {
    let Some(config) = crate::auth::get_config(depot) else {
        res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
        res.render(json_error(
            StatusCode::INTERNAL_SERVER_ERROR,
            "Server configuration not available",
        ));
        return;
    };
    if let Err((status, _, message)) =
        crate::public_ingress_auth::require_authority(req, depot, &config)
    {
        let status = StatusCode::from_u16(status).unwrap_or(StatusCode::FORBIDDEN);
        res.status_code(status);
        res.render(json_error(status, message));
        return;
    }
    if request_header(req, MCP_PROTOCOL_VERSION_HEADER) == Some(MCP_STATELESS_PROTOCOL_VERSION) {
        res.status_code(StatusCode::METHOD_NOT_ALLOWED);
        return;
    }
    let auth_required = config.is_auth_enabled();
    res.render(Json(json!({
        "name": "webcodex",
        "version": env!("CARGO_PKG_VERSION"),
        "protocol": "mcp",
        "protocolVersion": MCP_PROTOCOL_VERSION,
        "transport": "streamable-http-jsonrpc",
        "endpoint": "/mcp",
        "methods": MCP_INFO_METHODS,
        "auth": {
            "type": "bearer",
            "required": auth_required,
            "header": "Authorization: Bearer <shared_key_or_wc_pat>"
        }
    })));
}

#[derive(Debug, Clone, Default)]
struct McpToolJobAuditCorrelation {
    async_job_id: Option<String>,
    observed_job_ids: Vec<String>,
    resolved_project: Option<String>,
}

fn safe_audit_job_id(value: Option<&Value>) -> Option<String> {
    value
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|job_id| webcodex_core::workflow_session_contract::is_safe_job_id(job_id))
        .map(str::to_string)
}

fn safe_audit_project(value: Option<&Value>) -> Option<String> {
    value
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|project| {
            !project.is_empty()
                && project.chars().count() <= 512
                && !project.chars().any(char::is_control)
        })
        .map(str::to_string)
}

fn mcp_tool_job_audit_correlation(
    tool_name: Option<&str>,
    body: &Value,
) -> McpToolJobAuditCorrelation {
    let Some(output) = body.pointer("/result/structuredContent/output") else {
        return McpToolJobAuditCorrelation::default();
    };
    if tool_name == Some("wait_for_job_readiness") {
        let mut observed_job_ids = Vec::new();
        for value in output
            .get("ready")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
            .filter_map(|item| item.get("job_id"))
            .chain(
                output
                    .get("pending_job_ids")
                    .and_then(Value::as_array)
                    .into_iter()
                    .flatten(),
            )
            .take(8)
        {
            if let Some(id) = safe_audit_job_id(Some(value)) {
                if !observed_job_ids.contains(&id) {
                    observed_job_ids.push(id);
                }
            }
        }
        // Never infer Project authority from the sparse readiness result body.
        // The Job dispatcher may already bind a common Project from exact caller-authorized
        // Job records; mixed/projectless sets deliberately remain unanchored.
        return McpToolJobAuditCorrelation {
            observed_job_ids,
            ..Default::default()
        };
    }
    if tool_name == Some("observe_jobs") {
        let mut observed_job_ids = Vec::new();
        let mut resolved_project: Option<String> = None;
        let mut project_ambiguous = false;
        if let Some(items) = output.get("items").and_then(Value::as_array) {
            for item in items.iter().take(8) {
                let original_item = item.get("details").unwrap_or(item);
                let item_output = original_item
                    .get("output")
                    .filter(|value| value.is_object());
                let job_id = safe_audit_job_id(
                    item.pointer("/execution/job_id")
                        .or_else(|| original_item.get("job_id"))
                        .or_else(|| item_output.and_then(|output| output.get("job_id"))),
                );
                if let Some(job_id) = job_id {
                    if !observed_job_ids.contains(&job_id) {
                        observed_job_ids.push(job_id);
                    }
                    let project = safe_audit_project(
                        item_output
                            .and_then(|output| output.get("project"))
                            .or_else(|| original_item.get("project")),
                    );
                    match (resolved_project.as_deref(), project.as_deref()) {
                        (None, Some(project)) if !project_ambiguous => {
                            resolved_project = Some(project.to_string());
                        }
                        (Some(existing), Some(project)) if existing == project => {}
                        (_, None) | (Some(_), Some(_)) => {
                            resolved_project = None;
                            project_ambiguous = true;
                        }
                        (None, Some(_)) => {}
                    }
                }
            }
        }
        return McpToolJobAuditCorrelation {
            async_job_id: None,
            observed_job_ids,
            resolved_project: (!project_ambiguous).then_some(resolved_project).flatten(),
        };
    }

    // Reuse the canonical audit predicate, including uncertain promoted Jobs;
    // presentation outcome alone must not drop the original receipt identity.
    let execution_facts = output.get("execution").map(|execution| {
        json!({
            "job_id": execution.get("job_id"),
            "execution_state": execution.get("state"),
            "promoted_to_job": output.pointer("/details/promoted_to_job")
        })
    });
    McpToolJobAuditCorrelation {
        async_job_id: crate::tool_runtime::job_audit::execution_job_id_for_audit(
            tool_name,
            execution_facts.as_ref().unwrap_or(output),
        ),
        observed_job_ids: Vec::new(),
        resolved_project: None,
    }
}
fn mcp_tool_action_audit_ids(
    success: bool,
    observed_goal_plan_id: Option<&str>,
    correlation: &crate::tool_runtime::ToolCallCorrelation,
    jobs: Option<&McpToolJobAuditCorrelation>,
) -> Option<Value> {
    if !success {
        return None;
    }
    let mut ids = serde_json::Map::new();
    if let Some(goal_id) = observed_goal_plan_id {
        ids.insert("goal_id".to_string(), Value::String(goal_id.to_string()));
    }
    if let Some(session_id) = correlation.business_session_id.as_deref() {
        ids.insert(
            "business_session_id".to_string(),
            Value::String(session_id.to_string()),
        );
    }
    if let Some(jobs) = jobs {
        if let Some(job_id) = jobs.async_job_id.as_deref() {
            ids.insert(
                "async_job_id".to_string(),
                Value::String(job_id.to_string()),
            );
        }
        if !jobs.observed_job_ids.is_empty() {
            ids.insert(
                "observed_job_ids".to_string(),
                Value::Array(
                    jobs.observed_job_ids
                        .iter()
                        .cloned()
                        .map(Value::String)
                        .collect(),
                ),
            );
        }
    }
    (!ids.is_empty()).then_some(Value::Object(ids))
}

tokio::task_local! {
    static REQUEST_PUBLIC_ORIGIN: Option<String>;
}

pub(super) fn app_public_origin(runtime: &ToolRuntime) -> Option<String> {
    REQUEST_PUBLIC_ORIGIN
        .try_with(Clone::clone)
        .ok()
        .flatten()
        .or_else(|| runtime.runtime_info.configured_public_url.clone())
}

#[handler]
pub async fn mcp_post(req: &mut Request, depot: &mut Depot, res: &mut Response) {
    let mut guard = ToolRequestLifecycle::new("mcp", new_trace_id(), "-", "POST /mcp", None);
    guard.received();

    let Some(authority_config) = crate::auth::get_config(depot) else {
        let status = StatusCode::INTERNAL_SERVER_ERROR;
        guard.parsed("http_validation_error");
        guard.response_serialized(
            status.as_u16(),
            None,
            Some(false),
            None,
            "http_validation_error",
        );
        res.status_code(status);
        res.render(json_error(status, "Server configuration not available"));
        guard.handler_returned(
            status.as_u16(),
            None,
            Some(false),
            None,
            "http_validation_error",
        );
        return;
    };
    if let Err((status, _, message)) =
        crate::public_ingress_auth::require_json_authority(req, depot, &authority_config)
    {
        let status = StatusCode::from_u16(status).unwrap_or(StatusCode::BAD_REQUEST);
        guard.parsed("http_validation_error");
        guard.response_serialized(
            status.as_u16(),
            None,
            Some(false),
            None,
            "http_validation_error",
        );
        res.status_code(status);
        res.render(json_error(status, message));
        guard.handler_returned(
            status.as_u16(),
            None,
            Some(false),
            None,
            "http_validation_error",
        );
        return;
    }

    let Some(runtime) = runtime(depot) else {
        // Size unknown without building the json_error body for measurement.
        guard.response_serialized(500, None, Some(false), None, "error_runtime_missing");
        res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
        res.render(json_error(
            StatusCode::INTERNAL_SERVER_ERROR,
            "Tool runtime not configured",
        ));
        guard.handler_returned(500, None, Some(false), None, "error_runtime_missing");
        return;
    };
    let request: JsonRpcRequest = match req.parse_json().await {
        Ok(request) => request,
        Err(e) => {
            guard.set_jsonrpc_id("none");
            guard.parsed("parse_error");
            let body = rpc_error(None, -32700, format!("Parse error: {}", e));
            let estimated = estimate_json_bytes(&body);
            guard.response_serialized(400, estimated, Some(false), None, "parse_error");
            res.status_code(StatusCode::BAD_REQUEST);
            res.render(Json(body));
            guard.handler_returned(400, estimated, Some(false), None, "parse_error");
            return;
        }
    };

    guard.set_jsonrpc_id(jsonrpc_id_safe(request.id.as_ref()));
    guard.set_method(request.method.clone());
    let tool_name = if request.method == "tools/call" {
        tools::tool_name_from_params(&request.params)
    } else {
        None
    };
    guard.set_tool_name(tool_name.clone());
    guard.set_app_call_id(tools::agent_continuation_app_call_id_from_params(
        &request.params,
    ));
    let computer_app_resource_uri = if request.method == "resources/read" {
        request
            .params
            .get("uri")
            .and_then(Value::as_str)
            .filter(|uri| *uri == app_registry::MCP_COMPUTER_UI_RESOURCE_URI)
            .map(str::to_string)
    } else {
        None
    };
    let computer_app_ui_capability_present = resources::request_supports_mcp_apps(&request.params);
    // Computer App resource delivery is part of gray-card diagnosis, but its
    // durable projection must remain metadata-only. Never persist App HTML,
    // screenshot/tool-result content, tool arguments, window titles, or other
    // request payload fields here.
    let computer_app_resource_audit = computer_app_resource_uri.as_ref().and_then(|uri| {
        request.id.as_ref().map(|_| {
            (
                ActionAudit::start(req, depot, "/mcp", "resourcesRead"),
                uri.clone(),
            )
        })
    });
    let record_computer_app_resource_audit =
        |protocol_era: &str, status: StatusCode, mcp_error_code: Option<i64>| {
            if let Some((audit, uri)) = computer_app_resource_audit.as_ref() {
                audit.record(
                    ActionAuditRecord::new(
                        "computer_app_resource_read",
                        status.is_success(),
                        status,
                    )
                    .summary(json!({
                        "transport": "mcp",
                        "resource_uri": uri,
                        "resource_version": uri.rsplit('/').next().unwrap_or("unknown"),
                        "protocol_era": protocol_era,
                        "ui_capability_present": computer_app_ui_capability_present,
                        "mcp_error_code": mcp_error_code,
                    })),
                );
            }
        };
    let protocol_era = match validate_http_protocol(req, &request) {
        Ok(protocol_era) => protocol_era,
        Err(body) => {
            guard.parsed("protocol_error");
            if let Some(uri) = computer_app_resource_uri.as_deref() {
                log_mcp_computer_app_resource_delivery(
                    uri,
                    "validation_failed",
                    computer_app_ui_capability_present,
                    400,
                    body["error"]["code"].as_i64(),
                );
                record_computer_app_resource_audit(
                    "validation_failed",
                    StatusCode::BAD_REQUEST,
                    body["error"]["code"].as_i64(),
                );
            }
            let estimated = estimate_json_bytes(&body);
            guard.response_serialized(400, estimated, Some(false), None, "protocol_error");
            res.status_code(StatusCode::BAD_REQUEST);
            res.render(Json(body));
            guard.handler_returned(400, estimated, Some(false), None, "protocol_error");
            return;
        }
    };
    let (policy_selection, surface, default_project) =
        match request_policy::resolve(req.headers(), runtime.mcp_host_policy).and_then(|policy| {
            let surface = request_policy::resolve_surface(req.headers())?;
            let project = request_policy::resolve_default_project(req.headers(), surface)?;
            Ok((policy, surface, project))
        }) {
            Ok(selection) => selection,
            Err(message) => {
                // Reject ambiguous transport preferences before any tool/Job effect.
                // Do not echo potentially sensitive header values into diagnostics.
                guard.parsed("request_policy_error");
                let body = rpc_error(request.id.clone(), -32600, message);
                let estimated = estimate_json_bytes(&body);
                guard.response_serialized(
                    400,
                    estimated,
                    Some(false),
                    None,
                    "request_policy_error",
                );
                res.status_code(StatusCode::BAD_REQUEST);
                res.render(Json(body));
                guard.handler_returned(400, estimated, Some(false), None, "request_policy_error");
                return;
            }
        };
    let policy = policy_selection.effective;
    // Equal explicit profiles still have request-header provenance. Clone only
    // the lightweight view when policy or its diagnostic source differs; shared
    // stores, execution ownership and the deployment snapshot remain unchanged.
    let runtime = if policy == runtime.mcp_host_policy
        && policy_selection.profile_source == runtime.mcp_host_profile_source
    {
        runtime
    } else {
        Arc::new(
            runtime
                .as_ref()
                .clone()
                .with_request_mcp_host_policy(policy_selection),
        )
    };
    let auth = depot.obtain::<crate::auth::AuthContext>().ok().cloned();
    let window = match crate::client_window::mcp_window(
        req,
        &request.params,
        auth.as_ref(),
        protocol_era == McpProtocolEra::Legacy,
        request.method == "initialize",
    ) {
        Ok(window) => window,
        Err(message) => {
            guard.parsed("client_window_error");
            let body = rpc_error(request.id.clone(), -32600, message);
            let estimated = estimate_json_bytes(&body);
            guard.response_serialized(400, estimated, Some(false), None, "client_window_error");
            res.status_code(StatusCode::BAD_REQUEST);
            res.render(Json(body));
            guard.handler_returned(400, estimated, Some(false), None, "client_window_error");
            return;
        }
    };
    // A host may list tools on throwaway legacy connections. Preserve the
    // audit, but do not turn transport-session discovery into a ghost Window.
    // Explicit ChatGPT/Codex/header Window discovery remains liveness evidence.
    let observed_window = window
        .identity
        .as_ref()
        .filter(|identity| request.method != "tools/list" || identity.source() != "mcp");
    guard.set_client_window(observed_window);
    guard.capture_mcp_host_policy(&policy_selection);
    guard.parsed("ok");
    let server_trace_id = guard.correlation_trace_id();
    let window_registry = runtime.window_activity_registry();
    let window_activity_visible = !work_result_app_internal_tool(tool_name.as_deref());
    let mut live_window_request = if window_activity_visible
        && request.id.is_some()
        && matches!(request.method.as_str(), "tools/call" | "tools/list")
    {
        observed_window.map(|identity| {
            window_registry.start_authenticated(
                identity,
                &server_trace_id,
                &request.method,
                tool_name.as_deref(),
                auth.as_ref(),
                guard.request_observed_at_ms(),
            )
        })
    } else {
        None
    };

    // Chat-window MCP tool calls must land in the action audit exactly like
    // the REST surface (they were previously invisible there). Summary-level
    // only: tool name and project — never arguments or outputs. JSON-RPC
    // notifications are acknowledged but never dispatched, so they must not be
    // represented as executed actions.
    let audit = if request.method == "tools/call" && request.id.is_some() {
        let audit = ActionAudit::start(req, depot, "/mcp", "toolsCall");
        // Presentation stays out of live activity, but its durable Window binding
        // is required when the Host later opens the empty-argument thread panel.
        let audit =
            if window_activity_visible || tool_name.as_deref() == Some("present_work_result") {
                audit.with_window(window.identity.as_ref(), Some(&server_trace_id))
            } else {
                audit
            };
        Some((
            audit,
            tool_name.clone().unwrap_or_else(|| "unknown".to_string()),
            tools::project_from_tool_call_params(&request.params),
        ))
    } else {
        None
    };
    let observed_goal_plan_id = goal_plan_observation_id(tool_name.as_deref(), &request.params);
    let build_audit_event = |success: bool,
                             status: StatusCode,
                             error: Option<String>,
                             model_ergonomics: Option<&ModelErgonomicsRecord>,
                             correlation: &crate::tool_runtime::ToolCallCorrelation,
                             jobs: Option<&McpToolJobAuditCorrelation>|
     -> Option<(
        ActionAuditRecord,
        crate::action_audit::ActionAuditRecordTiming,
    )> {
        if let Some((audit, tool, project)) = audit.as_ref() {
            let mut summary = json!({ "transport": "mcp" });
            if let Some(telemetry) =
                model_ergonomics.and_then(|record| serde_json::to_value(record).ok())
            {
                summary["model_ergonomics"] = telemetry;
            }
            if let Some(composition) = correlation.code_mode_composition_audit_summary() {
                summary["code_mode_composition"] = composition;
            }
            if let Some(expectation) = &correlation.failure_expectation_result {
                summary["failure_expectation_result"] = json!(expectation);
            }
            if let Some(job_trace) = correlation.job_audit_summary() {
                summary["job_trace"] = job_trace;
            }
            let mut event = ActionAuditRecord::new(tool.clone(), success, status)
                .error(error)
                .summary(summary)
                .meaningful(
                    webcodex_tool_contracts::runtime_tool_activity_interaction(tool)
                        .is_meaningful(),
                )
                .recorder_gap(correlation.recorder_gap_session_id.clone());
            if let Some(ids) = mcp_tool_action_audit_ids(
                success,
                observed_goal_plan_id.as_deref(),
                correlation,
                jobs,
            ) {
                event = event.ids(ids);
            }
            event.project = correlation
                .resolved_project
                .clone()
                .or_else(|| project.clone());
            for link in &correlation.workflow_sessions {
                let relation = match link.relation {
                    crate::tool_runtime::WorkflowSessionCorrelationRelation::Recording => {
                        crate::action_audit_sessions::WorkflowSessionRelation::Recording
                    }
                    crate::tool_runtime::WorkflowSessionCorrelationRelation::WorkOnProject => {
                        crate::action_audit_sessions::WorkflowSessionRelation::WorkOnProject
                    }
                };
                event =
                    event.workflow_link(link.session_id.clone(), relation, link.project.clone());
            }
            Some((event, audit.capture_record_timing()))
        } else {
            None
        }
    };

    let tools_list_audit = if request.method == "tools/list" && request.id.is_some() {
        Some(
            ActionAudit::start(req, depot, "/mcp", "toolsList")
                .with_window(observed_window, Some(&server_trace_id)),
        )
    } else {
        None
    };
    let compact_schemas = runtime.runtime_info.mcp_compact_schemas;
    let server_mcp_apps_enabled = runtime.runtime_info.mcp_apps_enabled;

    let config = crate::auth::get_config(depot);
    let db = crate::auth::get_db(depot);
    let host_file_import_trust = tools::host_file_import_trust_for_call(
        tool_name.as_deref(),
        auth.as_ref(),
        config.as_deref(),
        db.as_deref(),
    );
    // Defense-in-depth backstop: every tool bounds its own agent/subprocess
    // waits at <= 124s, so this outer limit never preempts a legitimate inner
    // timeout. It only fires if a dispatch path hangs without a bound (the
    // failure mode behind "MCP request never gets a reply"), converting a
    // silently dead HTTP request into an observable JSON-RPC error.
    let request_id = request.id.clone();
    // The shared kernel timer is authoritative for completed runtime calls. Keep
    // one outer emergency timer only so the MCP hard-timeout path does not erase
    // an otherwise established runtime invocation from ergonomics telemetry.
    let mut hard_timeout_model_ergonomics = tool_name.as_deref().and_then(|name| {
        let mut timer =
            ModelErgonomicsTimer::start_with_arguments(name, &request.params["arguments"])?;
        timer.resolve_work_on_project_guidance_profile(policy, true);
        Some(timer)
    });
    let mut tool_correlation = crate::tool_runtime::ToolCallCorrelation::default();
    let mut model_ergonomics = None;
    // Window liveness needs request correlation even when trace retention is off.
    let active_trace_id = Some(server_trace_id.clone());
    // Keep the complete MCP dispatch future off the current thread's stack. The
    // handler state spans every method arm,
    // so nesting it inline under tracing + timeout can exhaust the default
    // ~2 MiB libtest/Tokio worker stack even when a request takes another arm.
    let outcome = match tokio::time::timeout(
        MCP_DISPATCH_HARD_TIMEOUT,
        REQUEST_PUBLIC_ORIGIN.scope(
            crate::public_ingress_auth::entry(depot).map(|entry| entry.origin.clone()),
            scope_active_trace(
                active_trace_id,
                Box::pin(handle_mcp_request_for_surface(
                    &runtime,
                    request,
                    auth.as_ref(),
                    protocol_era,
                    host_file_import_trust,
                    window.identity.as_ref(),
                    Some(&mut guard),
                    Some(&mut model_ergonomics),
                    compact_schemas,
                    server_mcp_apps_enabled,
                    Some(&mut tool_correlation),
                    surface,
                    default_project.as_deref(),
                )),
            ),
        ),
    )
    .await
    {
        Ok(outcome) => outcome,
        Err(_) => {
            let body = rpc_error(
                request_id,
                -32000,
                format!(
                    "server-side dispatch exceeded {}s hard limit; the tool may still be running — check session/job status before retrying",
                    MCP_DISPATCH_HARD_TIMEOUT.as_secs()
                ),
            );
            if let Some(uri) = computer_app_resource_uri.as_deref() {
                log_mcp_computer_app_resource_delivery(
                    uri,
                    protocol::era_label(protocol_era),
                    computer_app_ui_capability_present,
                    500,
                    Some(-32000),
                );
                record_computer_app_resource_audit(
                    protocol::era_label(protocol_era),
                    StatusCode::INTERNAL_SERVER_ERROR,
                    Some(-32000),
                );
            }
            let timeout_model_ergonomics = hard_timeout_model_ergonomics.take().map(|timer| {
                timer
                    .finish()
                    .record_for_pre_result_failure("dispatch_hard_timeout")
            });
            let audit_event = build_audit_event(
                false,
                StatusCode::INTERNAL_SERVER_ERROR,
                Some("mcp dispatch hard timeout".to_string()),
                timeout_model_ergonomics.as_ref(),
                &tool_correlation,
                None,
            );
            guard.capture_payload("final_response", &body);
            let estimated = estimate_json_bytes(&body);
            guard.response_serialized(500, estimated, Some(false), None, "dispatch_hard_timeout");
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
            res.render(Json(body));
            let timing =
                guard.handler_returned(500, estimated, Some(false), None, "dispatch_hard_timeout");
            finalize_mcp_tool_observability(
                &guard,
                &runtime,
                audit.as_ref().map(|(audit, _, _)| audit),
                audit_event,
                timeout_model_ergonomics.as_ref(),
                &mut live_window_request,
                timing,
                false,
                false,
                "unknown",
            );
            return;
        }
    };

    let job_correlation = match &outcome {
        McpOutcome::Ok(body) => mcp_tool_job_audit_correlation(tool_name.as_deref(), body),
        _ => McpToolJobAuditCorrelation::default(),
    };
    if tool_correlation.resolved_project.is_none() {
        tool_correlation.resolved_project = job_correlation.resolved_project.clone();
    }

    if let (Some(active), Some(project)) = (
        live_window_request.as_ref(),
        tool_correlation.resolved_project.as_deref(),
    ) {
        active.update(None, Some(project));
    }

    if let Some(audit) = tools_list_audit.as_ref() {
        match &outcome {
            McpOutcome::Ok(body) => {
                let summary = body.get("result").and_then(|result| {
                    mcp_tools_list_audit_summary(result, protocol_era, compact_schemas)
                });
                let mut event = ActionAuditRecord::new(
                    "mcp_tools_list",
                    summary.is_some(),
                    if summary.is_some() {
                        StatusCode::OK
                    } else {
                        StatusCode::INTERNAL_SERVER_ERROR
                    },
                );
                if let Some(summary) = summary {
                    event = event.summary(summary);
                }
                audit.record(event);
            }
            McpOutcome::BadRequest(_) => audit.record(
                ActionAuditRecord::new("mcp_tools_list", false, StatusCode::BAD_REQUEST)
                    .summary(json!({"transport": "mcp"})),
            ),
            McpOutcome::NotFound(_) => audit.record(
                ActionAuditRecord::new("mcp_tools_list", false, StatusCode::NOT_FOUND)
                    .summary(json!({"transport": "mcp"})),
            ),
            McpOutcome::Forbidden { .. } => audit.record(
                ActionAuditRecord::new("mcp_tools_list", false, StatusCode::FORBIDDEN)
                    .summary(json!({"transport": "mcp"})),
            ),
            McpOutcome::ArtifactExportStream { .. } | McpOutcome::Notification => {}
        }
    }

    if let Some(uri) = computer_app_resource_uri.as_deref() {
        log_mcp_computer_app_resource_outcome(
            uri,
            protocol_era,
            computer_app_ui_capability_present,
            &outcome,
        );
        let (status, mcp_error_code) = match &outcome {
            McpOutcome::Ok(_) | McpOutcome::ArtifactExportStream { .. } => (StatusCode::OK, None),
            McpOutcome::BadRequest(body) => {
                (StatusCode::BAD_REQUEST, body["error"]["code"].as_i64())
            }
            McpOutcome::NotFound(body) => (StatusCode::NOT_FOUND, body["error"]["code"].as_i64()),
            McpOutcome::Notification => (StatusCode::ACCEPTED, None),
            McpOutcome::Forbidden { .. } => (StatusCode::FORBIDDEN, None),
        };
        record_computer_app_resource_audit(
            protocol::era_label(protocol_era),
            status,
            mcp_error_code,
        );
    }

    if matches!(
        outcome,
        McpOutcome::Ok(_) | McpOutcome::ArtifactExportStream { .. }
    ) {
        if let Some(session_id) = window.issued_session_id.as_deref() {
            crate::client_window::set_mcp_session_header(res, session_id);
        }
    }

    match outcome {
        McpOutcome::Ok(mut body) => {
            // Protocol success: valid JSON-RPC result envelope.
            // Tool success: only meaningful for tools/call (isError / structuredContent.success).
            let tool_success = body
                .get("result")
                .and_then(|r| r.get("structuredContent"))
                .and_then(|s| s.get("success").or_else(|| s.get("ok")))
                .and_then(|v| v.as_bool());
            let audit_success = tool_success.unwrap_or(true);
            let mut audit_event = build_audit_event(
                audit_success,
                StatusCode::OK,
                if audit_success {
                    None
                } else {
                    body["result"]["structuredContent"]["error"]
                        .as_str()
                        .map(str::to_string)
                },
                model_ergonomics.as_ref(),
                &tool_correlation,
                Some(&job_correlation),
            );
            if surface == request_policy::McpSurface::Cli {
                cli::project_response(tool_name.as_deref(), &mut body);
            }
            if let Some((event, _)) = audit_event.as_mut() {
                if let Some(measurement) = body
                    .get("result")
                    .and_then(|result| mcp_tool_response_audit_summary(result, surface))
                {
                    event.summary["response_projection"] = measurement;
                }
            }
            guard.capture_payload("final_response", &body);
            let estimated = estimate_json_bytes(&body);
            guard.response_serialized(200, estimated, Some(true), tool_success, "ok");
            res.render(Json(body));
            let timing = guard.handler_returned(200, estimated, Some(true), tool_success, "ok");
            finalize_mcp_tool_observability(
                &guard,
                &runtime,
                audit.as_ref().map(|(audit, _, _)| audit),
                audit_event,
                model_ergonomics.as_ref(),
                &mut live_window_request,
                timing,
                false,
                true,
                if audit_success { "success" } else { "failure" },
            );
        }
        McpOutcome::ArtifactExportStream { id, plan } => {
            let audit_event =
                build_audit_event(true, StatusCode::OK, None, None, &tool_correlation, None);
            guard.response_serialized(200, None, Some(true), None, "artifact_export_stream");
            res.status_code(StatusCode::OK);
            let _ = res.add_header("content-type", "application/json", true);
            let receiver =
                resources::start_artifact_export_stream(runtime.clone(), id, auth.clone(), plan);
            let response_stream = stream::unfold(receiver, |mut receiver| async move {
                receiver.recv().await.map(|frame| (frame, receiver))
            });
            res.stream(response_stream);
            let timing =
                guard.handler_returned(200, None, Some(true), None, "artifact_export_stream");
            finalize_mcp_tool_observability(
                &guard,
                &runtime,
                audit.as_ref().map(|(audit, _, _)| audit),
                audit_event,
                None,
                &mut live_window_request,
                timing,
                true,
                false,
                "success",
            );
        }
        McpOutcome::BadRequest(body) => {
            let audit_event = build_audit_event(
                false,
                StatusCode::BAD_REQUEST,
                body["error"]["message"].as_str().map(str::to_string),
                model_ergonomics.as_ref(),
                &tool_correlation,
                None,
            );
            guard.capture_payload("final_response", &body);
            let estimated = estimate_json_bytes(&body);
            guard.response_serialized(400, estimated, Some(false), None, "bad_request");
            res.status_code(StatusCode::BAD_REQUEST);
            res.render(Json(body));
            let timing = guard.handler_returned(400, estimated, Some(false), None, "bad_request");
            finalize_mcp_tool_observability(
                &guard,
                &runtime,
                audit.as_ref().map(|(audit, _, _)| audit),
                audit_event,
                model_ergonomics.as_ref(),
                &mut live_window_request,
                timing,
                false,
                true,
                "failure",
            );
        }
        McpOutcome::NotFound(body) => {
            let audit_event = build_audit_event(
                false,
                StatusCode::NOT_FOUND,
                body["error"]["message"].as_str().map(str::to_string),
                model_ergonomics.as_ref(),
                &tool_correlation,
                None,
            );
            guard.capture_payload("final_response", &body);
            let estimated = estimate_json_bytes(&body);
            guard.response_serialized(404, estimated, Some(false), None, "not_found");
            res.status_code(StatusCode::NOT_FOUND);
            res.render(Json(body));
            let timing = guard.handler_returned(404, estimated, Some(false), None, "not_found");
            finalize_mcp_tool_observability(
                &guard,
                &runtime,
                audit.as_ref().map(|(audit, _, _)| audit),
                audit_event,
                model_ergonomics.as_ref(),
                &mut live_window_request,
                timing,
                false,
                true,
                "failure",
            );
        }
        McpOutcome::Forbidden {
            body,
            required_scope,
        } => {
            let audit_event = build_audit_event(
                false,
                StatusCode::FORBIDDEN,
                Some(format!(
                    "insufficient scope: {}",
                    required_scope.unwrap_or("unknown")
                )),
                model_ergonomics.as_ref(),
                &tool_correlation,
                None,
            );
            guard.capture_payload("final_response", &body);
            let estimated = estimate_json_bytes(&body);
            guard.response_serialized(403, estimated, Some(false), None, "forbidden");
            res.status_code(StatusCode::FORBIDDEN);
            if auth.as_ref().is_some_and(AuthContext::is_oauth_token)
                && crate::auth::oauth_scope_denial_is_delegable(required_scope)
            {
                let challenge = crate::auth::oauth_insufficient_scope_challenge(required_scope);
                if let Ok(val) = salvo::http::HeaderValue::from_str(&challenge) {
                    res.headers_mut().insert("www-authenticate", val);
                }
            }
            res.render(Json(body));
            let timing = guard.handler_returned(403, estimated, Some(false), None, "forbidden");
            finalize_mcp_tool_observability(
                &guard,
                &runtime,
                audit.as_ref().map(|(audit, _, _)| audit),
                audit_event,
                model_ergonomics.as_ref(),
                &mut live_window_request,
                timing,
                false,
                true,
                "failure",
            );
        }
        McpOutcome::Notification => {
            // JSON-RPC notifications carry no `id`; the server MUST NOT reply
            // with a JSON-RPC body. Acknowledge with 202 and an empty body.
            // Empty body size is known (0) without JSON serialization.
            guard.response_serialized(202, Some(0), Some(true), None, "notification");
            res.status_code(StatusCode::ACCEPTED);
            guard.handler_returned(202, Some(0), Some(true), None, "notification");
        }
    }
}

/// Core MCP JSON-RPC dispatch. Pure (no HTTP types) so it can be unit tested.
///
/// Business logic stays in `ToolRuntime`; this function only frames the
/// JSON-RPC envelope and translates tool results into MCP content blocks.
/// Test-friendly wrapper: no lifecycle hooks.
#[cfg(test)]
async fn handle_mcp_request(
    runtime: &ToolRuntime,
    request: JsonRpcRequest,
    auth: Option<&AuthContext>,
) -> McpOutcome {
    let protocol_era = inferred_protocol_era(&request);
    let compact_schemas = runtime.runtime_info.mcp_compact_schemas;
    let server_mcp_apps_enabled = runtime.runtime_info.mcp_apps_enabled;
    let outcome = handle_mcp_request_with_lifecycle(
        runtime,
        request,
        auth,
        protocol_era,
        HostFileImportTrust::Untrusted,
        None,
        None,
        None,
        compact_schemas,
        server_mcp_apps_enabled,
        None,
    )
    .await;
    match outcome {
        McpOutcome::ArtifactExportStream { id, plan } => {
            match resources::mcp_artifact_export_collect_stream_response(runtime, &id, auth, plan)
                .await
            {
                Ok(body) => McpOutcome::Ok(body),
                Err(error) => {
                    resources::mcp_artifact_export_read_error_outcome(Some(id), auth, error)
                }
            }
        }
        outcome => outcome,
    }
}

#[cfg(test)]
async fn handle_mcp_request_with_lifecycle(
    runtime: &ToolRuntime,
    request: JsonRpcRequest,
    auth: Option<&AuthContext>,
    protocol_era: McpProtocolEra,
    host_file_import_trust: HostFileImportTrust,
    window: Option<&crate::client_window::ClientWindow>,
    lifecycle: Option<&mut ToolRequestLifecycle>,
    model_ergonomics_out: Option<&mut Option<ModelErgonomicsRecord>>,
    compact_schemas: bool,
    server_mcp_apps_enabled: bool,
    correlation_out: Option<&mut crate::tool_runtime::ToolCallCorrelation>,
) -> McpOutcome {
    handle_mcp_request_for_surface(
        runtime,
        request,
        auth,
        protocol_era,
        host_file_import_trust,
        window,
        lifecycle,
        model_ergonomics_out,
        compact_schemas,
        server_mcp_apps_enabled,
        correlation_out,
        request_policy::McpSurface::Adaptive,
        None,
    )
    .await
}

async fn handle_mcp_request_for_surface(
    runtime: &ToolRuntime,
    request: JsonRpcRequest,
    auth: Option<&AuthContext>,
    protocol_era: McpProtocolEra,
    host_file_import_trust: HostFileImportTrust,
    window: Option<&crate::client_window::ClientWindow>,
    lifecycle: Option<&mut ToolRequestLifecycle>,
    model_ergonomics_out: Option<&mut Option<ModelErgonomicsRecord>>,
    compact_schemas: bool,
    server_mcp_apps_enabled: bool,
    correlation_out: Option<&mut crate::tool_runtime::ToolCallCorrelation>,
    surface: request_policy::McpSurface,
    default_project: Option<&str>,
) -> McpOutcome {
    let server_mcp_apps_enabled =
        server_mcp_apps_enabled && surface != request_policy::McpSurface::Cli;
    let exposure = runtime
        .runtime_info
        .mcp_tool_exposure
        .resolve(surface, auth);
    let stateless_2026 = protocol_era == McpProtocolEra::Stateless2026;
    let resource_read_bypasses_runtime_read = request.method == "resources/read"
        && resources::resource_read_bypasses_runtime_read(&request.params);
    let mcp_app_enabled =
        resources::mcp_app_enabled(server_mcp_apps_enabled, stateless_2026, &request.params);
    let runtime_resource_method =
        matches!(request.method.as_str(), "resources/list" | "resources/read");

    if auth.is_some()
        && (matches!(request.method.as_str(), "server/discover" | "tools/list")
            || (runtime_resource_method && !resource_read_bypasses_runtime_read)
            || (!stateless_2026
                && matches!(
                    request.method.as_str(),
                    "initialize" | "ping" | "notifications/initialized"
                )))
    {
        if let Some(outcome) = require_mcp_scope(auth, crate::auth::SCOPE_RUNTIME_READ) {
            return outcome;
        }
    }

    if auth.is_some_and(|auth| !auth.is_bootstrap())
        && !stateless_2026
        && !matches!(
            request.method.as_str(),
            "server/discover"
                | "initialize"
                | "ping"
                | "tools/list"
                | "tools/call"
                | "notifications/initialized"
                | "resources/list"
                | "resources/read"
        )
    {
        return scope_forbidden(
            auth,
            None,
            "authenticated caller cannot call unknown MCP methods",
        );
    }

    // A JSON-RPC request without an `id` member is a notification. Per the
    // JSON-RPC 2.0 and MCP specs the server MUST NOT reply with a JSON-RPC
    // response body, even if the method is unknown or malformed. We accept
    // the notification silently. `notifications/initialized` is the common
    // case sent by MCP clients after `initialize` completes.
    if request.id.is_none() {
        return McpOutcome::Notification;
    }

    let jsonrpc_valid = if stateless_2026 {
        request.jsonrpc.as_deref() == Some("2.0")
    } else {
        request.jsonrpc.as_deref().unwrap_or("2.0") == "2.0"
    };
    if !jsonrpc_valid {
        return McpOutcome::BadRequest(rpc_error(request.id, -32600, "jsonrpc must be '2.0'"));
    }

    let id = request.id.clone();
    let response = match request.method.as_str() {
        // MCP 2026-07-28 clients discover capabilities before issuing ordinary
        // requests. WebCodex supports the stateless tools path required by
        // modern clients while retaining the initialized 2025 tool-only
        // session lifecycle used by 2025-06-18 and ChatGPT 2025-11-25 clients.
        "server/discover" if stateless_2026 => {
            let mut payload = protocol::server_discover_payload(resources::server_capabilities(
                server_mcp_apps_enabled,
            ));
            if surface == request_policy::McpSurface::Cli {
                payload["instructions"] = cli::initialize_instructions(default_project);
            }
            rpc_result(id, payload)
        }
        "initialize" if !stateless_2026 => {
            let mut payload = protocol::legacy_initialize_payload(&request.params);
            if surface == request_policy::McpSurface::Cli {
                payload["instructions"] = cli::initialize_instructions(default_project);
            }
            rpc_result(id, payload)
        }
        "ping" if !stateless_2026 => rpc_result(id, json!({})),
        "tools/list" => {
            if surface == request_policy::McpSurface::Cli {
                let result =
                    cli::tools_list_with_exposure(auth, default_project.is_some(), exposure);
                return McpOutcome::Ok(rpc_result(
                    id,
                    if stateless_2026 {
                        response::mcp_stateless_result(result, true)
                    } else {
                        result
                    },
                ));
            }
            return tools::handle_list_with_runtime(
                runtime,
                id,
                auth,
                stateless_2026,
                compact_schemas,
                mcp_app_enabled,
            )
            .await;
        }
        "resources/list" if runtime_resource_method => {
            let mut outcome = resources::handle_list(runtime, id, mcp_app_enabled);
            if let McpOutcome::Ok(body) = &mut outcome {
                if let Some(resources) = body
                    .pointer_mut("/result/resources")
                    .and_then(Value::as_array_mut)
                {
                    resources.retain(|resource| {
                        resource["uri"]
                            .as_str()
                            .is_some_and(|uri| exposure.allows_resource(uri))
                    });
                }
            }
            return outcome;
        }
        "resources/read" if runtime_resource_method => {
            if request.params["uri"]
                .as_str()
                .is_some_and(|uri| !exposure.allows_resource(uri))
            {
                return McpOutcome::BadRequest(rpc_error(
                    id,
                    -32602,
                    "MCP App resource is unavailable on the configured tool surface",
                ));
            }
            return resources::handle_read(
                runtime,
                request.params,
                id,
                auth,
                server_mcp_apps_enabled,
            )
            .await;
        }
        "tools/call" => {
            return tools::handle_call(
                runtime,
                request.params,
                id,
                auth,
                stateless_2026,
                mcp_app_enabled,
                server_mcp_apps_enabled,
                host_file_import_trust,
                window,
                lifecycle,
                model_ergonomics_out,
                correlation_out,
                surface,
                default_project,
            )
            .await;
        }
        "notifications/initialized" if !stateless_2026 => rpc_result(id, json!({})),
        _ => {
            let body = rpc_error(id, -32601, format!("Method not found: {}", request.method));
            return if stateless_2026 {
                McpOutcome::NotFound(body)
            } else {
                McpOutcome::BadRequest(body)
            };
        }
    };
    McpOutcome::Ok(response)
}

fn require_mcp_scope(auth: Option<&AuthContext>, scope: &'static str) -> Option<McpOutcome> {
    let auth = auth?;
    if auth.has_scope(scope) {
        return None;
    }
    Some(scope_forbidden(
        Some(auth),
        Some(scope),
        format!("missing required scope: {}", scope),
    ))
}

fn scope_forbidden(
    auth: Option<&AuthContext>,
    required_scope: Option<&'static str>,
    description: impl Into<String>,
) -> McpOutcome {
    let mut body = crate::auth::scope_forbidden_body(auth, required_scope, description);
    if body["error"] == "insufficient_scope" {
        body["_meta"] = serde_json::json!({
            "mcp/www_authenticate": [crate::auth::oauth_insufficient_scope_challenge(required_scope)],
        });
    }
    McpOutcome::Forbidden {
        body,
        required_scope,
    }
}

#[cfg(test)]
#[path = "mcp_tests.rs"]
mod tests;

/// Exercise the CLI adapter from the shared local Runner test harness.
#[cfg(test)]
pub(crate) async fn cli_call_for_test(
    runtime: &ToolRuntime,
    tool: &str,
    arguments: Value,
    auth: &AuthContext,
) -> Value {
    cli_call_with_model_for_test(runtime, tool, arguments, auth)
        .await
        .1
}

/// Legacy CLI model results already use this surface's recovery routes before
/// text rendering. Validate them with the same existing Schema route projection.
#[cfg(test)]
pub(crate) fn cli_model_output_schema_for_test(tool: &str) -> Value {
    let mut schema = crate::tool_runtime::registry::output_schema_for_tool(tool);
    crate::model_surface::project_suggested_tool_call_schema(&mut schema, &|name| {
        cli::suggested_route(name, false)
    });
    schema
}

/// Observe one actual invocation immediately before and after CLI rendering.
/// This does not replay effects or construct a replacement Runtime result.
#[cfg(test)]
pub(crate) async fn cli_call_with_model_for_test(
    runtime: &ToolRuntime,
    tool: &str,
    arguments: Value,
    auth: &AuthContext,
) -> (Value, Value) {
    let params = if cli::is_direct(tool) {
        json!({"name":tool,"arguments":arguments})
    } else {
        json!({"name":"call_runtime_tool","arguments":{"tool":tool,"arguments":arguments}})
    };
    let request = JsonRpcRequest {
        jsonrpc: Some("2.0".into()),
        method: "tools/call".into(),
        id: Some(json!(1)),
        params,
    };
    let outcome = handle_mcp_request_for_surface(
        runtime,
        request,
        Some(auth),
        McpProtocolEra::Legacy,
        HostFileImportTrust::Untrusted,
        None,
        None,
        None,
        true,
        true,
        None,
        request_policy::McpSurface::Cli,
        None,
    )
    .await;
    let McpOutcome::Ok(mut body) = outcome else {
        panic!("{outcome:?}")
    };
    let model = body["result"]["structuredContent"].clone();
    cli::project_response(Some(tool), &mut body);
    (model, body)
}