hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/tui_bridge.py

@@ -0,0 +1,938 @@
+#!/usr/bin/env python3
+"""
+TUI Bridge — Expose TUI's full capabilities to external systems (Telegram, API, etc.)
+
+This module wraps the TUI's chat function for programmatic access with:
+- Async interface for non-blocking execution
+- Output capture (text, tool results, screenshots)
+- Per-session context isolation
+- Structured response format
+"""
+
+import asyncio
+import json
+import sys
+import io
+import re
+import os
+import anthropic
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+from datetime import datetime
+from concurrent.futures import ThreadPoolExecutor
+import threading
+
+from hyperclaw.chat_scope import (GUEST, GUEST_RULES, GUEST_SAFE_TOOLS, OWNER,
+                                  guest_tools, scope_for)
+from hyperclaw.chat_scope import normalize as normalize_scope
+from hyperclaw.notices import failure_notice
+from hyperclaw.tools.surfaces import NEVER_FROM_CHAT, tools_for_surface
+from hyperclaw.tools.envelope import REASON_SURFACE, Status, make as make_envelope
+from hyperclaw.tools.registry import ToolTimeout
+from hyperclaw.tools.guard import TurnGuard, chat_tool_call_cap
+
+# This bridge serves remote chats (Telegram, iMessage). Shell/code execution
+# and desktop control are not offered here at all (spec rule 4, §6).
+SURFACE = "bridge"
+
+# Constants
+HYPERCLAW_ROOT = Path(os.environ.get("HYPERCLAW_ROOT", Path.home() / ".hyperclaw"))
+SCREENSHOTS_DIR = HYPERCLAW_ROOT / "screenshots"
+SCREENSHOTS_DIR.mkdir(parents=True, exist_ok=True)
+
+# Thread pool for running sync TUI in async context
+_executor = ThreadPoolExecutor(max_workers=3, thread_name_prefix="tui_bridge")
+
+# Per-session state (chat_id -> history)
+_session_histories: Dict[int, List[dict]] = {}
+_session_lock = threading.Lock()
+
+
+class TUIBridge:
+    """
+    Bridge for external systems to access TUI's full 80+ tool capabilities.
+
+    Usage:
+        bridge = TUIBridge()
+        result = await bridge.execute("list files in Downloads", chat_id=12345)
+        print(result['text'])
+        for screenshot in result.get('screenshots', []):
+            send_photo(screenshot)
+    """
+
+    def __init__(self):
+        self.api_key = os.environ.get("ANTHROPIC_API_KEY")
+        self.model = os.environ.get("HYPERCLAW_MODEL", "claude-fable-5")
+        self._load_system_prompt()
+        self._load_tools()
+
+    def _usable(self) -> str:
+        """"" when this bridge can serve a turn, else why not. The bridge
+        talks to Anthropic only; a Hyper-deployed install is V2-only, so the
+        bridge refuses there rather than use a third-party provider."""
+        from hyperclaw.deployment import is_hyper
+        if is_hyper():
+            return "hyper_deployed"
+        if not getattr(self, "api_key", None):
+            return "not_configured"
+        return ""
+
+    def _tools_allowed(self) -> bool:
+        """Tools only for a qualified model (spec §11), never when unusable."""
+        if self._usable():
+            return False
+        from hyperclaw.qualification import is_qualified
+        return is_qualified("anthropic", getattr(self, "model", ""))
+
+    def _identity_names(self):
+        from hyperclaw.userconfig import load_config
+        cfg = load_config()
+        ai = (cfg.get("ai_name") or os.environ.get("ASSISTANT_NAME") or "Assistant")
+        owner = (cfg.get("user_name") or os.environ.get("OWNER_NAME") or "")
+        return ai, owner
+
+    def _load_system_prompt(self):
+        """Load system prompts from workspace files (owner) and the fenced
+        guest prompt (no owner context at all)."""
+        self.system_prompt = self._build_system_prompt()
+        self.guest_system_prompt = self._build_guest_system_prompt()
+
+    def _access(self, scope: str = GUEST) -> str:
+        from hyperclaw.truth_guard import access_manifest
+        mode = "tools" if self._tools_allowed() else "chat_only"
+        return access_manifest(mode, "anthropic", getattr(self, "model", ""), surface="bridge",
+                               scope=scope)
+
+    def _owner_system_with_memories(self, memory_context: str) -> str:
+        """Owner system prompt + recalled memories, fenced as DATA after the
+        truth rules (benchmark 1.6: recalled text never becomes instructions)."""
+        if not memory_context or not memory_context.strip():
+            return self.system_prompt
+        from hyperclaw.prompt_assembly import fence_data
+        return self.system_prompt + "\n\n" + fence_data(memory_context, "relevant memories")
+
+    def _build_guest_system_prompt(self) -> str:
+        """System prompt for a non-owner chat: no persona, no owner name,
+        no MEMORY/USER/IDENTITY files, no handoff (spec §6 guest fence)."""
+        from hyperclaw.prompt_assembly import assemble, identity_block
+        from hyperclaw.truth_guard import TRUTH_RULES
+        ai_name, _ = self._identity_names()
+        return assemble(
+            truth_rules=TRUTH_RULES, access=self._access(GUEST),
+            identity=identity_block(ai_name, "", GUEST), scope=GUEST,
+            surface_instructions=("Context:\nThis request is coming via a chat channel. "
+                                  "Keep responses under 2000 characters."))
+
+    def _build_system_prompt(self) -> str:
+        """Build the full (OWNER) system prompt (hyperclaw.prompt_assembly
+        order: truth rules and access first, persona and memory after)."""
+        from hyperclaw.prompt_assembly import assemble, identity_block, persona_for
+        from hyperclaw.truth_guard import TRUTH_RULES
+        ai_name, owner_name = self._identity_names()
+
+        # Legacy persona file (PERSONA_FILE or workspace/persona.md): kept as
+        # the owner's standing instructions, below the truth rules.
+        standing = ""
+        persona_path = os.environ.get("PERSONA_FILE", "") or str(HYPERCLAW_ROOT / "workspace" / "persona.md")
+        try:
+            p = Path(persona_path)
+            if p.exists():
+                standing = p.read_text()[:4000]
+        except Exception:
+            standing = ""
+
+        surface = """
+You have FULL ACCESS to the computer via tools. Execute requests directly - don't ask permission for routine tasks.
+
+CRITICAL EXECUTION RULES:
+- DO IT NOW. Never say "I will" or "I can" or "I'll" - just DO IT.
+- TOOLS FIRST. Call the tool, THEN report what you did. Action before words.
+- NO DEFERRING. There is no "later". If asked to do something, do it THIS response.
+- FOLLOW THROUGH. If you say something will happen, make it happen immediately.
+- NO PROCRASTINATION. Every request gets executed, not acknowledged.
+
+BAD: "I can create that presentation for you"
+GOOD: [calls create_presentation tool] "Done. Created deck at ~/Desktop/presentation.pptx"
+
+BAD: "I'll send that email"
+GOOD: [calls gmail_send tool] "Sent to user@example.com"
+
+BAD: "Let me check your calendar" [doesn't call tool]
+GOOD: [calls calendar_read tool] "You have 3 meetings tomorrow..."
+
+Capabilities:
+- File read/write/edit
+- Email (Gmail) read/send/search
+- Calendar management
+- Create presentations, documents, spreadsheets
+- Vision on images you are given
+- Web browsing and search
+- iMessage and Telegram
+- NOT available from chat: shell commands, running code, AppleScript, screenshots,
+  or controlling apps, mouse or keyboard on the computer. If asked, say these only
+  work in the HyperClaw terminal on the computer itself.
+- FILE DELIVERY: send_file delivers any file (PDF, deck, doc, sheet, image) INTO this
+  conversation (via='here'), or via telegram/imessage/email/open. When you create a
+  document or image and the user is on Telegram/iMessage, ALWAYS send_file it back
+  to them here - never just report a local path they can't open from their phone.
+- EMAIL: full Gmail suite - email_send (supports body_html + attachments), email_forward,
+  email_draft (creates a Gmail draft for review instead of sending), email_mark
+  (read/archive/star), email_search, email_thread, email_download_attachment.
+
+Communication Style:
+- Execute first, report after. Always.
+- Write like a human texting, not a robot.
+- Concise responses. No filler.
+- No corporate phrases ("I'd be happy to help", "Great question!")
+
+Context:
+This request is coming via a chat channel. Keep responses under 2000 characters. Include key info, skip verbose explanations.
+"""
+        context = []
+        workspace = HYPERCLAW_ROOT / "workspace"
+        for filename in ["MEMORY.md", "USER.md", "IDENTITY.md"]:
+            filepath = workspace / filename
+            if filepath.exists():
+                try:
+                    content = filepath.read_text()[:3000]  # Limit size
+                    context.append(f"## {filename}\n{content}")
+                except:
+                    pass
+
+        return assemble(truth_rules=TRUTH_RULES, access=self._access(OWNER),
+                        identity=identity_block(ai_name, owner_name, OWNER,
+                                                model=getattr(self, "model", "")),
+                        scope=OWNER, surface_instructions=surface,
+                        persona=persona_for(OWNER), standing=standing, context=context)
+
+    # Tools allowed to run long (doc/media generation, research); everything else 120s.
+    _TOOL_TIMEOUTS = {
+        "create_document": 300, "create_presentation": 300,
+        "create_spreadsheet": 300, "zimage_generate": 300, "deep_research": 600,
+    }
+    _DEFAULT_TOOL_TIMEOUT = int(os.environ.get("HYPERCLAW_TOOL_TIMEOUT", "120"))
+
+    def _load_tools(self):
+        """Load tool definitions from TUI."""
+        # Import tools from TUI module
+        try:
+            from . import tui
+            tools = tui.TOOLS
+            self._raw_execute_tool = tui.execute_tool
+            self.registry = tui.REGISTRY
+        except ImportError:
+            # Fallback: define essential tools inline
+            tools = self._get_essential_tools()
+            self._raw_execute_tool = self._execute_tool_fallback
+            self.registry = None
+        # Removed, not gated: never_from_chat tools are not in this surface's list.
+        self.tools = tools_for_surface(tools, SURFACE)
+        if not self._tools_allowed():
+            self.tools = []   # spec §11: chat-only until the model is qualified
+        self.execute_tool = self._execute_tool_with_timeout
+
+    def _run_with_timeout(self, spec, args):
+        """Registry `run` hook: the tool runs in the worker pool under its time
+        budget; a timeout raises ToolTimeout, which the registry turns into
+        `uncertain` for side-effecting tools (never retried) and `failed` for
+        reads."""
+        import concurrent.futures as _cf
+        import contextvars as _cv
+        timeout = self._TOOL_TIMEOUTS.get(spec.name, self._DEFAULT_TOOL_TIMEOUT)
+        # The tool thread runs in this turn's context, so a model call a tool
+        # makes (sub-agent, research) is charged to this task's cost cap.
+        future = self._tool_executor.submit(_cv.copy_context().run, self._raw_execute_tool,
+                                            spec.name, args)
+        try:
+            return future.result(timeout=timeout)
+        except _cf.TimeoutError:
+            import logging
+            logging.getLogger("tui_bridge").error(
+                f"Tool '{spec.name}' exceeded {timeout}s — abandoning worker thread")
+            raise ToolTimeout(f"after {timeout}s")
+
+    def dispatch_tool(self, name, input_data, scope=GUEST, guard=None):
+        """Run one model tool call for this surface and scope; always returns
+        the structured envelope (tool standard S2). `guard` is the turn's
+        TurnGuard (wave 2: effect ledger, retry budgets, chat call cap)."""
+        registry = getattr(self, "registry", None)
+        if registry is not None:
+            return registry.dispatch(name, input_data, surface=SURFACE, scope=scope,
+                                     run=self._run_with_timeout, guard=guard)
+        # Fallback (no TUI registry importable): legacy string, classified generically.
+        from hyperclaw.tools.classify import classify
+        import types as _types
+        try:
+            raw = self.execute_tool(name, input_data)
+        except Exception as e:
+            return make_envelope(Status.FAILED, f"Error: tool {name} failed: {e}")
+        return classify(_types.SimpleNamespace(name=name, effect="system"), raw, input_data)
+
+    # One shared single-slot pool per bridge would serialize tools; use a small pool.
+    _tool_executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="tui_tool")
+
+    def _execute_tool_with_timeout(self, name, input_data):
+        """Run a tool with a hard timeout; a hung tool becomes an error result,
+        never a hung conversation. (Python threads can't be killed — the orphaned
+        worker is logged and abandoned; subprocess-backed tools should also pass
+        their own subprocess timeouts.)"""
+        import concurrent.futures as _cf
+        if name in NEVER_FROM_CHAT:  # defence in depth: never dispatched from chat
+            return (f"Error: tool '{name}' is not available from chat. It was NOT run. "
+                    f"Tell the user it only works in the HyperClaw terminal on the computer.")
+        timeout = self._TOOL_TIMEOUTS.get(name, self._DEFAULT_TOOL_TIMEOUT)
+        future = self._tool_executor.submit(self._raw_execute_tool, name, input_data)
+        try:
+            return future.result(timeout=timeout)
+        except _cf.TimeoutError:
+            import logging
+            logging.getLogger("tui_bridge").error(
+                f"Tool '{name}' exceeded {timeout}s — abandoning worker thread")
+            return (f"Error: tool '{name}' timed out after {timeout}s. "
+                    f"It may still be running in the background; do not retry blindly.")
+
+    # Universal tools always available regardless of the message (the workhorses).
+    _CORE_TOOLS = {
+        "read_file", "write_file", "edit_file", "glob", "grep",
+        "web_search", "web_fetch", "http_request", "telegram", "speak",
+        "system_info", "time_info", "weather", "news", "memory_search", "memory_store",
+        "memory_list", "task_create", "task_list", "task_update", "delegate_to_agent",
+        "swarm_dispatch", "generate_briefing", "notification", "send_file",
+        "team_delegate",
+    }
+    # Map intent words in the user's message to tool-name tokens (covers synonyms).
+    _SYNONYMS = {
+        "mail": "email", "inbox": "email", "reply": "email", "draft": "email",
+        "meeting": "calendar", "schedule": "calendar", "event": "calendar", "appointment": "calendar",
+        "deck": "presentation", "slides": "presentation", "powerpoint": "presentation", "ppt": "presentation",
+        "word": "document", "letter": "document", "sheet": "spreadsheet", "excel": "spreadsheet",
+        "website": "browser", "url": "browser", "webpage": "browser", "repo": "git", "commit": "git",
+        "pr": "github", "remind": "reminders", "note": "notes", "picture": "image", "photo": "image",
+        "trade": "trading", "position": "trading", "voice": "speak", "say": "speak",
+    }
+
+    def _select_tools(self, message: str) -> list:
+        """Return a focused subset of tools relevant to the message (reduces mis-selection vs
+        dumping all 220 tools). Fail-safe by design: too little signal, too few matches, or a
+        broad request all fall back to the FULL tool set, so a needed tool is never hidden.
+        Disable entirely with env HYPERCLAW_TOOL_ROUTING=off."""
+        import re
+        tools = self.tools
+        if os.environ.get("HYPERCLAW_TOOL_ROUTING", "on").lower() in ("off", "0", "false", "no"):
+            return tools
+        if not tools:
+            return tools
+        words = set(re.findall(r"[a-z0-9]{3,}", (message or "").lower()))
+        if len(words) < 2:
+            return tools  # not enough signal to route safely -> give everything
+        words |= {self._SYNONYMS[w] for w in list(words) if w in self._SYNONYMS}
+
+        selected = []
+        for t in tools:
+            name = t.get("name", "")
+            if name in self._CORE_TOOLS:
+                selected.append(t)
+                continue
+            name_tokens = set(name.lower().replace("_", " ").split())
+            if words & name_tokens:
+                selected.append(t)
+
+        # Fail-safes: keep the full set if routing didn't help or could starve the model.
+        if len(selected) < 15 or len(selected) > 70 or len(selected) >= len(tools) - 5:
+            return tools
+        return selected
+
+    def _get_essential_tools(self) -> list:
+        """Essential tools if TUI import fails (no shell: this is a chat surface)."""
+        return [
+            {
+                "name": "read_file",
+                "description": "Read a file's contents",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string", "description": "File path to read"}
+                    },
+                    "required": ["path"]
+                }
+            }
+        ]
+
+    def _execute_tool_fallback(self, name: str, input_data: dict) -> str:
+        """Fallback tool execution."""
+        if name == "read_file":
+            try:
+                return Path(input_data["path"]).read_text()[:10000]
+            except Exception as e:
+                return f"Error: {e}"
+        return f"Tool {name} not available in fallback mode"
+
+    def get_session_history(self, chat_id: int) -> List[dict]:
+        """Get conversation history for a session."""
+        with _session_lock:
+            if chat_id not in _session_histories:
+                _session_histories[chat_id] = []
+            return _session_histories[chat_id]
+
+    def add_to_history(self, chat_id: int, role: str, content: Any):
+        """Add message to session history."""
+        with _session_lock:
+            if chat_id not in _session_histories:
+                _session_histories[chat_id] = []
+            _session_histories[chat_id].append({"role": role, "content": content})
+            # Keep last 30 exchanges (60 messages)
+            if len(_session_histories[chat_id]) > 60:
+                _session_histories[chat_id] = _session_histories[chat_id][-60:]
+
+    def clear_session(self, chat_id: int):
+        """Clear session history."""
+        with _session_lock:
+            _session_histories[chat_id] = []
+        from hyperclaw import taint
+        taint.clear(f"{SURFACE}:{chat_id}")   # the history (and its connector content) is gone
+
+    def _get_relevant_memories(self, message: str) -> str:
+        """Get relevant memories from vector storage for the given message."""
+        memory_parts = []
+
+        # 1. Try MemoryBus for cross-channel context
+        try:
+            from .memory_bus import get_memory_bus
+            bus = get_memory_bus()
+
+            # Get semantically relevant memories
+            context = bus.get_context(message, time_range_hours=48, limit=5)
+            if context:
+                memory_parts.append(context)
+        except Exception:
+            pass
+
+        # 2. Fallback to persistent_memory if MemoryBus fails
+        if not memory_parts:
+            try:
+                from .persistent_memory import recall_relevant_memories
+                memories = recall_relevant_memories(message, limit=5)
+                if memories:
+                    lines = []
+                    for m in memories:
+                        content = m.get('content', '')[:300]
+                        lines.append(f"- {content}")
+                    memory_parts.append("\n".join(lines))
+            except Exception:
+                pass
+
+        return "\n\n".join(memory_parts) if memory_parts else ""
+
+    async def execute(
+        self,
+        message: str,
+        chat_id: int,
+        include_history: bool = True,
+        scope: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Execute a message through TUI with full tool access.
+
+        Args:
+            message: User's message/request
+            chat_id: Session identifier (Telegram chat_id)
+            include_history: Whether to include conversation history
+            scope: chat_scope.OWNER or GUEST. None resolves the Telegram
+                   owner identity for chat_id; unknown -> GUEST (fail closed).
+
+        Returns:
+            {
+                'text': str,           # Response text
+                'tools_used': list,    # Tools that were called
+                'screenshots': list,   # Paths to any screenshots taken
+                'success': bool,       # Whether execution succeeded
+                'error': str|None      # Error message if failed
+            }
+        """
+        if scope is None:
+            scope = scope_for("telegram", chat_id)
+        why = self._usable()
+        if why:
+            text = ("This chat bridge isn't available on a Hyper-deployed install (HyperSpeed V2 "
+                    "only); use the HyperClaw chat instead." if why == "hyper_deployed" else
+                    "This chat bridge has no model configured.")
+            return {'text': text, 'tools_used': [], 'screenshots': [], 'files': [],
+                    'success': False, 'error': why}
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            _executor,
+            self._execute_sync,
+            message,
+            chat_id,
+            include_history,
+            normalize_scope(scope),
+        )
+
+
+    # Failover ladder: on overload/rate-limit/transient errors (and policy refusals), walk
+    # down the Claude 5 family instead of failing the turn. Chain is built from the env-driven
+    # tier config (FABLE_MODEL / HYPERCLAW_OPUS_MODEL / HYPERCLAW_SONNET_MODEL) so operator overrides in
+    # .env apply to failover too, not just the primary pick.
+    _FAILOVER_CHAIN = ["claude-fable-5", "claude-opus-5", "claude-sonnet-5"]  # fallback if model_selector unavailable
+
+    def _failover_chain(self):
+        try:
+            from hyperclaw.model_selector import tiers
+            t = tiers()
+            chain = [t["fable"], t["opus"], t["sonnet"]]
+            # De-dup while preserving order (overrides may collapse tiers)
+            return list(dict.fromkeys(chain))
+        except Exception:
+            return list(self._FAILOVER_CHAIN)
+
+    def _create_with_failover(self, client, *, model, deadline=None, **kwargs):
+        """client.messages.create with model failover on 429/5xx/timeouts/refusals.
+
+        Returns (response, model_used). Raises the last transient error if every
+        rung fails; respects an optional time.monotonic() deadline between rungs.
+        """
+        import time as _time
+        import logging
+        log = logging.getLogger("tui_bridge")
+        chain = [model] + [m for m in self._failover_chain() if m != model]
+        last_err = None
+        last_refusal = None
+        for attempt, m in enumerate(chain):
+            if deadline is not None and _time.monotonic() > deadline and attempt > 0:
+                break  # out of time budget; fall through to last_err/last_refusal
+            try:
+                kw = kwargs
+                if m != model and kwargs.get("max_tokens"):
+                    # a failover rung keeps the turn's max unless its model needs less
+                    from hyperclaw.cost_guard import max_output
+                    kw = dict(kwargs, max_tokens=min(int(kwargs["max_tokens"]),
+                                                     max_output("bridge", "anthropic", m)))
+                resp = client.messages.create(model=m, **kw)
+                if getattr(resp, "stop_reason", None) == "refusal":
+                    sd = getattr(resp, "stop_details", None)
+                    log.warning(
+                        f"Refusal on {m} (category={getattr(sd, 'category', None)}): "
+                        f"{getattr(sd, 'explanation', '')}"
+                    )
+                    last_refusal = (resp, m)
+                    continue  # try the next rung — categories often differ by model
+                if m != model:
+                    log.warning(f"Model failover: {model} -> {m}")
+                return resp, m
+            except anthropic.APIStatusError as e:
+                status = getattr(e, "status_code", 0)
+                if status in (429, 500, 502, 503, 529):
+                    last_err = e
+                    _time.sleep(min(1 + attempt, 2))
+                    continue
+                raise
+            except (anthropic.APIConnectionError, anthropic.APITimeoutError) as e:
+                last_err = e
+                _time.sleep(min(1 + attempt, 2))
+                continue
+        if last_refusal is not None:
+            return last_refusal  # whole chain refused — surface it, don't crash
+        if last_err is not None:
+            raise last_err
+        raise RuntimeError("Model failover chain exhausted with no result")
+
+    def _execute_sync(
+        self,
+        message: str,
+        chat_id: int,
+        include_history: bool,
+        scope: str = GUEST,
+    ) -> Dict[str, Any]:
+        """Synchronous execution (runs in thread pool). One message is one
+        task for the cost guard (spec §9)."""
+        from hyperclaw import cost_guard, taint
+        scope = normalize_scope(scope)
+        notices = cost_guard.take_owner_notices() if scope == OWNER else []
+        session = f"{SURFACE}:{chat_id}"
+        if scope != OWNER and isinstance(message, str):
+            # A guest's words: connector content for the taint guard.
+            message = taint.mark(message, "telegram", "telegram", session=session)
+        with taint.conversation(session), \
+                cost_guard.task(surface=SURFACE, request=message, owner=(scope == OWNER),
+                                conversation=session) as task:
+            result = self._execute_turn(message, chat_id, include_history, scope)
+            from hyperclaw import client_guard   # what the restricted-client guard left out
+            withheld_note = client_guard.reply_note(task)
+            if withheld_note and result.get('text') is not None:
+                result['text'] = (result['text'].rstrip() + "\n\n" + withheld_note).strip()
+            if scope == OWNER:
+                line = cost_guard.spend_line(task)
+                extra = ([line] if line else []) + notices
+                if extra and result.get('text') is not None:
+                    result['text'] = (result['text'].rstrip() + "\n\n" + "\n".join(extra)).strip()
+        return result
+
+    def _execute_turn(
+        self,
+        message: str,
+        chat_id: int,
+        include_history: bool,
+        scope: str = GUEST,
+    ) -> Dict[str, Any]:
+        from hyperclaw.cost_guard import (CostCapReached, current_task, guard_client, max_output,
+                                          stop_message)
+        from hyperclaw.client_guard import RestrictedContentBlocked
+
+        result = {
+            'text': '',
+            'tools_used': [],
+            'screenshots': [],
+            'files': [],
+            'success': True,
+            'error': None
+        }
+
+        # Bind this worker thread to the conversation so send_file(via='here')
+        # queues files for THIS chat; drained into result['files'] at turn end.
+        try:
+            from . import outbox as _outbox
+        except Exception:
+            _outbox = None
+        if _outbox is not None:
+            try:
+                _outbox.set_current_session(chat_id)
+            except Exception:
+                # Clear any stale binding from a previous turn on this pooled thread so
+                # files can't be queued into the WRONG chat; drain below still works.
+                try:
+                    _outbox.set_current_session(None)
+                except Exception:
+                    pass
+
+        try:
+            # timeout/max_retries: SDK defaults are 600s x 3 attempts, which multiplied by
+            # the 3-rung failover ladder and the 12-iteration loop is a multi-hour hang.
+            client = guard_client(anthropic.Anthropic(api_key=self.api_key, timeout=120.0,
+                                                      max_retries=1), "anthropic")
+            import time as _walltime
+            _turn_deadline = _walltime.monotonic() + 600  # 10 min wall-clock per message
+
+            if scope == OWNER:
+                # Get relevant memories for this message
+                memory_context = self._get_relevant_memories(message)
+
+                # Build system prompt with memory context (fenced as DATA)
+                system_with_memory = self._owner_system_with_memories(memory_context)
+            else:
+                # Guest fence: no owner memory, recalls or persona in context.
+                system_with_memory = self.guest_system_prompt
+
+            # Build messages with history
+            messages = []
+            if include_history:
+                history = self.get_session_history(chat_id)
+                messages.extend(history[-20:])  # Last 10 exchanges
+
+            messages.append({"role": "user", "content": message})
+
+            # Bounded agentic loop. Interactive chat turns should resolve quickly; genuinely large
+            # jobs get delegated/queued, not spun inline. The guards below stop runaway loops
+            # (the previous version had max_iterations=100 and NO loop/error detection).
+            max_iterations = 12
+            iteration = 0
+            response_text = ""
+            # Route to a focused tool subset for this message (fail-safe to all tools).
+            selected_tools = self._select_tools(message)
+            if scope != OWNER:
+                selected_tools = guest_tools(self.tools)
+            offered_names = {t.get("name") for t in selected_tools}
+            # Model routing (Fable backend): pick the right model for THIS request.
+            try:
+                from hyperclaw.model_selector import pick_model
+                turn_model = pick_model(message, self.model)
+            except Exception:
+                turn_model = self.model
+            import hashlib as _hashlib, json as _json
+            _tool_sig_counts = {}      # (tool, input) signature -> times called this turn
+            _consecutive_errors = 0
+            _MAX_REPEAT = 3
+            _loop_break = False
+            # Wave 2: idempotency per conversation (persists across turns and
+            # restarts), retry budgets per tool/resource, ~8 tool calls per message.
+            # Wave 3: the user's own words in this chat are the provenance a
+            # read-only fetch is checked against; ask-tier calls are queued
+            # for the owner's Send / Edit / Cancel (result['approvals']).
+            from hyperclaw.tools.approval import provenance_from_messages
+            guard = TurnGuard(conversation=f"{SURFACE}:{chat_id}", surface=SURFACE,
+                              call_cap=chat_tool_call_cap(),
+                              provenance=provenance_from_messages(messages))
+            result['approvals'] = guard.queued
+            _task = current_task()
+            if _task is not None and _task.evidence is None:
+                _task.evidence = guard   # the stop message is built from its results
+
+            while iteration < max_iterations:
+                iteration += 1
+                if _walltime.monotonic() > _turn_deadline:
+                    if not response_text.strip():
+                        response_text = ("This is taking longer than my time budget for one message. "
+                                         "Tell me which part to prioritize and I'll continue.")
+                    break
+
+                # Call Claude (with model failover on overload/transient errors/refusals).
+                # At a cost cap the guard refuses the call: stop and ask (owner) or
+                # a neutral reply with the owner notified (guest); never a cheaper model.
+                try:
+                    response, _model_used = self._create_with_failover(
+                        client,
+                        model=turn_model,
+                        deadline=_turn_deadline,
+                        max_tokens=max_output("bridge", "anthropic", turn_model),
+                        system=system_with_memory,
+                        tools=selected_tools,
+                        messages=messages
+                    )
+                except CostCapReached as _cap:
+                    response_text = (response_text.rstrip() + "\n\n"
+                                     + stop_message(_cap, owner=(scope == OWNER))).strip()
+                    result['stopped_at_cost_cap'] = _cap.scope
+                    break
+                except RestrictedContentBlocked as _blocked:   # nothing was sent
+                    response_text = (response_text.rstrip() + "\n\n"
+                                     + _blocked.user_message).strip()
+                    break
+                result['model_used'] = _model_used
+                if _model_used != turn_model:
+                    result['failover_from'] = turn_model
+                if getattr(response, "stop_reason", None) == "refusal":
+                    sd = getattr(response, "stop_details", None)
+                    response_text = response_text or (
+                        "I can't help with that request"
+                        + (f" ({sd.category})" if sd is not None and getattr(sd, 'category', None) else "")
+                        + "."
+                    )
+                    break
+
+                # Process response
+                assistant_content = []
+                tool_results = []
+                has_text_this_turn = False
+
+                for block in response.content:
+                    if block.type == "text":
+                        text = block.text
+                        if text.strip():
+                            has_text_this_turn = True
+                        response_text += text
+                        assistant_content.append({
+                            "type": "text",
+                            "text": text
+                        })
+
+                    elif block.type == "tool_use":
+                        tool_name = block.name
+                        tool_input = block.input
+
+                        # Track tool usage
+                        result['tools_used'].append({
+                            'name': tool_name,
+                            'input': tool_input
+                        })
+
+                        # Loop guard: refuse to run the SAME tool with identical input repeatedly
+                        # (the classic runaway shape). Legit multi-step work varies tool/input, so
+                        # this only trips on stuck repetition - not on normal long tool sequences.
+                        try:
+                            _sig = _hashlib.sha1(
+                                (tool_name + _json.dumps(tool_input, sort_keys=True, default=str)).encode()
+                            ).hexdigest()
+                        except Exception:
+                            _sig = tool_name
+                        _tool_sig_counts[_sig] = _tool_sig_counts.get(_sig, 0) + 1
+                        if _tool_sig_counts[_sig] > _MAX_REPEAT:
+                            envelope = make_envelope(
+                                Status.BUDGET_EXHAUSTED,
+                                f"[loop-guard] '{tool_name}' was already called with identical "
+                                f"input {_MAX_REPEAT} times; it was NOT run again. Change approach "
+                                f"or give your final answer.")
+                            _loop_break = True
+                        else:
+                            if tool_name not in offered_names or (
+                                    scope != OWNER and tool_name not in GUEST_SAFE_TOOLS):
+                                # Never run a tool that was not offered on this
+                                # surface/scope, whatever the model asks for.
+                                envelope = make_envelope(
+                                    Status.PERMISSION_DENIED,
+                                    f"Tool '{tool_name}' is not available in this chat; it was "
+                                    f"NOT run.", reason=REASON_SURFACE)
+                            else:
+                                envelope = self.dispatch_tool(tool_name, tool_input, scope=scope,
+                                                              guard=guard)
+                        tool_result = envelope.to_content(8000)
+                        # Consecutive-error backstop
+                        if not envelope.ok:
+                            _consecutive_errors += 1
+                        else:
+                            _consecutive_errors = 0
+
+                        assistant_content.append({
+                            "type": "tool_use",
+                            "id": block.id,
+                            "name": tool_name,
+                            "input": tool_input
+                        })
+
+                        tool_results.append({
+                            "type": "tool_result",
+                            "tool_use_id": block.id,
+                            "content": tool_result
+                        })
+
+                # Add to messages
+                messages.append({"role": "assistant", "content": assistant_content})
+
+                if tool_results:
+                    messages.append({"role": "user", "content": tool_results})
+                    if guard.cap_hit:  # tool-call cap: stop and say what did not run
+                        note = guard.stop_note()
+                        response_text = (response_text.rstrip() + "\n\n" + note).strip()
+                        result['stopped_at_tool_cap'] = True
+                        break
+                    # Stop if a loop or repeated tool errors were detected this turn.
+                    if _loop_break or _consecutive_errors >= 5:
+                        if not response_text.strip():
+                            response_text = ("I stopped because I was repeating the same step without "
+                                             "making progress. Tell me how you'd like to proceed.")
+                        break
+                    # Otherwise keep working through the tool sequence.
+                else:
+                    # No tools this turn. (assistant turn already appended above - do NOT re-append.)
+                    if response.stop_reason == "max_tokens":
+                        messages.append({"role": "user", "content": "Continue from where you left off."})
+                        continue
+                    # Finished naturally.
+                    break
+
+            # If the step budget was exhausted without an answer, say so (don't return blank/hang).
+            if iteration >= max_iterations and not response_text.strip():
+                response_text = ("I hit my step limit for this turn without finishing. The task may "
+                                 "need to be broken down - tell me which part to tackle first.")
+
+            # Update session history
+            self.add_to_history(chat_id, "user", message)
+            self.add_to_history(chat_id, "assistant", response_text or assistant_content)
+
+            # Record in cross-channel memory (non-blocking). Owner only: a
+            # guest must not be able to write into the owner's memory.
+            if scope == OWNER:
+                try:
+                    from .memory_bus import get_memory_bus
+                    bus = get_memory_bus()
+                    bus.record_exchange(
+                        channel="tui_bridge",
+                        user_message=message,
+                        assistant_message=response_text or str(assistant_content)[:2000],
+                        metadata={"chat_id": chat_id},
+                        extract_knowledge=True
+                    )
+                except Exception:
+                    pass  # Don't fail on memory errors
+
+            result['text'] = response_text
+
+        except Exception as e:
+            result['success'] = False
+            result['error'] = str(e)
+            # The technical error stays in result['error'] and the crash log
+            # below; the user-facing text names the failed action only.
+            result['text'] = failure_notice("request")
+            # Crash guard: a failed message must never take the process down and must
+            # leave forensics. Full traceback to a dedicated, private crash log.
+            try:
+                import traceback
+                crash_log = HYPERCLAW_ROOT / "logs" / "crashes.log"
+                crash_log.parent.mkdir(parents=True, exist_ok=True)
+                with open(crash_log, "a") as fh:
+                    fh.write(f"\n=== {datetime.now().isoformat()} chat={chat_id} ===\n")
+                    fh.write(f"message: {str(message)[:500]}\n")
+                    traceback.print_exc(file=fh)
+                os.chmod(crash_log, 0o600)
+            except Exception:
+                pass
+
+        # Deliver any files tools queued for this conversation (send_file via='here',
+        # doc engines, charts). Channel adapters send these natively after the text.
+        try:
+            if _outbox is not None:
+                result['files'] = _outbox.drain(chat_id)
+        except Exception:
+            pass
+
+        return result
+
+    async def execute_gmail(self, action: str, **kwargs) -> Dict[str, Any]:
+        """
+        Execute Gmail-specific operations.
+
+        Actions:
+            - inbox: List inbox emails
+            - read: Read specific email
+            - send: Send email
+            - search: Search emails
+            - thread: Get email thread
+        """
+        try:
+            from .integrations_layer import (
+                gmail_list_inbox, gmail_get_message, gmail_send,
+                gmail_search, gmail_get_thread, gmail_read_message_text
+            )
+
+            if action == "inbox":
+                max_results = kwargs.get('max_results', 10)
+                emails = await asyncio.to_thread(gmail_list_inbox, max_results)
+                return {'success': True, 'data': emails}
+
+            elif action == "read":
+                message_id = kwargs.get('message_id')
+                if not message_id:
+                    return {'success': False, 'error': 'message_id required'}
+                text = await asyncio.to_thread(gmail_read_message_text, message_id)
+                return {'success': True, 'data': text}
+
+            elif action == "send":
+                to = kwargs.get('to')
+                subject = kwargs.get('subject')
+                body = kwargs.get('body')
+                cc = kwargs.get('cc', '')
+                reply_to = kwargs.get('reply_to_id', '')
+
+                if not all([to, subject, body]):
+                    return {'success': False, 'error': 'to, subject, and body required'}
+
+                result = await asyncio.to_thread(gmail_send, to, subject, body, cc, reply_to)
+                return {'success': True, 'data': result}
+
+            elif action == "search":
+                query = kwargs.get('query', '')
+                max_results = kwargs.get('max_results', 10)
+                results = await asyncio.to_thread(gmail_search, query, max_results)
+                return {'success': True, 'data': results}
+
+            elif action == "thread":
+                thread_id = kwargs.get('thread_id')
+                if not thread_id:
+                    return {'success': False, 'error': 'thread_id required'}
+                thread = await asyncio.to_thread(gmail_get_thread, thread_id)
+                return {'success': True, 'data': thread}
+
+            else:
+                return {'success': False, 'error': f'Unknown action: {action}'}
+
+        except Exception as e:
+            return {'success': False, 'error': str(e)}
+
+
+# Singleton instance
+_bridge_instance: Optional[TUIBridge] = None
+
+def get_tui_bridge() -> TUIBridge:
+    """Get singleton TUI bridge instance."""
+    global _bridge_instance
+    if _bridge_instance is None:
+        _bridge_instance = TUIBridge()
+    return _bridge_instance