feat(mcp): add project issue context and knowledge search

mcp_servers/project_context/providers/knowledge.py

@@ -1,10 +1,52 @@
-"""Provider boundary owned with search_project_knowledge."""
+"""Read-only project-knowledge adapter for search_project_knowledge.
+
+Retrieval reuses what Cowork already owns rather than adding a vector store,
+an embedding pipeline, or a new RAG framework:
+
+* core.projects already defines a project's *knowledge* as the files at its
+  workspace root, and already confines one project's agent to that folder.
+  That same folder is the only corpus this provider will ever read, which is
+  what makes project isolation structural instead of a filter applied later.
+* core.doc_extract.extract_text already turns docx/pptx/xlsx/pdf/text into
+  plain text for prompt building, so this provider inherits format support.
+
+Ranking is a bounded lexical (term-overlap) scan over those files. It is a
+deliberate floor, not a claim of semantic search -- see the ponytail note on
+_score_chunk.
+
+Target and access resolution stay separate here, exactly as in the issue
+provider, so a pilot workspace root can later become a served knowledge base
+without changing the tool or the provider contract.
+"""
 
 from __future__ import annotations
 
+import os
+import re
+import unicodedata
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
 from typing import Any, Protocol
 
-from ..foundation import IdentityContext, ProviderError
+from ..foundation import IdentityContext, ProviderError, decode_offset_cursor
+
+# ---- tunables (documented, not hardcoded secrets) -------------------------
+_PAGE_SIZE_BY_DETAIL = {"summary": 3, "standard": 5, "full": 10}
+_EXCERPT_CHARS_BY_DETAIL = {"summary": 200, "standard": 600, "full": 1200}
+_MAX_FILES_SCANNED = 200
+_MAX_FILE_BYTES = 2_000_000
+_MAX_CHARS_PER_DOCUMENT = 200_000
+_CHUNK_CHARS = 1_200
+_MAX_CANDIDATES = 500
+_MAX_QUERY_TERMS = 32
+
+_KNOWLEDGE_SUFFIXES = frozenset({
+    ".md", ".markdown", ".txt", ".rst", ".csv", ".json", ".yaml", ".yml",
+    ".docx", ".docm", ".pptx", ".xlsx", ".xlsm", ".pdf", ".odt", ".odp", ".ods",
+})
+_WORD_PATTERN = re.compile(r"\w+", re.UNICODE)
+_HEADING_PATTERN = re.compile(r"^(#{1,6})[ \t]+(.+?)\s*$", re.MULTILINE)
 
 
 class KnowledgeProvider(Protocol):
@@ -33,6 +75,334 @@ class UnconfiguredKnowledgeProvider:
         )
 
 
-def build_provider(identity: IdentityContext) -> KnowledgeProvider:
-    """Replace only this factory when wiring approved project retrieval."""
-    return UnconfiguredKnowledgeProvider()
+@dataclass(frozen=True)
+class _WorkspaceTarget:
+    """One project's approved knowledge root. The provider never reads outside it."""
+
+    root: Path
+    project_id: str
+
+
+class KnowledgeTargetResolver(Protocol):
+    def resolve(self, identity: IdentityContext) -> _WorkspaceTarget: ...
+
+
+class KnowledgeAccessResolver(Protocol):
+    def resolve(self, identity: IdentityContext, target: _WorkspaceTarget) -> None: ...
+
+
+def _is_safe_segment(value: str) -> bool:
+    return (
+        bool(value)
+        and value not in {".", ".."}
+        and not set(value) & set("/\\")
+        and "\x00" not in value
+    )
+
+
+@dataclass(frozen=True)
+class ProjectWorkspaceTargetResolver:
+    """Resolve the workspace root from the *identity*, never from the request.
+
+    project_id in the request is only ever verified against this result; it is
+    never routing authority.
+    """
+
+    def resolve(self, identity: IdentityContext) -> _WorkspaceTarget:
+        configured = os.environ.get("PROJECT_CONTEXT_KNOWLEDGE_ROOT", "").strip()
+        if not configured:
+            raise ProviderError(
+                "UNAVAILABLE",
+                "PROJECT_CONTEXT_KNOWLEDGE_ROOT is not configured for this environment.",
+                retryable=False,
+            )
+        base = Path(configured).expanduser()
+        # The identity's project name is a path *segment*, never a path, so a
+        # traversal-shaped project can never escape the configured base.
+        if not _is_safe_segment(identity.project):
+            raise ProviderError(
+                "UNAVAILABLE",
+                "This identity is not mapped to an approved knowledge workspace.",
+                retryable=False,
+            )
+        try:
+            resolved = (base / identity.project).resolve()
+            resolved_base = base.resolve()
+        except OSError as exc:
+            raise ProviderError(
+                "UNAVAILABLE",
+                "The approved knowledge workspace could not be opened.",
+                retryable=False,
+            ) from exc
+        if resolved_base not in resolved.parents or not resolved.is_dir():
+            raise ProviderError(
+                "UNAVAILABLE",
+                "This identity is not mapped to an approved knowledge workspace.",
+                retryable=False,
+            )
+        return _WorkspaceTarget(root=resolved, project_id=identity.project)
+
+
+@dataclass(frozen=True)
+class LocalWorkspaceAccessResolver:
+    """Pilot access check for a local workspace root.
+
+    The local corpus needs no fetch credential, so this resolver only asserts
+    the workspace is readable. It exists as its own seam so an on-behalf-of
+    credential for a served knowledge base can replace it without touching the
+    tool or the provider.
+    """
+
+    def resolve(self, identity: IdentityContext, target: _WorkspaceTarget) -> None:
+        del identity
+        if not os.access(target.root, os.R_OK):
+            raise ProviderError(
+                "UNAVAILABLE",
+                "The approved knowledge workspace is not readable.",
+                retryable=False,
+            )
+
+
+def build_provider(
+    identity: IdentityContext,
+    *,
+    target_resolver: KnowledgeTargetResolver | None = None,
+    access_resolver: KnowledgeAccessResolver | None = None,
+) -> KnowledgeProvider:
+    """Compose routing and access only after the policy has allowed the call."""
+    target = (target_resolver or ProjectWorkspaceTargetResolver()).resolve(identity)
+    (access_resolver or LocalWorkspaceAccessResolver()).resolve(identity, target)
+    return WorkspaceKnowledgeProvider(target)
+
+
+def _normalize(text: str) -> str:
+    return unicodedata.normalize("NFKC", text).casefold()
+
+
+def _terms(text: str) -> list[str]:
+    return _WORD_PATTERN.findall(_normalize(text))[:_MAX_QUERY_TERMS]
+
+
+class WorkspaceKnowledgeProvider:
+    """Ranked, bounded, read-only lexical search over ONE project's workspace."""
+
+    def __init__(self, target: _WorkspaceTarget, *, extractor: Any = None) -> None:
+        self._target = target
+        self._extractor = extractor
+
+    def search_knowledge(
+        self,
+        *,
+        project_id: str,
+        query: str,
+        detail: str,
+        top_k: int,
+        language: str | None = None,
+        cursor: str | None = None,
+        **_: Any,
+    ) -> dict[str, Any]:
+        del language  # accepted by the contract; the lexical scan is language-neutral
+        if project_id != self._target.project_id:
+            # Defense in depth: the runtime's policy already guarantees this
+            # (DENIED fires first), but the provider never trusts
+            # caller-supplied routing regardless.
+            raise ProviderError(
+                "INTERNAL",
+                "Resolved provider does not match the requested project.",
+                retryable=False,
+            )
+        terms = _terms(query)
+        if not terms:
+            # Whitespace/punctuation-only queries pass the contract's length
+            # bound but carry no search intent -- reject before any file read.
+            raise ProviderError(
+                "INVALID_INPUT",
+                "query must contain at least one searchable term.",
+                retryable=False,
+            )
+        offset = decode_offset_cursor(cursor)
+
+        scored = self._scan(terms)
+        page_size = min(_PAGE_SIZE_BY_DETAIL.get(detail, 5), top_k)
+        excerpt_chars = _EXCERPT_CHARS_BY_DETAIL.get(detail, 600)
+
+        page = scored[offset : offset + page_size]
+        remaining = max(0, len(scored) - (offset + page_size))
+        truncated = remaining > 0
+        retrieved_at = datetime.now(timezone.utc).isoformat()
+
+        items = tuple(
+            {
+                "document_id": hit["document_id"],
+                "chunk_id": hit["chunk_id"],
+                "title": hit["title"][:200],
+                "excerpt": hit["text"][:excerpt_chars],
+                "score": hit["score"],
+                "source": {
+                    "system": "cowork-workspace",
+                    "url": hit["url"],
+                    "revision": hit["revision"],
+                    "retrieved_at": retrieved_at,
+                },
+            }
+            for hit in page
+        )
+
+        return {
+            "project_id": project_id,
+            "query": query,
+            "items": items,
+            "truncated": truncated,
+            "returned": len(items),
+            "remaining": remaining,
+            "next_cursor": str(offset + page_size) if truncated else None,
+        }
+
+    # ---- internals ---------------------------------------------------
+    def _scan(self, terms: list[str]) -> list[dict[str, Any]]:
+        candidates: list[dict[str, Any]] = []
+        for path in self._knowledge_files():
+            text = self._read(path)
+            if not text:
+                continue
+            document_id = path.relative_to(self._target.root).as_posix()
+            revision = self._revision(path)
+            url = path.as_uri()
+            for index, (heading, chunk) in enumerate(_chunk(text)):
+                score = _score_chunk(chunk, heading, document_id, terms)
+                if score <= 0:
+                    continue
+                candidates.append({
+                    "document_id": document_id,
+                    "chunk_id": f"{document_id}#{index}",
+                    "title": heading or path.name,
+                    "text": chunk.strip(),
+                    "score": score,
+                    "url": url,
+                    "revision": revision,
+                })
+                if len(candidates) >= _MAX_CANDIDATES:
+                    break
+            if len(candidates) >= _MAX_CANDIDATES:
+                break
+        # Deterministic order: best score first, then a stable identity tiebreak
+        # so pagination cursors stay meaningful across calls.
+        candidates.sort(key=lambda hit: (-hit["score"], hit["chunk_id"]))
+        return candidates
+
+    def _knowledge_files(self) -> list[Path]:
+        try:
+            entries = sorted(
+                p for p in self._target.root.rglob("*")
+                if p.is_file() and p.suffix.lower() in _KNOWLEDGE_SUFFIXES
+            )
+        except OSError as exc:
+            raise ProviderError(
+                "UNAVAILABLE",
+                "The approved knowledge workspace could not be listed.",
+                retryable=False,
+            ) from exc
+        approved: list[Path] = []
+        for path in entries:
+            # A symlink can point outside the workspace: resolve and re-check
+            # containment so project isolation survives a planted link.
+            try:
+                resolved = path.resolve()
+            except OSError:
+                continue
+            if self._target.root not in resolved.parents:
+                continue
+            try:
+                if path.stat().st_size > _MAX_FILE_BYTES:
+                    continue
+            except OSError:
+                continue
+            approved.append(path)
+            if len(approved) >= _MAX_FILES_SCANNED:
+                break
+        return approved
+
+    def _read(self, path: Path) -> str:
+        extractor = self._extractor or _default_extractor()
+        try:
+            text, _note = extractor(path)
+        except Exception:  # noqa: BLE001 - one unreadable document must not fail the search
+            return ""
+        return (text or "")[:_MAX_CHARS_PER_DOCUMENT]
+
+    def _revision(self, path: Path) -> str:
+        try:
+            stat = path.stat()
+        except OSError:
+            return "unknown"
+        modified = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc).isoformat()
+        return f"mtime:{modified};size:{stat.st_size}"
+
+
+def _default_extractor():
+    """Reuse Cowork's existing text extraction; fall back to plain-text reads.
+
+    The fallback keeps the MCP server importable as a standalone process (the
+    app package pulls in UI-oriented dependencies) without duplicating any of
+    the format handling when the app package is present.
+    """
+    try:
+        from ....core.doc_extract import extract_text
+    except Exception:  # noqa: BLE001 - standalone server run outside the app package
+        def _plain(path: Path) -> tuple[str | None, str]:
+            try:
+                return path.read_text(encoding="utf-8", errors="replace"), ""
+            except OSError as exc:
+                return None, f"could not read ({exc})"
+        return _plain
+    return lambda path: extract_text(path)
+
+
+def _chunk(text: str) -> list[tuple[str, str]]:
+    """Split a document into (heading, body) chunks.
+
+    Markdown headings give a citable section; unheaded text falls back to
+    fixed-size windows so every chunk stays bounded.
+    """
+    headings = list(_HEADING_PATTERN.finditer(text))
+    if not headings:
+        return [("", text[i : i + _CHUNK_CHARS]) for i in range(0, len(text), _CHUNK_CHARS)]
+    chunks: list[tuple[str, str]] = []
+    preamble = text[: headings[0].start()].strip()
+    if preamble:
+        chunks.append(("", preamble[:_CHUNK_CHARS]))
+    for index, match in enumerate(headings):
+        end = headings[index + 1].start() if index + 1 < len(headings) else len(text)
+        body = text[match.end() : end]
+        heading = match.group(2).strip().rstrip("#").strip()
+        for start in range(0, max(len(body), 1), _CHUNK_CHARS):
+            chunks.append((heading, body[start : start + _CHUNK_CHARS]))
+    return chunks
+
+
+def _score_chunk(chunk: str, heading: str, document_id: str, terms: list[str]) -> float:
+    """Term-coverage score in [0, 1], weighted toward heading/title matches.
+
+    ponytail: lexical term overlap, not embeddings. It needs no index, no
+    model, and no new dependency, and it is honest about what it is -- the
+    score is coverage, never a fabricated similarity. Upgrade path: swap this
+    one function for a Cowork-provided semantic ranker when the project corpus
+    is large enough that recall (not plumbing) is the bottleneck.
+    """
+    body = _normalize(chunk)
+    label = _normalize(f"{heading} {document_id}")
+    matched = 0
+    weighted = 0.0
+    for term in terms:
+        in_body = term in body
+        in_label = term in label
+        if not (in_body or in_label):
+            continue
+        matched += 1
+        weighted += 1.0 if in_label else 0.6
+    if not matched:
+        return 0.0
+    coverage = matched / len(terms)
+    emphasis = weighted / len(terms)
+    # Bounded to the contract's [0, 1] score range.
+    return round(min(1.0, 0.7 * coverage + 0.3 * emphasis), 4)