aru-code 0.19.2__tar.gz → 0.20.0__tar.gz

{aru_code-0.19.2/aru_code.egg-info → aru_code-0.20.0}/PKG-INFO

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

aru_code-0.20.0/aru/__init__.py

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

{aru_code-0.19.2 → aru_code-0.20.0}/aru/agents/base.py

@@ -21,6 +21,12 @@ Examples of ideal responses:
 - user: "what command lists files?" → assistant: "ls"
 - user: "fix the typo in line 5" → [call edit_file immediately, no narration]
 
+## Permission denials — CRITICAL
+
+When a tool returns "PERMISSION DENIED", the user intentionally refused the action. \
+NEVER retry the same operation. Do NOT try alternative approaches to achieve the same edit. \
+Instead, stop immediately and ask the user what they would like you to do instead.
+
 ## Scope rules
 
 NEVER create documentation files (*.md) unless the user explicitly asks for them.

{aru_code-0.19.2 → aru_code-0.20.0}/aru/cli.py

@@ -208,6 +208,38 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
     paste_state = PasteState()
     prompt_session = _create_prompt_session(paste_state, config)
 
+    # Load custom tools (synchronous — fast, no network)
+    from aru.plugins.custom_tools import discover_custom_tools, register_custom_tools
+    _disabled_tools = config.disabled_tools if hasattr(config, "disabled_tools") else []
+    _custom_tool_descs = discover_custom_tools(disabled=_disabled_tools)
+    if _custom_tool_descs:
+        _ct_count = register_custom_tools(_custom_tool_descs)
+        console.print(f"[dim]Loaded {_ct_count} custom tool(s): {', '.join(d['name'] for d in _custom_tool_descs)}[/dim]")
+
+    # Load plugins (local imports only, no network)
+    from aru.plugins.manager import PluginManager
+    from aru.plugins.hooks import PluginInput
+    _plugin_mgr = PluginManager()
+    ctx.plugin_manager = _plugin_mgr
+
+    try:
+        _p_input = PluginInput(
+            directory=os.getcwd(),
+            config_path="aru.json" if os.path.isfile("aru.json") else "",
+            model_ref=session.model_ref,
+        )
+        _plugin_specs = config.plugin_specs if hasattr(config, "plugin_specs") else []
+        _plugin_count = await _plugin_mgr.load_all(_p_input, plugin_specs=_plugin_specs)
+        if _plugin_count:
+            plugin_tools = _plugin_mgr.get_plugin_tools()
+            if plugin_tools:
+                _pt_count = register_custom_tools(plugin_tools)
+                console.print(f"[dim]Loaded {_plugin_count} plugin(s): {', '.join(_plugin_mgr.plugin_names)} ({_pt_count} tool(s))[/dim]")
+            else:
+                console.print(f"[dim]Loaded {_plugin_count} plugin(s): {', '.join(_plugin_mgr.plugin_names)}[/dim]")
+    except Exception as exc:
+        console.print(f"[dim yellow]Warning: plugin loading failed: {exc}[/dim yellow]")
+
     # Startup: load MCP tools in background (don't block REPL)
     async def _load_mcp_background():
         from aru.tools.codebase import load_mcp_tools

{aru_code-0.19.2 → aru_code-0.20.0}/aru/config.py

@@ -161,6 +161,8 @@ class AgentConfig:
     custom_agents: dict[str, CustomAgent] = field(default_factory=dict)
     plan_reviewer: bool = True
     tree_depth: int = 2  # max depth for directory tree in system prompt
+    disabled_tools: list[str] = field(default_factory=list)  # tools to skip loading
+    plugin_specs: list = field(default_factory=list)  # plugin specs from aru.json
 
     @property
     def has_instructions(self) -> bool:
@@ -515,6 +517,14 @@ def load_config(cwd: str | None = None) -> AgentConfig:
                         td = data["tree_depth"]
                         if isinstance(td, int) and 0 <= td <= 5:
                             config.tree_depth = td
+                    # Plugin specs
+                    if "plugins" in data and isinstance(data["plugins"], list):
+                        config.plugin_specs = data["plugins"]
+                    # Custom tools config
+                    if "tools" in data and isinstance(data["tools"], dict):
+                        tools_cfg = data["tools"]
+                        if "disabled" in tools_cfg and isinstance(tools_cfg["disabled"], list):
+                            config.disabled_tools = [str(t) for t in tools_cfg["disabled"]]
                     # Resolve instructions (local files, globs, URLs)
                     if "instructions" in data and isinstance(data["instructions"], list):
                         entries = [str(e) for e in data["instructions"] if isinstance(e, str)]

{aru_code-0.19.2 → aru_code-0.20.0}/aru/context.py

@@ -420,34 +420,52 @@ def truncate_output(
     # Save full output to disk before truncating (like OpenCode)
     saved_path = _save_truncated_output(text)
 
-    # Truncate by lines
+    # Truncate by lines — keep head + tail so summaries at the end are visible
     if line_count > TRUNCATE_MAX_LINES:
         head = lines[:TRUNCATE_KEEP_START]
-        omitted = line_count - TRUNCATE_KEEP_START
+        tail = lines[-TRUNCATE_KEEP_END:]
+        omitted = line_count - TRUNCATE_KEEP_START - TRUNCATE_KEEP_END
         hint = _build_truncation_hint(source_file, source_tool, TRUNCATE_KEEP_START, saved_path)
         return (
             "".join(head)
             + f"\n\n[... {omitted:,} lines omitted ({line_count:,} total)]\n"
-            + hint + "\n"
+            + hint + "\n\n"
+            + "".join(tail)
         )
 
     # Truncate by bytes (lines fit but total bytes too large)
-    kept_lines: list[str] = []
-    total = 0
+    # Reserve ~20% of budget for tail lines
+    head_budget = int(TRUNCATE_MAX_BYTES * 0.75)
+    tail_budget = TRUNCATE_MAX_BYTES - head_budget
+
+    head_lines: list[str] = []
+    head_bytes = 0
     for line in lines:
         line_bytes = len(line.encode("utf-8", errors="replace"))
-        if total + line_bytes > TRUNCATE_MAX_BYTES:
+        if head_bytes + line_bytes > head_budget:
             break
-        kept_lines.append(line)
-        total += line_bytes
+        head_lines.append(line)
+        head_bytes += line_bytes
 
-    remaining = line_count - len(kept_lines)
-    hint = _build_truncation_hint(source_file, source_tool, len(kept_lines), saved_path)
+    # Collect tail lines within tail budget
+    tail_lines: list[str] = []
+    tail_bytes = 0
+    for line in reversed(lines[len(head_lines):]):
+        line_bytes = len(line.encode("utf-8", errors="replace"))
+        if tail_bytes + line_bytes > tail_budget:
+            break
+        tail_lines.append(line)
+        tail_bytes += line_bytes
+    tail_lines.reverse()
+
+    omitted = line_count - len(head_lines) - len(tail_lines)
+    hint = _build_truncation_hint(source_file, source_tool, len(head_lines), saved_path)
     return (
-        "".join(kept_lines)
+        "".join(head_lines)
         + f"\n\n[... truncated at ~{TRUNCATE_MAX_BYTES // 1024}KB — "
-        f"{remaining:,} more lines]\n"
-        + hint + "\n"
+        f"{omitted:,} lines omitted]\n"
+        + hint + "\n\n"
+        + "".join(tail_lines)
     )
 
 
@@ -660,6 +678,17 @@ async def compact_conversation(
     """
     from aru.providers import create_model
 
+    # Fire session.compact hook — plugins can pre-process history.
+    # Import is lazy here to avoid circular dependency (context ← runtime).
+    try:
+        from aru.runtime import get_ctx  # noqa: lazy to avoid circular dep
+        mgr = get_ctx().plugin_manager
+        if mgr is not None and mgr.loaded:
+            event = await mgr.fire("session.compact", {"history": history})
+            history = event.data.get("history", history)
+    except (LookupError, AttributeError, ImportError):
+        pass  # no plugin manager available — proceed without hooks
+
     prompt = build_compaction_prompt(history, plan_task, model_id=model_id)
 
     try:

{aru_code-0.19.2 → aru_code-0.20.0}/aru/permissions.py

@@ -413,6 +413,42 @@ def resolve_permission(
 # Permission gate (user-facing prompt)
 # ---------------------------------------------------------------------------
 
+def _fire_permission_hook(mgr, category: str, subject: str) -> bool | None:
+    """Fire permission.ask hook through all plugin handlers.
+
+    Supports both sync and async handlers. Returns True/False if a handler
+    sets event.data["allow"], or None if no handler overrode the decision.
+    """
+    import asyncio
+    from aru.plugins.hooks import HookEvent
+
+    evt = HookEvent(hook="permission.ask", data={"category": category, "subject": subject})
+
+    for hooks_obj in mgr._hooks:
+        for handler in hooks_obj.get_handlers("permission.ask"):
+            try:
+                if asyncio.iscoroutinefunction(handler):
+                    # Async handler — run via the event loop
+                    loop = asyncio.get_event_loop()
+                    if loop.is_running():
+                        # Schedule as a task and wait with run_until_complete
+                        # won't work, so use a new loop in a thread
+                        import concurrent.futures
+                        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                            pool.submit(asyncio.run, handler(evt)).result(timeout=5)
+                    else:
+                        loop.run_until_complete(handler(evt))
+                else:
+                    handler(evt)
+            except Exception:
+                continue  # skip broken handlers
+
+            if "allow" in evt.data:
+                return bool(evt.data["allow"])
+
+    return None  # no handler overrode
+
+
 def check_permission(
     category: str,
     subject: str,
@@ -429,8 +465,20 @@ def check_permission(
     if action == "deny":
         return False
 
-    # action == "ask" -> prompt user
+    # Fire permission.ask hook — plugins can override the decision.
+    # check_permission runs in a sync context (called from tool threads),
+    # so we fire sync handlers directly and async handlers via the event loop.
     ctx = get_ctx()
+    mgr = getattr(ctx, "plugin_manager", None)
+    if mgr is not None and getattr(mgr, "loaded", False):
+        try:
+            override = _fire_permission_hook(mgr, category, subject)
+            if override is not None:
+                return override
+        except Exception:
+            pass  # never let plugin errors block permissions
+
+    # action == "ask" -> prompt user
     with ctx.permission_lock:
         # Re-check after acquiring lock (another thread may have resolved it)
         action2, pattern2 = resolve_permission(category, subject)

aru_code-0.20.0/aru/plugins/__init__.py

@@ -0,0 +1,12 @@
+"""Aru plugin system — custom tools, hooks, and OpenCode TS bridge.
+
+Public API for plugin authors:
+
+    from aru.plugins import tool          # @tool decorator for custom tools
+    from aru.plugins import PluginInput, Hooks  # Full plugin API (Phase 2)
+"""
+
+from aru.plugins.tool_api import tool
+from aru.plugins.hooks import Hooks, HookEvent, PluginInput
+
+__all__ = ["tool", "Hooks", "HookEvent", "PluginInput"]

aru_code-0.20.0/aru/plugins/custom_tools.py

@@ -0,0 +1,350 @@
+"""Discover and load custom tool files (.py) from tool directories.
+
+Discovery paths (later overrides earlier):
+  1. ~/.agents/tools/*.py, ~/.aru/tools/*.py  (global)
+  2. .agents/tools/*.py, .aru/tools/*.py      (project-local)
+
+Tool files can define tools in two ways:
+  - @tool-decorated functions (from aru.plugins import tool)
+  - Bare functions with -> str return annotation
+
+Naming convention (mirrors OpenCode):
+  - File deploy.py with def deploy -> tool name: "deploy"
+  - File ci.py with def build + def test -> tool names: "ci_build", "ci_test"
+  - Single function in file -> filename only (no prefix)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import inspect
+import logging
+import sys
+import types
+from pathlib import Path
+from typing import Any, Callable
+
+from aru.plugins.tool_api import get_tool_meta
+
+logger = logging.getLogger("aru.plugins")
+
+
+def _extract_tools_from_module(mod: types.ModuleType) -> list[tuple[str, Callable, dict[str, Any] | None]]:
+    """Extract tool functions from a loaded module.
+
+    Returns list of (export_name, function, tool_meta_or_None).
+    """
+    tools: list[tuple[str, Callable, dict[str, Any] | None]] = []
+
+    for name in dir(mod):
+        if name.startswith("_"):
+            continue
+        obj = getattr(mod, name)
+        if not callable(obj) or not inspect.isfunction(obj):
+            continue
+
+        meta = get_tool_meta(obj)
+        if meta is not None:
+            # @tool-decorated function
+            tools.append((name, obj, meta))
+        else:
+            # Bare function — must have -> str annotation
+            hints = getattr(obj, "__annotations__", {})
+            ret = hints.get("return")
+            if ret is str or (isinstance(ret, str) and ret == "str"):
+                tools.append((name, obj, None))
+
+    return tools
+
+
+def _build_parameters_from_function(fn: Callable) -> dict[str, Any]:
+    """Build a JSON Schema parameters dict from a function's signature + docstring."""
+    sig = inspect.signature(fn)
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    # Parse argument descriptions from docstring Args section
+    arg_descriptions = _parse_arg_descriptions(fn.__doc__ or "")
+
+    type_map = {
+        str: "string",
+        int: "integer",
+        float: "number",
+        bool: "boolean",
+        list: "array",
+        dict: "object",
+    }
+
+    for pname, param in sig.parameters.items():
+        if pname in ("self", "cls"):
+            continue
+
+        annotation = param.annotation
+        json_type = "string"  # default
+        if annotation != inspect.Parameter.empty:
+            if annotation in type_map:
+                json_type = type_map[annotation]
+            elif isinstance(annotation, str) and annotation in ("str", "int", "float", "bool", "list", "dict"):
+                json_type = type_map.get({"str": str, "int": int, "float": float, "bool": bool, "list": list, "dict": dict}.get(annotation, str), "string")
+
+        prop: dict[str, Any] = {"type": json_type}
+        desc = arg_descriptions.get(pname)
+        if desc:
+            prop["description"] = desc
+
+        if param.default != inspect.Parameter.empty:
+            prop["default"] = param.default
+        else:
+            required.append(pname)
+
+        properties[pname] = prop
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def _parse_arg_descriptions(docstring: str) -> dict[str, str]:
+    """Parse 'Args:' section from a Google-style docstring."""
+    descriptions: dict[str, str] = {}
+    in_args = False
+    current_arg = ""
+    current_desc_parts: list[str] = []
+
+    for line in docstring.splitlines():
+        stripped = line.strip()
+
+        if stripped.lower().startswith("args:"):
+            in_args = True
+            continue
+
+        if in_args:
+            # End of Args section: another section header or blank after content
+            if stripped and not stripped.startswith("-") and ":" not in stripped and current_arg:
+                # Continuation line
+                current_desc_parts.append(stripped)
+                continue
+            if stripped == "" and current_arg:
+                descriptions[current_arg] = " ".join(current_desc_parts)
+                current_arg = ""
+                current_desc_parts = []
+                continue
+            if stripped == "":
+                continue
+
+            # Check for section headers (Returns:, Raises:, etc.)
+            if stripped.endswith(":") and not stripped.startswith("-") and " " not in stripped.rstrip(":"):
+                if current_arg:
+                    descriptions[current_arg] = " ".join(current_desc_parts)
+                break
+
+            # Parse "param_name: description" or "param_name (type): description"
+            if ":" in stripped:
+                if current_arg:
+                    descriptions[current_arg] = " ".join(current_desc_parts)
+
+                parts = stripped.split(":", 1)
+                arg_part = parts[0].strip().lstrip("-").strip()
+                # Remove type annotations like (str) or (int)
+                if "(" in arg_part:
+                    arg_part = arg_part[:arg_part.index("(")].strip()
+                current_arg = arg_part
+                current_desc_parts = [parts[1].strip()] if len(parts) > 1 and parts[1].strip() else []
+
+    if current_arg:
+        descriptions[current_arg] = " ".join(current_desc_parts)
+
+    return descriptions
+
+
+def _load_module_from_path(filepath: Path) -> types.ModuleType | None:
+    """Dynamically import a Python file as a module."""
+    module_name = f"aru_custom_tool_{filepath.stem}"
+    try:
+        spec = importlib.util.spec_from_file_location(module_name, str(filepath))
+        if spec is None or spec.loader is None:
+            logger.warning("Cannot load tool file (no spec): %s", filepath)
+            return None
+        mod = importlib.util.module_from_spec(spec)
+        # Add the file's directory to sys.path temporarily so relative imports work
+        parent = str(filepath.parent)
+        added = parent not in sys.path
+        if added:
+            sys.path.insert(0, parent)
+        try:
+            spec.loader.exec_module(mod)
+        finally:
+            if added and parent in sys.path:
+                sys.path.remove(parent)
+        return mod
+    except Exception as e:
+        logger.warning("Failed to load custom tool %s: %s", filepath, e)
+        return None
+
+
+def discover_custom_tools(
+    search_roots: list[Path] | None = None,
+    disabled: list[str] | None = None,
+) -> list[dict[str, Any]]:
+    """Discover custom tool files and return tool descriptors.
+
+    Args:
+        search_roots: Directories to scan for tools/ subdirectories.
+            If None, uses default paths (global + project-local).
+        disabled: List of tool names to skip.
+
+    Returns:
+        List of dicts with keys: name, description, parameters, entrypoint, source.
+        Later entries override earlier ones (project-local wins).
+    """
+    from agno.tools import Function
+
+    if search_roots is None:
+        search_roots = _default_search_roots()
+
+    disabled_set = set(disabled or [])
+    tools_by_name: dict[str, dict[str, Any]] = {}
+
+    for root in search_roots:
+        tools_dir = root / "tools"
+        if not tools_dir.is_dir():
+            continue
+
+        for filepath in sorted(tools_dir.glob("*.py")):
+            if filepath.name.startswith("_"):
+                continue
+
+            mod = _load_module_from_path(filepath)
+            if mod is None:
+                continue
+
+            file_stem = filepath.stem
+            extracted = _extract_tools_from_module(mod)
+
+            # Naming: single function -> filename; multiple -> filename_exportname
+            use_prefix = len(extracted) > 1
+
+            for export_name, fn, meta in extracted:
+                if use_prefix and export_name != file_stem and export_name != "default":
+                    tool_name = f"{file_stem}_{export_name}"
+                else:
+                    tool_name = file_stem
+
+                if tool_name in disabled_set:
+                    logger.debug("Skipping disabled custom tool: %s", tool_name)
+                    continue
+
+                description = ""
+                if meta and meta.get("description"):
+                    description = meta["description"]
+                elif fn.__doc__:
+                    # First line of docstring as description
+                    description = fn.__doc__.strip().split("\n")[0]
+                else:
+                    description = f"Custom tool: {tool_name}"
+
+                parameters = _build_parameters_from_function(fn)
+
+                # Wrap async/sync functions uniformly
+                original_fn = fn
+                if asyncio.iscoroutinefunction(fn):
+                    async def entrypoint(*, _fn=original_fn, **kwargs) -> str:
+                        result = await _fn(**kwargs)
+                        return str(result) if result is not None else ""
+                else:
+                    async def entrypoint(*, _fn=original_fn, **kwargs) -> str:
+                        result = _fn(**kwargs)
+                        return str(result) if result is not None else ""
+
+                entrypoint.__name__ = tool_name
+                entrypoint.__doc__ = fn.__doc__
+
+                tools_by_name[tool_name] = {
+                    "name": tool_name,
+                    "description": description,
+                    "parameters": parameters,
+                    "entrypoint": entrypoint,
+                    "source": str(filepath),
+                    "override": bool(meta and meta.get("override")),
+                }
+
+    return list(tools_by_name.values())
+
+
+def register_custom_tools(tool_descriptors: list[dict[str, Any]]) -> int:
+    """Inject custom tools into the global tool registry.
+
+    Custom tools with the same name as built-in tools will override them.
+
+    Returns:
+        Number of tools registered.
+    """
+    from agno.tools import Function
+
+    from aru.tools.codebase import (
+        ALL_TOOLS,
+        EXECUTOR_TOOLS,
+        GENERAL_TOOLS,
+        TOOL_REGISTRY,
+    )
+
+    count = 0
+    for desc in tool_descriptors:
+        name = desc["name"]
+        agno_fn = Function(
+            name=name,
+            description=desc["description"],
+            parameters=desc["parameters"],
+            entrypoint=desc["entrypoint"],
+        )
+
+        # Override existing tool if same name exists
+        existing = TOOL_REGISTRY.get(name)
+        if existing is not None:
+            # Determine what's being overridden for clear logging
+            existing_source = getattr(existing, "_aru_source", "built-in")
+            for tool_list in (ALL_TOOLS, GENERAL_TOOLS, EXECUTOR_TOOLS):
+                for i, t in enumerate(tool_list):
+                    t_name = getattr(t, "__name__", None) or getattr(t, "name", None)
+                    if t_name == name:
+                        tool_list[i] = agno_fn
+                        break
+            logger.warning("Tool '%s' from %s overrides %s", name, desc["source"], existing_source)
+        else:
+            ALL_TOOLS.append(agno_fn)
+            GENERAL_TOOLS.append(agno_fn)
+            EXECUTOR_TOOLS.append(agno_fn)
+
+        agno_fn._aru_source = desc["source"]  # tag for collision logging
+        TOOL_REGISTRY[name] = agno_fn
+        count += 1
+        logger.debug("Registered custom tool: %s (from %s)", name, desc["source"])
+
+    return count
+
+
+def _default_search_roots() -> list[Path]:
+    """Return default tool search roots: global dirs first, then project-local."""
+    import os
+    roots: list[Path] = []
+    home = Path.home()
+
+    # Global roots
+    for dirname in (".agents", ".aru"):
+        global_dir = home / dirname
+        if global_dir.is_dir():
+            roots.append(global_dir)
+
+    # Project-local roots
+    cwd = Path(os.getcwd())
+    for dirname in (".agents", ".aru"):
+        local_dir = cwd / dirname
+        if local_dir.is_dir():
+            roots.append(local_dir)
+
+    return roots