@oswaldzsh/devhive 0.1.0

package/storage/checkpoint.py

@@ -0,0 +1,153 @@
+"""Storage layer — SQLite-based checkpoint and signature database."""
+
+import sqlite3
+import json
+import os
+from datetime import datetime
+from typing import Optional
+
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS checkpoints (
+    id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL,
+    stage TEXT NOT NULL,
+    agent_id TEXT,
+    handoff_json TEXT,
+    verdict_json TEXT,
+    state_before TEXT,
+    state_after TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    duration_ms INTEGER,
+    outcome TEXT,
+    escalation_id TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_checkpoint_task ON checkpoints(task_id, created_at);
+
+CREATE TABLE IF NOT EXISTS tasks (
+    id TEXT PRIMARY KEY,
+    spec_json TEXT NOT NULL,
+    branch TEXT NOT NULL,
+    base_commit TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    current_stage TEXT DEFAULT 'SPECIFY',
+    status TEXT DEFAULT 'pending'
+);
+
+CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status, created_at);
+
+CREATE TABLE IF NOT EXISTS escalation_log (
+    id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL,
+    report_json TEXT NOT NULL,
+    resolved_by TEXT,
+    resolved_at TIMESTAMP,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+"""
+
+
+class CheckpointStore:
+    """Persistent task-state snapshots."""
+
+    def __init__(self, db_path: str = "storage/devhive.db"):
+        os.makedirs(os.path.dirname(db_path), exist_ok=True)
+        self.db_path = db_path
+        self._init_db()
+
+    def _init_db(self):
+        with sqlite3.connect(self.db_path) as conn:
+            conn.executescript(SCHEMA_SQL)
+
+    def _get_conn(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def save_checkpoint(self, checkpoint_id: str, task_id: str, stage: str,
+                        agent_id: Optional[str] = None,
+                        handoff_json: Optional[str] = None,
+                        verdict_json: Optional[str] = None,
+                        state_before: Optional[str] = None,
+                        state_after: Optional[str] = None,
+                        duration_ms: Optional[int] = None,
+                        outcome: Optional[str] = None,
+                        escalation_id: Optional[str] = None):
+        with self._get_conn() as conn:
+            conn.execute(
+                """INSERT OR REPLACE INTO checkpoints
+                   (id, task_id, stage, agent_id, handoff_json, verdict_json,
+                    state_before, state_after, duration_ms, outcome, escalation_id)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                (checkpoint_id, task_id, stage, agent_id, handoff_json,
+                 verdict_json, state_before, state_after, duration_ms,
+                 outcome, escalation_id))
+            conn.commit()
+
+    def get_checkpoint(self, checkpoint_id: str) -> Optional[dict]:
+        with self._get_conn() as conn:
+            row = conn.execute(
+                "SELECT * FROM checkpoints WHERE id = ?", (checkpoint_id,)
+            ).fetchone()
+        return dict(row) if row else None
+
+    def get_task_history(self, task_id: str) -> list[dict]:
+        with self._get_conn() as conn:
+            rows = conn.execute(
+                "SELECT * FROM checkpoints WHERE task_id = ? ORDER BY created_at",
+                (task_id,)
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def save_task(self, task_id: str, spec_json: str, branch: str, base_commit: str):
+        with self._get_conn() as conn:
+            conn.execute(
+                """INSERT OR REPLACE INTO tasks (id, spec_json, branch, base_commit)
+                   VALUES (?, ?, ?, ?)""",
+                (task_id, spec_json, branch, base_commit))
+            conn.commit()
+
+    def update_task_stage(self, task_id: str, stage: str):
+        with self._get_conn() as conn:
+            conn.execute(
+                "UPDATE tasks SET current_stage = ? WHERE id = ?",
+                (stage, task_id))
+            conn.commit()
+
+    def get_task(self, task_id: str) -> Optional[dict]:
+        with self._get_conn() as conn:
+            row = conn.execute(
+                "SELECT * FROM tasks WHERE id = ?", (task_id,)
+            ).fetchone()
+        return dict(row) if row else None
+
+    def get_pending_tasks(self) -> list[dict]:
+        with self._get_conn() as conn:
+            rows = conn.execute(
+                "SELECT * FROM tasks WHERE status = 'pending' ORDER BY created_at"
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def save_escalation(self, escalation_id: str, task_id: str, report_json: str):
+        with self._get_conn() as conn:
+            conn.execute(
+                """INSERT OR REPLACE INTO escalation_log (id, task_id, report_json)
+                   VALUES (?, ?, ?)""",
+                (escalation_id, task_id, report_json))
+            conn.commit()
+
+    def resolve_escalation(self, escalation_id: str, resolved_by: str):
+        with self._get_conn() as conn:
+            conn.execute(
+                """UPDATE escalation_log SET resolved_by = ?, resolved_at = ?
+                   WHERE id = ?""",
+                (resolved_by, datetime.utcnow().isoformat(), escalation_id))
+            conn.commit()
+
+    def get_open_escalations(self) -> list[dict]:
+        with self._get_conn() as conn:
+            rows = conn.execute(
+                "SELECT * FROM escalation_log WHERE resolved_by IS NULL ORDER BY created_at"
+            ).fetchall()
+        return [dict(r) for r in rows]

package/storage/signature_db.py

@@ -0,0 +1,62 @@
+"""Signature Database — stores and queries failure signatures."""
+
+import json
+import os
+from typing import Optional
+
+
+class SignatureDB:
+    """JSON-file backed signature store (Python wrapper).
+
+    The heavy matching is done by the C extension (signature/src/matcher.c).
+    This module handles CRUD and learning.
+    """
+
+    def __init__(self, db_path: str = "signatures/signatures.db"):
+        self.db_path = db_path
+        self._signatures: dict[str, dict] = {}
+        self._load()
+
+    def _load(self):
+        if os.path.exists(self.db_path):
+            with open(self.db_path) as f:
+                data = json.load(f)
+            self._signatures = {s["signature_id"]: s for s in data.get("signatures", [])}
+
+    def _save(self):
+        os.makedirs(os.path.dirname(self.db_path), exist_ok=True)
+        with open(self.db_path, "w") as f:
+            json.dump({"signatures": list(self._signatures.values())}, f, indent=2)
+
+    def add(self, signature: dict):
+        sig_id = signature["signature_id"]
+        self._signatures[sig_id] = signature
+        self._save()
+
+    def get(self, sig_id: str) -> Optional[dict]:
+        return self._signatures.get(sig_id)
+
+    def all(self) -> list[dict]:
+        return list(self._signatures.values())
+
+    def update_match(self, sig_id: str):
+        """Increment match count and update last_matched timestamp."""
+        if sig_id in self._signatures:
+            from datetime import datetime
+            self._signatures[sig_id]["last_matched"] = datetime.utcnow().isoformat()
+            self._signatures[sig_id]["match_count"] = \
+                self._signatures[sig_id].get("match_count", 0) + 1
+            self._save()
+
+    def seed_from_file(self, seed_path: str):
+        """Load seed signatures from a JSON file."""
+        if os.path.exists(seed_path):
+            with open(seed_path) as f:
+                data = json.load(f)
+            for sig in data.get("signatures", []):
+                if sig["signature_id"] not in self._signatures:
+                    self._signatures[sig["signature_id"]] = sig
+            self._save()
+
+    def count(self) -> int:
+        return len(self._signatures)

package/tools/api_client.py

@@ -0,0 +1,101 @@
+"""Anthropic-compatible API client for lejuapi."""
+
+import os
+import json
+import httpx
+from typing import Optional
+
+
+class APIClient:
+    """Async client for Anthropic-compatible Messages API via lejuapi."""
+
+    def __init__(self, base_url: str = None, auth_token: str = None,
+                 default_model: str = None):
+        self.base_url = base_url or os.getenv("ANTHROPIC_BASE_URL",
+                                               "https://aiapi.lejurobot.com")
+        self.auth_token = auth_token or os.getenv("ANTHROPIC_AUTH_TOKEN",
+                                                   os.getenv("LEJU_TOKEN", ""))
+        self.default_model = default_model or os.getenv("DEVHIVE_MODEL",
+                                                         "deepseek/deepseek-v4-pro")
+
+    def _headers(self) -> dict:
+        return {
+            "x-api-key": self.auth_token,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+        }
+
+    async def create_message(
+        self,
+        system: str,
+        messages: list[dict],
+        tools: list[dict] = None,
+        model: str = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.3,
+    ) -> dict:
+        """Send a message to the model and return the API response."""
+        body = {
+            "model": model or self.default_model,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            "system": system,
+            "messages": messages,
+        }
+        if tools:
+            body["tools"] = tools
+
+        async with httpx.AsyncClient(timeout=httpx.Timeout(600.0)) as client:
+            resp = await client.post(
+                f"{self.base_url}/v1/messages",
+                headers=self._headers(),
+                json=body,
+            )
+            resp.raise_for_status()
+            return resp.json()
+
+    async def create_message_stream(
+        self,
+        system: str,
+        messages: list[dict],
+        tools: list[dict] = None,
+        model: str = None,
+        max_tokens: int = 4096,
+    ):
+        """Stream a message response token-by-token."""
+        body = {
+            "model": model or self.default_model,
+            "max_tokens": max_tokens,
+            "system": system,
+            "messages": messages,
+            "stream": True,
+        }
+        if tools:
+            body["tools"] = tools
+
+        async with httpx.AsyncClient(timeout=httpx.Timeout(600.0)) as client:
+            async with client.stream(
+                "POST",
+                f"{self.base_url}/v1/messages",
+                headers=self._headers(),
+                json=body,
+            ) as resp:
+                resp.raise_for_status()
+                async for line in resp.aiter_lines():
+                    if line.startswith("data: "):
+                        data = line[6:]
+                        if data.strip():
+                            yield json.loads(data)
+
+
+def extract_text_from_response(response: dict) -> str:
+    """Extract the text content from an Anthropic API response."""
+    for block in response.get("content", []):
+        if block.get("type") == "text":
+            return block["text"]
+    return ""
+
+
+def extract_tool_use(response: dict) -> list[dict]:
+    """Extract tool_use blocks from an Anthropic API response."""
+    return [b for b in response.get("content", []) if b.get("type") == "tool_use"]

package/tools/git.py

@@ -0,0 +1,75 @@
+"""Git operations wrapper — safe, auditable, with trace."""
+
+import subprocess
+import os
+from typing import Optional
+from datetime import datetime
+
+
+class GitError(Exception):
+    pass
+
+
+class GitOps:
+    """Thin wrapper around git CLI. Every mutation logs the command for audit."""
+
+    def __init__(self, repo_path: str = "."):
+        self.repo_path = repo_path
+        self.command_log: list[dict] = []
+
+    def _run(self, args: list[str], capture: bool = True) -> Optional[str]:
+        cmd = ["git", "-C", self.repo_path] + args
+        self.command_log.append({
+            "timestamp": datetime.utcnow().isoformat(),
+            "command": " ".join(cmd),
+        })
+        try:
+            result = subprocess.run(cmd, capture_output=capture, text=True, timeout=120)
+            if result.returncode != 0 and capture:
+                raise GitError(result.stderr.strip())
+            return result.stdout.strip() if capture else None
+        except subprocess.TimeoutExpired:
+            raise GitError(f"Git command timed out: {' '.join(cmd)}")
+
+    def current_branch(self) -> str:
+        return self._run(["branch", "--show-current"]) or ""
+
+    def current_commit(self) -> str:
+        return self._run(["rev-parse", "HEAD"]) or ""
+
+    def create_branch(self, name: str, base: str = "HEAD"):
+        self._run(["checkout", "-b", name, base])
+
+    def checkout(self, branch: str):
+        self._run(["checkout", branch])
+
+    def status(self) -> str:
+        return self._run(["status", "--short"]) or ""
+
+    def diff(self, target: str = "HEAD") -> str:
+        return self._run(["diff", target]) or ""
+
+    def diff_stat(self, target: str = "HEAD") -> str:
+        return self._run(["diff", "--stat", target]) or ""
+
+    def changed_files(self, target: str = "HEAD") -> list[str]:
+        output = self._run(["diff", "--name-only", target]) or ""
+        return [f for f in output.split("\n") if f]
+
+    def stage(self, *files: str):
+        self._run(["add"] + list(files))
+
+    def commit(self, message: str):
+        self._run(["commit", "-m", message])
+
+    def get_file_at_commit(self, file_path: str, commit: str = "HEAD") -> str:
+        return self._run(["show", f"{commit}:{file_path}"]) or ""
+
+    def log(self, n: int = 10, oneline: bool = True) -> str:
+        args = ["log", f"-{n}"]
+        if oneline:
+            args.append("--oneline")
+        return self._run(args) or ""
+
+    def merge_base(self, branch: str) -> str:
+        return self._run(["merge-base", "HEAD", branch]) or ""

package/tools/sandbox.py

@@ -0,0 +1,79 @@
+"""Sandbox management — Docker-based isolation for agent execution."""
+
+import subprocess
+import os
+import tempfile
+import shutil
+from typing import Optional
+
+
+class SandboxError(Exception):
+    pass
+
+
+class Sandbox:
+    """Docker-based sandbox for safe agent code execution."""
+
+    def __init__(self, image: str = "devhive-sandbox:latest",
+                 memory_limit: str = "2g", cpu_limit: int = 2,
+                 timeout: int = 600):
+        self.image = image
+        self.memory_limit = memory_limit
+        self.cpu_limit = cpu_limit
+        self.timeout = timeout
+        self._container_id: Optional[str] = None
+
+    def _run_docker(self, args: list[str], timeout: int = None) -> subprocess.CompletedProcess:
+        cmd = ["docker"] + args
+        t = timeout or self.timeout
+        return subprocess.run(cmd, capture_output=True, text=True, timeout=t)
+
+    def ensure_image(self):
+        """Pull the sandbox image if not present."""
+        result = self._run_docker(["images", "-q", self.image])
+        if not result.stdout.strip():
+            r = self._run_docker(["pull", self.image], timeout=300)
+            if r.returncode != 0:
+                raise SandboxError(f"Failed to pull image: {r.stderr}")
+
+    def create(self, repo_path: str, env_vars: dict[str, str] = None) -> str:
+        """Create a sandbox container from the repo and return its ID."""
+        self.ensure_image()
+        env_args = []
+        if env_vars:
+            for k, v in env_vars.items():
+                env_args.extend(["-e", f"{k}={v}"])
+
+        result = self._run_docker([
+            "run", "-d", "--rm",
+            "--memory", self.memory_limit,
+            "--cpus", str(self.cpu_limit),
+            "-v", f"{os.path.abspath(repo_path)}:/workspace",
+            "-w", "/workspace",
+        ] + env_args + [self.image, "sleep", "infinity"])
+
+        if result.returncode != 0:
+            raise SandboxError(f"Failed to create sandbox: {result.stderr}")
+        self._container_id = result.stdout.strip()
+        return self._container_id
+
+    def exec(self, command: str, timeout: int = None) -> tuple[int, str, str]:
+        """Execute a command inside the sandbox. Returns (returncode, stdout, stderr)."""
+        if not self._container_id:
+            raise SandboxError("No sandbox container. Call create() first.")
+        result = self._run_docker([
+            "exec", self._container_id, "bash", "-c", command
+        ], timeout=timeout)
+        return result.returncode, result.stdout, result.stderr
+
+    def destroy(self):
+        """Stop and remove the sandbox container."""
+        if self._container_id:
+            self._run_docker(["stop", self._container_id])
+            self._container_id = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.destroy()

package/verification/diagnostic.py

@@ -0,0 +1,124 @@
+"""Diagnostic Aggregator — deterministic rule engine for verdict aggregation."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from protocol.schemas import (
+    Verdict, SemanticVerdict, ConvergenceDecision, ConcurrencyAction,
+    EscalationReport, VerdictOverall, ConflictType, Alignment,
+)
+
+
+@dataclass
+class AggregatorResult:
+    action: ConcurrencyAction
+    reason: str
+    fix_strategy: Optional[str] = None
+    escalation: Optional[EscalationReport] = None
+    conflict_type: Optional[ConflictType] = None
+    needs_human: bool = False
+
+
+class DiagnosticAggregator:
+    """Merges multiple Verifier outputs using deterministic rules.
+
+    This is NOT an LLM-based agent. It uses a rule engine because:
+    1. Aggregation must be predictable and auditable
+    2. No black-box decisions in the critical path
+    3. Fast — runs in microseconds, not seconds
+    """
+
+    def __init__(self, config: dict = None):
+        self.config = config or {}
+
+    def aggregate_l1(self, static: Verdict, dynamic: Verdict,
+                     task_id: str) -> AggregatorResult:
+        """Aggregate Static + Dynamic verdicts (L1 convergence check)."""
+
+        # Both PASS → advance
+        if (static.overall == VerdictOverall.PASS and
+                dynamic.overall == VerdictOverall.PASS):
+            return AggregatorResult(
+                action=ConcurrencyAction.PASS,
+                reason="L1: Static and Dynamic verification both passed",
+            )
+
+        # Either FAIL → determine if fixable or needs escalation
+        all_findings = static.findings + dynamic.findings
+        critical_findings = [f for f in all_findings
+                             if f.severity in ("CRITICAL", "HIGH")]
+        matched_findings = [f for f in critical_findings
+                            if f.matched_signature]
+
+        if matched_findings:
+            # We have known fixes for some failures
+            return AggregatorResult(
+                action=ConcurrencyAction.FIX,
+                reason=f"L1: {len(matched_findings)} findings matched known signatures",
+                fix_strategy=matched_findings[0].matched_signature,
+            )
+        elif critical_findings:
+            # Unknown critical issues → escalate
+            return AggregatorResult(
+                action=ConcurrencyAction.ESCALATE,
+                reason=f"L1: {len(critical_findings)} critical findings with no known fix",
+                needs_human=True,
+            )
+        else:
+            # WARN/LOW only → pass with caution
+            return AggregatorResult(
+                action=ConcurrencyAction.PASS,
+                reason="L1: No critical findings, passing with warnings",
+            )
+
+    def aggregate_l2(self, static: Verdict, dynamic: Verdict,
+                     semantic: SemanticVerdict,
+                     mutation: Optional[Verdict],
+                     task_id: str) -> AggregatorResult:
+        """Aggregate L1 + Semantic + Mutation (L2 convergence check)."""
+
+        # Check L1 first
+        l1 = self.aggregate_l1(static, dynamic, task_id)
+        if l1.action != ConcurrencyAction.PASS:
+            return l1
+
+        # Check semantic alignment
+        if semantic.alignment == Alignment.DEVIATED:
+            return AggregatorResult(
+                action=ConcurrencyAction.ESCALATE,
+                reason=f"L2: Semantic alignment DEVIATED — {semantic.reasoning}",
+                conflict_type=ConflictType.INTERPRETATION,
+                needs_human=True,
+            )
+        elif semantic.alignment == Alignment.CONFLICT:
+            return AggregatorResult(
+                action=ConcurrencyAction.CONFLICT,
+                reason=f"L2: Semantic CONFLICT detected — {semantic.reasoning}",
+                conflict_type=ConflictType.INTERPRETATION,
+                needs_human=True,
+            )
+        elif semantic.alignment == Alignment.ENHANCED:
+            # Flag for human review but don't block
+            return AggregatorResult(
+                action=ConcurrencyAction.PASS,
+                reason="L2: Semantically ENHANCED — changes exceed Spec but are reasonable. Human review recommended.",
+            )
+
+        # Check mutation
+        if mutation and mutation.overall == VerdictOverall.FAIL:
+            return AggregatorResult(
+                action=ConcurrencyAction.FIX,
+                reason="L2: Mutation testing found coverage gaps",
+            )
+
+        return AggregatorResult(
+            action=ConcurrencyAction.PASS,
+            reason="L2: All verification layers passed",
+        )
+
+    def detect_conflict(self, verdicts: list[Verdict]) -> Optional[ConflictType]:
+        """Detect if multiple verdicts contradict each other."""
+        # FACT conflict: Static says PASS, Dynamic says FAIL for same assertion
+        # INTERPRETATION: Semantic says DEVIATED but Static/Dynamic say PASS
+        # SPEC_AMBIGUITY: Multiple Semantic verdicts with different interpretations
+        return None  # MVP: basic conflict detection

package/verification/patterns/api_breaking.yaml

@@ -0,0 +1,25 @@
+# API breaking change detection rules
+patterns:
+  - id: P001
+    name: public_api_break
+    desc: "Public function signature changed but callers not updated in this diff"
+    severity: HIGH
+    detector:
+      type: ast_diff
+      rule: "function signature changed AND call sites unchanged"
+
+  - id: P002
+    name: removed_public_symbol
+    desc: "Public class/function/module removed without deprecation period"
+    severity: HIGH
+    detector:
+      type: ast_diff
+      rule: "public symbol removed AND no deprecation warning added"
+
+  - id: P003
+    name: return_type_changed
+    desc: "Function return type changed — may break downstream consumers"
+    severity: HIGH
+    detector:
+      type: ast_diff
+      rule: "return type annotation changed AND callers not updated"

package/verification/patterns/code_quality.yaml

@@ -0,0 +1,41 @@
+# Code quality regression detection rules
+patterns:
+  - id: Q001
+    name: error_swallowed
+    desc: "Exception caught but not handled or logged"
+    severity: MEDIUM
+    detector:
+      type: ast_pattern
+      rule: "except block with empty body or bare pass"
+
+  - id: Q002
+    name: overly_broad_except
+    desc: "Bare 'except:' or 'except Exception:' without specific types"
+    severity: LOW
+    detector:
+      type: ast_pattern
+      rule: "bare except or except Exception without specific exception types"
+
+  - id: Q003
+    name: dependency_drift
+    desc: "New external dependency introduced without explicit version pinning"
+    severity: MEDIUM
+    detector:
+      type: file_diff
+      rule: "new entry in requirements.txt/Cargo.toml/package.json without version"
+
+  - id: Q004
+    name: commented_out_code
+    desc: "Blocks of commented-out code added — should be removed"
+    severity: LOW
+    detector:
+      type: pattern_match
+      rule: "5+ consecutive lines of commented-out code in diff"
+
+  - id: Q005
+    name: todo_without_ticket
+    desc: "TODO/FIXME comment without issue tracker reference"
+    severity: LOW
+    detector:
+      type: pattern_match
+      rule: "TODO|FIXME|HACK without issue/PR reference"