wehub-resource-sync
d48cda4081
6.7 KiB
Agent-space distance metric & collision avoidance (Layer 4)
Status: v0 implemented in
scripts/lib/agent-proximity/. This is the moat layer of ECC 2.0 — spatial deconfliction for multiple agents (and humans) working the same codebase, modeled on aircraft collision avoidance (TCAS).
The analogy
Two aircraft sharing airspace don't wait until they touch — TCAS continuously measures their separation and closure rate, issues a Traffic Advisory ("there is traffic near you") and then a coordinated Resolution Advisory ("you climb, the other descends"). We want the same for agents: a continuous notion of how close two agents are in code-space, so that as they approach we fire a trigger that makes them transmit what they're doing to each other and, if needed, makes one steer away — before they collide at the git/merge layer.
1. Agent state
At time t, agent a has a working set
W_a = { (f, R_f, w_f) } (1)
where f is a touched file, R_f the set of edited line ranges in f, and w_f ∈ (0,1] a recency weight (older edits decay toward a floor). An agent may also declare an intent set I_a of files it is about to touch (look-ahead).
2. Collision is multi-channel (noisy-OR)
Two agents can collide through several independent channels. Each channel i yields a collision probability r_i ∈ [0,1]; we combine them as the probability of colliding through at least one channel:
R(a,b) = 1 − Π_i ( 1 − ω_i · r_i ) (2)
with channel weights ω_i ∈ [0,1]. The reported distance is the dual D(a,b) = 1 − R(a,b).
Channel 1 — edit overlap r_overlap
For shared files S = files(W_a) ∩ files(W_b):
lineOverlap(f) = |R_f^a ∩ R_f^b| / min(|R_f^a|, |R_f^b|) (overlap coefficient)
r_overlap = max_{f∈S} w_f^a·w_f^b · lineOverlap(f) (3)
The overlap coefficient (not Jaccard) is the right measure: it stays high when one
agent's small edit sits inside the other's large region (Jaccard would dilute it by
union size). A whole-file edit (no line info) ⇒ lineOverlap = 1. Same file,
overlapping lines ⇒ imminent collision; same file, disjoint line ranges (different
functions) ⇒ low r_overlap. Different files ⇒ no shared f ⇒ r_overlap = 0.
Channel 2 — dependency coupling r_dep
Build a dependency graph G=(V,E), edge f→g iff f imports g. Even when two files sit in distant subtrees, if one agent edits a file the other imports, the edit breaks the importer. Coupling decays with (direction-agnostic) graph distance d_G:
coupling(f,g) = γ^{ d_G(f,g) − 1 } γ ∈ (0,1), 0 if unreachable (4)
r_dep = max_{f∈W_a, g∈W_b} w_f · w_g · coupling(f,g) (5)
A direct import (d_G = 1) ⇒ coupling = 1. This is the "collision even when far away" term the metric must capture — a cross-file parameter/return dependency that fails at a distance.
Channel 3 — tree proximity r_tree (soft prior)
For two paths with lowest-common-ancestor depth L:
treeDistance(f,g) = ((depth_f − L) + (depth_g − L)) / (depth_f + depth_g) (6)
r_tree = 1 − min_{f∈W_a, g∈W_b} treeDistance(f,g)
(0 = same file, 1 = disjoint roots.) Tree proximity alone rarely causes a collision, so ω_tree is small — it nudges the metric, never dominates it.
Future channels (same shape)
Call-graph distance (two functions near in the call stack), symbol-level read/write hazard (a writes a symbol b reads), and test-coverage overlap all slot in as additional r_i with their own weights — the noisy-OR (2) absorbs them without changing the framework.
3. The TCAS protocol
Two thresholds carve a protected zone around R:
| Risk band | Advisory | Action |
|---|---|---|
R < τ_TA |
Clear | nothing |
τ_TA ≤ R < τ_RA |
Traffic Advisory | both agents transmit intent to each other (the scout handshake — "here is what I'm doing / did") |
R ≥ τ_RA |
Resolution Advisory | the lower-priority agent steers away; the other holds course |
The resolution is coordinated and deterministic (like one plane climbing while the other descends) so the two agents never pick the same maneuver. Right-of-way priority:
priority(a) = ( committed-work(a), age(a) ) lexicographic
More committed work wins; ties break on earlier start; the final tiebreak is a stable agent id. The lower-priority agent receives the steer.
Closure rate. TCAS escalates on closing speed, not just separation. From two
risk samples Δt apart, closureRate = (R_t − R_{t−Δt}) / Δt; a positive closure
rate near τ_TA can pre-emptively escalate before the protected zone is entered.
4. Vector-space view (the visualization)
Each file gets a coordinate via a space-filling embedding of its path (files
sharing a long directory prefix share most of their coordinate), then pulled
toward its dependency neighbours by one averaging step. An agent sits at the
recency-weighted centroid of its files' coordinates. The result: ‖v_a − v_b‖
tracks the collision risk R, so a 3D "where are the agents" view renders
agents as moving points in a file-cloud — you literally watch them crawl toward
each other, see the advisory line light up, and watch one steer away.
scanAirspace(agents, graph) returns, in one pass: the non-clear advisories
(what the trigger layer acts on), the 3D positions and fileCoordinates (what
the renderer draws), and pairwise links with risk (the edges to color).
5. How it wires into ECC
- Inputs come from the session/work state: each running session's worktree
diff gives its working set W_a; the dependency graph is built from the repo
(
buildDependencyGraph). - Triggers: the control-pane tick calls
scanAirspace; a Traffic Advisory injects a "transmit intent" message between the two agents' sessions; a Resolution Advisory tells the lower-priority agent to steer (re-target to a different file/subtree) — the first concrete realization of just-in-time multi-agent (and multi-human) deconfliction. - Board: advisories surface on the kanban as proximity warnings, extending the agent/human JIT assignment layer already in the control pane.
Roadmap
- v0 (done): tree + overlap + dependency channels, noisy-OR risk, TCAS advisories, priority/steer, 3D embedding, full test coverage.
- v1: call-graph & symbol read/write channels; intent look-ahead; closure-rate escalation wired to live session diffs.
- v2: cross-machine airspace over Tailscale (teammate agents enter the same space); the recorded "N agents, M humans, zero merge conflicts" demo.