solo_api/

mcp.rs

// SPDX-License-Identifier: Apache-2.0

//! MCP (Model Context Protocol) server for Solo.
//!
//! Exposes thirteen tools to MCP clients (Claude Desktop, Cursor, etc.):
//!
//! Episode tools (v0.1+):
//!   - `memory_remember(content, source_type?, source_id?)` — store an
//!     episode. Returns the new MemoryId.
//!   - `memory_recall(query, limit?)` — vector search. Returns the top-K
//!     matches with content + tier + status.
//!   - `memory_forget(memory_id, reason?)` — soft-delete an episode.
//!   - `memory_inspect(memory_id)` — return the full episode record.
//!
//! Derived-layer tools (v0.4.0+):
//!   - `memory_themes(window_days?, limit?)` — list cluster themes.
//!   - `memory_facts_about(subject, ...)` — query the structured-fact
//!     knowledge graph (subject-predicate-object triples).
//!   - `memory_contradictions(limit?)` — disagreements flagged during
//!     consolidation.
//!
//! Derived-layer tools (v0.5.0+):
//!   - `memory_inspect_cluster(cluster_id, full_content?)` — drill
//!     into one cluster's abstraction + source episodes (truncated).
//!
//! Document tools (v0.7.0+):
//!   - `memory_ingest_document(path)` — read a file from disk, split it
//!     into chunks, embed each, and store under documents/document_chunks.
//!   - `memory_search_docs(query, limit?)` — vector search restricted to
//!     document chunks; returns chunk content + parent-doc context.
//!   - `memory_inspect_document(doc_id)` — show one document's metadata
//!     plus a previewed list of its chunks.
//!   - `memory_list_documents(limit?, offset?, include_forgotten?)` —
//!     paginate over ingested documents, newest first.
//!   - `memory_forget_document(doc_id)` — soft-delete a document; chunks
//!     stop appearing in `memory_search_docs` and tombstone in HNSW.
//!
//! ## Transport
//!
//! `serve_stdio` wires the server to stdin/stdout for use as a subprocess
//! ("`claude_desktop_config.json` or `~/.cursor/mcp.json` invokes
//! `solo mcp-stdio`"). The function awaits a graceful shutdown when stdin
//! closes (parent disconnects) — same lifecycle as `solo daemon`'s
//! Ctrl+C path.
//!
//! ## What's deferred
//!
//! - SSE/HTTP transports — `rmcp` ships them, but v0.1 ships stdio only.
//! - `prompts/` and `resources/` capabilities — not needed for the
//!   four-tool surface; ServerHandler defaults return empty lists.
//! - Tool argument validation beyond JSON Schema typing — we trust rmcp
//!   to deserialize per the schema, then serde-deserialize into our
//!   typed param structs. Bad inputs surface as clear errors.

use std::sync::Arc;

use rmcp::handler::server::ServerHandler;
use rmcp::model::{
    CallToolRequestParam, CallToolResult, Content, Implementation, ListToolsResult,
    PaginatedRequestParam, ProtocolVersion, ServerCapabilities, ServerInfo, Tool,
    ToolsCapability,
};
use rmcp::service::{RequestContext, RoleServer};
use rmcp::{Error as McpError, ServiceExt};
use serde::{Deserialize, Serialize};
use solo_core::{
    Confidence, DocumentId, EncodingContext, Episode, MemoryId, Tier,
};
use solo_storage::{TenantHandle, TenantRegistry};
use std::str::FromStr;

/// The MCP server. Cheap to clone — every field is `Arc`-cloneable.
///
/// v0.8.0 P2: an MCP session resolves to **one tenant**. The session's
/// `tenant_handle` is resolved at `initialize` time (today: from the
/// CLI invocation via `solo mcp-stdio --tenant <id>`; future versions
/// may resolve per-bearer-token via OIDC). Subsequent `tools/call`
/// invocations route through the cached handle without re-resolving.
/// Operators that need multi-tenant MCP spawn one `solo mcp-stdio`
/// subprocess per tenant.
#[derive(Clone)]
pub struct SoloMcpServer {
    inner: Arc<Inner>,
}

struct Inner {
    /// Multi-tenant registry shared across all sessions. Held so that a
    /// future MCP capability that lists/inspects other tenants has a
    /// path to them (out of scope for v0.8.0 P2). P3 (auth) will use
    /// this to re-resolve the tenant from a bearer-token claim.
    #[allow(dead_code)]
    registry: Arc<TenantRegistry>,
    /// The tenant this MCP session speaks for. Resolved at session
    /// construction time.
    tenant: Arc<TenantHandle>,
    /// Read-path aliases for the canonical `"user"` subject. Sourced
    /// from `solo.config.toml` `[identity] user_aliases`; threaded
    /// through to `solo_query::facts_about` so a query for `"alex"`
    /// also surfaces rows historically extracted as `"user"`. Empty
    /// vec = behave as today (no expansion).
    user_aliases: Vec<String>,
    /// v0.8.0 P4 audit-log principal for this MCP session. MCP is
    /// bearer-only (no OIDC story in the spec), so the principal is
    /// effectively `"bearer"` when the daemon was started with
    /// `--bearer-token-file` and `None` otherwise. Persisted here so
    /// every tool dispatch threads it into the audit emit without
    /// reconstructing it per call.
    audit_principal: Option<String>,
}

/// v0.8.1 P2: env var name MCP clients set when launching the server
/// process to attribute audit rows on the stdio transport. Closes the
/// v0.8.0 known-issue gap where MCP audit rows always carried
/// `principal_subject = NULL` on the daemon path.
///
/// Precedence (when the future HTTP-MCP transport lands):
///   1. `Authorization: Bearer <token>` header on the HTTP-MCP request
///      (resolved through `AuthConfig::Bearer` validator).
///   2. `SOLO_MCP_PRINCIPAL_TOKEN` env var on the spawned process.
///
/// For the v0.8.x stdio-only world only the env-var path applies; the
/// header path is a no-op (no HTTP transport wired). The constant lives
/// at module scope so external callers (CLI subcommand, tests) reference
/// it by name rather than re-typing the string literal.
pub const ENV_MCP_PRINCIPAL_TOKEN: &str = "SOLO_MCP_PRINCIPAL_TOKEN";

/// v0.8.1 P2: resolve the MCP-session principal at `initialize`-time.
///
/// Reads `SOLO_MCP_PRINCIPAL_TOKEN` env var (stdio path); future HTTP-MCP
/// callers will pass the bearer header value in via the explicit
/// `header_value` arg. The header beats the env when both are present.
///
/// Returns `Some(subject)` on resolution success; `None` when neither
/// source carries a non-empty value. Empty / whitespace-only values are
/// treated as absent so an accidentally-set `SOLO_MCP_PRINCIPAL_TOKEN=""`
/// in a launcher script doesn't pin every audit row to a blank principal.
///
/// The current implementation treats the env var value as the principal
/// subject directly. A future hardening pass can validate against the
/// daemon's `[auth] bearer.token` config to refuse mismatched tokens —
/// today the env var is operator-trusted (same trust model as
/// `SOLO_PASSPHRASE`).
pub fn resolve_mcp_principal(header_value: Option<&str>) -> Option<String> {
    // HTTP-MCP path wins when configured.
    if let Some(h) = header_value {
        if let Some(token) = h.strip_prefix("Bearer ") {
            let trimmed = token.trim();
            if !trimmed.is_empty() {
                // Header carries the raw bearer token. Same shape as the
                // stdio env-var path: the *value* is the principal
                // subject in v0.8.1; v0.8.2+ may validate against a
                // configured token set and surface the JWT `sub` claim
                // instead.
                return Some(trimmed.to_string());
            }
        }
    }
    // Stdio env-var fallback.
    match std::env::var(ENV_MCP_PRINCIPAL_TOKEN) {
        Ok(v) => {
            let trimmed = v.trim();
            if trimmed.is_empty() {
                None
            } else {
                Some(trimmed.to_string())
            }
        }
        Err(_) => None,
    }
}

impl SoloMcpServer {
    /// Build a server speaking for `tenant` (v0.8.0 P2 — one MCP session
    /// ↔ one tenant). The registry is held so future capabilities can
    /// reach across tenants if needed; today every handler routes
    /// through `self.inner.tenant`.
    ///
    /// v0.8.1 P2: auto-resolves the audit principal from the
    /// `SOLO_MCP_PRINCIPAL_TOKEN` env var (see [`resolve_mcp_principal`]).
    /// When neither the env var nor a header is set, the principal stays
    /// `None` — preserving v0.8.0 behavior for single-user setups.
    pub fn new_for_tenant(
        registry: Arc<TenantRegistry>,
        tenant: Arc<TenantHandle>,
        user_aliases: Vec<String>,
    ) -> Self {
        let principal = resolve_mcp_principal(None);
        Self::new_for_tenant_with_principal(registry, tenant, user_aliases, principal)
    }

    /// v0.8.0 P4: like [`Self::new_for_tenant`], but records an explicit
    /// audit principal subject for every tool dispatch. MCP is
    /// bearer-only at v0.8.0 — the orchestration layer (today: the
    /// daemon's `--bearer-token-file` path) decides whether a session
    /// counts as "bearer-authenticated" and passes `Some("bearer")`;
    /// CLI / unauth paths pass `None`.
    ///
    /// v0.8.1 P2: when the caller passes `audit_principal = None`, the
    /// env-var auto-resolution still runs (in `new_for_tenant`). Callers
    /// who want to *explicitly* suppress env-var resolution can call
    /// this method with `None` after `std::env::remove_var(...)`, or use
    /// the dedicated test constructor that bypasses env reads.
    pub fn new_for_tenant_with_principal(
        registry: Arc<TenantRegistry>,
        tenant: Arc<TenantHandle>,
        user_aliases: Vec<String>,
        audit_principal: Option<String>,
    ) -> Self {
        Self {
            inner: Arc::new(Inner {
                registry,
                tenant,
                user_aliases,
                audit_principal,
            }),
        }
    }
}

/// Convenience: run the server over stdio and await its termination.
/// Returns when stdin closes (parent disconnect) or the runtime exits.
pub async fn serve_stdio(server: SoloMcpServer) -> anyhow::Result<()> {
    use rmcp::transport::io::stdio;
    let (stdin, stdout) = stdio();
    let running = server.serve((stdin, stdout)).await?;
    running.waiting().await?;
    Ok(())
}

// ---------------------------------------------------------------------------
// Tool argument schemas
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RememberArgs {
    pub content: String,
    #[serde(default)]
    pub source_type: Option<String>,
    #[serde(default)]
    pub source_id: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RecallArgs {
    pub query: String,
    #[serde(default = "default_limit")]
    pub limit: usize,
}

fn default_limit() -> usize {
    5
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ForgetArgs {
    pub memory_id: String,
    #[serde(default = "default_forget_reason")]
    pub reason: String,
}

fn default_forget_reason() -> String {
    "user-initiated via MCP".into()
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InspectArgs {
    pub memory_id: String,
}

// Path 1 derived-layer tools (v0.4.0+) — query the Steward's outputs.
// `solo_query::derived` is the single source of truth; these handlers
// just translate JSON args to function args and serialise the result
// vec to JSON for the MCP wire.

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ThemesArgs {
    /// Optional time window in days; `None` = unfiltered, return up
    /// to `limit` most-recent themes across all time. `Some(7)` =
    /// "themes from the last week".
    #[serde(default)]
    pub window_days: Option<i64>,
    #[serde(default = "default_limit")]
    pub limit: usize,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FactsAboutArgs {
    /// Subject id to query — required (predicate-only scans
    /// intentionally not supported).
    pub subject: String,
    #[serde(default)]
    pub predicate: Option<String>,
    #[serde(default)]
    pub since_ms: Option<i64>,
    #[serde(default)]
    pub until_ms: Option<i64>,
    /// v0.5.1 Priority 8 — widen the query to also match rows where
    /// `subject` appears as the object (e.g. surface "Sam pushes back
    /// on PRs about Maya" under `facts_about(subject="maya")`).
    /// Default `false` preserves v0.5.0 behaviour.
    #[serde(default)]
    pub include_as_object: bool,
    #[serde(default = "default_limit")]
    pub limit: usize,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContradictionsArgs {
    #[serde(default = "default_limit")]
    pub limit: usize,
}

/// Args for `memory_inspect_cluster` (v0.5.0 Priority 3). `cluster_id`
/// is required; `full_content` is opt-in for the rare power-user case
/// where 200-char-per-episode truncation is too aggressive.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InspectClusterArgs {
    pub cluster_id: String,
    /// If `true`, episode `content` fields are returned verbatim. If
    /// `false` or omitted (the default), each episode's content is
    /// truncated to `solo_query::EPISODE_TRUNCATE_CHARS` chars with a
    /// trailing `…`.
    #[serde(default)]
    pub full_content: bool,
}

// Document tools (v0.7.0+). Five args structs paired with five handlers.
// Wire shapes per `docs/dev-log/0083-v0.7.0-implementation-plan.md` §2 P5.

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct IngestDocumentArgs {
    /// Server-side filesystem path to the file to ingest. Must be
    /// readable by the Solo process. The writer parses the file by
    /// extension, splits it into ~500-token chunks, embeds each, and
    /// stores them under `documents` + `document_chunks`.
    pub path: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SearchDocsArgs {
    pub query: String,
    #[serde(default = "default_search_docs_limit")]
    pub limit: usize,
}

fn default_search_docs_limit() -> usize {
    5
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InspectDocumentArgs {
    pub doc_id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ListDocumentsArgs {
    #[serde(default = "default_list_documents_limit")]
    pub limit: usize,
    #[serde(default)]
    pub offset: usize,
    /// If `true`, also include documents the user has forgotten. Default
    /// `false` matches the agent-UX expectation that recall + listing
    /// ignore soft-deleted rows.
    #[serde(default)]
    pub include_forgotten: bool,
}

fn default_list_documents_limit() -> usize {
    20
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ForgetDocumentArgs {
    pub doc_id: String,
}

// ---------------------------------------------------------------------------
// ServerHandler implementation
// ---------------------------------------------------------------------------

impl ServerHandler for SoloMcpServer {
    fn get_info(&self) -> ServerInfo {
        ServerInfo {
            protocol_version: ProtocolVersion::default(),
            capabilities: ServerCapabilities {
                tools: Some(ToolsCapability {
                    list_changed: Some(false),
                }),
                ..Default::default()
            },
            server_info: Implementation {
                name: "solo".into(),
                version: env!("CARGO_PKG_VERSION").into(),
            },
            instructions: Some(
                "Solo gives you persistent memory across conversations \
                 with this user — what they've told you before, the \
                 people and projects in their life, and where their \
                 stated beliefs have shifted, plus a library of \
                 documents the user has ingested (notes, runbooks, \
                 PDFs). Reach for these tools whenever the user \
                 references something from earlier (\"like I \
                 mentioned\", \"the project I'm working on\", \"my \
                 friend Alex\", \"the notes I uploaded last week\") \
                 or asks a question that hinges on personal context \
                 or document content you don't have in the current \
                 chat. \
                 \n\nTools to write or look up specific moments: \
                 memory_remember (save something worth keeping), \
                 memory_recall (search past conversations by topic), \
                 memory_inspect (show one saved item by id), \
                 memory_forget (delete one saved item). \
                 \n\nTools for the bigger picture (populated as the \
                 user uses Solo over time): memory_themes (recent \
                 topics they've been thinking about), \
                 memory_facts_about (what you know about a person, \
                 project, or place — \"what do you know about \
                 Alex?\"), memory_contradictions (places where the \
                 user has said two things that disagree — surface \
                 these before answering), memory_inspect_cluster \
                 (the raw conversations behind one summary). \
                 \n\nTools for the user's documents: \
                 memory_ingest_document (read a file from disk and \
                 add it to Solo's library), memory_search_docs \
                 (search across ingested documents by topic — use \
                 when the user asks about something they wrote down \
                 or saved as a file), memory_inspect_document (show \
                 one document's metadata plus a preview of its \
                 chunks), memory_list_documents (browse documents \
                 by recency), memory_forget_document (drop a \
                 document from the library)."
                    .into(),
            ),
        }
    }

    async fn list_tools(
        &self,
        _request: PaginatedRequestParam,
        _context: RequestContext<RoleServer>,
    ) -> std::result::Result<ListToolsResult, McpError> {
        Ok(ListToolsResult {
            tools: build_tools(),
            next_cursor: None,
        })
    }

    async fn call_tool(
        &self,
        request: CallToolRequestParam,
        _context: RequestContext<RoleServer>,
    ) -> std::result::Result<CallToolResult, McpError> {
        let CallToolRequestParam { name, arguments } = request;
        let args_value = serde_json::Value::Object(arguments.unwrap_or_default());
        self.dispatch_tool(&name, args_value).await
    }
}

impl SoloMcpServer {
    /// Direct tool-dispatch path used by both `call_tool` (the
    /// ServerHandler trait method, behind the rmcp protocol layer) and
    /// in-process tests that don't want to spin up a full transport pair.
    /// Bypasses `RequestContext` (which requires a `Peer` not constructible
    /// outside rmcp internals).
    pub async fn dispatch_tool(
        &self,
        name: &str,
        args_value: serde_json::Value,
    ) -> std::result::Result<CallToolResult, McpError> {
        match name {
            "memory_remember" => {
                let args: RememberArgs = parse_args(&args_value)?;
                self.handle_remember(args).await
            }
            "memory_recall" => {
                let args: RecallArgs = parse_args(&args_value)?;
                self.handle_recall(args).await
            }
            "memory_forget" => {
                let args: ForgetArgs = parse_args(&args_value)?;
                self.handle_forget(args).await
            }
            "memory_inspect" => {
                let args: InspectArgs = parse_args(&args_value)?;
                self.handle_inspect(args).await
            }
            "memory_themes" => {
                let args: ThemesArgs = parse_args(&args_value)?;
                self.handle_themes(args).await
            }
            "memory_facts_about" => {
                let args: FactsAboutArgs = parse_args(&args_value)?;
                self.handle_facts_about(args).await
            }
            "memory_contradictions" => {
                let args: ContradictionsArgs = parse_args(&args_value)?;
                self.handle_contradictions(args).await
            }
            "memory_inspect_cluster" => {
                let args: InspectClusterArgs = parse_args(&args_value)?;
                self.handle_inspect_cluster(args).await
            }
            "memory_ingest_document" => {
                let args: IngestDocumentArgs = parse_args(&args_value)?;
                self.handle_ingest_document(args).await
            }
            "memory_search_docs" => {
                let args: SearchDocsArgs = parse_args(&args_value)?;
                self.handle_search_docs(args).await
            }
            "memory_inspect_document" => {
                let args: InspectDocumentArgs = parse_args(&args_value)?;
                self.handle_inspect_document(args).await
            }
            "memory_list_documents" => {
                let args: ListDocumentsArgs = parse_args(&args_value)?;
                self.handle_list_documents(args).await
            }
            "memory_forget_document" => {
                let args: ForgetDocumentArgs = parse_args(&args_value)?;
                self.handle_forget_document(args).await
            }
            other => Err(McpError::invalid_params(
                format!("unknown tool `{other}`"),
                None,
            )),
        }
    }

    /// List the tools this server exposes. Mirrors `ServerHandler::list_tools`
    /// without requiring a RequestContext.
    pub fn dispatch_list_tools(&self) -> Vec<Tool> {
        build_tools()
    }
}

fn parse_args<T: serde::de::DeserializeOwned>(
    v: &serde_json::Value,
) -> std::result::Result<T, McpError> {
    serde_json::from_value(v.clone()).map_err(|e| {
        McpError::invalid_params(format!("invalid tool arguments: {e}"), None)
    })
}

fn solo_to_mcp(e: solo_core::Error) -> McpError {
    use solo_core::Error;
    match e {
        Error::NotFound(msg) => McpError::invalid_params(msg, None),
        Error::InvalidInput(msg) => McpError::invalid_params(msg, None),
        Error::Conflict(msg) => McpError::invalid_params(msg, None),
        other => McpError::internal_error(other.to_string(), None),
    }
}

// ---------------------------------------------------------------------------
// Tool definitions (JSON Schema)
// ---------------------------------------------------------------------------

fn build_tools() -> Vec<Tool> {
    vec![
        Tool::new(
            "memory_remember",
            "Save something the user has told you — a fact, a \
             preference, a name, a date, a context — so you can pick \
             it up next conversation. Use whenever the user mentions \
             something they'd reasonably expect you to recall later \
             (\"I just started at Quotient\", \"my partner is Maya\"). \
             Returns the saved item's id.",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "content": {
                        "type": "string",
                        "description": "The text to remember.",
                    },
                    "source_type": {
                        "type": "string",
                        "description": "Optional source-type tag (default: \"user_message\").",
                    },
                    "source_id": {
                        "type": "string",
                        "description": "Optional upstream id for traceability.",
                    },
                },
                "required": ["content"],
            })),
        ),
        Tool::new(
            "memory_recall",
            "Search past conversations with this user by topic or \
             phrase. Returns up to `limit` of the closest matches, \
             best match first. Use when the user references \
             something they said before (\"that book I told you \
             about\", \"the bug we were debugging last week\"). \
             Skips items the user has deleted.",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The query text.",
                    },
                    "limit": {
                        "type": "integer",
                        "description": "Maximum results (default 5).",
                        "minimum": 1,
                        "maximum": 100,
                    },
                },
                "required": ["query"],
            })),
        ),
        Tool::new(
            "memory_forget",
            "Delete one saved item by id. Use when the user asks you \
             to forget something specific (\"forget that I said \
             X\"). The item stops appearing in future recalls. \
             Reversible only via backups.",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "memory_id": {
                        "type": "string",
                        "description": "MemoryId to forget (UUID v7).",
                    },
                    "reason": {
                        "type": "string",
                        "description": "Optional free-form reason (logged, not yet persisted).",
                    },
                },
                "required": ["memory_id"],
            })),
        ),
        Tool::new(
            "memory_inspect",
            "Show the full record for one saved item — when it was \
             saved, where it came from, and the full text. Use after \
             memory_recall when you want the complete content of a \
             specific hit (recall results may be truncated).",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "memory_id": {
                        "type": "string",
                        "description": "MemoryId to inspect (UUID v7).",
                    },
                },
                "required": ["memory_id"],
            })),
        ),
        // Path 1 derived-layer tools (v0.4.0+) — query the Steward's
        // outputs. These four are populated by `solo consolidate` and
        // were previously unreadable except via direct SQL.
        Tool::new(
            "memory_themes",
            "Recent topics the user has been thinking about. Use to \
             orient yourself at the start of a conversation, or when \
             the user asks \"what have I been up to\" / \"what was I \
             working on last week\". Pass `window_days` to scope \
             (e.g. 7 for last week); omit for all-time.",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "window_days": {
                        "type": "integer",
                        "description": "Optional time window in days. Omit for unfiltered.",
                        "minimum": 1,
                    },
                    "limit": {
                        "type": "integer",
                        "description": "Maximum results (default 5).",
                        "minimum": 1,
                        "maximum": 100,
                    },
                },
            })),
        ),
        Tool::new(
            "memory_facts_about",
            "Look up what you remember about a person, project, or \
             topic — names, dates, preferences, relationships. Use \
             when the user asks \"what do you know about Alex?\", \
             \"when did I start at Quotient?\", \"who is Maya?\", or \
             whenever you need grounded facts about someone or \
             something before answering. Subject is required (the \
             person/place/thing you're asking about); narrow further \
             with `predicate` (\"works_at\", \"lives_in\") or a date \
             range. Set `include_as_object=true` to also surface \
             facts where the subject appears on the receiving side of \
             a relationship (e.g. \"Sam pushes back on PRs about \
             Maya\" surfaces under facts_about(subject=\"Maya\", \
             include_as_object=true)). (Backed by \
             subject-predicate-object triples distilled from past \
             conversations.) Clients should set a 30s timeout on this \
             call; if exceeded, retry once or fall back to \
             `memory_recall`.",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "subject": {
                        "type": "string",
                        "description": "Subject id to query (e.g. 'Sam').",
                    },
                    "predicate": {
                        "type": "string",
                        "description": "Optional predicate filter (e.g. 'works_at').",
                    },
                    "since_ms": {
                        "type": "integer",
                        "description": "Optional valid_from_ms lower bound (epoch ms).",
                    },
                    "until_ms": {
                        "type": "integer",
                        "description": "Optional valid_to_ms upper bound (epoch ms). NULL upper bounds (still-valid facts) pass through.",
                    },
                    "include_as_object": {
                        "type": "boolean",
                        "description": "If true, also match facts where `subject` appears as the object (e.g. 'Sam pushes back on PRs about Maya' surfaces under subject='Maya'). Default false.",
                        "default": false,
                    },
                    "limit": {
                        "type": "integer",
                        "description": "Maximum results (default 5).",
                        "minimum": 1,
                        "maximum": 100,
                    },
                },
                "required": ["subject"],
            })),
        ),
        Tool::new(
            "memory_contradictions",
            "Find places where the user's stated beliefs or facts \
             disagree across conversations — flag disagreements \
             before answering. Use whenever you're about to rely on \
             a remembered fact that could have changed (jobs, \
             relationships, preferences, opinions); a disagreement \
             here means the user has told you both X and not-X over \
             time and you should ask which is current instead of \
             guessing. Each result shows both conflicting statements \
             with the topic.",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "limit": {
                        "type": "integer",
                        "description": "Maximum results (default 5).",
                        "minimum": 1,
                        "maximum": 100,
                    },
                },
            })),
        ),
        Tool::new(
            "memory_inspect_cluster",
            "Show the raw conversations behind one summary. Returns \
             the one-line topic (the LLM-generated summary) and the \
             source conversations the topic was built from. Use \
             after memory_themes when the user asks \"show me the \
             raw context behind this\" or \"why does Solo think \
             that about cluster Y\". Source items are truncated to \
             200 chars unless `full_content` is set.",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "cluster_id": {
                        "type": "string",
                        "description": "Cluster id to inspect (from memory_themes hits).",
                    },
                    "full_content": {
                        "type": "boolean",
                        "description": "If true, episode content is returned verbatim. Default false (truncate to 200 chars + ellipsis).",
                    },
                },
                "required": ["cluster_id"],
            })),
        ),
        // Document tools (v0.7.0+). RAG over user-supplied files —
        // markdown notes, PDFs, runbooks, code, etc. Same vector space
        // as episodes; same embedder; same HNSW index.
        Tool::new(
            "memory_ingest_document",
            "Read a file from disk and add it to the user's document \
             library so it becomes searchable alongside past \
             conversations. Use when the user asks you to remember a \
             whole file (\"add my notes/runbook.md\", \"ingest this \
             PDF\"). The file is split into ~500-token chunks and \
             each chunk is embedded; chunks then surface through \
             memory_search_docs. Returns the new document id, chunk \
             count, and a `deduped` flag (true if the same content \
             was already ingested under another id).",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "Server-side absolute path to the file to ingest. The file must be readable by the Solo process.",
                    },
                },
                "required": ["path"],
            })),
        ),
        Tool::new(
            "memory_search_docs",
            "Search across the user's ingested documents by topic or \
             phrase. Returns up to `limit` matching chunks, best \
             match first, each with the parent document's title + \
             source path so you can cite where the answer came from. \
             Use when the user asks a question that hinges on \
             material they've added as a file (\"what does my \
             runbook say about backups?\", \"find the section in the \
             notes about the new policy\"). Forgotten documents are \
             skipped.",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The query text.",
                    },
                    "limit": {
                        "type": "integer",
                        "description": "Maximum results (default 5).",
                        "minimum": 1,
                        "maximum": 100,
                    },
                },
                "required": ["query"],
            })),
        ),
        Tool::new(
            "memory_inspect_document",
            "Show one document's metadata plus a preview of every \
             chunk it was split into. Use after memory_search_docs \
             when the user wants the bigger picture for one hit \
             (\"show me the whole document this came from\"), or \
             after memory_list_documents to drill into one entry. \
             Each chunk preview is truncated to 200 chars.",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "Document id to inspect (UUID v7).",
                    },
                },
                "required": ["doc_id"],
            })),
        ),
        Tool::new(
            "memory_list_documents",
            "List the user's ingested documents, newest first. Use \
             when the user asks \"what documents have I added?\" or \
             \"show me my files\". Returns a paginated index — pass \
             `offset` to page further back. Forgotten documents are \
             hidden by default; set `include_forgotten=true` to see \
             them too.",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "limit": {
                        "type": "integer",
                        "description": "Maximum results per page (default 20).",
                        "minimum": 1,
                        "maximum": 100,
                    },
                    "offset": {
                        "type": "integer",
                        "description": "Number of rows to skip (for paging). Default 0.",
                        "minimum": 0,
                    },
                    "include_forgotten": {
                        "type": "boolean",
                        "description": "If true, also include documents the user has forgotten. Default false.",
                    },
                },
            })),
        ),
        Tool::new(
            "memory_forget_document",
            "Drop one document from the user's library by id. Use \
             when the user asks you to forget a specific file \
             (\"forget my old runbook\"). The document's chunks stop \
             appearing in memory_search_docs and the vectors are \
             tombstoned in the index. The chunk rows themselves are \
             kept for forensic value (a future restore command can \
             undo this).",
            json_schema_object(serde_json::json!({
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "Document id to forget (UUID v7).",
                    },
                },
                "required": ["doc_id"],
            })),
        ),
    ]
}

fn json_schema_object(value: serde_json::Value) -> serde_json::Map<String, serde_json::Value> {
    match value {
        serde_json::Value::Object(map) => map,
        _ => panic!("json_schema_object: input must be an object"),
    }
}

/// Names of every tool this server exposes, in registration order.
///
/// Exposed for cross-crate consumers (notably `solo doctor
/// --check-mcp-compat`) that want the name list without paying the
/// cost of building full `rmcp::Tool` records (which allocate JSON
/// schemas). The registration order matches `build_tools()` so any
/// drift between the two would be caught by the cross-provider regex
/// test which iterates `build_tools()`.
pub fn tool_names() -> Vec<&'static str> {
    vec![
        "memory_remember",
        "memory_recall",
        "memory_forget",
        "memory_inspect",
        "memory_themes",
        "memory_facts_about",
        "memory_contradictions",
        "memory_inspect_cluster",
        // Document tools added in v0.7.0:
        "memory_ingest_document",
        "memory_search_docs",
        "memory_inspect_document",
        "memory_list_documents",
        "memory_forget_document",
    ]
}

// ---------------------------------------------------------------------------
// Tool handlers
// ---------------------------------------------------------------------------

impl SoloMcpServer {
    async fn handle_remember(
        &self,
        args: RememberArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        let content = args.content.trim_end().to_string();
        if content.is_empty() {
            return Err(McpError::invalid_params(
                "memory_remember: content must not be empty".to_string(),
                None,
            ));
        }
        let embedding: solo_core::Embedding = self
            .inner
            .tenant
            .embedder()
            .embed(&content)
            .await
            .map_err(solo_to_mcp)?;
        let episode = Episode {
            memory_id: MemoryId::new(),
            ts_ms: chrono::Utc::now().timestamp_millis(),
            source_type: args.source_type.unwrap_or_else(|| "user_message".into()),
            source_id: args.source_id,
            content,
            encoding_context: EncodingContext::default(),
            provenance: None,
            confidence: Confidence::new(0.9).unwrap(),
            strength: 0.5,
            salience: 0.5,
            tier: Tier::Hot,
        };
        let mid = self
            .inner
            .tenant
            .write()
            .remember_as(self.inner.audit_principal.clone(), episode, embedding)
            .await
            .map_err(solo_to_mcp)?;
        Ok(CallToolResult::success(vec![Content::text(format!(
            "remembered {mid}"
        ))]))
    }

    async fn handle_recall(
        &self,
        args: RecallArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        // Pipeline lives in solo-query; the transport just formats the
        // result. solo_query::run_recall validates empty queries
        // (returns InvalidInput → invalid_params via solo_to_mcp).
        let result = solo_query::run_recall(
            self.inner.tenant.as_ref(),
            self.inner.audit_principal.clone(),
            &args.query,
            args.limit,
        )
        .await
        .map_err(solo_to_mcp)?;

        if result.hits.is_empty() {
            return Ok(CallToolResult::success(vec![Content::text(format!(
                "no matches (index has {} vectors)",
                result.index_len
            ))]));
        }
        let body = serde_json::to_string_pretty(&result.hits).unwrap_or_else(|_| String::new());
        Ok(CallToolResult::success(vec![Content::text(body)]))
    }

    async fn handle_forget(
        &self,
        args: ForgetArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        let mid = MemoryId::from_str(&args.memory_id).map_err(|e| {
            McpError::invalid_params(format!("invalid memory_id: {e}"), None)
        })?;
        self.inner
            .tenant
            .write()
            .forget_as(self.inner.audit_principal.clone(), mid, args.reason)
            .await
            .map_err(solo_to_mcp)?;
        Ok(CallToolResult::success(vec![Content::text(format!(
            "forgotten {mid}"
        ))]))
    }

    async fn handle_inspect(
        &self,
        args: InspectArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        let mid = MemoryId::from_str(&args.memory_id).map_err(|e| {
            McpError::invalid_params(format!("invalid memory_id: {e}"), None)
        })?;
        // Pipeline lives in solo-query::inspect; transports just format.
        let row = solo_query::inspect_one(
            self.inner.tenant.read(),
            self.inner.tenant.audit(),
            self.inner.audit_principal.clone(),
            mid,
        )
        .await
        .map_err(solo_to_mcp)?;
        let body = serde_json::to_string_pretty(&row).unwrap_or_else(|_| String::new());
        Ok(CallToolResult::success(vec![Content::text(body)]))
    }

    // Path 1 derived-layer handlers (v0.4.0+). Each one delegates to a
    // single solo-query::derived pipeline and serialises the result Vec
    // to pretty JSON for the MCP wire. Empty result → JSON empty array
    // `[]` (not a special-case "no matches" string) so MCP clients can
    // parse uniformly.

    async fn handle_themes(
        &self,
        args: ThemesArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        let hits = solo_query::themes(
            self.inner.tenant.read(),
            self.inner.tenant.audit(),
            self.inner.audit_principal.clone(),
            args.window_days,
            args.limit,
        )
        .await
        .map_err(solo_to_mcp)?;
        let body = serde_json::to_string_pretty(&hits).unwrap_or_else(|_| String::new());
        Ok(CallToolResult::success(vec![Content::text(body)]))
    }

    async fn handle_facts_about(
        &self,
        args: FactsAboutArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        if args.subject.trim().is_empty() {
            return Err(McpError::invalid_params(
                "memory_facts_about: subject must not be empty".to_string(),
                None,
            ));
        }
        let hits = solo_query::facts_about(
            self.inner.tenant.read(),
            self.inner.tenant.audit(),
            self.inner.audit_principal.clone(),
            &args.subject,
            &self.inner.user_aliases,
            args.include_as_object,
            args.predicate.as_deref(),
            args.since_ms,
            args.until_ms,
            args.limit,
        )
        .await
        .map_err(solo_to_mcp)?;
        let body = serde_json::to_string_pretty(&hits).unwrap_or_else(|_| String::new());
        Ok(CallToolResult::success(vec![Content::text(body)]))
    }

    async fn handle_contradictions(
        &self,
        args: ContradictionsArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        let hits = solo_query::contradictions(
            self.inner.tenant.read(),
            self.inner.tenant.audit(),
            self.inner.audit_principal.clone(),
            args.limit,
        )
        .await
        .map_err(solo_to_mcp)?;
        let body = serde_json::to_string_pretty(&hits).unwrap_or_else(|_| String::new());
        Ok(CallToolResult::success(vec![Content::text(body)]))
    }

    async fn handle_inspect_cluster(
        &self,
        args: InspectClusterArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        if args.cluster_id.trim().is_empty() {
            return Err(McpError::invalid_params(
                "memory_inspect_cluster: cluster_id must not be empty".to_string(),
                None,
            ));
        }
        // `solo_to_mcp` maps `Error::NotFound` → `invalid_params` for
        // MCP (the protocol does not have a separate "not found" error
        // shape; clients see the message verbatim, which includes the
        // cluster_id).
        let record = solo_query::inspect_cluster(
            self.inner.tenant.read(),
            self.inner.tenant.audit(),
            self.inner.audit_principal.clone(),
            &args.cluster_id,
            args.full_content,
        )
        .await
        .map_err(solo_to_mcp)?;
        let body = serde_json::to_string_pretty(&record).unwrap_or_else(|_| String::new());
        Ok(CallToolResult::success(vec![Content::text(body)]))
    }

    // Document handlers (v0.7.0+). Each wraps the corresponding writer
    // / query API; the MCP wire shape is plain JSON serialisation of
    // the returned report / records.

    async fn handle_ingest_document(
        &self,
        args: IngestDocumentArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        if args.path.trim().is_empty() {
            return Err(McpError::invalid_params(
                "memory_ingest_document: path must not be empty".to_string(),
                None,
            ));
        }
        let path = std::path::PathBuf::from(args.path);
        // Defaults match what the daemon uses today (target 500 tokens,
        // 50-token overlap). Future: thread a per-call override through
        // the args struct if a use case appears.
        let chunk_config = solo_storage::document::ChunkConfig::default();
        let report = self
            .inner
            .tenant
            .write()
            .ingest_document_as(self.inner.audit_principal.clone(), path, chunk_config)
            .await
            .map_err(solo_to_mcp)?;
        let body = serde_json::to_string_pretty(&report).unwrap_or_else(|_| String::new());
        Ok(CallToolResult::success(vec![Content::text(body)]))
    }

    async fn handle_search_docs(
        &self,
        args: SearchDocsArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        // `solo_query::run_doc_search` validates empty queries (returns
        // InvalidInput → invalid_params via solo_to_mcp) and clamps
        // limit upstream of the embedder call.
        let hits = solo_query::run_doc_search(
            self.inner.tenant.as_ref(),
            self.inner.audit_principal.clone(),
            &args.query,
            args.limit,
        )
        .await
        .map_err(solo_to_mcp)?;
        let body = serde_json::to_string_pretty(&hits).unwrap_or_else(|_| String::new());
        Ok(CallToolResult::success(vec![Content::text(body)]))
    }

    async fn handle_inspect_document(
        &self,
        args: InspectDocumentArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        let doc_id = DocumentId::from_str(&args.doc_id).map_err(|e| {
            McpError::invalid_params(format!("invalid doc_id: {e}"), None)
        })?;
        let result_opt = solo_query::inspect_document(
            self.inner.tenant.read(),
            self.inner.tenant.audit(),
            self.inner.audit_principal.clone(),
            &doc_id,
        )
        .await
        .map_err(solo_to_mcp)?;
        match result_opt {
            Some(record) => {
                let body =
                    serde_json::to_string_pretty(&record).unwrap_or_else(|_| String::new());
                Ok(CallToolResult::success(vec![Content::text(body)]))
            }
            None => Err(McpError::invalid_params(
                format!("document {doc_id} not found"),
                None,
            )),
        }
    }

    async fn handle_list_documents(
        &self,
        args: ListDocumentsArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        let rows = solo_query::list_documents(
            self.inner.tenant.read(),
            self.inner.tenant.audit(),
            self.inner.audit_principal.clone(),
            args.limit,
            args.offset,
            args.include_forgotten,
        )
        .await
        .map_err(solo_to_mcp)?;
        let body = serde_json::to_string_pretty(&rows).unwrap_or_else(|_| String::new());
        Ok(CallToolResult::success(vec![Content::text(body)]))
    }

    async fn handle_forget_document(
        &self,
        args: ForgetDocumentArgs,
    ) -> std::result::Result<CallToolResult, McpError> {
        let doc_id = DocumentId::from_str(&args.doc_id).map_err(|e| {
            McpError::invalid_params(format!("invalid doc_id: {e}"), None)
        })?;
        let report = self
            .inner
            .tenant
            .write()
            .forget_document_as(self.inner.audit_principal.clone(), doc_id)
            .await
            .map_err(solo_to_mcp)?;
        let body = serde_json::to_string_pretty(&report).unwrap_or_else(|_| String::new());
        Ok(CallToolResult::success(vec![Content::text(body)]))
    }
}

#[cfg(test)]
mod dispatch_tests {
    //! In-process integration tests for the MCP tool surface. We invoke
    //! `SoloMcpServer::dispatch_tool` directly (bypasses the rmcp
    //! protocol framing + `RequestContext`, which requires a `Peer`
    //! that's not constructible outside rmcp internals). The server is
    //! constructed against a real WriterActor + ReaderPool +
    //! StubEmbedder + StubVectorIndex from `solo_storage::test_support`.
    //!
    //! Tests live inline in this module rather than `tests/` because an
    //! external integration-test exe in `target/debug/deps/mcp_dispatch-*`
    //! tripped Windows UAC ERROR_ELEVATION_REQUIRED on the dev machine.
    //! The lib test binary doesn't have that issue.
    use super::*;
    use serde_json::json;
    use solo_core::VectorIndex;
    use solo_storage::test_support::StubVectorIndex;
    use solo_storage::{
        EmbedderConfig, IdentityConfig, KeyMaterial, ReaderPool, SoloConfig,
        StubEmbedder, TenantHandle, TenantRegistry, WriterActor, WriterSpawn,
    };
    use std::sync::Arc as StdArc;

    fn fake_config(dim: u32) -> SoloConfig {
        SoloConfig {
            schema_version: 1,
            salt_hex: "00000000000000000000000000000000".to_string(),
            embedder: EmbedderConfig {
                name: "stub".to_string(),
                version: "v1".to_string(),
                dim,
                dtype: "f32".to_string(),
            },
            identity: IdentityConfig::default(),
            documents: solo_storage::DocumentConfig::default(),
            auth: None,
            audit: solo_storage::AuditSettings::default(),
            redaction: solo_storage::RedactionConfig::default(),
        }
    }

    struct Harness {
        server: SoloMcpServer,
        _tmp: tempfile::TempDir,
        write_handle_extra: Option<solo_storage::WriteHandle>,
        join: Option<std::thread::JoinHandle<()>>,
    }

    impl Harness {
        fn new(runtime: &tokio::runtime::Runtime) -> Self {
            let tmp = tempfile::TempDir::new().unwrap();
            let dim = 16usize;
            let hnsw: StdArc<dyn VectorIndex + Send + Sync> = StdArc::new(StubVectorIndex::new(dim));
            let embedder: StdArc<dyn solo_core::Embedder> = StdArc::new(StubEmbedder::new("stub", "v1", dim));

            let conn = solo_storage::test_support::open_test_db_at(&tmp.path().join("test.db"));
            let WriterSpawn { handle, join } = WriterActor::spawn(conn, hnsw.clone());

            // ReaderPool's deadpool::Pool needs a live tokio runtime for
            // both build + drop; build inside block_on.
            let path = tmp.path().join("test.db");
            let pool: ReaderPool =
                runtime.block_on(async { ReaderPool::new(&path, None, hnsw.clone()).unwrap() });

            let tenant_id = solo_core::TenantId::default_tenant();
            let tenant_handle = StdArc::new(
                TenantHandle::from_parts_for_tests(
                    tenant_id.clone(),
                    fake_config(dim as u32),
                    path.clone(),
                    tmp.path().to_path_buf(),
                    0, // embedder_id; tests using full embedder_id path build their own
                    hnsw,
                    embedder.clone(),
                    handle.clone(),
                    std::thread::spawn(|| {}),
                    pool,
                ),
            );
            let key = KeyMaterial::from_bytes_for_tests([0u8; 32]);
            let registry = StdArc::new(TenantRegistry::for_tests_with_single_tenant(
                tmp.path().to_path_buf(),
                key,
                embedder,
                tenant_handle.clone(),
            ));
            let server = SoloMcpServer::new_for_tenant(registry, tenant_handle, Vec::new());
            Harness {
                server,
                _tmp: tmp,
                write_handle_extra: Some(handle),
                join: Some(join),
            }
        }

        fn shutdown(mut self, runtime: &tokio::runtime::Runtime) {
            // The whole shutdown runs inside block_on so deadpool-sqlite's
            // drop (which schedules cleanup on the active runtime) sees a
            // live reactor. Without this, dropping the SoloMcpServer
            // (which holds the ReaderPool through its Arc<Inner>) panics
            // with "no reactor running".
            let join = self.join.take();
            let extra = self.write_handle_extra.take();
            runtime.block_on(async move {
                drop(extra);
                drop(self.server);
                drop(self._tmp);
                if let Some(join) = join {
                    let (tx, rx) = std::sync::mpsc::channel();
                    std::thread::spawn(move || {
                        let _ = tx.send(join.join());
                    });
                    tokio::task::spawn_blocking(move || {
                        rx.recv_timeout(std::time::Duration::from_secs(5))
                    })
                    .await
                    .expect("blocking task")
                    .expect("writer thread did not exit within 5s")
                    .expect("writer thread panicked");
                }
            });
        }
    }

    fn rt() -> tokio::runtime::Runtime {
        tokio::runtime::Builder::new_multi_thread()
            .worker_threads(2)
            .enable_all()
            .build()
            .unwrap()
    }

    /// Pull the first Content::text body out of a CallToolResult. Use
    /// serde_json roundtrip as a robust extractor — `Content`'s public
    /// API doesn't directly expose the inner text without going through
    /// pattern-matching on RawContent.
    fn first_text(r: &rmcp::model::CallToolResult) -> String {
        let first = r.content.first().expect("at least one content item");
        let v = serde_json::to_value(first).expect("content serialises");
        v.get("text")
            .and_then(|t| t.as_str())
            .map(|s| s.to_string())
            .unwrap_or_else(|| format!("{v}"))
    }

    #[test]
    fn tools_list_returns_thirteen_canonical_tools() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        let tools = h.server.dispatch_list_tools();
        let names: Vec<&str> = tools.iter().map(|t| t.name.as_ref()).collect();
        assert_eq!(
            names,
            vec![
                "memory_remember",
                "memory_recall",
                "memory_forget",
                "memory_inspect",
                // Derived-layer tools added in v0.4.0:
                "memory_themes",
                "memory_facts_about",
                "memory_contradictions",
                // Added in v0.5.0 (Priority 3):
                "memory_inspect_cluster",
                // Document tools added in v0.7.0:
                "memory_ingest_document",
                "memory_search_docs",
                "memory_inspect_document",
                "memory_list_documents",
                "memory_forget_document",
            ]
        );
        for t in &tools {
            assert!(!t.description.is_empty(), "{} description empty", t.name);
            let _schema = t.schema_as_json_value();
            // `required` is intentionally absent on memory_themes +
            // memory_contradictions + memory_list_documents (all args
            // optional with defaults). memory_facts_about has required
            // = ["subject"], etc. We don't assert per-tool 'required'
            // shape here; the schema's `properties` field is the more
            // important signal and is always present.
        }
        h.shutdown(&runtime);
    }

    #[test]
    fn themes_returns_json_array_on_empty_db() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let r = h
                .server
                .dispatch_tool("memory_themes", json!({}))
                .await
                .expect("themes succeeds");
            let text = first_text(&r);
            // Empty derived layer → empty array JSON. Parses cleanly.
            let v: serde_json::Value =
                serde_json::from_str(&text).expect("parses as json");
            assert!(v.is_array(), "expected array, got: {text}");
            assert_eq!(v.as_array().unwrap().len(), 0);
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn themes_passes_through_window_and_limit_args() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            // Should not crash with optional + integer args present.
            let r = h
                .server
                .dispatch_tool(
                    "memory_themes",
                    json!({ "window_days": 7, "limit": 20 }),
                )
                .await
                .expect("themes with args succeeds");
            let text = first_text(&r);
            let v: serde_json::Value =
                serde_json::from_str(&text).expect("parses as json");
            assert!(v.is_array());
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn facts_about_rejects_empty_subject() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool(
                    "memory_facts_about",
                    json!({ "subject": "   " }),
                )
                .await
                .expect_err("empty subject must error");
            // McpError doesn't expose a clean kind/message accessor; just
            // verify the error fires (validation path reached).
            let s = format!("{err:?}");
            assert!(
                s.to_lowercase().contains("subject")
                    || s.to_lowercase().contains("invalid"),
                "got: {s}"
            );
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn facts_about_returns_array_for_unknown_subject() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let r = h
                .server
                .dispatch_tool(
                    "memory_facts_about",
                    json!({ "subject": "NobodyKnowsThisSubject" }),
                )
                .await
                .expect("facts_about with unknown subject succeeds");
            let text = first_text(&r);
            let v: serde_json::Value =
                serde_json::from_str(&text).expect("parses as json");
            assert_eq!(v.as_array().unwrap().len(), 0);
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn facts_about_accepts_include_as_object_arg() {
        // Asserts the v0.5.1 P8 arg is parsed (serde default lets it
        // be omitted) and forwarded to the query lib without choking
        // the dispatcher. We don't seed triples — what we need to
        // verify is that the optional bool flows through. Both with
        // and without the arg, dispatch succeeds and returns an
        // empty array. (Functional coverage of the object-position
        // widening lives in the query-crate tests.)
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            // With include_as_object=true.
            let r = h
                .server
                .dispatch_tool(
                    "memory_facts_about",
                    json!({ "subject": "Maya", "include_as_object": true }),
                )
                .await
                .expect("dispatch with include_as_object=true succeeds");
            let v: serde_json::Value = serde_json::from_str(&first_text(&r))
                .expect("parses as json");
            assert_eq!(v.as_array().unwrap().len(), 0);

            // Omitted entirely — must default to false (no error).
            let r = h
                .server
                .dispatch_tool(
                    "memory_facts_about",
                    json!({ "subject": "Maya" }),
                )
                .await
                .expect("dispatch without include_as_object succeeds (default false)");
            let v: serde_json::Value = serde_json::from_str(&first_text(&r))
                .expect("parses as json");
            assert_eq!(v.as_array().unwrap().len(), 0);
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn contradictions_returns_json_array_on_empty_db() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let r = h
                .server
                .dispatch_tool("memory_contradictions", json!({}))
                .await
                .expect("contradictions succeeds");
            let text = first_text(&r);
            let v: serde_json::Value =
                serde_json::from_str(&text).expect("parses as json");
            assert!(v.is_array());
            assert_eq!(v.as_array().unwrap().len(), 0);
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn remember_then_recall_round_trip() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        // Use &h.server directly (no clone) so the only outstanding
        // reference at shutdown time is the harness's own. The clone
        // path triggered a 5-second writer-thread timeout because the
        // local clone held an Arc<Inner> with its own WriteHandle past
        // h.shutdown().
        runtime.block_on(async {
            let r = h
                .server
                .dispatch_tool("memory_remember", json!({ "content": "the cat sat on the mat" }))
                .await
                .expect("remember succeeds");
            let text = first_text(&r);
            assert!(text.starts_with("remembered "), "got: {text}");

            let r = h
                .server
                .dispatch_tool(
                    "memory_recall",
                    json!({ "query": "the cat sat on the mat", "limit": 5 }),
                )
                .await
                .expect("recall succeeds");
            let text = first_text(&r);
            assert!(text.contains("the cat sat on the mat"), "got: {text}");
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn forget_excludes_row_from_subsequent_recall() {
        let runtime = rt();
        let h = Harness::new(&runtime);

        runtime.block_on(async {
            let r = h
                .server
                .dispatch_tool("memory_remember", json!({ "content": "to be forgotten" }))
                .await
                .unwrap();
            let text = first_text(&r);
            let mid = text.strip_prefix("remembered ").unwrap().to_string();

            h.server
                .dispatch_tool(
                    "memory_forget",
                    json!({ "memory_id": mid, "reason": "test" }),
                )
                .await
                .expect("forget succeeds");

            let r = h
                .server
                .dispatch_tool(
                    "memory_recall",
                    json!({ "query": "to be forgotten", "limit": 5 }),
                )
                .await
                .unwrap();
            let text = first_text(&r);
            assert!(
                !text.contains(r#""content": "to be forgotten""#),
                "forgotten row should be excluded; got: {text}"
            );
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn empty_remember_returns_invalid_params() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool("memory_remember", json!({ "content": "" }))
                .await
                .unwrap_err();
            assert!(format!("{err:?}").contains("must not be empty"));
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn empty_recall_query_returns_invalid_params() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool("memory_recall", json!({ "query": "   " }))
                .await
                .unwrap_err();
            assert!(format!("{err:?}").contains("must not be empty"));
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn inspect_with_invalid_id_returns_invalid_params() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool("memory_inspect", json!({ "memory_id": "not-a-uuid" }))
                .await
                .unwrap_err();
            assert!(format!("{err:?}").contains("invalid memory_id"));
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn forget_unknown_id_returns_invalid_params() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            // Valid UUID format but not in episodes — handle_forget
            // surfaces NotFound, mapped to invalid_params per
            // solo_to_mcp.
            let err = h
                .server
                .dispatch_tool(
                    "memory_forget",
                    json!({ "memory_id": "00000000-0000-7000-8000-000000000000" }),
                )
                .await
                .unwrap_err();
            assert!(format!("{err:?}").contains("not found"));
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn unknown_tool_name_returns_invalid_params() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool("memory.summon", json!({}))
                .await
                .unwrap_err();
            assert!(format!("{err:?}").contains("unknown tool"));
        });
        h.shutdown(&runtime);
    }

    /// Regression guard for v0.4.1's MCP tool name fix, generalised
    /// in v0.5.0 Priority 4 to cover **all three** major LLM
    /// providers, not just Anthropic.
    ///
    /// Each provider enforces its own tool-name regex on the
    /// function-calling wire. A tool name has to satisfy ALL of them
    /// to be portable across clients:
    ///
    ///   - **Anthropic**: `^[a-zA-Z0-9_-]{1,64}$` (what shipped in
    ///     v0.4.1; failing this rejects the entire toolset on Claude
    ///     Desktop / Cursor / Claude Code with
    ///     `FrontendRemoteMcpToolDefinition.name: String should
    ///     match pattern ...`).
    ///   - **OpenAI** function-calling: `^[a-zA-Z_][a-zA-Z0-9_-]*$`
    ///     with length ≤ 64 (must start with letter or underscore).
    ///   - **Gemini** function-calling: documented as a-z, A-Z, 0-9,
    ///     underscores and dashes; some sources also allow dots. We
    ///     use the conservative intersection — must start with
    ///     letter or underscore, alphanumeric + underscore only (no
    ///     hyphen, no dot), length ≤ 63. This is the strictest of
    ///     the three patterns, so any tool that passes it also
    ///     passes the other two. Sources differ on whether Gemini
    ///     accepts dots or hyphens; the strictest reading guards us
    ///     against the future where one provider tightens the regex
    ///     (which is the failure mode v0.4.1 hit on Anthropic). See
    ///     <https://github.com/google-gemini/deprecated-generative-ai-python/blob/main/docs/api/google/generativeai/protos/FunctionDeclaration.md>
    ///     and <https://ai.google.dev/gemini-api/docs/function-calling>.
    ///
    /// Lesson banked v0.3 #8: rmcp framing tests pass dot-named
    /// tools fine because rmcp's own client-side validation is
    /// permissive. Only the downstream provider API enforces the
    /// regex. This test gates the names at `cargo test` time so any
    /// future tool-name change has to pass all three provider
    /// regexes before reaching real clients.
    #[test]
    fn tool_names_match_cross_provider_regex() {
        /// Anthropic API name regex: `^[a-zA-Z0-9_-]{1,64}$`.
        fn passes_anthropic(name: &str) -> bool {
            let len = name.len();
            if !(1..=64).contains(&len) {
                return false;
            }
            name.chars()
                .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
        }

        /// OpenAI function-calling name regex:
        /// `^[a-zA-Z_][a-zA-Z0-9_-]*$`, length ≤ 64.
        fn passes_openai(name: &str) -> bool {
            let len = name.len();
            if !(1..=64).contains(&len) {
                return false;
            }
            let mut chars = name.chars();
            let first = match chars.next() {
                Some(c) => c,
                None => return false,
            };
            if !(first.is_ascii_alphabetic() || first == '_') {
                return false;
            }
            chars.all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
        }

        /// Gemini function-calling name regex (conservative
        /// reading): `^[a-zA-Z_][a-zA-Z0-9_]*$`, length ≤ 63. No
        /// hyphen, no dot — strictest of the three so any name that
        /// passes this passes the other two.
        fn passes_gemini(name: &str) -> bool {
            let len = name.len();
            if !(1..=63).contains(&len) {
                return false;
            }
            let mut chars = name.chars();
            let first = match chars.next() {
                Some(c) => c,
                None => return false,
            };
            if !(first.is_ascii_alphabetic() || first == '_') {
                return false;
            }
            chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
        }

        let tools = build_tools();
        assert_eq!(
            tools.len(),
            13,
            "expected 13 tools in v0.7.0 (8 v0.5.x + 5 document tools)"
        );
        // Sanity-check that tool_names() agrees with build_tools().
        let tool_name_strings: Vec<String> =
            tools.iter().map(|t| t.name.to_string()).collect();
        let public_names: Vec<String> =
            super::tool_names().iter().map(|s| s.to_string()).collect();
        assert_eq!(
            tool_name_strings, public_names,
            "tool_names() drifted from build_tools() — keep them in sync"
        );

        for t in tools {
            assert!(
                passes_anthropic(&t.name),
                "tool name {:?} fails Anthropic regex \
                 ^[a-zA-Z0-9_-]{{1,64}}$ — see v0.3 lesson #8",
                t.name
            );
            assert!(
                passes_openai(&t.name),
                "tool name {:?} fails OpenAI function-calling regex \
                 ^[a-zA-Z_][a-zA-Z0-9_-]*$ (len ≤ 64)",
                t.name
            );
            assert!(
                passes_gemini(&t.name),
                "tool name {:?} fails Gemini function-calling regex \
                 ^[a-zA-Z_][a-zA-Z0-9_]*$ (len ≤ 63, strict)",
                t.name
            );
        }
    }

    /// Regression guard for the v0.5.0 Priority 4 jargon pass.
    ///
    /// Tool descriptions and `get_info().instructions` are the first
    /// (and often only) thing a calling LLM reads when its
    /// tool-search mechanism decides whether Solo's tools are
    /// relevant. Earlier descriptions leaned on Solo-internal
    /// vocabulary (`SPO`, `Steward`, `LEFT JOIN`, `candidate pair`,
    /// `tagged_with`) which doesn't pattern-match natural-language
    /// agent queries like "what do you know about Alex?" — that's
    /// the load-bearing v0.5.0 finding from the 2026-05-14
    /// thesis-test in Claude Desktop.
    ///
    /// This test pins the de-jargoning by forbidding the old
    /// vocabulary from appearing in any user-facing text. Future
    /// contributors who reach for jargon trip the test and have to
    /// pick plain-English phrasing instead.
    #[test]
    fn tool_descriptions_avoid_internal_jargon() {
        // Case-insensitive substring match. Drawn from the
        // pre-Priority-4 descriptions; expand only if a new term
        // creeps in.
        const FORBIDDEN: &[&str] = &[
            "SPO",
            "Steward",
            "Steward-flagged",
            "LEFT JOIN",
            "candidate pair",
            "candidate_pair",
            "tagged_with",
        ];

        fn contains_case_insensitive(haystack: &str, needle: &str) -> bool {
            haystack.to_lowercase().contains(&needle.to_lowercase())
        }

        // 1. Each tool description.
        for t in build_tools() {
            for term in FORBIDDEN {
                assert!(
                    !contains_case_insensitive(&t.description, term),
                    "tool {:?} description contains forbidden jargon \
                     {:?} — rewrite in plain English (see v0.5.0 \
                     Priority 4)",
                    t.name,
                    term,
                );
            }
        }

        // 2. The server-level instructions (what tool-search sees
        // first).
        let server_info = harness_server_info();
        let instructions = server_info
            .instructions
            .as_deref()
            .expect("get_info() must set instructions");
        for term in FORBIDDEN {
            assert!(
                !contains_case_insensitive(instructions, term),
                "get_info().instructions contains forbidden jargon \
                 {:?} — rewrite in plain English",
                term,
            );
        }
    }

    /// Build a `ServerInfo` for the jargon test without spinning up
    /// the full harness (which needs tokio + tempdir). The
    /// `ServerHandler::get_info()` method doesn't take `&self` state
    /// in any meaningful way for our impl — it returns a static
    /// `ServerInfo` literal — so we construct a minimal-input server
    /// just to call it.
    fn harness_server_info() -> rmcp::model::ServerInfo {
        let runtime = rt();
        let h = Harness::new(&runtime);
        let info = ServerHandler::get_info(&h.server);
        h.shutdown(&runtime);
        info
    }

    // ---- memory_inspect_cluster (v0.5.0 Priority 3) ----

    #[test]
    fn inspect_cluster_unknown_id_returns_invalid_params() {
        // NotFound from solo_query::inspect_cluster is mapped through
        // `solo_to_mcp` to `invalid_params` (MCP has no separate
        // not-found error shape). Error message should name the id.
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool(
                    "memory_inspect_cluster",
                    json!({ "cluster_id": "no-such-cluster" }),
                )
                .await
                .expect_err("unknown cluster must error");
            let s = format!("{err:?}");
            assert!(
                s.contains("no-such-cluster") || s.to_lowercase().contains("not found"),
                "expected error to mention the missing cluster id; got: {s}"
            );
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn inspect_cluster_rejects_empty_id() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool(
                    "memory_inspect_cluster",
                    json!({ "cluster_id": "   " }),
                )
                .await
                .expect_err("blank cluster_id must error");
            let s = format!("{err:?}");
            assert!(
                s.to_lowercase().contains("cluster_id")
                    || s.to_lowercase().contains("must not be empty"),
                "got: {s}"
            );
        });
        h.shutdown(&runtime);
    }

    // ---- Document tools (v0.7.0 P5) ----
    //
    // The five document handlers each have two arg-shape tests:
    //   - arg-struct parses from JSON (serde round-trip; defaults work).
    //   - dispatch arm routes to the handler (we observe behaviour via
    //     a known empty-DB response — bad routing surfaces as
    //     "unknown tool" or wrong shape).
    //
    // Functional coverage (ingest → search → inspect → forget) lives in
    // `crates/solo-cli/tests/mcp_smoke.rs` where a real subprocess + real
    // writer-with-embedder is wired up. The in-process Harness here uses
    // `WriterActor::spawn` which doesn't carry an embedder, so ingest /
    // search themselves return an error — but the dispatch + arg-parse
    // paths exercise correctly.

    #[test]
    fn ingest_document_args_parse_with_required_path() {
        let v: IngestDocumentArgs =
            serde_json::from_value(json!({ "path": "/tmp/notes.md" })).expect("parses");
        assert_eq!(v.path, "/tmp/notes.md");
        // path is required — missing must reject at deserialization.
        let err = serde_json::from_value::<IngestDocumentArgs>(json!({})).unwrap_err();
        assert!(format!("{err}").contains("path"));
    }

    #[test]
    fn search_docs_args_parse_with_default_limit() {
        let v: SearchDocsArgs =
            serde_json::from_value(json!({ "query": "backups" })).expect("parses");
        assert_eq!(v.query, "backups");
        assert_eq!(v.limit, 5, "default limit must be 5");
        let v: SearchDocsArgs =
            serde_json::from_value(json!({ "query": "backups", "limit": 20 })).expect("parses");
        assert_eq!(v.limit, 20);
    }

    #[test]
    fn inspect_document_args_parse_with_required_doc_id() {
        let v: InspectDocumentArgs =
            serde_json::from_value(json!({ "doc_id": "abc" })).expect("parses");
        assert_eq!(v.doc_id, "abc");
        let err = serde_json::from_value::<InspectDocumentArgs>(json!({})).unwrap_err();
        assert!(format!("{err}").contains("doc_id"));
    }

    #[test]
    fn list_documents_args_parse_with_all_defaults() {
        let v: ListDocumentsArgs = serde_json::from_value(json!({})).expect("parses");
        assert_eq!(v.limit, 20, "default limit must be 20");
        assert_eq!(v.offset, 0, "default offset must be 0");
        assert!(!v.include_forgotten, "default include_forgotten must be false");
        let v: ListDocumentsArgs = serde_json::from_value(
            json!({ "limit": 5, "offset": 10, "include_forgotten": true }),
        )
        .expect("parses");
        assert_eq!(v.limit, 5);
        assert_eq!(v.offset, 10);
        assert!(v.include_forgotten);
    }

    #[test]
    fn forget_document_args_parse_with_required_doc_id() {
        let v: ForgetDocumentArgs =
            serde_json::from_value(json!({ "doc_id": "abc" })).expect("parses");
        assert_eq!(v.doc_id, "abc");
        let err = serde_json::from_value::<ForgetDocumentArgs>(json!({})).unwrap_err();
        assert!(format!("{err}").contains("doc_id"));
    }

    #[test]
    fn ingest_document_rejects_empty_path() {
        // Reaches the dispatch arm → handle_ingest_document → empty
        // guard fires before the writer is touched. Proves routing.
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool("memory_ingest_document", json!({ "path": "" }))
                .await
                .expect_err("empty path must error");
            let s = format!("{err:?}");
            assert!(
                s.to_lowercase().contains("path")
                    || s.to_lowercase().contains("must not be empty"),
                "got: {s}"
            );
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn search_docs_rejects_empty_query() {
        // Empty query trips solo_query::run_doc_search's validation
        // → InvalidInput → invalid_params.
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool("memory_search_docs", json!({ "query": "   " }))
                .await
                .expect_err("empty query must error");
            let s = format!("{err:?}");
            assert!(
                s.to_lowercase().contains("must not be empty")
                    || s.to_lowercase().contains("invalid"),
                "got: {s}"
            );
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn inspect_document_unknown_id_returns_invalid_params() {
        // Valid UUID format but no row exists → handler returns
        // invalid_params with the missing id in the message.
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool(
                    "memory_inspect_document",
                    json!({ "doc_id": "00000000-0000-7000-8000-000000000000" }),
                )
                .await
                .expect_err("unknown doc must error");
            let s = format!("{err:?}");
            assert!(
                s.to_lowercase().contains("not found"),
                "expected 'not found' message; got: {s}"
            );
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn inspect_document_rejects_malformed_id() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool(
                    "memory_inspect_document",
                    json!({ "doc_id": "not-a-uuid" }),
                )
                .await
                .expect_err("malformed doc_id must error");
            let s = format!("{err:?}");
            assert!(s.contains("invalid doc_id"), "got: {s}");
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn list_documents_returns_empty_array_on_empty_db() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let r = h
                .server
                .dispatch_tool("memory_list_documents", json!({}))
                .await
                .expect("list succeeds");
            let text = first_text(&r);
            let v: serde_json::Value =
                serde_json::from_str(&text).expect("parses as json");
            assert!(v.is_array(), "expected array, got: {text}");
            assert_eq!(v.as_array().unwrap().len(), 0);
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn list_documents_passes_through_limit_offset_include_args() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let r = h
                .server
                .dispatch_tool(
                    "memory_list_documents",
                    json!({ "limit": 5, "offset": 10, "include_forgotten": true }),
                )
                .await
                .expect("list with args succeeds");
            let text = first_text(&r);
            let v: serde_json::Value =
                serde_json::from_str(&text).expect("parses as json");
            assert!(v.is_array());
        });
        h.shutdown(&runtime);
    }

    #[test]
    fn forget_document_rejects_malformed_id() {
        let runtime = rt();
        let h = Harness::new(&runtime);
        runtime.block_on(async {
            let err = h
                .server
                .dispatch_tool(
                    "memory_forget_document",
                    json!({ "doc_id": "not-a-uuid" }),
                )
                .await
                .expect_err("malformed doc_id must error");
            let s = format!("{err:?}");
            assert!(s.contains("invalid doc_id"), "got: {s}");
        });
        h.shutdown(&runtime);
    }
}

// ===========================================================================
// v0.8.1 P2: MCP audit principal extraction
// ===========================================================================
//
// These tests live in their own module because they manipulate the
// `SOLO_MCP_PRINCIPAL_TOKEN` env var, which is process-global mutable
// state. Serialised via a static `Mutex` so cargo test's multi-threaded
// runner doesn't race. Pattern mirrors the env-guard discipline in
// `solo_cli::commands::common::ollama_overrides_tests`.

#[cfg(test)]
mod principal_extraction_tests {
    use super::*;
    use std::sync::Mutex;

    /// Serialise tests that mutate `SOLO_MCP_PRINCIPAL_TOKEN`. Poisoned
    /// guards are recovered via `into_inner` so one panicking test
    /// doesn't sink the rest of the suite.
    static ENV_LOCK: Mutex<()> = Mutex::new(());

    /// RAII guard that unsets the env var on drop, so a panicking test
    /// doesn't leak state into the next case.
    struct EnvGuard;
    impl Drop for EnvGuard {
        fn drop(&mut self) {
            // SAFETY: every caller holds ENV_LOCK across construct + drop.
            unsafe { std::env::remove_var(ENV_MCP_PRINCIPAL_TOKEN) };
        }
    }

    fn set_principal_env(val: &str) -> EnvGuard {
        // SAFETY: ENV_LOCK held by caller.
        unsafe { std::env::set_var(ENV_MCP_PRINCIPAL_TOKEN, val) };
        EnvGuard
    }

    fn clear_principal_env() -> EnvGuard {
        // SAFETY: ENV_LOCK held by caller.
        unsafe { std::env::remove_var(ENV_MCP_PRINCIPAL_TOKEN) };
        EnvGuard
    }

    /// Stdio path: setting `SOLO_MCP_PRINCIPAL_TOKEN` produces a
    /// non-None principal at construction time.
    #[test]
    fn stdio_env_var_resolves_to_principal() {
        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
        let _g = set_principal_env("alice-token");
        let resolved = resolve_mcp_principal(None);
        assert_eq!(resolved.as_deref(), Some("alice-token"));
    }

    /// Stdio path: absent env var ⇒ `None` (regression — must preserve
    /// v0.8.0 behaviour for users without auth).
    #[test]
    fn stdio_no_env_var_resolves_to_none() {
        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
        let _g = clear_principal_env();
        assert_eq!(resolve_mcp_principal(None), None);
    }

    /// Stdio path: whitespace-only env var ⇒ `None` (don't pin every
    /// audit row to an empty/blank principal because of a launcher
    /// typo).
    #[test]
    fn stdio_whitespace_env_var_resolves_to_none() {
        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
        let _g = set_principal_env("   \t  ");
        assert_eq!(resolve_mcp_principal(None), None);
    }

    /// HTTP-MCP path: `Authorization: Bearer <token>` header resolves
    /// to the token as principal.
    #[test]
    fn http_header_resolves_to_bearer_token_principal() {
        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
        let _g = clear_principal_env();
        let resolved = resolve_mcp_principal(Some("Bearer api-token-xyz"));
        assert_eq!(resolved.as_deref(), Some("api-token-xyz"));
    }

    /// Precedence: when both env var AND header carry a token, the
    /// header wins (consistent with the rest of the auth stack — JWT
    /// claim beats `X-Solo-Tenant` header).
    #[test]
    fn http_header_beats_env_var() {
        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
        let _g = set_principal_env("env-token");
        let resolved = resolve_mcp_principal(Some("Bearer header-token"));
        assert_eq!(
            resolved.as_deref(),
            Some("header-token"),
            "header MUST win over env var per documented precedence"
        );
    }

    /// HTTP-MCP path: malformed header (no `Bearer ` prefix) ⇒ falls
    /// through to env-var path.
    #[test]
    fn http_malformed_header_falls_through_to_env() {
        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
        let _g = set_principal_env("env-fallback");
        let resolved = resolve_mcp_principal(Some("Basic dXNlcjpwYXNz"));
        assert_eq!(resolved.as_deref(), Some("env-fallback"));
    }

    /// HTTP-MCP path: empty bearer header (`Bearer ` with no token)
    /// falls through to env-var path. Matches the spirit of the
    /// whitespace-env-var rejection — don't credit a half-formed
    /// header.
    #[test]
    fn http_empty_bearer_header_falls_through_to_env() {
        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
        let _g = set_principal_env("env-fallback");
        let resolved = resolve_mcp_principal(Some("Bearer   "));
        assert_eq!(resolved.as_deref(), Some("env-fallback"));
    }

    /// Across N consecutive calls of `resolve_mcp_principal`, the
    /// resolved principal is stable for the same env-var setting
    /// (regression guard: an accidental thread-local cache would
    /// break the "stable across N tool calls in one session" contract
    /// the brief calls out).
    #[test]
    fn stable_across_multiple_resolutions() {
        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
        let _g = set_principal_env("stable-token");
        for _ in 0..5 {
            assert_eq!(
                resolve_mcp_principal(None).as_deref(),
                Some("stable-token")
            );
        }
    }
}

// fetch_recall_rows + RecallHit + RecallRow used to live here. Recall
// pipeline moved to solo_query::recall in commit (consolidate-recall);
// transports just call solo_query::run_recall and format the result.