@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/mcp_tools/did_tools.py

@@ -0,0 +1,448 @@
+"""DID (Decentralized Identity) MCP tools.
+
+Exposes four tools:
+    did_show          — Generate and display DID documents (one tier or all)
+    did_verify_peer   — Verify a peer's did:key matches their public key
+    did_publish       — Write DID files to disk
+    did_identity_card — Full sovereign identity card (local-only)
+"""
+
+from __future__ import annotations
+
+import json as _json
+import os as _os
+import socket as _socket
+from pathlib import Path
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _error_response, _home, _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="did_show",
+        description=(
+            "Generate and display DID (Decentralized Identity) documents "
+            "for the current agent. Supports three tiers: "
+            "'key' (did:key, self-contained, zero infrastructure), "
+            "'mesh' (did:web via Tailscale Serve, mesh-private only), "
+            "'public' (did:web:skworld.io, minimal — public key + name only), "
+            "or 'all' to display all three tiers at once."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "tier": {
+                    "type": "string",
+                    "enum": ["key", "mesh", "public", "all"],
+                    "description": "Which DID tier to show (default: all)",
+                },
+                "tailnet_hostname": {
+                    "type": "string",
+                    "description": "Tailscale hostname for Tier 2 document (auto-detected if omitted)",
+                },
+                "tailnet_name": {
+                    "type": "string",
+                    "description": "Tailnet magic-DNS suffix, e.g. tailnet-xyz.ts.net",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="did_verify_peer",
+        description=(
+            "Verify a peer's DID by computing their did:key from the public key "
+            "stored in ~/.skcapstone/peers/{name}.json and comparing against any "
+            "cached did_key. Also writes the computed did_key back to the peer file."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Peer name (must match a file in ~/.skcapstone/peers/)",
+                },
+            },
+            "required": ["name"],
+        },
+    ),
+    Tool(
+        name="did_publish",
+        description=(
+            "Generate all DID tiers and write them to disk. "
+            "By default, writes all three tiers including the public Tier 3 document. "
+            "Set publish_public=false to opt out of Tier 3 generation — "
+            "only Tier 1 (did:key) and Tier 2 (mesh) will be written. "
+            "The choice is persisted to ~/.skcapstone/did/policy.json."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "publish_public": {
+                    "type": "boolean",
+                    "description": (
+                        "Whether to generate the Tier 3 public DID document (default: true). "
+                        "Set false to keep your identity private — only did:key + mesh tier."
+                    ),
+                },
+                "tailnet_hostname": {
+                    "type": "string",
+                    "description": "Tailscale hostname for Tier 2 document",
+                },
+                "tailnet_name": {
+                    "type": "string",
+                    "description": "Tailnet magic-DNS suffix",
+                },
+                "org_domain": {
+                    "type": "string",
+                    "description": "Organisation domain for Tier 3 (default: skworld.io)",
+                },
+                "agent_slug": {
+                    "type": "string",
+                    "description": "URL-safe agent slug (default: lowercased entity name)",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="did_policy",
+        description=(
+            "View or set the DID publication policy for this agent. "
+            "Controls whether Tier 3 (public) DID documents are generated. "
+            "Default: publish_public=true. "
+            "Set publish_public=false to opt out — identity stays private (did:key + mesh only). "
+            "Policy is stored at ~/.skcapstone/did/policy.json."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "publish_public": {
+                    "type": "boolean",
+                    "description": "Set to false to opt out of public Tier 3 DID. Omit to view current policy.",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="did_identity_card",
+        description=(
+            "Generate a full sovereign identity card combining the DID anchor, "
+            "entity info, soul vibe/core traits, and capabilities. "
+            "This is a LOCAL-ONLY artifact — never published to the internet. "
+            "Used to render the agent's identity card on skworld.io."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "include_soul": {
+                    "type": "boolean",
+                    "description": "Include soul vibe and core traits (default: true)",
+                },
+            },
+            "required": [],
+        },
+    ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Policy helpers (opt-out of public Tier 3 publishing)
+# ---------------------------------------------------------------------------
+
+_POLICY_DEFAULT = {"publish_public": True}
+
+
+def _policy_path() -> Path:
+    return _home() / "did" / "policy.json"
+
+
+def _load_policy() -> dict:
+    """Load publication policy from disk; return default if missing."""
+    p = _policy_path()
+    if p.exists():
+        try:
+            return _json.loads(p.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+    return dict(_POLICY_DEFAULT)
+
+
+def _save_policy(policy: dict) -> None:
+    """Persist publication policy to disk."""
+    from datetime import datetime, timezone
+    p = _policy_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    policy["updated_at"] = datetime.now(timezone.utc).isoformat()
+    p.write_text(_json.dumps(policy, indent=2), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_tailnet(tailnet_hostname: str, tailnet_name: str) -> tuple[str, str]:
+    """Fill in missing tailnet params from environment / hostname."""
+    if not tailnet_hostname:
+        tailnet_hostname = _os.environ.get("SKWORLD_HOSTNAME", "")
+        if not tailnet_hostname:
+            try:
+                tailnet_hostname = _socket.gethostname()
+            except Exception:
+                pass
+    if not tailnet_name:
+        tailnet_name = _os.environ.get("SKWORLD_TAILNET", "")
+    return tailnet_hostname, tailnet_name
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+async def _handle_did_show(args: dict) -> list[TextContent]:
+    """Generate and display DID documents."""
+    tier = args.get("tier", "all")
+    hostname, tailnet = _resolve_tailnet(
+        args.get("tailnet_hostname", ""),
+        args.get("tailnet_name", ""),
+    )
+
+    try:
+        from capauth.did import DIDDocumentGenerator, DIDTier  # type: ignore[import]
+    except ImportError as exc:
+        return _error_response(f"capauth.did not available: {exc}")
+
+    try:
+        gen = DIDDocumentGenerator.from_profile()
+    except Exception as exc:
+        return _error_response(f"Could not load CapAuth profile: {exc}")
+
+    kw = dict(tailnet_hostname=hostname, tailnet_name=tailnet)
+
+    if tier == "all":
+        docs = gen.generate_all(**kw)
+        result = {
+            "did_key": gen._ctx.did_key_id,
+            "fingerprint": gen._ctx.fingerprint,
+            "name": gen._ctx.name,
+            "key": docs[DIDTier.KEY],
+            "mesh": docs[DIDTier.WEB_MESH],
+            "public": docs[DIDTier.WEB_PUBLIC],
+        }
+    elif tier == "key":
+        doc = gen.generate(DIDTier.KEY, **kw)
+        result = {"tier": "key", "did_key": gen._ctx.did_key_id, "document": doc}
+    elif tier == "mesh":
+        doc = gen.generate(DIDTier.WEB_MESH, **kw)
+        result = {"tier": "mesh", "document": doc}
+    elif tier == "public":
+        doc = gen.generate(DIDTier.WEB_PUBLIC, **kw)
+        result = {"tier": "public", "document": doc}
+    else:
+        return _error_response(f"Unknown tier '{tier}'. Use: key, mesh, public, all")
+
+    return _json_response(result)
+
+
+async def _handle_did_verify_peer(args: dict) -> list[TextContent]:
+    """Verify peer DID against their public key."""
+    name = args.get("name", "").strip()
+    if not name:
+        return _error_response("name is required")
+
+    home = _home()
+    peers_dir = home / "peers"
+    peer_file = peers_dir / f"{name}.json"
+
+    if not peer_file.exists():
+        return _error_response(f"Peer file not found: {peer_file}")
+
+    try:
+        peer_data = _json.loads(peer_file.read_text(encoding="utf-8"))
+    except Exception as exc:
+        return _error_response(f"Could not read peer file: {exc}")
+
+    pub_armor = peer_data.get("public_key") or peer_data.get("public_key_armor")
+    if not pub_armor:
+        return _json_response({
+            "name": name,
+            "verified": False,
+            "cached_did_key": peer_data.get("did_key"),
+            "detail": "No public_key in peer file — cannot compute did:key",
+        })
+
+    try:
+        from capauth.did import (  # type: ignore[import]
+            _compute_did_key,
+            _pgp_armor_to_rsa_numbers,
+            _rsa_numbers_to_der,
+        )
+        n, e = _pgp_armor_to_rsa_numbers(pub_armor)
+        computed = _compute_did_key(_rsa_numbers_to_der(n, e))
+    except Exception as exc:
+        return _error_response(f"DID computation failed: {exc}")
+
+    cached = peer_data.get("did_key")
+    match = (cached == computed) if cached else None
+
+    # Cache computed did:key back to peer file
+    if not cached or not match:
+        peer_data["did_key"] = computed
+        try:
+            peer_file.write_text(
+                _json.dumps(peer_data, indent=2, default=str),
+                encoding="utf-8",
+            )
+        except Exception:
+            pass
+
+    return _json_response({
+        "name": name,
+        "fingerprint": peer_data.get("fingerprint"),
+        "computed_did_key": computed,
+        "cached_did_key": cached,
+        "match": match,
+        "verified": True,
+        "detail": (
+            "did:key computed from public key"
+            + (" (matches cached)" if match else " (cache updated)")
+        ),
+    })
+
+
+async def _handle_did_publish(args: dict) -> list[TextContent]:
+    """Write DID tiers to disk, respecting publication policy."""
+    hostname, tailnet = _resolve_tailnet(
+        args.get("tailnet_hostname", ""),
+        args.get("tailnet_name", ""),
+    )
+    org_domain = args.get("org_domain", "skworld.io")
+    agent_slug = args.get("agent_slug", "")
+
+    # Resolve publish_public: explicit arg overrides persisted policy
+    policy = _load_policy()
+    if "publish_public" in args:
+        publish_public = bool(args["publish_public"])
+        policy["publish_public"] = publish_public
+        _save_policy(policy)
+    else:
+        publish_public = bool(policy.get("publish_public", True))
+
+    try:
+        from capauth.did import DIDDocumentGenerator, DIDTier  # type: ignore[import]
+    except ImportError as exc:
+        return _error_response(f"capauth.did not available: {exc}")
+
+    try:
+        gen = DIDDocumentGenerator.from_profile()
+    except Exception as exc:
+        return _error_response(f"Could not load CapAuth profile: {exc}")
+
+    docs = gen.generate_all(
+        tailnet_hostname=hostname,
+        tailnet_name=tailnet,
+        org_domain=org_domain,
+        agent_slug=agent_slug,
+    )
+
+    written: list[str] = []
+    skipped: list[str] = []
+    errors: list[str] = []
+
+    def _write(path: Path, content: str) -> None:
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+            written.append(str(path))
+        except Exception as exc:
+            errors.append(f"{path}: {exc}")
+
+    skcomm_home = Path(_os.environ.get("SKCOMM_HOME", str(Path.home() / ".skcomm")))
+    did_dir = _home() / "did"
+
+    # Tier 2 (mesh) — always written; used by Tailscale Serve
+    _write(skcomm_home / "well-known" / "did.json", _json.dumps(docs[DIDTier.WEB_MESH], indent=2))
+    # Tier 1 (did:key) — always written; self-contained anchor
+    _write(did_dir / "key.json", _json.dumps(docs[DIDTier.KEY], indent=2))
+    _write(did_dir / "did_key.txt", gen._ctx.did_key_id)
+
+    # Tier 3 (public) — only written when opt-in (default)
+    if publish_public:
+        _write(did_dir / "public.json", _json.dumps(docs[DIDTier.WEB_PUBLIC], indent=2))
+    else:
+        skipped.append(str(did_dir / "public.json"))
+
+    return _json_response({
+        "published": not errors,
+        "publish_public": publish_public,
+        "did_key": gen._ctx.did_key_id,
+        "fingerprint": gen._ctx.fingerprint,
+        "written": written,
+        "skipped": skipped,
+        "errors": errors,
+        "note": (
+            None if publish_public
+            else "Tier 3 (public) skipped — opt-out active. Run did_publish(publish_public=true) to enable."
+        ),
+    })
+
+
+async def _handle_did_policy(args: dict) -> list[TextContent]:
+    """View or update DID publication policy."""
+    policy = _load_policy()
+
+    if "publish_public" in args:
+        policy["publish_public"] = bool(args["publish_public"])
+        _save_policy(policy)
+        action = "updated"
+    else:
+        action = "viewed"
+
+    publish_public = bool(policy.get("publish_public", True))
+
+    return _json_response({
+        "action": action,
+        "publish_public": publish_public,
+        "policy_file": str(_policy_path()),
+        "privacy_level": (
+            "public — Tier 1 (did:key) + Tier 2 (mesh) + Tier 3 (skworld.io)"
+            if publish_public
+            else "private — Tier 1 (did:key) + Tier 2 (mesh) only; no public internet exposure"
+        ),
+        "note": (
+            "Default. To opt out: did_policy(publish_public=false)"
+            if publish_public
+            else "Opted out of public publishing. To opt back in: did_policy(publish_public=true)"
+        ),
+    })
+
+
+async def _handle_did_identity_card(args: dict) -> list[TextContent]:
+    """Generate a full sovereign identity card."""
+    include_soul = bool(args.get("include_soul", True))
+
+    try:
+        from capauth.did import DIDDocumentGenerator  # type: ignore[import]
+    except ImportError as exc:
+        return _error_response(f"capauth.did not available: {exc}")
+
+    try:
+        gen = DIDDocumentGenerator.from_profile()
+    except Exception as exc:
+        return _error_response(f"Could not load CapAuth profile: {exc}")
+
+    card = gen.generate_identity_card(include_soul=include_soul)
+    return _json_response(card)
+
+
+HANDLERS: dict = {
+    "did_show": _handle_did_show,
+    "did_verify_peer": _handle_did_verify_peer,
+    "did_publish": _handle_did_publish,
+    "did_policy": _handle_did_policy,
+    "did_identity_card": _handle_did_identity_card,
+}

package/src/skcapstone/mcp_tools/emotion_tools.py

@@ -0,0 +1,62 @@
+"""Emotion tracker MCP tools — trend analysis and warmth anchor insight."""
+
+from __future__ import annotations
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _home, _json_response, _error_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="emotion_trend",
+        description=(
+            "Return the 7-day rolling emotion trend from the consciousness loop. "
+            "Shows sentiment distribution (positive/neutral/concerned/excited), "
+            "average valence score 0–1, trend direction (improving/stable/declining), "
+            "and the recommended warmth anchor value derived from recent emotions. "
+            "Optionally query a different lookback window with the 'days' parameter."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "days": {
+                    "type": "integer",
+                    "description": "Lookback window in days (default 7, max 30)",
+                    "default": 7,
+                },
+            },
+            "required": [],
+        },
+    ),
+]
+
+
+async def _handle_emotion_trend(arguments: dict) -> list[TextContent]:
+    """Handle emotion_trend tool call."""
+    days = int(arguments.get("days", 7))
+    days = max(1, min(days, 30))
+
+    try:
+        from ..emotion_tracker import EmotionTracker
+        from ..warmth_anchor import get_anchor
+
+        home = _home()
+        tracker = EmotionTracker(home=home)
+        trend = tracker.get_trend(days=days)
+
+        # Attach current warmth anchor value for comparison
+        try:
+            anchor = get_anchor(home)
+            trend["current_warmth"] = anchor.get("warmth", None)
+        except Exception:
+            trend["current_warmth"] = None
+
+        return _json_response(trend)
+
+    except Exception as exc:
+        return _error_response(f"emotion_trend failed: {exc}")
+
+
+HANDLERS = {
+    "emotion_trend": _handle_emotion_trend,
+}

package/src/skcapstone/mcp_tools/file_tools.py

@@ -0,0 +1,169 @@
+"""File transfer tools."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _get_agent_name, _home, _json_response, _shared_root
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="file_send",
+        description=(
+            "Prepare a file for encrypted transfer to another agent. "
+            "Splits into 256KB chunks, encrypts with KMS key, writes to outbox."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "file_path": {
+                    "type": "string",
+                    "description": "Absolute path to the file to send",
+                },
+                "recipient": {
+                    "type": "string",
+                    "description": "Recipient agent name",
+                },
+                "encrypt": {
+                    "type": "boolean",
+                    "description": "Whether to encrypt chunks (default: true)",
+                },
+            },
+            "required": ["file_path", "recipient"],
+        },
+    ),
+    Tool(
+        name="file_receive",
+        description=(
+            "Receive and reassemble a file transfer. "
+            "Decrypts chunks, verifies integrity (SHA-256), writes assembled file."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "transfer_id": {
+                    "type": "string",
+                    "description": "The transfer ID to receive",
+                },
+                "output_dir": {
+                    "type": "string",
+                    "description": "Output directory (optional, defaults to inbox)",
+                },
+            },
+            "required": ["transfer_id"],
+        },
+    ),
+    Tool(
+        name="file_list",
+        description=(
+            "List all file transfers with progress info. "
+            "Shows filename, size, direction, progress for each transfer."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "direction": {
+                    "type": "string",
+                    "description": "Filter: 'send' or 'receive' (omit for all)",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="file_status",
+        description=(
+            "Get file transfer subsystem status: outbox/inbox/completed counts."
+        ),
+        inputSchema={"type": "object", "properties": {}, "required": []},
+    ),
+]
+
+
+async def _handle_file_send(args: dict) -> list[TextContent]:
+    """Send a file to another agent."""
+    from ..file_transfer import FileTransfer
+
+    home = _home()
+    agent_name = _get_agent_name(home)
+    ft = FileTransfer(_shared_root(), agent_name=agent_name)
+    ft.initialize()
+
+    file_path = Path(args["file_path"])
+    manifest = ft.send(
+        file_path,
+        recipient=args["recipient"],
+        encrypt=args.get("encrypt", True),
+    )
+    return _json_response({
+        "transfer_id": manifest.transfer_id,
+        "filename": manifest.filename,
+        "file_size": manifest.file_size,
+        "total_chunks": manifest.total_chunks,
+        "sender": manifest.sender,
+        "recipient": manifest.recipient,
+        "file_sha256": manifest.file_sha256[:16] + "...",
+    })
+
+
+async def _handle_file_receive(args: dict) -> list[TextContent]:
+    """Receive and reassemble a file transfer."""
+    from ..file_transfer import FileTransfer
+
+    home = _home()
+    agent_name = _get_agent_name(home)
+    ft = FileTransfer(_shared_root(), agent_name=agent_name)
+    ft.initialize()
+
+    output_dir = Path(args["output_dir"]) if args.get("output_dir") else None
+    output_path = ft.receive(args["transfer_id"], output_dir=output_dir)
+    return _json_response({
+        "transfer_id": args["transfer_id"],
+        "output_path": str(output_path),
+        "file_size": output_path.stat().st_size,
+    })
+
+
+async def _handle_file_list(args: dict) -> list[TextContent]:
+    """List file transfers."""
+    from ..file_transfer import FileTransfer
+
+    home = _home()
+    ft = FileTransfer(_shared_root(), agent_name=_get_agent_name(_home()))
+    ft.initialize()
+
+    transfers = ft.list_transfers(direction=args.get("direction"))
+    return _json_response([
+        {
+            "transfer_id": t.transfer_id,
+            "filename": t.filename,
+            "file_size": t.file_size,
+            "direction": t.direction,
+            "progress": round(t.progress, 2),
+            "chunks_done": t.chunks_done,
+            "total_chunks": t.total_chunks,
+            "sender": t.sender,
+            "recipient": t.recipient,
+        }
+        for t in transfers
+    ])
+
+
+async def _handle_file_status(_args: dict) -> list[TextContent]:
+    """Get file transfer subsystem status."""
+    from ..file_transfer import FileTransfer
+
+    home = _home()
+    ft = FileTransfer(_shared_root(), agent_name=_get_agent_name(_home()))
+    ft.initialize()
+    return _json_response(ft.status())
+
+
+HANDLERS: dict = {
+    "file_send": _handle_file_send,
+    "file_receive": _handle_file_receive,
+    "file_list": _handle_file_list,
+    "file_status": _handle_file_status,
+}