@agentic-qe/v3 3.0.0-alpha.5 → 3.0.0-alpha.7

package/implementation/adrs/ADR-031-strange-loop-self-awareness.md

@@ -1,484 +0,0 @@
-# ADR-031: Strange Loop Self-Awareness
-
-**Status:** Accepted
-**Date:** 2026-01-10
-**Decision Makers:** Architecture Team
-**Source:** RuVector MinCut Analysis (examples/mincut/strange_loop)
-
----
-
-## Context
-
-Current v3 AQE agents operate without self-awareness:
-- Agents don't observe their own swarm connectivity
-- No detection of single points of failure (bottlenecks)
-- No self-healing when agents become isolated
-- External monitoring required for swarm health
-
-RuVector's Strange Loop example demonstrates a powerful pattern:
-> "You look in a mirror. You see yourself looking. You adjust your hair *because* you saw it was messy. The act of observing changed what you observed."
-
-This creates **genuine autonomy** - the system doesn't need external monitoring because it *is* its own monitor.
-
-### The Strange Loop Pattern
-
-```
-┌──────────────────────────────────────────┐
-│              STRANGE LOOP                │
-│                                          │
-│   Observe ──► Model ──► Decide ──► Act   │
-│      ▲                              │    │
-│      └──────────────────────────────┘    │
-│                                          │
-│   "I see I'm weak here, so I strengthen" │
-└──────────────────────────────────────────┘
-```
-
----
-
-## Decision
-
-**Implement strange loop self-awareness enabling agents to observe, model, and heal their own swarm connectivity.**
-
-### Core Components
-
-#### 1. Self-Observation Protocol
-
-```typescript
-export interface SwarmHealthObservation {
-  /** Timestamp of observation */
-  timestamp: number;
-
-  /** Observer agent ID */
-  observerId: string;
-
-  /** Observed swarm topology */
-  topology: SwarmTopology;
-
-  /** Connectivity metrics */
-  connectivity: {
-    /** Minimum cut value (λ) */
-    minCut: number;
-
-    /** Number of connected components */
-    components: number;
-
-    /** Bottleneck agents (single points of failure) */
-    bottlenecks: string[];
-
-    /** Average path length between agents */
-    avgPathLength: number;
-
-    /** Clustering coefficient */
-    clusteringCoefficient: number;
-  };
-
-  /** Agent-specific health */
-  agentHealth: Map<string, AgentHealthMetrics>;
-
-  /** Detected vulnerabilities */
-  vulnerabilities: SwarmVulnerability[];
-}
-
-export interface SwarmTopology {
-  /** Agent nodes */
-  agents: AgentNode[];
-
-  /** Communication edges */
-  edges: CommunicationEdge[];
-
-  /** Current topology type */
-  type: 'mesh' | 'hierarchical' | 'ring' | 'star' | 'hybrid';
-}
-
-export interface AgentHealthMetrics {
-  /** Agent responsiveness (0-1) */
-  responsiveness: number;
-
-  /** Task completion rate (0-1) */
-  taskCompletionRate: number;
-
-  /** Memory utilization (0-1) */
-  memoryUtilization: number;
-
-  /** Active connections count */
-  activeConnections: number;
-
-  /** Is this agent a bottleneck? */
-  isBottleneck: boolean;
-
-  /** Degree (number of connections) */
-  degree: number;
-}
-```
-
-#### 2. Self-Modeling
-
-```typescript
-export class SwarmSelfModel {
-  private observationHistory: SwarmHealthObservation[] = [];
-  private currentModel: SwarmModel;
-
-  /** Update model based on new observation */
-  updateModel(observation: SwarmHealthObservation): SwarmModelDelta {
-    this.observationHistory.push(observation);
-
-    // Detect changes from previous state
-    const delta = this.computeDelta(observation);
-
-    // Update internal model
-    this.currentModel = this.mergeWithHistory(observation);
-
-    return delta;
-  }
-
-  /** Find bottleneck agents using min-cut analysis */
-  findBottlenecks(): BottleneckAnalysis {
-    const topology = this.currentModel.topology;
-
-    // Compute vertex connectivity
-    const bottlenecks: BottleneckInfo[] = [];
-
-    for (const agent of topology.agents) {
-      // Check if removing this agent disconnects the graph
-      const hypotheticalTopology = this.removeAgent(topology, agent.id);
-      const components = this.countComponents(hypotheticalTopology);
-
-      if (components > 1) {
-        bottlenecks.push({
-          agentId: agent.id,
-          criticality: this.computeCriticality(agent, topology),
-          affectedAgents: this.findAffectedAgents(agent, topology),
-          recommendation: this.suggestMitigation(agent, topology),
-        });
-      }
-    }
-
-    return {
-      bottlenecks,
-      overallHealth: this.computeOverallHealth(bottlenecks),
-      minCut: this.computeMinCut(topology),
-    };
-  }
-
-  /** Predict future vulnerabilities based on trends */
-  predictVulnerabilities(): PredictedVulnerability[] {
-    if (this.observationHistory.length < 3) {
-      return [];
-    }
-
-    const predictions: PredictedVulnerability[] = [];
-
-    // Analyze connectivity trend
-    const minCutTrend = this.analyzeTrend(
-      this.observationHistory.map(o => o.connectivity.minCut)
-    );
-
-    if (minCutTrend.direction === 'decreasing' && minCutTrend.rate > 0.1) {
-      predictions.push({
-        type: 'connectivity_degradation',
-        probability: Math.min(minCutTrend.rate * 2, 0.95),
-        timeToOccurrence: this.estimateTimeToThreshold(minCutTrend, 1),
-        suggestedAction: 'add_redundant_connections',
-      });
-    }
-
-    // Analyze agent health trends
-    for (const [agentId, healthHistory] of this.aggregateAgentHealth()) {
-      const responsivenessTrend = this.analyzeTrend(
-        healthHistory.map(h => h.responsiveness)
-      );
-
-      if (responsivenessTrend.direction === 'decreasing' && responsivenessTrend.rate > 0.2) {
-        predictions.push({
-          type: 'agent_degradation',
-          agentId,
-          probability: Math.min(responsivenessTrend.rate * 2.5, 0.9),
-          timeToOccurrence: this.estimateTimeToThreshold(responsivenessTrend, 0.5),
-          suggestedAction: 'spawn_backup_agent',
-        });
-      }
-    }
-
-    return predictions;
-  }
-}
-```
-
-#### 3. Self-Healing Actions
-
-```typescript
-export interface SelfHealingAction {
-  type: SelfHealingActionType;
-  targetAgentId?: string;
-  priority: 'low' | 'medium' | 'high' | 'critical';
-  estimatedImpact: number;
-  reversible: boolean;
-}
-
-export type SelfHealingActionType =
-  | 'spawn_redundant_agent'
-  | 'add_connection'
-  | 'redistribute_load'
-  | 'restart_agent'
-  | 'isolate_agent'
-  | 'promote_to_coordinator'
-  | 'demote_coordinator'
-  | 'trigger_failover';
-
-export class SelfHealingController {
-  private model: SwarmSelfModel;
-  private actionHistory: ExecutedAction[] = [];
-
-  /** Decide what healing action to take */
-  async decide(observation: SwarmHealthObservation): Promise<SelfHealingAction[]> {
-    const delta = this.model.updateModel(observation);
-    const actions: SelfHealingAction[] = [];
-
-    // Check for bottlenecks
-    const bottleneckAnalysis = this.model.findBottlenecks();
-
-    for (const bottleneck of bottleneckAnalysis.bottlenecks) {
-      if (bottleneck.criticality > 0.8) {
-        actions.push({
-          type: 'spawn_redundant_agent',
-          targetAgentId: bottleneck.agentId,
-          priority: 'critical',
-          estimatedImpact: 0.9,
-          reversible: true,
-        });
-      } else if (bottleneck.criticality > 0.5) {
-        actions.push({
-          type: 'add_connection',
-          targetAgentId: bottleneck.agentId,
-          priority: 'high',
-          estimatedImpact: 0.6,
-          reversible: true,
-        });
-      }
-    }
-
-    // Check for predicted vulnerabilities
-    const predictions = this.model.predictVulnerabilities();
-
-    for (const prediction of predictions) {
-      if (prediction.probability > 0.7) {
-        actions.push(this.mapPredictionToAction(prediction));
-      }
-    }
-
-    // Check for overloaded agents
-    for (const [agentId, health] of observation.agentHealth) {
-      if (health.memoryUtilization > 0.9) {
-        actions.push({
-          type: 'redistribute_load',
-          targetAgentId: agentId,
-          priority: 'high',
-          estimatedImpact: 0.5,
-          reversible: true,
-        });
-      }
-    }
-
-    return this.prioritizeActions(actions);
-  }
-
-  /** Execute healing action */
-  async act(action: SelfHealingAction): Promise<ActionResult> {
-    const startTime = Date.now();
-
-    try {
-      switch (action.type) {
-        case 'spawn_redundant_agent':
-          return await this.spawnRedundantAgent(action.targetAgentId!);
-
-        case 'add_connection':
-          return await this.addConnection(action.targetAgentId!);
-
-        case 'redistribute_load':
-          return await this.redistributeLoad(action.targetAgentId!);
-
-        case 'restart_agent':
-          return await this.restartAgent(action.targetAgentId!);
-
-        case 'isolate_agent':
-          return await this.isolateAgent(action.targetAgentId!);
-
-        case 'trigger_failover':
-          return await this.triggerFailover(action.targetAgentId!);
-
-        default:
-          throw new Error(`Unknown action type: ${action.type}`);
-      }
-    } finally {
-      this.actionHistory.push({
-        action,
-        timestamp: startTime,
-        duration: Date.now() - startTime,
-      });
-    }
-  }
-
-  private async spawnRedundantAgent(targetAgentId: string): Promise<ActionResult> {
-    const targetAgent = await this.getAgentInfo(targetAgentId);
-
-    // Clone the agent's configuration
-    const newAgentId = `${targetAgentId}-redundant-${Date.now()}`;
-
-    await this.agentSpawner.spawn({
-      id: newAgentId,
-      type: targetAgent.type,
-      config: targetAgent.config,
-      connections: [targetAgentId, ...targetAgent.connections],
-    });
-
-    return {
-      success: true,
-      message: `Spawned redundant agent ${newAgentId} to reduce bottleneck at ${targetAgentId}`,
-      newState: await this.observe(),
-    };
-  }
-}
-```
-
-#### 4. Strange Loop Orchestrator
-
-```typescript
-export class StrangeLoopOrchestrator {
-  private observer: SwarmObserver;
-  private model: SwarmSelfModel;
-  private healer: SelfHealingController;
-  private loopInterval: number = 5000; // 5 seconds
-
-  /** Start the strange loop */
-  async start(): Promise<void> {
-    console.log('[StrangeLoop] Starting self-observation cycle');
-
-    while (this.running) {
-      try {
-        // OBSERVE: Gather swarm state
-        const observation = await this.observer.observe();
-
-        // MODEL: Update internal representation
-        const delta = this.model.updateModel(observation);
-
-        // DECIDE: Determine if healing is needed
-        const actions = await this.healer.decide(observation);
-
-        if (actions.length > 0) {
-          console.log(`[StrangeLoop] Detected ${actions.length} healing opportunities`);
-
-          // ACT: Execute healing actions
-          for (const action of actions) {
-            if (action.priority === 'critical' || action.priority === 'high') {
-              const result = await this.healer.act(action);
-              console.log(`[StrangeLoop] Executed ${action.type}: ${result.message}`);
-            }
-          }
-        }
-
-        // Store observation for learning
-        await this.storeObservation(observation, delta, actions);
-
-      } catch (error) {
-        console.error('[StrangeLoop] Error in self-observation cycle:', error);
-      }
-
-      await this.sleep(this.loopInterval);
-    }
-  }
-
-  /** The agent observes itself being the bottleneck */
-  async selfDiagnose(): Promise<SelfDiagnosis> {
-    const observation = await this.observer.observe();
-    const myId = this.getMyAgentId();
-
-    const myHealth = observation.agentHealth.get(myId);
-    const amIBottleneck = observation.connectivity.bottlenecks.includes(myId);
-
-    return {
-      agentId: myId,
-      isHealthy: myHealth ? myHealth.responsiveness > 0.8 : false,
-      isBottleneck: amIBottleneck,
-      recommendations: amIBottleneck
-        ? ['Request backup agent', 'Reduce task queue', 'Offload connections']
-        : [],
-      overallSwarmHealth: observation.connectivity.minCut / 10, // Normalize to 0-1
-    };
-  }
-}
-```
-
----
-
-## Implementation Plan
-
-### Phase 1: Observer Module (Days 1-2)
-```
-v3/src/strange-loop/
-├── index.ts
-├── types.ts
-├── swarm-observer.ts        # Collect swarm state
-├── topology-analyzer.ts     # Analyze graph structure
-└── min-cut-calculator.ts    # Find bottlenecks
-```
-
-### Phase 2: Self-Model (Day 3)
-```
-├── self-model.ts           # SwarmSelfModel
-├── trend-analyzer.ts       # Predict vulnerabilities
-└── history-store.ts        # Observation persistence
-```
-
-### Phase 3: Self-Healing (Days 4-5)
-```
-├── healing-controller.ts   # SelfHealingController
-├── action-executor.ts      # Execute healing actions
-└── strange-loop.ts         # StrangeLoopOrchestrator
-```
-
----
-
-## Integration with Swarm Coordinators
-
-```typescript
-// In queen-coordinator.ts
-import { StrangeLoopOrchestrator } from '../strange-loop';
-
-export class QueenCoordinator {
-  private strangeLoop: StrangeLoopOrchestrator;
-
-  async initialize(): Promise<void> {
-    // Start self-observation
-    this.strangeLoop = new StrangeLoopOrchestrator(this.swarm);
-    await this.strangeLoop.start();
-  }
-
-  /** Called when strange loop detects bottleneck at this coordinator */
-  async onSelfBottleneckDetected(): Promise<void> {
-    // The coordinator can observe that IT is the bottleneck
-    // and take action to delegate more authority
-    console.log('[Queen] I am a bottleneck. Promoting workers to sub-coordinators.');
-    await this.promoteWorkersToCoordinators();
-  }
-}
-```
-
----
-
-## Success Metrics
-
-- [ ] Swarm observation every 5 seconds
-- [ ] Bottleneck detection <100ms
-- [ ] Self-healing action execution <1s
-- [ ] Trend prediction accuracy >70%
-- [ ] 0 human intervention for common issues
-- [ ] 60+ unit tests
-
----
-
-## References
-
-- [ruvector-mincut examples/mincut/strange_loop](https://github.com/ruvnet/ruvector/tree/main/examples/mincut/strange_loop)
-- [Hofstadter, "Godel, Escher, Bach"](https://en.wikipedia.org/wiki/Strange_loop)
-- Self-organizing systems theory