devsper 2.1.6__py3-none-any.whl

devsper/agents/message_bus.py

@@ -0,0 +1,124 @@
+"""
+Per-run pub/sub channel for agent-to-agent messaging. v1.7.
+Agents broadcast discoveries; subsequent agents receive them via memory context.
+Not persistent — lives only for the duration of a run.
+"""
+
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from devsper.types.event import Event, events
+
+
+@dataclass
+class AgentMessage:
+    sender_task_id: str
+    content: str
+    tags: list[str]
+    timestamp: str
+
+
+class SwarmMessageBus:
+    """
+    Per-run pub/sub channel. Agents broadcast discoveries;
+    all subsequent agents receive them via memory context.
+    Not persistent — lives only for the duration of a run.
+    """
+
+    def __init__(self, event_log=None):
+        self._messages: list[AgentMessage] = []
+        self._lock = asyncio.Lock()
+        self._event_log = event_log
+
+    def _emit(self, event_type: events, payload: dict) -> None:
+        if self._event_log:
+            self._event_log.append_event(
+                Event(
+                    timestamp=datetime.now(timezone.utc),
+                    type=event_type,
+                    payload=payload,
+                )
+            )
+
+    async def broadcast(
+        self, sender_task_id: str, content: str, tags: list[str] | None = None
+    ) -> None:
+        """Agent calls this when it discovers something worth sharing."""
+        tags = tags or []
+        async with self._lock:
+            self._messages.append(
+                AgentMessage(
+                    sender_task_id=sender_task_id,
+                    content=content,
+                    tags=tags,
+                    timestamp=datetime.now(timezone.utc).isoformat(),
+                )
+            )
+        self._emit(
+            events.AGENT_BROADCAST,
+            {
+                "sender_task_id": sender_task_id,
+                "content_preview": (content or "")[:100],
+            },
+        )
+
+    def broadcast_sync(
+        self, sender_task_id: str, content: str, tags: list[str] | None = None
+    ) -> None:
+        """Synchronous broadcast for use from sync agent.run()."""
+        tags = tags or []
+        self._messages.append(
+            AgentMessage(
+                sender_task_id=sender_task_id,
+                content=content,
+                tags=tags,
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+        )
+        self._emit(
+            events.AGENT_BROADCAST,
+            {
+                "sender_task_id": sender_task_id,
+                "content_preview": (content or "")[:100],
+            },
+        )
+
+    async def get_context(
+        self, requesting_task_id: str, max_messages: int = 5
+    ) -> str:
+        """
+        Return formatted string of recent broadcasts for injection into agent prompt.
+        Exclude messages from requesting_task_id itself.
+        Return most recent max_messages.
+        """
+        async with self._lock:
+            eligible = [
+                m
+                for m in self._messages
+                if m.sender_task_id != requesting_task_id
+            ]
+            recent = eligible[-max_messages:] if len(eligible) > max_messages else eligible
+        if not recent:
+            return ""
+        lines = ["Shared Discoveries (from other agents in this run):"]
+        for m in recent:
+            lines.append(f"- [{m.sender_task_id}]: {m.content[:500]}{'...' if len(m.content) > 500 else ''}")
+        return "\n".join(lines)
+
+    def get_context_sync(
+        self, requesting_task_id: str, max_messages: int = 5
+    ) -> str:
+        """Synchronous get_context for use from sync agent.run()."""
+        eligible = [
+            m
+            for m in self._messages
+            if m.sender_task_id != requesting_task_id
+        ]
+        recent = eligible[-max_messages:] if len(eligible) > max_messages else eligible
+        if not recent:
+            return ""
+        lines = ["Shared Discoveries (from other agents in this run):"]
+        for m in recent:
+            lines.append(f"- [{m.sender_task_id}]: {m.content[:500]}{'...' if len(m.content) > 500 else ''}")
+        return "\n".join(lines)

devsper/agents/roles.py

@@ -0,0 +1,181 @@
+"""
+Specialized agent roles: research, code, analysis, critic.
+
+Role determines tool access, prompt template, and model selection.
+Planner assigns roles based on task type.
+"""
+
+from dataclasses import dataclass
+
+RESEARCH_AGENT = "research_agent"
+CODE_AGENT = "code_agent"
+ANALYSIS_AGENT = "analysis_agent"
+CRITIC_AGENT = "critic_agent"
+
+# Dev / autonomous builder roles
+ARCHITECT_AGENT = "architect_agent"
+BACKEND_AGENT = "backend_agent"
+FRONTEND_AGENT = "frontend_agent"
+TEST_AGENT = "test_agent"
+REVIEW_AGENT = "review_agent"
+
+DEFAULT_ROLE = "general"
+
+
+@dataclass
+class RoleConfig:
+    """Configuration for an agent role."""
+
+    name: str
+    tool_categories: list[str]  # e.g. ["research", "documents"]
+    prompt_prefix: str
+    model_hint: str  # e.g. "analysis", "planning" for model router
+
+
+ROLE_CONFIGS: dict[str, RoleConfig] = {
+    RESEARCH_AGENT: RoleConfig(
+        name=RESEARCH_AGENT,
+        tool_categories=[
+            "research",
+            "research_advanced",
+            "documents",
+            "knowledge",
+            "memory",
+            "mcp",
+        ],
+        prompt_prefix="You are a research specialist. Focus on literature, citations, methodology, and evidence.",
+        model_hint="analysis",
+    ),
+    CODE_AGENT: RoleConfig(
+        name=CODE_AGENT,
+        tool_categories=["coding", "code_intelligence", "filesystem", "system", "mcp"],
+        prompt_prefix="You are a code specialist. Focus on implementation, structure, tests, and refactoring.",
+        model_hint="analysis",
+    ),
+    ANALYSIS_AGENT: RoleConfig(
+        name=ANALYSIS_AGENT,
+        tool_categories=["data", "data_science", "math", "experiments", "knowledge", "mcp"],
+        prompt_prefix="You are an analysis specialist. Focus on data, metrics, statistics, and interpretation.",
+        model_hint="analysis",
+    ),
+    CRITIC_AGENT: RoleConfig(
+        name=CRITIC_AGENT,
+        tool_categories=["documents", "memory", "knowledge"],
+        prompt_prefix="You are a critic/reviewer. Evaluate quality, consistency, and gaps. Be concise and constructive.",
+        model_hint="analysis",
+    ),
+    DEFAULT_ROLE: RoleConfig(
+        name=DEFAULT_ROLE,
+        tool_categories=[],  # empty = no filter; all tools (including mcp) eligible
+        prompt_prefix="You are an AI worker in a distributed system.",
+        model_hint="analysis",
+    ),
+    # Dev / autonomous builder roles
+    ARCHITECT_AGENT: RoleConfig(
+        name=ARCHITECT_AGENT,
+        tool_categories=["code_intelligence", "filesystem"],
+        prompt_prefix="You are an architect. Design system structure, APIs, and component layout. Output clear architecture plans (backend/frontend stack, modules, data flow).",
+        model_hint="planning",
+    ),
+    BACKEND_AGENT: RoleConfig(
+        name=BACKEND_AGENT,
+        tool_categories=["coding", "code_intelligence", "filesystem", "system"],
+        prompt_prefix="You are a backend specialist. Implement APIs, models, and server logic. Prefer FastAPI/Flask patterns and clear interfaces.",
+        model_hint="analysis",
+    ),
+    FRONTEND_AGENT: RoleConfig(
+        name=FRONTEND_AGENT,
+        tool_categories=["coding", "filesystem", "system"],
+        prompt_prefix="You are a frontend specialist. Implement UI components, pages, and client logic. Prefer simple HTML/JS or React patterns.",
+        model_hint="analysis",
+    ),
+    TEST_AGENT: RoleConfig(
+        name=TEST_AGENT,
+        tool_categories=["coding", "code_intelligence", "filesystem", "system"],
+        prompt_prefix="You are a test specialist. Write unit and integration tests. Use pytest for Python; ensure coverage of main flows.",
+        model_hint="analysis",
+    ),
+    REVIEW_AGENT: RoleConfig(
+        name=REVIEW_AGENT,
+        tool_categories=["code_intelligence", "coding", "filesystem"],
+        prompt_prefix="You are a code reviewer. Check correctness, style, and gaps. Suggest concrete fixes. Be concise.",
+        model_hint="analysis",
+    ),
+}
+
+
+def get_role_config(role: str | None) -> RoleConfig:
+    """Return config for the given role, or default if unknown/None."""
+    if role and role in ROLE_CONFIGS:
+        return ROLE_CONFIGS[role]
+    return ROLE_CONFIGS[DEFAULT_ROLE]
+
+
+# Keywords to infer role from task description
+RESEARCH_KEYWORDS = [
+    "research",
+    "paper",
+    "literature",
+    "cite",
+    "survey",
+    "methodology",
+    "findings",
+]
+CODE_KEYWORDS = [
+    "code",
+    "implement",
+    "refactor",
+    "test",
+    "repository",
+    "function",
+    "api",
+    "lint",
+    "list",
+    "directory",
+    "files",
+    "contents",
+    "path",
+    "read file",
+    "write file",
+]
+ANALYSIS_KEYWORDS = [
+    "analyze",
+    "data",
+    "metric",
+    "statistic",
+    "plot",
+    "dataset",
+    "experiment",
+    "evaluate",
+]
+CRITIC_KEYWORDS = [
+    "review",
+    "critique",
+    "evaluate",
+    "quality",
+    "check",
+    "verify",
+    "feedback",
+]
+
+# Dev builder: explicit roles are set by planner; no inference needed for build tasks
+DEV_ROLES = [
+    ARCHITECT_AGENT,
+    BACKEND_AGENT,
+    FRONTEND_AGENT,
+    TEST_AGENT,
+    REVIEW_AGENT,
+]
+
+
+def infer_role_from_description(description: str) -> str:
+    """Infer agent role from task description. Returns role name or DEFAULT_ROLE."""
+    text = (description or "").lower()
+    scores = {
+        RESEARCH_AGENT: sum(1 for k in RESEARCH_KEYWORDS if k in text),
+        CODE_AGENT: sum(1 for k in CODE_KEYWORDS if k in text),
+        ANALYSIS_AGENT: sum(1 for k in ANALYSIS_KEYWORDS if k in text),
+        CRITIC_AGENT: sum(1 for k in CRITIC_KEYWORDS if k in text),
+    }
+    best = max(scores, key=scores.get)
+    return best if scores[best] > 0 else DEFAULT_ROLE

devsper/agents/run_agent.py

@@ -0,0 +1,78 @@
+"""
+Entry point for Rust worker subprocess executor.
+Reads AgentRequest JSON from stdin, runs agent, writes AgentResponse JSON to stdout.
+Exit 0 on success, 1 on error (error details in AgentResponse.error on stdout).
+"""
+
+import json
+import sys
+
+from devsper.credentials import inject_into_env
+from devsper.agents.agent import Agent, AgentRequest, AgentResponse
+
+
+def run_agent_sync(request_json: str) -> str:
+    """Run agent from JSON request string; return JSON response string. Used by PyO3 executor."""
+    data = json.loads(request_json)
+    request = AgentRequest.from_dict(data)
+    agent = Agent()
+    response = agent.run(request)  # sync, not async
+    return json.dumps(response.to_dict())
+
+
+def main() -> None:
+    # So the subprocess can use GitHub/OpenAI etc.: inject keychain credentials into env
+    # (same as config resolver does for the Python worker).
+    inject_into_env()
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            out = AgentResponse(
+                task_id="",
+                result="",
+                tools_called=[],
+                broadcasts=[],
+                tokens_used=None,
+                duration_seconds=0.0,
+                error="Empty stdin",
+                success=False,
+            )
+            print(json.dumps(out.to_dict()), flush=True)
+            sys.exit(1)
+        request = AgentRequest.from_dict(json.loads(raw))
+    except Exception as e:
+        out = AgentResponse(
+            task_id="",
+            result="",
+            tools_called=[],
+            broadcasts=[],
+            tokens_used=None,
+            duration_seconds=0.0,
+            error=str(e),
+            success=False,
+        )
+        print(json.dumps(out.to_dict()), flush=True)
+        sys.exit(1)
+
+    try:
+        agent = Agent()
+        response = agent.run(request)  # sync, not async
+        print(json.dumps(response.to_dict()), flush=True)
+        sys.exit(0 if response.success else 1)
+    except Exception as e:
+        out = AgentResponse(
+            task_id=request.task.id,
+            result="",
+            tools_called=[],
+            broadcasts=[],
+            tokens_used=None,
+            duration_seconds=0.0,
+            error=str(e),
+            success=False,
+        )
+        print(json.dumps(out.to_dict()), flush=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

devsper/analytics/__init__.py

@@ -0,0 +1,5 @@
+"""Tool usage analytics: count, success rate, latency. Persisted in SQLite."""
+
+from devsper.analytics.tool_analytics import ToolAnalytics, get_default_analytics
+
+__all__ = ["ToolAnalytics", "get_default_analytics"]

devsper/analytics/tool_analytics.py

@@ -0,0 +1,78 @@
+"""
+Track tool usage: count, success rate, latency. Persist in SQLite.
+"""
+
+import sqlite3
+import time
+from pathlib import Path
+
+
+class ToolAnalytics:
+    """SQLite-backed analytics for tool usage: count, success rate, latency."""
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        if db_path is None:
+            db_path = Path(".devsper") / "tool_analytics.db"
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_schema()
+
+    def _conn(self) -> sqlite3.Connection:
+        return sqlite3.connect(str(self.db_path))
+
+    def _init_schema(self) -> None:
+        with self._conn() as c:
+            c.execute("""
+                CREATE TABLE IF NOT EXISTS tool_usage (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    tool_name TEXT NOT NULL,
+                    success INTEGER NOT NULL,
+                    latency_ms REAL NOT NULL,
+                    created_at REAL NOT NULL
+                )
+                """)
+            c.execute(
+                "CREATE INDEX IF NOT EXISTS idx_tool_usage_name ON tool_usage(tool_name)"
+            )
+
+    def record(self, tool_name: str, success: bool, latency_ms: float) -> None:
+        """Record one tool invocation."""
+        with self._conn() as c:
+            c.execute(
+                "INSERT INTO tool_usage (tool_name, success, latency_ms, created_at) VALUES (?, ?, ?, ?)",
+                (tool_name, 1 if success else 0, latency_ms, time.time()),
+            )
+
+    def get_stats(self) -> list[dict]:
+        """Return per-tool stats: name, count, success_rate, avg_latency_ms."""
+        with self._conn() as c:
+            rows = c.execute("""
+                SELECT tool_name,
+                       COUNT(*) AS cnt,
+                       SUM(success) AS ok,
+                       AVG(latency_ms) AS avg_ms
+                FROM tool_usage
+                GROUP BY tool_name
+                ORDER BY cnt DESC
+                """).fetchall()
+        return [
+            {
+                "tool_name": r[0],
+                "count": r[1],
+                "success_count": r[2],
+                "success_rate": (r[2] / r[1] * 100.0) if r[1] else 0.0,
+                "avg_latency_ms": round(r[3], 2) if r[3] is not None else 0.0,
+            }
+            for r in rows
+        ]
+
+
+_default: ToolAnalytics | None = None
+
+
+def get_default_analytics() -> ToolAnalytics:
+    """Return the default analytics instance (singleton)."""
+    global _default
+    if _default is None:
+        _default = ToolAnalytics()
+    return _default

devsper/audit/__init__.py

@@ -0,0 +1,5 @@
+"""Audit logging for compliance (v2.0)."""
+
+from devsper.audit.logger import AuditLogger, AuditRecord
+
+__all__ = ["AuditLogger", "AuditRecord"]

devsper/audit/logger.py

@@ -0,0 +1,214 @@
+"""
+Append-only audit log: JSONL file per run with optional chain integrity.
+"""
+
+import hashlib
+import json
+import os
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+@dataclass
+class AuditRecord:
+    """Single append-only audit entry."""
+    record_id: str
+    timestamp: str
+    run_id: str
+    task_id: str
+    agent_id: str
+    event_type: str
+    actor: str
+    resource: str
+    input_hash: str
+    output_hash: str
+    decision_rationale: str | None = None
+    quota_usage: dict | None = None
+    pii_detected: bool = False
+    pii_redacted: bool = False
+    duration_ms: int = 0
+    success: bool = True
+    prev_record_hash: str = ""
+
+    def to_json_line(self) -> str:
+        d = {
+            "record_id": self.record_id,
+            "timestamp": self.timestamp,
+            "run_id": self.run_id,
+            "task_id": self.task_id,
+            "agent_id": self.agent_id,
+            "event_type": self.event_type,
+            "actor": self.actor,
+            "resource": self.resource,
+            "input_hash": self.input_hash,
+            "output_hash": self.output_hash,
+            "decision_rationale": self.decision_rationale,
+            "quota_usage": self.quota_usage,
+            "pii_detected": self.pii_detected,
+            "pii_redacted": self.pii_redacted,
+            "duration_ms": self.duration_ms,
+            "success": self.success,
+            "prev_record_hash": self.prev_record_hash,
+        }
+        return json.dumps(d, sort_keys=True)
+
+    @classmethod
+    def from_json_line(cls, line: str) -> "AuditRecord":
+        d = json.loads(line)
+        return cls(
+            record_id=d.get("record_id", ""),
+            timestamp=d.get("timestamp", ""),
+            run_id=d.get("run_id", ""),
+            task_id=d.get("task_id", ""),
+            agent_id=d.get("agent_id", ""),
+            event_type=d.get("event_type", ""),
+            actor=d.get("actor", ""),
+            resource=d.get("resource", ""),
+            input_hash=d.get("input_hash", ""),
+            output_hash=d.get("output_hash", ""),
+            decision_rationale=d.get("decision_rationale"),
+            quota_usage=d.get("quota_usage"),
+            pii_detected=bool(d.get("pii_detected", False)),
+            pii_redacted=bool(d.get("pii_redacted", False)),
+            duration_ms=int(d.get("duration_ms", 0)),
+            success=bool(d.get("success", True)),
+            prev_record_hash=d.get("prev_record_hash", ""),
+        )
+
+
+def _sha256(s: str) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def make_audit_record(
+    run_id: str,
+    task_id: str,
+    event_type: str,
+    actor: str = "",
+    resource: str = "",
+    input_text: str = "",
+    output_text: str = "",
+    duration_ms: int = 0,
+    success: bool = True,
+    pii_detected: bool = False,
+    pii_redacted: bool = False,
+    agent_id: str = "",
+) -> AuditRecord:
+    """Build an AuditRecord with hashes; agent_id = node_id + task_id or task_id."""
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+    return AuditRecord(
+        record_id=str(uuid.uuid4()),
+        timestamp=ts,
+        run_id=run_id,
+        task_id=task_id,
+        agent_id=agent_id or task_id,
+        event_type=event_type,
+        actor=actor,
+        resource=resource,
+        input_hash=_sha256(input_text),
+        output_hash=_sha256(output_text),
+        pii_detected=pii_detected,
+        pii_redacted=pii_redacted,
+        duration_ms=duration_ms,
+        success=success,
+    )
+
+
+class AuditLogger:
+    """Write-once append-only audit log. Backend: JSONL file under data_dir/audit/{run_id}.audit.jsonl."""
+
+    def __init__(self, data_dir: str, run_id: str = "") -> None:
+        self.data_dir = data_dir
+        self.run_id = run_id
+        self._audit_dir = os.path.join(data_dir, "audit")
+        self._last_hash: str = ""
+        self._file_path: str | None = None
+
+    def _path(self, run_id: str) -> str:
+        return os.path.join(self._audit_dir, f"{run_id or self.run_id}.audit.jsonl")
+
+    def _ensure_chain(self, path: str) -> None:
+        """Load last line hash from file so chain continues."""
+        if self._file_path == path:
+            return
+        self._file_path = path
+        self._last_hash = ""
+        if os.path.isfile(path):
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    for line in f:
+                        line = line.strip()
+                        if line:
+                            self._last_hash = _sha256(line)
+            except Exception:
+                pass
+
+    def log(self, record: AuditRecord) -> None:
+        """Append one record to the run's audit file. Permissions 0o600."""
+        run_id = record.run_id or self.run_id
+        if not run_id:
+            return
+        path = self._path(run_id)
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        self._ensure_chain(path)
+        record.prev_record_hash = self._last_hash
+        line = record.to_json_line()
+        self._last_hash = _sha256(line)
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+        try:
+            os.chmod(path, 0o600)
+        except Exception:
+            pass
+
+    def export(self, run_id: str, format: str = "jsonl") -> str:
+        """Return formatted export for compliance (jsonl, csv, siem)."""
+        path = self._path(run_id)
+        if not os.path.isfile(path):
+            return ""
+        with open(path, "r", encoding="utf-8") as f:
+            lines = [ln.strip() for ln in f if ln.strip()]
+        records = [AuditRecord.from_json_line(ln) for ln in lines]
+        if format == "jsonl":
+            return "\n".join(r.to_json_line() for r in records)
+        if format == "csv":
+            headers = [
+                "record_id", "timestamp", "run_id", "task_id", "event_type",
+                "actor", "resource", "success", "duration_ms", "pii_detected", "pii_redacted",
+            ]
+            rows = [
+                ",".join(
+                    str(getattr(r, h, "")).replace(",", ";")
+                    for h in headers
+                )
+                for r in records
+            ]
+            return ",".join(headers) + "\n" + "\n".join(rows)
+        if format == "siem":
+            return json.dumps([r.to_json_line() for r in records])
+        return "\n".join(r.to_json_line() for r in records)
+
+    @staticmethod
+    def verify(run_id: str, data_dir: str) -> tuple[bool, str]:
+        """
+        Verify chain integrity: each record's prev_record_hash must match previous line hash.
+        Return (ok, message).
+        """
+        audit_dir = os.path.join(data_dir, "audit")
+        path = os.path.join(audit_dir, f"{run_id}.audit.jsonl")
+        if not os.path.isfile(path):
+            return False, "Audit file not found"
+        prev_hash = ""
+        with open(path, "r", encoding="utf-8") as f:
+            for i, line in enumerate(f, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                rec = AuditRecord.from_json_line(line)
+                expected = _sha256(line)
+                if rec.prev_record_hash != prev_hash:
+                    return False, f"Chain break at record {i}: prev_record_hash mismatch"
+                prev_hash = expected
+        return True, "Chain intact"