hypermind 0.11.0__py3-none-any.whl

hypermind/mcp/server.py

@@ -0,0 +1,248 @@
+"""MCP server — JSON-RPC 2.0 dispatcher with CapToken-bound provenance.
+
+Accepts a :class:`MCPTransport` and a tool registry view, dispatches
+``initialize`` / ``tools/list`` / ``tools/call`` requests, and enforces
+the T1-03 provenance binding before invoking any tool handler.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from hypermind.mcp.provenance import (
+    ERR_PROVENANCE_MISSING,
+    ERR_PROVENANCE_UNKNOWN_CAP,
+    Provenance,
+    ProvenanceError,
+    compute_cap_token_root,
+    verify_provenance,
+)
+from hypermind.mcp.transport import MCP_SCHEMA_VERSION, MCPTransport
+
+logger = logging.getLogger(__name__)
+
+
+# JSON-RPC 2.0 standard error codes (§5.1).
+ERR_PARSE = -32700
+ERR_INVALID_REQUEST = -32600
+ERR_METHOD_NOT_FOUND = -32601
+ERR_INVALID_PARAMS = -32602
+ERR_INTERNAL = -32603
+
+#: Async handler signature: ``async def handler(params) -> result``.
+ToolHandler = Callable[[dict[str, Any]], Awaitable[Any]]
+
+
+@dataclass
+class ToolDescriptor:
+    """An MCP-visible tool entry."""
+
+    name: str
+    description: str
+    parameters_schema: dict[str, Any]
+    handler: ToolHandler
+
+    def to_mcp_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.parameters_schema,
+        }
+
+
+@dataclass
+class MCPServer:
+    """JSON-RPC 2.0 dispatcher serving a tool registry over an
+    :class:`MCPTransport`.
+
+    Provenance enforcement
+    ----------------------
+    Every ``tools/call`` request MUST carry a ``provenance`` block in
+    its ``params`` (signed Ed25519 over the canonical CBOR of the
+    request body — see :mod:`hypermind.mcp.provenance`). The server
+    rejects calls that:
+
+    1. Omit the provenance block (``-32001``).
+    2. Reference a ``cap_token_root`` not in :attr:`known_cap_roots`
+       (``-32003``).
+    3. Have an invalid signature or mismatched ``request_kid``
+       (``-32002`` / ``-32004``).
+
+    Idempotency
+    -----------
+    A successful ``tools/call`` caches its result keyed by
+    ``request_kid``. Re-receiving the same ``request_kid`` returns the
+    cached result without re-dispatching the handler — closing T1-05's
+    "idempotent retry" requirement.
+    """
+
+    tools: dict[str, ToolDescriptor] = field(default_factory=dict)
+    #: SHA-256 hashes of root CapToken canonical bytes that are
+    #: authorised to call tools on this server. The server checks
+    #: membership only — full CapToken validation happens upstream
+    #: when the cap is registered.
+    known_cap_roots: set[bytes] = field(default_factory=set)
+    #: request_kid -> cached result (for idempotent retries).
+    _idempotency_cache: dict[bytes, Any] = field(default_factory=dict)
+
+    def register_tool(
+        self,
+        name: str,
+        *,
+        description: str,
+        parameters_schema: dict[str, Any],
+        handler: ToolHandler,
+    ) -> None:
+        if name in self.tools:
+            raise ValueError(f"tool {name!r} already registered")
+        self.tools[name] = ToolDescriptor(
+            name=name,
+            description=description,
+            parameters_schema=parameters_schema,
+            handler=handler,
+        )
+
+    def register_cap_root(self, cap_token_bytes: bytes) -> bytes:
+        """Register a CapToken root and return its SHA-256 root hash."""
+        root = compute_cap_token_root(cap_token_bytes)
+        self.known_cap_roots.add(root)
+        return root
+
+    # ---- request loop --------------------------------------------------
+
+    async def serve(self, transport: MCPTransport) -> None:
+        """Service requests until the transport is closed."""
+        try:
+            while True:
+                try:
+                    msg = await transport.recv()
+                except (ConnectionError, asyncio.CancelledError):
+                    return
+                except (ValueError, Exception) as e:
+                    logger.warning("MCP recv error: %s", e)
+                    await self._send_error(transport, None, ERR_PARSE, str(e))
+                    continue
+                await self._dispatch(transport, msg)
+        finally:
+            await transport.close()
+
+    async def _dispatch(self, transport: MCPTransport, msg: dict[str, Any]) -> None:
+        if msg.get("jsonrpc") != "2.0":
+            await self._send_error(
+                transport,
+                msg.get("id"),
+                ERR_INVALID_REQUEST,
+                "jsonrpc field must be '2.0'",
+            )
+            return
+        msg_id = msg.get("id")
+        method = msg.get("method")
+        params = msg.get("params") or {}
+        if not isinstance(method, str):
+            await self._send_error(
+                transport, msg_id, ERR_INVALID_REQUEST, "method must be a string"
+            )
+            return
+        if not isinstance(params, dict):
+            await self._send_error(
+                transport, msg_id, ERR_INVALID_PARAMS, "params must be an object"
+            )
+            return
+        try:
+            result = await self._handle(method, params)
+        except ProvenanceError as e:
+            await self._send_error(transport, msg_id, e.code, e.message)
+            return
+        except _MethodNotFound as e:
+            await self._send_error(transport, msg_id, ERR_METHOD_NOT_FOUND, str(e))
+            return
+        except _InvalidParams as e:
+            await self._send_error(transport, msg_id, ERR_INVALID_PARAMS, str(e))
+            return
+        except Exception as e:
+            logger.exception("MCP handler raised")
+            await self._send_error(transport, msg_id, ERR_INTERNAL, str(e))
+            return
+        await transport.send({"jsonrpc": "2.0", "id": msg_id, "result": result})
+
+    async def _handle(self, method: str, params: dict[str, Any]) -> Any:
+        if method == "initialize":
+            return {
+                "protocolVersion": MCP_SCHEMA_VERSION,
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": {"name": "hypermind-mcp", "version": "0.10.1"},
+            }
+        if method == "tools/list":
+            return {"tools": [t.to_mcp_dict() for t in self.tools.values()]}
+        if method == "tools/call":
+            return await self._handle_tool_call(params)
+        raise _MethodNotFound(f"unknown method {method!r}")
+
+    async def _handle_tool_call(self, params: dict[str, Any]) -> Any:
+        name = params.get("name")
+        if not isinstance(name, str):
+            raise _InvalidParams("tools/call requires 'name' (string)")
+        arguments = params.get("arguments") or {}
+        if not isinstance(arguments, dict):
+            raise _InvalidParams("tools/call 'arguments' must be an object")
+        tool = self.tools.get(name)
+        if tool is None:
+            raise _MethodNotFound(f"unknown tool {name!r}")
+
+        # ---- T1-03: provenance enforcement -----------------------------
+        prov_obj = params.get("provenance")
+        if prov_obj is None:
+            raise ProvenanceError(
+                ERR_PROVENANCE_MISSING,
+                "tools/call requires a 'provenance' object (T1-03)",
+            )
+        provenance = Provenance.from_dict(prov_obj)
+        # The signed body is the params *without* provenance — strip it
+        # before recomputing the request_kid.
+        signed_params = {k: v for k, v in params.items() if k != "provenance"}
+        verify_provenance(
+            method="tools/call",
+            params_without_provenance=signed_params,
+            provenance=provenance,
+        )
+        if provenance.cap_token_root not in self.known_cap_roots:
+            raise ProvenanceError(
+                ERR_PROVENANCE_UNKNOWN_CAP,
+                "cap_token_root is not registered with this server",
+            )
+
+        # ---- T1-05: idempotent retry -----------------------------------
+        cached = self._idempotency_cache.get(provenance.request_kid)
+        if cached is not None:
+            return cached
+        result = await tool.handler(arguments)
+        envelope = {"content": result, "request_kid": provenance.request_kid.hex()}
+        self._idempotency_cache[provenance.request_kid] = envelope
+        return envelope
+
+    @staticmethod
+    async def _send_error(
+        transport: MCPTransport,
+        msg_id: Any,
+        code: int,
+        message: str,
+    ) -> None:
+        await transport.send(
+            {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "error": {"code": code, "message": message},
+            }
+        )
+
+
+class _MethodNotFound(Exception):
+    pass
+
+
+class _InvalidParams(Exception):
+    pass

hypermind/mcp/transport.py

@@ -0,0 +1,206 @@
+"""MCP transport layer — JSON-RPC 2.0 over stdio (and WebSocket, deferred).
+
+Pinned MCP schema version: **MCP v1.0** (`MCP_SCHEMA_VERSION` constant
+below). The JSON-RPC 2.0 envelope on the wire is::
+
+    {"jsonrpc": "2.0", "id": <int|str>, "method": <str>, "params": <obj>}
+
+Replies::
+
+    {"jsonrpc": "2.0", "id": <id>, "result": <obj>}
+    {"jsonrpc": "2.0", "id": <id>, "error": {"code": <int>, "message": <str>}}
+
+Two transports ship in v0.10.1:
+
+- :class:`StdioTransport` — line-delimited JSON over a pair of byte
+  streams (asyncio :class:`asyncio.StreamReader`/:class:`StreamWriter`).
+  Suitable for in-process pipes, subprocess stdin/stdout, and Unix
+  domain sockets wrapped as streams.
+- :class:`WebSocketTransport` — only available when the optional
+  ``websockets`` extra is installed. v0.10.1 ships the class but
+  declares WebSocket support as deferred to v0.10.2 if the dependency
+  is not present at import time. The class itself imports lazily.
+
+Both transports implement the :class:`MCPTransport` Protocol.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Protocol, runtime_checkable
+
+#: MCP schema version this transport speaks. Bound into the
+#: ``initialize`` handshake so peers can negotiate.
+MCP_SCHEMA_VERSION = "1.0"
+
+
+@runtime_checkable
+class MCPTransport(Protocol):
+    """Bidirectional message channel for JSON-RPC 2.0 frames."""
+
+    async def send(self, msg: dict[str, Any]) -> None: ...
+
+    async def recv(self) -> dict[str, Any]: ...
+
+    async def close(self) -> None: ...
+
+
+class StdioTransport:
+    """Line-delimited JSON over an asyncio reader/writer pair.
+
+    Each frame is a single JSON object terminated by ``\\n``. Empty
+    lines and lines that fail to decode are surfaced as
+    :class:`ValueError` from :meth:`recv` so the caller can decide
+    whether to skip or close the channel.
+
+    The transport accepts either a real :class:`asyncio.StreamWriter`
+    or a duck-typed object that exposes ``write(bytes)`` plus async
+    ``drain()`` / ``close()``. The in-memory test pair below uses the
+    duck-typed form to avoid the StreamReaderProtocol handshake that
+    asyncio's real StreamWriter needs.
+    """
+
+    def __init__(
+        self,
+        reader: asyncio.StreamReader,
+        writer: Any,
+    ) -> None:
+        self._reader = reader
+        self._writer = writer
+        self._send_lock = asyncio.Lock()
+        self._closed = False
+
+    async def send(self, msg: dict[str, Any]) -> None:
+        if self._closed:
+            raise ConnectionError("transport closed")
+        line = (json.dumps(msg, separators=(",", ":")) + "\n").encode("utf-8")
+        async with self._send_lock:
+            self._writer.write(line)
+            drain = getattr(self._writer, "drain", None)
+            if drain is not None:
+                result = drain()
+                if asyncio.iscoroutine(result):
+                    await result
+
+    async def recv(self) -> dict[str, Any]:
+        if self._closed:
+            raise ConnectionError("transport closed")
+        line = await self._reader.readline()
+        if not line:
+            raise ConnectionError("peer closed transport")
+        try:
+            obj = json.loads(line.decode("utf-8").rstrip("\n"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as e:
+            raise ValueError(f"non-JSON frame: {e}") from e
+        if not isinstance(obj, dict):
+            raise ValueError("JSON-RPC frame must be a JSON object")
+        return obj
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            close = getattr(self._writer, "close", None)
+            if close is not None:
+                result = close()
+                if asyncio.iscoroutine(result):
+                    await result
+            wait_closed = getattr(self._writer, "wait_closed", None)
+            if wait_closed is not None:
+                result = wait_closed()
+                if asyncio.iscoroutine(result):
+                    await result
+        except (ConnectionError, OSError):
+            pass
+
+    @classmethod
+    def in_memory_pair(cls) -> tuple[StdioTransport, StdioTransport]:
+        """Return two transports connected by a pair of in-memory pipes.
+
+        Useful for unit tests that want JSON-RPC over the real
+        :class:`StdioTransport` code path without spawning a subprocess.
+        """
+        a_reader: asyncio.StreamReader = asyncio.StreamReader()
+        b_reader: asyncio.StreamReader = asyncio.StreamReader()
+        # Side A reads from a_reader, writes feed b_reader (B's input).
+        side_a = cls(a_reader, _ReaderFeederWriter(b_reader))
+        side_b = cls(b_reader, _ReaderFeederWriter(a_reader))
+        return side_a, side_b
+
+
+class _ReaderFeederWriter:
+    """Tiny duck-typed writer that pushes bytes into an asyncio
+    StreamReader on the peer side. Used by
+    :meth:`StdioTransport.in_memory_pair` to wire two transports
+    without spinning up a real protocol/transport pair."""
+
+    def __init__(self, peer_reader: asyncio.StreamReader) -> None:
+        self._peer_reader = peer_reader
+        self._closed = False
+
+    def write(self, data: bytes) -> None:
+        if self._closed:
+            raise ConnectionError("writer closed")
+        self._peer_reader.feed_data(data)
+
+    async def drain(self) -> None:
+        # In-memory: no buffer pressure, drain is a no-op.
+        return None
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._peer_reader.feed_eof()
+
+    async def wait_closed(self) -> None:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# WebSocket transport — optional, deferred to v0.10.2 unless extra installed.
+# ---------------------------------------------------------------------------
+
+
+class WebSocketTransport:
+    """JSON-RPC 2.0 over a single WebSocket connection.
+
+    Requires the optional ``websockets`` dependency. v0.10.1 declares
+    this transport as a deferred capability — the class is importable
+    even without ``websockets`` installed, but instantiation raises
+    ``RuntimeError`` directing the caller to install the extra. The
+    full WebSocket implementation lands in v0.10.2.
+    """
+
+    def __init__(self, ws: Any) -> None:
+        try:
+            import websockets  # noqa: F401
+        except ImportError as e:  # pragma: no cover — env-dependent
+            raise RuntimeError(
+                "WebSocketTransport requires the `websockets` package "
+                "(deferred to v0.10.2; install via `pip install websockets`)"
+            ) from e
+        self._ws = ws
+        self._closed = False
+
+    async def send(self, msg: dict[str, Any]) -> None:  # pragma: no cover
+        if self._closed:
+            raise ConnectionError("transport closed")
+        await self._ws.send(json.dumps(msg, separators=(",", ":")))
+
+    async def recv(self) -> dict[str, Any]:  # pragma: no cover
+        raw = await self._ws.recv()
+        if isinstance(raw, bytes):
+            raw = raw.decode("utf-8")
+        obj = json.loads(raw)
+        if not isinstance(obj, dict):
+            raise ValueError("JSON-RPC frame must be a JSON object")
+        return obj
+
+    async def close(self) -> None:  # pragma: no cover
+        if self._closed:
+            return
+        self._closed = True
+        await self._ws.close()

hypermind/mind/__init__.py

@@ -0,0 +1,150 @@
+"""hypermind.mind — the agent mind.
+
+Adds a deliberation layer on top of HyperMindAgent's primitive verbs
+(publish_claim, dispute, consult, synthesize, checkpoint). The mind is
+strictly *additive*: agents constructed without a Deliberator behave
+exactly as before. Calling ``agent.pursue(goal)`` activates the mind.
+
+Public surface:
+    Goal, GoalQueue                 — what the agent wants to achieve
+    ActionPolicy + built-in policies — how the agent decides
+    Deliberator                     — the loop that turns goals into actions
+    SelfReflector                   — adjusts policy thresholds from track record
+    DiversityGuard                  — blocks correlated synthesis
+    SybilGuard                      — caps influence of new agents
+    LeverageCap                     — bounds claim impact by historical Brier
+
+Every action dispatched by a Deliberator is gated by a CapToken (caveat
+chain) — autonomy is governable, not unbounded.
+
+Spec: docs/spec/19-autonomy-contract.md
+"""
+
+from __future__ import annotations
+
+from hypermind.mind.active import (
+    AgentSnapshot,
+    AntiHerdingTrigger,
+    CandidateQuestion,
+    CurriculumScheduler,
+    GradedQuestion,
+    InformationGainPlanner,
+)
+from hypermind.mind.belief import (
+    BeliefRecord,
+    BeliefRevisionError,
+    BeliefStore,
+    TheoryOfMind,
+)
+from hypermind.mind.deliberator import Deliberator, DeliberatorTick
+from hypermind.mind.diversity import DiversityGuard, EpistemicDependence, QuorumResult
+from hypermind.mind.evolve import BrierFeedback, MentorFollowing, SelfReflector
+from hypermind.mind.federation import (
+    FederationPolicy,
+    assert_never_merge,
+    auto_relay,
+)
+from hypermind.mind.goals import Goal, GoalOutcome, GoalQueue, GoalStatus
+from hypermind.mind.mediator import MediatorSelector, select_mediator
+from hypermind.mind.policy import (
+    ActionDecision,
+    ActionKind,
+    ActionPolicy,
+    CheckpointOnSignalGain,
+    ConsultOnDisagreement,
+    DisputeOnContradiction,
+    LeverageCap,
+    NoOpPolicy,
+    PolicyContext,
+    PublishWhenConfident,
+    select_top_decision,
+)
+from hypermind.mind.records import (
+    DissentRecord,
+    IntentRecord,
+    TraceRecord,
+    decode_mind_record,
+    encode_mind_record,
+)
+from hypermind.mind.roles import (
+    Role,
+    RoleKind,
+    SwarmComposition,
+    generalist,
+    mediator,
+    oracle,
+    role_by_name,
+    sceptic,
+    scout,
+    synthesist,
+)
+from hypermind.mind.sybil_guard import SybilGuard
+from hypermind.mind.world_model import (
+    BetaWorldModel,
+    ImaginedOutcome,
+    LookaheadPolicy,
+    WorldModel,
+    update_world_model_from_resolution,
+)
+
+__all__ = [
+    "ActionDecision",
+    "ActionKind",
+    "ActionPolicy",
+    "AgentSnapshot",
+    "AntiHerdingTrigger",
+    "BeliefRecord",
+    "BeliefRevisionError",
+    "BeliefStore",
+    "BetaWorldModel",
+    "BrierFeedback",
+    "CandidateQuestion",
+    "CheckpointOnSignalGain",
+    "ConsultOnDisagreement",
+    "CurriculumScheduler",
+    "Deliberator",
+    "DeliberatorTick",
+    "DisputeOnContradiction",
+    "DissentRecord",
+    "DiversityGuard",
+    "EpistemicDependence",
+    "FederationPolicy",
+    "Goal",
+    "GoalOutcome",
+    "GoalQueue",
+    "GoalStatus",
+    "GradedQuestion",
+    "ImaginedOutcome",
+    "InformationGainPlanner",
+    "IntentRecord",
+    "LeverageCap",
+    "LookaheadPolicy",
+    "MediatorSelector",
+    "MentorFollowing",
+    "NoOpPolicy",
+    "PolicyContext",
+    "PublishWhenConfident",
+    "QuorumResult",
+    "Role",
+    "RoleKind",
+    "SelfReflector",
+    "SwarmComposition",
+    "SybilGuard",
+    "TheoryOfMind",
+    "TraceRecord",
+    "WorldModel",
+    "assert_never_merge",
+    "auto_relay",
+    "decode_mind_record",
+    "encode_mind_record",
+    "generalist",
+    "mediator",
+    "oracle",
+    "role_by_name",
+    "sceptic",
+    "scout",
+    "select_mediator",
+    "select_top_decision",
+    "synthesist",
+    "update_world_model_from_resolution",
+]