attocode-code-intel 0.1.0__py3-none-any.whl

attocode_intel/_internal/tricks/recursive_context.py

@@ -0,0 +1,357 @@
+"""Recursive context retrieval technique.
+
+Implements a strategy where the agent progressively deepens context
+by following references found in initial results. Useful for understanding
+complex code flows that span multiple files.
+
+Strategy:
+1. Start with a seed query (file path, symbol, etc.)
+2. Retrieve initial context
+3. Extract references/imports from the context
+4. Recursively retrieve context for those references
+5. Stop at a depth/token budget limit
+"""
+
+from __future__ import annotations
+
+import re
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from attocode_intel._internal.integrations.utilities.token_estimate import estimate_tokens as _estimate_tokens
+
+
+class ContentProvider(Protocol):
+    """Protocol for retrieving file content."""
+
+    def get_content(self, file_path: str) -> str | None: ...
+
+
+@dataclass(slots=True)
+class ContextNode:
+    """A node in the recursive context tree."""
+
+    file_path: str
+    content: str
+    depth: int
+    references: list[str] = field(default_factory=list)
+    estimated_tokens: int = 0
+    is_truncated: bool = False
+
+    def __post_init__(self) -> None:
+        if self.estimated_tokens == 0 and self.content:
+            self.estimated_tokens = _estimate_tokens(self.content)
+
+
+@dataclass(slots=True)
+class RecursiveContextResult:
+    """Result of recursive context retrieval."""
+
+    nodes: list[ContextNode]
+    total_tokens: int
+    max_depth_reached: int
+    files_visited: int
+    budget_exhausted: bool = False
+
+    @property
+    def content(self) -> str:
+        """Combined content from all nodes."""
+        parts: list[str] = []
+        for node in self.nodes:
+            header = f"--- {node.file_path} (depth {node.depth}) ---"
+            parts.append(f"{header}\n{node.content}")
+        return "\n\n".join(parts)
+
+
+def extract_python_references(content: str, current_file: str = "") -> list[str]:
+    """Extract file references from Python import statements.
+
+    Returns a list of potential file paths derived from imports.
+    """
+    references: list[str] = []
+
+    # from X import Y
+    for match in re.finditer(r"from\s+([\w.]+)\s+import", content):
+        module = match.group(1)
+        # Convert module path to file path
+        path = module.replace(".", "/") + ".py"
+        references.append(path)
+
+    # import X  or  import X, Y, Z
+    for match in re.finditer(r"^import\s+([\w.,\s]+)", content, re.MULTILINE):
+        modules_str = match.group(1)
+        for module in modules_str.split(","):
+            module = module.strip()
+            if module and re.fullmatch(r"[\w.]+", module):
+                path = module.replace(".", "/") + ".py"
+                references.append(path)
+
+    return references
+
+
+def extract_js_references(content: str, current_file: str = "") -> list[str]:
+    """Extract file references from JS/TS import statements.
+
+    Returns a list of potential file paths.
+    """
+    references: list[str] = []
+
+    # import ... from 'path'
+    for match in re.finditer(r"""from\s+['"]([^'"]+)['"]""", content):
+        ref = match.group(1)
+        if ref.startswith("."):
+            # Relative import
+            if not ref.endswith((".js", ".ts", ".tsx", ".jsx")):
+                references.append(ref + ".ts")
+                references.append(ref + ".js")
+            else:
+                references.append(ref)
+
+    # export { X } from './y' (barrel re-exports)
+    for match in re.finditer(r"""export\s+\{[^}]*\}\s+from\s+['"]([^'"]+)['"]""", content):
+        ref = match.group(1)
+        if ref.startswith("."):
+            if not ref.endswith((".js", ".ts", ".tsx", ".jsx")):
+                references.append(ref + ".ts")
+                references.append(ref + ".js")
+            else:
+                references.append(ref)
+
+    # require('path')
+    for match in re.finditer(r"""require\s*\(\s*['"]([^'"]+)['"]\s*\)""", content):
+        ref = match.group(1)
+        if ref.startswith("."):
+            references.append(ref + ".js")
+
+    return references
+
+
+def extract_references(content: str, file_path: str) -> list[str]:
+    """Extract file references based on file type."""
+    if file_path.endswith(".py"):
+        return extract_python_references(content, file_path)
+    elif file_path.endswith((".js", ".ts", ".tsx", ".jsx")):
+        return extract_js_references(content, file_path)
+    return []
+
+
+class RecursiveContextRetriever:
+    """Retrieves context by recursively following references.
+
+    Starting from a seed file, follows imports and references
+    up to a configurable depth and token budget.
+
+    Args:
+        provider: Content provider for reading files.
+        max_depth: Maximum recursion depth (default 3).
+        token_budget: Maximum total tokens across all files.
+        max_files: Maximum number of files to visit.
+    """
+
+    def __init__(
+        self,
+        provider: ContentProvider,
+        *,
+        max_depth: int = 3,
+        token_budget: int = 50_000,
+        max_files: int = 20,
+    ) -> None:
+        self._provider = provider
+        self._max_depth = max_depth
+        self._token_budget = token_budget
+        self._max_files = max_files
+
+    def retrieve(
+        self,
+        seed_files: list[str],
+        *,
+        max_content_per_file: int = 10_000,
+    ) -> RecursiveContextResult:
+        """Recursively retrieve context starting from seed files.
+
+        Args:
+            seed_files: Initial files to start from.
+            max_content_per_file: Maximum characters per file content.
+
+        Returns:
+            A :class:`RecursiveContextResult` with all gathered context.
+        """
+        visited: set[str] = set()
+        nodes: list[ContextNode] = []
+        total_tokens = 0
+        max_depth_reached = 0
+
+        # BFS queue: (file_path, depth)
+        queue: deque[tuple[str, int]] = deque((f, 0) for f in seed_files)
+
+        while queue:
+            file_path, depth = queue.popleft()
+
+            # Skip if already visited
+            if file_path in visited:
+                continue
+
+            # Check limits
+            if depth > self._max_depth:
+                continue
+            if len(visited) >= self._max_files:
+                break
+            if total_tokens >= self._token_budget:
+                break
+
+            visited.add(file_path)
+
+            content = self._provider.get_content(file_path)
+            if content is None:
+                continue
+
+            is_truncated = False
+            if len(content) > max_content_per_file:
+                content = content[:max_content_per_file]
+                is_truncated = True
+
+            # Check if adding this would exceed budget
+            est_tokens = _estimate_tokens(content)
+            if total_tokens + est_tokens > self._token_budget:
+                # Try to fit with truncation
+                remaining = self._token_budget - total_tokens
+                chars = remaining * 4
+                if chars < 200:
+                    break
+                content = content[:chars]
+                is_truncated = True
+                est_tokens = _estimate_tokens(content)
+
+            # Extract references for next depth
+            references = extract_references(content, file_path)
+
+            node = ContextNode(
+                file_path=file_path,
+                content=content,
+                depth=depth,
+                references=references,
+                estimated_tokens=est_tokens,
+                is_truncated=is_truncated,
+            )
+            nodes.append(node)
+            total_tokens += est_tokens
+            max_depth_reached = max(max_depth_reached, depth)
+
+            # Enqueue references for next depth
+            for ref in references:
+                if ref not in visited:
+                    queue.append((ref, depth + 1))
+
+        return RecursiveContextResult(
+            nodes=nodes,
+            total_tokens=total_tokens,
+            max_depth_reached=max_depth_reached,
+            files_visited=len(visited),
+            budget_exhausted=total_tokens >= self._token_budget,
+        )
+
+    def retrieve_with_priority(
+        self,
+        seed_files: list[str],
+        priority_files: list[str] | None = None,
+        *,
+        max_content_per_file: int = 10_000,
+    ) -> RecursiveContextResult:
+        """Retrieve with priority files getting budget preference.
+
+        Priority files are loaded first and given more token budget.
+        Remaining budget is used for recursive exploration.
+        """
+        _priority = set(priority_files or [])
+        visited: set[str] = set()
+        nodes: list[ContextNode] = []
+        total_tokens = 0
+        max_depth_reached = 0
+
+        # Phase 1: Load priority files first (use 50% of budget)
+        priority_budget = self._token_budget // 2
+        for file_path in (priority_files or []):
+            if file_path in visited:
+                continue
+            content = self._provider.get_content(file_path)
+            if content is None:
+                continue
+            visited.add(file_path)
+            is_truncated = False
+            if len(content) > max_content_per_file:
+                content = content[:max_content_per_file]
+                is_truncated = True
+            est_tokens = _estimate_tokens(content)
+            if total_tokens + est_tokens > priority_budget:
+                remaining = priority_budget - total_tokens
+                chars = remaining * 4
+                if chars < 200:
+                    break
+                content = content[:chars]
+                is_truncated = True
+                est_tokens = _estimate_tokens(content)
+            references = extract_references(content, file_path)
+            nodes.append(ContextNode(
+                file_path=file_path,
+                content=content,
+                depth=0,
+                references=references,
+                estimated_tokens=est_tokens,
+                is_truncated=is_truncated,
+            ))
+            total_tokens += est_tokens
+
+        # Phase 2: BFS from seeds with remaining budget
+        queue: deque[tuple[str, int]] = deque(
+            (f, 0) for f in seed_files if f not in visited
+        )
+        # Also enqueue references from priority files
+        for node in nodes:
+            for ref in node.references:
+                if ref not in visited:
+                    queue.append((ref, 1))
+
+        while queue and total_tokens < self._token_budget and len(visited) < self._max_files:
+            file_path, depth = queue.popleft()
+            if file_path in visited or depth > self._max_depth:
+                continue
+            visited.add(file_path)
+            content = self._provider.get_content(file_path)
+            if content is None:
+                continue
+            is_truncated = False
+            if len(content) > max_content_per_file:
+                content = content[:max_content_per_file]
+                is_truncated = True
+            est_tokens = _estimate_tokens(content)
+            if total_tokens + est_tokens > self._token_budget:
+                remaining = self._token_budget - total_tokens
+                chars = remaining * 4
+                if chars < 200:
+                    break
+                content = content[:chars]
+                is_truncated = True
+                est_tokens = _estimate_tokens(content)
+            references = extract_references(content, file_path)
+            nodes.append(ContextNode(
+                file_path=file_path,
+                content=content,
+                depth=depth,
+                references=references,
+                estimated_tokens=est_tokens,
+                is_truncated=is_truncated,
+            ))
+            total_tokens += est_tokens
+            max_depth_reached = max(max_depth_reached, depth)
+            for ref in references:
+                if ref not in visited:
+                    queue.append((ref, depth + 1))
+
+        return RecursiveContextResult(
+            nodes=nodes,
+            total_tokens=total_tokens,
+            max_depth_reached=max_depth_reached,
+            files_visited=len(visited),
+            budget_exhausted=total_tokens >= self._token_budget,
+        )

attocode_intel/_internal/types/__init__.py

@@ -0,0 +1 @@
+"""Internal code intelligence support; not a public API."""

attocode_intel/_internal/types/events.py

@@ -0,0 +1,289 @@
+"""Agent event types.
+
+Comprehensive event system covering lifecycle, execution, multi-agent,
+policy, context, resilience, insight, and subagent categories.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+# Shared callback type for simple event listeners used across the codebase.
+SimpleEventListener = Callable[[str, dict[str, Any]], None]
+
+
+class SimpleEventEmitter:
+    """Mixin: subscribe/emit ``(event, data)`` events. Listener errors are swallowed."""
+
+    _listeners: list[SimpleEventListener]
+
+    def __init__(self) -> None:
+        self._listeners = []
+
+    def on(self, listener: SimpleEventListener) -> Callable[[], None]:
+        self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            if listener in self._listeners:
+                self._listeners.remove(listener)
+
+        return unsubscribe
+
+    def _emit(self, event: str, data: dict[str, Any]) -> None:
+        for listener in self._listeners:
+            try:
+                listener(event, data)
+            except Exception:
+                pass
+
+
+class EventType(StrEnum):
+    """Types of agent events.
+
+    Organized into categories:
+    - Lifecycle: start, complete, error, shutdown
+    - Execution: iteration, tool.*, llm.*
+    - Budget: budget.*
+    - Context: compaction.*, context.*
+    - Multi-agent: subagent.*, swarm.*
+    - Policy: policy.*, permission.*
+    - Session: session.*
+    - Mode: mode.*
+    - Plan: plan.*
+    - Quality: quality.*, learning.*
+    - Resilience: resilience.*, circuit_breaker.*
+    - MCP: mcp.*
+    - Undo: undo.*
+    - Insight: insight.*
+    """
+
+    # --- Lifecycle ---
+    START = "start"
+    COMPLETE = "complete"
+    ERROR = "error"
+    SHUTDOWN = "shutdown"
+    STATUS = "status"  # General status update (e.g. "Indexing codebase...")
+
+    # --- Execution core ---
+    ITERATION = "iteration"
+    THINKING = "thinking"
+    RESPONSE = "response"
+
+    # --- Tool events ---
+    TOOL_START = "tool.start"
+    TOOL_COMPLETE = "tool.complete"
+    TOOL_ERROR = "tool.error"
+    TOOL_APPROVAL_REQUESTED = "tool.approval.requested"
+    TOOL_APPROVAL_GRANTED = "tool.approval.granted"
+    TOOL_APPROVAL_DENIED = "tool.approval.denied"
+    TOOL_BLOCKED = "tool.blocked"
+    TOOL_COERCED = "tool.coerced"
+    TOOL_CALL_MISMATCH = "tool.call.mismatch"
+    SUSPICIOUS_TOOL_MARKUP = "tool.markup.suspicious"
+    LOOP_GUARD_ACTIVATED = "tool.loop_guard.activated"
+
+    # --- LLM events ---
+    LLM_START = "llm.start"
+    LLM_COMPLETE = "llm.complete"
+    LLM_ERROR = "llm.error"
+    LLM_RETRY = "llm.retry"
+    LLM_STREAM_START = "llm.stream.start"
+    LLM_STREAM_CHUNK = "llm.stream.chunk"
+    LLM_STREAM_END = "llm.stream.end"
+
+    # --- Budget events ---
+    BUDGET_WARNING = "budget.warning"
+    BUDGET_EXHAUSTED = "budget.exhausted"
+    BUDGET_CHECK = "budget.check"
+    BUDGET_EXTENSION_REQUESTED = "budget.extension.requested"
+    BUDGET_EXTENSION_GRANTED = "budget.extension.granted"
+    BUDGET_EXTENSION_DENIED = "budget.extension.denied"
+
+    # --- Context / Compaction events ---
+    COMPACTION = "compaction"
+    COMPACTION_START = "compaction.start"
+    COMPACTION_COMPLETE = "compaction.complete"
+    COMPACTION_ERROR = "compaction.error"
+    CONTEXT_FRESH_REFRESH = "context.fresh_refresh"
+    CONTEXT_OVERFLOW = "context.overflow"
+    CONTEXT_BREAKDOWN = "context.breakdown"
+
+    # --- Session events ---
+    SESSION_CREATED = "session.created"
+    SESSION_LOADED = "session.loaded"
+    SESSION_SAVED = "session.saved"
+    SESSION_RESUMED = "session.resumed"
+    SESSION_RESUME_REJECTED = "session.resume.rejected"
+    SESSION_FORKED = "session.forked"
+    SESSION_CHECKPOINT = "session.checkpoint"
+
+    # --- Mode events ---
+    MODE_CHANGED = "mode.changed"
+    MODE_WRITE_INTERCEPTED = "mode.write.intercepted"
+
+    # --- Plan events ---
+    PLAN_CREATED = "plan.created"
+    PLAN_STEP_START = "plan.step.start"
+    PLAN_STEP_COMPLETE = "plan.step.complete"
+    PLAN_APPROVED = "plan.approved"
+    PLAN_REJECTED = "plan.rejected"
+    PLAN_UPDATED = "plan.updated"
+
+    # --- Subagent events ---
+    SUBAGENT_SPAWN = "subagent.spawn"
+    SUBAGENT_COMPLETE = "subagent.complete"
+    SUBAGENT_ERROR = "subagent.error"
+    SUBAGENT_ITERATION = "subagent.iteration"
+    SUBAGENT_PHASE = "subagent.phase"
+    SUBAGENT_WRAPUP_STARTED = "subagent.wrapup.started"
+    SUBAGENT_WRAPUP_COMPLETED = "subagent.wrapup.completed"
+    SUBAGENT_TIMEOUT_HARD_KILL = "subagent.timeout.hard_kill"
+
+    # --- Swarm events ---
+    SWARM_START = "swarm.start"
+    SWARM_COMPLETE = "swarm.complete"
+    SWARM_TASK_QUEUED = "swarm.task.queued"
+    SWARM_TASK_START = "swarm.task.start"
+    SWARM_TASK_COMPLETE = "swarm.task.complete"
+    SWARM_TASK_FAILED = "swarm.task.failed"
+    SWARM_WAVE_START = "swarm.wave.start"
+    SWARM_WAVE_COMPLETE = "swarm.wave.complete"
+    SWARM_WORKER_ASSIGNED = "swarm.worker.assigned"
+    SWARM_WORKER_RELEASED = "swarm.worker.released"
+
+    # --- Policy events ---
+    POLICY_EVALUATION = "policy.evaluation"
+    POLICY_OVERRIDE = "policy.override"
+    PERMISSION_GRANTED = "permission.granted"
+    PERMISSION_DENIED = "permission.denied"
+    PERMISSION_REMEMBERED = "permission.remembered"
+
+    # --- Quality events ---
+    QUALITY_CHECK = "quality.check"
+    QUALITY_SCORE = "quality.score"
+    LEARNING_PROPOSED = "learning.proposed"
+    LEARNING_APPROVED = "learning.approved"
+    LEARNING_REJECTED = "learning.rejected"
+    HEALTH_CHECK = "health.check"
+
+    # --- Resilience events ---
+    RESILIENCE_RETRY = "resilience.retry"
+    RESILIENCE_FALLBACK = "resilience.fallback"
+    CIRCUIT_BREAKER_OPEN = "circuit_breaker.open"
+    CIRCUIT_BREAKER_HALF_OPEN = "circuit_breaker.half_open"
+    CIRCUIT_BREAKER_CLOSED = "circuit_breaker.closed"
+
+    # --- MCP events ---
+    MCP_CONNECT = "mcp.connect"
+    MCP_DISCONNECT = "mcp.disconnect"
+    MCP_TOOL_DISCOVERED = "mcp.tool.discovered"
+    MCP_TOOL_CALL = "mcp.tool.call"
+    MCP_TOOL_ERROR = "mcp.tool.error"
+
+    # --- Undo events ---
+    UNDO_TRACKED = "undo.tracked"
+    UNDO_EXECUTED = "undo.executed"
+    UNDO_FAILED = "undo.failed"
+
+    # --- Insight / Loop detection ---
+    INSIGHT_DOOM_LOOP = "insight.doom_loop"
+    INSIGHT_SATURATION = "insight.saturation"
+    INSIGHT_NUDGE = "insight.nudge"
+    INSIGHT_PHASE_CHANGE = "insight.phase_change"
+
+
+class EventCategory(StrEnum):
+    """Categories for event grouping."""
+
+    LIFECYCLE = "lifecycle"
+    EXECUTION = "execution"
+    TOOL = "tool"
+    LLM = "llm"
+    BUDGET = "budget"
+    CONTEXT = "context"
+    SESSION = "session"
+    MODE = "mode"
+    PLAN = "plan"
+    SUBAGENT = "subagent"
+    SWARM = "swarm"
+    POLICY = "policy"
+    QUALITY = "quality"
+    RESILIENCE = "resilience"
+    MCP = "mcp"
+    UNDO = "undo"
+    INSIGHT = "insight"
+
+
+# Map events to categories
+EVENT_CATEGORIES: dict[EventType, EventCategory] = {}
+for _evt in EventType:
+    _name = _evt.value
+    if _name in ("start", "complete", "error", "shutdown"):
+        EVENT_CATEGORIES[_evt] = EventCategory.LIFECYCLE
+    elif _name.startswith("tool."):
+        EVENT_CATEGORIES[_evt] = EventCategory.TOOL
+    elif _name.startswith("llm."):
+        EVENT_CATEGORIES[_evt] = EventCategory.LLM
+    elif _name.startswith("budget."):
+        EVENT_CATEGORIES[_evt] = EventCategory.BUDGET
+    elif _name.startswith(("compaction", "context.")):
+        EVENT_CATEGORIES[_evt] = EventCategory.CONTEXT
+    elif _name.startswith("session."):
+        EVENT_CATEGORIES[_evt] = EventCategory.SESSION
+    elif _name.startswith("mode."):
+        EVENT_CATEGORIES[_evt] = EventCategory.MODE
+    elif _name.startswith("plan."):
+        EVENT_CATEGORIES[_evt] = EventCategory.PLAN
+    elif _name.startswith("subagent."):
+        EVENT_CATEGORIES[_evt] = EventCategory.SUBAGENT
+    elif _name.startswith("swarm."):
+        EVENT_CATEGORIES[_evt] = EventCategory.SWARM
+    elif _name.startswith(("policy.", "permission.")):
+        EVENT_CATEGORIES[_evt] = EventCategory.POLICY
+    elif _name.startswith(("quality.", "learning.", "health.")):
+        EVENT_CATEGORIES[_evt] = EventCategory.QUALITY
+    elif _name.startswith(("resilience.", "circuit_breaker.")):
+        EVENT_CATEGORIES[_evt] = EventCategory.RESILIENCE
+    elif _name.startswith("mcp."):
+        EVENT_CATEGORIES[_evt] = EventCategory.MCP
+    elif _name.startswith("undo."):
+        EVENT_CATEGORIES[_evt] = EventCategory.UNDO
+    elif _name.startswith("insight."):
+        EVENT_CATEGORIES[_evt] = EventCategory.INSIGHT
+    else:
+        EVENT_CATEGORIES[_evt] = EventCategory.EXECUTION
+
+
+def get_event_category(event_type: EventType) -> EventCategory:
+    """Get the category for an event type."""
+    return EVENT_CATEGORIES.get(event_type, EventCategory.EXECUTION)
+
+
+@dataclass(slots=True)
+class AgentEvent:
+    """An event emitted during agent execution."""
+
+    type: EventType
+    task: str | None = None
+    tool: str | None = None
+    args: dict[str, Any] | None = None
+    result: str | None = None
+    error: str | None = None
+    tokens: int | None = None
+    cost: float | None = None
+    iteration: int | None = None
+    metadata: dict[str, Any] | None = None
+    # Extended fields for rich events
+    session_id: str | None = None
+    agent_id: str | None = None
+    parent_id: str | None = None
+    duration_ms: float | None = None
+    timestamp: float | None = None
+
+    @property
+    def category(self) -> EventCategory:
+        """Get the category of this event."""
+        return get_event_category(self.type)

attocode_intel/_internal/types/severity.py

@@ -0,0 +1,15 @@
+"""Shared severity levels for findings, security patterns, etc."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class Severity(StrEnum):
+    """Finding severity level."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"