aru-code 0.7.0__tar.gz → 0.9.0__tar.gz

{aru_code-0.7.0/aru_code.egg-info → aru_code-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.7.0
+Version: 0.9.0
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT
@@ -302,6 +302,31 @@ Without any `aru.json` config, aru applies safe defaults:
 
 Place an `AGENTS.md` file in your project root with custom instructions that will be appended to all agent system prompts.
 
+### Instructions (Rules)
+
+You can load additional instructions from local files, glob patterns, or remote URLs via the `instructions` field in `aru.json`:
+
+```json
+{
+  "instructions": [
+    "CONTRIBUTING.md",
+    "docs/coding-standards.md",
+    "packages/*/AGENTS.md",
+    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
+  ]
+}
+```
+
+Each entry is resolved as follows:
+
+| Format | Example | Behavior |
+|--------|---------|----------|
+| **Local file** | `"CONTRIBUTING.md"` | Reads the file relative to the project root |
+| **Glob pattern** | `"docs/**/*.md"` | Expands the pattern, respects `.gitignore` |
+| **Remote URL** | `"https://example.com/rules.md"` | Fetches via HTTP (5s timeout, cached per session) |
+
+All resolved content is combined and appended to the agent's system prompt alongside `AGENTS.md`. Individual files are capped at 10KB, and the total combined size is capped at 50KB to prevent context bloat. Missing files and failed URL fetches are skipped with a warning.
+
 ### `.agents/` Directory
 
 ```

{aru_code-0.7.0 → aru_code-0.9.0}/README.md

@@ -255,6 +255,31 @@ Without any `aru.json` config, aru applies safe defaults:
 
 Place an `AGENTS.md` file in your project root with custom instructions that will be appended to all agent system prompts.
 
+### Instructions (Rules)
+
+You can load additional instructions from local files, glob patterns, or remote URLs via the `instructions` field in `aru.json`:
+
+```json
+{
+  "instructions": [
+    "CONTRIBUTING.md",
+    "docs/coding-standards.md",
+    "packages/*/AGENTS.md",
+    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
+  ]
+}
+```
+
+Each entry is resolved as follows:
+
+| Format | Example | Behavior |
+|--------|---------|----------|
+| **Local file** | `"CONTRIBUTING.md"` | Reads the file relative to the project root |
+| **Glob pattern** | `"docs/**/*.md"` | Expands the pattern, respects `.gitignore` |
+| **Remote URL** | `"https://example.com/rules.md"` | Fetches via HTTP (5s timeout, cached per session) |
+
+All resolved content is combined and appended to the agent's system prompt alongside `AGENTS.md`. Individual files are capped at 10KB, and the total combined size is capped at 50KB to prevent context bloat. Missing files and failed URL fetches are skipped with a warning.
+
 ### `.agents/` Directory
 
 ```

aru_code-0.9.0/aru/__init__.py

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

{aru_code-0.7.0 → aru_code-0.9.0}/aru/agent_factory.py

@@ -13,7 +13,8 @@ def create_general_agent(session: Session, config: AgentConfig | None = None):
     from agno.agent import Agent
     from agno.compression.manager import CompressionManager
 
-    from aru.tools.codebase import GENERAL_TOOLS, _get_small_model_ref
+    from aru.tools.codebase import GENERAL_TOOLS
+    from aru.runtime import get_ctx
 
     extra = config.get_extra_instructions() if config else ""
 
@@ -25,7 +26,7 @@ def create_general_agent(session: Session, config: AgentConfig | None = None):
         markdown=True,
         compress_tool_results=True,
         compression_manager=CompressionManager(
-            model=create_model(_get_small_model_ref(), max_tokens=1024),
+            model=create_model(get_ctx().small_model_ref, max_tokens=1024),
             compress_tool_results=True,
             compress_tool_results_limit=15,
         ),
@@ -39,7 +40,8 @@ def create_custom_agent_instance(agent_def: CustomAgent, session: Session,
     from agno.agent import Agent
     from agno.compression.manager import CompressionManager
     from aru.agents.base import BASE_INSTRUCTIONS
-    from aru.tools.codebase import resolve_tools, _get_small_model_ref
+    from aru.tools.codebase import resolve_tools
+    from aru.runtime import get_ctx
 
     model_ref = agent_def.model or session.model_ref
     tools = resolve_tools(agent_def.tools)
@@ -58,7 +60,7 @@ def create_custom_agent_instance(agent_def: CustomAgent, session: Session,
         markdown=True,
         compress_tool_results=True,
         compression_manager=CompressionManager(
-            model=create_model(_get_small_model_ref(), max_tokens=1024),
+            model=create_model(get_ctx().small_model_ref, max_tokens=1024),
             compress_tool_results=True,
             compress_tool_results_limit=15,
         ),

{aru_code-0.7.0 → aru_code-0.9.0}/aru/agents/executor.py

@@ -6,7 +6,8 @@ from agno.utils.log import log_warning
 
 from aru.agents.base import build_instructions
 from aru.providers import create_model
-from aru.tools.codebase import EXECUTOR_TOOLS, _get_small_model_ref
+from aru.tools.codebase import EXECUTOR_TOOLS
+from aru.runtime import get_ctx
 
 # Max chars for truncation fallback when compression fails
 _TRUNCATE_FALLBACK = 3000
@@ -50,7 +51,7 @@ def create_executor(model_ref: str = "anthropic/claude-sonnet-4-5", extra_instru
         # Compress tool results after 5 uncompressed tool calls to save tokens
         compress_tool_results=True,
         compression_manager=_SafeCompressionManager(
-            model=create_model(_get_small_model_ref(), max_tokens=2048),
+            model=create_model(get_ctx().small_model_ref, max_tokens=2048),
             compress_tool_results=True,
             compress_tool_results_limit=15,
         ),

{aru_code-0.7.0 → aru_code-0.9.0}/aru/agents/planner.py

@@ -6,9 +6,9 @@ from agno.compression.manager import CompressionManager
 from aru.agents.base import build_instructions
 from aru.providers import create_model
 from aru.tools.codebase import (
-    _get_small_model_ref,
     glob_search, grep_search, list_directory, read_file, read_file_smart,
 )
+from aru.runtime import get_ctx
 
 REVIEWER_INSTRUCTIONS = """\
 You are a plan scope reviewer. You receive a user request and a generated implementation plan.
@@ -47,7 +47,7 @@ async def review_plan(request: str, plan: str) -> str:
     """
     reviewer = Agent(
         name="Reviewer",
-        model=create_model(_get_small_model_ref(), max_tokens=2048),
+        model=create_model(get_ctx().small_model_ref, max_tokens=2048),
         instructions=REVIEWER_INSTRUCTIONS,
         markdown=True,
     )
@@ -77,7 +77,7 @@ def create_planner(model_ref: str = "anthropic/claude-sonnet-4-5", extra_instruc
         # Compress tool results after 6 uncompressed tool calls to save tokens
         compress_tool_results=True,
         compression_manager=CompressionManager(
-            model=create_model(_get_small_model_ref(), max_tokens=1024),
+            model=create_model(get_ctx().small_model_ref, max_tokens=1024),
             compress_tool_results=True,
             compress_tool_results_limit=15,
         ),

{aru_code-0.7.0 → aru_code-0.9.0}/aru/cli.py

@@ -104,24 +104,18 @@ from aru.providers import (
 
 async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
     """Main REPL loop."""
-    from aru.tools.codebase import set_model_id, set_small_model_ref, set_on_file_mutation
-    from aru.permissions import (
-        set_config as set_perm_config,
-        set_skip_permissions,
-        set_console as perm_set_console,
-        reset_session as perm_reset_session,
-        parse_permission_config,
-    )
-    from aru.tools.codebase import set_console
-    set_console(console)
-    perm_set_console(console)
-    set_skip_permissions(skip_permissions)
+    import atexit
+    from aru.runtime import init_ctx, get_ctx
+    from aru.permissions import parse_permission_config, reset_session as perm_reset_session
+    from aru.tools.codebase import cleanup_processes
+
+    ctx = init_ctx(console=console, skip_permissions=skip_permissions)
 
     store = SessionStore()
 
     def _sync_model(sess: Session):
-        """Sync the model IDs to the tools module from the session's model_ref."""
-        set_model_id(sess.model_id)
+        """Sync the model IDs to the RuntimeContext from the session's model_ref."""
+        ctx.model_id = sess.model_id
         small_ref = config.model_aliases.get("small") if config else None
         if not small_ref:
             provider_key, _ = resolve_model_ref(sess.model_ref)
@@ -133,7 +127,7 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
                 "ollama": "ollama/llama3.1",
             }
             small_ref = _small_defaults.get(provider_key, sess.model_ref)
-        set_small_model_ref(small_ref)
+        ctx.small_model_ref = small_ref
 
     # Load project configuration
     config = load_config()
@@ -143,6 +137,8 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
         console.print(f"[dim]Loaded {len(config.commands)} custom command(s): {', '.join(f'/{k}' for k in config.commands)}[/dim]")
     if config.skills:
         console.print(f"[dim]Loaded {len(config.skills)} skill(s): {', '.join(config.skills.keys())}[/dim]")
+    if config.rules_instructions:
+        console.print("[dim]Loaded custom instructions from aru.json[/dim]")
     if config.custom_agents:
         primary = [k for k, v in config.custom_agents.items() if v.mode == "primary"]
         subagents = [k for k, v in config.custom_agents.items() if v.mode == "subagent"]
@@ -155,8 +151,7 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
         from aru.tools.codebase import set_custom_agents
         set_custom_agents(config.custom_agents)
     if config.permissions:
-        perm_config = parse_permission_config(config.permissions)
-        set_perm_config(perm_config)
+        ctx.perm_config = parse_permission_config(config.permissions)
         console.print("[dim]Loaded permission config[/dim]")
 
     extra_instructions = config.get_extra_instructions()
@@ -188,8 +183,9 @@ async def run_cli(skip_permissions: bool = False, resume_id: str | None = None):
         _sync_model(session)
         _render_home(session, skip_permissions)
 
-    # Wire file-mutation callback
-    set_on_file_mutation(session.invalidate_context_cache)
+    # Wire file-mutation callback and atexit cleanup
+    ctx.on_file_mutation = session.invalidate_context_cache
+    atexit.register(lambda: cleanup_processes(ctx.tracked_processes))
 
     planner = None
     executor = None

{aru_code-0.7.0 → aru_code-0.9.0}/aru/config.py

@@ -10,12 +10,15 @@ Supports:
 from __future__ import annotations
 
 import json
+import logging
 import os
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+logger = logging.getLogger("aru.config")
+
 
 @dataclass
 class CustomCommand:
@@ -54,6 +57,92 @@ class CustomAgent:
 
 
 MAX_README_CHARS = 2000  # Reduced from 8000 to save ~1.7K tokens per request
+MAX_RULE_FILE_SIZE = 10_000  # 10KB per rule file
+URL_FETCH_TIMEOUT = 5  # seconds
+MAX_TOTAL_RULES_SIZE = 50_000  # 50KB combined cap
+
+# Module-level URL cache (session-scoped, persists for process lifetime)
+_url_cache: dict[str, str | None] = {}
+
+
+def _resolve_instructions(entries: list[str], root: Path) -> str:
+    """Resolve instruction entries (local files, glob patterns, URLs) into combined text.
+
+    Each entry is classified as:
+    - URL: starts with http:// or https://
+    - Glob: contains *, ?, or [
+    - File path: everything else (resolved relative to root)
+    """
+    from aru.tools.gitignore import is_ignored
+
+    parts: list[str] = []
+    total_size = 0
+
+    def _add_content(source: str, content: str) -> None:
+        nonlocal total_size
+        if not content.strip():
+            return
+        truncated = content[:MAX_RULE_FILE_SIZE]
+        if total_size + len(truncated) > MAX_TOTAL_RULES_SIZE:
+            remaining = MAX_TOTAL_RULES_SIZE - total_size
+            if remaining <= 0:
+                logger.warning("Total rules size cap reached, skipping: %s", source)
+                return
+            truncated = truncated[:remaining]
+            logger.warning("Total rules size cap reached, truncating: %s", source)
+        parts.append(f"## Rules: {source}\n\n{truncated}")
+        total_size += len(truncated)
+
+    def _read_file(filepath: Path, source_label: str) -> None:
+        try:
+            content = filepath.read_text(encoding="utf-8")
+            _add_content(source_label, content)
+        except (OSError, UnicodeDecodeError) as exc:
+            logger.warning("Failed to read instruction file %s: %s", filepath, exc)
+
+    for entry in entries:
+        if entry.startswith("http://") or entry.startswith("https://"):
+            # Remote URL
+            if entry in _url_cache:
+                cached = _url_cache[entry]
+                if cached is not None:
+                    _add_content(entry, cached)
+                continue
+            try:
+                import httpx
+                with httpx.Client(timeout=URL_FETCH_TIMEOUT, follow_redirects=True) as client:
+                    resp = client.get(entry)
+                    resp.raise_for_status()
+                    text = resp.text
+                _url_cache[entry] = text
+                _add_content(entry, text)
+            except Exception as exc:
+                _url_cache[entry] = None
+                logger.warning("Failed to fetch instruction URL %s: %s", entry, exc)
+
+        elif any(c in entry for c in ("*", "?", "[")):
+            # Glob pattern
+            matched = sorted(root.glob(entry))
+            for filepath in matched:
+                if not filepath.is_file():
+                    continue
+                try:
+                    rel = filepath.relative_to(root)
+                except ValueError:
+                    continue
+                if is_ignored(str(rel), str(root)):
+                    continue
+                _read_file(filepath, str(rel))
+
+        else:
+            # Local file path
+            filepath = root / entry
+            if filepath.is_file():
+                _read_file(filepath, entry)
+            else:
+                logger.warning("Instruction file not found: %s", filepath)
+
+    return "\n\n".join(parts)
 
 
 @dataclass
@@ -61,6 +150,7 @@ class AgentConfig:
     """Loaded configuration from AGENTS.md, README.md, and .agents/ directory."""
     readme_md: str = ""
     agents_md: str = ""
+    rules_instructions: 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)
@@ -71,7 +161,7 @@ class AgentConfig:
 
     @property
     def has_instructions(self) -> bool:
-        return bool(self.agents_md) or bool(self.skills)
+        return bool(self.agents_md) or bool(self.skills) or bool(self.rules_instructions)
 
     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.
@@ -85,6 +175,8 @@ class AgentConfig:
             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 self.rules_instructions:
+            parts.append(self.rules_instructions)
         if active_skills:
             for name in active_skills:
                 if name in self.skills:
@@ -409,6 +501,10 @@ def load_config(cwd: str | None = None) -> AgentConfig:
                         config.model_aliases = data["model_aliases"]
                     if "plan_reviewer" in data:
                         config.plan_reviewer = bool(data["plan_reviewer"])
+                    # 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)]
+                        config.rules_instructions = _resolve_instructions(entries, root)
                     # Agent-level permission overrides from aru.json
                     if "agent" in data and isinstance(data["agent"], dict):
                         for agent_name, agent_data in data["agent"].items():

{aru_code-0.7.0 → aru_code-0.9.0}/aru/context.py

@@ -204,7 +204,7 @@ async def compact_conversation(
     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.runtime import get_ctx
     from aru.providers import create_model
 
     prompt = build_compaction_prompt(history, plan_task)
@@ -212,7 +212,7 @@ async def compact_conversation(
     try:
         from agno.agent import Agent
 
-        small_ref = _get_small_model_ref()
+        small_ref = get_ctx().small_model_ref
         compactor = Agent(
             name="Compactor",
             model=create_model(small_ref, max_tokens=2048),

{aru_code-0.7.0 → aru_code-0.9.0}/aru/permissions.py

@@ -19,15 +19,16 @@ from __future__ import annotations
 
 import fnmatch
 import os
-import threading
 from contextlib import contextmanager
 from dataclasses import dataclass, field
 from typing import Any, Generator, Literal
 
-from rich.console import Console, Group
+from rich.console import Group
 from rich.panel import Panel
 from rich.text import Text
 
+from aru.runtime import get_ctx
+
 PermissionAction = Literal["allow", "ask", "deny"]
 
 VALID_ACTIONS: set[str] = {"allow", "ask", "deny"}
@@ -96,62 +97,24 @@ for _prefix in SAFE_COMMAND_PREFIXES:
 
 
 # ---------------------------------------------------------------------------
-# Module-level state
+# Thin wrappers over RuntimeContext (preserve public API for callers)
 # ---------------------------------------------------------------------------
 
-_config: PermissionConfig = PermissionConfig()
-_session_allowed: set[tuple[str, str]] = set()  # (category, pattern) approved via "always"
-_skip_permissions: bool = False
-_permission_lock = threading.Lock()
-_live = None
-_display = None
-_console = Console()
-
-
-# ---------------------------------------------------------------------------
-# Setters
-# ---------------------------------------------------------------------------
+def set_config(config: PermissionConfig) -> None:
+    get_ctx().perm_config = config
 
-def set_config(config: PermissionConfig):
-    global _config
-    _config = config
 
-
-def set_skip_permissions(value: bool):
-    global _skip_permissions
-    _skip_permissions = value
+def set_skip_permissions(value: bool) -> None:
+    get_ctx().skip_permissions = value
 
 
 def get_skip_permissions() -> bool:
-    return _skip_permissions
-
-
-def set_live(live):
-    global _live
-    _live = live
-
+    return get_ctx().skip_permissions
 
-def set_display(display):
-    global _display
-    _display = display
 
-
-def set_console(console: Console):
-    global _console
-    _console = console
-
-
-def reset_session():
+def reset_session() -> None:
     """Reset session-level permission state (call between conversations)."""
-    _session_allowed.clear()
-
-
-# ---------------------------------------------------------------------------
-# Agent-level permission scoping
-# ---------------------------------------------------------------------------
-
-_config_stack: list[PermissionConfig] = []
-_session_stack: list[set[tuple[str, str]]] = []
+    get_ctx().session_allowed.clear()
 
 
 def merge_configs(base: PermissionConfig, overlay: PermissionConfig) -> PermissionConfig:
@@ -175,22 +138,22 @@ def permission_scope(overlay_raw: dict[str, Any] | None) -> Generator[None, None
     Each scope gets its own fresh "always" session memory, so agent approvals
     don't leak to the global scope or other agents.
     """
-    global _config, _session_allowed
     if not overlay_raw:
         yield
         return
 
-    _config_stack.append(_config)
-    _session_stack.append(_session_allowed)
-    _session_allowed = set()
+    ctx = get_ctx()
+    ctx.config_stack.append(ctx.perm_config)
+    ctx.session_stack.append(ctx.session_allowed)
+    ctx.session_allowed = set()
 
     overlay = parse_permission_config(overlay_raw)
-    _config = merge_configs(_config, overlay)
+    ctx.perm_config = merge_configs(ctx.perm_config, overlay)
     try:
         yield
     finally:
-        _config = _config_stack.pop()
-        _session_allowed = _session_stack.pop()
+        ctx.perm_config = ctx.config_stack.pop()
+        ctx.session_allowed = ctx.session_stack.pop()
 
 
 # ---------------------------------------------------------------------------
@@ -304,8 +267,9 @@ def _build_rules(category: str) -> list[PermissionRule]:
         rules.extend(_SENSITIVE_FILE_RULES)
 
     # Add user-configured rules
-    if category in _config.categories:
-        rules.extend(_config.categories[category])
+    ctx = get_ctx()
+    if category in ctx.perm_config.categories:
+        rules.extend(ctx.perm_config.categories[category])
 
     return rules
 
@@ -382,7 +346,7 @@ def _resolve_bash_compound(command: str) -> tuple[PermissionAction, str]:
 def _resolve_bash_single(command: str) -> tuple[PermissionAction, str]:
     """Resolve permission for a single (non-compound) bash command."""
     rules = _build_rules("bash")
-    result: PermissionAction = CATEGORY_DEFAULTS.get("bash", _config.default)
+    result: PermissionAction = CATEGORY_DEFAULTS.get("bash", get_ctx().perm_config.default)
     matched_pattern = "*"
 
     for rule in rules:
@@ -419,11 +383,12 @@ def resolve_permission(
     4. For others: walk rules (defaults + user config), last-match-wins
     5. Fallback: category default, then global default
     """
-    if _skip_permissions:
+    ctx = get_ctx()
+    if ctx.skip_permissions:
         return ("allow", "*")
 
     # Check session memory
-    for cat, pattern in _session_allowed:
+    for cat, pattern in ctx.session_allowed:
         if cat == category and _match_rule(pattern, subject):
             return ("allow", pattern)
 
@@ -433,7 +398,7 @@ def resolve_permission(
 
     # All other categories
     rules = _build_rules(category)
-    result: PermissionAction = CATEGORY_DEFAULTS.get(category, _config.default)
+    result: PermissionAction = CATEGORY_DEFAULTS.get(category, ctx.perm_config.default)
     matched_pattern = "*"
 
     for rule in rules:
@@ -465,7 +430,8 @@ def check_permission(
         return False
 
     # action == "ask" -> prompt user
-    with _permission_lock:
+    ctx = get_ctx()
+    with ctx.permission_lock:
         # Re-check after acquiring lock (another thread may have resolved it)
         action2, pattern2 = resolve_permission(category, subject)
         if action2 == "allow":
@@ -474,25 +440,25 @@ def check_permission(
             return False
 
         # Pause Live and flush already-streamed content
-        if _live:
-            _live.stop()
-        if _display:
-            _display.flush()
+        if ctx.live:
+            ctx.live.stop()
+        if ctx.display:
+            ctx.display.flush()
 
         title = f"{category}: {subject}" if subject else category
-        _console.print()
-        _console.print(Panel(
+        ctx.console.print()
+        ctx.console.print(Panel(
             display_details,
             title=f"[bold yellow]{title}[/bold yellow]",
             border_style="yellow",
             expand=False,
         ))
         try:
-            answer = _console.input(
+            answer = ctx.console.input(
                 "[bold yellow]Allow? (y)es once / (a)lways / (n)o:[/bold yellow] "
             ).strip().lower()
             if answer in ("a", "always", "all"):
-                _session_allowed.add((category, matched_pattern))
+                ctx.session_allowed.add((category, matched_pattern))
                 allowed = True
             else:
                 allowed = answer in ("y", "yes", "s", "sim")
@@ -500,8 +466,8 @@ def check_permission(
             allowed = False
 
         # Resume Live display
-        if _live:
-            _live.start()
-            _live._live_render._shape = None
+        if ctx.live:
+            ctx.live.start()
+            ctx.live._live_render._shape = None
 
         return allowed