code-coordinator 0.5.332__tar.gz → 0.5.333__tar.gz

{code_coordinator-0.5.332 → code_coordinator-0.5.333}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.332
+Version: 0.5.333
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.332 → code_coordinator-0.5.333}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.332
+Version: 0.5.333
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.332 → code_coordinator-0.5.333}/code_coordinator.egg-info/SOURCES.txt

@@ -734,6 +734,7 @@ tests/test_scoped_review_wiring.py
 tests/test_scorecard.py
 tests/test_self_health.py
 tests/test_serve.py
+tests/test_serve_app.py
 tests/test_serve_app_board_trim.py
 tests/test_serve_rest_routes.py
 tests/test_session.py

{code_coordinator-0.5.332 → code_coordinator-0.5.333}/code_coordinator.egg-info/scm_file_list.json

@@ -760,6 +760,7 @@
     "tests/test_scorecard.py",
     "tests/test_self_health.py",
     "tests/test_serve.py",
+    "tests/test_serve_app.py",
     "tests/test_serve_app_board_trim.py",
     "tests/test_serve_rest_routes.py",
     "tests/test_session.py",

{code_coordinator-0.5.332 → code_coordinator-0.5.333}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.332",
+  "tag": "0.5.333",
   "distance": 0,
-  "node": "g9eb084d2d068fc5fdf96e3a5de7f75bb41902679",
+  "node": "g05e864bdfa3476802900ee1d85295822957907e0",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-01"

{code_coordinator-0.5.332 → code_coordinator-0.5.333}/coord/machine_metrics.py

@@ -48,10 +48,12 @@ for exactly this reason) are not this module's job.
 from __future__ import annotations
 
 import logging
+import re
 import time
 from collections import deque
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
+from datetime import datetime
 
 import httpx
 
@@ -215,3 +217,174 @@ class MachineMetricsSampler:
         except Exception as exc:  # noqa: BLE001 — one bad machine must never abort the refresh
             log.warning("machine-metrics poll: %s raised %s", machine.name, exc)
             return _unknown(f"poll raised: {exc}")
+
+
+# ── read path: GET /machines/metrics (#3021) ────────────────────────────────
+#
+# Everything below is pure — no I/O, no dependence on the sampler's internal
+# deques beyond the plain ``list[dict]`` returned by ``series()``/
+# ``all_series()``. That keeps it trivially unit-testable and reusable from
+# `coord.serve_app`'s request handler without either side needing to know
+# about the other's internals.
+
+_DURATION_RE = re.compile(r"^\s*(\d+(?:\.\d+)?)\s*([smhdw])\s*$", re.IGNORECASE)
+_UNIT_SECONDS = {"s": 1.0, "m": 60.0, "h": 3600.0, "d": 86400.0, "w": 604800.0}
+
+
+def resolve_since(raw: str | None, *, now: float | None = None) -> float | None:
+    """Resolve a ``?since=`` query value to an absolute epoch timestamp.
+
+    Accepts three forms (mirrors the vocabulary the issue asks for,
+    ``<epoch|duration>``, plus ISO-8601 for parity with ``coord audit``'s
+    ``since``/``until``):
+
+    - ``None`` or ``""`` → ``None``, meaning "no lower bound" (the full
+      retained window — the endpoint's documented default).
+    - A duration like ``"6h"``, ``"90m"``, ``"3d"`` (units: s, m, h, d, w) →
+      ``now - duration``.
+    - An epoch number (``"1699999999"``) or an ISO-8601 timestamp
+      (``"2026-01-01T00:00:00Z"``) → that instant, verbatim.
+
+    Raises :class:`ValueError` on anything else, so the HTTP handler can
+    turn it into a 400 with the bad value quoted back.
+    """
+    if raw is None or raw == "":
+        return None
+    now = now if now is not None else time.time()
+    match = _DURATION_RE.match(raw)
+    if match:
+        return now - float(match.group(1)) * _UNIT_SECONDS[match.group(2).lower()]
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        pass
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp()
+    except ValueError as exc:
+        raise ValueError(
+            f"not an epoch number, ISO-8601 timestamp, or duration: {raw!r} "
+            "(duration units: s, m, h, d, w)"
+        ) from exc
+
+
+def _filter_since(samples: list[dict], since: float | None) -> list[dict]:
+    if since is None:
+        return list(samples)
+    return [s for s in samples if s["timestamp"] >= since]
+
+
+def _sample_intensity(sample: dict) -> float:
+    """How "interesting" a sample is for peak-preserving downsampling.
+
+    An ``unknown`` sample never outranks a real one — it always scores
+    below every possible real reading (percentages are 0-100) — so a bucket
+    with even one real sample surfaces that reading rather than the gap.
+    """
+    if sample.get("status") != STATUS_OK:
+        return -1.0
+    cpu = sample.get("cpu_percent") or 0.0
+    mem = sample.get("mem_percent") or 0.0
+    return max(cpu, mem)
+
+
+def _pick_representative(bucket: list[dict]) -> dict:
+    """The single sample that best represents ``bucket``.
+
+    Picks the highest-intensity real sample in the bucket (see
+    :func:`_sample_intensity`) so a brief spike survives downsampling
+    instead of being averaged away or dropped by naive striding. A bucket
+    with no real samples at all — every poll in that span came back
+    ``unknown`` — reports its first ``unknown`` sample, so a renderer still
+    sees the gap rather than the bucket silently vanishing.
+    """
+    best = bucket[0]
+    best_score = _sample_intensity(best)
+    for sample in bucket[1:]:
+        score = _sample_intensity(sample)
+        if score > best_score:
+            best, best_score = sample, score
+    return best
+
+
+def downsample(samples: list[dict], resolution: int) -> list[dict]:
+    """Reduce ``samples`` (oldest-first) to at most ``resolution`` points.
+
+    A 6h window at the default ~15s cadence is ~1440 points per machine; a
+    phone asking for ``resolution=100`` must get **at most** 100 back, and
+    the server must do the reduction — never ship the raw buffer and let
+    the client thin it (the whole point of #3021).
+
+    Buckets ``samples`` into ``resolution`` roughly-equal, chronologically
+    contiguous spans and keeps one representative per bucket (see
+    :func:`_pick_representative`) — naive fixed-stride sampling (every Nth
+    point) would silently skip over a spike that lands on a dropped index;
+    this always surfaces the bucket's peak instead.
+
+    Raises :class:`ValueError` if ``resolution`` is not positive.
+    """
+    if resolution <= 0:
+        raise ValueError("resolution must be positive")
+    n = len(samples)
+    if n <= resolution:
+        return list(samples)
+    out: list[dict] = []
+    for i in range(resolution):
+        lo = (i * n) // resolution
+        hi = ((i + 1) * n) // resolution
+        bucket = samples[lo:hi]
+        if bucket:
+            out.append(_pick_representative(bucket))
+    return out
+
+
+def build_metrics_response(
+    series_by_machine: dict[str, list[dict]],
+    *,
+    machine: str | None = None,
+    since: float | None = None,
+    resolution: int | None = None,
+    now: float | None = None,
+) -> dict:
+    """Assemble the versioned ``GET /machines/metrics`` response body.
+
+    ``series_by_machine`` is exactly :meth:`MachineMetricsSampler.all_series`'s
+    shape (name → oldest-first list of :meth:`MetricsSample.to_dict`), kept
+    as a plain argument rather than the sampler itself so this stays a pure
+    function a test can call with a synthetic dict.
+
+    - ``machine`` narrows to a single machine's series; a name with no
+      buffer yet (never polled, or simply unknown) comes back as ``[]``,
+      same as :meth:`MachineMetricsSampler.series` — never a 404, since "no
+      data yet" and "no such machine" are indistinguishable from here and
+      both mean the same thing to a renderer: nothing to draw.
+    - ``since`` filters to samples at or after that epoch timestamp
+      (:func:`resolve_since` turns the query string into this).
+    - ``resolution`` server-side downsamples each machine's filtered series
+      independently (:func:`downsample`); omitted means the full filtered
+      series.
+
+    ``schema: 1`` — versioned explicitly, matching
+    ``FleetHealthSnapshot.to_dict()``'s posture, so a client can detect a
+    future incompatible reshape rather than guess from field presence.
+    """
+    now = now if now is not None else time.time()
+    selected = (
+        {machine: series_by_machine.get(machine, [])}
+        if machine is not None
+        else series_by_machine
+    )
+
+    machines_out: dict[str, list[dict]] = {}
+    for name, series in selected.items():
+        windowed = _filter_since(series, since)
+        if resolution is not None:
+            windowed = downsample(windowed, resolution)
+        machines_out[name] = windowed
+
+    return {
+        "schema": 1,
+        "generated_at": now,
+        "since": since,
+        "resolution": resolution,
+        "machines": machines_out,
+    }

{code_coordinator-0.5.332 → code_coordinator-0.5.333}/coord/serve_app.py

@@ -4957,6 +4957,91 @@ def openapi_spec() -> dict:
                 },
             }
         },
+        "/machines/metrics": {
+            "get": {
+                "summary": (
+                    "#3021: server-downsampled cpu/mem history from #3020's "
+                    "bounded per-machine ring buffers (~6h at ~15s cadence). "
+                    "Never ships the raw buffer for the client to thin — pass "
+                    "`resolution` and the server reduces it."
+                ),
+                "parameters": [
+                    {
+                        "name": "since",
+                        "in": "query",
+                        "schema": {"type": "string"},
+                        "description": (
+                            "epoch seconds, ISO-8601, or a duration like '6h' "
+                            "('now minus 6h'). Omitted = the full retained window."
+                        ),
+                    },
+                    {
+                        "name": "resolution",
+                        "in": "query",
+                        "schema": {"type": "integer"},
+                        "description": (
+                            "max points per machine per series in the response, "
+                            "e.g. 100. Downsampling is peak-preserving (keeps the "
+                            "highest cpu/mem reading per bucket, never naive "
+                            "striding). Omitted = full filtered series."
+                        ),
+                    },
+                    {
+                        "name": "machine",
+                        "in": "query",
+                        "schema": {"type": "string"},
+                        "description": "narrow to a single machine's series",
+                    },
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "schema": {"type": "integer", "enum": [1]},
+                                        "generated_at": {"type": "number"},
+                                        "since": {"type": ["number", "null"]},
+                                        "resolution": {"type": ["integer", "null"]},
+                                        "machines": {
+                                            "type": "object",
+                                            "description": (
+                                                "machine name -> oldest-first list "
+                                                "of samples; status=unknown carries "
+                                                "no cpu/mem values so a renderer "
+                                                "draws a gap instead of interpolating"
+                                            ),
+                                            "additionalProperties": {
+                                                "type": "array",
+                                                "items": {
+                                                    "type": "object",
+                                                    "properties": {
+                                                        "timestamp": {"type": "number"},
+                                                        "status": {
+                                                            "type": "string",
+                                                            "enum": ["ok", "unknown"],
+                                                        },
+                                                        "cpu_percent": {"type": ["number", "null"]},
+                                                        "mem_percent": {"type": ["number", "null"]},
+                                                        "mem_used_mb": {"type": ["number", "null"]},
+                                                        "mem_total_mb": {"type": ["number", "null"]},
+                                                        "reason": {"type": "string"},
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                    "required": ["schema", "generated_at", "machines"],
+                                }
+                            }
+                        },
+                    },
+                    "400": {"description": "Bad `since` or `resolution`"},
+                },
+            }
+        },
         "/report": {
             "get": {
                 "summary": (
@@ -5304,11 +5389,23 @@ def openapi_spec() -> dict:
     )
 
 
-def build_app(store: CoordStore, config: Config, *, token: str | None = None) -> Starlette:
+def build_app(
+    store: CoordStore,
+    config: Config,
+    *,
+    token: str | None = None,
+    machine_metrics_sampler: MachineMetricsSampler | None = None,
+) -> Starlette:
     """Build the read-only control-center Starlette app bound to *store* + *config*.
 
     *token* — when set, every endpoint except ``/healthz`` requires
     ``Authorization: Bearer <token>``.
+
+    *machine_metrics_sampler* — injectable for tests (#3021): a fresh
+    :class:`~coord.machine_metrics.MachineMetricsSampler` is created when
+    omitted, exactly as before. Passing a pre-seeded instance lets a test
+    drive ``GET /machines/metrics`` against known ring-buffer contents
+    without waiting on the tick loop or a live agent poll.
     """
     # #1081: track the backing coordinator.yml's mtime so the handlers below
     # can swap in a freshly-reloaded Config when it changes on disk, instead
@@ -5343,11 +5440,12 @@ def build_app(store: CoordStore, config: Config, *, token: str | None = None) ->
     # #3020: same shape again — polling every agent's own /metrics is real
     # per-machine I/O, so it runs on the tick loop's cadence
     # (`_machine_metrics_loop` below), never inline off a request handler.
-    # Series live only in this sampler's bounded in-memory ring buffers; no
-    # read endpoint exists yet (that's #A2) and nothing here touches /board.
+    # Series live only in this sampler's bounded in-memory ring buffers;
+    # `GET /machines/metrics` (#3021, below) is the read endpoint and does
+    # bare in-memory reads only. Nothing here touches /board.
     from coord.machine_metrics import MachineMetricsSampler  # noqa: PLC0415
 
-    _machine_metrics_sampler = MachineMetricsSampler()
+    _machine_metrics_sampler = machine_metrics_sampler or MachineMetricsSampler()
 
     # Short-TTL cache for the computed /board projection so burst polls from the
     # TUI don't each pay the full board_projection + merge-plan + stage-projection
@@ -8882,6 +8980,39 @@ def build_app(store: CoordStore, config: Config, *, token: str | None = None) ->
             )
         return JSONResponse(result.to_dict())
 
+    async def get_machine_metrics(request: Request) -> Response:
+        # #3021: the read side of #3020's sampler. Bare in-memory reads +
+        # pure filtering/downsampling — no I/O, so (unlike /board) this
+        # never needs a threadpool hop and can't be slowed by a hanging
+        # agent (that's `_machine_metrics_loop`'s problem, not this
+        # handler's).
+        from coord.machine_metrics import build_metrics_response, resolve_since  # noqa: PLC0415
+
+        qp = request.query_params
+
+        resolution_raw = qp.get("resolution")
+        try:
+            resolution = int(resolution_raw) if resolution_raw else None
+            if resolution is not None and resolution <= 0:
+                raise ValueError("resolution must be a positive integer")
+        except ValueError as e:
+            return JSONResponse(
+                {"error": f"bad resolution={resolution_raw!r}: {e}"}, status_code=400
+            )
+
+        try:
+            since = resolve_since(qp.get("since"))
+        except ValueError as e:
+            return JSONResponse({"error": str(e)}, status_code=400)
+
+        result = build_metrics_response(
+            _machine_metrics_sampler.all_series(),
+            machine=qp.get("machine") or None,
+            since=since,
+            resolution=resolution,
+        )
+        return JSONResponse(result)
+
     async def post_merge(request: Request) -> Response:
         # #584: the merge queue + board live in THIS (canonical) DB, and gh is
         # authenticated here — so a thin client's `coord merge` / TUI 'Go' routes
@@ -10292,6 +10423,9 @@ def build_app(store: CoordStore, config: Config, *, token: str | None = None) ->
         # read-only, both alongside /audit because they read the same data.
         Route("/report", get_report_catalogue, methods=["GET"]),
         Route("/report/{report_id}", get_report, methods=["GET"]),
+        # #3021: read side of #3020's sampler — server-downsampled machine
+        # cpu/mem history for the coord-web Machines panel.
+        Route("/machines/metrics", get_machine_metrics, methods=["GET"]),
         Route("/config", serve_config, methods=["GET"]),
         Route("/result", post_result, methods=["POST"]),
         Route("/completion", post_completion, methods=["POST"]),