@pheem49/mint 1.15.0 → 1.16.0

package/crates/mint-core/src/integrations/mcp_catalog.rs

@@ -0,0 +1,267 @@
+//! Session-scoped discovery and local validation. No command is sent by preflight.
+use super::*;
+use sha2::{Digest, Sha256};
+use std::time::Instant;
+
+const MAX_DEFINITION_BYTES: usize = 256 * 1024;
+
+pub(super) struct Catalog {
+    identity: String,
+    generation: u64,
+    loaded: Instant,
+    tools: BTreeMap<String, Arc<ToolDefinition>>,
+}
+
+pub struct ToolDefinition {
+    pub value: Value,
+    pub fingerprint: String,
+    validator: Result<jsonschema::Validator, String>,
+}
+
+pub(crate) struct BoundTool {
+    pub definition: Arc<ToolDefinition>,
+    pub binding: SessionBinding,
+}
+
+impl ToolDefinition {
+    pub(crate) fn valid_schema(&self) -> Result<(), McpError> {
+        self.validator
+            .as_ref()
+            .map(|_| ())
+            .map_err(|e| McpError::Preflight(e.clone()))
+    }
+    pub(crate) fn validate_output(&self, value: &Value) -> Result<(), McpError> {
+        let validator = self.output_validator()?;
+        validator.validate(value).map_err(|e| {
+            McpError::Preflight(format!(
+                "Invalid device observation at {}: {e}",
+                e.instance_path()
+            ))
+        })
+    }
+    pub(crate) fn output_validator(&self) -> Result<jsonschema::Validator, McpError> {
+        let schema = self
+            .value
+            .get("outputSchema")
+            .ok_or_else(|| McpError::Preflight("Mint Device v1 requires outputSchema".into()))?;
+        jsonschema::options()
+            .with_retriever(DenyExternalReferences)
+            .build(schema)
+            .map_err(|e| McpError::Preflight(format!("Invalid device outputSchema: {e}")))
+    }
+    pub fn validate(&self, arguments: &Value) -> Result<(), McpError> {
+        let validator = self
+            .validator
+            .as_ref()
+            .map_err(|e| McpError::Preflight(e.clone()))?;
+        if !arguments.is_object() {
+            return Err(McpError::Preflight("arguments must be an object".into()));
+        }
+        let errors: Vec<String> = validator
+            .iter_errors(arguments)
+            .take(8)
+            .map(|e| format!("{}: {}", e.instance_path(), e))
+            .collect();
+        if errors.is_empty() {
+            Ok(())
+        } else {
+            Err(McpError::Preflight(errors.join("; ")))
+        }
+    }
+}
+
+pub(crate) fn tool_timeout(config: &MintConfig, server: &str) -> Result<u64, McpError> {
+    let servers = configured_mcp_servers(config)?;
+    let entry = servers
+        .get(server)
+        .ok_or_else(|| McpError::MissingServer(server.into()))?;
+    if entry.disabled {
+        close_mcp_session(server);
+        return Err(McpError::Disabled(server.into()));
+    }
+    Ok(entry.timeout_secs.unwrap_or(300))
+}
+
+pub async fn describe_tool(
+    config: &MintConfig,
+    server: &str,
+    tool: &str,
+    chat: &str,
+) -> Result<Arc<ToolDefinition>, McpError> {
+    Ok(resolve_tool(config, server, tool, chat, None)
+        .await?
+        .definition)
+}
+
+pub(crate) async fn resolve_tool(
+    config: &MintConfig,
+    server: &str,
+    tool: &str,
+    chat: &str,
+    pinned: Option<&SessionBinding>,
+) -> Result<BoundTool, McpError> {
+    let (tools, binding) = calls::McpScope::new(chat)
+        .run(catalog_tools(config, server, chat, pinned), MCP_TIMEOUT)
+        .await?;
+    let definition = tools.get(tool).cloned().ok_or_else(|| {
+        McpError::Preflight(format!(
+            "Unknown tool '{server}/{tool}'. Read mcp_list_tools; do not guess tool names."
+        ))
+    })?;
+    Ok(BoundTool {
+        definition,
+        binding,
+    })
+}
+
+pub async fn list_tools(config: &MintConfig, server: &str, chat: &str) -> Result<Value, McpError> {
+    let (tools, _) = calls::McpScope::new(chat)
+        .run(catalog_tools(config, server, chat, None), MCP_TIMEOUT)
+        .await?;
+    Ok(json!({"tools":tools.values().map(|t|t.value.clone()).collect::<Vec<_>>()}))
+}
+
+async fn catalog_tools(
+    config: &MintConfig,
+    server: &str,
+    chat: &str,
+    pinned: Option<&SessionBinding>,
+) -> Result<(BTreeMap<String, Arc<ToolDefinition>>, SessionBinding), McpError> {
+    let cfg = config.clone();
+    let name = server.to_owned();
+    let pinned = pinned.cloned();
+    let (cache, generation, binding) = tokio::task::spawn_blocking(move || {
+        let session = if let Some(binding) = &pinned {
+            binding.check()?;
+            binding.session.clone()
+        } else {
+            get_or_start_session(&cfg, &name)?
+        };
+        let locked = session.lock().unwrap();
+        let generation = match &locked.backend {
+            McpSessionBackend::Stdio(s) => Arc::clone(&s.catalog_generation),
+            McpSessionBackend::Remote(s) => Arc::clone(&s.catalog_generation),
+        };
+        let binding = SessionBinding {
+            server: name,
+            session: session.clone(),
+            generation: generation.load(Ordering::Acquire),
+            generation_counter: Arc::clone(&generation),
+        };
+        Ok::<_, McpError>((Arc::clone(&locked.catalog), generation, binding))
+    })
+    .await
+    .map_err(|e| McpError::Remote(e.to_string()))??;
+    let mut cached = cache.lock().await;
+    let epoch = generation.load(Ordering::Acquire);
+    if let Some(catalog) = &*cached
+        && catalog.generation == epoch
+        && catalog.loaded.elapsed() < Duration::from_secs(60)
+    {
+        binding.check()?;
+        return Ok((catalog.tools.clone(), binding));
+    }
+    let identity = cached
+        .as_ref()
+        .map(|c| c.identity.clone())
+        .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
+    let mut cursor = None;
+    let mut cursors = std::collections::HashSet::new();
+    let mut tools = BTreeMap::new();
+    for page in 0..100 {
+        let response = calls::request_on_session(
+            &binding,
+            "tools/list",
+            json!({"cursor":cursor})
+                .as_object()
+                .map(|m| {
+                    let mut m = m.clone();
+                    if cursor.is_none() {
+                        m.remove("cursor");
+                    }
+                    Value::Object(m)
+                })
+                .unwrap(),
+            chat,
+            MCP_TIMEOUT,
+            |_| {},
+        )
+        .await?;
+        let entries = response["tools"]
+            .as_array()
+            .ok_or_else(|| McpError::Preflight("tools/list did not return a tools array".into()))?;
+        for entry in entries {
+            let name = entry["name"]
+                .as_str()
+                .filter(|n| !n.is_empty())
+                .ok_or_else(|| McpError::Preflight("tool definition has no name".into()))?;
+            let serialized = serde_json::to_string(entry).unwrap();
+            if serialized.len() > MAX_DEFINITION_BYTES || tools.len() >= 1000 {
+                return Err(McpError::Preflight("Discovery exceeds 1,000 tools or 256 KiB/definition; no partial schema will be used".into()));
+            }
+            let validator = entry
+                .get("inputSchema")
+                .ok_or_else(|| "Missing inputSchema".to_string())
+                .and_then(|schema| {
+                    if schema["type"] != "object" {
+                        return Err("inputSchema must declare an object".into());
+                    }
+                    jsonschema::options()
+                        .with_retriever(DenyExternalReferences)
+                        .build(schema)
+                        .map_err(|e| format!("Invalid or unsupported inputSchema: {e}"))
+                });
+            let fingerprint = format!("{:x}", Sha256::digest(format!("{identity}:{serialized}")));
+            if tools
+                .insert(
+                    name.into(),
+                    Arc::new(ToolDefinition {
+                        value: entry.clone(),
+                        fingerprint,
+                        validator,
+                    }),
+                )
+                .is_some()
+            {
+                return Err(McpError::Preflight(format!("Duplicate tool name: {name}")));
+            }
+        }
+        cursor = match response.get("nextCursor") {
+            None | Some(Value::Null) => None,
+            Some(Value::String(s)) if !s.is_empty() => Some(s.clone()),
+            _ => return Err(McpError::Preflight("Invalid pagination cursor".into())),
+        };
+        if cursor.is_none() {
+            break;
+        }
+        if page == 99 || !cursors.insert(cursor.clone().unwrap()) {
+            return Err(McpError::Preflight(
+                "Discovery pagination exceeded its bound or repeated a cursor".into(),
+            ));
+        }
+    }
+    if generation.load(Ordering::Acquire) != epoch {
+        return Err(McpError::Preflight(
+            "Tool definitions changed during discovery; prepare again before calling".into(),
+        ));
+    }
+    let result = tools.clone();
+    *cached = Some(Catalog {
+        identity,
+        generation: epoch,
+        loaded: Instant::now(),
+        tools,
+    });
+    binding.check()?;
+    Ok((result, binding))
+}
+
+struct DenyExternalReferences;
+impl jsonschema::Retrieve for DenyExternalReferences {
+    fn retrieve(
+        &self,
+        uri: &jsonschema::Uri<String>,
+    ) -> Result<Value, Box<dyn std::error::Error + Send + Sync>> {
+        Err(format!("External schema reference is disabled: {uri}").into())
+    }
+}

package/crates/mint-core/src/integrations/mcp_device.rs

@@ -0,0 +1,319 @@
+//! Opt-in Mint Device v1 orchestration; transports and physical I/O stay separate.
+use super::*;
+use crate::integrations::mcp_result::ToolStatus;
+use std::time::Instant;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DevicePhase {
+    Accepted,
+    Running,
+    Verified,
+    Failed,
+    Unconfirmed,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DeviceUpdate {
+    pub state: DevicePhase,
+    pub device_id: Option<String>,
+    pub operation_id: Option<String>,
+    pub target: Value,
+    pub actual: Value,
+    pub observation_seq: Option<u64>,
+    pub elapsed_secs: u64,
+    pub message: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct Observation {
+    device_id: String,
+    operation_id: String,
+    state: String,
+    target: serde_json::Map<String, Value>,
+    actual: serde_json::Map<String, Value>,
+    observation_seq: u64,
+    error: Option<String>,
+}
+
+impl Observation {
+    fn read(value: &Value, definition: &catalog::ToolDefinition) -> Result<Self, McpError> {
+        definition.validate_output(value)?;
+        let result: Self = serde_json::from_value(value.clone())
+            .map_err(|e| McpError::Preflight(format!("Invalid Mint Device v1 observation: {e}")))?;
+        if result.device_id.is_empty()
+            || result.operation_id.is_empty()
+            || !matches!(
+                result.state.as_str(),
+                "accepted" | "running" | "completed" | "failed"
+            )
+        {
+            return Err(McpError::Preflight(
+                "Invalid device identity or state".into(),
+            ));
+        }
+        Ok(result)
+    }
+    fn update(&self, state: DevicePhase, elapsed_secs: u64, message: String) -> DeviceUpdate {
+        DeviceUpdate {
+            state,
+            device_id: Some(self.device_id.clone()),
+            operation_id: Some(self.operation_id.clone()),
+            target: Value::Object(self.target.clone()),
+            actual: Value::Object(self.actual.clone()),
+            observation_seq: Some(self.observation_seq),
+            elapsed_secs,
+            message,
+        }
+    }
+}
+
+pub(crate) fn status_tool(
+    definition: &catalog::ToolDefinition,
+) -> Result<Option<String>, McpError> {
+    let Some(meta) = definition.value.pointer("/_meta/mint~1device") else {
+        return Ok(None);
+    };
+    if meta["version"] != 1 {
+        return Err(McpError::Preflight(
+            "Unsupported Mint Device contract version".into(),
+        ));
+    }
+    let status = meta["statusTool"]
+        .as_str()
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| McpError::Preflight("Mint Device command has no statusTool".into()))?;
+    Ok(Some(status.into()))
+}
+
+pub(crate) struct DeviceResult {
+    pub receipt: Value,
+    pub status: ToolStatus,
+    pub message: String,
+    pub completion_unconfirmed: bool,
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn call_verified(
+    config: &MintConfig,
+    server: &str,
+    tool: &str,
+    arguments: Value,
+    chat: &str,
+    definition: Arc<catalog::ToolDefinition>,
+    status_name: &str,
+    status_definition: Arc<catalog::ToolDefinition>,
+    mut progress: impl FnMut(McpProgress) + Send,
+    mut state: impl FnMut(DeviceUpdate) + Send,
+) -> DeviceResult {
+    let started = Instant::now();
+    let timeout = Duration::from_secs(catalog::tool_timeout(config, server).unwrap_or(300));
+    let deadline = tokio::time::Instant::now() + timeout;
+    let mut receipt = Value::Null;
+    let mut last = None::<Observation>;
+    let mut command_attempted = false;
+    let work = async {
+        let current = catalog::resolve_tool(config, server, tool, chat, None).await?;
+        if current.definition.fingerprint != definition.fingerprint {
+            return Err(McpError::Preflight(
+                "Definition changed; read it again before sending the command".into(),
+            ));
+        }
+        let current_status =
+            catalog::resolve_tool(config, server, status_name, chat, Some(&current.binding))
+                .await?;
+        if current_status.definition.fingerprint != status_definition.fingerprint
+            || !current.binding.same_session(&current_status.binding)
+        {
+            return Err(McpError::Preflight(
+                "Status definition changed before command dispatch; read it again".into(),
+            ));
+        }
+        command_attempted = true;
+        receipt = calls::call_bound_tool(
+            config,
+            server,
+            tool,
+            arguments.clone(),
+            chat,
+            &current,
+            &mut progress,
+        )
+        .await?;
+        if receipt["isError"] == true {
+            return Err(McpError::Tool(receipt.clone()));
+        }
+        let accepted = Observation::read(&receipt["structuredContent"], &definition)?;
+        if arguments["deviceId"].as_str() != Some(accepted.device_id.as_str()) {
+            return Err(McpError::Preflight(
+                "Receipt deviceId does not match the command".into(),
+            ));
+        }
+        if accepted.state == "failed" {
+            state(
+                accepted.update(
+                    DevicePhase::Failed,
+                    started.elapsed().as_secs(),
+                    accepted
+                        .error
+                        .clone()
+                        .unwrap_or_else(|| "Device reported physical failure".into()),
+                ),
+            );
+            last = Some(accepted);
+            return Err(McpError::Remote("Device reported physical failure".into()));
+        }
+        let status_arguments =
+            json!({"deviceId":accepted.device_id,"operationId":accepted.operation_id});
+        status_definition.validate(&status_arguments)?;
+        state(accepted.update(
+            DevicePhase::Accepted,
+            started.elapsed().as_secs(),
+            "Command accepted; physical completion is not yet confirmed".into(),
+        ));
+        let acceptance_seq = accepted.observation_seq;
+        let device = accepted.device_id.clone();
+        let operation = accepted.operation_id.clone();
+        let target = accepted.target.clone();
+        last = Some(accepted);
+        loop {
+            let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
+            if remaining.is_zero() {
+                return Err(McpError::Timeout);
+            }
+            let response = tokio::time::timeout(
+                remaining.min(Duration::from_secs(10)),
+                calls::call_bound_tool(
+                    config,
+                    server,
+                    status_name,
+                    status_arguments.clone(),
+                    chat,
+                    &current_status,
+                    &mut progress,
+                ),
+            )
+            .await
+            .map_err(|_| McpError::Timeout)??;
+            if response["isError"] == true {
+                return Err(McpError::Tool(response));
+            }
+            let observed = Observation::read(&response["structuredContent"], &status_definition)?;
+            if observed.device_id != device
+                || observed.operation_id != operation
+                || observed.target != target
+            {
+                return Err(McpError::Preflight("Status does not match this device, operationId, and target; completion is unconfirmed".into()));
+            }
+            if observed.observation_seq > acceptance_seq
+                && observed.observation_seq > last.as_ref().unwrap().observation_seq
+            {
+                if observed.state == "failed" {
+                    state(
+                        observed.update(
+                            DevicePhase::Failed,
+                            started.elapsed().as_secs(),
+                            observed
+                                .error
+                                .clone()
+                                .unwrap_or_else(|| "Device reported physical failure".into()),
+                        ),
+                    );
+                    last = Some(observed);
+                    return Err(McpError::Remote("Device reported physical failure".into()));
+                }
+                if observed.state == "completed" {
+                    state(observed.update(
+                        DevicePhase::Verified,
+                        started.elapsed().as_secs(),
+                        "Fresh device observation confirmed completion".into(),
+                    ));
+                    receipt["structuredContent"] = response["structuredContent"].clone();
+                    last = Some(observed);
+                    return Ok(());
+                }
+                state(observed.update(
+                    DevicePhase::Running,
+                    started.elapsed().as_secs(),
+                    "Device is working; awaiting a fresh completed observation".into(),
+                ));
+                last = Some(observed);
+            }
+            tokio::time::sleep(Duration::from_secs(1)).await;
+        }
+    };
+    let result = calls::McpScope::new(chat).run(work, timeout).await;
+    match result {
+        Ok(()) => DeviceResult {
+            receipt,
+            status: ToolStatus::Success,
+            message: "Device completion verified from a fresh observation".into(),
+            completion_unconfirmed: false,
+        },
+        Err(error) => {
+            let error = if !receipt.is_null() {
+                match error {
+                    McpError::Preflight(reason) => {
+                        McpError::Remote(format!("Device verification failed: {reason}"))
+                    }
+                    other => other,
+                }
+            } else {
+                error
+            };
+            let physical_failure = last.as_ref().is_some_and(|o| o.state == "failed");
+            let completion_unconfirmed = command_attempted
+                && !physical_failure
+                && !matches!(&error, McpError::Preflight(_) | McpError::NotAllowed { .. });
+            let message = if physical_failure {
+                format!(
+                    "Device reported physical failure: {}",
+                    last.as_ref()
+                        .unwrap()
+                        .error
+                        .as_deref()
+                        .unwrap_or("unknown failure")
+                )
+            } else {
+                format!(
+                    "{error}; remote completion is unconfirmed. Do not automatically repeat the command. Canceling a wait does not physically stop the device."
+                )
+            };
+            if !physical_failure {
+                let update = last
+                    .as_ref()
+                    .map(|o| {
+                        o.update(
+                            DevicePhase::Unconfirmed,
+                            started.elapsed().as_secs(),
+                            message.clone(),
+                        )
+                    })
+                    .unwrap_or(DeviceUpdate {
+                        state: DevicePhase::Unconfirmed,
+                        device_id: arguments["deviceId"].as_str().map(str::to_owned),
+                        operation_id: None,
+                        target: Value::Null,
+                        actual: Value::Null,
+                        observation_seq: None,
+                        elapsed_secs: started.elapsed().as_secs(),
+                        message: message.clone(),
+                    });
+                state(update);
+            }
+            let status = match error {
+                McpError::Timeout | McpError::TimeoutUndelivered => ToolStatus::TimedOut,
+                McpError::Cancelled | McpError::CancelledUndelivered => ToolStatus::Cancelled,
+                _ => ToolStatus::Failed,
+            };
+            DeviceResult {
+                receipt,
+                status,
+                message,
+                completion_unconfirmed,
+            }
+        }
+    }
+}