aru-code 0.1.0__py3-none-any.whl

aru/config.py

@@ -0,0 +1,237 @@
+"""Configuration loader for AGENTS.md and .agents/ directory.
+
+Supports:
+- AGENTS.md: Project-level agent instructions (appended to system prompt)
+- .agents/commands/*.md: Custom slash commands (filename = command name)
+- .agents/skills/*.md: Custom skills/personas (loaded as additional instructions)
+
+Follows the Gemini .agents convention for cross-platform compatibility.
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class CustomCommand:
+    """A custom command defined in .agents/commands/."""
+    name: str
+    description: str
+    template: str
+    source_path: str
+
+
+@dataclass
+class Skill:
+    """A skill defined in .agents/skills/."""
+    name: str
+    description: str
+    content: str
+    source_path: str
+
+
+MAX_README_CHARS = 2000  # Reduced from 8000 to save ~1.7K tokens per request
+
+
+@dataclass
+class AgentConfig:
+    """Loaded configuration from AGENTS.md, README.md, and .agents/ directory."""
+    readme_md: str = ""
+    agents_md: str = ""
+    commands: dict[str, CustomCommand] = field(default_factory=dict)
+    skills: dict[str, Skill] = field(default_factory=dict)
+    permissions: dict[str, Any] = field(default_factory=dict)
+    model_defaults: dict[str, str] = field(default_factory=dict)
+    plan_reviewer: bool = True
+
+    @property
+    def has_instructions(self) -> bool:
+        return bool(self.agents_md) or bool(self.skills)
+
+    def get_extra_instructions(self, active_skills: list[str] | None = None, lightweight: bool = False) -> str:
+        """Build extra instructions from README.md, AGENTS.md, and active skills.
+
+        Args:
+            active_skills: List of skill names to include.
+            lightweight: If True, skip README.md to save tokens (for executor steps).
+        """
+        parts = []
+        if self.readme_md and not lightweight:
+            parts.append(f"## Project Overview (README.md)\n\n{self.readme_md}")
+        if self.agents_md:
+            parts.append(f"## Project Instructions (AGENTS.md)\n\n{self.agents_md}")
+        if active_skills:
+            for name in active_skills:
+                if name in self.skills:
+                    skill = self.skills[name]
+                    parts.append(f"## Skill: {skill.name}\n\n{skill.content}")
+        return "\n\n".join(parts)
+
+
+def _parse_frontmatter(content: str) -> tuple[dict[str, str], str]:
+    """Parse YAML-like frontmatter from a markdown file.
+
+    Returns (metadata_dict, body_content).
+    """
+    metadata: dict[str, str] = {}
+    body = content
+
+    if content.startswith("---"):
+        lines = content.split("\n")
+        end_idx = -1
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                end_idx = i
+                break
+        if end_idx > 0:
+            for line in lines[1:end_idx]:
+                if ":" in line:
+                    key, _, value = line.partition(":")
+                    metadata[key.strip()] = value.strip()
+            body = "\n".join(lines[end_idx + 1:]).strip()
+
+    return metadata, body
+
+
+def _load_commands(agents_dir: Path) -> dict[str, CustomCommand]:
+    """Load custom commands from .agents/commands/."""
+    commands_dir = agents_dir / "commands"
+    commands: dict[str, CustomCommand] = {}
+
+    if not commands_dir.is_dir():
+        return commands
+
+    for filepath in sorted(commands_dir.iterdir()):
+        if filepath.suffix != ".md":
+            continue
+
+        name = filepath.stem
+        try:
+            content = filepath.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+
+        metadata, body = _parse_frontmatter(content)
+        description = metadata.get("description", f"Custom command: {name}")
+
+        commands[name] = CustomCommand(
+            name=name,
+            description=description,
+            template=body,
+            source_path=str(filepath),
+        )
+
+    return commands
+
+
+def _load_skills(agents_dir: Path) -> dict[str, Skill]:
+    """Load skills from .agents/skills/."""
+    skills_dir = agents_dir / "skills"
+    skills: dict[str, Skill] = {}
+
+    if not skills_dir.is_dir():
+        return skills
+
+    for filepath in sorted(skills_dir.iterdir()):
+        if filepath.suffix != ".md":
+            continue
+
+        name = filepath.stem
+        try:
+            content = filepath.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+
+        metadata, body = _parse_frontmatter(content)
+        description = metadata.get("description", f"Skill: {name}")
+
+        skills[name] = Skill(
+            name=name,
+            description=description,
+            content=body,
+            source_path=str(filepath),
+        )
+
+    return skills
+
+
+def load_config(cwd: str | None = None) -> AgentConfig:
+    """Load agent configuration from AGENTS.md and .agents/ directory.
+
+    Searches the current working directory for:
+    - AGENTS.md: Project-level instructions
+    - .agents/commands/*.md: Custom slash commands
+    - .agents/skills/*.md: Custom skills/personas
+
+    Args:
+        cwd: Working directory to search in. Defaults to os.getcwd().
+
+    Returns:
+        AgentConfig with all loaded configuration.
+    """
+    root = Path(cwd or os.getcwd())
+    config = AgentConfig()
+
+    # Load README.md first — gives the agent project context upfront
+    for readme_name in ("README.md", "readme.md", "Readme.md"):
+        readme_path = root / readme_name
+        if readme_path.is_file():
+            try:
+                content = readme_path.read_text(encoding="utf-8").strip()
+                config.readme_md = content[:MAX_README_CHARS]
+            except (OSError, UnicodeDecodeError):
+                pass
+            break
+
+    # Load AGENTS.md
+    agents_md_path = root / "AGENTS.md"
+    if agents_md_path.is_file():
+        try:
+            config.agents_md = agents_md_path.read_text(encoding="utf-8").strip()
+        except (OSError, UnicodeDecodeError):
+            pass
+
+    # Load .agents/ directory
+    agents_dir = root / ".agents"
+    if agents_dir.is_dir():
+        config.commands = _load_commands(agents_dir)
+        config.skills = _load_skills(agents_dir)
+
+    # Load opencode-style config (aru.json or .aru/config.json)
+    config_paths = [root / "aru.json", root / ".aru" / "config.json"]
+    for config_path in config_paths:
+        if config_path.is_file():
+            try:
+                content = config_path.read_text(encoding="utf-8")
+                data = json.loads(content)
+                if isinstance(data, dict):
+                    if "permission" in data:
+                        config.permissions = data["permission"]
+                    # Load provider configuration
+                    if "providers" in data or "models" in data:
+                        from aru.providers import load_providers_from_config
+                        load_providers_from_config(data)
+                    # Store model defaults for CLI
+                    if "models" in data and isinstance(data["models"], dict):
+                        config.model_defaults = data["models"]
+                    if "plan_reviewer" in data:
+                        config.plan_reviewer = bool(data["plan_reviewer"])
+                break
+            except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+                pass
+
+    return config
+
+
+def render_command_template(template: str, user_input: str) -> str:
+    """Render a command template with user input.
+
+    Replaces $INPUT with the user's arguments.
+    Also supports $SELECTION (empty if not provided) for future use.
+    """
+    result = template.replace("$INPUT", user_input)
+    result = result.replace("$SELECTION", "")
+    return result

aru/context.py

@@ -0,0 +1,287 @@
+"""Context management for token optimization.
+
+Implements three layers of token reduction:
+1. Pruning — evict old tool/assistant outputs from history
+2. Truncation — universal cap on tool output size
+3. Compaction — summarize entire conversation when approaching context limits
+"""
+
+from __future__ import annotations
+
+# ── Constants ──────────────────────────────────────────────────────
+
+# Pruning: protect the most recent N chars of assistant content from eviction
+PRUNE_PROTECT_CHARS = 50_000  # ~14K tokens
+# Pruning: minimum chars that must be freeable to justify a prune pass
+PRUNE_MINIMUM_CHARS = 20_000  # ~5.7K tokens
+# Placeholder that replaces evicted content
+PRUNED_PLACEHOLDER = "[previous output cleared to save context]"
+
+# Truncation: universal limits for any tool output
+TRUNCATE_MAX_LINES = 500
+TRUNCATE_MAX_BYTES = 20 * 1024  # 20 KB
+TRUNCATE_KEEP_START = 350  # lines to keep from the start
+TRUNCATE_KEEP_END = 100  # lines to keep from the end
+
+# Compaction: trigger when cumulative input tokens exceed this fraction of model limit
+COMPACTION_THRESHOLD_RATIO = 0.50
+# Default model context limits (input tokens)
+MODEL_CONTEXT_LIMITS: dict[str, int] = {
+    "claude-sonnet-4-5-20250929": 200_000,
+    "claude-sonnet-4-20250514": 200_000,
+    "claude-haiku-4-5-20251001": 200_000,
+    "claude-opus-4-20250514": 200_000,
+    "claude-opus-4-6": 1_000_000,
+    "claude-sonnet-4-6": 1_000_000,
+    "gpt-4o": 128_000,
+    "gpt-4o-mini": 128_000,
+    "default": 200_000,
+}
+
+COMPACTION_TEMPLATE = """\
+Summarize this conversation concisely. Preserve:
+1. **Goal**: What the user wants to accomplish
+2. **Key decisions**: Important choices made during the conversation
+3. **Discoveries**: What was learned about the codebase or problem
+4. **Accomplished**: What has been done so far (be specific about files changed)
+5. **Relevant files**: File paths that are important for continuing the work
+6. **Next steps**: What remains to be done
+
+Be concise but complete. This summary replaces the full conversation history."""
+
+
+# ── Layer 1: Pruning ──────────────────────────────────────────────
+
+def prune_history(history: list[dict[str, str]]) -> list[dict[str, str]]:
+    """Replace old assistant messages with a short placeholder to reduce tokens.
+
+    Walks backward through history, protecting the most recent assistant
+    content (up to PRUNE_PROTECT_CHARS). Older assistant messages beyond
+    that budget are replaced with a compact placeholder.
+
+    Returns a new list (does not mutate the input).
+    """
+    if len(history) <= 2:
+        return list(history)
+
+    # Calculate total assistant chars
+    total_assistant_chars = sum(
+        len(msg["content"]) for msg in history if msg["role"] == "assistant"
+    )
+
+    # Not enough to prune
+    if total_assistant_chars < PRUNE_PROTECT_CHARS + PRUNE_MINIMUM_CHARS:
+        return list(history)
+
+    # Walk backward, protecting recent content
+    result = list(history)
+    protected = 0
+
+    for i in range(len(result) - 1, -1, -1):
+        msg = result[i]
+        if msg["role"] != "assistant":
+            continue
+
+        msg_len = len(msg["content"])
+        if protected + msg_len <= PRUNE_PROTECT_CHARS:
+            # Still within protection window
+            protected += msg_len
+        else:
+            # Beyond protection window — prune this message
+            if msg["content"] != PRUNED_PLACEHOLDER:
+                result[i] = {"role": "assistant", "content": PRUNED_PLACEHOLDER}
+
+    return result
+
+
+# ── Layer 2: Truncation ───────────────────────────────────────────
+
+def truncate_output(text: str) -> str:
+    """Universal truncation for tool outputs.
+
+    Caps output at TRUNCATE_MAX_BYTES / TRUNCATE_MAX_LINES, keeping the
+    start and end with a middle marker showing what was cut.
+    """
+    if not text:
+        return text
+
+    # Check byte size
+    byte_len = len(text.encode("utf-8", errors="replace"))
+    lines = text.splitlines(keepends=True)
+    line_count = len(lines)
+
+    if byte_len <= TRUNCATE_MAX_BYTES and line_count <= TRUNCATE_MAX_LINES:
+        return text
+
+    # Truncate by lines
+    if line_count > TRUNCATE_MAX_LINES:
+        head = lines[:TRUNCATE_KEEP_START]
+        tail = lines[-TRUNCATE_KEEP_END:]
+        omitted = line_count - TRUNCATE_KEEP_START - TRUNCATE_KEEP_END
+        return (
+            "".join(head)
+            + f"\n\n[... {omitted:,} lines omitted ({line_count:,} total) — "
+            f"use offset/limit or a more specific query ...]\n\n"
+            + "".join(tail)
+        )
+
+    # Truncate by bytes (lines fit but total bytes too large)
+    kept_lines: list[str] = []
+    total = 0
+    for line in lines:
+        line_bytes = len(line.encode("utf-8", errors="replace"))
+        if total + line_bytes > TRUNCATE_MAX_BYTES:
+            break
+        kept_lines.append(line)
+        total += line_bytes
+
+    remaining = line_count - len(kept_lines)
+    return (
+        "".join(kept_lines)
+        + f"\n\n[... truncated at ~{TRUNCATE_MAX_BYTES // 1024}KB — "
+        f"{remaining:,} more lines — use offset/limit to read further ...]\n"
+    )
+
+
+# ── Layer 3: Compaction ───────────────────────────────────────────
+
+def should_compact(total_input_tokens: int, model_id: str = "default") -> bool:
+    """Check if the conversation should be compacted based on token usage."""
+    limit = MODEL_CONTEXT_LIMITS.get(model_id, MODEL_CONTEXT_LIMITS["default"])
+    threshold = int(limit * COMPACTION_THRESHOLD_RATIO)
+    return total_input_tokens >= threshold
+
+
+def build_compaction_prompt(history: list[dict[str, str]], plan_task: str | None = None) -> str:
+    """Build the prompt sent to the compaction agent to summarize the conversation."""
+    parts = [COMPACTION_TEMPLATE, "\n\n---\n\n## Conversation to summarize:\n"]
+
+    if plan_task:
+        parts.append(f"**Active task:** {plan_task}\n\n")
+
+    for msg in history:
+        role = msg["role"].upper()
+        content = msg["content"]
+        # Cap individual messages in the compaction input to avoid blowing up
+        if len(content) > 2000:
+            content = content[:2000] + f"... [{len(content) - 2000} chars truncated]"
+        parts.append(f"**{role}:** {content}\n\n")
+
+    return "".join(parts)
+
+
+def apply_compaction(history: list[dict[str, str]], summary: str) -> list[dict[str, str]]:
+    """Replace history with a compaction summary + the most recent exchange."""
+    compacted = [
+        {"role": "user", "content": f"[Conversation compacted]\n\n{summary}"}
+    ]
+    # Keep the last user message and last assistant message for continuity
+    last_user = None
+    last_assistant = None
+    for msg in reversed(history):
+        if msg["role"] == "user" and last_user is None:
+            last_user = msg
+        elif msg["role"] == "assistant" and last_assistant is None:
+            last_assistant = msg
+        if last_user and last_assistant:
+            break
+
+    if last_assistant:
+        compacted.append(last_assistant)
+    if last_user and last_user != compacted[0]:
+        compacted.append(last_user)
+
+    return compacted
+
+
+async def compact_conversation(
+    history: list[dict[str, str]],
+    model_ref: str,
+    plan_task: str | None = None,
+) -> list[dict[str, str]]:
+    """Run the compaction agent to summarize and replace history.
+
+    Uses a small/fast model for the summarization to minimize cost.
+    Falls back to simple truncation if the agent call fails.
+    """
+    from aru.tools.codebase import _get_small_model_ref
+    from aru.providers import create_model
+
+    prompt = build_compaction_prompt(history, plan_task)
+
+    try:
+        from agno.agent import Agent
+
+        small_ref = _get_small_model_ref()
+        compactor = Agent(
+            name="Compactor",
+            model=create_model(small_ref, max_tokens=2048),
+            instructions="You summarize conversations concisely. Output ONLY the summary, no preamble.",
+            markdown=True,
+        )
+
+        result = await compactor.arun(prompt, stream=False)
+        summary = result.content if result and result.content else ""
+
+        if not summary:
+            # Fallback: simple mechanical summary
+            summary = _fallback_summary(history, plan_task)
+
+        return apply_compaction(history, summary)
+
+    except Exception:
+        # Fallback if agent fails
+        summary = _fallback_summary(history, plan_task)
+        return apply_compaction(history, summary)
+
+
+def _fallback_summary(history: list[dict[str, str]], plan_task: str | None = None) -> str:
+    """Mechanical summary when the compaction agent is unavailable."""
+    parts = []
+    if plan_task:
+        parts.append(f"**Task:** {plan_task}")
+
+    msg_count = len(history)
+    user_msgs = sum(1 for m in history if m["role"] == "user")
+    parts.append(f"**Conversation:** {msg_count} messages ({user_msgs} from user)")
+
+    # Extract file paths mentioned
+    import re
+    all_text = " ".join(m["content"] for m in history)
+    files = set(re.findall(r'[\w./\\-]+\.(?:py|js|ts|tsx|jsx|go|rs|java|md|json|yaml|yml|toml)', all_text))
+    if files:
+        parts.append(f"**Files referenced:** {', '.join(sorted(files)[:20])}")
+
+    # Keep last 3 messages as brief excerpts
+    parts.append("\n**Recent context:**")
+    for msg in history[-3:]:
+        role = msg["role"]
+        text = msg["content"][:300]
+        if len(msg["content"]) > 300:
+            text += "..."
+        parts.append(f"- [{role}]: {text}")
+
+    return "\n".join(parts)
+
+
+def format_context_block(content: str, label: str = "Context", include_timestamp: bool = True) -> str:
+    """Format a context block with separator and optional timestamp.
+    
+    Args:
+        content: The content to include in the block.
+        label: Label for the context block.
+        include_timestamp: Whether to include timestamp in the separator.
+    
+    Returns:
+        Formatted context block with separators and timestamp.
+    """
+    from datetime import datetime
+    
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    
+    if include_timestamp:
+        separator = f"-- {label} ({timestamp}) --"
+    else:
+        separator = f"-- {label} --"
+    
+    return f"{separator}\n{content}\n{separator}"