@oswaldzsh/devhive 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# DevHive
+
+Multi-Agent Software Development System — autonomous coding with verify-specialized agents, failure signatures, and structured handoff protocols.
+
+## Install
+
+```bash
+npm install -g devhive
+```
+
+Or via pip:
+
+```bash
+pip install devhive
+```
+
+Requires Python 3.12+.
+
+## Quick start
+
+```bash
+# Start interactive REPL with live dashboard
+dh
+
+# Submit a task from natural language
+dh do "fix the login timeout bug in auth/session.py"
+
+# Check system status
+dh status
+
+# Review and resolve escalations
+dh review
+
+# View task execution timeline
+dh log <task-id>
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `dh` | Interactive REPL with live dashboard |
+| `dh do <desc>` | Submit task from natural language |
+| `dh do -f <file>` | Submit task from JSON/YAML spec |
+| `dh status` | Show system status |
+| `dh log <id>` | Show task execution timeline |
+| `dh review` | Interactive escalation review |
+| `dh resolve <id>` | Resolve an escalation |
+| `dh run` | Start orchestrator daemon |
+
+## Configuration
+
+Copy `config.yaml` to `config.local.yaml` and set your API credentials:
+
+```yaml
+api:
+  base_url: "https://your-api-endpoint"
+  auth_token: "${YOUR_TOKEN}"
+  default_model: "your-model"
+```
+
+## Architecture
+
+DevHive uses a multi-agent architecture with three verification layers:
+
+```
+Task → Execute Agent → L1 Verify (Static + Dynamic) → L2 Verify (Semantic) → Merge
+                              ↓ fail                        ↓ fail
+                         Signature Match                Human Escalation
+                              ↓                             ↓
+                         Auto-fix / Retry              Human resolves
+```
+
+### Agent Types
+
+- **Execute Agent** — Produces code changes with structured Handoff
+- **Static Verifier** — Detects code pattern issues (API breaks, security, quality)
+- **Dynamic Verifier** — Runs tests, detects drift, matches failure signatures
+- **Semantic Verifier** — Validates Spec alignment (on merge gate)
+
+### Key Design Decisions
+
+- Agents communicate via **structured JSON Handoff**, not natural language
+- **No Agent arbitrates Agents** — Diagnostic Aggregator is a deterministic rule engine
+- Failure diagnosis uses a **growing signature database** with weighted feature matching
+- **Human intervenes**, not "human in the loop"
+- All escalation thresholds are **quantified**, not fuzzy
+
+## License
+
+MIT

package/agents/base.py

@@ -0,0 +1,118 @@
+"""Agent base class — process lifecycle, tool registration, context management."""
+
+import json
+import multiprocessing
+import os
+import signal
+import time
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from typing import Optional
+
+from tools.api_client import APIClient, extract_text_from_response, extract_tool_use
+from protocol.schemas import (
+    Task, ExecutionHandoff, Verdict, DevHiveEvent,
+    Finding, Severity, SuggestedAction, VerdictOverall, VerifierType,
+    EscalationReport,
+)
+
+
+class AgentStuckException(Exception):
+    pass
+
+
+class AgentProcess(multiprocessing.Process, ABC):
+    """Each Agent runs in an independent process, communicating via UDS/Queue."""
+
+    def __init__(self, agent_id: str, agent_type: str,
+                 task_queue: multiprocessing.Queue,
+                 result_queue: multiprocessing.Queue,
+                 config: dict = None):
+        super().__init__()
+        self.agent_id = agent_id
+        self.agent_type = agent_type
+        self._task_queue = task_queue
+        self._result_queue = result_queue
+        self.config = config or {}
+        self.api_client: Optional[APIClient] = None
+        self._stop_event = multiprocessing.Event()
+
+    def run(self):
+        """Agent main loop — wait for tasks, execute, emit results."""
+        signal.signal(signal.SIGINT, signal.SIG_IGN)
+        self.api_client = APIClient(
+            base_url=self.config.get("base_url"),
+            auth_token=self.config.get("auth_token"),
+            default_model=self.config.get("default_model"),
+        )
+        self._setup()
+        self._emit_idle()
+
+        while not self._stop_event.is_set():
+            try:
+                task_data = self._task_queue.get(timeout=2)
+            except Exception:
+                continue
+
+            if task_data is None:  # poison pill
+                break
+
+            task = Task(**task_data) if isinstance(task_data, dict) else task_data
+            start_time = time.monotonic()
+
+            try:
+                result = self._execute(task)
+                duration_ms = int((time.monotonic() - start_time) * 1000)
+                self._emit_result({"type": "success", "task_id": task.id,
+                                   "result": result, "duration_ms": duration_ms})
+            except AgentStuckException as e:
+                duration_ms = int((time.monotonic() - start_time) * 1000)
+                self._emit_result({"type": "stuck", "task_id": task.id,
+                                   "error": str(e), "duration_ms": duration_ms})
+            except Exception as e:
+                duration_ms = int((time.monotonic() - start_time) * 1000)
+                self._emit_result({"type": "error", "task_id": task.id,
+                                   "error": str(e), "duration_ms": duration_ms})
+
+    def stop(self):
+        self._stop_event.set()
+
+    def _setup(self):
+        """Override for agent-specific initialization."""
+        pass
+
+    @abstractmethod
+    def _execute(self, task: Task) -> dict | ExecutionHandoff | Verdict:
+        """Execute the task. Must be implemented by each agent type."""
+        ...
+
+    def _emit_idle(self):
+        self._result_queue.put({"type": "agent.idle", "agent_id": self.agent_id,
+                                "agent_type": self.agent_type})
+
+    def _emit_result(self, result: dict):
+        result["agent_id"] = self.agent_id
+        result["agent_type"] = self.agent_type
+        self._result_queue.put(result)
+
+    def _call_model(self, system_prompt: str, user_message: str,
+                    tools: list[dict] = None,
+                    max_tokens: int = 4096,
+                    model: str = None) -> dict:
+        """Convenience wrapper for API calls."""
+        return self.api_client.create_message(
+            system=system_prompt,
+            messages=[{"role": "user", "content": user_message}],
+            tools=tools,
+            max_tokens=max_tokens,
+            model=model,
+        )
+
+    def _call_model_sync(self, *args, **kwargs):
+        """Synchronous version for use in multiprocessing context."""
+        import asyncio
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(self._call_model(*args, **kwargs))
+        finally:
+            loop.close()

package/agents/execute.py

@@ -0,0 +1,150 @@
+"""Execute Agent — receives Task, produces code changes + Handoff."""
+
+import json
+from datetime import datetime, timezone
+
+from agents.base import AgentProcess, AgentStuckException
+from protocol.schemas import (
+    Task, ExecutionHandoff, FileChange, VerificationFocus,
+    EnvChanges, RiskAssessment, ExecutionTrace, ChangeType, Priority, Severity,
+)
+from tools.git import GitOps, GitError
+
+
+EXECUTE_SYSTEM_PROMPT = """You are an Execute Agent in the DevHive system. Your job is to:
+
+1. Read the task Spec carefully — understand the target state
+2. Explore the codebase to understand the current state and relevant code
+3. Produce code changes that move the system toward the target state
+4. Run self-checks (compile, lint, basic tests) to verify your changes work
+5. Output a structured Execution Handoff in JSON format
+
+CRITICAL RULES:
+- Never merge code. Your output goes to a Verifier, not directly to the main branch.
+- If you are uncertain about any change, note it in risk_self_assessment.
+- Always specify verification_focus — what the verifier should check most carefully.
+- Report env_changes — new dependencies, config changes, migrations needed.
+- If you cannot complete the task, escalate with a clear explanation of what's blocking you.
+
+OUTPUT FORMAT:
+You MUST end your response with a JSON block labeled HANDOFF:
+```json
+{
+  "intent": "one-line summary of what you changed and why",
+  "changes": [...],
+  "verification_focus": [...],
+  "env_changes": {...},
+  "execution_trace": {...}
+}
+```
+"""
+
+
+class ExecuteAgent(AgentProcess):
+    """Produces code changes based on Task Spec."""
+
+    def __init__(self, agent_id: str, task_queue, result_queue, config: dict = None):
+        super().__init__(agent_id, "execute", task_queue, result_queue, config)
+        self.git = None
+        self.max_self_retries = 2
+
+    def _setup(self):
+        self.git = GitOps(self.config.get("repo_path", "."))
+
+    def _execute(self, task: Task) -> dict:
+        attempt = 0
+        last_error = None
+
+        while attempt <= self.max_self_retries:
+            try:
+                handoff = self._run_execute(task)
+                # Self-check: run basic verification
+                if not self._self_check(handoff):
+                    attempt += 1
+                    last_error = "Self-check failed"
+                    continue
+                return {"handoff": handoff.model_dump()}
+            except Exception as e:
+                attempt += 1
+                last_error = str(e)
+
+        raise AgentStuckException(
+            f"ExecuteAgent {self.agent_id} failed after {self.max_self_retries + 1} "
+            f"attempts. Last error: {last_error}"
+        )
+
+    def _run_execute(self, task: Task) -> ExecutionHandoff:
+        """Run the model to produce code changes."""
+        spec_text = json.dumps(task.spec.model_dump(), indent=2)
+        current_files = self.git.changed_files() or ["(clean working tree)"]
+
+        user_message = f"""## Task Spec
+{spec_text}
+
+## Current State
+Branch: {self.git.current_branch()}
+Base commit: {task.base_commit}
+Changed files: {', '.join(current_files)}
+
+## Instructions
+Read the task spec, explore the codebase, make the necessary changes.
+Output the HANDOFF JSON when done.
+"""
+
+        # In production this would be an interactive conversation with tool use.
+        # For the MVP, we do a single-turn call expecting the HANDOFF.
+        import asyncio
+        loop = asyncio.new_event_loop()
+        try:
+            response = loop.run_until_complete(
+                self._call_model(EXECUTE_SYSTEM_PROMPT, user_message,
+                                 max_tokens=8192,
+                                 model=self.config.get("execute_model"))
+            )
+        finally:
+            loop.close()
+
+        handoff = self._parse_handoff(response)
+        return handoff
+
+    def _parse_handoff(self, response: dict) -> ExecutionHandoff:
+        """Extract HANDOFF JSON from model response."""
+        text = ""
+        for block in response.get("content", []):
+            if block.get("type") == "text":
+                text += block["text"]
+
+        # Try to extract JSON between ```json ... ``` markers
+        import re
+        match = re.search(r'```json\s*\n(.*?)\n```', text, re.DOTALL)
+        if match:
+            handoff_data = json.loads(match.group(1))
+        else:
+            # Try parsing the whole text as JSON
+            handoff_data = json.loads(text)
+
+        return ExecutionHandoff(
+            source=self.agent_id,
+            task_id=handoff_data.get("task_id", ""),
+            intent=handoff_data["intent"],
+            changes=[FileChange(**c) for c in handoff_data.get("changes", [])],
+            verification_focus=[
+                VerificationFocus(**v) for v in handoff_data.get("verification_focus", [])
+            ],
+            env_changes=EnvChanges(**handoff_data.get("env_changes", {})),
+            execution_trace=ExecutionTrace(
+                **handoff_data.get("execution_trace", {"self_check_passed": False})
+            ),
+        )
+
+    def _self_check(self, handoff: ExecutionHandoff) -> bool:
+        """Run basic self-checks: compile/lint if applicable."""
+        # Run linter/type-checker on changed files
+        changed_files = [c.file for c in handoff.changes]
+        for f in changed_files:
+            if f.endswith(".py"):
+                try:
+                    self.git._run(["run", "mypy", f, "--ignore-missing-imports"])
+                except Exception:
+                    pass  # Non-blocking for now
+        return True  # MVP: self-check is advisory, not blocking

package/agents/verifier_dynamic.py

@@ -0,0 +1,164 @@
+"""Dynamic Verifier — runs tests, detects drift, matches failure signatures."""
+
+import json
+import os
+import subprocess
+import time
+from typing import Optional
+
+from agents.base import AgentProcess, AgentStuckException
+from protocol.schemas import (
+    Task, Verdict, Finding, FindingEvidence,
+    Severity, SuggestedAction, VerdictOverall, VerifierType,
+)
+
+
+DYNAMIC_SYSTEM_PROMPT = """You are a Dynamic Verifier Agent. Your job is to:
+
+1. Run tests affected by the code change (not full suite — use call graph)
+2. Analyze test results beyond red/green:
+   - Match failures against known signatures
+   - Detect performance regressions (runtime, memory)
+   - Detect behavioral drifts (log volume, output changes)
+3. Output a structured Verdict in JSON format
+
+OUTPUT FORMAT:
+```json
+{
+  "overall": "PASS|WARN|FAIL",
+  "findings": [
+    {
+      "severity": "HIGH|MEDIUM|LOW",
+      "category": "test_failure|perf_regression|coverage_gap|drift|flaky",
+      "title": "short description",
+      "detail": "detailed explanation",
+      "matched_signature": "sig-XXXX or null",
+      "suggested_action": "RETEST|FIX|ESCALATE|IGNORE"
+    }
+  ]
+}
+```
+"""
+
+
+class DynamicVerifier(AgentProcess):
+    """Runs tests and analyzes results."""
+
+    def __init__(self, agent_id: str, task_queue, result_queue, config: dict = None):
+        super().__init__(agent_id, "dynamic_verifier", task_queue, result_queue, config)
+        self.drift_thresholds = {}
+        self.signature_engine = None
+
+    def _setup(self):
+        self.drift_thresholds = {
+            "duration_change_pct": 20,
+            "memory_change_pct": 50,
+            "log_volume_change_multiplier": 3.0,
+        }
+        self.drift_thresholds.update(
+            self.config.get("drift_thresholds", {})
+        )
+
+    def _execute(self, task: Task) -> Verdict:
+        findings = []
+
+        # 1. Run tests
+        test_findings = self._run_tests(task)
+        findings.extend(test_findings)
+
+        # 2. Check for drift
+        drift_findings = self._check_drift(task)
+        findings.extend(drift_findings)
+
+        # 3. Match against signature DB
+        for f in findings:
+            if f.severity in (Severity.HIGH, Severity.CRITICAL):
+                matched = self._match_signature(f)
+                if matched:
+                    f.matched_signature = matched["signature_id"]
+                    f.suggested_action = SuggestedAction(matched.get("resolution", {}).get(
+                        "strategy", "ESCALATE"))
+
+        # Determine overall
+        has_fail = any(f.severity in (Severity.HIGH, Severity.CRITICAL) for f in findings)
+        has_warn = any(f.severity == Severity.MEDIUM for f in findings)
+
+        if has_fail:
+            overall = VerdictOverall.FAIL
+        elif has_warn:
+            overall = VerdictOverall.WARN
+        else:
+            overall = VerdictOverall.PASS
+
+        return Verdict(
+            verifier_type=VerifierType.DYNAMIC,
+            task_id=task.id,
+            overall=overall,
+            findings=findings,
+        )
+
+    def _run_tests(self, task: Task) -> list[Finding]:
+        """Run relevant tests based on call graph or Handoff verification_focus."""
+        findings = []
+        repo_path = self.config.get("repo_path", ".")
+
+        # Run pytest if it's a Python project
+        if os.path.exists(os.path.join(repo_path, "pyproject.toml")) or \
+           os.path.exists(os.path.join(repo_path, "setup.py")) or \
+           os.path.exists(os.path.join(repo_path, "setup.cfg")):
+            try:
+                start = time.monotonic()
+                result = subprocess.run(
+                    ["pytest", "-x", "--tb=short", "-q"],
+                    cwd=repo_path, capture_output=True, text=True, timeout=300
+                )
+                duration = time.monotonic() - start
+
+                if result.returncode != 0:
+                    findings.append(Finding(
+                        severity=Severity.HIGH,
+                        category="test_failure",
+                        title="Tests failed",
+                        detail=result.stdout[-2000:] + "\n" + result.stderr[-1000:],
+                        evidence=FindingEvidence(type="log", data=result.stdout),
+                        suggested_action=SuggestedAction.FIX,
+                    ))
+                elif duration > 60:
+                    findings.append(Finding(
+                        severity=Severity.LOW,
+                        category="perf_regression",
+                        title=f"Test suite took {duration:.1f}s (>60s threshold)",
+                        detail=f"Previous baseline: N/A. Current: {duration:.1f}s",
+                        evidence=FindingEvidence(type="metric", data=str(duration)),
+                        suggested_action=SuggestedAction.ESCALATE,
+                    ))
+
+            except subprocess.TimeoutExpired:
+                findings.append(Finding(
+                    severity=Severity.HIGH,
+                    category="test_failure",
+                    title="Test suite timed out after 300s",
+                    detail="Tests did not complete within the timeout.",
+                    evidence=FindingEvidence(type="log", data="TIMEOUT"),
+                    suggested_action=SuggestedAction.ESCALATE,
+                ))
+
+        return findings
+
+    def _check_drift(self, task: Task) -> list[Finding]:
+        """Detect behavioral drift: performance, memory, output changes."""
+        return []  # MVP: drift detection requires baseline data, skipped for now
+
+    def _match_signature(self, finding: Finding) -> Optional[dict]:
+        """Query signature DB for matching failure patterns."""
+        if not self.signature_engine:
+            return None
+
+        try:
+            results = self.signature_engine.match({
+                "error_type": finding.category,
+                "error_location_pattern": finding.title,
+            }, k=1, min_confidence=0.65)
+            return results[0] if results else None
+        except Exception:
+            return None

package/agents/verifier_semantic.py

@@ -0,0 +1,84 @@
+"""Semantic Verifier — checks if changes align with Spec intent."""
+
+import json
+
+from agents.base import AgentProcess
+from protocol.schemas import (
+    Task, SemanticVerdict, Finding, FindingEvidence,
+    Severity, SuggestedAction, VerdictOverall, Alignment,
+)
+
+
+SEMANTIC_SYSTEM_PROMPT = """You are a Semantic Verifier Agent. Your job is to:
+
+1. Read the original Spec and the code changes (from the Execution Handoff)
+2. Determine if the changes align with the Spec's intent — not just its text
+3. Categorize the alignment:
+   - ALIGNED: Changes match Spec intent exactly
+   - ENHANCED: Changes add reasonable improvements beyond Spec (flag for human review)
+   - DEVIATED: Changes diverge from Spec intent (block)
+   - CONFLICT: Changes contradict Spec or are internally inconsistent (block)
+
+4. Output your verdict in JSON format
+
+OUTPUT FORMAT:
+```json
+{
+  "alignment": "ALIGNED|ENHANCED|DEVIATED|CONFLICT",
+  "reasoning": "detailed explanation of your judgment",
+  "concerns": ["list of specific concerns, empty if none"]
+}
+```
+"""
+
+
+class SemanticVerifier(AgentProcess):
+    """Validates semantic alignment between changes and Spec."""
+
+    def __init__(self, agent_id: str, task_queue, result_queue, config: dict = None):
+        super().__init__(agent_id, "semantic_verifier", task_queue, result_queue, config)
+
+    def _execute(self, task: Task) -> SemanticVerdict:
+        import asyncio
+
+        task_json = json.dumps(task.model_dump(), indent=2, default=str)
+
+        loop = asyncio.new_event_loop()
+        try:
+            response = loop.run_until_complete(
+                self._call_model(SEMANTIC_SYSTEM_PROMPT,
+                                 f"## Task with Spec, Handoff, and Verdicts\n\n{task_json}",
+                                 max_tokens=4096)
+            )
+        finally:
+            loop.close()
+
+        return self._parse_verdict(response)
+
+    def _parse_verdict(self, response: dict) -> SemanticVerdict:
+        import re
+        text = ""
+        for block in response.get("content", []):
+            if block.get("type") == "text":
+                text += block["text"]
+
+        match = re.search(r'```json\s*\n(.*?)\n```', text, re.DOTALL)
+        if not match:
+            return SemanticVerdict(
+                task_id="",
+                alignment=Alignment.CONFLICT,
+                reasoning="Failed to parse model output",
+                overall=VerdictOverall.FAIL,
+            )
+
+        data = json.loads(match.group(1))
+        alignment = Alignment(data.get("alignment", "DEVIATED"))
+
+        return SemanticVerdict(
+            task_id=data.get("task_id", ""),
+            alignment=alignment,
+            reasoning=data.get("reasoning", ""),
+            concerns=data.get("concerns", []),
+            overall=VerdictOverall.PASS if alignment in (Alignment.ALIGNED, Alignment.ENHANCED)
+                     else VerdictOverall.FAIL,
+        )