codereview-loop 0.13.0__py3-none-any.whl

codereview/mcp_transport.py

@@ -0,0 +1,272 @@
+"""MCP stdio transport (Epic L2): the wire layer only.
+
+Newline-delimited JSON-RPC 2.0 over a pair of binary streams —
+the Model Context Protocol's stdio transport. This module
+knows nothing about CodeReview, the gate, or the tools served
+on top of it (that layer is codereview.mcp_tools); it frames
+messages, dispatches them to a caller-supplied handler, and
+writes the responses.
+
+Fail-closed contract (a bad frame can never kill the host
+loop or take the server down with it):
+
+- an unparseable line is answered with a JSON-RPC parse error
+  (id null) and the loop continues with the next line;
+- a frame larger than the size cap is discarded through its
+  terminating newline, answered with an invalid-request error,
+  and the loop continues — the stream stays in sync;
+- a structurally invalid request (not an object, no method,
+  a batch array — MCP does not batch) is answered with an
+  invalid-request error;
+- an exception escaping the handler becomes an internal-error
+  response for that request; for a notification it is only
+  recorded (notifications never get responses).
+
+Every protocol-level failure is appended to the server's
+`errors` ledger and mirrored to the diagnostic log (stderr in
+production — stdout is the protocol), so a malformed or
+oversized request is always recorded somewhere inspectable,
+never silently swallowed. Stdlib only, like the rest of the
+package.
+"""
+
+import json
+import math
+import sys
+
+# JSON-RPC 2.0 error codes used by this layer.
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
+
+# One frame's ceiling. A gate request carries a diff; the
+# review path's own per-batch budget is 80k chars, and even a
+# monorepo-scale hand-off diff fits far under this — 16 MiB is
+# generous headroom, not an invitation.
+MAX_FRAME_BYTES = 16 * 1024 * 1024
+
+
+class JsonRpcError(Exception):
+    """A protocol-level error: answered to the client with
+    `code` and `message`, never raised out of the serve loop."""
+
+    def __init__(self, code, message, data=None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.data = data
+
+
+def _sanitised_id(req_id):
+    """A request id is echoed verbatim — except a non-finite
+    float. Python's json accepts NaN/Infinity by default, so
+    a frame can carry one as its id; echoing it would emit
+    invalid JSON (P3-10). It is answered as null."""
+    if isinstance(req_id, float) and not math.isfinite(req_id):
+        return None
+    return req_id
+
+
+def result_response(req_id, result):
+    return {"jsonrpc": "2.0", "id": req_id, "result": result}
+
+
+def error_response(req_id, code, message, data=None):
+    error = {"code": code, "message": message}
+    if data is not None:
+        error["data"] = data
+    return {"jsonrpc": "2.0", "id": req_id, "error": error}
+
+
+class StdioServer:
+    """Serve newline-delimited JSON-RPC over binary streams.
+
+    `dispatch(method, params, notification)` returns the result
+    for a request (its return value is ignored for a
+    notification) and raises JsonRpcError for protocol-level
+    refusals. Anything else it raises becomes an internal
+    error. `max_frame_bytes` is injectable so tests can trip
+    the cap without moving megabytes.
+    """
+
+    def __init__(self, dispatch, stdin=None, stdout=None,
+                 log=None, max_frame_bytes=MAX_FRAME_BYTES):
+        self._dispatch = dispatch
+        self._stdin = stdin if stdin is not None \
+            else sys.stdin.buffer
+        self._stdout = stdout if stdout is not None \
+            else sys.stdout.buffer
+        self._log = log if log is not None else (
+            lambda text: print(text, file=sys.stderr))
+        self._max_frame_bytes = max_frame_bytes
+        # The failure ledger: one entry per protocol-level
+        # failure, in arrival order — the recorded half of the
+        # fail-closed contract.
+        self.errors = []
+
+    # -- framing ------------------------------------------------
+
+    def _read_frame(self):
+        """Read one newline-terminated frame. Returns
+        (raw_bytes, oversized): raw is None at EOF. An oversized
+        frame's bytes are consumed through its newline (and
+        dropped) so the next frame starts in sync."""
+        chunk = self._stdin.readline(self._max_frame_bytes + 2)
+        if chunk == b"":
+            return None, False
+        if len(chunk) <= self._max_frame_bytes + 1 \
+                and chunk.endswith(b"\n"):
+            return chunk, False
+        if len(chunk) <= self._max_frame_bytes + 1:
+            # Final line without a newline (EOF right after):
+            # still a frame.
+            return chunk, False
+        # Oversized: discard through the terminating newline.
+        while not chunk.endswith(b"\n"):
+            chunk = self._stdin.readline(self._max_frame_bytes + 2)
+            if chunk == b"":
+                break
+        return b"", True
+
+    def _send(self, message):
+        try:
+            data = (json.dumps(message, ensure_ascii=False,
+                               allow_nan=False)
+                    + "\n").encode("utf-8")
+        except (TypeError, ValueError):
+            # allow_nan=False refuses a non-finite float
+            # anywhere in the payload (P3-10): the wire must
+            # never carry NaN/Infinity literals — they are
+            # not JSON. Answer with a plain internal error
+            # instead of killing the loop.
+            data = (json.dumps(error_response(
+                None, INTERNAL_ERROR,
+                "response was not JSON-serialisable"))
+                + "\n").encode("utf-8")
+        self._stdout.write(data)
+        self._stdout.flush()
+
+    def _record(self, kind, detail):
+        entry = {"kind": kind, "detail": str(detail)[:500]}
+        self.errors.append(entry)
+        self._log(f"codereview mcp: {kind}: {entry['detail']}")
+
+    # -- the loop -------------------------------------------------
+
+    def serve_forever(self):
+        """Run until EOF on stdin. Never raises for a bad
+        frame, a bad request, or a failing handler."""
+        while True:
+            raw, oversized = self._read_frame()
+            if raw is None:
+                return
+            if oversized:
+                self._record(
+                    "oversized_frame",
+                    f"frame exceeds {self._max_frame_bytes} bytes")
+                self._send(error_response(
+                    None, INVALID_REQUEST,
+                    "request frame exceeds the size limit "
+                    f"({self._max_frame_bytes} bytes)"))
+                continue
+            if not raw.strip():
+                continue
+            try:
+                message = json.loads(raw.decode("utf-8"))
+            except (UnicodeDecodeError, ValueError,
+                    RecursionError) as exc:
+                # RecursionError: a frame nested deeper than
+                # the interpreter's limit is a parse failure
+                # like any other (P3-05) — it must not kill
+                # the loop or skip the ledger.
+                self._record("parse_error", exc)
+                self._send(error_response(
+                    None, PARSE_ERROR, f"parse error: {exc}"))
+                continue
+            self._handle(message)
+
+    def _handle(self, message):
+        if not isinstance(message, dict):
+            self._record("invalid_request",
+                         "request is not a JSON object")
+            self._send(error_response(
+                None, INVALID_REQUEST,
+                "request must be a JSON object"))
+            return
+        req_id = _sanitised_id(message.get("id"))
+        if message.get("jsonrpc") != "2.0":
+            # P3-10: the version field was never read — a
+            # "1.0" frame, or one with no version at all, was
+            # served as if it were 2.0. Fail closed with
+            # -32600; a notification-shaped frame (no id)
+            # keeps notification semantics — ledger only,
+            # never a response.
+            self._record("invalid_request",
+                         "jsonrpc field is not \"2.0\"")
+            if "id" in message:
+                self._send(error_response(
+                    req_id, INVALID_REQUEST,
+                    "jsonrpc field must be \"2.0\""))
+            return
+        if "id" in message:
+            # P5-05: a request id must be a string or an integer
+            # (JSON-RPC 2.0). Bool (an int subclass — excluded
+            # explicitly), float, null, object and array ids are
+            # invalid requests, answered -32600 with a null id:
+            # the offending id cannot be echoed as an identity.
+            # An ABSENT id is a notification and never reaches
+            # this check.
+            raw_id = message["id"]
+            # One carve-out, inherited from P3-10: a NON-FINITE
+            # float (NaN/Infinity — not producible by a
+            # conforming JSON encoder, and unemittable in a
+            # strict-JSON response) is sanitised to a null id
+            # by _sanitised_id and served, rather than refused.
+            nonfinite = isinstance(raw_id, float) and not \
+                math.isfinite(raw_id)
+            if not nonfinite and (isinstance(raw_id, bool)
+                                  or not isinstance(
+                                      raw_id, (str, int))):
+                self._record("invalid_request",
+                             "request id is not a string or "
+                             "an integer")
+                self._send(error_response(
+                    None, INVALID_REQUEST,
+                    "request id must be a string or an integer"))
+                return
+        method = message.get("method")
+        if not isinstance(method, str) or not method:
+            self._record("invalid_request",
+                         "request has no method")
+            self._send(error_response(
+                req_id, INVALID_REQUEST,
+                "request has no method"))
+            return
+        notification = "id" not in message
+        try:
+            result = self._dispatch(
+                method, message.get("params"), notification)
+        except JsonRpcError as exc:
+            if notification:
+                self._record("notification_error",
+                             f"{method}: {exc.message}")
+                return
+            self._record("request_error",
+                         f"{method}: {exc.message}")
+            self._send(error_response(
+                req_id, exc.code, exc.message, exc.data))
+            return
+        except Exception as exc:  # noqa: BLE001 — fail closed
+            if notification:
+                self._record("notification_error",
+                             f"{method}: {exc}")
+                return
+            self._record("internal_error", f"{method}: {exc}")
+            self._send(error_response(
+                req_id, INTERNAL_ERROR,
+                f"internal error: {exc}"))
+            return
+        if not notification:
+            self._send(result_response(req_id, result))

codereview/notify.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""codereview attention notifications (Epic L4).
+
+A long gate run should call the operator back instead of
+waiting to be checked. When a seat enters a blocked state
+(the Epic K2 classes — quota, auth, input, stalled) or the
+gate reaches a verdict, the run fires ONE local command the
+operator configured: a terminal bell, a desktop toast, a
+herdr-style attention hook. No hosted service, no
+CodeReview-managed endpoint — the command is the operator's
+own, on their own machine.
+
+Configuration surface: the USER SETUP only — a `[notify]`
+table in the saved config (see userconfig.py):
+
+    [notify]
+    command = ["my-notify-script"]
+
+Notifications are operator preference, not project contract:
+the project policy (.codereview.toml) has no notify key and
+cannot set one (policy.load_policy rejects the table as
+unknown). A run with no [notify] command configured behaves
+exactly as before this epic — no invocations, and the record
+carries no `notifications` section.
+
+Argv contract: the configured argv is executed directly
+(no shell) with two arguments appended — the event name and
+a one-line summary:
+
+    <command...> seat_blocked "seat cx blocked:quota"
+    <command...> verdict      "gate blocked: 3 finding(s)"
+
+Bounds and recording: each invocation is bounded by
+NOTIFY_TIMEOUT_S; the outcome (status ok / failed / timeout
+/ error, exit code, duration) is appended to the run
+record's `notifications` section. A failing, missing, or
+hanging notifier is recorded and never delays the run beyond
+the bound, never changes a finding or the verdict, and never
+raises into the review. The command runs in its own process
+group, and the group is killed when the invocation ends —
+on timeout (L10/NT9: a timed-out notifier leaves no
+grandchildren behind) and on normal exit (a notifier that
+backgrounds a helper and returns leaves nothing running;
+a helper that must outlive the notification has to detach
+into its own session, the documented setsid boundary).
+Duplicate suppression is per run: a seat that ends blocked
+in several jobs notifies once per (seat, class); the
+verdict notifies once.
+
+Deliberately distinct from Epic L3's lifecycle hooks: L3 is
+project-level deterministic automation declared in the
+project policy and executed inside the evidence sandbox; L4
+is a personal local command declared in the user setup and
+executed as the operator, inheriting the operator's
+environment — it is a doorbell, not a build step.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import time
+
+# The per-invocation bound: long enough for a toast/bell
+# command to start and finish, short enough that a wedged
+# notifier can never hold a gate run hostage. Two events in
+# a run (a blocked seat + the verdict) cost at most twice
+# this in the pathological all-hanging case.
+NOTIFY_TIMEOUT_S = 5.0
+
+EVENT_SEAT_BLOCKED = "seat_blocked"
+EVENT_VERDICT = "verdict"
+
+
+def _kill_notify_group(proc):
+    """Kill the notifier's whole process group (it runs in
+    its own session), so a timed-out — or merely
+    backgrounding — notifier leaves no children behind.
+    Mirrors probe._kill_probe_group (the C5 pattern). Never
+    raises."""
+    killpg = getattr(os, "killpg", None)
+    if killpg is not None:
+        try:
+            pgid = os.getpgid(proc.pid)
+        except (ProcessLookupError, PermissionError, OSError):
+            # The child has exited and been reaped: it WAS
+            # its group leader (start_new_session), so the
+            # pid IS the pgid — and the group can still hold
+            # live grandchildren.
+            pgid = proc.pid
+        try:
+            killpg(pgid, signal.SIGKILL)
+            return
+        except (ProcessLookupError, PermissionError, OSError):
+            pass
+    try:
+        proc.kill()
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _supervise_notify_run(proc, timeout):
+    """The notifier's supervised wait — the pairing the
+    subprocess-timeout guard accepts by name, as it does the
+    probe harness's and the evidence sandbox's: the wait is
+    deadline-bounded (wait(timeout=...)) and expiry kills
+    the whole process group, not just the direct child
+    (L10/NT9). The group is swept on normal exit too, so a
+    notifier that backgrounds a helper and returns leaves
+    nothing behind (the P3-06 rule). Raises
+    subprocess.TimeoutExpired on a hang, exactly as
+    subprocess.run(timeout=...) did."""
+    try:
+        proc.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        _kill_notify_group(proc)
+        try:
+            proc.wait(timeout=5)
+        except Exception:  # noqa: BLE001 — reaping is
+            pass  # best-effort; the kill already landed
+        raise
+    _kill_notify_group(proc)
+    return proc.returncode
+
+
+def _default_runner(argv, timeout):
+    """Run argv directly (no shell), bounded by `timeout`,
+    output discarded (the notification is the side effect;
+    anything the command prints is the operator's own console
+    business, not the record's). Returns the exit code.
+    Raises subprocess.TimeoutExpired on a hang, OSError when
+    the command cannot be started at all."""
+    proc = subprocess.Popen(
+        argv, stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        shell=False, start_new_session=True)
+    return _supervise_notify_run(proc, timeout)
+
+
+# The summary length ceiling (P3-12): a notification is a
+# doorbell, not a document — past this the summary is cut
+# and marked with an ellipsis.
+_SUMMARY_CAP_CHARS = 500
+
+
+def _one_line(text):
+    """The summary as it reaches BOTH the notifier argv and
+    the recorded outcome: one line, no control bytes, capped.
+
+    Whitespace runs collapse to single spaces (a seat name is
+    operator config and could carry a newline). Every other
+    control/escape byte (C0, DEL, C1 — ESC and BEL included,
+    so ANSI/OSC sequences lose their teeth) is dropped
+    (P3-12): a hostile or merely odd seat name must not
+    smuggle terminal escapes into a notifier UI that renders
+    raw argv, nor a 100KB string into the record."""
+    line = " ".join(str(text or "").split())
+    line = "".join(
+        ch for ch in line
+        if not (ord(ch) < 0x20 or 0x7F <= ord(ch) <= 0x9F))
+    if len(line) > _SUMMARY_CAP_CHARS:
+        line = line[:_SUMMARY_CAP_CHARS - 1] + "…"
+    return line
+
+
+class Notifier:
+    """One run's notification channel: a configured command
+    plus the outcomes it produced. Constructed by the caller
+    (CLI: from the user setup; tests: with a stub runner) and
+    handed to core.run_review / run_verification. Every
+    method is total — fire() records and returns, never
+    raises."""
+
+    def __init__(self, command, timeout=NOTIFY_TIMEOUT_S,
+                 runner=None):
+        self.command = [str(c) for c in command]
+        self.timeout = float(timeout)
+        self._runner = runner or _default_runner
+        self._fired = set()
+        self.outcomes = []
+
+    def fire(self, event, summary, dedupe_key=None):
+        """Invoke the command once for `event`, unless an
+        event with `dedupe_key` already fired in this run.
+        Returns the recorded outcome dict, or None when the
+        invocation was suppressed as a duplicate."""
+        key = dedupe_key if dedupe_key is not None else (event,)
+        if key in self._fired:
+            return None
+        self._fired.add(key)
+        summary = _one_line(summary)
+        argv = self.command + [event, summary]
+        started = time.monotonic()
+        status, exit_code, detail = "ok", None, None
+        try:
+            exit_code = self._runner(argv, self.timeout)
+            if exit_code != 0:
+                status = "failed"
+        except subprocess.TimeoutExpired:
+            status = "timeout"
+        except Exception as exc:  # noqa: BLE001 — a notifier
+            # that cannot even start is an outcome, not a crash
+            status = "error"
+            detail = str(exc)[:200]
+        outcome = {"event": event, "summary": summary,
+                   "status": status, "exit_code": exit_code,
+                   "duration_ms": int(
+                       (time.monotonic() - started) * 1000)}
+        if detail:
+            outcome["detail"] = detail
+        self.outcomes.append(outcome)
+        return outcome
+
+    def seat_blocked(self, seat, cls):
+        """The blocked-seat event (Epic K2 classes): once per
+        (seat, class) per run — a seat blocked in three batch
+        jobs is one fact for the operator, not three pings."""
+        label = f"blocked:{cls}" if cls else "blocked"
+        return self.fire(
+            EVENT_SEAT_BLOCKED, f"seat {seat} {label}",
+            dedupe_key=(EVENT_SEAT_BLOCKED, str(seat),
+                        str(cls)))
+
+    def verdict(self, summary):
+        """The gate-verdict event: once per run."""
+        return self.fire(EVENT_VERDICT, summary,
+                         dedupe_key=(EVENT_VERDICT,))
+
+
+def notifier_for(command, **kwargs):
+    """A Notifier for a configured command argv, or None when
+    no command is configured — the unset state, in which the
+    review path is byte-identical to before this epic."""
+    if not command:
+        return None
+    return Notifier(command, **kwargs)