marcus-toolkit 0.1.0__py3-none-any.whl

marcus_toolkit/client.py

@@ -0,0 +1,319 @@
+"""
+A minimal MCP-over-HTTP client for run-side tooling.
+
+Lifted from ``dev-tools/experiments/runners/marcus_client.py`` in the Marcus
+repository, which the Minecraft plumbing loaded by absolute file path from two
+scripts. The transport (``urllib``) lives in :class:`MarcusMCPClient`; the SSE
+envelope parsing is pure and unit-testable without a server.
+
+Two additions. :meth:`MarcusMCPClient.call` raises instead of returning
+``None``, for callers that must read back every reply body rather than infer
+success from silence. And the handshake speaks the current protocol: it offers
+version 2025-03-26 (what the Node client sends), keeps the version the server
+answers with, sends it as ``MCP-Protocol-Version`` on every later request, and
+records why a connect or call failed in ``last_error``. The first CI run of the
+live check failed at connect against a server built on a newer ``mcp`` package
+than the development machine's, and said nothing about why.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+_DEFAULT_MARCUS_URL = "http://127.0.0.1:4298/mcp/"
+#: The protocol version offered on initialize; the server answers with its own.
+PROTOCOL_VERSION = "2025-03-26"
+
+
+class MarcusClientError(RuntimeError):
+    """A tool call that produced no readable reply."""
+
+
+def parse_mcp_envelopes(raw: bytes) -> list[dict[str, Any]]:
+    """
+    Read every JSON-RPC envelope out of an SSE or plain-JSON response body.
+
+    Parameters
+    ----------
+    raw : bytes
+        The raw HTTP response body.
+
+    Returns
+    -------
+    List[Dict[str, Any]]
+        The envelopes in order; empty when none parse.
+    """
+    text = raw.decode(errors="replace")
+    envelopes: list[dict[str, Any]] = []
+    saw_data = False
+    for line in text.splitlines():
+        if not line.startswith("data:"):
+            continue
+        saw_data = True
+        try:
+            parsed = json.loads(line[len("data:") :].strip())
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            envelopes.append(parsed)
+    if not saw_data and text.strip().startswith("{"):
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError:
+            return envelopes
+        if isinstance(parsed, dict):
+            envelopes.append(parsed)
+    return envelopes
+
+
+def parse_mcp_tool_result(raw: bytes) -> dict[str, Any] | None:
+    """
+    Parse an MCP ``tools/call`` HTTP response into its structured result.
+
+    The tool's own return value sits at ``result.structuredContent.result``.
+
+    Parameters
+    ----------
+    raw : bytes
+        The raw HTTP response body.
+
+    Returns
+    -------
+    Optional[Dict[str, Any]]
+        The tool's structured result, or ``None`` if none is present.
+    """
+    for envelope in parse_mcp_envelopes(raw):
+        result = envelope.get("result")
+        if not isinstance(result, dict):
+            continue
+        structured = result.get("structuredContent")
+        if isinstance(structured, dict):
+            inner = structured.get("result")
+            if isinstance(inner, dict):
+                return inner
+    return None
+
+
+class MarcusMCPClient:
+    """
+    Reusable MCP-over-HTTP client for one Marcus server.
+
+    Call :meth:`connect` once, then :meth:`call_tool` or :meth:`call` as often
+    as needed; the session id from the handshake is reused.
+
+    Parameters
+    ----------
+    marcus_url : str
+        The Marcus MCP HTTP endpoint. A trailing slash is forced: a POST to
+        ``/mcp`` without one gets a 307 that ``urllib`` will not replay.
+    timeout : float
+        Per-request timeout in seconds.
+    """
+
+    def __init__(
+        self, marcus_url: str = _DEFAULT_MARCUS_URL, timeout: float = 10.0
+    ) -> None:
+        self._url = marcus_url.rstrip("/") + "/"
+        self._timeout = timeout
+        self._session_id: str = ""
+        self._protocol_version: str = ""
+        self._request_id = 0
+        #: Why the last connect or call failed, for a record that must say so.
+        self.last_error: str = ""
+
+    @property
+    def url(self) -> str:
+        """Return the endpoint this client posts to."""
+        return self._url
+
+    @property
+    def connected(self) -> bool:
+        """Return True once :meth:`connect` has established a session."""
+        return bool(self._session_id)
+
+    @property
+    def protocol_version(self) -> str:
+        """Return the protocol version the server answered with, once connected."""
+        return self._protocol_version
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        }
+        if self._session_id:
+            headers["mcp-session-id"] = self._session_id
+        if self._protocol_version:
+            headers["MCP-Protocol-Version"] = self._protocol_version
+        return headers
+
+    def _send(self, payload: dict[str, Any]) -> tuple[str, bytes]:
+        """
+        POST once, following a 307 or 308 with the same method and body.
+
+        Older servers redirect ``/mcp`` to ``/mcp/``; newer ones redirect the other
+        way. ``urllib`` refuses to replay a POST through a redirect, so it is done
+        here, and the endpoint the server named is kept for every later call.
+
+        Parameters
+        ----------
+        payload : dict[str, Any]
+            The JSON-RPC envelope.
+
+        Returns
+        -------
+        tuple[str, bytes]
+            The ``mcp-session-id`` header (``""`` when absent) and the body.
+        """
+        for _ in range(4):
+            req = urllib.request.Request(
+                self._url,
+                data=json.dumps(payload).encode(),
+                headers=self._headers(),
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(
+                    req, timeout=self._timeout
+                ) as resp:  # nosec B310
+                    session = resp.headers.get("mcp-session-id", "") or ""
+                    body: bytes = resp.read()
+                    return session, body
+            except urllib.error.HTTPError as exc:
+                location = exc.headers.get("Location") if exc.headers else None
+                if exc.code in (307, 308) and location:
+                    self._url = urllib.parse.urljoin(self._url, location)
+                    continue
+                raise
+        raise urllib.error.URLError("too many redirects from the MCP endpoint")
+
+    def _post(self, payload: dict[str, Any]) -> bytes:
+        return self._send(payload)[1]
+
+    def connect(self) -> bool:
+        """
+        Perform the MCP handshake and store the session id and protocol version.
+
+        Returns
+        -------
+        bool
+            True if a session was established; on False, ``last_error`` says why.
+        """
+        init_payload = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {},
+                "clientInfo": {"name": "marcus-toolkit", "version": "0.1"},
+            },
+        }
+        self._session_id = ""
+        self._protocol_version = ""
+        try:
+            session, body = self._send(init_payload)
+            for envelope in parse_mcp_envelopes(body):
+                if envelope.get("error"):
+                    self.last_error = f"initialize refused: {envelope['error']}"
+                    return False
+                result = envelope.get("result")
+                if isinstance(result, dict) and result.get("protocolVersion"):
+                    self._protocol_version = str(result["protocolVersion"])
+            if not session:
+                self.last_error = "initialize reply carried no mcp-session-id header"
+                return False
+            self._session_id = session
+            if not self._protocol_version:
+                self._protocol_version = PROTOCOL_VERSION
+            self._post(
+                {"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}
+            )
+            self.last_error = ""
+            return True
+        except urllib.error.HTTPError as exc:
+            detail = exc.read()[:300].decode(errors="replace")
+            self.last_error = f"HTTP {exc.code} from {self._url}: {detail}"
+        except (urllib.error.URLError, OSError, json.JSONDecodeError) as exc:
+            self.last_error = f"{type(exc).__name__}: {exc}"
+        self._session_id = ""
+        return False
+
+    def call_tool(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> dict[str, Any] | None:
+        """
+        Call a tool and return its structured result, or ``None`` on any failure.
+
+        Parameters
+        ----------
+        name : str
+            The tool name.
+        arguments : Optional[Dict[str, Any]]
+            The tool arguments.
+
+        Returns
+        -------
+        Optional[Dict[str, Any]]
+            The reply body, or ``None`` when not connected, the request failed,
+            or the response carried no structured result; ``last_error`` says why.
+        """
+        if not self._session_id:
+            self.last_error = f"{name}: not connected"
+            return None
+        self._request_id += 1
+        try:
+            raw = self._post(
+                {
+                    "jsonrpc": "2.0",
+                    "id": self._request_id,
+                    "method": "tools/call",
+                    "params": {"name": name, "arguments": arguments or {}},
+                }
+            )
+        except urllib.error.HTTPError as exc:
+            detail = exc.read()[:300].decode(errors="replace")
+            self.last_error = f"{name}: HTTP {exc.code}: {detail}"
+            return None
+        except (urllib.error.URLError, OSError) as exc:
+            self.last_error = f"{name}: {type(exc).__name__}: {exc}"
+            return None
+        result = parse_mcp_tool_result(raw)
+        if result is None:
+            self.last_error = f"{name}: no structured result in the reply"
+        return result
+
+    def call(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """
+        Call a tool and return its reply body, raising when there is none.
+
+        Parameters
+        ----------
+        name : str
+            The tool name.
+        arguments : Optional[Dict[str, Any]]
+            The tool arguments.
+
+        Returns
+        -------
+        Dict[str, Any]
+            The reply body.
+
+        Raises
+        ------
+        MarcusClientError
+            When the client is not connected or the call produced no readable
+            reply. The message names the tool and the reason.
+        """
+        if not self._session_id:
+            raise MarcusClientError(f"{name}: not connected")
+        reply = self.call_tool(name, arguments)
+        if reply is None:
+            raise MarcusClientError(f"{name}: {self.last_error or 'no readable reply'}")
+        return reply

marcus_toolkit/funnel.py

@@ -0,0 +1,154 @@
+"""The candidate funnel, read from ``candidates.jsonl``, never reconstructed."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from .views import candidate_views
+
+
+def candidate_funnel(
+    path: Path | None,
+    calls: Iterable[dict[str, Any]] | None = None,
+    planned: Path | None = None,
+) -> dict[str, Any]:
+    """
+    Summarise the candidate funnel from the controller's ``candidates.jsonl``.
+
+    Parameters
+    ----------
+    path : Optional[Path]
+        ``candidates.jsonl``; missing means candidates were off.
+    calls : Optional[Iterable[Dict[str, Any]]]
+        The agents' board calls, for the view log; with it, evaporations split
+        into ``evaporated_declined`` and ``evaporated_unseen``.
+    planned : Optional[Path]
+        A planner's ``planned.jsonl`` whose passes record ``candidates_posted``.
+
+    Returns
+    -------
+    Dict[str, Any]
+        Counts, per-candidate view numbers, the promotions, and the raw events.
+    """
+    empty: dict[str, Any] = {
+        "promoted": 0,
+        "evaporated": 0,
+        "open_at_end": 0,
+        "shown_to": {},
+        "declined_by": {},
+        "awaiting_turn": {},
+        "abstained_by": {},
+        "abstentions": 0,
+        "promotions": [],
+        "evaporated_declined": 0,
+        "evaporated_unseen": 0,
+        "posted_by_planner": 0,
+        "posted_from_proposals": 0,
+        "posted_from_observations": 0,
+        "posted_by_coordinator": 0,
+        "objections": 0,
+        "mean_seconds_to_promotion": None,
+        "supporters": {},
+        "views": {},
+        "events": [],
+    }
+    by_planner: set[str] = set()
+    if planned is not None and planned.exists():
+        for line in planned.read_text(errors="replace").splitlines():
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            for subject in record.get("candidates_posted") or []:
+                by_planner.add(str(subject))
+    if path is None or not path.exists():
+        return {**empty, "posted_by_planner": len(by_planner)}
+    events: list[dict[str, Any]] = []
+    for line in path.read_text(errors="replace").splitlines():
+        try:
+            events.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    promoted = [e for e in events if e.get("event") == "promoted"]
+    evaporated = [e for e in events if e.get("event") == "evaporated"]
+    open_at_end = [e for e in events if e.get("event") == "open_at_end"]
+    posted_all = [e for e in events if e.get("event") == "posted"]
+    observed = [e for e in posted_all if e.get("observers")]
+    coordinator = [e for e in posted_all if e.get("from") == "coordinator"]
+    proposals = [
+        e
+        for e in posted_all
+        if not e.get("observers") and e.get("from") != "coordinator"
+    ]
+    supporters: Counter[str] = Counter()
+    for e in promoted:
+        for agent in e.get("supporters") or []:
+            supporters[agent] += 1
+    times = [
+        int(e["seconds_to_promotion"])
+        for e in promoted
+        if e.get("seconds_to_promotion") is not None
+    ]
+    closed_at = {
+        str(e.get("subject")): str(e.get("at"))
+        for e in events
+        if e.get("event") in ("promoted", "evaporated")
+        and e.get("subject")
+        and e.get("at")
+    }
+    seen_by = (
+        candidate_views(list(calls), before=closed_at) if calls is not None else {}
+    )
+    subjects = {str(e.get("subject")) for e in events if e.get("subject")} | by_planner
+    views = {s: len(seen_by.get(s, [])) for s in sorted(subjects)}
+    declined = sum(1 for e in evaporated if views.get(str(e.get("subject")), 0) > 0)
+    closed = promoted + evaporated + open_at_end
+
+    def per(key: str) -> dict[str, int]:
+        return {
+            str(e.get("subject")): len(e.get(key) or [])
+            for e in closed
+            if e.get("subject")
+        }
+
+    return {
+        "promoted": len(promoted),
+        "evaporated": len(evaporated),
+        "open_at_end": len(open_at_end),
+        "shown_to": per("shown_to"),
+        "declined_by": per("declined_by"),
+        "awaiting_turn": per("awaiting_turn"),
+        "abstained_by": per("abstained_by"),
+        "abstentions": sum(
+            len(e.get("agents") or []) for e in events if e.get("event") == "abstained"
+        ),
+        "promotions": [
+            {
+                "name": e.get("name"),
+                "subject": e.get("subject"),
+                "supporters": list(e.get("supporters") or []),
+                "objectors": list(e.get("objectors") or []),
+                "seconds_to_promotion": e.get("seconds_to_promotion"),
+                "shown_to": len(e.get("shown_to") or []),
+                "declined_by": len(e.get("declined_by") or []),
+                "abstained_by": len(e.get("abstained_by") or []),
+                "task_ids": list(e.get("task_ids") or []),
+            }
+            for e in promoted
+        ],
+        "evaporated_declined": declined,
+        "evaporated_unseen": len(evaporated) - declined,
+        "views": views,
+        "posted_by_planner": len(by_planner),
+        "posted_from_proposals": len(proposals),
+        "posted_from_observations": len(observed),
+        "posted_by_coordinator": len(coordinator),
+        "objections": sum(1 for e in promoted + evaporated if e.get("objectors")),
+        "mean_seconds_to_promotion": round(sum(times) / len(times)) if times else None,
+        "supporters": dict(sorted(supporters.items())),
+        "events": events,
+    }

marcus_toolkit/gate.py

@@ -0,0 +1,150 @@
+"""
+Does the agreement chain still work? Asked of a run's record, in three links.
+
+Work is agreed before it is created: the coordinator posts a candidate; agents
+answer it; two supporters promote it into a task an agent then picks up. Three
+links, each needing the one before it: a candidate is posted at all; support
+is recorded against a candidate; a promotion creates a task on the board. The
+verdict is one of four, and PARTIAL is a real outcome rather than a softened
+failure: PROVEN, PARTIAL (posted and supported, nobody promoted, an agent
+choice), FAILED (a link that does not depend on an agent's choice did not fire,
+or a promotion created nothing), NOT PROVEN (nothing ran).
+
+Lifted from the Minecraft plumbing's ``live_check_no_regression.py``, the
+reading half; starting a run is the extension's business.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from .measure import read_jsonl
+
+PROVEN, FAILED, NOT_PROVEN, PARTIAL = 0, 1, 2, 3
+NAMES = {
+    PROVEN: "PROVEN",
+    FAILED: "FAILED",
+    NOT_PROVEN: "NOT PROVEN",
+    PARTIAL: "PARTIAL",
+}
+
+
+def task_exists(kanban_db: Path, task_id: str) -> bool | None:
+    """Return whether a task with this id is on the board, or ``None`` if unreadable."""
+    if not kanban_db.exists():
+        return None
+    con = sqlite3.connect(f"file:{kanban_db}?mode=ro", uri=True)
+    try:
+        row = con.execute(
+            "select count(*) from tasks where id = ?", (task_id,)
+        ).fetchone()
+        return bool(row and row[0])
+    except sqlite3.Error:
+        return None
+    finally:
+        con.close()
+
+
+def check_chain(
+    candidates_jsonl: Path, kanban_db: Path, planned_jsonl: Path | None = None
+) -> dict[str, Any]:
+    """
+    Report which links of the chain fired.
+
+    Parameters
+    ----------
+    candidates_jsonl : Path
+        The controller's event stream.
+    kanban_db : Path
+        The run's own board, to confirm each promoted task id.
+    planned_jsonl : Optional[Path]
+        A planner's passes, whose ``candidates_posted`` count as postings.
+
+    Returns
+    -------
+    Dict[str, Any]
+        ``code`` (0 proven, 3 partial, 1 failed, 2 not proven), ``verdict``,
+        the three link counts, and ``lines`` explaining the reading.
+    """
+    events = read_jsonl(candidates_jsonl)
+    passes = read_jsonl(planned_jsonl) if planned_jsonl else []
+    by_planner: set[str] = set()
+    for record in passes:
+        for subject in record.get("candidates_posted") or []:
+            by_planner.add(str(subject))
+    # A candidate that closed, failed or stayed open was necessarily posted, so
+    # link 1 counts every subject any candidate event names, not only the
+    # "posted" events a planning pass may record elsewhere.
+    candidate_events = {
+        "posted",
+        "promoted",
+        "evaporated",
+        "open_at_end",
+        "promotion_failed",
+        "promotion_abandoned",
+        "abstained",
+        "already_on_board",
+    }
+    posted = {
+        str(e.get("subject"))
+        for e in events
+        if e.get("event") in candidate_events and e.get("subject")
+    } | by_planner
+    promoted = [e for e in events if e.get("event") == "promoted"]
+    failed = [e for e in events if e.get("event") == "promotion_failed"]
+    supported = [e for e in events if (e.get("supporters") or [])]
+    lines: list[str] = [
+        f"LINK 1, candidates posted: {len(posted)}",
+        f"LINK 2, candidates with support recorded: {len(supported)}",
+        f"LINK 3, promotions: {len(promoted)} ({len(failed)} refused by the board)",
+    ]
+    out: dict[str, Any] = {
+        "posted": len(posted),
+        "supported": len(supported),
+        "promoted": len(promoted),
+        "refused": len(failed),
+        "lines": lines,
+    }
+
+    def finish(code: int, reason: str) -> dict[str, Any]:
+        lines.append(f"VERDICT: {NAMES[code]} -- {reason}")
+        return {**out, "code": code, "verdict": NAMES[code]}
+
+    if not events and not passes:
+        return finish(NOT_PROVEN, "nothing was tended, so no link was exercised.")
+    if not posted:
+        return finish(
+            FAILED,
+            "no candidate was posted; posting does not depend on an agent's choice.",
+        )
+    for event in promoted:
+        ids = [str(i) for i in (event.get("task_ids") or [])]
+        if not ids:
+            return finish(FAILED, "a promotion created nothing.")
+        for task_id in ids:
+            if task_exists(kanban_db, task_id) is not True:
+                return finish(
+                    FAILED,
+                    f"promoted task {task_id[:12]} is not on the run's own board.",
+                )
+        lines.append(f"  promoted {str(event.get('name'))[:60]}: task_ids {ids}")
+    if failed and not promoted:
+        return finish(FAILED, "every promotion was refused by the board.")
+    if not promoted:
+        if not supported:
+            return finish(
+                PARTIAL,
+                "candidates posted and no agent answered any; link 2 unexercised.",
+            )
+        return finish(
+            PARTIAL,
+            "support was recorded and no candidate reached promotion;"
+            " link 3 unexercised.",
+        )
+    return finish(
+        PROVEN,
+        "candidates posted, support recorded, and a promotion created a task"
+        " on the board.",
+    )