codegraph-engine 2.3.0__py3-none-any.whl → 3.0.1__py3-none-any.whl

codegraph/memory/trajectory.py

@@ -0,0 +1,282 @@
+"""Long-Term Agent Trajectory & Debugging Memory for CodeGraph.
+
+Maintains persistent, FTS5 full-text indexed records of past agent debugging sessions,
+bug investigations, test repair trajectories, and architectural decisions to accelerate future
+agent tasks and eliminate repeated troubleshooting mistakes.
+"""
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class AgentMemoryRecord:
+    id: str
+    created_at: str
+    session_id: str
+    category: str  # BUG_FIX, ARCHITECTURE_DECISION, TEST_PATTERN, ROOT_CAUSE, REFACTORING
+    title: str
+    symptoms: str
+    root_cause: str
+    resolution: str
+    files: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+    outcome: str = "SUCCESS"
+    score: float = 1.0
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "created_at": self.created_at,
+            "session_id": self.session_id,
+            "category": self.category,
+            "title": self.title,
+            "symptoms": self.symptoms,
+            "root_cause": self.root_cause,
+            "resolution": self.resolution,
+            "files": self.files,
+            "tags": self.tags,
+            "outcome": self.outcome,
+            "score": round(self.score, 3),
+        }
+
+
+class TrajectoryMemoryStore:
+    """Persistent SQLite + FTS5 store for agent debugging trajectories."""
+
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = db_path
+        self._init_db()
+
+    def _init_db(self) -> None:
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        with sqlite3.connect(self.db_path) as con:
+            con.execute("PRAGMA journal_mode = WAL")
+            con.execute("PRAGMA synchronous = NORMAL")
+            con.execute(
+                """
+                CREATE TABLE IF NOT EXISTS agent_trajectories (
+                    id TEXT PRIMARY KEY,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    session_id TEXT NOT NULL,
+                    category TEXT NOT NULL,
+                    title TEXT NOT NULL,
+                    symptoms TEXT NOT NULL DEFAULT '',
+                    root_cause TEXT NOT NULL DEFAULT '',
+                    resolution TEXT NOT NULL DEFAULT '',
+                    files_json TEXT NOT NULL DEFAULT '[]',
+                    tags_json TEXT NOT NULL DEFAULT '[]',
+                    outcome TEXT NOT NULL DEFAULT 'SUCCESS'
+                )
+                """
+            )
+            con.execute(
+                """
+                CREATE VIRTUAL TABLE IF NOT EXISTS agent_trajectories_fts USING fts5(
+                    id UNINDEXED,
+                    title,
+                    symptoms,
+                    root_cause,
+                    resolution,
+                    content='agent_trajectories',
+                    content_rowid='rowid'
+                )
+                """
+            )
+
+    def store(
+        self,
+        title: str,
+        resolution: str,
+        category: str = "BUG_FIX",
+        session_id: str | None = None,
+        symptoms: str = "",
+        root_cause: str = "",
+        files: list[str] | None = None,
+        tags: list[str] | None = None,
+        outcome: str = "SUCCESS",
+    ) -> AgentMemoryRecord:
+        """Store an agent debugging or architectural trajectory into memory."""
+        mem_id = f"mem_{uuid.uuid4().hex[:12]}"
+        sess = session_id or f"sess_{uuid.uuid4().hex[:8]}"
+        files_json = json.dumps(files or [])
+        tags_json = json.dumps(tags or [])
+
+        with sqlite3.connect(self.db_path) as con:
+            cur = con.cursor()
+            cur.execute(
+                """
+                INSERT INTO agent_trajectories (
+                    id, session_id, category, title, symptoms, root_cause, resolution, files_json, tags_json, outcome
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (mem_id, sess, category, title, symptoms, root_cause, resolution, files_json, tags_json, outcome),
+            )
+            # Update FTS5
+            cur.execute(
+                """
+                INSERT INTO agent_trajectories_fts (rowid, id, title, symptoms, root_cause, resolution)
+                VALUES (last_insert_rowid(), ?, ?, ?, ?, ?)
+                """,
+                (mem_id, title, symptoms, root_cause, resolution),
+            )
+            con.commit()
+
+        return AgentMemoryRecord(
+            id=mem_id,
+            created_at=time.strftime("%Y-%m-%d %H:%M:%S"),
+            session_id=sess,
+            category=category,
+            title=title,
+            symptoms=symptoms,
+            root_cause=root_cause,
+            resolution=resolution,
+            files=files or [],
+            tags=tags or [],
+            outcome=outcome,
+        )
+
+    def search(
+        self,
+        query: str,
+        category: str | None = None,
+        limit: int = 5,
+        max_tokens: int = 1500,
+    ) -> list[AgentMemoryRecord]:
+        """Search past agent memories using FTS5 BM25 relevance and recency weighting."""
+        clean_q = query.strip()
+        if not clean_q:
+            return self.list_recent(limit=limit)
+
+        records: list[AgentMemoryRecord] = []
+        with sqlite3.connect(self.db_path) as con:
+            con.row_factory = sqlite3.Row
+            # FTS5 search
+            safe_query = re.sub(r'[^\w\s]', ' ', clean_q).strip()
+            if not safe_query:
+                return self.list_recent(limit=limit)
+
+            match_clause = "agent_trajectories_fts MATCH ?"
+            params: list[Any] = [safe_query]
+
+            cat_clause = ""
+            if category:
+                cat_clause = "AND t.category = ?"
+                params.append(category)
+
+            sql = f"""
+                SELECT t.id, t.created_at, t.session_id, t.category, t.title,
+                       t.symptoms, t.root_cause, t.resolution, t.files_json, t.tags_json, t.outcome,
+                       bm25(agent_trajectories_fts) as rank
+                FROM agent_trajectories_fts fts
+                JOIN agent_trajectories t ON t.rowid = fts.rowid
+                WHERE {match_clause} {cat_clause}
+                ORDER BY rank ASC
+                LIMIT ?
+            """
+            params.append(limit * 2)
+
+            try:
+                rows = con.execute(sql, params).fetchall()
+            except sqlite3.OperationalError:
+                # Fallback to LIKE
+                like_sql = """
+                    SELECT id, created_at, session_id, category, title, symptoms, root_cause, resolution,
+                           files_json, tags_json, outcome, 1.0 as rank
+                    FROM agent_trajectories
+                    WHERE title LIKE ? OR resolution LIKE ? OR symptoms LIKE ?
+                    ORDER BY id DESC LIMIT ?
+                """
+                rows = con.execute(like_sql, (f"%{clean_q}%", f"%{clean_q}%", f"%{clean_q}%", limit)).fetchall()
+
+            total_chars = 0
+            char_budget = max_tokens * 4
+
+            for r in rows:
+                files = json.loads(r["files_json"]) if r["files_json"] else []
+                tags = json.loads(r["tags_json"]) if r["tags_json"] else []
+                bm_score = float(r["rank"])
+                relevance = round(1.0 / (1.0 + max(0.0, bm_score)), 3)
+
+                rec = AgentMemoryRecord(
+                    id=r["id"],
+                    created_at=str(r["created_at"]),
+                    session_id=r["session_id"],
+                    category=r["category"],
+                    title=r["title"],
+                    symptoms=r["symptoms"],
+                    root_cause=r["root_cause"],
+                    resolution=r["resolution"],
+                    files=files,
+                    tags=tags,
+                    outcome=r["outcome"],
+                    score=relevance,
+                )
+
+                # Token budget check
+                rec_len = len(rec.title) + len(rec.symptoms) + len(rec.root_cause) + len(rec.resolution)
+                if total_chars + rec_len > char_budget and records:
+                    break
+                total_chars += rec_len
+                records.append(rec)
+                if len(records) >= limit:
+                    break
+
+        return records
+
+    def list_recent(self, limit: int = 10) -> list[AgentMemoryRecord]:
+        """List most recent agent memories."""
+        records: list[AgentMemoryRecord] = []
+        with sqlite3.connect(self.db_path) as con:
+            con.row_factory = sqlite3.Row
+            rows = con.execute(
+                """
+                SELECT id, created_at, session_id, category, title, symptoms, root_cause,
+                       resolution, files_json, tags_json, outcome
+                FROM agent_trajectories
+                ORDER BY rowid DESC
+                LIMIT ?
+                """,
+                (limit,),
+            ).fetchall()
+
+            for r in rows:
+                files = json.loads(r["files_json"]) if r["files_json"] else []
+                tags = json.loads(r["tags_json"]) if r["tags_json"] else []
+                records.append(
+                    AgentMemoryRecord(
+                        id=r["id"],
+                        created_at=str(r["created_at"]),
+                        session_id=r["session_id"],
+                        category=r["category"],
+                        title=r["title"],
+                        symptoms=r["symptoms"],
+                        root_cause=r["root_cause"],
+                        resolution=r["resolution"],
+                        files=files,
+                        tags=tags,
+                        outcome=r["outcome"],
+                        score=1.0,
+                    )
+                )
+        return records
+
+    def clear(self) -> None:
+        """Clear all stored agent trajectories."""
+        with sqlite3.connect(self.db_path) as con:
+            con.execute("DELETE FROM agent_trajectories")
+            con.execute("DELETE FROM agent_trajectories_fts")
+            con.commit()
+
+
+def get_trajectory_memory_store(repository: Path) -> TrajectoryMemoryStore:
+    """Get the default trajectory memory store for a repository."""
+    db_path = repository.resolve() / ".codegraph" / "memory.sqlite3"
+    return TrajectoryMemoryStore(db_path)

codegraph/models.py

@@ -56,6 +56,13 @@ EdgeType = Literal[
     "EVENT_LISTENER",
     "TASK_HANDLER",
     "COMMAND_HANDLER",
+    "DISPATCHES_TASK",
+    "TRIGGERS_SIGNAL",
+    "HANDLES_SIGNAL",
+    "RENDERS_TEMPLATE",
+    "DISPATCHES_FORWARD",
+    "TOOL_HANDLER",
+    "PIPELINE_STEP",
     "TESTS",
     "TESTS_ROUTE",
     "TESTS_SYMBOL",

codegraph/monorepo.py

@@ -920,3 +920,6 @@ def detect_workspace(
         unresolved_dependencies=unresolved_dependencies,
         ambiguous_packages=ambiguous_packages,
     )
+
+
+discover_workspace = detect_workspace

codegraph/multi_agent/__init__.py

@@ -0,0 +1,13 @@
+"""Multi-Agent Coordination & Shared Working State for CodeGraph."""
+from __future__ import annotations
+
+from .coordinator import MultiAgentCoordinator
+from .models import AgentSession, FileLease, MultiAgentStatusReport, SemanticConflict
+
+__all__ = [
+    "AgentSession",
+    "FileLease",
+    "MultiAgentCoordinator",
+    "MultiAgentStatusReport",
+    "SemanticConflict",
+]

codegraph/multi_agent/coordinator.py

@@ -0,0 +1,229 @@
+"""Multi-Agent Coordinator & Shared Working State Manager for CodeGraph.
+
+Provides concurrent multi-agent collaboration with:
+- SQLite-backed agent registration and TTL heartbeats (.codegraph/agents.sqlite3)
+- File and module lease locks (EXCLUSIVE_WRITE vs SHARED_READ)
+- Automatic reaping of dead/orphaned agent leases
+- Semantic AST conflict prediction between concurrent agent edits
+"""
+from __future__ import annotations
+
+import sqlite3
+import time
+from pathlib import Path
+
+from .models import AgentSession, FileLease, MultiAgentStatusReport, SemanticConflict
+
+
+class MultiAgentCoordinator:
+    """Coordinates multiple AI coding agents working concurrently on a repository."""
+
+    def __init__(self, repository: Path):
+        self.repository = repository.resolve()
+        self.dot_codegraph = self.repository / ".codegraph"
+        self.dot_codegraph.mkdir(parents=True, exist_ok=True)
+        self.db_path = self.dot_codegraph / "agents.sqlite3"
+        self._init_db()
+
+    def _init_db(self) -> None:
+        with sqlite3.connect(str(self.db_path)) as con:
+            con.execute("PRAGMA journal_mode=WAL;")
+            con.execute("PRAGMA synchronous=NORMAL;")
+            con.execute("""
+                CREATE TABLE IF NOT EXISTS agent_sessions (
+                    agent_id TEXT PRIMARY KEY,
+                    name TEXT NOT NULL,
+                    task_description TEXT NOT NULL,
+                    registered_at REAL NOT NULL,
+                    last_heartbeat REAL NOT NULL,
+                    status TEXT NOT NULL
+                );
+            """)
+            con.execute("""
+                CREATE TABLE IF NOT EXISTS file_leases (
+                    file_path TEXT NOT NULL,
+                    agent_id TEXT NOT NULL,
+                    lease_type TEXT NOT NULL,
+                    granted_at REAL NOT NULL,
+                    expires_at REAL NOT NULL,
+                    PRIMARY KEY (file_path, agent_id)
+                );
+            """)
+            con.commit()
+
+    def register_session(self, agent_id: str, name: str, task_description: str) -> AgentSession:
+        """Register a new or re-activating AI agent session."""
+        now = time.time()
+        with sqlite3.connect(str(self.db_path)) as con:
+            con.execute("""
+                INSERT INTO agent_sessions (agent_id, name, task_description, registered_at, last_heartbeat, status)
+                VALUES (?, ?, ?, ?, ?, 'ACTIVE')
+                ON CONFLICT(agent_id) DO UPDATE SET
+                    name=excluded.name,
+                    task_description=excluded.task_description,
+                    last_heartbeat=excluded.last_heartbeat,
+                    status='ACTIVE';
+            """, (agent_id, name, task_description, now, now))
+            con.commit()
+        return AgentSession(
+            agent_id=agent_id,
+            name=name,
+            task_description=task_description,
+            registered_at=now,
+            last_heartbeat=now,
+            status="ACTIVE",
+        )
+
+    def heartbeat(self, agent_id: str) -> bool:
+        """Send heartbeat to maintain active session and leases."""
+        now = time.time()
+        with sqlite3.connect(str(self.db_path)) as con:
+            cur = con.execute("UPDATE agent_sessions SET last_heartbeat = ? WHERE agent_id = ?;", (now, agent_id))
+            con.commit()
+            return cur.rowcount > 0
+
+    def claim_lease(
+        self,
+        agent_id: str,
+        file_path: str,
+        lease_type: str = "EXCLUSIVE_WRITE",
+        ttl_seconds: float = 60.0,
+    ) -> tuple[bool, str]:
+        """Attempt to claim a lease on a file path."""
+        self.reap_expired_leases()
+        now = time.time()
+        expires = now + ttl_seconds
+        clean_path = str(Path(file_path).as_posix())
+
+        with sqlite3.connect(str(self.db_path)) as con:
+            # Check existing leases on path
+            cur = con.execute("SELECT agent_id, lease_type, expires_at FROM file_leases WHERE file_path = ?;", (clean_path,))
+            rows = cur.fetchall()
+
+            for existing_agent, existing_type, existing_exp in rows:
+                if existing_agent == agent_id:
+                    # Renew own lease
+                    con.execute("UPDATE file_leases SET expires_at = ? WHERE file_path = ? AND agent_id = ?;", (expires, clean_path, agent_id))
+                    con.commit()
+                    return True, "Renewed existing lease."
+
+                if existing_exp > now:
+                    if lease_type == "EXCLUSIVE_WRITE" or existing_type == "EXCLUSIVE_WRITE":
+                        return False, f"Conflict: file '{clean_path}' currently leased by agent '{existing_agent}' ({existing_type})."
+
+            con.execute("""
+                INSERT INTO file_leases (file_path, agent_id, lease_type, granted_at, expires_at)
+                VALUES (?, ?, ?, ?, ?)
+                ON CONFLICT(file_path, agent_id) DO UPDATE SET
+                    lease_type=excluded.lease_type,
+                    expires_at=excluded.expires_at;
+            """, (clean_path, agent_id, lease_type, now, expires))
+            con.commit()
+            return True, f"Lease granted on '{clean_path}' until {expires:.0f}."
+
+    def release_lease(self, agent_id: str, file_path: str | None = None) -> int:
+        """Release leases held by agent. If file_path omitted, releases all leases for agent."""
+        with sqlite3.connect(str(self.db_path)) as con:
+            if file_path:
+                clean_path = str(Path(file_path).as_posix())
+                cur = con.execute("DELETE FROM file_leases WHERE agent_id = ? AND file_path = ?;", (agent_id, clean_path))
+            else:
+                cur = con.execute("DELETE FROM file_leases WHERE agent_id = ?;", (agent_id,))
+            con.commit()
+            return cur.rowcount
+
+    def reap_expired_leases(self) -> int:
+        """Reap leases that have expired past TTL or whose agent heartbeat is stale (>60s)."""
+        now = time.time()
+        with sqlite3.connect(str(self.db_path)) as con:
+            cur = con.execute("DELETE FROM file_leases WHERE expires_at < ?;", (now,))
+            # Mark agents inactive if heartbeat older than 90s
+            con.execute("UPDATE agent_sessions SET status = 'INACTIVE' WHERE (? - last_heartbeat) > 90.0;", (now,))
+            con.commit()
+            return cur.rowcount
+
+    def check_conflicts(self, con: sqlite3.Connection | None = None) -> list[SemanticConflict]:
+        """Inspect all active leases and detect direct write-write conflicts or downstream caller breaks."""
+        self.reap_expired_leases()
+        conflicts: list[SemanticConflict] = []
+        now = time.time()
+
+        with sqlite3.connect(str(self.db_path)) as agent_con:
+            rows = agent_con.execute(
+                "SELECT file_path, agent_id, lease_type FROM file_leases WHERE expires_at > ?;",
+                (now,),
+            ).fetchall()
+
+        leases_by_file: dict[str, list[tuple[str, str]]] = {}
+        for fp, aid, ltype in rows:
+            leases_by_file.setdefault(fp, []).append((aid, ltype))
+
+        # 1. Direct multiple-writer conflict
+        for fp, holders in leases_by_file.items():
+            writers = [aid for aid, ltype in holders if ltype == "EXCLUSIVE_WRITE"]
+            if len(writers) > 1:
+                conflicts.append(
+                    SemanticConflict(
+                        file_path=fp,
+                        conflicting_agents=tuple(writers),
+                        conflict_type="WRITE_WRITE",
+                        reason=f"Multiple agents {writers} hold concurrent write leases on '{fp}'.",
+                    )
+                )
+
+        # 2. Downstream caller contract breaks across leased files if repo connection available
+        if con is not None:
+            try:
+                leased_paths = list(leases_by_file.keys())
+                for fp in leased_paths:
+                    agents_on_file = [aid for aid, _ in leases_by_file[fp]]
+                    # Check calls where source_file is leased by another agent
+                    cur_calls = con.execute(
+                        "SELECT source_file, target_file FROM calls WHERE target_file = ? AND source_file != ?;",
+                        (fp, fp),
+                    )
+                    for caller_file, _ in cur_calls.fetchall():
+                        if caller_file in leases_by_file:
+                            caller_agents = [aid for aid, _ in leases_by_file[caller_file]]
+                            other_agents = [a for a in caller_agents if a not in agents_on_file]
+                            if other_agents:
+                                conflicts.append(
+                                    SemanticConflict(
+                                        file_path=fp,
+                                        conflicting_agents=tuple(sorted(set(agents_on_file + other_agents))),
+                                        conflict_type="DOWNSTREAM_CONTRACT_BREAK",
+                                        reason=f"File '{fp}' leased by {agents_on_file} has caller '{caller_file}' leased by {other_agents}.",
+                                    )
+                                )
+            except Exception:
+                pass
+
+        return conflicts
+
+    def get_status_report(self) -> MultiAgentStatusReport:
+        """Return consolidated multi-agent status report."""
+        self.reap_expired_leases()
+        now = time.time()
+        with sqlite3.connect(str(self.db_path)) as con:
+            cur_agents = con.execute("SELECT agent_id, name, task_description, registered_at, last_heartbeat, status FROM agent_sessions WHERE status = 'ACTIVE';")
+            agents = [
+                AgentSession(agent_id=r[0], name=r[1], task_description=r[2], registered_at=r[3], last_heartbeat=r[4], status=r[5])
+                for r in cur_agents.fetchall()
+            ]
+
+            cur_leases = con.execute("SELECT file_path, agent_id, lease_type, granted_at, expires_at FROM file_leases WHERE expires_at > ?;", (now,))
+            leases = [
+                FileLease(file_path=r[0], agent_id=r[1], lease_type=r[2], granted_at=r[3], expires_at=r[4])
+                for r in cur_leases.fetchall()
+            ]
+
+        conflicts = self.check_conflicts()
+        return MultiAgentStatusReport(
+            workspace=str(self.repository),
+            total_agents=len(agents),
+            active_leases_count=len(leases),
+            conflicts_count=len(conflicts),
+            agents=agents,
+            leases=leases,
+            conflicts=conflicts,
+        )

codegraph/multi_agent/models.py

@@ -0,0 +1,76 @@
+"""Data models for Multi-Agent Shared Working State and Lease Management."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AgentSession:
+    """An active AI coding agent registered in the repository workspace."""
+
+    agent_id: str
+    name: str
+    task_description: str
+    registered_at: float
+    last_heartbeat: float
+    status: str = "ACTIVE"
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class FileLease:
+    """A lease on a file or module held by an AI agent."""
+
+    file_path: str
+    agent_id: str
+    lease_type: str  # EXCLUSIVE_WRITE | SHARED_READ
+    granted_at: float
+    expires_at: float
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class SemanticConflict:
+    """A detected or predicted conflict between multiple concurrent agents."""
+
+    file_path: str
+    conflicting_agents: tuple[str, ...]
+    conflict_type: str  # WRITE_WRITE | DOWNSTREAM_CONTRACT_BREAK
+    reason: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "file_path": self.file_path,
+            "conflicting_agents": list(self.conflicting_agents),
+            "conflict_type": self.conflict_type,
+            "reason": self.reason,
+        }
+
+
+@dataclass
+class MultiAgentStatusReport:
+    """Consolidated workspace report of active agents, leases, and conflicts."""
+
+    workspace: str
+    total_agents: int
+    active_leases_count: int
+    conflicts_count: int
+    agents: list[AgentSession] = field(default_factory=list)
+    leases: list[FileLease] = field(default_factory=list)
+    conflicts: list[SemanticConflict] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "workspace": self.workspace,
+            "total_agents": self.total_agents,
+            "active_leases_count": self.active_leases_count,
+            "conflicts_count": self.conflicts_count,
+            "agents": [a.as_dict() for a in self.agents],
+            "leases": [lease.as_dict() for lease in self.leases],
+            "conflicts": [c.as_dict() for c in self.conflicts],
+        }