mcp_tools.py

"""Viking operations exposed as MCP tools for host agents.

The host agent (OpenClaw, Claude Code, Codex, Cursor, nanobot, …) sees
these as ordinary MCP tools and can invoke them directly — without ever
delegating a task to OpenSpace's full execution engine. This closes the
biggest gap in the Viking integration: previously the host agent's
direct chat surface could not benefit from cross-session memories.

Five tools are exposed:

    openviking_retrieve_memory(query, category?, limit?)
        — fetch cross-session abstracts for a query

    openviking_remember(content, category, polarity?)
        — record a new memory from an explicit user/agent observation

    openviking_forget_memory(uri, reason?)
        — mark a specific memory as stale / delete it

    openviking_report_stale_memory(uri, reason)
        — lighter-weight variant that never deletes, just flags

    openviking_memory_status()
        — health + config introspection (namespace, user_id, push toggle)

Every tool is best-effort. When Viking is offline or the client is
not configured, tools return a structured error string instead of
raising, so the host LLM can recover gracefully.

Registration: call :func:`register_viking_mcp_tools(mcp, get_client)`
from the MCP server bootstrap (``openspace/mcp_server.py``). The
``get_client`` callable is used to lazily fetch the shared
``OpenVikingClient`` so the MCP server does not need to import the
Viking module at startup.
"""
from __future__ import annotations

import json
from typing import Any, Awaitable, Callable, Dict, List, Optional

from openspace.utils.logging import Logger

logger = Logger.get_logger(__name__)


# Category aliases the host LLM might use — mapped to the canonical
# memory category names understood by the client's URI builder.
_CATEGORY_ALIASES = {
    "tools": "tools",
    "tool": "tools",
    "tool_knowledge": "tools",
    "patterns": "patterns",
    "pattern": "patterns",
    "skills": "skills",
    "skill": "skills",
    "cases": "cases",
    "case": "cases",
    "preferences": "preferences",
    "preference": "preferences",
    "user_preferences": "preferences",
    "antipatterns": "antipatterns",
    "antipattern": "antipatterns",
    "failures": "antipatterns",
    "anti_patterns": "antipatterns",
}


def _normalize_category(category: Optional[str]) -> Optional[str]:
    if not category:
        return None
    key = category.strip().lower().replace("-", "_")
    return _CATEGORY_ALIASES.get(key)


def _resolve_target_uri(client: Any, category: Optional[str]) -> str:
    """Return the target URI for a normalized category, or '' for all."""
    norm = _normalize_category(category)
    if norm is None:
        return ""
    if norm in ("tools", "patterns", "skills", "cases", "antipatterns"):
        return client.agent_memory_uri(norm)
    if norm == "preferences":
        return client.user_memory_uri("preferences")
    return ""


def _error(message: str, **extra: Any) -> str:
    return json.dumps({"status": "error", "error": message, **extra}, ensure_ascii=False)


def _ok(data: Any) -> str:
    return json.dumps({"status": "ok", "data": data}, ensure_ascii=False)


# ---------------------------------------------------------------------------
# Tool implementations
# ---------------------------------------------------------------------------
async def tool_retrieve_memory(
    get_client: Callable[[], Awaitable[Any]],
    query: str,
    category: Optional[str] = None,
    limit: int = 5,
) -> str:
    """Retrieve cross-session memory abstracts for a query.

    This is how a host agent (OpenClaw chat surface, etc.) pulls user
    preferences / tool knowledge / past solutions *without* invoking
    the full OpenSpace execution engine.
    """
    if not query or not isinstance(query, str):
        return _error("query is required and must be a non-empty string")
    limit = max(1, min(int(limit or 5), 20))

    client = await get_client()
    if client is None:
        return _error("OpenViking client is not configured")
    if not await client.is_available():
        return _error("OpenViking server is not available", code="unavailable")

    target_uri = _resolve_target_uri(client, category)
    try:
        results = await client.find_memories(
            query,
            target_uri=target_uri,
            limit=limit,
        )
    except Exception as exc:
        return _error(f"find_memories failed: {exc}")

    abstracts: List[Dict[str, Any]] = []
    for m in results or []:
        if not isinstance(m, dict):
            continue
        abstracts.append({
            "uri": m.get("uri", ""),
            "abstract": m.get("abstract") or m.get("summary") or m.get("content") or "",
            "score": m.get("score", 0.0),
            "category": m.get("category", ""),
        })

    return _ok({
        "query": query,
        "category": _normalize_category(category),
        "target_uri": target_uri,
        "count": len(abstracts),
        "results": abstracts,
    })


async def tool_remember(
    get_client: Callable[[], Awaitable[Any]],
    content: str,
    category: str = "cases",
    polarity: str = "positive",
) -> str:
    """Record an explicit user observation as a Viking memory.

    The host agent can surface a "save this" intent from the user and
    forward the observation here. A lightweight session is created and
    committed so Viking's extraction pipeline writes it into the right
    memory bucket.
    """
    if not content or not isinstance(content, str):
        return _error("content is required")
    norm = _normalize_category(category) or "cases"
    pol = (polarity or "positive").strip().lower()
    if pol not in ("positive", "negative"):
        return _error("polarity must be 'positive' or 'negative'")

    client = await get_client()
    if client is None:
        return _error("OpenViking client is not configured")
    if not await client.is_available():
        return _error("OpenViking server is not available", code="unavailable")

    # Use enrichment.feedback_negative for polarity=negative so the
    # session is written to the antipatterns bucket with the correct
    # polarity marker. For positive we compose a minimal session here.
    import time as _time
    session_id = f"openspace-remember-{int(_time.time() * 1000)}"

    try:
        await client.create_session(session_id)
        if pol == "negative":
            await client.add_session_message(
                session_id,
                "assistant",
                "POLARITY: negative — explicit anti-pattern recorded by host agent.",
            )
        await client.add_session_message(session_id, "user", content[:4000])
        await client.add_session_message(
            session_id,
            "assistant",
            f"Category hint: {norm}",
        )
        await client.commit_session(session_id)
    except Exception as exc:
        return _error(f"remember failed: {exc}")

    return _ok({
        "session_id": session_id,
        "category": norm,
        "polarity": pol,
    })


async def tool_forget_memory(
    get_client: Callable[[], Awaitable[Any]],
    uri: str,
    reason: str = "",
) -> str:
    """Delete (or deprecate) a specific memory by URI."""
    if not uri:
        return _error("uri is required")
    client = await get_client()
    if client is None:
        return _error("OpenViking client is not configured")
    if not await client.is_available():
        return _error("OpenViking server is not available", code="unavailable")

    try:
        resp = await client.delete_resource(uri)
    except Exception as exc:
        return _error(f"forget_memory failed: {exc}")

    if resp:
        return _ok({"uri": uri, "deleted": True, "reason": reason[:500]})
    return _ok({"uri": uri, "deleted": False, "reason": reason[:500],
                "note": "Viking did not confirm deletion — stale-report fallback may still run"})


async def tool_report_stale_memory(
    get_client: Callable[[], Awaitable[Any]],
    uri: str,
    reason: str,
) -> str:
    """Flag a memory as stale without forcing deletion.

    Writes a dedicated report session so Viking's extraction pipeline
    can later decide to prune or deprioritize the target memory.
    """
    if not uri or not reason:
        return _error("both uri and reason are required")
    client = await get_client()
    if client is None:
        return _error("OpenViking client is not configured")
    if not await client.is_available():
        return _error("OpenViking server is not available", code="unavailable")

    try:
        from .enrichment import VikingEnrichment
        enricher = VikingEnrichment(client)
        ok = await enricher.report_stale_memory(uri, reason)
    except Exception as exc:
        return _error(f"report_stale_memory failed: {exc}")

    return _ok({"uri": uri, "reported": bool(ok), "reason": reason[:500]})


async def tool_memory_status(
    get_client: Callable[[], Awaitable[Any]],
) -> str:
    """Return integration health, namespace, and config visibility.

    Useful for host agents to decide whether to rely on Viking for a
    given turn and to surface status in UI.
    """
    client = await get_client()
    if client is None:
        return _ok({
            "configured": False,
            "available": False,
            "namespace": "",
            "user_id": "",
        })
    available = await client.is_available()
    return _ok({
        "configured": True,
        "available": bool(available),
        "base_url": client.base_url,
        "namespace": client.namespace,
        "user_id": client.user_id,
        "agent_memory_uri_tools": client.agent_memory_uri("tools"),
        "user_memory_uri_prefs": client.user_memory_uri("preferences"),
    })


# ---------------------------------------------------------------------------
# Registration helper
# ---------------------------------------------------------------------------
def register_viking_mcp_tools(
    mcp: Any,
    get_client: Callable[[], Awaitable[Any]],
) -> int:
    """Register the Viking tools on an MCP server instance.

    ``mcp`` is the FastMCP-compatible server object exposing a
    ``@mcp.tool()`` decorator. ``get_client`` is an async callable
    returning the shared ``OpenVikingClient`` (or ``None``).

    Returns the number of tools registered. Logs a warning and returns
    0 if the MCP object does not support tool registration.
    """
    if not hasattr(mcp, "tool") or not callable(mcp.tool):
        logger.debug("MCP object does not support .tool() decorator")
        return 0

    @mcp.tool()
    async def openviking_retrieve_memory(
        query: str,
        category: Optional[str] = None,
        limit: int = 5,
    ) -> str:
        """Retrieve cross-session memory abstracts from OpenViking.

        Args:
            query: Natural language search for relevant memories.
            category: Optional filter: tools, patterns, skills, cases,
                preferences, antipatterns. Omit to search all.
            limit: Maximum number of abstracts to return (1-20, default 5).
        """
        return await tool_retrieve_memory(get_client, query, category, limit)

    @mcp.tool()
    async def openviking_remember(
        content: str,
        category: str = "cases",
        polarity: str = "positive",
    ) -> str:
        """Record an explicit observation as a Viking memory.

        Args:
            content: The observation or knowledge to remember.
            category: One of tools, patterns, skills, cases,
                preferences, antipatterns.
            polarity: "positive" (default) or "negative" for anti-patterns.
        """
        return await tool_remember(get_client, content, category, polarity)

    @mcp.tool()
    async def openviking_forget_memory(
        uri: str,
        reason: str = "",
    ) -> str:
        """Delete or deprecate a specific memory by its Viking URI.

        Args:
            uri: The viking:// URI of the memory to forget.
            reason: Optional explanation for the forget action.
        """
        return await tool_forget_memory(get_client, uri, reason)

    @mcp.tool()
    async def openviking_report_stale_memory(
        uri: str,
        reason: str,
    ) -> str:
        """Flag a memory as stale without deleting it.

        Args:
            uri: The viking:// URI of the stale memory.
            reason: Why the memory is stale (e.g. "tool X updated to v2").
        """
        return await tool_report_stale_memory(get_client, uri, reason)

    @mcp.tool()
    async def openviking_memory_status() -> str:
        """Return OpenViking integration health and configuration."""
        return await tool_memory_status(get_client)

    logger.info("Registered 5 OpenViking MCP tools for host agent access")
    return 5