@event4u/agent-config 1.40.0 → 1.41.0

package/scripts/mcp_server/tools.py

@@ -1,9 +1,14 @@
-"""MCP Server — Phase 4 tools layer.
-
-A0 contract amendment: Phase 4 lifts the read-only line for exactly the
-tools listed in ``ALLOWLIST`` (`lint_skills` + `chat_history_append`).
-Every other tool name is unreachable — `tools/call` against an unknown
-name raises ``ValueError``, not just "unlisted".
+"""MCP Server — Phase 4 tools layer + Phase 1 discovery stubs.
+
+A0 contract amendment: real handlers run only for the tools listed in
+``ALLOWLIST`` (`lint_skills` + `chat_history_append`). All other names
+in ``scripts/mcp_server/consumer_tool_catalog.json`` are surfaced via
+``tools/list`` as discovery stubs; ``tools/call`` against them returns
+the ``not_implemented`` envelope defined in
+``docs/contracts/mcp-tool-stub-envelope.md`` (a successful result with
+``code: not_implemented``, an ``install_hint`` and an ``alternative``).
+Names that are neither implemented nor catalog-listed raise
+``ValueError`` (rendered by the SDK as JSON-RPC error).
 
 Path-scoping is mandatory for any tool that writes: the resolved target
 path must stay under ``<consumer_root>`` and within the allowlist of
@@ -26,6 +31,18 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Awaitable, Callable
 
+from .catalog import (
+    CatalogEntry,
+    install_hint as _catalog_install_hint,
+    load_catalog,
+    not_implemented_envelope,
+)
+from .telemetry import Outcome, record_call
+
+# Stable transport tag for the stub envelope. Mirrored verbatim by
+# `workers/mcp/src/stubs.ts` with ``"worker"``.
+STDIO_TRANSPORT = "stdio"
+
 # Allowlisted directories (relative to consumer_root) where tool writes
 # are permitted. ``chat_history_append`` resolves its path through this
 # guard before the underlying writer touches the filesystem.
@@ -242,7 +259,249 @@ async def _chat_history_append_handler(
 
 
 # ---------------------------------------------------------------------
-# Allowlist — hardcoded per AI Council Q1-a verdict (2026-05-10).
+# Phase 3 L2 — read-only handlers added under the
+# `agents/decisions/mcp-coverage-cut-2026-05-12.md` waiver verdict.
+# Each handler wraps an existing project module via lazy import so the
+# module-level import surface stays small.
+# ---------------------------------------------------------------------
+
+
+async def _chat_history_read_handler(
+    arguments: dict[str, Any],
+    consumer_root: Path,
+) -> dict[str, Any]:
+    """Phase 3 L2 — read entries from the consumer's chat-history JSONL.
+
+    Arguments:
+        last: optional trailing-N filter (positive integer).
+        session: optional 16-char session id.
+        entry_type: optional ``t`` field exact-match filter.
+        path: optional override; must resolve under
+            ``agents/.agent-chat-history`` or ``.agent-chat-history``.
+    """
+    from scripts.chat_history import read_entries  # noqa: PLC0415
+
+    raw_path = arguments.get("path")
+    target = _validate_in_tree_path(raw_path, consumer_root)
+
+    last = arguments.get("last")
+    if last is not None and (not isinstance(last, int) or last < 1):
+        raise ValueError("'last' must be a positive integer when provided")
+    session = arguments.get("session")
+    if session is not None and not isinstance(session, str):
+        raise ValueError("'session' must be a string when provided")
+    entry_type = arguments.get("entry_type")
+    if entry_type is not None and not isinstance(entry_type, str):
+        raise ValueError("'entry_type' must be a string when provided")
+
+    if not target.exists():
+        return {
+            "path": str(target),
+            "entries": [],
+            "count": 0,
+        }
+
+    entries = read_entries(last=last, path=target, session=session)
+    if entry_type:
+        entries = [e for e in entries if e.get("t") == entry_type]
+    return {
+        "path": str(target),
+        "entries": entries,
+        "count": len(entries),
+    }
+
+
+async def _memory_lookup_handler(
+    arguments: dict[str, Any],
+    consumer_root: Path,
+) -> dict[str, Any]:
+    """Phase 3 L2 — hybrid memory retrieval over ``agents/memory/``.
+
+    Wraps ``scripts/memory_lookup.retrieve_v1`` to keep the v1 envelope
+    on the wire. File-only fallback by default; ``with_package=true``
+    enables the optional ``@event4u/agent-memory`` provider when
+    reachable.
+    """
+    import os  # noqa: PLC0415
+
+    from scripts.memory_lookup import (  # noqa: PLC0415
+        package_operational_provider,
+        retrieve_v1,
+    )
+
+    types = arguments.get("types")
+    if not isinstance(types, list) or not types or not all(
+        isinstance(t, str) for t in types
+    ):
+        raise ValueError("'types' must be a non-empty list of strings")
+    keys = arguments.get("keys") or []
+    if not isinstance(keys, list) or not all(isinstance(k, str) for k in keys):
+        raise ValueError("'keys' must be a list of strings")
+    limit_raw = arguments.get("limit", 5)
+    if not isinstance(limit_raw, int) or limit_raw < 1:
+        raise ValueError("'limit' must be a positive integer")
+
+    provider = None
+    if arguments.get("with_package"):
+        provider = package_operational_provider()
+
+    prev_cwd = Path.cwd()
+    try:
+        os.chdir(consumer_root)
+        envelope = retrieve_v1(
+            types=list(types),
+            keys=list(keys),
+            limit=limit_raw,
+            operational_provider=provider,
+        )
+    finally:
+        os.chdir(prev_cwd)
+    return envelope
+
+
+async def _memory_status_handler(
+    _arguments: dict[str, Any],
+    consumer_root: Path,
+) -> dict[str, Any]:
+    """Phase 3 L2 — surface ``scripts/memory_status.status()`` as JSON."""
+    import os  # noqa: PLC0415
+
+    from dataclasses import asdict  # noqa: PLC0415
+
+    from scripts.memory_status import status  # noqa: PLC0415
+
+    prev_cwd = Path.cwd()
+    try:
+        os.chdir(consumer_root)
+        result = status()
+    finally:
+        os.chdir(prev_cwd)
+    payload = asdict(result)
+    payload["features"] = list(result.features)
+    return payload
+
+
+# Module-level prompt / resource caches reused across handler calls so
+# repeated `list_*` / `read_resource_body` calls share mtime tracking.
+_PROMPT_CACHES: dict[str, Any] = {}
+_RESOURCE_CACHES: dict[str, Any] = {}
+
+
+def _get_prompt_cache(consumer_root: Path) -> Any:
+    from .prompts import PromptCache  # noqa: PLC0415
+
+    key = str(consumer_root.resolve())
+    cache = _PROMPT_CACHES.get(key)
+    if cache is None:
+        cache = PromptCache(root=consumer_root)
+        _PROMPT_CACHES[key] = cache
+    return cache
+
+
+def _get_resource_cache(consumer_root: Path) -> Any:
+    from .resources import ResourceCache  # noqa: PLC0415
+
+    key = str(consumer_root.resolve())
+    cache = _RESOURCE_CACHES.get(key)
+    if cache is None:
+        cache = ResourceCache(root=consumer_root)
+        _RESOURCE_CACHES[key] = cache
+    return cache
+
+
+async def _list_skills_handler(
+    _arguments: dict[str, Any],
+    consumer_root: Path,
+) -> dict[str, Any]:
+    """Phase 3 L2 — enumerate skill prompts (kind=='skill')."""
+    from .prompts import to_mcp_prompt_meta  # noqa: PLC0415
+
+    cache = _get_prompt_cache(consumer_root)
+    prompts, errors = cache.get()
+    items = [
+        {
+            "name": p.name,
+            "description": p.description,
+            "source": p.source,
+            "wire_name": to_mcp_prompt_meta(p)["name"],
+        }
+        for p in prompts
+        if p.kind == "skill"
+    ]
+    items.sort(key=lambda r: r["name"])
+    return {"count": len(items), "skills": items, "errors": list(errors)}
+
+
+async def _list_commands_handler(
+    _arguments: dict[str, Any],
+    consumer_root: Path,
+) -> dict[str, Any]:
+    """Phase 3 L2 — enumerate command prompts (kind=='command')."""
+    from .prompts import to_mcp_prompt_meta  # noqa: PLC0415
+
+    cache = _get_prompt_cache(consumer_root)
+    prompts, errors = cache.get()
+    items = [
+        {
+            "name": p.name,
+            "description": p.description,
+            "source": p.source,
+            "wire_name": to_mcp_prompt_meta(p)["name"],
+        }
+        for p in prompts
+        if p.kind == "command"
+    ]
+    items.sort(key=lambda r: r["name"])
+    return {"count": len(items), "commands": items, "errors": list(errors)}
+
+
+async def _list_rules_handler(
+    _arguments: dict[str, Any],
+    consumer_root: Path,
+) -> dict[str, Any]:
+    """Phase 3 L2 — enumerate rule resources (kind=='rule')."""
+    cache = _get_resource_cache(consumer_root)
+    resources, errors = cache.get()
+    items = [
+        {
+            "uri": r.uri,
+            "name": r.name,
+            "description": r.description,
+            "source": r.source,
+        }
+        for r in resources
+        if r.kind == "rule"
+    ]
+    items.sort(key=lambda r: r["uri"])
+    return {"count": len(items), "rules": items, "errors": list(errors)}
+
+
+async def _read_resource_body_handler(
+    arguments: dict[str, Any],
+    consumer_root: Path,
+) -> dict[str, Any]:
+    """Phase 3 L2 — fetch the rendered body of a resource URI."""
+    uri = arguments.get("uri")
+    if not isinstance(uri, str) or not uri:
+        raise ValueError("'uri' must be a non-empty string")
+    cache = _get_resource_cache(consumer_root)
+    resource = cache.lookup(uri)
+    if resource is None:
+        raise ValueError(f"resource not found: {uri}")
+    return {
+        "uri": resource.uri,
+        "name": resource.name,
+        "description": resource.description,
+        "mime_type": resource.mime_type,
+        "kind": resource.kind,
+        "source": resource.source,
+        "body": resource.body,
+    }
+
+
+# ---------------------------------------------------------------------
+# Allowlist — hardcoded per AI Council Q1-a verdict (2026-05-10),
+# extended Phase 3 L2 (2026-05-12) under the council-waiver verdict.
 # Adding a tool here is a code-review event; settings cannot enable an
 # unlisted tool. Boot-time stderr log enumerates the registered set.
 # ---------------------------------------------------------------------
@@ -309,6 +568,123 @@ ALLOWLIST: dict[str, BuiltinTool] = {
         },
         handler=_chat_history_append_handler,
     ),
+    "chat_history_read": BuiltinTool(
+        name="chat_history_read",
+        description=(
+            "Read recent chat-history entries from "
+            "`agents/.agent-chat-history`. Filter by session, "
+            "trailing-N, or entry-type. Read-only."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "last": {"type": "integer", "minimum": 1},
+                "session": {"type": "string"},
+                "entry_type": {"type": "string"},
+                "path": {"type": "string"},
+            },
+            "additionalProperties": False,
+        },
+        handler=_chat_history_read_handler,
+    ),
+    "memory_lookup": BuiltinTool(
+        name="memory_lookup",
+        description=(
+            "Hybrid memory retrieval over `agents/memory/<type>/*.yml` "
+            "and `agents/memory/intake/*.jsonl`. Returns the v1 "
+            "retrieval envelope. Read-only."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "types": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "minItems": 1,
+                },
+                "keys": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                },
+                "limit": {"type": "integer", "minimum": 1, "default": 5},
+                "with_package": {"type": "boolean", "default": False},
+            },
+            "required": ["types"],
+            "additionalProperties": False,
+        },
+        handler=_memory_lookup_handler,
+    ),
+    "memory_status": BuiltinTool(
+        name="memory_status",
+        description=(
+            "Report whether the optional `@event4u/agent-memory` "
+            "package is reachable, and surface its routing metadata. "
+            "Read-only."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+        handler=_memory_status_handler,
+    ),
+    "list_skills": BuiltinTool(
+        name="list_skills",
+        description=(
+            "Enumerate every skill currently exposed as a prompt, with "
+            "name + description + source. Read-only manifest view."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+        handler=_list_skills_handler,
+    ),
+    "list_commands": BuiltinTool(
+        name="list_commands",
+        description=(
+            "Enumerate every slash command currently exposed as a "
+            "prompt. Read-only manifest view."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+        handler=_list_commands_handler,
+    ),
+    "list_rules": BuiltinTool(
+        name="list_rules",
+        description=(
+            "Enumerate every rule currently exposed as a resource. "
+            "Read-only manifest view."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+        handler=_list_rules_handler,
+    ),
+    "read_resource_body": BuiltinTool(
+        name="read_resource_body",
+        description=(
+            "Fetch the rendered body of any resource URI (rule, "
+            "guideline, context) without going through "
+            "`resources/read`. Convenience for clients that want to "
+            "inline content into a tool call result."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "uri": {"type": "string"},
+            },
+            "required": ["uri"],
+            "additionalProperties": False,
+        },
+        handler=_read_resource_body_handler,
+    ),
 }
 
 
@@ -321,17 +697,72 @@ def to_mcp_tool_meta(tool: BuiltinTool) -> dict[str, Any]:
     }
 
 
+# ---------------------------------------------------------------------
+# Phase 1 discovery stubs — catalog entries with no real handler.
+# Loaded at module import time. The Worker reads the same catalog via
+# `content.json` so `tools/list` returns identical metadata on both
+# transports apart from `implemented_on`.
+# ---------------------------------------------------------------------
+
+
+def _make_stub_handler(entry: CatalogEntry, install_hint_value: str) -> ToolHandler:
+    """Closure that returns the `not_implemented` envelope for a stub."""
+
+    async def _stub(
+        _arguments: dict[str, Any],
+        _consumer_root: Path,
+    ) -> dict[str, Any]:
+        return not_implemented_envelope(
+            entry.name,
+            transport=STDIO_TRANSPORT,
+            install_hint_value=install_hint_value,
+        )
+
+    return _stub
+
+
+def _build_catalog_registry() -> tuple[dict[str, BuiltinTool], frozenset[str]]:
+    """Build the stub registry from the catalog. ALLOWLIST wins on overlap.
+
+    Returns (registry, stub_names). `registry` contains every catalog
+    entry not already in ALLOWLIST, each wired to a closure that emits
+    the envelope.
+    """
+    install_hint_value = _catalog_install_hint()
+    entries = load_catalog()
+    registry: dict[str, BuiltinTool] = {}
+    stub_names: set[str] = set()
+    for entry in entries:
+        if entry.name in ALLOWLIST:
+            continue
+        registry[entry.name] = BuiltinTool(
+            name=entry.name,
+            description=entry.description,
+            input_schema=entry.input_schema,
+            handler=_make_stub_handler(entry, install_hint_value),
+        )
+        stub_names.add(entry.name)
+    return registry, frozenset(stub_names)
+
+
+CATALOG_STUBS, STUB_NAMES = _build_catalog_registry()
+
+# Full wire-surface registry — implemented + stubs. `tools/list` reads
+# from this; `tools/call` dispatches against it.
+REGISTRY: dict[str, BuiltinTool] = {**ALLOWLIST, **CATALOG_STUBS}
+
+
 class ToolCache:
-    """Hardcoded registry view of ``ALLOWLIST`` with a stable interface.
+    """Registry view backing the MCP `tools/*` handlers.
 
-    Kept as a class for symmetry with ``PromptCache`` / ``ResourceCache``.
-    No mtime check needed — the allowlist lives in source and changes
-    require a deploy.
+    Default registry is ``REGISTRY`` (implemented + catalog stubs).
+    Tests can pass a narrower dict (e.g. ``ALLOWLIST`` alone) to isolate
+    the implemented surface.
     """
 
     def __init__(self, registry: dict[str, BuiltinTool] | None = None) -> None:
         self._registry: dict[str, BuiltinTool] = dict(
-            registry if registry is not None else ALLOWLIST
+            registry if registry is not None else REGISTRY
         )
 
     def names(self) -> list[str]:
@@ -343,21 +774,49 @@ class ToolCache:
     def get(self, name: str) -> BuiltinTool | None:
         return self._registry.get(name)
 
+    def is_stub(self, name: str) -> bool:
+        """True when `name` is a catalog stub on this cache."""
+        return name in STUB_NAMES and name in self._registry
+
+    def implemented_names(self) -> list[str]:
+        """Subset of `names()` whose handlers run real logic."""
+        return sorted(n for n in self._registry if n in ALLOWLIST)
+
     async def dispatch(
         self,
         name: str,
         arguments: dict[str, Any],
         consumer_root: Path | None = None,
     ) -> dict[str, Any]:
+        root = _resolve_consumer_root(consumer_root)
         tool = self.get(name)
         if tool is None:
+            # Sonnet's latent-demand pattern: log the unknown name before
+            # surfacing the JSON-RPC error so Phase 2 can rank the gap.
+            self._record(name, "latent_demand", root)
             raise ValueError(f"Unknown tool: {name}")
-        root = _resolve_consumer_root(consumer_root)
+        outcome: Outcome = "stub" if self.is_stub(name) else "implemented"
+        self._record(name, outcome, root)
         return await tool.handler(arguments or {}, root)
 
+    @staticmethod
+    def _record(tool_name: str, outcome: Outcome, consumer_root: Path) -> None:
+        """Best-effort JSONL write — failures never break the wire surface."""
+        record_call(
+            tool_name=tool_name,
+            outcome=outcome,
+            transport=STDIO_TRANSPORT,
+            consumer_root=consumer_root,
+        )
+
 
 def boot_log_line(cache: ToolCache) -> str:
     """Single-line stderr enumeration of the registered tools."""
-    names = cache.names()
-    return f"mcp-server: registered {len(names)} tools: {names}"
+    total = len(cache.names())
+    implemented = len(cache.implemented_names())
+    stubs = total - implemented
+    return (
+        f"mcp-server: registered {total} tools "
+        f"({implemented} implemented, {stubs} stubs): {cache.names()}"
+    )