Fork: 0
yangyangxie / cortex-hub
Transfer to URL with SHA Find file
Newer
Older
cortex-hub / docs / architecture / workspace_mirroring_design.md
@Antigravity AI Antigravity AI 17 hours ago 4 KB feat: phase 5 - implement automatic drift detection and recovery for node reconnection
Raw Blame History

Cortex Agent Node: Workspace Mirroring & Real-time Sync

📌 Overview

This document outlines the architecture for the Cortex Workspace Sync System, designed to provide the AI with "Zero-latency Perception" of remote node files while maintaining high-fidelity synchronization across a collaborative agent mesh.

The core innovation is the "Ghost Mirror" pattern, where the Cortex Server maintains a local, hash-verified copy of the node's workspace to allow instantaneous AI analysis without gRPC round-trips for every file read.

🏗️ Core Concepts

1. The Session-Based Attachment

When a user begins an AI session, they can "Attach Nodes" to that specific execution context.

  • Workspace Selection: During attachment, the user chooses the Source of Truth (SoT) for the files.
  • Unique Identification: Every sync folder in a node uses a session-specific UUID to prevent path collisions.

2. Dual Source-of-Truth Models

A. Server-Primary (The "Scratchpad" Model)

Used for new projects or AI-generated tasks.

  • Root: A temporary or persistent directory on the Cortex Server.
  • Propagation: On initialization, the server pushes the initial manifest and data to all attached nodes.
  • Lifecycle: Node folders are "mirrors" of the server. Any code generated by the AI on the server is instantly pushed down to the nodes for execution.

B. Node-Primary (The "Local Codebase" Model)

Used for existing local repositories (e.g., a professional dev machine).

  • Root: A specific local folder on one "Lead" Agent Node.
  • Mirroring: The server pulls the initial state to create a local Ghost Mirror.
  • Change Detection: The Lead Node uses OS-level watchers (inotify, FSEvents) to detect changes and stream deltas back to the server.
  • Propagation: The server then broadcasts these changes to any other "Support" nodes attached to the session.

🚀 Technical Architecture

1. Change Detection & Reconciliation

  • Watcher-Driven Deltas: Nodes stream (File Path, Hash, ContentDelta) messages via the gRPC TaskStream whenever local files change.
  • Hashed State Checks: Before the AI begins a complex multi-file refactor, the server executes a quick "Fingerprint" check (comparing top-level directory hashes) to ensure the Ghost Mirror isn't drifting from the Node.

2. Efficiency & Large Data Handling

  • Cortex-Ignore: Native support for .cortexignore (and inherited .gitignore) to block heavy assets (node_modules, .git, .venv).
  • Chunked Deduplication: Using chunk-based transfer to only send binary changes, minimizing bandwidth during repeated refactors.

3. Conflict Resolution & Safety

  • Workspace Locking: During AI "Write" operations, the target node's sync folder can be briefly locked to prevent concurrent manual edits from corrupting the refactor.
  • Deterministic Reconciliation: If a conflict is detected (Node changed during AI planning), the server enters a Reconcile Mode, forcing a pull of the node state before retrying the edit.

🛠️ Implementation Phasing

Phase 1: Ghost Mirror Foundations

  • Implement FSMirror service on the Orchestrator.
  • Implement basic gRPC FileSync messages in agent.proto.
  • support for server-to-node initial push.

Phase 2: Active Watchers & Multi-Node Sync

  • Integrate local directory watchers on Agent Nodes.
  • Implement node-to-server delta streaming.
  • Multi-node propagation (Server broadcasts Lead Node updates to Support Nodes).

Phase 3: Conflict Handling & Optimization

  • Implementation of .cortexignore and .gitignore filtering.
  • Workspace state locking and concurrency guards.
  • Dynamic reloading of ignore rules on change.

Phase 4: Browser & Skill Integration

  • Integrate browser download handling into mirrored workspace.
  • Implement dynamic session mounting for agent skills (CWD sharing).

Phase 5: Distributed Conflict Resolution & Resiliency

  • Implement incremental hash-based drift detection.
  • Finalize automatic drift recovery logic for reconnection.