tylor-mcp 1.0.0

package/server/ui_server.py

@@ -0,0 +1,292 @@
+"""
+server/ui_server.py — aiohttp web server for the Thread Visualizer UI.
+
+Serves static UI files, REST endpoints for thread data, and a WebSocket
+endpoint for real-time thread state updates.
+
+Architecture: shares the asyncio event loop with FastMCP (started as a
+concurrent task in server/main.py). Never blocks the MCP control plane.
+"""
+from __future__ import annotations
+import asyncio
+import errno
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Set
+
+from aiohttp import web, WSMsgType
+
+_THREAD_ID_RE = re.compile(r"^[a-zA-Z0-9_-]{3,64}$")
+
+logger = logging.getLogger(__name__)
+
+UI_DIR = Path(__file__).parent.parent / "ui"
+PORT = 8765          # updated to the actual bound port on startup
+PORT_RANGE = (8765, 8775)  # try these ports in order
+
+# ── Global state ────────────────────────────────────────────────────────────
+# Shared across the process lifetime; safe because asyncio is single-threaded.
+ui_available: bool = False
+_seq: int = 0  # monotonic broadcast sequence counter
+
+
+# ── WebSocket manager ────────────────────────────────────────────────────────
+
+class WsManager:
+    """Registry of connected WebSocket clients with fan-out broadcast."""
+
+    def __init__(self) -> None:
+        self._clients: Set[web.WebSocketResponse] = set()
+
+    def connect(self, ws: web.WebSocketResponse) -> None:
+        self._clients.add(ws)
+
+    def disconnect(self, ws: web.WebSocketResponse) -> None:
+        self._clients.discard(ws)
+
+    async def broadcast(self, payload: dict) -> None:
+        """Send payload to all connected clients. Slow/closed clients are dropped."""
+        global _seq
+        _seq += 1
+        # Copy to avoid mutating the caller's dict
+        outbound = {**payload, "seq": _seq}
+        text = json.dumps(outbound)
+
+        dead: list[web.WebSocketResponse] = []
+        for ws in list(self._clients):
+            if ws.closed:
+                dead.append(ws)
+                continue
+            try:
+                await asyncio.wait_for(ws.send_str(text), timeout=0.5)
+            except Exception:
+                dead.append(ws)
+        for ws in dead:
+            self._clients.discard(ws)
+
+    @property
+    def count(self) -> int:
+        return len(self._clients)
+
+
+# Module-level singleton — imported by tools that need to broadcast.
+ws_manager = WsManager()
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+def _fetch_threads() -> list[dict]:
+    """Fetch current thread list from storage. Returns [] on any error."""
+    try:
+        from .tools.tylor import list_threads
+        result = list_threads()
+        raw = result.get("threads", [])
+        return [
+            {
+                "id":            t.get("thread_id", ""),
+                "title":         t.get("name", ""),
+                "status":        t.get("status", "idle"),
+                "created_at":    t.get("last_activity", ""),
+                "message_count": t.get("message_count", 0),
+                "project":       t.get("project", ""),
+            }
+            for t in raw
+        ]
+    except Exception as exc:
+        logger.warning("ui_server: could not fetch threads: %s", exc)
+        return []
+
+
+def _group_threads_by_project(threads: list[dict]) -> list[dict]:
+    """Group flat thread list into project buckets for the UI."""
+    from collections import OrderedDict
+    buckets: OrderedDict = OrderedDict()
+    for t in threads:
+        proj = t.get("project") or "default"
+        if proj not in buckets:
+            buckets[proj] = []
+        buckets[proj].append(t)
+    return [
+        {"id": name, "name": name, "threads": ts}
+        for name, ts in buckets.items()
+    ]
+
+
+def _fetch_messages(thread_id: str, limit: int = 50, before: str | None = None) -> list[dict]:
+    """Fetch the last `limit` messages for a thread, optionally before a timestamp.
+
+    `before` is an ISO timestamp string (CreatedAt of the oldest message already
+    shown in the UI). Only messages strictly older than `before` are returned,
+    enabling "load earlier" pagination without re-fetching the same items.
+    """
+    try:
+        from .tools.tylor import _get_db
+        db = _get_db()
+        prefix = f"THREAD#{thread_id}#MSG#"
+        items = db.query_all(prefix)
+        items.sort(key=lambda i: i.get("SK", ""))
+        if before:
+            items = [i for i in items if i.get("CreatedAt", "") < before]
+        tail = items[-limit:]
+        return [
+            {
+                "role":      i.get("Role", "unknown"),
+                "content":   i.get("Content", ""),
+                "timestamp": i.get("CreatedAt", ""),
+            }
+            for i in tail
+        ]
+    except Exception as exc:
+        logger.warning("ui_server: could not fetch messages for %s: %s", thread_id, exc)
+        return []
+
+
+def _fetch_current_thread_id() -> str | None:
+    """Return the ID of the currently active thread, or None."""
+    try:
+        from .tools.tylor import _get_db
+        db = _get_db()
+        marker = db.get_current_thread_marker()
+        return marker.get("CurrentThreadId") if marker else None
+    except Exception:
+        return None
+
+
+async def thread_update_payload() -> dict:
+    """Build the standard thread_update broadcast payload."""
+    threads = _fetch_threads()
+    current_id = _fetch_current_thread_id()
+    return {
+        "type":             "thread_update",
+        "projects":         _group_threads_by_project(threads),
+        "current_thread_id": current_id,
+    }
+
+
+# ── Route handlers ───────────────────────────────────────────────────────────
+
+async def handle_index(request: web.Request) -> web.Response:
+    index = UI_DIR / "index.html"
+    if not index.exists():
+        return web.Response(status=404, text="UI not built — run: cd ui && npm run build")
+    # Inject the actual bound port so API/WS URLs are always correct,
+    # even when the server falls back to a non-default port (e.g. 8766).
+    html = index.read_text(encoding="utf-8")
+    html = html.replace(
+        "const API = 'http://localhost:8765'",
+        f"const API = 'http://localhost:{PORT}'"
+    ).replace(
+        "const WS  = 'ws://localhost:8765/ws/threads'",
+        f"const WS  = 'ws://localhost:{PORT}/ws/threads'"
+    )
+    return web.Response(text=html, content_type="text/html",
+                        headers={"Cache-Control": "no-store"})
+
+
+async def handle_threads(request: web.Request) -> web.Response:
+    loop = asyncio.get_running_loop()
+    threads = await loop.run_in_executor(None, _fetch_threads)
+    projects = _group_threads_by_project(threads)
+    current_id = await loop.run_in_executor(None, _fetch_current_thread_id)
+    return web.json_response({"projects": projects, "current_thread_id": current_id})
+
+
+async def handle_thread_messages(request: web.Request) -> web.Response:
+    thread_id = request.match_info["thread_id"]
+    if not _THREAD_ID_RE.match(thread_id):
+        return web.json_response({"error": "invalid thread_id"}, status=400)
+    before = request.rel_url.query.get("before") or None
+    loop = asyncio.get_running_loop()
+    messages = await loop.run_in_executor(None, _fetch_messages, thread_id, 50, before)
+    return web.json_response(messages)
+
+
+async def handle_websocket(request: web.Request) -> web.WebSocketResponse:
+    ws = web.WebSocketResponse(heartbeat=30)
+    await ws.prepare(request)
+
+    ws_manager.connect(ws)
+    logger.debug("ui_server: WS client connected (total=%d)", ws_manager.count)
+
+    # Send full thread state immediately on connect (seq=0 = initial snapshot)
+    loop = asyncio.get_running_loop()
+    threads_now = await loop.run_in_executor(None, _fetch_threads)
+    initial = {"type": "thread_update", "projects": _group_threads_by_project(threads_now), "seq": 0}
+    await ws.send_str(json.dumps(initial))
+
+    try:
+        async for msg in ws:
+            if msg.type == WSMsgType.PING:
+                await ws.pong(msg.data)
+            elif msg.type in (WSMsgType.CLOSE, WSMsgType.ERROR):
+                break
+    finally:
+        ws_manager.disconnect(ws)
+        logger.debug("ui_server: WS client disconnected (total=%d)", ws_manager.count)
+
+    return ws
+
+
+# ── App factory ──────────────────────────────────────────────────────────────
+
+def _make_app() -> web.Application:
+    app = web.Application()
+    app.router.add_get("/",                            handle_index)
+    app.router.add_get("/api/threads",                 handle_threads)
+    app.router.add_get("/api/threads/{thread_id}/messages", handle_thread_messages)
+    app.router.add_get("/ws/threads",                  handle_websocket)
+
+    # Serve static assets from ui/ (dist/ when built, raw files in dev)
+    if UI_DIR.exists():
+        app.router.add_static("/", UI_DIR, show_index=False, follow_symlinks=False)
+
+    return app
+
+
+# ── Startup / shutdown ───────────────────────────────────────────────────────
+
+async def start_ui_server() -> web.AppRunner | None:
+    """
+    Start the aiohttp UI server, trying PORT_RANGE in order until one binds.
+    Updates the module-level PORT to the actual bound port.
+    Returns the AppRunner on success, None if all ports are unavailable.
+    Sets module-level `ui_available` accordingly.
+    """
+    global ui_available, PORT
+
+    app = _make_app()
+    runner = web.AppRunner(app, access_log=None)
+    await runner.setup()
+
+    for candidate in range(PORT_RANGE[0], PORT_RANGE[1]):
+        site = web.TCPSite(runner, "localhost", candidate)
+        try:
+            await site.start()
+            PORT = candidate
+            ui_available = True
+            logger.info("ui_server: Thread Visualizer running at http://localhost:%d", PORT)
+            return runner
+        except OSError as exc:
+            if exc.errno == errno.EADDRINUSE:
+                logger.debug("ui_server: port %d in use, trying next…", candidate)
+                continue
+            # Non-EADDRINUSE error — give up immediately
+            await runner.cleanup()
+            ui_available = False
+            logger.warning(
+                "ui_server: could not start on port %d (%s) — Thread Visualizer unavailable.",
+                candidate, exc,
+            )
+            return None
+
+    # All ports exhausted
+    await runner.cleanup()
+    ui_available = False
+    logger.warning(
+        "ui_server: all ports %d–%d in use — Thread Visualizer unavailable. "
+        "MCP tools continue to work normally.",
+        PORT_RANGE[0], PORT_RANGE[1] - 1,
+    )
+    return None

package/server/validate.py

@@ -0,0 +1,237 @@
+"""
+Story 1.2: AWS Connectivity & Credential Validation
+Each check_*() returns (passed: bool, message: str).
+run_all() prints results and returns the count of failed AWS checks.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import urllib.request
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Colour helpers (ANSI — safe on macOS/Linux terminals)
+# ---------------------------------------------------------------------------
+GREEN  = "\033[0;32m"
+RED    = "\033[0;31m"
+YELLOW = "\033[1;33m"
+NC     = "\033[0m"
+
+def _ok(msg: str) -> str:
+    return f"  {GREEN}✓{NC}  {msg}"
+
+def _fail(msg: str) -> str:
+    return f"  {RED}✗{NC}  {msg}"
+
+def _warn(msg: str) -> str:
+    return f"  {YELLOW}⚠{NC}   {msg}"
+
+
+# ---------------------------------------------------------------------------
+# IAM action extraction helper
+# ---------------------------------------------------------------------------
+_IAM_RE = re.compile(r"(dynamodb:\w+|s3:\w+|bedrock:\w+|iam:\w+|sts:\w+)")
+
+def _extract_iam_action(error_message: str, fallback: str) -> str:
+    m = _IAM_RE.search(error_message)
+    return m.group(1) if m else fallback
+
+
+# ---------------------------------------------------------------------------
+# Individual service checks
+# ---------------------------------------------------------------------------
+
+def check_dynamodb() -> tuple[bool, str]:
+    """Test DynamoDB connectivity using list_tables."""
+    try:
+        import boto3  # noqa: PLC0415
+        from botocore.exceptions import ClientError, NoCredentialsError  # noqa: PLC0415
+
+        boto3.client("dynamodb").list_tables(Limit=1)
+        return True, _ok("DynamoDB")
+    except ImportError:
+        return False, _fail("DynamoDB — boto3 not installed")
+    except Exception as exc:  # noqa: BLE001
+        try:
+            from botocore.exceptions import ClientError, NoCredentialsError  # noqa: PLC0415
+
+            if isinstance(exc, NoCredentialsError):
+                return False, _fail("DynamoDB — no AWS credentials found")
+            if isinstance(exc, ClientError):
+                code = exc.response["Error"]["Code"]
+                msg  = exc.response["Error"]["Message"]
+                action = _extract_iam_action(msg, code)
+                return False, _fail(f"DynamoDB — missing permission: {action}")
+        except ImportError:
+            pass
+        return False, _fail(f"DynamoDB — {exc}")
+
+
+def check_s3() -> tuple[bool, str]:
+    """Test S3 connectivity using list_buckets."""
+    try:
+        import boto3  # noqa: PLC0415
+        from botocore.exceptions import ClientError, NoCredentialsError  # noqa: PLC0415
+
+        boto3.client("s3").list_buckets()
+        return True, _ok("S3")
+    except ImportError:
+        return False, _fail("S3 — boto3 not installed")
+    except Exception as exc:  # noqa: BLE001
+        try:
+            from botocore.exceptions import ClientError, NoCredentialsError  # noqa: PLC0415
+
+            if isinstance(exc, NoCredentialsError):
+                return False, _fail("S3 — no AWS credentials found")
+            if isinstance(exc, ClientError):
+                code = exc.response["Error"]["Code"]
+                msg  = exc.response["Error"]["Message"]
+                action = _extract_iam_action(msg, code)
+                return False, _fail(f"S3 — missing permission: {action}")
+        except ImportError:
+            pass
+        return False, _fail(f"S3 — {exc}")
+
+
+def check_bedrock() -> tuple[bool, str]:
+    """Test Bedrock connectivity using list_foundation_models (us-east-1 only)."""
+    try:
+        import boto3  # noqa: PLC0415
+        from botocore.exceptions import ClientError, NoCredentialsError  # noqa: PLC0415
+
+        # Architecture mandates us-east-1 for Bedrock — hard-coded intentionally.
+        boto3.client("bedrock", region_name="us-east-1").list_foundation_models()
+        return True, _ok("Bedrock")
+    except ImportError:
+        return False, _fail("Bedrock — boto3 not installed")
+    except Exception as exc:  # noqa: BLE001
+        try:
+            from botocore.exceptions import ClientError, NoCredentialsError  # noqa: PLC0415
+
+            if isinstance(exc, NoCredentialsError):
+                return False, _fail("Bedrock — no AWS credentials found")
+            if isinstance(exc, ClientError):
+                code = exc.response["Error"]["Code"]
+                msg  = exc.response["Error"]["Message"]
+                action = _extract_iam_action(msg, code)
+                return False, _fail(f"Bedrock — missing permission: {action}")
+        except ImportError:
+            pass
+        return False, _fail(f"Bedrock — {exc}")
+
+
+def check_opensearch(host: str = "", port: str = "9200") -> tuple[bool, str]:
+    """
+    Test OpenSearch cluster health via HTTP GET.
+    Returns (True, advisory_warn_msg) when host is not configured — skipped is not an error.
+    """
+    if not host:
+        return True, _warn("OpenSearch — not configured (skipped)")
+
+    url = f"http://{host}:{port}/_cluster/health"
+    try:
+        urllib.request.urlopen(url, timeout=5)  # noqa: S310
+        return True, _ok("OpenSearch")
+    except Exception as exc:  # noqa: BLE001
+        return False, _fail(f"OpenSearch — {exc}")
+
+
+def check_platform_key(plugin_dir: str | Path = "") -> tuple[bool, str]:
+    """
+    Check for ANTHROPIC_PLATFORM_AWS_API_KEY — non-fatal, always returns True.
+    Resolution order: env var → plugin_dir/.env file.
+    """
+    key = os.environ.get("ANTHROPIC_PLATFORM_AWS_API_KEY", "")
+
+    if not key and plugin_dir:
+        env_file = Path(plugin_dir) / ".env"
+        if env_file.exists():
+            for line in env_file.read_text().splitlines():
+                if line.startswith("ANTHROPIC_PLATFORM_AWS_API_KEY="):
+                    key = line.split("=", 1)[1].strip()
+                    break
+
+    if not key:
+        return True, _warn(
+            "ANTHROPIC_PLATFORM_AWS_API_KEY not set — token overflow fallback disabled.\n"
+            "     Set it in ~/.agent101/config.json or .env to enable Claude Platform on AWS fallback."
+        )
+    return True, _ok("ANTHROPIC_PLATFORM_AWS_API_KEY present")
+
+
+# ---------------------------------------------------------------------------
+# OpenSearch host resolution
+# ---------------------------------------------------------------------------
+
+def _resolve_opensearch_host() -> tuple[str, str]:
+    """
+    Resolution order:
+    1. ~/.agent101/config.json → OPENSEARCH_HOST / OPENSEARCH_PORT
+    2. Environment variables OPENSEARCH_HOST / OPENSEARCH_PORT
+    3. Empty string → caller interprets as "not configured"
+    """
+    config_path = Path.home() / ".agent101" / "config.json"
+    config: dict = {}
+    if config_path.exists():
+        try:
+            config = json.loads(config_path.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    host = config.get("OPENSEARCH_HOST") or os.environ.get("OPENSEARCH_HOST", "")
+    port = config.get("OPENSEARCH_PORT") or os.environ.get("OPENSEARCH_PORT", "9200")
+    return host, str(port)
+
+
+# ---------------------------------------------------------------------------
+# run_all — called by install.sh
+# ---------------------------------------------------------------------------
+
+def run_all(plugin_dir: str = "") -> int:
+    """
+    Run all service checks, print results, return count of failed AWS checks.
+    OpenSearch skips and platform key warnings do NOT increment the error count.
+    """
+    print(f"\n\033[1mValidating AWS connectivity\033[0m")
+
+    aws_errors = 0
+
+    for check_fn in (check_dynamodb, check_s3, check_bedrock):
+        passed, message = check_fn()
+        print(message)
+        if not passed:
+            aws_errors += 1
+
+    host, port = _resolve_opensearch_host()
+    passed, message = check_opensearch(host, port)
+    print(message)
+    if not passed:
+        aws_errors += 1
+
+    # Platform key — non-fatal, never increments aws_errors
+    _, message = check_platform_key(plugin_dir)
+    print(message)
+
+    if aws_errors > 0:
+        print(
+            f"\n  {YELLOW}⚠{NC}   AWS validation: {aws_errors} service(s) unreachable. "
+            "Personal mode features require working AWS credentials.\n"
+            "     Fix credentials then re-run ./install.sh"
+        )
+
+    return aws_errors
+
+
+# ---------------------------------------------------------------------------
+# Entry point — called by install.sh as:
+#   python3 "$PLUGIN_DIR/server/validate.py" "$PLUGIN_DIR"
+# Always exits 0 (advisory only).
+# ---------------------------------------------------------------------------
+if __name__ == "__main__":
+    plugin_dir = sys.argv[1] if len(sys.argv) > 1 else ""
+    run_all(plugin_dir)
+    sys.exit(0)

package/skills/add-skill/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: add-skill
+description: Install an agent101 skill package by copying it into skills/ and generating a registry.json entry.
+---
+
+# /add-skill
+
+Use when the user invokes `/add-skill` or asks to install a skill package into agent101.
+
+## Workflow
+
+1. Ask for the source path if the user did not provide it.
+2. Ask for the skill name if it cannot be inferred from the package `SKILL.md`.
+3. If the skill already exists, prompt the user to confirm overwrite before proceeding.
+4. Run the installer module:
+
+```text
+python3 -m server.tools.skill_installer <source_path> [--name <name>] [--overwrite]
+```
+
+5. Confirm the generated `registry.json` entry and install location.
+
+## Error Handling
+
+Use this recovery format exactly.
+
+If the installer fails, respond with:
+
+```text
+Failed operation: add_skill
+Reason: <installer error>
+Recovery steps:
+- Verify the source path is a directory.
+- Verify the source directory contains SKILL.md.
+- If the skill already exists, rerun only after confirming overwrite.
+- Check registry.json remains valid JSON.
+```

package/skills/afk-status/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: afk-status
+description: Report current AFK execution progress for the active thread.
+---
+
+# /afk-status
+
+Use when the developer invokes `/afk-status` or asks whether an AFK session is running.
+
+Call the `afk_status` Tier 1 tool with the active thread unless the user supplies a specific thread id.
+
+If no session is active, show the tool message exactly:
+
+`No AFK session running`
+
+If a session is active, report:
+- current step
+- steps completed / total
+- elapsed time
+- last command output

package/skills/bmad/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: bmad
+description: Use when the user wants to create a PRD, review stories, or run BMAD workflows.
+module: server.tools.ecc.web
+tools: ["web_fetch", "web_scrape"]
+---
+
+# /bmad
+
+Use when the user wants to create a PRD, review stories, or run BMAD workflows.
+
+This skill package registers the BMAD workflow metadata for automatic detection and lazy-loaded ECC tool usage.
+
+Call `load_skill_tools("bmad")` when this trigger matches.

package/skills/help-agent101/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: help-agent101
+description: Show a current structured listing of agent101 commands, tools, skills, personas, and ECC categories.
+---
+
+# /help-agent101
+
+Use when the user invokes `/help-agent101` or asks what agent101 can do.
+
+## Workflow
+
+1. Call `help_agent101` to get the current capability index.
+2. Present the result in these sections:
+   - Slash commands
+   - Tier 1 MCP tools
+   - Registered skill packages
+   - Available personas
+   - ECC tool categories
+3. Keep the output concise. Include command/tool names and one-line descriptions only.
+4. If the user asks for installed skills specifically, call `list_registry`.
+5. If the user asks for personas specifically, call `list_personas`.
+
+## Required Coverage
+
+The slash-command section must include:
+
+- `/new-thread`
+- `/switch-thread`
+- `/kill-thread`
+- `/list-threads`
+- `/recall`
+- `/add-skill`
+- `/open-threads-ui`
+
+## Error Handling
+
+Use this recovery format exactly.
+
+If capability discovery fails, respond with:
+
+```text
+Failed operation: help_agent101
+Reason: <tool error>
+Recovery steps:
+- Try `list_registry` to inspect installed skills.
+- Try `list_personas` to inspect available personas.
+- Check registry.json remains valid JSON.
+```

package/skills/kill-thread/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: kill-thread
+description: Close an agent101 thread with kill_thread and confirm that async summarization has started.
+---
+
+# /kill-thread
+
+Use when the user invokes `/kill-thread` or asks to close, kill, archive, or summarize a Tylor thread.
+
+## Workflow
+
+1. If the user did not provide a thread ID, call `list_threads()` and ask which active thread to kill.
+2. Call `kill_thread(thread_id: str)`.
+3. Show a formatted confirmation:
+
+```text
+Killing thread: <thread_id>
+Status: killing
+Message: Summarization in progress
+```
+
+## Error Handling
+
+Use this recovery format exactly.
+
+If the tool fails, respond with:
+
+```text
+Failed operation: kill_thread
+Reason: <tool error>
+Recovery steps:
+- Run /list-threads and verify the thread ID.
+- Retry /kill-thread with an active thread ID.
+- If summarization fails later, the fallback summary will store raw last messages.
+```