@oswaldzsh/devhive 0.1.0

package/orchestrator/convergence_gate.py

@@ -0,0 +1,133 @@
+"""Convergence Gate — determines whether to pass, retry, or escalate."""
+
+import hashlib
+import json
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Optional
+
+from protocol.schemas import (
+    Task, ExecutionHandoff, Verdict, SemanticVerdict, ConvergenceDecision,
+    ConcurrencyAction, EscalationReport,
+)
+from verification.diagnostic import DiagnosticAggregator, AggregatorResult
+
+
+@dataclass
+class StageState:
+    stage: str
+    attempt: int
+    fingerprint: str
+
+
+class ConvergenceGate:
+    """Implements L1/L2 convergence checks with escalation rules."""
+
+    def __init__(self, config: dict = None):
+        self.config = config or {}
+        self.max_l1_retries = config.get("l1_max_retries", 3)
+        self.max_l2_retries = config.get("l2_max_retries", 2)
+        self.loop_window = config.get("loop_detection_window", 5)
+        self.loop_threshold = config.get("loop_similarity_threshold", 0.8)
+        self.aggregator = DiagnosticAggregator(config)
+        self._stage_history: dict[str, deque[StageState]] = {}
+
+    def evaluate_l1(self, task: Task, static: Verdict, dynamic: Verdict,
+                    attempt: int) -> ConvergenceDecision:
+        """Evaluate L1 convergence."""
+        result = self.aggregator.aggregate_l1(static, dynamic, task.id)
+
+        # Check retry limit
+        if result.action == ConcurrencyAction.FIX and attempt >= self.max_l1_retries:
+            return ConvergenceDecision(
+                action=ConcurrencyAction.ESCALATE,
+                reason=f"L1 retry limit ({self.max_l1_retries}) exceeded",
+                escalation=self._build_escalation(task, result),
+            )
+
+        # Check for loop detection
+        if self._detect_loop(task.id, "L1"):
+            return ConvergenceDecision(
+                action=ConcurrencyAction.ESCALATE,
+                reason="Loop detected in L1 verification",
+                escalation=self._build_escalation(task, result),
+            )
+
+        return ConvergenceDecision(
+            action=result.action,
+            reason=result.reason,
+            fix_strategy=result.fix_strategy,
+        )
+
+    def evaluate_l2(self, task: Task, static: Verdict, dynamic: Verdict,
+                    semantic: SemanticVerdict, mutation: Optional[Verdict],
+                    attempt: int) -> ConvergenceDecision:
+        """Evaluate L2 convergence."""
+        result = self.aggregator.aggregate_l2(
+            static, dynamic, semantic, mutation, task.id
+        )
+
+        if result.action == ConcurrencyAction.FIX and attempt >= self.max_l2_retries:
+            return ConvergenceDecision(
+                action=ConcurrencyAction.ESCALATE,
+                reason=f"L2 retry limit ({self.max_l2_retries}) exceeded",
+                escalation=self._build_escalation(task, result),
+            )
+
+        return ConvergenceDecision(
+            action=result.action,
+            reason=result.reason,
+            fix_strategy=result.fix_strategy,
+        )
+
+    def check_sensitive_modules(self, task: Task) -> bool:
+        """Check if the task touches modules that require human approval."""
+        sensitive = set(self.config.get("escalation", {}).get(
+            "require_approval_for", []))
+        task_modules = set(task.spec.sensitive_modules)
+        return bool(sensitive & task_modules)
+
+    def _detect_loop(self, task_id: str, stage: str) -> bool:
+        """Check if recent stage fingerprints indicate a loop."""
+        if task_id not in self._stage_history:
+            self._stage_history[task_id] = deque(maxlen=self.loop_window)
+            return False
+
+        history = self._stage_history[task_id]
+        if len(history) < self.loop_window:
+            return False
+
+        # Count similar fingerprints in the window
+        fingerprints = [h.fingerprint for h in history]
+        unique = len(set(fingerprints))
+        similarity = 1.0 - (unique / len(fingerprints))
+        return similarity >= self.loop_threshold
+
+    def record_state(self, task_id: str, stage: str, attempt: int,
+                     handoff: dict = None, verdict: dict = None):
+        """Record stage state for loop detection."""
+        if task_id not in self._stage_history:
+            self._stage_history[task_id] = deque(maxlen=self.loop_window)
+
+        # Build a fingerprint
+        data = json.dumps({
+            "stage": stage,
+            "handoff_keys": sorted(handoff.keys()) if handoff else [],
+            "verdict_overall": verdict.get("overall") if verdict else None,
+        }, sort_keys=True)
+        fingerprint = hashlib.sha256(data.encode()).hexdigest()[:16]
+
+        self._stage_history[task_id].append(StageState(
+            stage=stage, attempt=attempt, fingerprint=fingerprint,
+        ))
+
+    def _build_escalation(self, task: Task,
+                          result: AggregatorResult) -> EscalationReport:
+        from datetime import datetime, timezone
+        return EscalationReport(
+            escalation_id=f"esc-{task.id}-{datetime.now(timezone.utc).timestamp()}",
+            task_id=task.id,
+            triggered_by=result.reason,
+            current_state={"stage": task.current_stage},
+            suggested_human_action=result.reason,
+        )

package/orchestrator/engine.py

@@ -0,0 +1,353 @@
+"""Orchestrator Engine — the central event loop for DevHive."""
+
+import asyncio
+import json
+import time
+from datetime import datetime, timezone
+from typing import Optional
+
+from protocol.schemas import (
+    Task, ExecutionHandoff, Verdict, SemanticVerdict, DevHiveEvent,
+    VerdictOverall, ConcurrencyAction, TaskSpec, Priority,
+)
+from orchestrator.event_bus import EventBus
+from orchestrator.task_queue import TaskQueue
+from orchestrator.agent_pool import AgentPool, AgentType
+from orchestrator.convergence_gate import ConvergenceGate
+from verification.pipeline import VerificationPipeline
+from verification.diagnostic import DiagnosticAggregator
+from storage.checkpoint import CheckpointStore
+
+
+class Orchestrator:
+    """Central orchestrator for the DevHive multi-agent system.
+
+    Routes events between agents, manages task lifecycle,
+    and enforces convergence gates.
+    """
+
+    def __init__(self, config: dict = None):
+        self.config = config or {}
+        self.event_bus = EventBus()
+        self.task_queue = TaskQueue()
+        self.agent_pool = AgentPool(config)
+        self.verification = VerificationPipeline(config.get("verification", {}))
+        self.convergence = ConvergenceGate(config.get("convergence", {}))
+        self.checkpoint = CheckpointStore(config.get("checkpoint_db",
+                                                      "storage/devhive.db"))
+        self.diagnostic = DiagnosticAggregator(config)
+        self._task_attempts: dict[str, dict[str, int]] = {}
+
+    async def start(self, agent_counts: dict[str, int] = None):
+        """Start the orchestrator and all agent processes."""
+        counts = agent_counts or {
+            "execute": 1,
+            "static_verifier": 1,
+            "dynamic_verifier": 1,
+            "semantic_verifier": 1,
+        }
+
+        # Start agents
+        agent_type_map = {
+            "execute": AgentType.EXECUTE,
+            "static_verifier": AgentType.STATIC_VERIFIER,
+            "dynamic_verifier": AgentType.DYNAMIC_VERIFIER,
+            "semantic_verifier": AgentType.SEMANTIC_VERIFIER,
+        }
+
+        for name, count in counts.items():
+            atype = agent_type_map.get(name)
+            if atype:
+                for _ in range(count):
+                    self.agent_pool.start_agent(atype)
+
+        # Subscribe to events
+        self.event_bus.subscribe("task.created", self._on_task_created)
+        self.event_bus.subscribe("agent.idle", self._on_agent_idle)
+        self.event_bus.subscribe("handoff.emitted", self._on_handoff)
+        self.event_bus.subscribe("verdict.ready", self._on_verdict)
+        self.event_bus.subscribe("escalation.needed", self._on_escalation)
+
+        # Start event processing
+        await self.event_bus.start()
+
+        # Start result collection loop
+        asyncio.create_task(self._collect_results())
+
+    async def stop(self):
+        """Stop the orchestrator and all agents."""
+        self.agent_pool.stop_all()
+        await self.event_bus.stop()
+
+    async def submit_task(self, spec: TaskSpec, branch: str = "main",
+                          base_commit: str = "HEAD") -> str:
+        """Submit a new task to the system."""
+        import uuid
+        task_id = f"task-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}-{uuid.uuid4().hex[:6]}"
+
+        task = Task(
+            id=task_id,
+            spec=spec,
+            branch=branch,
+            base_commit=base_commit,
+        )
+
+        # Persist
+        self.checkpoint.save_task(task_id, json.dumps(spec.model_dump()),
+                                  branch, base_commit)
+
+        # Enqueue
+        self.task_queue.enqueue(task)
+
+        # Publish event
+        await self.event_bus.publish(DevHiveEvent(
+            event_type="task.created",
+            task_id=task_id,
+            payload={"task": task.model_dump()},
+        ))
+
+        return task_id
+
+    async def _on_task_created(self, event: DevHiveEvent):
+        """A new task was created — try to dispatch it."""
+        task = self.task_queue.peek(event.task_id)
+        if task:
+            await self._try_dispatch(task)
+
+    async def _on_agent_idle(self, event: DevHiveEvent):
+        """An agent became idle — try to dispatch pending tasks."""
+        agent_type_str = event.payload.get("agent_type", "")
+        agent_map = {
+            "execute": AgentType.EXECUTE,
+            "static_verifier": AgentType.STATIC_VERIFIER,
+            "dynamic_verifier": AgentType.DYNAMIC_VERIFIER,
+            "semantic_verifier": AgentType.SEMANTIC_VERIFIER,
+        }
+        atype = agent_map.get(agent_type_str)
+        if atype:
+            task = self.task_queue.next_pending(agent_type_str)
+            if task:
+                handle = self.agent_pool.get_idle(atype)
+                if handle:
+                    self.agent_pool.dispatch(handle, task)
+                    self._increment_attempt(task.id, "execute")
+                    self.checkpoint.update_task_stage(task.id, "EXECUTE")
+
+    async def _on_handoff(self, event: DevHiveEvent):
+        """Execute Agent produced a Handoff → trigger L1 verification."""
+        task_id = event.task_id
+        handoff_data = event.payload.get("handoff", {})
+        task = self.task_queue.peek(task_id)
+
+        if not task:
+            return
+
+        # Save checkpoint
+        self.checkpoint.save_checkpoint(
+            checkpoint_id=f"{task_id}-execute",
+            task_id=task_id,
+            stage="EXECUTE",
+            agent_id=event.payload.get("agent_id", ""),
+            handoff_json=json.dumps(handoff_data),
+            outcome="COMPLETED",
+        )
+        self.checkpoint.update_task_stage(task_id, "VERIFY_L1")
+
+        # Run L1 verification
+        static, dynamic = await self.verification.run_l1(task)
+
+        # Evaluate convergence
+        attempt = self._get_attempt(task_id, "l1")
+        decision = self.convergence.evaluate_l1(task, static, dynamic, attempt)
+
+        # Save checkpoints
+        self.checkpoint.save_checkpoint(
+            checkpoint_id=f"{task_id}-static",
+            task_id=task_id, stage="VERIFY_L1",
+            agent_id="static-verifier",
+            verdict_json=json.dumps(static.model_dump()),
+            outcome=static.overall.value,
+        )
+        self.checkpoint.save_checkpoint(
+            checkpoint_id=f"{task_id}-dynamic",
+            task_id=task_id, stage="VERIFY_L1",
+            agent_id="dynamic-verifier",
+            verdict_json=json.dumps(dynamic.model_dump()),
+            outcome=dynamic.overall.value,
+        )
+
+        # Act on decision
+        await self._handle_convergence(task_id, decision)
+
+    async def _on_verdict(self, event: DevHiveEvent):
+        """Handle manual verdict submission."""
+        pass  # Reserved for human-in-the-loop verdict input
+
+    async def _on_escalation(self, event: DevHiveEvent):
+        """An escalation was triggered — notify human operators."""
+        task_id = event.task_id
+        report = event.payload.get("report", {})
+        self.checkpoint.save_escalation(
+            escalation_id=report.get("escalation_id", f"esc-{task_id}"),
+            task_id=task_id,
+            report_json=json.dumps(report),
+        )
+        self._notify_human(task_id, report)
+
+    async def _handle_convergence(self, task_id: str,
+                                  decision) -> None:
+        """Process a convergence decision."""
+        task = self.task_queue.peek(task_id)
+
+        if decision.action == ConcurrencyAction.PASS:
+            # L1 passed → run L2
+            self._increment_attempt(task_id, "l2")
+            self.checkpoint.update_task_stage(task_id, "VERIFY_L2")
+            semantic = await self.verification.run_l2(task)
+            mutation = await self.verification.run_mutation(task)
+
+            l2_decision = self.convergence.evaluate_l2(
+                task, Verdict(verifier_type="static", task_id=task_id,
+                             overall=VerdictOverall.PASS, findings=[]),
+                Verdict(verifier_type="dynamic", task_id=task_id,
+                       overall=VerdictOverall.PASS, findings=[]),
+                semantic, mutation,
+                self._get_attempt(task_id, "l2"),
+            )
+
+            self.checkpoint.save_checkpoint(
+                checkpoint_id=f"{task_id}-semantic",
+                task_id=task_id, stage="VERIFY_L2",
+                agent_id="semantic-verifier",
+                verdict_json=json.dumps(semantic.model_dump()),
+                outcome=semantic.alignment.value,
+            )
+
+            if l2_decision.action == ConcurrencyAction.PASS:
+                self.checkpoint.update_task_stage(task_id, "MERGE")
+                await self.event_bus.publish(DevHiveEvent(
+                    event_type="convergence.reached",
+                    task_id=task_id,
+                    payload={"status": "ready_to_merge"},
+                ))
+            else:
+                await self._escalate(task_id, l2_decision)
+
+        elif decision.action == ConcurrencyAction.FIX:
+            # Retry with fix strategy
+            await self._retry_task(task_id, decision.fix_strategy)
+
+        elif decision.action == ConcurrencyAction.ESCALATE:
+            await self._escalate(task_id, decision)
+
+        elif decision.action == ConcurrencyAction.CONFLICT:
+            await self._escalate(task_id, decision)
+
+    async def _retry_task(self, task_id: str, fix_strategy: str = None):
+        """Retry execution with a fix strategy."""
+        task = self.task_queue.peek(task_id)
+        if task:
+            self.task_queue.enqueue(task)
+            await self._try_dispatch(task)
+
+    async def _escalate(self, task_id: str, decision) -> None:
+        """Escalate to human operators."""
+        escalation = decision.escalation or {
+            "escalation_id": f"esc-{task_id}",
+            "task_id": task_id,
+            "triggered_by": decision.reason,
+        }
+
+        await self.event_bus.publish(DevHiveEvent(
+            event_type="escalation.needed",
+            task_id=task_id,
+            payload={"report": escalation},
+        ))
+
+    async def _try_dispatch(self, task: Task):
+        """Try to dispatch a task to an idle Execute Agent."""
+        handle = self.agent_pool.get_idle(AgentType.EXECUTE)
+        if handle:
+            self.agent_pool.dispatch(handle, task)
+            self._increment_attempt(task.id, "execute")
+            self.checkpoint.update_task_stage(task.id, "EXECUTE")
+
+    async def _collect_results(self):
+        """Background task: collect results from agent processes."""
+        while True:
+            await asyncio.sleep(0.5)
+            for agent_id, handle in list(self.agent_pool.agents.items()):
+                try:
+                    while not handle.result_queue.empty():
+                        result = handle.result_queue.get_nowait()
+                        await self._process_agent_result(agent_id, result)
+                except Exception:
+                    pass
+
+    async def _process_agent_result(self, agent_id: str, result: dict):
+        """Process a result from an agent process."""
+        result_type = result.get("type", "")
+
+        if result_type == "agent.idle":
+            self.agent_pool.mark_idle(agent_id)
+            await self.event_bus.publish(DevHiveEvent(
+                event_type="agent.idle",
+                task_id="",
+                payload={"agent_id": agent_id,
+                         "agent_type": result.get("agent_type", "")},
+            ))
+
+        elif result_type == "success":
+            task_id = result.get("task_id", "")
+            self.agent_pool.mark_idle(agent_id)
+
+            if "handoff" in result.get("result", {}):
+                # Execute agent produced a handoff
+                await self.event_bus.publish(DevHiveEvent(
+                    event_type="handoff.emitted",
+                    task_id=task_id,
+                    payload={"handoff": result["result"]["handoff"],
+                             "agent_id": agent_id},
+                ))
+
+        elif result_type == "stuck":
+            task_id = result.get("task_id", "")
+            self.agent_pool.mark_idle(agent_id)
+            await self.event_bus.publish(DevHiveEvent(
+                event_type="escalation.needed",
+                task_id=task_id,
+                payload={"reason": "agent_stuck",
+                         "error": result.get("error", ""),
+                         "agent_id": agent_id},
+            ))
+
+        elif result_type == "error":
+            task_id = result.get("task_id", "")
+            self.agent_pool.mark_idle(agent_id)
+            await self.event_bus.publish(DevHiveEvent(
+                event_type="escalation.needed",
+                task_id=task_id,
+                payload={"reason": "agent_error",
+                         "error": result.get("error", ""),
+                         "agent_id": agent_id},
+            ))
+
+    def _increment_attempt(self, task_id: str, stage: str):
+        if task_id not in self._task_attempts:
+            self._task_attempts[task_id] = {}
+        self._task_attempts[task_id][stage] = \
+            self._task_attempts[task_id].get(stage, 0) + 1
+
+    def _get_attempt(self, task_id: str, stage: str) -> int:
+        return self._task_attempts.get(task_id, {}).get(stage, 1)
+
+    def _notify_human(self, task_id: str, report: dict):
+        """Send desktop notification for escalations."""
+        msg = f"[DevHive] Task {task_id} needs attention\n{report.get('triggered_by', '')}"
+        try:
+            import subprocess
+            subprocess.run(["notify-send", "DevHive Escalation", msg],
+                          timeout=5)
+        except Exception:
+            pass  # notify-send not available
+        print(f"\n{'='*60}\nESCALATION: {task_id}\n{msg}\n{'='*60}\n")

package/orchestrator/event_bus.py

@@ -0,0 +1,58 @@
+"""Event Bus — async publish/subscribe for agent communication."""
+
+import asyncio
+from collections import defaultdict
+from typing import Callable, Awaitable
+
+from protocol.schemas import DevHiveEvent
+
+
+EventHandler = Callable[[DevHiveEvent], Awaitable[None]]
+
+
+class EventBus:
+    """Lightweight pub/sub event bus for orchestrator-agent communication."""
+
+    def __init__(self):
+        self._subscribers: dict[str, list[EventHandler]] = defaultdict(list)
+        self._queue: asyncio.Queue[DevHiveEvent] = asyncio.Queue()
+        self._running = False
+        self._task: asyncio.Task | None = None
+
+    def subscribe(self, event_type: str, handler: EventHandler):
+        """Register a handler for a specific event type."""
+        self._subscribers[event_type].append(handler)
+
+    async def publish(self, event: DevHiveEvent):
+        """Publish an event to the bus. Non-blocking."""
+        await self._queue.put(event)
+
+    async def start(self):
+        """Start the event processing loop."""
+        self._running = True
+        self._task = asyncio.create_task(self._process_events())
+
+    async def stop(self):
+        """Stop the event processing loop."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+
+    async def _process_events(self):
+        """Main event processing loop."""
+        while self._running:
+            try:
+                event = await asyncio.wait_for(self._queue.get(), timeout=1.0)
+                handlers = self._subscribers.get(event.event_type, [])
+                # Dispatch to all handlers concurrently
+                tasks = [handler(event) for handler in handlers]
+                if tasks:
+                    await asyncio.gather(*tasks, return_exceptions=True)
+            except asyncio.TimeoutError:
+                continue
+            except Exception:
+                continue

package/orchestrator/task_queue.py

@@ -0,0 +1,59 @@
+"""Task Queue — priority-based task scheduling."""
+
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Optional
+
+from protocol.schemas import Task, Priority
+
+
+@dataclass
+class QueueEntry:
+    task: Task
+    enqueued_at: float
+    priority: Priority = Priority.MEDIUM
+
+
+class TaskQueue:
+    """Simple priority-based task queue with FIFO within each priority level."""
+
+    def __init__(self):
+        self._queues: dict[Priority, deque[QueueEntry]] = {
+            Priority.CRITICAL: deque(),
+            Priority.HIGH: deque(),
+            Priority.MEDIUM: deque(),
+            Priority.LOW: deque(),
+        }
+        self._all_tasks: dict[str, Task] = {}
+
+    def enqueue(self, task: Task) -> QueueEntry:
+        import time
+        entry = QueueEntry(task=task, enqueued_at=time.monotonic(),
+                          priority=task.spec.priority)
+        self._queues[task.spec.priority].append(entry)
+        self._all_tasks[task.id] = task
+        return entry
+
+    def next_pending(self, agent_type: str = None) -> Optional[Task]:
+        """Get the next pending task by priority."""
+        for priority in (Priority.CRITICAL, Priority.HIGH,
+                         Priority.MEDIUM, Priority.LOW):
+            if self._queues[priority]:
+                entry = self._queues[priority].popleft()
+                return entry.task
+        return None
+
+    def peek(self, task_id: str) -> Optional[Task]:
+        return self._all_tasks.get(task_id)
+
+    def pending_count(self) -> int:
+        return sum(len(q) for q in self._queues.values())
+
+    def remove(self, task_id: str):
+        """Remove a task from the queue."""
+        for q in self._queues.values():
+            for i, entry in enumerate(q):
+                if entry.task.id == task_id:
+                    del q[i]
+                    break
+        self._all_tasks.pop(task_id, None)

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@oswaldzsh/devhive",
+  "version": "0.1.0",
+  "description": "Multi-Agent Software Development System — autonomous coding with verify-specialized agents, failure signatures, and structured handoff protocols.",
+  "keywords": [
+    "ai",
+    "agent",
+    "coding",
+    "devtool",
+    "multi-agent",
+    "claude",
+    "orchestration",
+    "verification",
+    "autonomous"
+  ],
+  "homepage": "https://github.com/lejurobot/devhive",
+  "license": "MIT",
+  "bin": {
+    "dh": "bin/dh"
+  },
+  "files": [
+    "bin/",
+    "control_plane/",
+    "agents/",
+    "orchestrator/",
+    "protocol/",
+    "verification/",
+    "signature/",
+    "storage/",
+    "tools/",
+    "signatures/",
+    "config.yaml",
+    "setup.py",
+    "install.sh",
+    "__init__.py"
+  ],
+  "scripts": {
+    "postinstall": "bash install.sh || echo 'DevHive: Python deps not installed. Run: pip3 install httpx pydantic pyyaml rich'",
+    "uninstall": "rm -rf ~/.devhive"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lejurobot/devhive"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "os": ["darwin", "linux"],
+  "preferGlobal": true
+}