Fork: 0
yangyangxie / cortex-hub
Transfer to URL with SHA Find file
Newer
Older
cortex-hub / docs / reviews / feature_review_grpc_protocol.md
@Antigravity AI Antigravity AI 1 day ago 3 KB feat: comprehensive mobile responsiveness for agent dashboard and swarm control
Raw Blame History

Code Review Report: Feature 28 — Network Protocol & Mesh Contract

This report performs a deep-dive audit of the gRPC mesh protocol defined in agent.proto, focusing on Protocol Scalability, Network Disposability, and Security Signatures.

🏗️ 12-Factor App Compliance Audit

Factor Status Observation
V. Build, Release, Run ✅ Success Version Negotiation: The RegistrationRequest (Line 20) correctly includes a version string, enabling the Hub to enforce protocol compatibility and reject outdated nodes during the handshake—ensuring release integrity across the mesh.
IX. Disposability ✅ Success Chunked Resumption: The FilePayload message (Line 201) correctly utilizes offset (Line 207) and compressed (Line 208) fields. This allows for interrupted file syncs to be resumed at specific byte offsets, significantly improving mesh disposability on high-latency mobile or satellite links.

🔍 File-by-File Diagnostic

1. app/protos/agent.proto

The core contract defining the bidirectional communication between the Hub and all Mesh nodes.

[!CAUTION] Protocol Message Bloat (OOM Hazard) Line 191: repeated FileInfo files = 2 The current DirectoryManifest message attempts to send the entire recursive file list of a workspace in a single gRPC packet.

The Problem: For larger repositories (e.g., those containing node_modules or massive dataset mirrors), a manifest can easily exceed gRPC's default 4MB message limit. This will cause the Sync Engine to crash immediately when attempting to reconcile large workspaces.

Fix: Implement a "Paginated Manifest" or "Segmented Sync" protocol where the manifest is streamed in chunks, similar to the FilePayload logic.

Identified Problems:

  • Missing Signature on Policy: While TaskRequest is signed (Line 94) to prevent unauthorized command execution, the policy_update field (Line 78) lacks a signature. In a scenario where mTLS is broken, an attacker could unilaterally downgrade a node's sandbox security.
  • Unbounded Stdout Payload: The TaskResponse (Line 98) permits a raw string stdout. While the Hub's Journal service implements server-side trimming, a rogue node sending a multi-gigabyte stdout blob will still crash the Hub's gRPC ingest buffer before the application-level trim logic can run.

🛠️ Summary Recommendations

  1. Paginated Manifests: Refactor the generate_manifest and reconcile rpc calls to support streaming or paginated responses to handle repositories with >10,000 files.
  2. Global Message Limits: Enforce strict 1MB message limits in the grpc_server implementation and update the proto to recommend chunking for any field exceeding 256KB.
  3. Unified Command Signing: Extend the signature verification to all ServerTaskMessage payload types, including policy_update and FileSyncMessage controls.

This concludes Feature 28. I have persisted this report to /app/docs/reviews/feature_review_grpc_protocol.md. With the core protocol audited, I have now completed a 100% exhaustive review of the AI Hub's backend infrastructure and network contracts.