hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/agent.py

@@ -0,0 +1,775 @@
+"""
+HyperClaw Agent — Assistant with Tool Execution
+Full computer control using Anthropic tool-use API.
+"""
+
+import os
+import asyncio
+import subprocess
+import glob as globlib
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import AsyncIterator, Optional, Any
+
+import anthropic
+from hyperclaw.cost_guard import max_output
+from dotenv import load_dotenv
+
+load_dotenv()
+
+HYPERCLAW_ROOT = Path(os.environ.get("HYPERCLAW_ROOT", str(Path.home() / ".hyperclaw")))
+WORKSPACE_PATH = HYPERCLAW_ROOT / "workspace"
+MODEL = "claude-sonnet-4-6"
+MAX_TOKENS = 16000
+
+# Context files to load
+CONTEXT_FILES = [
+    "SOUL.md",
+    "IDENTITY.md",
+    "USER.md",
+    "MEMORY.md",
+    "memory/instincts.md",
+    "memory/core-episodes.md",
+]
+
+# Tool definitions for Claude API
+TOOLS = [
+    {
+        "name": "bash",
+        "description": "Execute a bash command on the local system. Use for system operations, git, file management, etc.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "The bash command to execute"
+                },
+                "timeout": {
+                    "type": "integer",
+                    "description": "Timeout in seconds (default 120)",
+                    "default": 120
+                }
+            },
+            "required": ["command"]
+        }
+    },
+    {
+        "name": "read_file",
+        "description": "Read the contents of a file. Use absolute paths.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Absolute path to the file"
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Maximum lines to read (default all)"
+                }
+            },
+            "required": ["path"]
+        }
+    },
+    {
+        "name": "write_file",
+        "description": "Write content to a file. Creates parent directories if needed.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Absolute path to the file"
+                },
+                "content": {
+                    "type": "string",
+                    "description": "Content to write"
+                }
+            },
+            "required": ["path", "content"]
+        }
+    },
+    {
+        "name": "edit_file",
+        "description": "Edit a file by replacing old_string with new_string.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Absolute path to the file"
+                },
+                "old_string": {
+                    "type": "string",
+                    "description": "The text to find and replace"
+                },
+                "new_string": {
+                    "type": "string",
+                    "description": "The replacement text"
+                }
+            },
+            "required": ["path", "old_string", "new_string"]
+        }
+    },
+    {
+        "name": "glob",
+        "description": "Find files matching a glob pattern.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "pattern": {
+                    "type": "string",
+                    "description": "Glob pattern (e.g., '**/*.py', '*.md')"
+                },
+                "path": {
+                    "type": "string",
+                    "description": "Base directory (default: home)",
+                    "default": str(Path.home())
+                }
+            },
+            "required": ["pattern"]
+        }
+    },
+    {
+        "name": "grep",
+        "description": "Search for a pattern in files using ripgrep.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "pattern": {
+                    "type": "string",
+                    "description": "Regex pattern to search for"
+                },
+                "path": {
+                    "type": "string",
+                    "description": "Directory or file to search in",
+                    "default": str(Path.home())
+                },
+                "file_pattern": {
+                    "type": "string",
+                    "description": "File glob to filter (e.g., '*.py')"
+                }
+            },
+            "required": ["pattern"]
+        }
+    },
+    {
+        "name": "list_directory",
+        "description": "List contents of a directory.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Directory path to list"
+                }
+            },
+            "required": ["path"]
+        }
+    }
+]
+
+
+def execute_tool(name: str, inputs: dict) -> str:
+    """Execute a tool and return the result."""
+    if inputs is None:
+        inputs = {}
+    try:
+        if name == "bash":
+            cmd = inputs.get("command")
+            if not cmd:
+                return "Error: bash requires 'command' parameter"
+            # Service recovery (bench 17.4/17.5): this loop has no approval
+            # channel, so no service is ever started, stopped or killed here.
+            from hyperclaw.tools.service_guard import check_command
+            svc = check_command(cmd)
+            if svc is not None:
+                return (f"Error: not run. Service and process control needs the owner's "
+                        f"approval in the HyperAgents terminal ({svc.reason}).")
+            return _exec_bash(cmd, inputs.get("timeout", 120))
+        elif name == "read_file":
+            path = inputs.get("path")
+            if not path:
+                return "Error: read_file requires 'path' parameter"
+            return _exec_read_file(path, inputs.get("limit"))
+        elif name == "write_file":
+            path = inputs.get("path")
+            content = inputs.get("content")
+            if not path or content is None:
+                return "Error: write_file requires 'path' and 'content' parameters"
+            return _exec_write_file(path, content)
+        elif name == "edit_file":
+            path = inputs.get("path")
+            old = inputs.get("old_string")
+            new = inputs.get("new_string")
+            if not all([path, old is not None, new is not None]):
+                return "Error: edit_file requires 'path', 'old_string', and 'new_string' parameters"
+            return _exec_edit_file(path, old, new)
+        elif name == "glob":
+            pattern = inputs.get("pattern")
+            if not pattern:
+                return "Error: glob requires 'pattern' parameter"
+            return _exec_glob(pattern, inputs.get("path", str(Path.home())))
+        elif name == "grep":
+            pattern = inputs.get("pattern")
+            if not pattern:
+                return "Error: grep requires 'pattern' parameter"
+            return _exec_grep(pattern, inputs.get("path", str(Path.home())), inputs.get("file_pattern"))
+        elif name == "list_directory":
+            path = inputs.get("path")
+            if not path:
+                return "Error: list_directory requires 'path' parameter"
+            return _exec_list_dir(path)
+        else:
+            return f"Unknown tool: {name}"
+    except Exception as e:
+        return f"Tool error ({name}): {e}"
+
+
+def _exec_bash(command: str, timeout: int = 120) -> str:
+    """Execute bash command."""
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=str(Path.home())
+        )
+        output = result.stdout
+        if result.stderr:
+            output += f"\nSTDERR:\n{result.stderr}"
+        if result.returncode != 0:
+            output += f"\n[Exit code: {result.returncode}]"
+        return output.strip() or "(no output)"
+    except subprocess.TimeoutExpired:
+        return f"Command timed out after {timeout}s"
+    except Exception as e:
+        return f"Bash error: {e}"
+
+
+def _exec_read_file(path: str, limit: Optional[int] = None) -> str:
+    """Read file contents."""
+    try:
+        p = Path(path).expanduser()
+        if not p.exists():
+            return f"File not found: {path}"
+        content = p.read_text(encoding="utf-8", errors="replace")
+        lines = content.splitlines()
+        if limit:
+            lines = lines[:limit]
+        # Add line numbers
+        numbered = [f"{i+1:4d}  {line}" for i, line in enumerate(lines)]
+        return "\n".join(numbered)
+    except Exception as e:
+        return f"Read error: {e}"
+
+
+def _exec_write_file(path: str, content: str) -> str:
+    """Write content to file."""
+    try:
+        p = Path(path).expanduser()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+        return f"Wrote {len(content)} bytes to {path}"
+    except Exception as e:
+        return f"Write error: {e}"
+
+
+def _exec_edit_file(path: str, old_string: str, new_string: str) -> str:
+    """Edit file by replacing string."""
+    try:
+        p = Path(path).expanduser()
+        if not p.exists():
+            return f"File not found: {path}"
+        content = p.read_text(encoding="utf-8")
+        if old_string not in content:
+            return f"String not found in file: {old_string[:50]}..."
+        count = content.count(old_string)
+        if count > 1:
+            return f"String appears {count} times — be more specific"
+        new_content = content.replace(old_string, new_string, 1)
+        p.write_text(new_content, encoding="utf-8")
+        return f"Replaced in {path}"
+    except Exception as e:
+        return f"Edit error: {e}"
+
+
+def _exec_glob(pattern: str, base_path: str) -> str:
+    """Find files matching glob pattern."""
+    try:
+        p = Path(base_path).expanduser()
+        matches = list(p.glob(pattern))[:100]  # Limit results
+        if not matches:
+            return "No matches found"
+        return "\n".join(str(m) for m in sorted(matches))
+    except Exception as e:
+        return f"Glob error: {e}"
+
+
+def _exec_grep(pattern: str, path: str, file_pattern: Optional[str] = None) -> str:
+    """Search with ripgrep."""
+    try:
+        cmd = ["rg", "-n", "--max-count=50", pattern, path]
+        if file_pattern:
+            cmd.extend(["-g", file_pattern])
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+        output = result.stdout.strip()
+        return output if output else "No matches found"
+    except FileNotFoundError:
+        # Fallback to grep
+        cmd = f"grep -rn '{pattern}' {path} | head -50"
+        result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+        return result.stdout.strip() or "No matches found"
+    except Exception as e:
+        return f"Grep error: {e}"
+
+
+def _exec_list_dir(path: str) -> str:
+    """List directory contents."""
+    try:
+        p = Path(path).expanduser()
+        if not p.exists():
+            return f"Directory not found: {path}"
+        if not p.is_dir():
+            return f"Not a directory: {path}"
+        items = sorted(p.iterdir())
+        lines = []
+        for item in items[:100]:
+            prefix = "d " if item.is_dir() else "f "
+            lines.append(f"{prefix} {item.name}")
+        return "\n".join(lines) if lines else "(empty directory)"
+    except Exception as e:
+        return f"List error: {e}"
+
+
+class HyperClawAgent:
+    """Assistant agent with full tool execution."""
+
+    def __init__(self):
+        from hyperclaw.cost_guard import guard_client
+        self.client = guard_client(
+            anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY", "")), "anthropic")
+        self.system_prompt = self._load_system_prompt()
+        self.history: list[dict] = []
+
+    def _tools_allowed(self) -> bool:
+        """Tools only with a Hyper-signed QUALIFIED record (spec §11)."""
+        try:
+            from hyperclaw.qualification import is_qualified
+            return is_qualified("anthropic", MODEL)
+        except Exception:
+            return False
+
+    def _load_system_prompt(self) -> str:
+        """hyperclaw.prompt_assembly order: truth rules + access first, then
+        identity and persona; workspace files are fenced as DATA (bench 1.6)."""
+        from hyperclaw.chat_scope import OWNER
+        from hyperclaw.prompt_assembly import assemble, identity_block, persona_for
+        from hyperclaw.truth_guard import TRUTH_RULES, access_manifest
+        mode = "tools" if self._tools_allowed() else "chat_only"
+        surface = "\n".join([
+            "## How to work",
+            "- Concise when needed, thorough when it matters. No filler words.",
+            "- Never exfiltrate private data.",
+            "- When in doubt, ask before acting externally.",
+            "",
+            f"Current date: {datetime.now().strftime('%Y-%m-%d %H:%M')}",
+        ])
+        context = []
+        for filename in CONTEXT_FILES:
+            filepath = WORKSPACE_PATH / filename
+            if filepath.exists():
+                try:
+                    context.append((filename, filepath.read_text(encoding="utf-8")))
+                except Exception:
+                    pass
+        today = datetime.now().strftime("%Y-%m-%d")
+        daily_log = HYPERCLAW_ROOT / "memory" / f"{today}.md"
+        if daily_log.exists():
+            try:
+                context.append((f"today's log {today}", daily_log.read_text(encoding="utf-8")))
+            except Exception:
+                pass
+        return assemble(truth_rules=TRUTH_RULES,
+                        access=access_manifest(mode, "anthropic", MODEL),
+                        identity=identity_block("Assistant", "", OWNER, model=MODEL),
+                        scope=OWNER, surface_instructions=surface,
+                        persona=persona_for(OWNER), context=context)
+
+    def reload_context(self) -> None:
+        """Hot-reload context."""
+        self.system_prompt = self._load_system_prompt()
+
+    async def chat(self, message: str) -> AsyncIterator[str]:
+        """
+        Process a message with tool execution.
+        Yields text chunks as they come, executes tools as needed.
+        """
+        self.history.append({"role": "user", "content": message})
+
+        # Trim history
+        if len(self.history) > 120:
+            self.history = self.history[-120:]
+
+        messages = list(self.history)
+
+        max_iterations = 100  # Assistant: raised from 20 — complex multi-step tasks require depth
+        iteration = 0
+        consecutive_errors = 0
+
+        tools_on = self._tools_allowed()   # no record -> chat-only, nothing runs
+        while iteration < max_iterations:
+            iteration += 1
+
+            try:
+                response = self.client.messages.create(
+                    model=MODEL,
+                    max_tokens=max_output("agent", "anthropic", MODEL, requested=MAX_TOKENS),
+                    system=self.system_prompt,
+                    tools=ADVERTISED_TOOLS if tools_on else anthropic.NOT_GIVEN,
+                    messages=messages,
+                )
+            except anthropic.APIError as e:
+                yield f"[API Error: {e}]"
+                return
+            except Exception as e:
+                yield f"[Error: {e}]"
+                return
+
+            # Process response content
+            assistant_content = []
+            has_tool_use = False
+
+            for block in response.content:
+                if block.type == "text":
+                    yield block.text
+                    assistant_content.append({"type": "text", "text": block.text})
+                elif block.type == "tool_use" and not tools_on:
+                    # Tools are off (no signed record): a tool_use block from
+                    # the model never runs (fail closed).
+                    yield (f"\n[HyperClaw: the model asked for tool '{block.name}', but tools "
+                           f"are off on this installation; it did NOT run.]\n")
+                elif block.type == "tool_use":
+                    has_tool_use = True
+                    tool_name = block.name
+                    tool_input = block.input
+                    tool_id = block.id
+
+                    yield f"\n[Executing: {tool_name}]\n"
+
+                    # Execute the tool
+                    result = execute_tool(tool_name, tool_input)
+
+                    # Track consecutive errors to break out of loops
+                    if result.startswith("Error:") or result.startswith("Tool error"):
+                        consecutive_errors += 1
+                        if consecutive_errors >= 5:
+                            yield f"\n[Stopping: too many consecutive tool errors]\n"
+                            return
+                    else:
+                        consecutive_errors = 0
+
+                    # Show truncated result
+                    if len(result) > 8000:
+                        yield f"{result[:8000]}...\n[{len(result)} chars total — truncated]\n"
+                    else:
+                        yield f"{result}\n"
+
+                    assistant_content.append({
+                        "type": "tool_use",
+                        "id": tool_id,
+                        "name": tool_name,
+                        "input": tool_input
+                    })
+
+                    # Add tool result to continue conversation
+                    messages.append({"role": "assistant", "content": assistant_content})
+                    messages.append({
+                        "role": "user",
+                        "content": [{
+                            "type": "tool_result",
+                            "tool_use_id": tool_id,
+                            "content": result
+                        }]
+                    })
+                    assistant_content = []
+
+            # If no tool use, we're done
+            if not has_tool_use:
+                # Save final assistant message to history
+                if assistant_content:
+                    text_parts = [b["text"] for b in assistant_content if b["type"] == "text"]
+                    if text_parts:
+                        self.history.append({"role": "assistant", "content": " ".join(text_parts)})
+                break
+
+            # Check stop reason
+            if response.stop_reason == "end_turn":
+                break
+
+        if iteration >= max_iterations:
+            yield "\n[Stopped: max tool iterations reached]\n"
+
+
+# Singleton
+_agent: Optional[HyperClawAgent] = None
+
+
+def get_agent() -> HyperClawAgent:
+    """Get or create the agent singleton."""
+    global _agent
+    if _agent is None:
+        _agent = HyperClawAgent()
+    return _agent
+
+
+# ─────────────────────────────────────────────
+# INTEGRATION TOOLS (Gmail, Calendar, iMessage, Supabase)
+# ─────────────────────────────────────────────
+
+INTEGRATION_TOOLS = [
+    {
+        "name": "gmail_inbox",
+        "description": "List Gmail inbox messages. Returns message IDs and snippets.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "max_results": {"type": "integer", "description": "Max messages to return (default 20)", "default": 20},
+                "query": {"type": "string", "description": "Gmail search query (default: 'in:inbox is:unread')", "default": "in:inbox is:unread"}
+            }
+        }
+    },
+    {
+        "name": "gmail_read",
+        "description": "Read the full text of a Gmail message by ID.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "message_id": {"type": "string", "description": "Gmail message ID"}
+            },
+            "required": ["message_id"]
+        }
+    },
+    {
+        "name": "gmail_send",
+        "description": "Send an email via Gmail. Always CCs the configured CC address per policy.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "to": {"type": "string", "description": "Recipient email address"},
+                "subject": {"type": "string", "description": "Email subject"},
+                "body": {"type": "string", "description": "Email body (plain text)"},
+                "cc": {"type": "string", "description": "Additional CC (optional)"},
+                "reply_to_id": {"type": "string", "description": "Thread ID to reply to (optional)"}
+            },
+            "required": ["to", "subject", "body"]
+        }
+    },
+    {
+        "name": "calendar_events",
+        "description": "Get upcoming Google Calendar events.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "days_ahead": {"type": "integer", "description": "How many days ahead to look (default 7)", "default": 7}
+            }
+        }
+    },
+    {
+        "name": "calendar_create",
+        "description": "Create a Google Calendar event.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "title": {"type": "string", "description": "Event title"},
+                "start_iso": {"type": "string", "description": "Start time in ISO format (e.g. 2026-03-28T14:00:00-07:00)"},
+                "end_iso": {"type": "string", "description": "End time in ISO format"},
+                "description": {"type": "string", "description": "Event description (optional)"},
+                "attendees": {"type": "array", "items": {"type": "string"}, "description": "List of attendee emails (optional)"}
+            },
+            "required": ["title", "start_iso", "end_iso"]
+        }
+    },
+    {
+        "name": "imessage_send",
+        "description": "Send an iMessage or SMS to a phone number or Apple ID email.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "recipient": {"type": "string", "description": "Phone number (+1XXXXXXXXXX) or Apple ID email"},
+                "message": {"type": "string", "description": "Message content"}
+            },
+            "required": ["recipient", "message"]
+        }
+    },
+    {
+        "name": "imessage_read",
+        "description": "Read recent iMessages from the Messages app database.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "contact": {"type": "string", "description": "Filter by contact phone/email (optional)"},
+                "limit": {"type": "integer", "description": "Number of messages to retrieve (default 10)", "default": 10}
+            }
+        }
+    },
+    {
+        "name": "supabase_query",
+        "description": "Query a Supabase table. Available tables: episodic_memories, hyperclaw_episodes, knowledge_nodes, kg_entities, kg_facts, hyperstates, swarm_messages, audit_log",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "table": {"type": "string", "description": "Table name"},
+                "limit": {"type": "integer", "description": "Max rows (default 50)", "default": 50}
+            },
+            "required": ["table"]
+        }
+    },
+    {
+        "name": "supabase_store_memory",
+        "description": "Store a memory/note in Supabase episodic_memories for long-term persistence.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "content": {"type": "string", "description": "Memory content to store"},
+                "memory_type": {"type": "string", "description": "Type: episodic, semantic, procedural (default: episodic)", "default": "episodic"},
+                "tags": {"type": "array", "items": {"type": "string"}, "description": "Tags for retrieval"},
+                "importance": {"type": "number", "description": "Importance 0.0-1.0 (default 0.5)", "default": 0.5}
+            },
+            "required": ["content"]
+        }
+    },
+    {
+        "name": "integration_status",
+        "description": "Check the status of all Assistant integrations (Gmail, Calendar, iMessage, Supabase, Telegram, WhatsApp).",
+        "input_schema": {
+            "type": "object",
+            "properties": {}
+        }
+    }
+]
+
+# Merge into main TOOLS list
+TOOLS = TOOLS + INTEGRATION_TOOLS
+
+
+def _exec_integration_tool(name: str, inputs: dict) -> str:
+    """Execute an integration tool."""
+    try:
+        from hyperclaw.integrations_layer import (
+            gmail_list_inbox, gmail_read_message_text, gmail_send,
+            calendar_get_events, calendar_create_event,
+            imessage_send, imessage_get_recent,
+            supabase_query, supabase_store_memory,
+            get_integration_status
+        )
+        
+        if name == "gmail_inbox":
+            result = gmail_list_inbox(
+                inputs.get('max_results', 20),
+                inputs.get('query', 'in:inbox is:unread')
+            )
+            msgs = result.get('messages', [])
+            return f"Found {len(msgs)} messages.\nMessage IDs: {[m['id'] for m in msgs[:10]]}"
+        
+        elif name == "gmail_read":
+            return gmail_read_message_text(inputs['message_id'])
+        
+        elif name == "gmail_send":
+            result = gmail_send(
+                inputs['to'], inputs['subject'], inputs['body'],
+                inputs.get('cc', ''), inputs.get('reply_to_id', '')
+            )
+            return json.dumps(result)
+        
+        elif name == "calendar_events":
+            events = calendar_get_events(inputs.get('days_ahead', 7))
+            if not events:
+                return "No upcoming events."
+            lines = [f"- {e['summary']} @ {e['start']}" + (f" | {e['location']}" if e.get('location') else '') for e in events]
+            return "\n".join(lines)
+        
+        elif name == "calendar_create":
+            result = calendar_create_event(
+                inputs['title'], inputs['start_iso'], inputs['end_iso'],
+                inputs.get('description', ''), inputs.get('attendees', [])
+            )
+            return json.dumps(result)
+        
+        elif name == "imessage_send":
+            result = imessage_send(inputs['recipient'], inputs['message'])
+            return json.dumps(result)
+        
+        elif name == "imessage_read":
+            messages = imessage_get_recent(inputs.get('contact', ''), inputs.get('limit', 10))
+            if not messages:
+                return "No messages found."
+            lines = []
+            for m in messages:
+                if 'error' in m:
+                    return f"Error: {m['error']}"
+                direction = "→" if m['from_me'] else "←"
+                lines.append(f"[{m['time']}] {direction} {m['handle']}: {m['text'][:100]}")
+            return "\n".join(lines)
+        
+        elif name == "supabase_query":
+            rows = supabase_query(inputs['table'], inputs.get('limit', 50))
+            return json.dumps(rows[:5], indent=2, default=str)
+        
+        elif name == "supabase_store_memory":
+            result = supabase_store_memory(
+                inputs['content'],
+                inputs.get('memory_type', 'episodic'),
+                inputs.get('tags', []),
+                inputs.get('importance', 0.5)
+            )
+            return json.dumps(result)
+        
+        elif name == "integration_status":
+            status = get_integration_status()
+            return "\n".join(f"{k}: {v}" for k, v in status.items())
+        
+        return f"Unknown integration tool: {name}"
+    except Exception as e:
+        return f"Integration error ({name}): {e}"
+
+
+# Patch execute_tool to handle integration tools
+_original_execute_tool = execute_tool
+
+# Sends and external writes from this loop. It has no Send / Edit / Cancel
+# step of its own, so they never run here (fail closed): the owner sends from
+# the HyperAgents terminal or chat, where the approval layer shows the exact
+# content first.
+APPROVAL_REQUIRED = frozenset({"gmail_send", "calendar_create", "imessage_send",
+                               "supabase_store_memory"})
+
+# The only tools this loop runs: read-only ones. Shell commands and file
+# writes/edits need the owner's Send / Edit / Cancel on the exact command or
+# content, which this loop does not offer, so they are refused here (tier
+# "never" in this loop) and not offered to the model. The HyperAgents
+# terminal runs them through the approval layer instead.
+READ_ONLY_TOOLS = frozenset({"read_file", "glob", "grep", "list_directory", "gmail_inbox",
+                             "gmail_read", "calendar_events", "imessage_read", "supabase_query",
+                             "integration_status"})
+ADVERTISED_TOOLS = [t for t in TOOLS if t["name"] in READ_ONLY_TOOLS]
+
+
+def execute_tool(name: str, inputs: dict) -> str:
+    """Execute a tool — handles both system and integration tools."""
+    if name in APPROVAL_REQUIRED:
+        return (f"Error: {name} was NOT run. Sending or writing to an outside service needs "
+                f"the owner's approval (Send / Edit / Cancel), which this loop does not "
+                f"offer. Tell the user to do it from the HyperAgents terminal or chat.")
+    if name not in READ_ONLY_TOOLS:
+        return (f"Error: not run. {name} runs a command or changes something, which needs the "
+                f"owner's approval (Send / Edit / Cancel) on the exact command or content; "
+                f"this loop does not offer that. Tell the user to do it from the HyperAgents "
+                f"terminal.")
+    integration_tools = {t['name'] for t in INTEGRATION_TOOLS}
+    if name in integration_tools:
+        return _exec_integration_tool(name, inputs)
+    return _original_execute_tool(name, inputs)