aru-code 0.22.1__tar.gz → 0.24.0__tar.gz

{aru_code-0.22.1/aru_code.egg-info → aru_code-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.22.1
+Version: 0.24.0
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT

aru_code-0.24.0/aru/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.24.0"

aru_code-0.24.0/aru/agent_factory.py

@@ -0,0 +1,220 @@
+"""Agent creation: general-purpose and custom agent instantiation."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+
+from aru.agents.base import build_instructions as _build_instructions
+from aru.config import AgentConfig, CustomAgent
+from aru.providers import create_model
+from aru.session import Session
+
+logger = logging.getLogger("aru.agent_factory")
+
+
+def _wrap_tools_with_hooks(tools: list) -> list:
+    """Wrap tool functions to fire tool.execute.before/after plugin hooks.
+
+    Before hook can mutate args; after hook can mutate the result.
+    If a before hook raises, the tool is not executed and the error is returned.
+    """
+    from aru.runtime import get_ctx
+
+    async def _fire(event_name: str, data: dict) -> dict:
+        try:
+            ctx = get_ctx()
+            mgr = ctx.plugin_manager
+            if mgr is not None and mgr.loaded:
+                event = await mgr.fire(event_name, data)
+                return event.data
+        except (LookupError, AttributeError):
+            pass
+        return data
+
+    async def _fire_tool_definition(tool_name: str, description: str, parameters: dict) -> dict:
+        """Fire tool.definition hook — plugins can modify tool desc/params."""
+        try:
+            ctx = get_ctx()
+            mgr = ctx.plugin_manager
+            if mgr is not None and mgr.loaded:
+                event = await mgr.fire("tool.definition", {
+                    "tool_name": tool_name,
+                    "description": description,
+                    "parameters": parameters,
+                })
+                return event.data
+        except (LookupError, AttributeError):
+            pass
+        return {"tool_name": tool_name, "description": description, "parameters": parameters}
+
+    def _wrap_one(fn):
+        if not callable(fn) or getattr(fn, "_hook_wrapped", False):
+            return fn
+
+        @functools.wraps(fn)
+        async def wrapper(**kwargs):
+            tool_name = fn.__name__
+            # Before hook — plugins can mutate args or raise PermissionError to block
+            try:
+                before_data = await _fire("tool.execute.before", {
+                    "tool_name": tool_name,
+                    "args": kwargs,
+                })
+                kwargs = before_data.get("args", kwargs)
+            except PermissionError as e:
+                return f"BLOCKED by plugin: {e}. Do NOT retry this operation."
+
+            # Execute the tool
+            if inspect.iscoroutinefunction(fn):
+                result = await fn(**kwargs)
+            else:
+                result = fn(**kwargs)
+
+            # After hook — plugins can mutate the result
+            after_data = await _fire("tool.execute.after", {
+                "tool_name": tool_name,
+                "args": kwargs,
+                "result": result,
+            })
+            return after_data.get("result", result)
+
+        wrapper._hook_wrapped = True
+        return wrapper
+
+    return [_wrap_one(t) for t in tools]
+
+
+def _fire_sync_hook(event_name: str, data: dict) -> dict:
+    """Fire a plugin hook synchronously (for agent creation context).
+
+    Agent creation happens in sync code, so we need a sync path.
+    """
+    try:
+        from aru.runtime import get_ctx
+        ctx = get_ctx()
+        mgr = ctx.plugin_manager
+        if mgr is not None and mgr.loaded:
+            import asyncio
+            from aru.plugins.hooks import HookEvent
+            event = HookEvent(hook=event_name, data=data or {})
+            for hooks in mgr._hooks:
+                for handler in hooks.get_handlers(event_name):
+                    try:
+                        if asyncio.iscoroutinefunction(handler):
+                            # Best-effort: try to run async handler
+                            try:
+                                loop = asyncio.get_running_loop()
+                            except RuntimeError:
+                                loop = None
+                            if loop and loop.is_running():
+                                # Can't await in sync context with running loop — skip
+                                continue
+                            else:
+                                asyncio.run(handler(event))
+                        else:
+                            handler(event)
+                    except Exception as e:
+                        logger.warning("Hook handler error (%s): %s", event_name, e)
+            return event.data
+    except (LookupError, AttributeError):
+        pass
+    return data
+
+
+def _apply_chat_hooks(instructions: str, model_ref: str, agent_name: str,
+                      max_tokens: int = 8192) -> tuple[str, str, int]:
+    """Apply chat.system.transform and chat.params hooks to agent creation params.
+
+    Returns (instructions, model_ref, max_tokens) — possibly modified by plugins.
+    """
+    # chat.system.transform — plugins can modify the system prompt
+    data = _fire_sync_hook("chat.system.transform", {
+        "system_prompt": instructions,
+        "agent": agent_name,
+    })
+    instructions = data.get("system_prompt", instructions)
+
+    # chat.params — plugins can modify LLM parameters
+    data = _fire_sync_hook("chat.params", {
+        "model": model_ref,
+        "max_tokens": max_tokens,
+        "temperature": None,  # let plugin set if desired
+    })
+    model_ref = data.get("model", model_ref)
+    max_tokens = data.get("max_tokens", max_tokens)
+
+    return instructions, model_ref, max_tokens
+
+
+def create_general_agent(
+    session: Session,
+    config: AgentConfig | None = None,
+    model_override: str | None = None,
+    env_context: str = "",
+):
+    """Create the general-purpose agent.
+
+    Args:
+        env_context: Environment context (cwd, tree, git status) to include
+            in the system prompt. Placed in instructions so it's cacheable.
+    """
+    from agno.agent import Agent
+
+    from aru.tools.codebase import GENERAL_TOOLS
+    tools = _wrap_tools_with_hooks(GENERAL_TOOLS)
+
+    extra = config.get_extra_instructions() if config else ""
+    if env_context:
+        extra = f"{extra}\n\n{env_context}" if extra else env_context
+    model_ref = model_override or session.model_ref
+    instructions = _build_instructions("general", extra)
+
+    # Apply chat hooks (system.transform + params)
+    instructions, model_ref, max_tokens = _apply_chat_hooks(
+        instructions, model_ref, "Aru", max_tokens=8192,
+    )
+
+    return Agent(
+        name="Aru",
+        model=create_model(model_ref, max_tokens=max_tokens),
+        tools=tools,
+        instructions=instructions,
+        markdown=True,
+        tool_call_limit=20,
+    )
+
+
+def create_custom_agent_instance(agent_def: CustomAgent, session: Session,
+                                  config: AgentConfig | None = None,
+                                  env_context: str = ""):
+    """Create an Agno Agent from a CustomAgent definition."""
+    from agno.agent import Agent
+    from aru.agents.base import BASE_INSTRUCTIONS
+    from aru.tools.codebase import resolve_tools
+
+    model_ref = agent_def.model or session.model_ref
+    tools = _wrap_tools_with_hooks(resolve_tools(agent_def.tools))
+
+    extra = config.get_extra_instructions() if config else ""
+    if env_context:
+        extra = f"{extra}\n\n{env_context}" if extra else env_context
+    parts = [agent_def.system_prompt, BASE_INSTRUCTIONS]
+    if extra:
+        parts.append(extra)
+    instructions = "\n\n".join(parts)
+
+    # Apply chat hooks (system.transform + params)
+    instructions, model_ref, max_tokens = _apply_chat_hooks(
+        instructions, model_ref, agent_def.name, max_tokens=8192,
+    )
+
+    return Agent(
+        name=agent_def.name,
+        model=create_model(model_ref, max_tokens=max_tokens),
+        tools=tools,
+        instructions=instructions,
+        markdown=True,
+        tool_call_limit=agent_def.max_turns or 20,
+    )

{aru_code-0.22.1 → aru_code-0.24.0}/aru/agents/base.py

@@ -161,7 +161,10 @@ Use `context_lines=30` for full function bodies.
 
 **Batch independent tool calls**: emit ALL independent tool calls in a single response.
 
-Use delegate_task to split work into independent subtasks for parallel execution.
+Use delegate_task to split work into independent subtasks for parallel execution. \
+For broad codebase exploration (searching many files, finding patterns, understanding code), \
+break the research into focused questions and spawn multiple \
+`delegate_task(task="<specific search>", agent_name="explorer")` calls in parallel.
 
 When given a plan, execute it step by step. When given a direct task, figure out what needs to be done and do it.
 **ZERO narration between tool calls.** No "Now I have enough context...", \
@@ -208,7 +211,34 @@ Batch what you need upfront, then execute.
 
 **When adding or modifying unit tests, ALWAYS run them to verify they pass before finishing.**
 
-Use delegate_task to split work into independent subtasks for parallel execution.\
+## Delegation strategy — CRITICAL for context efficiency
+
+For simple, directed lookups (one known file, one specific symbol) use \
+`grep_search` / `glob_search` / `read_file` directly.
+
+For **anything broader** — understanding a system, researching before implementing, \
+analyzing multiple files, writing specs or documentation — **always use explorer agents**. \
+Every `read_file` / `read_file_smart` / `grep_search` result you call directly accumulates \
+in YOUR context window and stays there forever. Explorer agents read files in their own \
+isolated context and return only a concise summary. This is critical: \
+**3 explorer summaries < 8 raw file reads** in context cost.
+
+**Rule of thumb**: If you'd need to read or search more than 2-3 files, use explorers instead.
+
+**Decompose, don't dump.** Never throw one vague task at one explorer. \
+Break the work into **focused, independent search questions** and spawn one explorer \
+per question — all in a single response so they run in parallel. Each explorer prompt \
+should be specific enough that it can search and answer on its own.
+
+Example — user asks "explain the authentication system":
+```
+delegate_task(task="Find auth middleware: search for login/logout handlers, session management, token validation", agent_name="explorer")
+delegate_task(task="Find auth configuration: search for auth-related config files, env vars, secrets setup", agent_name="explorer")
+delegate_task(task="Find auth tests: search for test files covering authentication flows", agent_name="explorer")
+```
+
+After all explorers return, **synthesize their findings yourself** — the user sees \
+your summary, not the raw explorer output.\
 """
 
 

aru_code-0.24.0/aru/agents/explorer.py

@@ -0,0 +1,91 @@
+"""Explorer agent — fast, read-only codebase exploration specialist."""
+
+import os
+
+from agno.agent import Agent
+
+from aru.providers import create_model
+from aru.runtime import get_ctx
+from aru.tools.codebase import (
+    bash,
+    glob_search,
+    grep_search,
+    list_directory,
+    rank_files,
+    read_file,
+    read_file_smart,
+)
+
+# Read-only tools only — no write/edit/delegate (prevents recursion and mutations)
+EXPLORER_TOOLS = [
+    read_file,
+    read_file_smart,
+    glob_search,
+    grep_search,
+    list_directory,
+    bash,
+    rank_files,
+]
+
+EXPLORER_ROLE = """\
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+=== CRITICAL: READ-ONLY MODE — NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no write_file, touch, or file creation of any kind)
+- Modifying existing files (no edit_file operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. \
+You do NOT have access to file editing tools — attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+- Use glob_search for broad file pattern matching
+- Use grep_search for searching file contents with regex
+- Use read_file when you know the specific file path you need to read
+- Use read_file_smart when you know the file and have a specific question about it
+- Use bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- NEVER use bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, \
+or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+
+NOTE: You are meant to be a FAST agent that returns output as quickly as possible. To achieve this:
+- Make efficient use of tools: be smart about how you search for files and implementations
+- Wherever possible, spawn MULTIPLE PARALLEL tool calls for grepping and reading files
+- Do not read files you don't need — stop as soon as you have enough information
+
+Complete the search request efficiently and report your findings clearly.\
+"""
+
+
+def create_explorer(task: str, context: str = "") -> Agent:
+    """Create and return an explorer agent for a specific task.
+
+    Args:
+        task: The exploration task description.
+        context: Optional extra context (file paths, constraints).
+    """
+    cwd = os.getcwd()
+    small_model_ref = get_ctx().small_model_ref
+
+    instructions = EXPLORER_ROLE + f"\nThe current working directory is: {cwd}\n"
+    if context:
+        instructions += f"\nAdditional context:\n{context}\n"
+
+    return Agent(
+        name="Explorer",
+        model=create_model(small_model_ref, max_tokens=4096),
+        tools=EXPLORER_TOOLS,
+        instructions=instructions,
+        markdown=True,
+        tool_call_limit=15,
+    )

{aru_code-0.22.1 → aru_code-0.24.0}/aru/cache_patch.py

@@ -22,9 +22,9 @@ from __future__ import annotations
 # - Protect recent tool results within a token budget
 # - Only prune if there's enough to free (avoid churn)
 # - Walk backwards, protecting recent content first
-# Aligned with context.py thresholds to keep context ~30K tokens.
-_PRUNE_PROTECT_CHARS = 55_000    # ~14K tokens — recent content always kept
-_PRUNE_MINIMUM_CHARS = 20_000    # ~5K tokens — only prune if this much is freeable
+# OpenCode uses 40K protect / 20K minimum; we use chars (~4 chars/token)
+_PRUNE_PROTECT_CHARS = 160_000   # ~40K tokens — recent content always kept
+_PRUNE_MINIMUM_CHARS = 80_000    # ~20K tokens — only prune if this much is freeable
 _PRUNED_PLACEHOLDER = "[Old tool result cleared]"
 
 # Last API call metrics (updated on every internal API call)

{aru_code-0.22.1 → aru_code-0.24.0}/aru/cli.py

@@ -228,10 +228,20 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
     ctx.plugin_manager = _plugin_mgr
 
     try:
+        _config_dict = {
+            "default_model": config.default_model,
+            "model_aliases": config.model_aliases,
+            "permissions": config.permissions,
+            "plugin_specs": config.plugin_specs,
+            "disabled_tools": config.disabled_tools,
+            "plan_reviewer": config.plan_reviewer,
+        }
         _p_input = PluginInput(
             directory=os.getcwd(),
             config_path="aru.json" if os.path.isfile("aru.json") else "",
             model_ref=session.model_ref,
+            config=_config_dict,
+            session=session,
         )
         _plugin_specs = config.plugin_specs if hasattr(config, "plugin_specs") else []
         _plugin_count = await _plugin_mgr.load_all(_p_input, plugin_specs=_plugin_specs)
@@ -252,6 +262,17 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
 
     asyncio.create_task(_load_mcp_background())
 
+    # Event: session.start
+    if _plugin_mgr.loaded:
+        try:
+            await _plugin_mgr.publish("session.start", {
+                "session_id": getattr(session, "id", None),
+                "model_ref": session.model_ref,
+                "directory": os.getcwd(),
+            })
+        except Exception:
+            pass
+
     while True:
         try:
             paste_state.clear()
@@ -393,6 +414,14 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
             continue
 
         if user_input.lower() in ("/quit", "/exit", "quit", "exit"):
+            # Event: session.end
+            if _plugin_mgr.loaded:
+                try:
+                    await _plugin_mgr.publish("session.end", {
+                        "session_id": getattr(session, "id", None),
+                    })
+                except Exception:
+                    pass
             store.save(session)
             console.print(f"\n[dim]Session saved: {session.session_id}[/dim]")
             console.print(f"[dim]Resume with:[/dim] [bold cyan]aru --resume {session.session_id}[/bold cyan]")
@@ -579,6 +608,26 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
             cmd_name = parts[0].lower()
             cmd_args = parts[1] if len(parts) > 1 else ""
 
+            # Hook: command.execute.before — plugins can block or modify
+            _cmd_blocked = False
+            try:
+                _mgr = ctx.plugin_manager
+                if _mgr is not None and _mgr.loaded:
+                    _cmd_event = await _mgr.fire("command.execute.before", {
+                        "command": cmd_name,
+                        "command_args": cmd_args,
+                        "blocked": False,
+                    })
+                    if _cmd_event.data.get("blocked"):
+                        console.print(f"[yellow]Command /{cmd_name} blocked by plugin.[/yellow]")
+                        _cmd_blocked = True
+                    else:
+                        cmd_args = _cmd_event.data.get("command_args", cmd_args)
+            except Exception:
+                pass
+            if _cmd_blocked:
+                continue
+
             if cmd_name in config.commands:
                 cmd_def = config.commands[cmd_name]
                 prompt = render_command_template(cmd_def.template, cmd_args)

{aru_code-0.22.1 → aru_code-0.24.0}/aru/config.py

@@ -552,7 +552,7 @@ def load_config(cwd: str | None = None) -> AgentConfig:
     # Load config: global (~/.aru/config.json) first, then project-level on top.
     # Project values override global values via deep merge.
     home = Path.home()
-    global_config_paths = [home / ".aru" / "config.json"]
+    global_config_paths = [home / ".aru" / "aru.json", home / ".aru" / "config.json"]
     project_config_paths = [root / "aru.json", root / ".aru" / "config.json"]
 
     merged_data: dict = {}

{aru_code-0.22.1 → aru_code-0.24.0}/aru/context.py

@@ -24,8 +24,8 @@ from __future__ import annotations
 # ── Constants ──────────────────────────────────────────────────────
 
 # Pruning: minimum chars that must be freeable to justify a prune pass.
-# Lower than opencode's 20K tokens to fire early and keep context ~30K tokens.
-PRUNE_MINIMUM_CHARS = 20_000  # ~5K tokens
+# Matches opencode's PRUNE_MINIMUM = 20_000 tokens (~80K chars @ 4 chars/token).
+PRUNE_MINIMUM_CHARS = 80_000  # ~20K tokens
 # Placeholder that replaces cleared tool_result content. Matches
 # cache_patch.py's _PRUNED_PLACEHOLDER so both layers produce identical
 # text when a tool output is cleared.
@@ -48,21 +48,9 @@ TRUNCATE_MAX_LINE_LENGTH = 1500  # chars per individual line (prevents minified
 TRUNCATE_SAVE_DIR = ".aru/truncated"
 
 # Compaction: chars of recent conversation preserved verbatim post-compact.
-#
-# Separate from the prune protect window (160K) because they measure
-# different things:
-#   - Prune protect: "how much tool_result content stays intact"
-#   - Compact recent: "how much full-message history stays verbatim after
-#     the summary replaces the older portion"
-#
-# Set to 80K chars (~20K tokens) — half the prune window. Rationale:
-# with the compactor now running on the main model (not a small one),
-# summaries are faithful enough that we don't need 40K of recent overlap
-# as a safety net. 20K still covers 3-6 recent turns verbatim, which
-# mirrors the "last few exchanges" a human would re-read to resume work.
-# Going to zero would match opencode exactly but requires the reactive
-# overflow replay flow we haven't implemented yet.
-COMPACT_RECENT_CHARS = 80_000
+# Uses the same budget as prune protect (160K chars ≈ 40K tokens) to match
+# opencode's approach where the split point mirrors the prune window.
+COMPACT_RECENT_CHARS = 160_000
 
 # Compaction: trigger when per-call input tokens approach real overflow.
 # Matches opencode's philosophy: only fire near the model's actual context
@@ -177,20 +165,24 @@ def _tool_result_content_len(msg: dict) -> int:
 
 
 def _get_prune_protect_chars(model_id: str = "default") -> int:
-    """Chars of recent tool-result content that must NEVER be pruned.
+    """Chars of recent history that must NEVER be pruned.
+
+    Flat value across all models, mirroring opencode's fixed
+    `PRUNE_PROTECT = 40_000` tokens (compaction.ts:36). At ~4 chars/token
+    that's 160K chars of tool-result content kept intact in the recent
+    window. Older tool_result blocks beyond this budget are eligible for
+    the lossy clear pass in `prune_history`.
 
-    Targets a ~30K token total context window. With ~5K tokens of
-    system prompt + tool definitions and ~7K of user/assistant text,
-    the tool output budget is ~18K tokens ≈ 65K chars. We protect
-    55K chars (~14K tokens) of recent tool output so pruning fires
-    at protect + PRUNE_MINIMUM = 55K + 20K = 75K chars (~19K tokens
-    of tool output), keeping the steady-state around 30K total.
+    Why flat (not scaled by model): opencode validated this in production
+    on contexts from 128K to 1M — scaling by ratio adds complexity without
+    improving behavior, and protecting too much in 1M-context models can
+    actually hurt prompt caching by keeping rarely-touched tail content warm.
 
     The `model_id` parameter is retained for signature compatibility with
     older call sites; it has no effect on the returned value.
     """
     del model_id  # unused — kept for signature compatibility
-    return 55_000
+    return 160_000
 
 
 def prune_history(

{aru_code-0.22.1 → aru_code-0.24.0}/aru/display.py

@@ -204,6 +204,7 @@ TOOL_DISPLAY_NAMES = {
     "list_directory": "List",
     "bash": "Bash",
     "rank_files": "Rank",
+    "delegate_task": "Agent",
 }
 
 TOOL_PRIMARY_ARG = {
@@ -216,6 +217,12 @@ TOOL_PRIMARY_ARG = {
     "list_directory": "directory",
     "bash": "command",
     "rank_files": "task",
+    "delegate_task": "task",
+}
+
+# Agent type display names for delegate_task
+_AGENT_TYPE_LABELS = {
+    "explorer": "Explorer",
 }
 
 
@@ -225,6 +232,17 @@ def _format_tool_label(tool_name: str, tool_args: dict | None) -> str:
     if not tool_args:
         return display
 
+    # Special handling for delegate_task — show agent type and task summary
+    if tool_name == "delegate_task":
+        agent = str(tool_args.get("agent_name", "") or tool_args.get("agent", ""))
+        agent_label = _AGENT_TYPE_LABELS.get(agent, agent.title() if agent else "SubAgent")
+        task = str(tool_args.get("task", ""))
+        # Extract first meaningful line/sentence as summary
+        summary = task.split("\n")[0].strip()
+        if len(summary) > 60:
+            summary = summary[:57] + "..."
+        return f"{agent_label}({summary})" if summary else agent_label
+
     primary_key = TOOL_PRIMARY_ARG.get(tool_name)
     if primary_key and primary_key in tool_args:
         value = str(tool_args[primary_key])

{aru_code-0.22.1 → aru_code-0.24.0}/aru/plugins/__init__.py

@@ -8,5 +8,6 @@ Public API for plugin authors:
 
 from aru.plugins.tool_api import tool
 from aru.plugins.hooks import Hooks, HookEvent, PluginInput
+from aru.plugins.manager import PluginManager
 
-__all__ = ["tool", "Hooks", "HookEvent", "PluginInput"]
+__all__ = ["tool", "Hooks", "HookEvent", "PluginInput", "PluginManager"]