tylor-mcp 1.0.0

package/server/tools/hooks.py

@@ -0,0 +1,357 @@
+"""
+server/tools/hooks.py — Claude Code lifecycle hook helpers.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+from typing import Any, Callable
+
+from server.tools.summarizer import summarize_thread
+from server.tools.tylor import _get_db, _get_memory_client, _now_iso, list_threads
+
+
+CODE_INDEX_QUERY = "code index"
+CODE_INDEX_MAX_ENTRIES = 30
+CODE_INDEX_TOKEN_BUDGET = 150
+INDEXABLE_SUFFIXES = {".py", ".js", ".jsx", ".ts", ".tsx"}
+SKIP_SUFFIXES = {".json", ".yaml", ".yml", ".toml", ".md", ".txt", ".env"}
+SKIP_NAME_PARTS = {"config", "settings", "requirements", "package-lock"}
+
+
+def _rough_word_count(text: str) -> int:
+    # Approximation only — actual LLM token count is ~1.3–1.5× word count.
+    # Used for budget enforcement; keeps header well under the true token limit.
+    return len(text.split())
+
+
+def _code_index_header(thread_name: str, facts: list[dict], max_tokens: int = CODE_INDEX_TOKEN_BUDGET) -> str:
+    header = f"[{thread_name or 'Active'} Thread — Code Index]"
+    lines = [header]
+    used = _rough_word_count(header)
+    sorted_facts = sorted(
+        facts,
+        key=lambda fact: fact.get("last_used_at") or fact.get("created_at") or "",
+        reverse=True,
+    )
+    for fact in sorted_facts:
+        content = str(fact.get("content", "")).strip()
+        if not content:
+            continue
+        cost = _rough_word_count(content)
+        if used + cost > max_tokens:
+            continue  # skip this entry but keep trying smaller ones
+        lines.append(content)
+        used += cost
+    return "\n".join(lines) if len(lines) > 1 else ""
+
+
+def build_code_index_header(
+    thread_id: str,
+    thread_name: str,
+    memory_client: Any | None = None,
+    max_tokens: int = CODE_INDEX_TOKEN_BUDGET,
+) -> str:
+    """Return compact code-index header for active thread context injection."""
+    try:
+        memory = memory_client or _get_memory_client()
+        facts = memory.search_memory(
+            thread_id=thread_id,
+            query=CODE_INDEX_QUERY,
+            k=CODE_INDEX_MAX_ENTRIES,
+            type="code_index",
+        )
+    except Exception:
+        return ""
+    return _code_index_header(thread_name, facts, max_tokens=max_tokens)
+
+
+def _thread_line(thread: dict) -> str:
+    return (
+        f"- {thread.get('name', '(unnamed)')} "
+        f"({thread.get('thread_id')}, {thread.get('status', 'unknown')}, "
+        f"{thread.get('message_count', 0)} messages)"
+    )
+
+
+def session_start_message(
+    db: Any | None = None,
+    list_threads_fn: Callable[[], dict] = list_threads,
+    memory_client: Any | None = None,
+) -> str:
+    """Return active-thread context for Claude Code SessionStart output."""
+    db = db or _get_db()
+    marker = db.get_current_thread_marker()
+    threads = list_threads_fn().get("threads", [])
+
+    if not marker or not marker.get("CurrentThreadId"):
+        if not threads:
+            return "agent101: No active thread found. Start with /new-thread when ready."
+        thread_list = "\n".join(_thread_line(thread) for thread in threads[:5])
+        return (
+            "agent101 thread context: No active thread marker found.\n"
+            "Recent threads:\n"
+            f"{thread_list}"
+        )
+
+    current_id = marker["CurrentThreadId"]
+    current = next((thread for thread in threads if thread.get("thread_id") == current_id), None)
+    if not current:
+        meta = db.get_thread_meta(current_id) or {}
+        current = {
+            "thread_id": current_id,
+            "name": meta.get("Name", ""),
+            "status": meta.get("Status", "unknown"),
+            "message_count": meta.get("MessageCount", 0),
+        }
+
+    thread_list = "\n".join(_thread_line(thread) for thread in threads[:5])
+    code_header = build_code_index_header(
+        current_id,
+        current.get("name", ""),
+        memory_client=memory_client,
+    )
+    code_block = f"{code_header}\n\n" if code_header else ""
+    return (
+        f"{code_block}"
+        "agent101 active thread context:\n"
+        f"Active thread: {_thread_line(current)}\n"
+        f"Active since: {marker.get('ActiveAt', 'unknown')}\n"
+        "Recent threads:\n"
+        f"{thread_list}\n"
+        "Acknowledge this active thread before continuing."
+    )
+
+
+def checkpoint_current_thread(
+    db: Any | None = None,
+    now_fn: Callable[[], str] = _now_iso,
+) -> dict:
+    """Snapshot current thread metadata with a fresh checkpoint timestamp."""
+    db = db or _get_db()
+    marker = db.get_current_thread_marker()
+    if not marker or not marker.get("CurrentThreadId"):
+        return {"status": "skipped", "reason": "no_active_thread"}
+
+    thread_id = marker["CurrentThreadId"]
+    meta = db.get_thread_meta(thread_id)
+    if not meta:
+        return {"status": "skipped", "reason": "active_thread_missing", "thread_id": thread_id}
+
+    now = now_fn()
+    updated = dict(meta)
+    updated["LastActivity"] = now
+    updated["CheckpointAt"] = now
+    db.put_item(f"THREAD#{thread_id}#META", updated)
+    return {"status": "checkpointed", "thread_id": thread_id}
+
+
+def dispatch_kill_thread_summary(
+    thread_id: str,
+    project_root: Path | str | None = None,
+    python_executable: str = sys.executable,
+) -> dict:
+    """Start summarization in a detached process and return immediately."""
+    root = Path(project_root or Path(__file__).resolve().parents[2])
+    subprocess.Popen(
+        [
+            python_executable,
+            "-m",
+            "server.tools.hooks",
+            "summarize-thread",
+            thread_id,
+        ],
+        cwd=str(root),
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        stdin=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    return {"status": "dispatched", "thread_id": thread_id}
+
+
+def _thread_id_from_hook_payload(payload: str) -> str | None:
+    if not payload.strip():
+        return None
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError:
+        return None
+    for path in (
+        ("tool_input", "thread_id"),
+        ("input", "thread_id"),
+        ("thread_id",),
+    ):
+        value: Any = data
+        for key in path:
+            if not isinstance(value, dict):
+                value = None
+                break
+            value = value.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+def _file_path_from_hook_payload(payload: str) -> str | None:
+    if not payload.strip():
+        return None
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError:
+        return None
+    for path in (
+        ("tool_input", "file_path"),
+        ("tool_input", "path"),
+        ("input", "file_path"),
+        ("input", "path"),
+        ("file_path",),
+        ("path",),
+    ):
+        value: Any = data
+        for key in path:
+            if not isinstance(value, dict):
+                value = None
+                break
+            value = value.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+_MAX_FILE_BYTES = 512 * 1024  # 512 KB — skip larger files to avoid blocking
+
+
+def _extract_code_index_fact(file_path: Path, project_root: Path | None = None) -> str | None:
+    if file_path.suffix not in INDEXABLE_SUFFIXES:
+        return None
+    lowered = file_path.name.lower()
+    if any(part in lowered for part in SKIP_NAME_PARTS):
+        return None
+    try:
+        if file_path.stat().st_size > _MAX_FILE_BYTES:
+            return None
+        lines = file_path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return None
+
+    # Hooks checked before generic components — use[A-Z] names would match component patterns first
+    patterns = [
+        (re.compile(r"^\s*export\s+function\s+(use[A-Z][A-Za-z0-9_]*)\b"), "hook"),
+        (re.compile(r"^\s*function\s+(use[A-Z][A-Za-z0-9_]*)\b"), "hook"),
+        (re.compile(r"^\s*export\s+function\s+([A-Z][A-Za-z0-9_]*)\b"), "component"),
+        (re.compile(r"^\s*function\s+([A-Z][A-Za-z0-9_]*)\b"), "component"),
+        (re.compile(r"^\s*export\s+const\s+([A-Z][A-Za-z0-9_]*)\b"), "component"),
+        (re.compile(r"^\s*const\s+([A-Z][A-Za-z0-9_]*)\b"), "component"),
+        (re.compile(r"^\s*def\s+([A-Za-z_][A-Za-z0-9_]*)\("), "python function"),
+        (re.compile(r"^\s*class\s+([A-Za-z_][A-Za-z0-9_]*)\b"), "class"),
+    ]
+    # Use relative path for portability and token efficiency
+    try:
+        root = project_root or Path.cwd()
+        display_path = file_path.relative_to(root)
+    except ValueError:
+        display_path = file_path  # fallback to absolute if not under project root
+
+    for line_no, line in enumerate(lines, start=1):
+        for pattern, label in patterns:
+            match = pattern.search(line)
+            if match:
+                symbol = match.group(1)
+                return f"{symbol}: {display_path}:{line_no} — {label}"
+    return None
+
+
+def index_code_file_for_active_thread(
+    file_path: str,
+    db: Any | None = None,
+    memory_client: Any | None = None,
+    project_root: Path | str | None = None,
+) -> dict:
+    """Index one touched source file as a compact code_index memory fact."""
+    path = Path(file_path).expanduser()
+    root = Path(project_root).expanduser() if project_root else Path.cwd()
+    fact = _extract_code_index_fact(path, project_root=root)
+    if not fact:
+        return {"status": "skipped", "reason": "no_indexable_symbol"}
+
+    db = db or _get_db()
+    marker = db.get_current_thread_marker()
+    thread_id = marker.get("CurrentThreadId") if marker else None
+    if not thread_id:
+        return {"status": "skipped", "reason": "no_active_thread"}
+
+    memory = memory_client or _get_memory_client()
+    memory_id = memory.index_memory(
+        thread_id=thread_id,
+        fact=fact,
+        metadata={"type": "code_index"},
+    )
+    return {"status": "indexed", "thread_id": thread_id, "memory_id": memory_id, "fact": fact}
+
+
+async def _summarize_thread_cli(thread_id: str) -> None:
+    await summarize_thread(thread_id, db=_get_db())
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="agent101 Claude Code hook helper")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("session-start")
+    sub.add_parser("session-checkpoint")
+    sub.add_parser("post-tool-use-code-index")
+    kill_parser = sub.add_parser("kill-thread-trigger")
+    kill_parser.add_argument("thread_id", nargs="?")
+    summarize_parser = sub.add_parser("summarize-thread")
+    summarize_parser.add_argument("thread_id")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "session-start":
+        # Read cwd from Claude Code's stdin JSON payload and persist it
+        try:
+            raw = sys.stdin.read()
+            if raw.strip():
+                payload = json.loads(raw)
+                cwd = payload.get("cwd") or payload.get("session", {}).get("cwd")
+                if cwd:
+                    from pathlib import Path as _Path
+                    proj_file = _Path.home() / ".tylor" / "current_project.txt"
+                    proj_file.parent.mkdir(parents=True, exist_ok=True)
+                    proj_file.write_text(cwd)
+        except Exception:
+            pass
+        print(session_start_message())
+        return 0
+    if args.command == "session-checkpoint":
+        print(json.dumps(checkpoint_current_thread()))
+        return 0
+    if args.command == "post-tool-use-code-index":
+        file_path = _file_path_from_hook_payload(sys.stdin.read())
+        if not file_path:
+            print(json.dumps({"status": "skipped", "reason": "missing_file_path"}))
+            return 0
+        print(json.dumps(index_code_file_for_active_thread(file_path)))
+        return 0
+    if args.command == "kill-thread-trigger":
+        thread_id = args.thread_id or _thread_id_from_hook_payload(sys.stdin.read())
+        if not thread_id:
+            print(json.dumps({"status": "skipped", "reason": "missing_thread_id"}))
+            return 0
+        print(json.dumps(dispatch_kill_thread_summary(thread_id)))
+        return 0
+    if args.command == "summarize-thread":
+        asyncio.run(_summarize_thread_cli(args.thread_id))
+        return 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/server/tools/personas.py

@@ -0,0 +1,110 @@
+"""
+server/tools/personas.py — persona definition loading for agent orchestration.
+
+Story 3.1 stores personas as structured markdown. This module provides the
+deterministic parser used by Story 3.2 MCP tools.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+
+
+PERSONAS_DIR = Path(__file__).resolve().parents[1] / "personas"
+REQUIRED_PERSONAS = ("analyst", "ceo", "code_agent", "cto")
+
+
+@dataclass(frozen=True)
+class PersonaDefinition:
+    name: str
+    display_name: str
+    role_summary: str
+    communication_style: str
+    ecc_tool_categories: list[str]
+    role_prompt: str
+
+    def summary(self) -> dict:
+        return {
+            "name": self.name,
+            "role_summary": self.role_summary,
+            "ecc_tool_categories": list(self.ecc_tool_categories),
+        }
+
+
+def _section(lines: list[str], heading: str) -> list[str]:
+    start = None
+    marker = f"## {heading}"
+    for idx, line in enumerate(lines):
+        if line.strip() == marker:
+            start = idx + 1
+            break
+    if start is None:
+        return []
+
+    end = len(lines)
+    for idx in range(start, len(lines)):
+        if lines[idx].startswith("## "):
+            end = idx
+            break
+    return [line.rstrip() for line in lines[start:end] if line.strip()]
+
+
+def _parse_ecc_categories(lines: list[str]) -> list[str]:
+    categories: list[str] = []
+    for line in lines:
+        value = line.strip().removeprefix("-").strip().strip("`")
+        if value.startswith("ecc/"):
+            categories.append(value)
+    return categories
+
+
+def load_persona(name: str) -> PersonaDefinition | None:
+    normalized = name.strip().lower().replace("-", "_")
+    if normalized not in REQUIRED_PERSONAS:
+        return None
+
+    path = PERSONAS_DIR / f"{normalized}.md"
+    if not path.exists():
+        return None
+
+    text = path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+    display_name = next(
+        (line.removeprefix("#").strip() for line in lines if line.startswith("# ")),
+        normalized,
+    )
+    role_lines = _section(lines, "Role Description")
+    style_lines = _section(lines, "Communication Style")
+    category_lines = _section(lines, "ECC Tool Categories")
+
+    role_summary = " ".join(role_lines).strip()
+    communication_style = " ".join(style_lines).strip()
+    ecc_tool_categories = _parse_ecc_categories(category_lines)
+    role_prompt = (
+        f"# {display_name}\n\n"
+        f"## Role Description\n{role_summary}\n\n"
+        f"## Communication Style\n{communication_style}\n\n"
+        "## ECC Tool Categories\n"
+        + "\n".join(f"- `{category}`" for category in ecc_tool_categories)
+    )
+
+    return PersonaDefinition(
+        name=normalized,
+        display_name=display_name,
+        role_summary=role_summary,
+        communication_style=communication_style,
+        ecc_tool_categories=ecc_tool_categories,
+        role_prompt=role_prompt,
+    )
+
+
+def load_personas() -> list[PersonaDefinition]:
+    personas = []
+    for name in REQUIRED_PERSONAS:
+        persona = load_persona(name)
+        if persona is not None:
+            personas.append(persona)
+    return personas
+
+
+def list_persona_summaries() -> list[dict]:
+    return [persona.summary() for persona in load_personas()]

package/server/tools/registry.py

@@ -0,0 +1,195 @@
+"""
+server/tools/registry.py — Tier 1 skill registry MCP tools.
+FR36-FR39: load_skill_tools, list_registry.
+
+Story 4.1 implements built-in ECC category loading. Story 4.2 expands this
+to the full registry client for external skill groups.
+"""
+from __future__ import annotations
+import importlib
+import json
+import re
+from pathlib import Path
+
+from mcp.shared.exceptions import McpError
+from mcp.types import ErrorData, INVALID_PARAMS
+
+from ._mcp import mcp
+
+PLUGIN_DIR = Path(__file__).resolve().parents[2]
+REGISTRY_PATH = PLUGIN_DIR / "registry.json"
+
+ECC_GROUPS = {
+    "ecc/web": ("server.tools.ecc.web", ["web_scrape", "web_fetch"]),
+    "ecc/data": ("server.tools.ecc.data", ["dataset_manager", "data_clean", "data_transform"]),
+    "ecc/presentation": ("server.tools.ecc.presentation", ["build_pptx", "build_doc"]),
+    "ecc/diagrams": ("server.tools.ecc.diagrams", ["diagram_gen", "flowchart_gen"]),
+    "ecc/pipeline": ("server.tools.ecc.pipeline", ["pipeline_builder", "pipeline_run"]),
+}
+
+
+def _invalid_category(tool_group: str) -> McpError:
+    return McpError(
+        ErrorData(
+            code=INVALID_PARAMS,
+            message=f"Unknown skill category: {tool_group}",
+        )
+    )
+
+
+def _read_registry() -> dict:
+    if not REGISTRY_PATH.exists():
+        return {"version": "1.0", "skills": []}
+    return json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
+
+
+def _registry_skills() -> list[dict]:
+    data = _read_registry()
+    return data.get("skills", [])
+
+
+def _find_registry_skill(name: str) -> dict | None:
+    normalized = name.strip().lower()
+    for skill in _registry_skills():
+        if skill.get("name", "").strip().lower() == normalized:
+            return skill
+    return None
+
+
+def _task_tokens(task: str) -> set[str]:
+    return set(re.findall(r"[a-z0-9]+", task.lower()))
+
+
+def _skill_keyword_tokens(skill: dict) -> set[str]:
+    tokens: set[str] = set()
+    for keyword in skill.get("keywords") or []:
+        if isinstance(keyword, str):
+            tokens.update(_task_tokens(keyword))
+    return tokens
+
+
+def _native_slash_skill(task: str) -> str | None:
+    stripped = task.strip()
+    if not stripped.startswith("/"):
+        return None
+    command = stripped.split(maxsplit=1)[0][1:].lower()
+    return command or None
+
+
+def _suggestion(skill_name: str) -> dict:
+    return {
+        "matched": True,
+        "skill": skill_name,
+        "action": "suggest",
+        "message": f"You have {skill_name.upper()} in agent101 — want me to use it?",
+        "thread_persistence": True,
+    }
+
+
+import re as _re
+_SAFE_MODULE_RE = _re.compile(r'^server\.tools\.[a-z0-9_.]+$')
+
+
+def _load_module_group(tool_group: str, module_path: str, tools: list[str]) -> dict:
+    if not _SAFE_MODULE_RE.match(module_path):
+        from mcp.server.fastmcp.exceptions import ToolError
+        raise ToolError(
+            f"Unsafe module path '{module_path}' — must match server.tools.<name>"
+        )
+    importlib.import_module(module_path)
+    return {
+        "tool_group": tool_group,
+        "status": "loaded",
+        "tools": sorted(tools),
+    }
+
+
+@mcp.tool()
+def load_skill_tools(tool_group: str) -> dict:
+    """
+    Lazy-load a Tier 2 tool group into the active session manifest.
+    Use when a task matches a specific skill category.
+    Available groups: ecc/web, ecc/data, ecc/presentation, ecc/diagrams, ecc/pipeline.
+
+    Args:
+        tool_group: The tool group path to load (e.g. "ecc/web", "ecc/data").
+    """
+    if tool_group in ECC_GROUPS:
+        module_path, tools = ECC_GROUPS[tool_group]
+        return _load_module_group(tool_group, module_path, tools)
+
+    skill = _find_registry_skill(tool_group)
+    if not skill:
+        raise _invalid_category(tool_group)
+
+    module_path = skill.get("module")
+    tools = skill.get("tools", [])
+    if not module_path or not tools:
+        raise _invalid_category(tool_group)
+
+    return _load_module_group(tool_group, module_path, tools)
+
+
+def detect_registry_skill(task: str, auto_load: bool = False) -> dict:
+    """
+    Detect whether a user task matches an installed agent101 registry skill.
+    Non-matches never import Tier 2 modules, keeping the startup manifest lean.
+
+    Args:
+        task: User task text to evaluate against registry trigger metadata.
+        auto_load: When true, load the matched registry skill's Tier 2 tools.
+    """
+    native_command = _native_slash_skill(task)
+    if native_command and _find_registry_skill(native_command):
+        return {
+            "matched": True,
+            "skill": native_command,
+            "action": "claude_native",
+            "thread_persistence": False,
+        }
+
+    tokens = _task_tokens(task)
+    for skill in _registry_skills():
+        name = skill.get("name", "").strip()
+        if not name or not tokens.intersection(_skill_keyword_tokens(skill)):
+            continue
+
+        if auto_load and skill.get("module") and skill.get("tools"):
+            return {
+                "matched": True,
+                "skill": name,
+                "action": "loaded",
+                "loaded": load_skill_tools(name),
+                "thread_persistence": True,
+            }
+
+        return _suggestion(name)
+
+    return {"matched": False, "action": "none"}
+
+
+@mcp.tool()
+def list_registry() -> dict:
+    """
+    List all installed skills from registry.json with their trigger descriptions.
+    Returns skills sorted by install date descending.
+    """
+    skills = sorted(
+        _registry_skills(),
+        key=lambda skill: skill.get("installed_date", ""),
+        reverse=True,
+    )
+    return {
+        "skills": [
+            {
+                "name": skill.get("name", ""),
+                "trigger_description": skill.get(
+                    "trigger_description",
+                    skill.get("trigger", ""),
+                ),
+                "keywords": list(skill.get("keywords", [])),
+                "tool_count": int(skill.get("tool_count", 0)),
+            }
+            for skill in skills
+        ]
+    }