llmcode-cli 1.0.0__py3-none-any.whl

llm_code/runtime/hooks.py

@@ -0,0 +1,223 @@
+"""Hook runner supporting 6 types, 24 events, glob event matching, per-hook timeout/on_error."""
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import subprocess
+from dataclasses import dataclass, field
+
+from llm_code.runtime.config import HookConfig
+from llm_code.tools.base import ToolResult
+
+# Legacy global fallback timeout (used only when hook.timeout is not set, kept for compat)
+HOOK_TIMEOUT = 10.0
+
+# All 24 supported event names across 6 types.
+# Canonical names used for glob matching with event patterns like "tool.*", "session.*", "*".
+#
+# Group prefixes are derived from the event name by taking the segment before "_" or the
+# shorthand group word that appears in the category comment below.
+#
+# tool     -> pre_tool_use, post_tool_use, tool_error, tool_denied
+# command  -> pre_command, post_command, command_error
+# prompt   -> prompt_submit, prompt_compile, prompt_cache_hit, prompt_cache_miss
+# agent    -> agent_spawn, agent_complete, agent_error, agent_message
+# session  -> session_start, session_end, session_save, session_compact, session_dream
+# http     -> http_request, http_response, http_error, http_retry, http_fallback
+
+# Mapping from event name to its dot-prefixed canonical group name used for glob matching.
+# E.g. "pre_tool_use" -> "tool.pre_tool_use", so pattern "tool.*" matches.
+_EVENT_GROUP: dict[str, str] = {
+    # tool
+    "pre_tool_use": "tool.pre_tool_use",
+    "post_tool_use": "tool.post_tool_use",
+    "tool_error": "tool.tool_error",
+    "tool_denied": "tool.tool_denied",
+    # command
+    "pre_command": "command.pre_command",
+    "post_command": "command.post_command",
+    "command_error": "command.command_error",
+    # prompt
+    "prompt_submit": "prompt.prompt_submit",
+    "prompt_compile": "prompt.prompt_compile",
+    "prompt_cache_hit": "prompt.prompt_cache_hit",
+    "prompt_cache_miss": "prompt.prompt_cache_miss",
+    # agent
+    "agent_spawn": "agent.agent_spawn",
+    "agent_complete": "agent.agent_complete",
+    "agent_error": "agent.agent_error",
+    "agent_message": "agent.agent_message",
+    # session
+    "session_start": "session.session_start",
+    "session_end": "session.session_end",
+    "session_save": "session.session_save",
+    "session_compact": "session.session_compact",
+    "session_dream": "session.session_dream",
+    # http
+    "http_request": "http.http_request",
+    "http_response": "http.http_response",
+    "http_error": "http.http_error",
+    "http_retry": "http.http_retry",
+    "http_fallback": "http.http_fallback",
+}
+
+
+def _event_matches(pattern: str, event: str) -> bool:
+    """Return True if *pattern* matches *event*.
+
+    Matching rules (in order):
+    1. "*" matches any event.
+    2. Pattern containing "." is matched against the dotted form "group.event"
+       (e.g. "tool.*" matches "tool.pre_tool_use").
+    3. Exact match (original event name, no dots).
+    """
+    if pattern == "*":
+        return True
+    dotted = _EVENT_GROUP.get(event, event)
+    if "." in pattern:
+        return fnmatch.fnmatch(dotted, pattern)
+    return pattern == event
+
+
+def _build_env(event: str, context: dict) -> dict[str, str]:
+    """Build the environment mapping to pass to a hook process."""
+    env = {**os.environ}
+    env["HOOK_EVENT"] = event
+    env["HOOK_TOOL_NAME"] = context.get("tool_name", "")
+    env["HOOK_TOOL_INPUT"] = context.get("tool_input", "")
+    env["HOOK_TOOL_OUTPUT"] = context.get("tool_output", "")
+    env["HOOK_SESSION_ID"] = context.get("session_id", "")
+    env["HOOK_AGENT_ID"] = context.get("agent_id", "")
+    env["HOOK_HTTP_URL"] = context.get("url", "")
+    env["HOOK_HTTP_STATUS"] = context.get("status", "")
+    env["HOOK_COMMAND"] = context.get("command", "")
+    return env
+
+
+@dataclass
+class HookOutcome:
+    denied: bool = False
+    messages: list[str] = field(default_factory=list)
+
+
+class HookRunner:
+    def __init__(self, hooks: tuple[HookConfig, ...] = ()) -> None:
+        self._hooks = hooks
+
+    # ------------------------------------------------------------------
+    # Public generic entry point
+    # ------------------------------------------------------------------
+
+    def fire(self, event: str, context: dict) -> HookOutcome:
+        """Fire all hooks whose event pattern matches *event*.
+
+        *context* is a plain dict carrying optional keys:
+            tool_name, tool_input, tool_output,
+            session_id, agent_id, url, status, command
+        """
+        env = _build_env(event, context)
+        outcome = HookOutcome()
+
+        for hook in self._hooks:
+            if not _event_matches(hook.event, event):
+                continue
+
+            hook_outcome = self._run_single_hook(hook, env)
+            if hook_outcome.denied:
+                return hook_outcome  # stop on first deny
+            outcome.messages.extend(hook_outcome.messages)
+
+        return outcome
+
+    # ------------------------------------------------------------------
+    # Legacy helpers (backwards compat)
+    # ------------------------------------------------------------------
+
+    def pre_tool_use(self, tool_name: str, args: dict) -> HookOutcome:
+        """Run all pre_tool_use hooks that match tool_name."""
+        context = {
+            "tool_name": tool_name,
+            "tool_input": json.dumps(args),
+            "tool_output": "",
+        }
+        # Build env with legacy keys too
+        env = _build_env("pre_tool_use", context)
+        env["HOOK_TOOL_IS_ERROR"] = "false"
+        return self._run_hooks_with_env("pre_tool_use", tool_name, env)
+
+    def post_tool_use(self, tool_name: str, args: dict, result: ToolResult) -> HookOutcome:
+        """Run all post_tool_use hooks that match tool_name."""
+        context = {
+            "tool_name": tool_name,
+            "tool_input": json.dumps(args),
+            "tool_output": result.output,
+        }
+        env = _build_env("post_tool_use", context)
+        env["HOOK_TOOL_IS_ERROR"] = "true" if result.is_error else "false"
+        return self._run_hooks_with_env("post_tool_use", tool_name, env)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _run_hooks_with_env(
+        self, event: str, tool_name: str, env: dict[str, str]
+    ) -> HookOutcome:
+        """Execute matching hooks using a pre-built env (legacy path)."""
+        outcome = HookOutcome()
+
+        for hook in self._hooks:
+            if not _event_matches(hook.event, event):
+                continue
+            if not fnmatch.fnmatch(tool_name, hook.tool_pattern):
+                continue
+
+            hook_outcome = self._run_single_hook(hook, env)
+            if hook_outcome.denied:
+                return hook_outcome
+            outcome.messages.extend(hook_outcome.messages)
+
+        return outcome
+
+    def _run_single_hook(self, hook: HookConfig, env: dict[str, str]) -> HookOutcome:
+        """Run one shell command and interpret its exit code respecting hook.on_error."""
+        timeout = getattr(hook, "timeout", HOOK_TIMEOUT)
+        on_error = getattr(hook, "on_error", "warn")
+
+        try:
+            proc = subprocess.run(
+                hook.command,
+                shell=True,
+                env=env,
+                timeout=timeout,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.TimeoutExpired:
+            msg = f"Hook timed out after {timeout}s: {hook.command}"
+            denied = hook.on_error == "deny"
+            return HookOutcome(denied=denied, messages=[msg])
+        except Exception as exc:
+            denied = hook.on_error == "deny"
+            return HookOutcome(denied=denied, messages=[f"Hook error: {exc}"])
+
+        if proc.returncode == 0:
+            return HookOutcome(denied=False)
+
+        if proc.returncode == 2:
+            msg = proc.stdout.strip() or proc.stderr.strip() or "Hook denied tool use"
+            return HookOutcome(denied=True, messages=[msg])
+
+        # Non-zero, non-2: apply on_error policy
+        msg = (
+            proc.stdout.strip()
+            or proc.stderr.strip()
+            or f"Hook exited with code {proc.returncode}: {hook.command}"
+        )
+        if on_error == "deny":
+            return HookOutcome(denied=True, messages=[msg])
+        elif on_error == "ignore":
+            return HookOutcome(denied=False, messages=[])
+        else:  # "warn" (default)
+            return HookOutcome(denied=False, messages=[msg])

llm_code/runtime/indexer.py

@@ -0,0 +1,230 @@
+"""Project file and symbol indexer."""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class FileEntry:
+    path: str       # relative path from project root
+    size: int
+    language: str   # "python", "typescript", "go", "rust", "javascript", "unknown"
+
+
+@dataclass(frozen=True)
+class SymbolEntry:
+    name: str
+    kind: str       # "class" | "function" | "method" | "variable" | "export"
+    file: str       # relative path
+    line: int
+
+
+@dataclass(frozen=True)
+class ProjectIndex:
+    files: tuple[FileEntry, ...]
+    symbols: tuple[SymbolEntry, ...]
+    generated_at: str
+
+
+# ---------------------------------------------------------------------------
+# Language detection
+# ---------------------------------------------------------------------------
+
+_EXT_TO_LANG: dict[str, str] = {
+    ".py": "python",
+    ".pyi": "python",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".go": "go",
+    ".rs": "rust",
+    ".java": "java",
+    ".rb": "ruby",
+    ".php": "php",
+    ".swift": "swift",
+    ".kt": "kotlin",
+}
+
+# ---------------------------------------------------------------------------
+# Directories to skip
+# ---------------------------------------------------------------------------
+
+_SKIP_DIRS: frozenset[str] = frozenset(
+    {
+        ".git",
+        "node_modules",
+        ".venv",
+        "venv",
+        "__pycache__",
+        "dist",
+        "build",
+        ".next",
+        ".nuxt",
+        "target",
+        ".tox",
+        ".mypy_cache",
+        ".pytest_cache",
+    }
+)
+
+# ---------------------------------------------------------------------------
+# Symbol regex patterns
+# ---------------------------------------------------------------------------
+
+_SYMBOL_PATTERNS: dict[str, list[tuple[re.Pattern[str], str]]] = {
+    "python": [
+        (re.compile(r"^class\s+(\w+)"), "class"),
+        (re.compile(r"^def\s+(\w+)"), "function"),
+        (re.compile(r"^(\w+)\s*(?::\s*\w+)?\s*="), "variable"),
+    ],
+    "typescript": [
+        (re.compile(r"^export\s+(?:class|interface)\s+(\w+)"), "class"),
+        (re.compile(r"^export\s+(?:function|const|let|var)\s+(\w+)"), "export"),
+        (re.compile(r"^class\s+(\w+)"), "class"),
+        (re.compile(r"^function\s+(\w+)"), "function"),
+    ],
+    "javascript": [
+        (re.compile(r"^export\s+(?:class|function|const|let|var)\s+(\w+)"), "export"),
+        (re.compile(r"^class\s+(\w+)"), "class"),
+        (re.compile(r"^function\s+(\w+)"), "function"),
+    ],
+    "go": [
+        (re.compile(r"^func\s+(\w+)"), "function"),
+        (re.compile(r"^type\s+(\w+)\s+struct"), "class"),
+        (re.compile(r"^type\s+(\w+)\s+interface"), "class"),
+    ],
+    "rust": [
+        (re.compile(r"^(?:pub\s+)?fn\s+(\w+)"), "function"),
+        (re.compile(r"^(?:pub\s+)?struct\s+(\w+)"), "class"),
+        (re.compile(r"^(?:pub\s+)?enum\s+(\w+)"), "class"),
+        (re.compile(r"^(?:pub\s+)?trait\s+(\w+)"), "class"),
+    ],
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _should_skip(name: str) -> bool:
+    """Return True if the directory name matches a skip pattern."""
+    if name in _SKIP_DIRS:
+        return True
+    # Handle glob-style patterns like *.egg-info
+    if name.endswith(".egg-info"):
+        return True
+    return False
+
+
+def _detect_language(path: Path) -> str:
+    return _EXT_TO_LANG.get(path.suffix.lower(), "unknown")
+
+
+# ---------------------------------------------------------------------------
+# ProjectIndexer
+# ---------------------------------------------------------------------------
+
+
+class ProjectIndexer:
+    def __init__(self, cwd: Path) -> None:
+        self._cwd = cwd
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def build_index(self) -> ProjectIndex:
+        files = self._scan_files()
+        symbols: list[SymbolEntry] = []
+        for f in files:
+            symbols.extend(self._extract_symbols(f))
+        now = datetime.now(timezone.utc).isoformat()
+        return ProjectIndex(
+            files=tuple(files),
+            symbols=tuple(symbols),
+            generated_at=now,
+        )
+
+    def save(self, index: ProjectIndex, path: Path) -> None:
+        data = {
+            "files": [asdict(f) for f in index.files],
+            "symbols": [asdict(s) for s in index.symbols],
+            "generated_at": index.generated_at,
+        }
+        path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    @staticmethod
+    def load(path: Path) -> ProjectIndex | None:
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+            files = tuple(FileEntry(**f) for f in raw["files"])
+            symbols = tuple(SymbolEntry(**s) for s in raw["symbols"])
+            return ProjectIndex(
+                files=files,
+                symbols=symbols,
+                generated_at=raw["generated_at"],
+            )
+        except (FileNotFoundError, KeyError, TypeError, json.JSONDecodeError):
+            return None
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _scan_files(self) -> list[FileEntry]:
+        entries: list[FileEntry] = []
+        for item in self._walk(self._cwd):
+            rel = item.relative_to(self._cwd).as_posix()
+            entries.append(
+                FileEntry(
+                    path=rel,
+                    size=item.stat().st_size,
+                    language=_detect_language(item),
+                )
+            )
+        entries.sort(key=lambda e: e.path)
+        return entries
+
+    def _walk(self, root: Path):
+        """Yield all files under *root*, skipping ignored directories."""
+        for child in sorted(root.iterdir()):
+            if child.is_dir():
+                if not _should_skip(child.name):
+                    yield from self._walk(child)
+            elif child.is_file():
+                yield child
+
+    def _extract_symbols(self, file: FileEntry) -> list[SymbolEntry]:
+        patterns = _SYMBOL_PATTERNS.get(file.language)
+        if not patterns:
+            return []
+        abs_path = self._cwd / file.path
+        try:
+            text = abs_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return []
+        results: list[SymbolEntry] = []
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            for pattern, kind in patterns:
+                m = pattern.match(line)
+                if m:
+                    results.append(
+                        SymbolEntry(
+                            name=m.group(1),
+                            kind=kind,
+                            file=file.path,
+                            line=lineno,
+                        )
+                    )
+                    break  # first matching pattern wins for this line
+        return results

llm_code/runtime/knowledge_compiler.py

@@ -0,0 +1,232 @@
+"""Knowledge Compiler — incrementally builds a structured project knowledge base."""
+from __future__ import annotations
+
+import logging
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from llm_code.api.types import Message, MessageRequest, TextBlock
+
+logger = logging.getLogger(__name__)
+
+_INDEX_LINE_RE = re.compile(r"^- \[(.+?)\]\((.+?)\)\s*—\s*(.+)$")
+
+_COMPILE_SYSTEM_PROMPT = """\
+You are a knowledge compiler for a software project. Given a list of changed files \
+and session facts, produce a concise Markdown knowledge article about the affected \
+module or area.
+
+Format:
+# [Module Name]
+
+[2-3 sentence description of what this module does]
+
+## Key Types
+- [Important classes, dataclasses, types]
+
+## Patterns
+- [Recurring patterns or conventions in this area]
+
+## Dependencies
+- [Key imports or integrations]
+
+Be concise and factual. Focus on architecture, not implementation details.
+"""
+
+
+@dataclass(frozen=True)
+class KnowledgeEntry:
+    """A single entry in the knowledge index."""
+
+    path: str  # relative to .llm-code/knowledge/
+    title: str
+    summary: str  # one-line for index
+    last_compiled: str  # ISO timestamp
+    source_files: tuple[str, ...]  # which source files this knowledge covers
+
+
+@dataclass(frozen=True)
+class IngestResult:
+    """Result of the ingest phase."""
+
+    changed_files: tuple[str, ...]
+    facts: tuple[str, ...]
+
+
+class KnowledgeCompiler:
+    """Incrementally builds and maintains a structured project knowledge base."""
+
+    def __init__(self, cwd: Path, llm_provider: Any | None, compile_model: str = "") -> None:
+        self._cwd = cwd
+        self._provider = llm_provider
+        self._compile_model = compile_model
+        self._knowledge_dir = cwd / ".llm-code" / "knowledge"
+        self._knowledge_dir.mkdir(parents=True, exist_ok=True)
+        (self._knowledge_dir / "modules").mkdir(exist_ok=True)
+
+    @property
+    def knowledge_dir(self) -> Path:
+        return self._knowledge_dir
+
+    def get_index(self) -> list[KnowledgeEntry]:
+        """Parse index.md and return all knowledge entries."""
+        index_path = self._knowledge_dir / "index.md"
+        if not index_path.exists():
+            return []
+
+        entries: list[KnowledgeEntry] = []
+        for line in index_path.read_text(encoding="utf-8").splitlines():
+            m = _INDEX_LINE_RE.match(line.strip())
+            if m:
+                title, path, summary = m.group(1), m.group(2), m.group(3).strip()
+                entries.append(
+                    KnowledgeEntry(
+                        path=path,
+                        title=title,
+                        summary=summary,
+                        last_compiled="",
+                        source_files=(),
+                    )
+                )
+        return entries
+
+    def ingest(
+        self,
+        facts: list[str] | None = None,
+        since_commit: str | None = None,
+    ) -> IngestResult:
+        """Phase 1: Gather changed files and session facts."""
+        changed: list[str] = []
+        if since_commit:
+            try:
+                result = subprocess.run(
+                    ["git", "diff", "--name-only", since_commit, "HEAD"],
+                    cwd=self._cwd,
+                    capture_output=True,
+                    text=True,
+                    timeout=10,
+                )
+                if result.returncode == 0:
+                    changed = [f.strip() for f in result.stdout.strip().splitlines() if f.strip()]
+            except Exception:
+                pass
+        return IngestResult(
+            changed_files=tuple(changed),
+            facts=tuple(facts or []),
+        )
+
+    async def compile(self, ingest_data: IngestResult) -> None:
+        """Phase 2: Use LLM to compile knowledge from ingested data."""
+        if self._provider is None:
+            return
+        if not ingest_data.changed_files and not ingest_data.facts:
+            return
+
+        modules = self._group_by_module(ingest_data.changed_files)
+
+        for module_name, files in modules.items():
+            try:
+                article = await self._compile_module(module_name, files, ingest_data.facts)
+                if article:
+                    self._write_module(module_name, article)
+            except Exception:
+                logger.debug("Knowledge compile failed for module %s", module_name, exc_info=True)
+
+        self._rebuild_index()
+
+    def _group_by_module(self, files: tuple[str, ...]) -> dict[str, list[str]]:
+        """Group files by their top-level package directory."""
+        modules: dict[str, list[str]] = {}
+        for f in files:
+            parts = Path(f).parts
+            if len(parts) >= 2:
+                module = parts[1] if parts[0] in ("llm_code", "src", "lib") else parts[0]
+            else:
+                module = Path(f).stem
+            modules.setdefault(module, []).append(f)
+        return modules
+
+    async def _compile_module(
+        self, module_name: str, files: list[str], facts: tuple[str, ...]
+    ) -> str:
+        """Call LLM to generate a knowledge article for a module."""
+        existing = ""
+        article_path = self._knowledge_dir / "modules" / f"{module_name}.md"
+        if article_path.exists():
+            existing = article_path.read_text(encoding="utf-8")
+
+        facts_str = "\n".join(f"- {fact}" for fact in facts) if facts else "None"
+        files_str = "\n".join(f"- {f}" for f in files)
+
+        user_msg = (
+            f"Module: {module_name}\n\n"
+            f"Changed files:\n{files_str}\n\n"
+            f"Session facts:\n{facts_str}\n\n"
+        )
+        if existing:
+            user_msg += f"Existing article (merge new information, don't overwrite):\n\n{existing}\n"
+
+        request = MessageRequest(
+            model=self._compile_model or "",
+            messages=(Message(role="user", content=(TextBlock(text=user_msg),)),),
+            system=_COMPILE_SYSTEM_PROMPT,
+            tools=(),
+            max_tokens=1024,
+            temperature=0.3,
+        )
+
+        response = await self._provider.send_message(request)
+        parts: list[str] = []
+        for block in response.content:
+            if hasattr(block, "text"):
+                parts.append(block.text)
+        return "\n".join(parts)
+
+    def _write_module(self, module_name: str, content: str) -> None:
+        """Write a module article to the knowledge directory."""
+        path = self._knowledge_dir / "modules" / f"{module_name}.md"
+        path.write_text(content, encoding="utf-8")
+
+    def _rebuild_index(self) -> None:
+        """Regenerate index.md from existing module files."""
+        modules_dir = self._knowledge_dir / "modules"
+        lines = ["# Knowledge Index\n"]
+        for md_file in sorted(modules_dir.glob("*.md")):
+            title = md_file.stem.replace("_", " ").title()
+            summary = ""
+            for file_line in md_file.read_text(encoding="utf-8").splitlines():
+                stripped = file_line.strip()
+                if stripped and not stripped.startswith("#"):
+                    summary = stripped
+                    break
+            lines.append(f"- [{title}]({md_file.relative_to(self._knowledge_dir)}) — {summary}")
+        (self._knowledge_dir / "index.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    def query(self, max_tokens: int = 3000) -> str:
+        """Phase 3: Return relevant knowledge for system prompt injection."""
+        entries = self.get_index()
+        if not entries:
+            return ""
+
+        max_chars = max_tokens * 4
+        parts: list[str] = ["# Project Knowledge\n"]
+        char_count = len(parts[0])
+
+        for entry in entries:
+            article_path = self._knowledge_dir / entry.path
+            if not article_path.exists():
+                continue
+            content = article_path.read_text(encoding="utf-8").strip()
+            if char_count + len(content) + 2 > max_chars:
+                summary_line = f"- **{entry.title}**: {entry.summary}"
+                if char_count + len(summary_line) + 1 <= max_chars:
+                    parts.append(summary_line)
+                    char_count += len(summary_line) + 1
+                break
+            parts.append(content)
+            char_count += len(content) + 2
+
+        return "\n\n".join(parts) if len(parts) > 1 else ""