code-coordinator 0.5.338__tar.gz → 0.5.339__tar.gz

{code_coordinator-0.5.338 → code_coordinator-0.5.339}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.338
+Version: 0.5.339
 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.338 → code_coordinator-0.5.339}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.338
+Version: 0.5.339
 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.338 → code_coordinator-0.5.339}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.338",
+  "tag": "0.5.339",
   "distance": 0,
-  "node": "g219cbaf1280fdc6f1816823863f605cda1f936f1",
+  "node": "g9385deb1f400cff71b39039be094c1078708bd9c",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-01"

{code_coordinator-0.5.338 → code_coordinator-0.5.339}/coord/dashboard/server.py

@@ -607,6 +607,229 @@ def openapi_spec() -> dict:
         },
         "required": ["submission_id", "question_revision", "question"],
     }
+    # #3027: the four `/api/machines*` endpoints (#3021-#3026) went out
+    # carrying a bare `{"200": {"description": "OK"}}` stub — every other
+    # surface here has a real `content` schema, this milestone's own
+    # deliverable is closing that gap. Hand-built (not `dataclass_schema`),
+    # matching the same "mirror the handler's actual dict field-for-field"
+    # convention `report_result_ref`/`portal_ledger_entry` above already
+    # use, because none of these four responses is a plain
+    # `dataclasses.asdict()` of a single dataclass.
+    components["MachineAssignmentSpec"] = {
+        "type": "object",
+        "properties": {
+            "issue_number": {"type": "integer"},
+            "issue_title": {"type": "string"},
+            "repo_name": {"type": "string"},
+        },
+    }
+    machine_assignment_spec_ref = {"$ref": "#/components/schemas/MachineAssignmentSpec"}
+    components["MachineActiveAssignment"] = {
+        "type": "object",
+        "properties": {
+            "assignment_id": {"type": "string"},
+            "status": {"type": "string"},
+            "spec": machine_assignment_spec_ref,
+        },
+    }
+    machine_active_assignment_ref = {
+        "$ref": "#/components/schemas/MachineActiveAssignment"
+    }
+    components["MachineActiveAssignments"] = {
+        "type": "object",
+        "properties": {
+            "active": {"type": "array", "items": machine_active_assignment_ref}
+        },
+        "required": ["active"],
+    }
+    machine_active_assignments_ref = {
+        "$ref": "#/components/schemas/MachineActiveAssignments"
+    }
+    components["MachineRow"] = {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+            "host": {"type": "string"},
+            "repos": {"type": "array", "items": {"type": "string"}},
+            "state": {"type": "string", "description": "unknown|online|offline|..."},
+            "reason": {"type": "string"},
+            "latency_ms": {"type": "number", "nullable": True},
+            "agent_version": {"type": "string", "nullable": True},
+            "worktree_bytes": {"type": "number", "nullable": True},
+            "assignments": {
+                **machine_active_assignments_ref,
+                "nullable": True,
+                "description": "present only when this machine has running work",
+            },
+        },
+        "required": ["name", "host", "repos", "state", "reason"],
+    }
+    machine_row_ref = {"$ref": "#/components/schemas/MachineRow"}
+    machines_response = {"type": "array", "items": machine_row_ref}
+    # `coord.health.models.CheckResult.to_dict()` verbatim — shared by
+    # `MachineHealthRow.results` and `FleetHealthResponse.fleet_checks`,
+    # since both are that same to_dict() shape (see fleet_snapshot.py's
+    # `_machine_health_rows`/`FleetHealthRefresher.refresh`).
+    components["HealthCheckResult"] = {
+        "type": "object",
+        "properties": {
+            "key": {"type": "string"},
+            "check_id": {"type": "string"},
+            "scope": {"type": "string"},
+            "subject": {"type": "string", "nullable": True},
+            "title": {"type": "string"},
+            "label": {"type": "string"},
+            "severity": {"type": "string", "description": "ok|warn|crit|unknown"},
+            "headroom": {"type": "string"},
+            "threshold": {"type": "string"},
+            "detail": {"type": "string"},
+            "trend": {"type": "string", "nullable": True},
+            "values": {"type": "object"},
+            "error": {"type": "string", "nullable": True},
+        },
+        "required": ["key", "check_id", "scope", "title", "label", "severity", "headroom"],
+    }
+    health_check_result_ref = {"$ref": "#/components/schemas/HealthCheckResult"}
+    components["MachineHealthRow"] = {
+        "type": "object",
+        "properties": {
+            "machine": {"type": "string"},
+            "state": {"type": "string"},
+            "reason": {"type": "string"},
+            "latency_ms": {"type": "number", "nullable": True},
+            "received_at": {"type": "number", "nullable": True},
+            "stale": {"type": "boolean"},
+            "severity": {"type": "string", "description": "ok|warn|crit|unknown"},
+            "checked_at": {"type": "number", "nullable": True},
+            "results": {"type": "array", "items": health_check_result_ref},
+            "worktree_bytes": {"type": "number", "nullable": True},
+            "agent_runtime_version": {"type": "string", "nullable": True},
+        },
+        "required": ["machine", "state", "reason", "stale", "severity", "results"],
+    }
+    machine_health_row_ref = {"$ref": "#/components/schemas/MachineHealthRow"}
+    # Mirrors `coord.health.fleet_snapshot.FleetHealthSnapshot.to_dict()`
+    # exactly (`{schema, refreshed_at, machine_health, fleet_checks,
+    # truncated}`) -- the same body `/board`'s own `fleet_health` key
+    # carries, per this endpoint's docstring.
+    components["FleetHealthResponse"] = {
+        "type": "object",
+        "properties": {
+            "schema": {"type": "integer"},
+            "refreshed_at": {"type": "number", "nullable": True},
+            "machine_health": {"type": "array", "items": machine_health_row_ref},
+            "fleet_checks": {"type": "array", "items": health_check_result_ref},
+            "truncated": {"type": "boolean"},
+        },
+        "required": ["schema", "machine_health", "fleet_checks", "truncated"],
+    }
+    fleet_health_response_ref = {"$ref": "#/components/schemas/FleetHealthResponse"}
+    # Shared by `/api/machines/health` and `/api/machines/metrics` (#3024/
+    # #3021/#3022 both degrade an unreachable thin-client daemon the same
+    # way): an explicit `{error, detail, reachable: false}` 503 body, never
+    # a stale-looking 200.
+    components["DaemonUnreachableError"] = {
+        "type": "object",
+        "properties": {
+            "error": {"type": "string"},
+            "detail": {"type": "string"},
+            "reachable": {"type": "boolean"},
+        },
+        "required": ["error", "reachable"],
+    }
+    daemon_unreachable_ref = {"$ref": "#/components/schemas/DaemonUnreachableError"}
+    components["BadRequestError"] = {
+        "type": "object",
+        "properties": {"error": {"type": "string"}},
+        "required": ["error"],
+    }
+    bad_request_ref = {"$ref": "#/components/schemas/BadRequestError"}
+    # `coord.machine_metrics.MetricsSample.to_dict()` verbatim.
+    components["MachineMetricsSample"] = {
+        "type": "object",
+        "properties": {
+            "timestamp": {"type": "number"},
+            "status": {"type": "string", "description": "ok|unknown"},
+            "cpu_percent": {"type": "number", "nullable": True},
+            "mem_percent": {"type": "number", "nullable": True},
+            "mem_used_mb": {"type": "number", "nullable": True},
+            "mem_total_mb": {"type": "number", "nullable": True},
+            "reason": {"type": "string"},
+        },
+        "required": ["timestamp", "status", "reason"],
+    }
+    machine_metrics_sample_ref = {"$ref": "#/components/schemas/MachineMetricsSample"}
+    # `coord.machine_metrics.build_metrics_response()`'s body verbatim.
+    components["MachineMetricsResponse"] = {
+        "type": "object",
+        "properties": {
+            "schema": {"type": "integer"},
+            "generated_at": {"type": "number"},
+            "since": {"type": "number", "nullable": True},
+            "resolution": {"type": "integer", "nullable": True},
+            "machines": {
+                "type": "object",
+                "additionalProperties": {
+                    "type": "array",
+                    "items": machine_metrics_sample_ref,
+                },
+                "description": "machine name -> oldest-first sample series",
+            },
+        },
+        "required": ["schema", "generated_at", "machines"],
+    }
+    machine_metrics_response_ref = {"$ref": "#/components/schemas/MachineMetricsResponse"}
+    # `api_machines_stats`'s per-machine dict verbatim (#3025).
+    components["MachineStatsJobHistoryEntry"] = {
+        "type": "object",
+        "properties": {
+            "assignment_id": {"type": "string"},
+            "repo_name": {"type": "string"},
+            "issue_number": {"type": "integer", "nullable": True},
+            "issue_title": {"type": "string", "nullable": True},
+            "type": {"type": "string"},
+            "status": {"type": "string"},
+            "dispatched_at": {"type": "number", "nullable": True},
+            "finished_at": {"type": "number", "nullable": True},
+        },
+        "required": ["assignment_id", "repo_name", "type", "status"],
+    }
+    machine_stats_job_history_entry_ref = {
+        "$ref": "#/components/schemas/MachineStatsJobHistoryEntry"
+    }
+    components["MachineCapacity"] = {
+        "type": "object",
+        "properties": {
+            "active": {"type": "integer"},
+            "max": {"type": "integer"},
+        },
+        "required": ["active", "max"],
+    }
+    machine_capacity_ref = {"$ref": "#/components/schemas/MachineCapacity"}
+    components["MachineJobCounts"] = {
+        "type": "object",
+        "properties": {
+            "completed": {"type": "integer"},
+            "failed": {"type": "integer"},
+        },
+        "required": ["completed", "failed"],
+    }
+    machine_job_counts_ref = {"$ref": "#/components/schemas/MachineJobCounts"}
+    components["MachineStatsRow"] = {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+            "capacity": machine_capacity_ref,
+            "counts": machine_job_counts_ref,
+            "job_history": {
+                "type": "array",
+                "items": machine_stats_job_history_entry_ref,
+            },
+        },
+        "required": ["name", "capacity", "counts", "job_history"],
+    }
+    machine_stats_row_ref = {"$ref": "#/components/schemas/MachineStatsRow"}
+    machines_stats_response = {"type": "array", "items": machine_stats_row_ref}
     paths = {
         "/": {
             "get": {
@@ -628,7 +851,12 @@ def openapi_spec() -> dict:
         "/api/machines": {
             "get": {
                 "summary": "Machine reachability + live agent /status per machine",
-                "responses": {"200": {"description": "OK"}},
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {"application/json": {"schema": machines_response}},
+                    }
+                },
             }
         },
         "/api/machines/health": {
@@ -644,12 +872,18 @@ def openapi_spec() -> dict:
                             "OK -- {schema, refreshed_at, machine_health: [...], "
                             "fleet_checks: [...], truncated}, unchanged"
                         ),
+                        "content": {
+                            "application/json": {"schema": fleet_health_response_ref}
+                        },
                     },
                     "503": {
                         "description": (
                             "The daemon is unreachable -- an explicit "
                             "{error, reachable: false} body, never a stale-looking 200"
                         ),
+                        "content": {
+                            "application/json": {"schema": daemon_unreachable_ref}
+                        },
                     },
                 },
             }
@@ -690,15 +924,22 @@ def openapi_spec() -> dict:
                 "responses": {
                     "200": {
                         "description": "OK -- daemon's versioned metrics payload, verbatim",
+                        "content": {
+                            "application/json": {"schema": machine_metrics_response_ref}
+                        },
                     },
                     "400": {
                         "description": "The daemon rejected since/resolution as malformed",
+                        "content": {"application/json": {"schema": bad_request_ref}},
                     },
                     "503": {
                         "description": (
                             "The daemon is unreachable -- an explicit "
                             "{error, reachable: false} body, never an empty series"
                         ),
+                        "content": {
+                            "application/json": {"schema": daemon_unreachable_ref}
+                        },
                     },
                 },
             }
@@ -710,7 +951,14 @@ def openapi_spec() -> dict:
                     "active vs configured concurrency, completed/failed counts "
                     "over the retention window, and recent (last 20) job history"
                 ),
-                "responses": {"200": {"description": "OK"}},
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {
+                            "application/json": {"schema": machines_stats_response}
+                        },
+                    }
+                },
             }
         },
         "/api/proposals": {

{code_coordinator-0.5.338 → code_coordinator-0.5.339}/tests/test_dashboard_api.py

@@ -18,8 +18,9 @@ import pytest
 from starlette.testclient import TestClient
 
 from coord.config import Config
-from coord.dashboard.server import build_app
+from coord.dashboard.server import build_app, openapi_spec
 from coord.models import Assignment, Board, Machine, Repo
+from coord.openapi import validate_json_schema
 
 
 @pytest.fixture(autouse=True)
@@ -1372,3 +1373,239 @@ class TestMachineMetricsAPI:
         r = client.get("/api/machines/metrics")
         assert r.status_code == 200
         assert r.json()["machines"] == {"laptop": seeded.machine_metrics_raw["laptop"]}
+
+
+class TestMachinesEndpointsMatchOpenApiSpec:
+    """#3027: every ``/api/machines*`` endpoint (#3021-#3026) must now carry a
+    real response schema in ``openapi_spec()``, not the bare ``{"200":
+    {"description": "OK"}}`` stub ``/api/machines`` had carried until now.
+
+    Mirrors ``tests/test_openapi.py``'s
+    ``test_serve_openapi_board_schema_validates_golden_fixture`` pattern:
+    exercise the REAL (non-fixture) handler with a richly populated payload
+    -- assignments, multi-severity health results, metric samples, job
+    history -- so every optional/nullable field the schema declares is
+    actually hit at least once, then validate the served JSON against the
+    schema the SAME ``openapi_spec()`` this repo's codegen reads declares
+    for that path. A schema that silently drifted from what the handler
+    actually returns fails right here.
+    """
+
+    def _schema_for(self, spec: dict, path: str, status: str = "200") -> dict:
+        return spec["paths"][path]["get"]["responses"][status]["content"][
+            "application/json"
+        ]["schema"]
+
+    def test_machines_response_matches_its_schema(self) -> None:
+        board = Board(active=[
+            Assignment(
+                machine_name="laptop", repo_name="api",
+                issue_number=42, issue_title="Fix auth",
+                assignment_id="abc123", status="running",
+            ),
+        ])
+        health = {
+            "laptop": {
+                "state": "online", "reason": "", "latency_ms": 7.5,
+                "received_at": time.time(),
+                "health": {
+                    "schema": 1, "checked_at": time.time(), "severity": "ok",
+                    "results": [], "worktree_bytes": 4096,
+                    "agent_runtime_version": "0.42.0",
+                },
+            },
+        }
+        client = _client()
+        with (
+            patch("coord.state.load_machine_health", return_value=health),
+            patch("coord.dashboard.server.read_board", return_value=board),
+        ):
+            r = client.get("/api/machines")
+
+        assert r.status_code == 200
+        spec = openapi_spec()
+        schema = self._schema_for(spec, "/api/machines")
+        errors = validate_json_schema(r.json(), schema, spec["components"]["schemas"])
+        assert errors == [], errors
+        # A machine with no running work at all (the idle-machine case)
+        # must validate too -- `assignments` absent entirely, not null.
+        with (
+            patch("coord.state.load_machine_health", return_value={}),
+            patch("coord.dashboard.server.read_board", return_value=Board()),
+        ):
+            r2 = client.get("/api/machines")
+        errors2 = validate_json_schema(r2.json(), schema, spec["components"]["schemas"])
+        assert errors2 == [], errors2
+
+    def test_machines_stats_response_matches_its_schema(self) -> None:
+        now = time.time()
+        board = Board(completed=[
+            Assignment(
+                machine_name="laptop", repo_name="api",
+                issue_number=10, issue_title="Older done",
+                assignment_id="done_old", status="done",
+                dispatched_at=now - 200, finished_at=now - 100,
+            ),
+            Assignment(
+                machine_name="laptop", repo_name="api",
+                issue_number=11, issue_title="Newer failure",
+                assignment_id="fail_new", status="failed",
+                dispatched_at=now - 50, finished_at=now - 10,
+            ),
+        ])
+        client = _client()
+        with patch("coord.dashboard.server.read_board", return_value=board):
+            r = client.get("/api/machines/stats")
+
+        assert r.status_code == 200
+        spec = openapi_spec()
+        schema = self._schema_for(spec, "/api/machines/stats")
+        errors = validate_json_schema(r.json(), schema, spec["components"]["schemas"])
+        assert errors == [], errors
+
+    def test_machines_health_response_matches_its_schema(self) -> None:
+        now = time.time()
+        full_result = {
+            "key": "disk", "check_id": "disk", "scope": "machine",
+            "subject": "/home", "title": "disk", "label": "disk /home",
+            "severity": "warn", "headroom": "8% free",
+            "threshold": "crit at 5%", "detail": "", "trend": None,
+            "values": {"free_gb": 12}, "error": None,
+        }
+        health = {
+            "laptop": {
+                "state": "online", "reason": "", "latency_ms": 7.5,
+                "received_at": now,
+                "health": {
+                    "schema": 1, "checked_at": now, "severity": "warn",
+                    "results": [full_result], "worktree_bytes": 4096,
+                    "agent_runtime_version": "0.42.0",
+                },
+            },
+        }
+        client = _client()
+        with patch("coord.state.load_machine_health", return_value=health):
+            r = client.get("/api/machines/health")
+
+        assert r.status_code == 200
+        spec = openapi_spec()
+        schema = self._schema_for(spec, "/api/machines/health")
+        errors = validate_json_schema(r.json(), schema, spec["components"]["schemas"])
+        assert errors == [], errors
+
+    def test_machines_health_unreachable_error_matches_its_schema(
+        self, monkeypatch
+    ) -> None:
+        import httpx
+
+        import coord.client as cc
+
+        monkeypatch.setattr(
+            cc, "resolve_board_service",
+            lambda *a, **k: cc.ServiceConfig("http://daemon:7435"),
+        )
+        monkeypatch.setattr(
+            cc.httpx, "get",
+            lambda *a, **k: (_ for _ in ()).throw(httpx.ConnectError("refused")),
+        )
+
+        client = _client()
+        r = client.get("/api/machines/health")
+
+        assert r.status_code == 503
+        spec = openapi_spec()
+        schema = self._schema_for(spec, "/api/machines/health", status="503")
+        errors = validate_json_schema(r.json(), schema, spec["components"]["schemas"])
+        assert errors == [], errors
+
+    def test_machine_metrics_response_matches_its_schema(self, monkeypatch) -> None:
+        import coord.client as cc
+
+        payload = {
+            "schema": 1, "generated_at": 1234.5, "since": None, "resolution": None,
+            "machines": {
+                "laptop": [
+                    {"timestamp": 1234.5, "status": "ok", "cpu_percent": 12.0,
+                     "mem_percent": 30.0, "mem_used_mb": 100.0,
+                     "mem_total_mb": 400.0, "reason": ""},
+                    {"timestamp": 1249.5, "status": "unknown", "cpu_percent": None,
+                     "mem_percent": None, "mem_used_mb": None,
+                     "mem_total_mb": None, "reason": "psutil not installed"},
+                ],
+            },
+        }
+
+        def fake_get(url, **kw):
+            class _Resp:
+                status_code = 200
+
+                def raise_for_status(self):
+                    return None
+
+                def json(self):
+                    return payload
+
+            return _Resp()
+
+        monkeypatch.setattr(cc.httpx, "get", fake_get)
+
+        client = _client()
+        r = client.get("/api/machines/metrics")
+
+        assert r.status_code == 200
+        spec = openapi_spec()
+        schema = self._schema_for(spec, "/api/machines/metrics")
+        errors = validate_json_schema(r.json(), schema, spec["components"]["schemas"])
+        assert errors == [], errors
+
+    def test_machine_metrics_bad_request_matches_its_schema(self, monkeypatch) -> None:
+        """A malformed since/resolution is the DAEMON's 400, forwarded as-is
+        (see ``test_daemon_400_is_forwarded_as_a_caller_error_not_folded_into_unreachable``
+        above) -- so the daemon call itself has to be mocked to return one."""
+        import coord.client as cc
+
+        def fake_get(url, **kw):
+            class _Resp:
+                status_code = 400
+
+                def raise_for_status(self):
+                    import httpx
+
+                    raise httpx.HTTPStatusError("boom", request=None, response=self)
+
+                def json(self):
+                    return {"error": "bad resolution='0': must be a positive integer"}
+
+            return _Resp()
+
+        monkeypatch.setattr(cc.httpx, "get", fake_get)
+
+        client = _client()
+        r = client.get("/api/machines/metrics", params={"resolution": "0"})
+
+        assert r.status_code == 400
+        spec = openapi_spec()
+        schema = self._schema_for(spec, "/api/machines/metrics", status="400")
+        errors = validate_json_schema(r.json(), schema, spec["components"]["schemas"])
+        assert errors == [], errors
+
+    def test_machine_metrics_unreachable_error_matches_its_schema(
+        self, monkeypatch
+    ) -> None:
+        import httpx
+
+        import coord.client as cc
+
+        monkeypatch.setattr(
+            cc.httpx, "get",
+            lambda *a, **k: (_ for _ in ()).throw(httpx.ConnectError("refused")),
+        )
+
+        client = _client()
+        r = client.get("/api/machines/metrics")
+
+        assert r.status_code == 503
+        spec = openapi_spec()
+        schema = self._schema_for(spec, "/api/machines/metrics", status="503")
+        errors = validate_json_schema(r.json(), schema, spec["components"]["schemas"])
+        assert errors == [], errors