utim-cli 1.0.0__py3-none-any.whl

utim_cli/tools.py

@@ -0,0 +1,3381 @@
+import os
+import re
+import shutil
+import subprocess
+import difflib
+import threading
+import time
+import queue
+import requests
+import json
+import urllib.parse
+import pathlib
+import sqlite3
+from typing import Dict, Optional
+from .blender_agent import blender_agent_create_from_image
+
+# Strip ANSI/VT100 escape sequences from terminal output
+_ANSI_RE = re.compile(r"\x1b(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+def _strip_ansi(text: str) -> str:
+    return _ANSI_RE.sub("", text)
+
+def _make_file_uri(path: str) -> str:
+    """Convert a Windows path to a clickable `file://` URI.
+    Handles spaces and backslashes correctly for terminals that auto‑link URIs.
+    """
+    # Resolve absolute path and normalise to POSIX style
+    p = pathlib.Path(path).resolve()
+    # Percent‑encode characters (e.g., spaces) and replace backslashes
+    encoded = urllib.parse.quote(str(p).replace('\\', '/'))
+    return f"file:///{encoded}"
+
+
+# ─── Background Process Management ─────────────────────────────────────────────
+import uuid, json, pathlib, subprocess, os, time, threading
+
+# Helper for Blender object creation
+def blender_create_object(name: str, object_type: str, mesh_data: dict, location: list = None, rotation: list = None, scale: list = None, export_path: str = None, export_format: str = "blend") -> str:
+    """Create a Blender object from mesh data.
+
+    Parameters
+    ----------
+    name: str
+        Name for the new object.
+    object_type: str
+        Currently only "MESH" is supported.
+    mesh_data: dict
+        Dictionary with ``vertices`` and ``faces`` (and optional normals/uvs).
+    location, rotation, scale: list of floats (optional)
+        Transform applied after creation.
+    export_path: str (optional)
+        Directory where the exported file will be saved. Defaults to ``blender_assets``.
+    export_format: str
+        One of "blend", "obj", "glb". Determines Blender export operator.
+    """
+    # Validate mesh data
+    if not isinstance(mesh_data, dict) or 'vertices' not in mesh_data or 'faces' not in mesh_data:
+        raise ValueError("mesh_data must contain 'vertices' and 'faces' keys")
+
+    # Build a temporary script that runs inside Blender
+    script_id = uuid.uuid4().hex
+    script_path = pathlib.Path('.utim_tmp') / f"{script_id}.py"
+    script_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Prepare export settings
+    export_path = export_path or os.path.abspath(os.path.join('.utim_tmp', 'blender_assets'))
+    os.makedirs(export_path, exist_ok=True)
+    export_file = pathlib.Path(export_path) / f"{name}.{export_format}"
+
+    script_content = f"""
+import bpy, json, os, pathlib
+
+# Clean scene
+bpy.ops.wm.read_factory_settings(use_empty=True)
+
+mesh_dict = {json.dumps(mesh_data)}
+verts = [(v[0], v[1], v[2]) for v in mesh_dict['vertices']]
+faces = [tuple(f) for f in mesh_dict['faces']]
+
+mesh = bpy.data.meshes.new('{name}_mesh')
+mesh.from_pydata(verts, [], faces)
+mesh.update()
+obj = bpy.data.objects.new('{name}', mesh)
+
+# Link object to collection
+collection = bpy.context.scene.collection
+collection.objects.link(obj)
+
+# Apply transforms if provided
+if {location is not None}:
+    obj.location = {location or [0,0,0]}
+if {rotation is not None}:
+    obj.rotation_euler = {rotation or [0,0,0]}
+if {scale is not None}:
+    obj.scale = {scale or [1,1,1]}
+
+# Export according to format
+export_path = r"{export_file}"
+os.makedirs(os.path.dirname(export_path), exist_ok=True)
+if '{export_format}' == 'obj':
+    bpy.ops.export_scene.obj(filepath=export_path, use_selection=False)
+elif '{export_format}' == 'glb':
+    bpy.ops.export_scene.gltf(filepath=export_path, export_format='GLB')
+else:
+    # default blend save
+    bpy.ops.wm.save_as_mainfile(filepath=export_path)
+"""
+    script_path.write_text(script_content)
+
+    # Run Blender in background mode
+    blender_exe = os.getenv('BLENDER_EXE', 'blender')
+    cmd = [blender_exe, '--background', '--python', str(script_path)]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(f"Blender execution failed: {result.stderr}")
+
+    # Cleanup script
+    try:
+        os.remove(script_path)
+    except OSError:
+        pass
+
+    return f"Blender object created and exported to {export_file}"
+
+# Stores running background processes: {process_id: {process, output_queue, stopped}}
+_BACKGROUND_PROCESSES: Dict[int, dict] = {}
+_PROCESS_COUNTER = 0
+_PROCESS_LOCK = threading.Lock()
+
+def read_file(filepath: str, start_line: int = None, end_line: int = None) -> str:
+    """Reads the content of a file, optionally between start_line and end_line (1-indexed, inclusive).
+    
+    If no range is given and the file is large, the first 250 lines AND last 250 lines 
+    are returned (total 500 lines) to preserve critical tail sections like implementations.
+    The response header always shows the total line count so you know when to read further.
+    """
+    MAX_LINES = 250
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            all_lines = f.readlines()
+    except Exception as e:
+        return f"Error reading file {filepath}: {str(e)}"
+
+    total = len(all_lines)
+
+    if start_line is not None or end_line is not None:
+        # 1-indexed, inclusive; clamp to file bounds
+        s = max(1, int(start_line or 1))
+        e = min(total, int(end_line or total))
+        selected = all_lines[s - 1 : e]
+        header = f"[File: {filepath} ({_make_file_uri(filepath)}) | Lines {s}-{e} of {total}]\n"
+        return header + "".join(selected)
+    else:
+        if total <= MAX_LINES:
+            header = f"[File: {filepath} ({_make_file_uri(filepath)}) | {total} lines]\n"
+            return header + "".join(all_lines)
+        elif total <= MAX_LINES * 2:
+            # For moderately large files, show first 250 lines
+            selected = all_lines[:MAX_LINES]
+            header = (
+                f"[File: {filepath} ({_make_file_uri(filepath)}) | Showing lines 1-{MAX_LINES} of {total} — "
+                f"use start_line/end_line to read further]\n"
+            )
+            return header + "".join(selected)
+        else:
+            # FIX #3: For very large files, show BOTH first 250 AND last 250 lines
+            # This preserves critical tail sections (implementations, closing brackets, etc.)
+            first_part = all_lines[:MAX_LINES]
+            last_part = all_lines[-MAX_LINES:]
+            header = (
+                f"[File: {filepath} ({_make_file_uri(filepath)}) | Showing lines 1-{MAX_LINES} and {total-MAX_LINES+1}-{total} of {total} — "
+                f"critical end section preserved]\n"
+            )
+            result = "".join(first_part)
+            # Add separator to indicate continuation
+            result += f"\n... [lines {MAX_LINES+1} through {total-MAX_LINES} omitted] ...\n"
+            result += "".join(last_part)
+            return header + result
+
+def _extract_patterns_after_write(filepath: str, content: str, old_content: str = ""):
+    """Extract patterns from file content after write/edit operation. Runs asynchronously."""
+    try:
+        from .pattern_extractor import extract_patterns
+        extract_patterns(filepath, content, "write" if not old_content else "edit")
+    except Exception:
+        pass  # Pattern extraction failures should be silent
+
+_DRY_RUN: bool = False
+
+def validate_syntax(filepath: str, content: str) -> Optional[str]:
+    """Validates syntax of content based on file extension.
+    Returns error string if invalid, None if valid or unsupported.
+    """
+    ext = os.path.splitext(filepath)[1].lower()
+    if ext == ".py":
+        import ast
+        try:
+            ast.parse(content, filename=filepath)
+        except SyntaxError as e:
+            return f"Syntax Error: {e.msg} at line {e.lineno}, column {e.offset} in {filepath}"
+        except Exception as e:
+            return f"Parse Error in {filepath}: {str(e)}"
+    elif ext == ".json":
+        import json
+        try:
+            json.loads(content)
+        except json.JSONDecodeError as e:
+            return f"JSON Syntax Error: {e.msg} at line {e.lineno}, column {e.colno} in {filepath}"
+        except Exception as e:
+            return f"JSON Parse Error in {filepath}: {str(e)}"
+    elif ext in (".yaml", ".yml"):
+        try:
+            import yaml
+            try:
+                yaml.safe_load(content)
+            except Exception as e:
+                return f"YAML Syntax Error in {filepath}: {str(e)}"
+        except ImportError:
+            pass
+    elif ext == ".js":
+        import shutil
+        import subprocess
+        import tempfile
+        if shutil.which("node"):
+            with tempfile.NamedTemporaryFile(suffix=".js", delete=False, mode="w", encoding="utf-8") as f:
+                f.write(content)
+                temp_name = f.name
+            try:
+                res = subprocess.run(["node", "--check", temp_name], capture_output=True, text=True)
+                if res.returncode != 0:
+                    err = res.stderr.replace(temp_name, filepath)
+                    return f"JavaScript Syntax Error in {filepath}:\n{err}"
+            finally:
+                try:
+                    os.unlink(temp_name)
+                except Exception:
+                    pass
+    elif ext == ".ts":
+        import shutil
+        import subprocess
+        import tempfile
+        if shutil.which("tsc"):
+            with tempfile.NamedTemporaryFile(suffix=".ts", delete=False, mode="w", encoding="utf-8") as f:
+                f.write(content)
+                temp_name = f.name
+            try:
+                res = subprocess.run(["tsc", "--noEmit", "--skipLibCheck", temp_name], capture_output=True, text=True)
+                if res.returncode != 0:
+                    err = res.stdout.replace(temp_name, filepath) + res.stderr.replace(temp_name, filepath)
+                    return f"TypeScript Compilation Error in {filepath}:\n{err}"
+            finally:
+                try:
+                    os.unlink(temp_name)
+                except Exception:
+                    pass
+    return None
+
+def write_file(filepath: str, content: str) -> str:
+    """Writes complete content to a file, overwriting any existing file. Use this to create or modify code."""
+    try:
+        old_content = ""
+        if os.path.exists(filepath):
+            with open(filepath, "r", encoding="utf-8") as f:
+                old_content = f.read()
+
+        # Pre-commit syntax check
+        syntax_error = validate_syntax(filepath, content)
+        if syntax_error:
+            err_mode = " (Dry Run Mode)" if _DRY_RUN else ""
+            return f"Pre-Commit Validation Failed{err_mode}:\n{syntax_error}"
+
+        if _DRY_RUN:
+            old_lines = old_content.splitlines() if old_content else []
+            new_lines = content.splitlines()
+            diff = list(difflib.unified_diff(old_lines, new_lines, n=0))
+            added = sum(1 for line in diff if line.startswith('+') and not line.startswith('+++'))
+            removed = sum(1 for line in diff if line.startswith('-') and not line.startswith('---'))
+            if old_content:
+                return f"[Dry Run] Successfully simulated modifying {filepath}. Projected changes: +{added} -{removed} lines."
+            else:
+                return f"[Dry Run] Successfully simulated creating {filepath}. Projected: {len(new_lines)} lines."
+
+        os.makedirs(os.path.dirname(os.path.abspath(filepath)), exist_ok=True)
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        # Extract patterns asynchronously after write
+        import threading
+        threading.Thread(target=_extract_patterns_after_write, args=(filepath, content, old_content), daemon=True).start()
+
+        # Calculate a simple diff
+        old_lines = old_content.splitlines()
+        new_lines = content.splitlines()
+        diff = list(difflib.unified_diff(old_lines, new_lines, n=0))
+        
+        added = sum(1 for line in diff if line.startswith('+') and not line.startswith('+++'))
+        removed = sum(1 for line in diff if line.startswith('-') and not line.startswith('---'))
+
+        if old_content:
+            return f"Successfully modified {filepath}. Changes: +{added} -{removed} lines."
+        else:
+            return f"Successfully created {filepath}. Added {len(new_lines)} lines."
+    except Exception as e:
+        return f"Error writing file {filepath}: {str(e)}"
+
+def edit_file(filepath: str, old_str: str = None, new_str: str = None, replacements: list = None) -> str:
+    """Replaces specific strings in a file. Can perform a single replacement or multiple non-contiguous replacements in batch."""
+    try:
+        if not os.path.exists(filepath):
+            return f"Error: File {filepath} does not exist."
+
+        with open(filepath, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        if replacements is not None:
+            if not isinstance(replacements, list):
+                return "Error: replacements must be a list of objects with 'old_str' and 'new_str' keys."
+            if not replacements:
+                return "Error: replacements list is empty."
+            
+            # Verify all replacements are valid and occur exactly once first
+            # to prevent partial edits leaving the file in a broken intermediate state.
+            current_content = content
+            for i, rep in enumerate(replacements):
+                if not isinstance(rep, dict) or "old_str" not in rep or "new_str" not in rep:
+                    return f"Error: Replacement at index {i} must be a dictionary with 'old_str' and 'new_str'."
+                
+                o_str = rep["old_str"]
+                n_str = rep["new_str"]
+                
+                count = current_content.count(o_str)
+                if count == 0:
+                    return f"Error (Replacement #{i+1}): The target string to replace was not found in the file."
+                if count > 1:
+                    return f"Error (Replacement #{i+1}): The target string is ambiguous as it occurs {count} times in the file. Please provide more context."
+                
+                current_content = current_content.replace(o_str, n_str, 1)
+            
+            # Pre-commit syntax check
+            syntax_error = validate_syntax(filepath, current_content)
+            if syntax_error:
+                err_mode = " (Dry Run Mode)" if _DRY_RUN else ""
+                return f"Pre-Commit Validation Failed{err_mode}:\n{syntax_error}"
+
+            if _DRY_RUN:
+                return f"[Dry Run] Successfully simulated applying {len(replacements)} replacements in batch to {filepath}."
+
+            # All checks passed, apply edits
+            with open(filepath, "w", encoding="utf-8") as f:
+                f.write(current_content)
+            return f"Successfully applied {len(replacements)} replacements in batch to {filepath}."
+        
+        else:
+            if old_str is None or new_str is None:
+                return "Error: Must specify either 'replacements' or both 'old_str' and 'new_str'."
+            
+            count = content.count(old_str)
+            if count == 0:
+                return f"Error: The string to replace was not found in {filepath}."
+            if count > 1:
+                return f"Error: The string to replace occurs {count} times in {filepath}. Please provide more context in `old_str` to make it unique."
+
+            new_content = content.replace(old_str, new_str, 1)
+
+            # Pre-commit syntax check
+            syntax_error = validate_syntax(filepath, new_content)
+            if syntax_error:
+                err_mode = " (Dry Run Mode)" if _DRY_RUN else ""
+                return f"Pre-Commit Validation Failed{err_mode}:\n{syntax_error}"
+
+            if _DRY_RUN:
+                return f"[Dry Run] Successfully edited {filepath} (Simulated)."
+
+            with open(filepath, "w", encoding="utf-8") as f:
+                f.write(new_content)            
+            return f"Successfully edited {filepath}."
+    except Exception as e:
+        return f"Error editing file {filepath}: {str(e)}"
+
+
+
+
+# Module-level cancel-event slot.  The orchestrator injects its own
+# threading.Event here before each tool call so run_command can be aborted.
+_cancel_event = None   # type: threading.Event | None
+
+# ─── Intelligent Sandbox mode ──────────────────────────────────────────────────
+# Set to True via --sandbox CLI flag. When active, run_command uses static analysis
+# to check commands for safety. Risky commands are blocked unless approved.
+_SANDBOX_MODE: bool = False
+_SANDBOX_IMAGE: str = "ubuntu:22.04"   # unused legacy parameter
+
+_APPROVED_COMMANDS = set()
+
+def approve_command(command: str):
+    """Mark a specific command string as approved by the user for execution."""
+    _APPROVED_COMMANDS.add(command)
+
+def is_command_approved(command: str) -> bool:
+    """Check if a command has been explicitly approved by the user."""
+    return command in _APPROVED_COMMANDS
+
+def analyze_command_safety(command: str) -> tuple:
+    """Analyze a shell command for potential security risks.
+    
+    Returns a tuple of (is_safe, reason).
+    """
+    if not command:
+        return True, ""
+        
+    cmd_lower = command.lower()
+    
+    # Exemptions for known safe combinations
+    exemptions = [
+        r"^pytest\b",
+        r"^npm\s+(run\s+)?test\b",
+        r"^git\s+(status|diff|log|show|branch)\b",
+        r"^python\s+-m\s+py_compile\b",
+        r"^python\s+--version\b",
+    ]
+    for ex in exemptions:
+        if re.search(ex, cmd_lower.strip()):
+            return True, ""
+            
+    # Deletion / destruction
+    destructive_patterns = [
+        (r"\brm\b", "File deletion (rm)"),
+        (r"\bdel\b", "File deletion (del)"),
+        (r"\berase\b", "File deletion (erase)"),
+        (r"\brd\b", "Directory removal (rd)"),
+        (r"\brmdir\b", "Directory removal (rmdir)"),
+        (r"\bremove-item\b", "File deletion (Remove-Item)"),
+        (r"\bformat\b", "Disk formatting (format)"),
+    ]
+    
+    # Execution of arbitrary/external scripts, binaries, or shells
+    execution_patterns = [
+        (r"\bsh\b", "Shell execution (sh)"),
+        (r"\bbash\b", "Shell execution (bash)"),
+        (r"\bcmd\b", "Shell execution (cmd)"),
+        (r"\bpowershell\b", "Shell execution (powershell)"),
+        (r"\bpwsh\b", "Shell execution (pwsh)"),
+        (r"\bpython\b", "Python script execution"),
+        (r"\bnode\b", "Node script execution"),
+        (r"\bperl\b", "Perl script execution"),
+        (r"\bruby\b", "Ruby script execution"),
+        (r"\bexec\b", "Process execution (exec)"),
+        (r"\beval\b", "Command evaluation (eval)"),
+        (r"\bsudo\b", "Superuser privilege escalation (sudo)"),
+        (r"\brunas\b", "Privilege escalation (runas)"),
+    ]
+    
+    # Network tools (potential data exfiltration or malware download)
+    network_patterns = [
+        (r"\bcurl\b", "Network download/upload (curl)"),
+        (r"\bwget\b", "Network download (wget)"),
+        (r"\biwr\b", "PowerShell web request (Invoke-WebRequest)"),
+        (r"\birm\b", "PowerShell web request (Invoke-RestMethod)"),
+        (r"\bssh\b", "Remote access (ssh)"),
+        (r"\bscp\b", "Remote copy (scp)"),
+        (r"\bsftp\b", "Remote file transfer (sftp)"),
+        (r"\bftp\b", "File transfer (ftp)"),
+        (r"\btelnet\b", "Remote connection (telnet)"),
+        (r"\bnslookup\b", "DNS lookup (nslookup)"),
+        (r"\bdig\b", "DNS lookup (dig)"),
+        (r"\bping\b", "Network ping"),
+    ]
+    
+    # Package managers & software installers (mutating system state)
+    installer_patterns = [
+        (r"\bpip\b", "Python package manager (pip)"),
+        (r"\bnpm\b", "Node package manager (npm)"),
+        (r"\byarn\b", "Node package manager (yarn)"),
+        (r"\bpnpm\b", "Node package manager (pnpm)"),
+        (r"\bpoetry\b", "Python environment manager (poetry)"),
+        (r"\bapt\b", "System package manager (apt)"),
+        (r"\byum\b", "System package manager (yum)"),
+        (r"\bbrew\b", "System package manager (brew)"),
+        (r"\bchoco\b", "System package manager (choco)"),
+        (r"\bgem\b", "Ruby package manager (gem)"),
+    ]
+    
+    # File redirection / piping to files (writing contents)
+    redirection_patterns = [
+        (r">", "File writing/overwriting redirection (>)"),
+        (r">>", "File appending redirection (>>)"),
+        (r"\|", "Pipeline redirection (|)"),
+    ]
+    
+    # Git mutation / modification
+    git_mutation_patterns = [
+        (r"\bgit\s+commit\b", "Git commit creation"),
+        (r"\bgit\s+push\b", "Git remote push"),
+        (r"\bgit\s+reset\b", "Git repository reset"),
+        (r"\bgit\s+checkout\b", "Git branch checkout/file discard"),
+        (r"\bgit\s+clean\b", "Git untracked file removal"),
+        (r"\bgit\s+merge\b", "Git branch merge"),
+        (r"\bgit\s+rebase\b", "Git branch rebase"),
+    ]
+    
+    # System and Process Control
+    system_patterns = [
+        (r"\bkill\b", "Process termination (kill)"),
+        (r"\btaskkill\b", "Process termination (taskkill)"),
+        (r"\bstop-process\b", "Process termination (Stop-Process)"),
+        (r"\bshutdown\b", "System shutdown"),
+        (r"\breboot\b", "System reboot"),
+        (r"\breg\b", "Windows Registry access"),
+    ]
+
+    all_patterns = (
+        destructive_patterns + 
+        execution_patterns + 
+        network_patterns + 
+        installer_patterns + 
+        redirection_patterns + 
+        git_mutation_patterns + 
+        system_patterns
+    )
+    
+    for pattern, name in all_patterns:
+        if re.search(pattern, cmd_lower):
+            # General safe check overrides
+            if "pytest" in cmd_lower and name in ["Python script execution", "Pipeline redirection (|)"]:
+                continue
+            if "git status" in cmd_lower and name == "Shell execution (sh)":
+                continue
+            if cmd_lower.strip() in ["python --version", "python -v"]:
+                continue
+            return False, name
+            
+    return True, ""
+
+
+# ─── Live shell state (shared with utim.py UI) ────────────────────────────────
+_SHELL_STATE = {
+    "proc":         None,
+    "cmd":          "",
+    "cwd":          "",
+    "output_lines": [],
+    "focused":      False,
+    "active":       False,
+    "_app_ref":     [None],
+}
+
+_MAX_SHELL_LINES = 50
+
+
+def _build_shell_argv(command: str, cwd: str) -> tuple:
+    """Return the argv list that executes *command* in the correct shell.
+
+    Returns a tuple of (argv_list, error_message). If error_message is not None,
+    the caller should return it instead of executing the command.
+
+    Dispatch rules
+    ──────────────
+    - Windows (native)  → powershell.exe -NoProfile -NonInteractive -Command …
+    - macOS / Linux     → bash -c …
+    """
+    if os.name == "nt":
+        return ["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", command], None
+    return ["bash", "-c", command], None
+
+
+def _run_single_command_internal(command: str, dir_path: str = "", timeout: int = 120) -> tuple:
+    """Core process runner logic returning (output_string, exit_code)."""
+    # Resolve working directory — fall back to process cwd
+    if dir_path:
+        cwd = os.path.abspath(dir_path)
+        if not os.path.isdir(cwd):
+            return f"Error: dir_path '{dir_path}' is not a valid directory.", -1
+    else:
+        cwd = os.getcwd()
+
+    argv, error_msg = _build_shell_argv(command, cwd)
+    if error_msg:
+        return error_msg, -1
+
+    try:
+        # On Windows with the subprocess list form, CREATE_NEW_PROCESS_GROUP
+        # lets us send CTRL_BREAK_EVENT to terminate the child tree cleanly.
+        _pg_flag = subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0
+        proc = subprocess.Popen(
+            argv,
+            shell=False,          # argv is already fully formed — no shell wrapper
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,   # capture stderr separately
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            cwd=cwd,
+            creationflags=_pg_flag,
+        )
+    except FileNotFoundError as e:
+        # Docker/PowerShell/bash not found — give a clear error
+        binary = argv[0]
+        return (
+            f"Error: could not start '{binary}'. "
+            f"Make sure it is installed and on your PATH.\nDetail: {e}", -1
+        )
+    except Exception as e:
+        return f"Error starting command: {e}", -1
+
+    # ── Update shell state so the UI panel can render immediately ─────────────
+    _SHELL_STATE["proc"]         = proc
+    _SHELL_STATE["cmd"]          = command
+    _SHELL_STATE["cwd"]          = cwd
+    _SHELL_STATE["output_lines"] = []
+    _SHELL_STATE["focused"]      = False
+    _SHELL_STATE["active"]       = True
+    _invalidate_ui()
+
+    stdout_parts: list = []
+    stderr_parts: list = []
+    cancel = _cancel_event  # snapshot so it can't change mid-run
+
+    # ── Stdout reader ─────────────────────────────────────────────────────────
+    def _stdout_reader():
+        try:
+            for raw in proc.stdout:
+                line = _strip_ansi(raw.rstrip("\n"))
+                stdout_parts.append(raw)
+                _SHELL_STATE["output_lines"].append(line)
+                if len(_SHELL_STATE["output_lines"]) > _MAX_SHELL_LINES:
+                    _SHELL_STATE["output_lines"].pop(0)
+                _invalidate_ui()
+        except Exception:
+            pass
+
+    # ── Stderr reader ─────────────────────────────────────────────────────────
+    def _stderr_reader():
+        try:
+            for raw in proc.stderr:
+                stderr_parts.append(raw)
+        except Exception:
+            pass
+
+    stdout_t = threading.Thread(target=_stdout_reader, daemon=True)
+    stderr_t = threading.Thread(target=_stderr_reader, daemon=True)
+    stdout_t.start()
+    stderr_t.start()
+
+    # ── Poll until process exits, is cancelled, or times out ───────────────
+    exit_code: int = 0
+    start_time = time.time()
+    try:
+        while True:
+            if cancel is not None and cancel.is_set():
+                _kill_proc(proc)
+                stdout_t.join(timeout=1)
+                stderr_t.join(timeout=1)
+                return "[Command aborted by user]", -1
+            if time.time() - start_time > timeout:
+                _kill_proc(proc)
+                stdout_t.join(timeout=1)
+                stderr_t.join(timeout=1)
+                return f"[Command timed out after {timeout} seconds]", -2
+            rc = proc.poll()
+            if rc is not None:
+                exit_code = rc
+                break
+            time.sleep(0.05)
+    finally:
+        _SHELL_STATE["active"]  = False
+        _SHELL_STATE["focused"] = False
+        _SHELL_STATE["proc"]    = None
+        _invalidate_ui()
+
+    stdout_t.join(timeout=2)
+    stderr_t.join(timeout=2)
+
+    stdout_text = "".join(stdout_parts)
+    stderr_text = "".join(stderr_parts)
+
+    # ── Build structured result ───────────────────────────────────────────────
+    parts = []
+    parts.append(f"[exit_code: {exit_code}]")
+    if stdout_text.strip():
+        parts.append("[stdout]")
+        parts.append(stdout_text.rstrip())
+    if stderr_text.strip():
+        parts.append("[stderr]")
+        parts.append(stderr_text.rstrip())
+    if not stdout_text.strip() and not stderr_text.strip():
+        parts.append("(no output)")
+
+    return "\n".join(parts), exit_code
+
+
+def run_command(command: str = "", dir_path: str = "", timeout: int = 120, commands: list = None) -> str:
+    """Execute a shell command (or list of commands sequentially) and return stdout, stderr, and exit code.
+
+    Parameters
+    ──────────
+    command  : the shell command string to run (single command)
+    dir_path : directory to run the command in (defaults to current working dir)
+    timeout  : maximum execution time in seconds (defaults to 120)
+    commands : list of shell commands to run in sequence (stops on first failure)
+    """
+    if commands is None:
+        if not command:
+            return "Error: No command specified."
+        commands = [command]
+    elif not commands:
+        return "Error: No commands specified in list."
+
+    if _DRY_RUN:
+        results = []
+        for cmd in commands:
+            results.append(f"--- Command: {cmd} ---\n[Dry Run] Simulated execution of: {cmd}\n(Exit Code: 0)")
+        return "\n\n".join(results)
+
+    results = []
+    for cmd in commands:
+        if _SANDBOX_MODE:
+            is_safe, reason = analyze_command_safety(cmd)
+            if not is_safe and not is_command_approved(cmd):
+                return f"Error: Command execution blocked by Intelligent Sandbox. Reason: {reason}."
+            _APPROVED_COMMANDS.discard(cmd)
+
+        res, code = _run_single_command_internal(cmd, dir_path, timeout)
+        results.append(f"--- Command: {cmd} ---\n{res}")
+        if code != 0:
+            results.append(f"\n[Execution halted due to non-zero exit code: {code}]")
+            break
+
+    return "\n\n".join(results)
+
+
+def _kill_proc(proc):
+    """Terminate a Popen process cross-platform."""
+    try:
+        import signal as _sig
+        if os.name == "nt":
+            proc.terminate()
+        else:
+            os.kill(proc.pid, _sig.SIGTERM)
+        proc.wait(timeout=3)
+    except Exception:
+        try:
+            proc.kill()
+        except Exception:
+            pass
+
+
+def _invalidate_ui():
+    """Ask the prompt_toolkit app to redraw (called from background threads)."""
+    app = _SHELL_STATE["_app_ref"][0]
+    if app is not None:
+        try:
+            if app.renderer and not getattr(app.renderer, "waiting_for_cpr", False):
+                app.invalidate()
+        except Exception:
+            pass
+
+
+def shell_send_input(text: str):
+    """Write text to the running shell process stdin (called from UI key handler)."""
+    proc = _SHELL_STATE.get("proc")
+    if proc and proc.stdin and not proc.stdin.closed:
+        try:
+            proc.stdin.write(text)
+            proc.stdin.flush()
+        except Exception:
+            pass
+
+
+def shell_send_ctrl_c():
+    """Kill the running shell process instantly (Ctrl+C scoped to shell only).
+
+    On Windows: uses 'taskkill /f /t' to force-kill the entire process tree
+    (cmd.exe + any child processes like npm/node) — equivalent to closing a
+    terminal window. This is more reliable than CTRL_BREAK_EVENT which can
+    be slow or ignored by grandchild processes when shell=True is used.
+
+    On Unix: sends SIGINT to the process group so all children receive it.
+    """
+    import signal as _sig
+    proc = _SHELL_STATE.get("proc")
+    if proc is None:
+        return
+    try:
+        if os.name == "nt":
+            # Force-kill the whole process tree instantly
+            subprocess.run(
+                ["taskkill", "/f", "/t", "/pid", str(proc.pid)],
+                capture_output=True,
+            )
+        else:
+            # Send SIGINT to the entire process group (pid < 0 targets group)
+            try:
+                os.killpg(os.getpgid(proc.pid), _sig.SIGINT)
+            except Exception:
+                os.kill(proc.pid, _sig.SIGINT)
+    except Exception:
+        try:
+            proc.terminate()
+        except Exception:
+            pass
+
+
+def list_directory(path: str = ".") -> str:
+    """Lists the files and directories in a given path."""
+    try:
+        items = os.listdir(path)
+        return f"Contents of {path}:\n" + "\n".join(items)
+    except Exception as e:
+        return f"Error listing directory: {str(e)}"
+
+def web_search(prompt: str, level: str = "medium") -> str:
+    """Performs an agentic deep web research based on the prompt and level.
+    
+    Concurrent scraping is used to fetch raw web page contents in parallel to enrich Tavily search snippets.
+    """
+    import concurrent.futures
+    import re
+    import html as html_lib
+    import time
+    
+    api_key = os.getenv("TAVILY_API_KEY")
+    from utim_cli.config import config
+    llm_key = os.getenv("OPENROUTER_API_KEY") or config.get("api_key")
+    if not api_key:
+        return "Error: TAVILY_API_KEY environment variable is not set."
+    if not llm_key:
+        return "Error: Neither UTIM API key nor OPENROUTER_API_KEY environment variable is set. The research agent needs an LLM key."
+
+    num_queries = {"low": 1, "medium": 4, "high": 8}.get(level.lower(), 4)
+
+    # 1. Generate search queries optimized for keyword-matching search engines
+    try:
+        from utim_cli.bootstrap import get_subagent_rag_context
+        subagent_rag_ctx = get_subagent_rag_context("web_search", prompt)
+    except Exception:
+        subagent_rag_ctx = ""
+        
+    system_prompt = (
+        "You are a search engine query optimizer. Generate exactly {num_queries} distinct, short, "
+        "keyword-based search queries (not full sentences) optimized for a standard keyword-matching "
+        "search engine to research the following prompt. Keep each query under 5-6 words. "
+        "Output ONLY the queries, one per line. Do not use quotes, bullet points, numbering, or extra text."
+    ).format(num_queries=num_queries)
+    if subagent_rag_ctx:
+        system_prompt += f"\n\n{subagent_rag_ctx}"
+    
+    models_to_try = [
+        "liquid/lfm-2.5-1.2b-instruct:free",
+        "qwen/qwen3-coder:free",
+        "google/gemma-3-27b-it:free",
+    ]
+    
+    queries = []
+    for model in models_to_try:
+        try:
+            query_gen_payload = {
+                "model": model,
+                "messages": [
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": prompt}
+                ]
+            }
+            from utim_cli.client_utils import proxy_openrouter_request
+            resp = proxy_openrouter_request(json_data=query_gen_payload, stream=False, timeout=20)
+            if resp.status_code == 200:
+                queries_text = resp.json()["choices"][0]["message"]["content"]
+                lines = [q.strip("- *1234567890.\"") for q in queries_text.splitlines() if q.strip()]
+                queries = [q for q in lines if len(q.split()) <= 8][:num_queries]
+                if queries:
+                    break
+        except Exception:
+            continue
+
+    if not queries:
+        # Heuristic fallback to turn prompt into keywords if LLMs are down or returned empty results
+        import re
+        s = re.sub(r"[^\w\s\-\/\.]", " ", prompt)
+        words = s.split()
+        stop_words = {
+            "find", "search", "specifically", "the", "a", "an", "and", "or", "but", "in", "on", 
+            "at", "to", "for", "with", "by", "about", "against", "from", "how", "what", "which", 
+            "who", "why", "where", "when", "are", "is", "was", "were", "be", "been", "being", 
+            "have", "has", "had", "do", "does", "did", "recommendations", "recommendation",
+            "reputable", "review", "reviews", "sites", "site", "sources", "source", "top", "picks",
+            "include", "source", "names", "links", "link"
+        }
+        keywords = [w for w in words if w.lower() not in stop_words]
+        fallback_query = " ".join(keywords[:6]) if keywords else " ".join(words[:6])
+        queries = [fallback_query]
+
+    # 2. Execute searches in parallel
+    search_results = []
+    
+    def fetch_query(q):
+        results = []
+        try:
+            tavily_resp = requests.post("https://api.tavily.com/search", json={
+                "api_key": api_key,
+                "query": q,
+                "search_depth": "advanced",
+                "include_raw_content": False,
+                "max_results": 10
+            }, timeout=20)
+            if tavily_resp.status_code == 200:
+                results = tavily_resp.json().get("results", [])
+        except Exception:
+            pass
+            
+        if not results:
+            # Fallback 1: Try Mojeek Search (very friendly to scrapers, returns status 200)
+            try:
+                from bs4 import BeautifulSoup
+                import urllib.parse
+                headers = {
+                    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
+                    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
+                    'Accept-Language': 'en-US,en;q=0.5',
+                }
+                encoded_q = urllib.parse.quote(q)
+                mojeek_url = f"https://www.mojeek.com/search?q={encoded_q}"
+                resp = requests.get(mojeek_url, headers=headers, timeout=10)
+                if resp.status_code == 200:
+                    soup = BeautifulSoup(resp.text, 'html.parser')
+                    items = soup.find_all('li')
+                    for r in items:
+                        title_el = r.find('h2') or r.find('a', class_='title')
+                        if not title_el:
+                            continue
+                        link_el = title_el.find('a') if title_el.name == 'h2' else title_el
+                        desc_el = r.find('p', class_='s') or r.find('p', class_='snippet') or r.find('p')
+                        
+                        if link_el:
+                            link = link_el.get('href', '')
+                            if link.startswith('/') or 'mojeek.com' in link:
+                                continue
+                            title = title_el.get_text(strip=True)
+                            desc = desc_el.get_text(strip=True) if desc_el else ""
+                            results.append({
+                                'url': link,
+                                'title': title,
+                                'content': desc
+                            })
+            except Exception:
+                pass
+
+        if not results:
+            # Fallback 2: Try Yahoo Search (returns status 200, highly reliable index)
+            try:
+                from bs4 import BeautifulSoup
+                import urllib.parse
+                headers = {
+                    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
+                    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
+                }
+                encoded_q = urllib.parse.quote(q)
+                yahoo_url = f"https://search.yahoo.com/search?p={encoded_q}"
+                resp = requests.get(yahoo_url, headers=headers, timeout=10)
+                if resp.status_code == 200:
+                    soup = BeautifulSoup(resp.text, 'html.parser')
+                    items = soup.find_all('div', class_='algo')
+                    for r in items:
+                        link_el = r.find('a')
+                        desc_el = r.find('div', class_='compText') or r.find('span', class_='compText') or r.find('p')
+                        
+                        if link_el:
+                            link = link_el.get('href', '')
+                            # Unquote Yahoo redirect URL if present
+                            if "/RU=" in link:
+                                try:
+                                    parts = link.split("/RU=")
+                                    if len(parts) > 1:
+                                        target = parts[1].split("/RK=")[0]
+                                        link = urllib.parse.unquote(target)
+                                except:
+                                    pass
+                            
+                            title = link_el.get_text(strip=True)
+                            desc = desc_el.get_text(strip=True) if desc_el else ""
+                            results.append({
+                                'url': link,
+                                'title': title,
+                                'content': desc
+                            })
+            except Exception as e:
+                pass
+                
+        return results
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
+        futures = [executor.submit(fetch_query, q) for q in queries]
+        for future in concurrent.futures.as_completed(futures):
+            search_results.extend(future.result())
+
+    if not search_results:
+        return "No results found during research. The search APIs or fallback endpoints may be blocked or unreachable."
+
+    # 3. Extract unique URLs to scrape raw content in parallel
+    unique_urls = []
+    seen_urls = set()
+    for r in search_results:
+        url = r.get("url")
+        if url and url not in seen_urls:
+            seen_urls.add(url)
+            unique_urls.append(url)
+            
+    # Take top 4 URLs to scrape using enhanced Scrapy-based scraper
+    urls_to_scrape = unique_urls[:4]
+    scraped_contents = {}
+
+    # Try to use Scrapy-enhanced scraper for better crawling
+    try:
+        from .scrapy_search import enhanced_scrape_urls
+        scraped_contents = enhanced_scrape_urls(urls_to_scrape, use_js=False, timeout=10)
+    except ImportError:
+        # Fall back to original requests-based scraping if Scrapy not available
+        def scrape_url_raw(url):
+            try:
+                headers = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"}
+                r = requests.get(url, headers=headers, timeout=10)
+                if r.status_code == 200:
+                    html_content = r.text
+                    # Remove scripts, styles
+                    html_content = re.sub(r'<(script|style).*?>.*?</\1>', '', html_content, flags=re.DOTALL | re.IGNORECASE)
+                    # Remove html tags
+                    text = re.sub(r'<.*?>', ' ', html_content)
+                    text = html_lib.unescape(text)
+                    # Format whitespace
+                    lines = [l.strip() for l in text.splitlines() if l.strip()]
+                    return url, "\n".join(lines)[:6000]
+            except Exception:
+                pass
+            return url, ""
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
+            scrape_futures = [executor.submit(scrape_url_raw, url) for url in urls_to_scrape]
+            for future in concurrent.futures.as_completed(scrape_futures):
+                url, content = future.result()
+                if content:
+                    scraped_contents[url] = content
+
+    # 4. Build aggregated context payload
+    aggregated_context = []
+    for r in search_results[:15]:  # limit snippets to keep context clean
+        url = r.get("url")
+        snippet = r.get("content", "")
+        scraped = scraped_contents.get(url, "")
+        
+        entry = f"Source URL: {url}\nSnippet: {snippet}"
+        if scraped:
+            entry += f"\nFull Scraped Page Body:\n{scraped}"
+        aggregated_context.append(entry)
+
+    full_context = "\n\n========================================\n\n".join(aggregated_context)[:60000]
+
+    # 5. Summarize and reason with fallback
+    models_to_try = [
+        "qwen/qwen3-coder:free",
+        "poolside/laguna-xs.2:free",
+        "nvidia/nemotron-3-super-120b-a12b:free",
+        "nvidia/nemotron-3-nano-30b-a3b:free",
+        "qwen/qwen3-next-80b-a3b-instruct:free",
+        "openrouter/free"
+    ]
+    last_err = None
+    
+    for model in models_to_try:
+        model_retries = 2
+        for attempt in range(model_retries + 1):
+            try:
+                try:
+                    from utim_cli.bootstrap import get_subagent_rag_context
+                    subagent_rag_ctx = get_subagent_rag_context("web_search", prompt)
+                except Exception:
+                    subagent_rag_ctx = ""
+                
+                sys_prompt = "You are a Deep Research AI. Analyze the provided search results and crawler content, then create a comprehensive, detailed, and properly structured technical information summary that addresses the user's research prompt. Focus on extracting exact facts, code snippets, configurations, documentation, and reasoning. Do not add conversational filler. Synthesize the data from all the sources into a highly informative report."
+                if subagent_rag_ctx:
+                    sys_prompt += f"\n\n{subagent_rag_ctx}"
+                    
+                summary_payload = {
+                    "model": model,
+                    "messages": [
+                        {"role": "system", "content": sys_prompt},
+                        {"role": "user", "content": f"Research Prompt: {prompt}\n\nSearch Results and Scraped Pages:\n{full_context}"}
+                    ],
+                    "stream": True
+                }
+                from utim_cli.client_utils import proxy_openrouter_request
+                resp = proxy_openrouter_request(json_data=summary_payload, stream=True, timeout=(15, 120))
+                resp.raise_for_status()
+                
+                summary = ""
+                start_time = time.time()
+                last_token_time = start_time
+                for raw_line in resp.iter_lines(decode_unicode=True):
+                    if _cancel_event and _cancel_event.is_set():
+                        return "Error: User cancelled the research process."
+                    now = time.time()
+                    if now - start_time > 600:  # 10 minute absolute max
+                        raise Exception("Hard timeout exceeded (10m)")
+                    if now - last_token_time > 60: # 60 seconds idle timeout
+                        raise Exception("Idle timeout: no tokens received for 60s")
+                    if not raw_line or not raw_line.startswith("data: "):
+                        continue
+                    data_str = raw_line[6:]
+                    if data_str == "[DONE]":
+                        break
+                    import json
+                    try:
+                        chunk = json.loads(data_str)
+                    except Exception:
+                        continue
+                    
+                    if "error" in chunk:
+                        raise Exception(chunk["error"].get("message", "API Error"))
+                        
+                    try:
+                        delta = chunk["choices"][0].get("delta", {})
+                        if "content" in delta and delta["content"]:
+                            summary += delta["content"]
+                            last_token_time = time.time()
+                    except Exception:
+                        continue
+                
+                summary = re.sub(r"<think(?:ing)?>.*?</think(?:ing)?>", "", summary, flags=re.DOTALL).strip()
+                if not summary:
+                    raise Exception("Model returned empty summary after parsing.")
+                
+                # Save the research report to .utim_tmp/web_search_{timestamp}.md
+                try:
+                    os.makedirs(".utim_tmp", exist_ok=True)
+                    timestamp = int(time.time())
+                    report_file = f".utim_tmp/web_search_{timestamp}.md"
+                    
+                    # Format queries
+                    queries_formatted = "\n".join(f"- `{q}`" for q in queries)
+                    
+                    # Format sources
+                    sources_formatted = "\n".join(f"- {url}" for url in unique_urls[:15])
+                    
+                    report_content = f"""# Web Research Report
+
+- **Research Prompt:** {prompt}
+- **Date/Time:** {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(timestamp))}
+- **Research Level:** {level}
+
+## Search Queries
+{queries_formatted}
+
+## Sources Explored
+{sources_formatted}
+
+---
+
+## Research Findings
+
+{summary}
+"""
+                    with open(report_file, "w", encoding="utf-8") as f:
+                        f.write(report_content)
+                    
+                    # Append a footnote about where the file was saved
+                    summary += f"\n\n*(Detailed research report saved to `{report_file}`)*"
+                except Exception:
+                    pass
+                
+                return summary
+            except requests.exceptions.HTTPError as e:
+                code = e.response.status_code if e.response is not None else 0
+                if code == 429 and attempt < model_retries:
+                    time.sleep(5 * (attempt + 1))
+                    continue
+                last_err = e
+                break
+            except Exception as e:
+                last_err = e
+                break
+            
+    return f"Error generating research summary after trying all fallback models: {last_err}"
+
+
+def plan_project(plan_part: str, prompt: str, context: str = "") -> str:
+    """Spawns a specialized sub-agent to plan a specific part of the project."""
+    from utim_cli.config import config
+    llm_key = os.getenv("OPENROUTER_API_KEY") or config.get("api_key")
+    if not llm_key:
+        return "Error: Neither UTIM API key nor OPENROUTER_API_KEY environment variable is set."
+
+    # Map plan parts to specific roles
+    roles = {
+        "design": """You are an expert UI/UX Design Architect. Your task is to architect a comprehensive, realistic design system and a granular component breakdown for the requested application or feature. 
+
+Do not speak in broad design generalities; instead, provide concrete, production-ready specifications.
+
+For every project, you must deliver:
+1. **Design Tokens & Theme:** 
+   - A precise color palette including exact HEX codes (Primary, Secondary, Neutrals, Semantic/Status colors). Specify accessible contrast ratios (WCAG AA/AAA).
+   - Typography scale specified in rem/px (Font families, weights, sizes, and line-heights for Headings, Body, and Captions).
+   - Global layout rules (Grid structure, spacing scale in a 4px/8px base, and border-radius tokens).
+
+2. **Component Architecture & Hierarchy:**
+   - Break down the core interface into atoms, molecules, and organisms (Atomic Design methodology).
+   - Detail the structural hierarchy—exactly how components nest within each other for this specific layout.
+
+3. **Interactive States & Edge Cases:**
+   - Define exact visual transformations for interactive components across all states: Default, Hover, Active, Focus (including outline styles), Disabled, and Loading.
+   - Specify responsive behavior (Mobile vs. Desktop layout shifts) and how empty or error states are handled visually.
+
+Structure your response using clear headers, markdown tables for tokens, and bulleted lists for structural breakdowns. Maintain a technical, precise, and highly analytical tone.
+
+If the project is a PowerPoint presentation (PPT/slide deck), document, or non-software asset, adapt the design plan to specify page/slide layouts, slide structure, visual themes, color palette, typography, and content alignment instead of UI components.""",
+        "architecture": """You are a Senior Systems Architect. Produce a production-ready architecture plan that an engineering team can act on immediately. Cover these without fluff:
+- **Stack**: Recommend specific tools/frameworks/services with one-line justifications and key trade-offs
+- **Structure**: Directory layout with clear separation of concerns (presentation / logic / data / infra)
+- **Data Flow**: Request lifecycle, sync vs async boundaries, ASCII component diagram
+- **API Design**: Endpoints, auth strategy (JWT/OAuth2), versioning, rate limiting, error contracts
+- **State**: Client/server/shared state boundaries, caching layers (Redis/CDN) + invalidation strategy
+- **Scalability**: Bottlenecks, failover, circuit breakers, horizontal scaling approach
+- **Security**: AuthN/AuthZ model, encryption at rest/transit, top OWASP risks for this system
+- **Deployment**: CI/CD shape, containerization (Docker/K8s), environment strategy (dev/staging/prod)
+
+Rules: Be opinionated. Flag assumptions. Prefer simple over clever. No filler.
+
+If the project is a PowerPoint presentation (PPT/slide deck), document, or non-software asset, adapt the architecture to specify the outline, slide hierarchy, layout structures, and narration/presentation flow rather than directories, APIs, and scaling strategies.""",
+        "security": """You are a world-class Security Engineer and Application Security Architect. Design a comprehensive, production-grade security strategy for the entire system. Analyze the application from an attacker’s perspective and identify potential vulnerabilities, attack vectors, trust boundaries, and high-risk components. Define secure authentication and authorization flows including RBAC, ABAC, OAuth2, JWT, session management, MFA, device trust, and secure token lifecycle handling. Specify data protection strategies for data at rest, in transit, and in use using modern encryption standards, key rotation, secrets management, hashing, salting, and secure credential storage. Enforce secure coding practices aligned with OWASP Top 10, SANS, and modern AppSec standards. Include API security, rate limiting, input validation, output encoding, CSRF/XSS/SQLi prevention, SSRF protection, CSP policies, sandboxing, dependency auditing, supply chain security, and secure file handling. Design infrastructure and cloud security including network isolation, firewalls, WAF, IAM policies, zero-trust architecture, container security, CI/CD hardening, runtime monitoring, and intrusion detection. Define logging, auditing, anomaly detection, threat monitoring, incident response workflows, backup/recovery strategies, and compliance considerations (GDPR, SOC2, HIPAA if applicable). Provide actionable recommendations, architecture-level protections, and implementation-level safeguards with clear reasoning behind every security decision.
+
+If the project is a PowerPoint presentation (PPT/slide deck), document, or non-software asset, adapt this plan to cover data confidentiality, distribution controls, or access control policies for the final document.""",
+        "database": """You are an expert Database Administrator. Create a detailed database schema, relationships, indexing strategies, and query optimization plans.
+
+If the project is a PowerPoint presentation (PPT/slide deck), document, or non-software asset, adapt this plan to detail data collection, slide tables/graphics data, or information schemas required for the content.""",
+        "verification": """You are an elite QA Engineer, Senior Software Architect, and Principal Code Reviewer specializing in deep system validation, debugging, and production-grade quality assurance. Thoroughly analyze the provided codebase, runtime behavior, logs, stack traces, UI output, architecture decisions, and all available context. Compare the implementation against the original requirements, design specifications, expected workflows, and intended user experience. Detect and explain all bugs, edge-case failures, race conditions, performance bottlenecks, memory leaks, state management issues, accessibility problems, security risks, responsiveness issues, missing features, broken integrations, and architectural inconsistencies. Identify missing or incorrect CSS, layout instability, animation glitches, typography inconsistencies, spacing/alignment problems, responsive design failures, and deviations from the intended visual design system. Validate frontend, backend, APIs, database interactions, authentication flows, caching behavior, and asynchronous operations. Analyze error logs deeply to trace root causes instead of only identifying surface-level failures. Detect bad coding practices, dead code, duplicated logic, anti-patterns, scalability concerns, and maintainability risks. Verify proper handling of loading states, empty states, retries, failures, permissions, validation, and edge-case user interactions. Ensure adherence to clean architecture principles, secure coding standards, performance optimization practices, and framework best practices. Output a highly structured, strict, implementation-focused checklist of exact fixes required. Each checklist item must include: the issue, root cause, affected component/file if identifiable, severity level, exact corrective action, and why the fix is necessary. Prioritize issues intelligently from critical to low priority and ensure the output is actionable enough for direct implementation without ambiguity.
+
+If the project is a PowerPoint presentation (PPT/slide deck), document, or non-software asset, adapt the verification checklist to cover readability, styling consistency, formatting alignment, visual appeal, grammar, and completeness of content against requirements."""
+    }
+    
+    system_role = roles.get(plan_part.lower(), "You are an expert Technical Planner. Create a detailed implementation plan for the requested domain.")
+    
+    system_content = (
+        f"{system_role}\n\n"
+        "CRITICAL PLANNING DIRECTIVES:\n"
+        "1. DO NOT WRITE CODE SNIPPETS, programming scripts, programming code, or function definitions in the plan. The goal of this planning agent is to design high-level/low-level architectures, layouts, sequential steps, schemas, and outlines. Avoid writing actual code blocks.\n"
+        "2. RESPECT THE SPECIFIC PROJECT FORMAT. If the user requested a PowerPoint presentation (PPT/slide deck), document, or non-software asset, adapt the plan to match that format entirely. Do not default to website, UI components, directory structures, or API routes. Detail the slide structure, narration points, visual elements, content outlines, and page layouts instead."
+    )
+    
+    try:
+        from utim_cli.bootstrap import get_subagent_rag_context
+        subagent_rag_ctx = get_subagent_rag_context("plan_project", prompt)
+        if subagent_rag_ctx:
+            system_content += f"\n\n{subagent_rag_ctx}"
+    except Exception:
+        pass
+    
+    # Gather workspace/project context
+    workspace_context = ""
+    try:
+        if os.path.exists("."):
+            items = [item for item in os.listdir(".") if not item.startswith(".") and item not in ("__pycache__", "node_modules", "build", "dist")]
+            if items:
+                workspace_context += f"Existing workspace files/folders: {', '.join(items)}\n"
+            # Read snippet of key project files
+            for key_file in ["package.json", "requirements.txt", "setup.py", "README.md"]:
+                if os.path.exists(key_file):
+                    try:
+                        with open(key_file, "r", encoding="utf-8") as f:
+                            workspace_context += f"\nSnippet of {key_file}:\n{f.read(1500)}\n"
+                    except Exception:
+                        pass
+    except Exception:
+        pass
+
+    user_content = f"Project Prompt: {prompt}\n"
+    if workspace_context:
+        user_content += f"\nWorkspace & Project Context:\n{workspace_context}\n"
+    if context:
+        user_content += f"\nPrevious Context/Other Plans:\n{context}\n"
+        
+    models_to_try = [
+        "qwen/qwen3-coder:free",
+        "poolside/laguna-xs.2:free",
+        "nvidia/nemotron-3-super-120b-a12b:free",
+        "nvidia/nemotron-3-nano-30b-a3b:free",
+        "qwen/qwen3-next-80b-a3b-instruct:free",
+        "openrouter/free"
+    ]
+    last_err = None
+    
+    for model in models_to_try:
+        model_retries = 2
+        for attempt in range(model_retries + 1):
+            try:
+                payload = {
+                    "model": model,
+                    "messages": [
+                        {"role": "system", "content": system_content},
+                        {"role": "user", "content": user_content}
+                    ],
+                    "stream": True
+                }
+                import time
+                from utim_cli.client_utils import proxy_openrouter_request
+                resp = proxy_openrouter_request(json_data=payload, stream=True, timeout=(15, 120))
+                resp.raise_for_status()
+                
+                plan = ""
+                start_time = time.time()
+                last_token_time = start_time
+                for raw_line in resp.iter_lines(decode_unicode=True):
+                    if _cancel_event and _cancel_event.is_set():
+                        return "Error: User cancelled the planning process."
+                    now = time.time()
+                    if now - start_time > 900:  # 15 minute absolute max for planning
+                        raise Exception("Hard timeout exceeded (15m)")
+                    if now - last_token_time > 120: # 120 seconds idle timeout for planning (models can think a long time)
+                        raise Exception("Idle timeout: no tokens received for 120s")
+                    if not raw_line or not raw_line.startswith("data: "):
+                        continue
+                    data_str = raw_line[6:]
+                    if data_str == "[DONE]":
+                        break
+                    import json
+                    try:
+                        chunk = json.loads(data_str)
+                    except Exception:
+                        continue
+    
+                    if "error" in chunk:
+                        raise Exception(chunk["error"].get("message", "API Error"))
+    
+                    try:
+                        delta = chunk["choices"][0].get("delta", {})
+                        if "content" in delta and delta["content"]:
+                            plan += delta["content"]
+                            last_token_time = time.time()
+                    except Exception:
+                        continue
+    
+                # Clean up thinking tags
+                import re
+                plan = re.sub(r"<think(?:ing)?>.*?</think(?:ing)?>", "", plan, flags=re.DOTALL).strip()
+    
+                if not plan:
+                    raise Exception("Model returned empty plan after parsing.")            
+                
+                # Save the plan to disk
+                os.makedirs(".utim_tmp/plans", exist_ok=True)
+                plan_file = f".utim_tmp/plans/{plan_part.lower()}_plan.md"
+                with open(plan_file, "w", encoding="utf-8") as f:
+                    f.write(plan)
+                
+                return f"Plan successfully generated and saved to {plan_file}. Please read this file when you need to implement the detailed {plan_part} plan."
+            except requests.exceptions.HTTPError as e:
+                code = e.response.status_code if e.response is not None else 0
+                if code == 429 and attempt < model_retries:
+                    time.sleep(5 * (attempt + 1))
+                    continue
+                last_err = e
+                break
+            except Exception as e:
+                last_err = e
+                break
+            
+    return f"Error generating plan after trying all fallback models: {last_err}"
+
+
+
+# ─────────────────────────────────────────────────────────────────────────────────
+# Caching infrastructure for query_codebase
+# ─────────────────────────────────────────────────────────────────────────────────
+
+_query_cache = {}  # {query_hash: {"time": float, "result": str, "keywords": list}}
+_file_index_cache = {"mtime": 0, "files": {}}  # Persistent file mtime cache
+_index_timestamp = 0
+_INDEX_CACHE_TTL = 300  # 5 minutes
+
+def _get_query_cache_key(query: str) -> str:
+    """Generate a cache key from the query."""
+    import hashlib
+    normalized = query.lower().strip()[:100]
+    return hashlib.md5(normalized.encode()).hexdigest()[:16]
+
+def _extract_keywords_fast(query: str) -> list:
+    """Fast local keyword extraction without LLM calls.
+    
+    Uses heuristics to extract technical identifiers, function names, 
+    class names, and file patterns from the query.
+    """
+    import re
+    # Extract potential variable/class/function names (camelCase, snake_case, PascalCase)
+    patterns = [
+        r'\b[A-Za-z_][A-Za-z0-9_]{3,}\b',  # Standard identifiers
+        r'\b[A-Z][a-z]+[A-Z][a-z]+\b',     # PascalCase (class names)
+        r'\b[a-z]+[A-Z][a-z]+\b',          # camelCase
+    ]
+    
+    keywords = set()
+    for pattern in patterns:
+        matches = re.findall(pattern, query)
+        for m in matches:
+            if len(m) > 2:  # Minimum length
+                keywords.add(m)
+    
+    # Also extract file extensions and known tech terms
+    tech_terms = re.findall(r'\b(js|ts|py|java|cpp|go|rs|rb|php|html|css|json|yaml|xml|sql)\b', query, re.I)
+    keywords.update(t.lower() for t in tech_terms)
+    
+    return list(keywords)[:5]  # Limit to 5 keywords
+
+def query_codebase(query: str) -> str:
+    """Acts as a local RAG. Optimized for speed with caching and intelligent keyword extraction.
+    
+    Speed optimizations:
+    - Query result caching (60s TTL)
+    - Fast local keyword extraction (no LLM call for keyword generation)
+    - Persistent file mtime caching
+    - Fast synthesis model first (liquid/lfm-2.5-1.2b-instruct:free)
+    - Reduced timeouts and smarter fallbacks
+    """
+    import os
+    import requests
+    import json
+    import sqlite3
+    import re
+    import time
+    
+    global _query_cache, _file_index_cache, _index_timestamp
+    
+    from utim_cli.config import config
+    llm_key = os.getenv("OPENROUTER_API_KEY") or config.get("api_key")
+    if not llm_key:
+        return "Error: Neither UTIM API key nor OPENROUTER_API_KEY environment variable is set."
+
+    # ── 1. Check query cache first (60s TTL) ─────────────────────────────
+    cache_key = _get_query_cache_key(query)
+    now = time.time()
+    if cache_key in _query_cache:
+        cached = _query_cache[cache_key]
+        if now - cached["time"] < 60:  # 60 second cache
+            return cached["result"]
+    
+    # ── 2. Fast local keyword extraction (no LLM) ───────────────────────
+    keywords = _extract_keywords_fast(query)
+    if not keywords:
+        # Fallback: use raw words from query
+        keywords = [w for w in query.lower().split() if len(w) > 3][:4]
+    
+    if not keywords:
+        return "Could not extract searchable keywords from query."
+    
+    # ── 3. Optimized file indexing with persistent cache ─────────────────
+    db_path = ".utim_tmp/codebase_fts.db"
+    os.makedirs(".utim_tmp", exist_ok=True)
+    
+    try:
+        conn = sqlite3.connect(db_path)
+        cur = conn.cursor()
+        
+        # Quick table setup
+        cur.execute("CREATE VIRTUAL TABLE IF NOT EXISTS files USING fts5(path, content);")
+        cur.execute("CREATE TABLE IF NOT EXISTS file_meta (path TEXT PRIMARY KEY, mtime REAL);")
+        
+        # Check if we need to update the index (only if 5+ minutes old)
+        cur.execute("SELECT last_modified FROM sqlite_master WHERE type='table' AND name='files'")
+        table_info = cur.fetchone()
+        
+        need_index = False
+        if table_info is None:
+            need_index = True
+        elif now - _index_timestamp > _INDEX_CACHE_TTL:
+            need_index = True
+        else:
+            # Quick check: see if any files changed
+            try:
+                cur.execute("SELECT path, mtime FROM file_meta LIMIT 20")
+                cached_meta = {row[0]: row[1] for row in cur.fetchall()}
+                for p in list(cached_meta.keys())[:5]:
+                    if os.path.exists(p):
+                        if abs(os.path.getmtime(p) - cached_meta.get(p, 0)) > 1:
+                            need_index = True
+                            break
+            except Exception:
+                need_index = True
+        
+        if need_index:
+            # Mini-indexing: only check a sample of files for changes
+            current_files = {}
+            for root, dirs, files in os.walk("."):
+                dirs[:] = [d for d in dirs if d not in [".git", "node_modules", "dist", "build", "__pycache__", ".venv", "venv", ".utim_tmp"]]
+                for f in files[:50]:  # Limit to 50 files per directory for speed
+                    ext = os.path.splitext(f)[1].lower()
+                    if ext in ['.png', '.jpg', '.jpeg', '.gif', '.mp4', '.pdf', '.zip', '.exe', '.dll', '.pyc', '.sqlite', '.db']:
+                        continue
+                    p = os.path.join(root, f)
+                    try:
+                        current_files[p] = os.path.getmtime(p)
+                    except Exception:
+                        pass
+            
+            # Update index incrementally
+            cur.execute("SELECT path, mtime FROM file_meta")
+            existing = {row[0]: row[1] for row in cur.fetchall()}
+            
+            for p, mtime in current_files.items():
+                if p not in existing or existing[p] < mtime - 1:
+                    try:
+                        with open(p, "r", encoding="utf-8") as f:
+                            content = f.read()[:30000]  # Limit content size
+                        cur.execute("INSERT OR REPLACE INTO files (path, content) VALUES (?, ?)", (p, content))
+                        cur.execute("INSERT OR REPLACE INTO file_meta (path, mtime) VALUES (?, ?)", (p, mtime))
+                    except Exception:
+                        pass
+            
+            conn.commit()
+            _index_timestamp = now
+            _file_index_cache = {"mtime": now, "files": current_files}
+    except Exception as e:
+        pass
+
+    # ── 4. FTS5 Search ────────────────────────────────────────────────────
+    try:
+        match_query = " OR ".join('"{}"'.format(kw.replace('"', '')) for kw in keywords[:5])
+        cur.execute("SELECT path, content FROM files WHERE files MATCH ? ORDER BY rank LIMIT 5", (match_query,))
+        results = cur.fetchall()
+        conn.close()
+    except Exception as e:
+        try:
+            conn.close()
+        except:
+            pass
+        return f"Database search error: {e}"
+    
+    if not results:
+        return f"No relevant code found for keywords: {', '.join(keywords)}"
+
+    # ── 5. Fast synthesis with optimized model order ─────────────────────
+    context = ""
+    for path, content in results[:4]:  # Limit to 4 files for speed
+        if len(content) > 6000:
+            content = content[:6000] + "\n...[truncated]"
+        context += f"\n--- {path} ---\n{content}\n"
+
+    synth_payload = {
+        "messages": [
+            {"role": "system", "content": "You are a senior developer. Answer the query concisely using only the provided context. Include relevant code snippets."},
+            {"role": "user", "content": f"Query: {query}\n\nContext:\n{context}"}
+        ]
+    }
+    
+    # Fast synthesis model first, with reduced timeout
+    fast_models = [
+        "liquid/lfm-2.5-1.2b-instruct:free",  # Fastest
+        "nex-agi/nex-n2-pro:free",      # Good balance
+        "qwen/qwen3-coder:free",              # Fallback
+    ]
+    
+    answer = ""
+    for model in fast_models:
+        try:
+            synth_payload["model"] = model
+            from utim_cli.client_utils import proxy_openrouter_request
+            resp = proxy_openrouter_request(json_data=synth_payload, stream=False, timeout=25)
+            if resp.status_code == 200:
+                answer = resp.json()["choices"][0]["message"]["content"]
+                answer = re.sub(r"<think(?:ing)?>.*?</think(?:ing)?>", "", answer, flags=re.DOTALL).strip()
+                if answer:
+                    break
+        except Exception:
+            continue
+
+    if not answer:
+        # Return raw context without synthesis
+        answer = f"Found relevant files but synthesis failed. Keywords: {', '.join(keywords)}\n\n{context[:2000]}"
+
+    # ── 6. Cache the result ───────────────────────────────────────────────
+    _query_cache[cache_key] = {"time": now, "result": answer, "keywords": keywords}
+    if len(_query_cache) > 20:
+        _query_cache = dict(list(_query_cache.items())[-10:])
+    
+    return answer
+
+
+def manage_todos(action: str = "", task_id: str = "", description: str = "", operations: list = None) -> str:
+    """Manages the project to-do list. Supports batch operations."""
+    
+    todo_file = ".utim_tmp/todos.json"
+    os.makedirs(".utim_tmp", exist_ok=True)
+    
+    todos = {}
+    if os.path.exists(todo_file):
+        try:
+            with open(todo_file, "r", encoding="utf-8") as f:
+                todos = json.load(f)
+        except Exception:
+            pass
+
+    ops = operations if operations else [{"action": action, "task_id": task_id, "description": description}]
+    results = []
+    
+    for op in ops:
+        act = op.get("action", "")
+        tid = op.get("task_id", "")
+        desc = op.get("description", "")
+        
+        if act == "add":
+            if not tid:
+                tid = f"task_{len(todos) + 1}"
+            todos[tid] = {"description": desc, "status": "pending"}
+            results.append(f"Added task '{tid}': {desc}")
+        elif act == "mark_done":
+            if tid in todos:
+                todos[tid]["status"] = "done"
+                results.append(f"Marked task '{tid}' as done.")
+            else:
+                results.append(f"Error: Task '{tid}' not found.")
+        elif act == "mark_pending":
+            if tid in todos:
+                todos[tid]["status"] = "pending"
+                results.append(f"Marked task '{tid}' as pending.")
+            else:
+                results.append(f"Error: Task '{tid}' not found.")
+        elif act == "delete":
+            if tid in todos:
+                del todos[tid]
+                results.append(f"Deleted task '{tid}'.")
+            else:
+                results.append(f"Error: Task '{tid}' not found.")
+        elif act == "list":
+            results.append("Listed tasks.")
+        else:
+            results.append(f"Error: Unknown action '{act}'.")
+
+    result = "\n".join(results)
+
+    with open(todo_file, "w", encoding="utf-8") as f:
+        json.dump(todos, f, indent=2)
+        
+    out = "Current To-Do List:\n"
+    if not todos:
+        out += "(empty)"
+    else:
+        for tid, t in todos.items():
+            status_mark = "[x]" if t["status"] == "done" else "[ ]"
+            out += f"{status_mark} {tid}: {t['description']}\n"
+    return result + "\n\n" + out if action != "list" else out
+
+def manage_memory(action: str, key: str = "", content: str = "",
+                  category: str = "fact", query: str = "") -> str:
+    """Manages persistent cross-session memory stored in .utim/memory.json.
+
+    Actions
+    -------
+    save        Store a memory under *key* with optional *category*.
+                Categories: 'behaviour' (how user communicates/works),
+                            'preference' (UI, design, style choices),
+                            'fact'       (explicit facts/codes/data user stated),
+                            'project'    (architecture & tech decisions).
+    read        Return the full content of *key*.
+    search      Keyword-search across all keys+content, return top matches
+                with short previews.  Use *query* for the search terms.
+    get_traits  Return ONLY 'behaviour' and 'preference' memories in compact
+                form (used to seed session context without bloating the prompt).
+    list        Return all keys and their categories with 60-char previews.
+    delete      Remove *key* from memory.
+    verify      Verify user identity using the secret code passed in *query*.
+    """
+    import os, json, pathlib, time as _time
+    from utim_cli.state import STATE
+    mem_file = pathlib.Path(".utim").resolve() / "memory.json"
+    os.makedirs(mem_file.parent, exist_ok=True)
+
+    memories: dict = {}
+    if mem_file.exists():
+        try:
+            with open(mem_file, "r", encoding="utf-8") as f:
+                memories = json.load(f)
+        except Exception:
+            pass
+
+    # Ensure all memories are synced to ChromaDB user_memories on load
+    try:
+        from utim_cli.vector_memory import get_user_memories_memory
+        vm = get_user_memories_memory()
+        if vm and vm.collection:
+            from utim_cli.state import STATE
+            if not STATE.get("memories_synced", False):
+                for k, v in memories.items():
+                    content_val = v if isinstance(v, str) else v.get("content", "")
+                    cat = "fact" if isinstance(v, str) else v.get("category", "fact")
+                    updated_at = "" if isinstance(v, str) else v.get("updated_at", "")
+                    vm.add_text(
+                        text_id=k,
+                        content=content_val,
+                        metadata={"category": cat, "updated_at": updated_at}
+                    )
+                STATE["memories_synced"] = True
+    except Exception:
+        pass
+
+    def _save():
+        with open(mem_file, "w", encoding="utf-8") as f:
+            json.dump(memories, f, indent=2, ensure_ascii=False)
+
+    act = action.lower()
+    is_verified = STATE.get("is_verified", False)
+    sensitive_keywords = {"girlfriend", "gf", "wife", "spouse", "partner", "relationship", "secret", "password", "code", "private", "personal", "anushka", "puchkuli"}
+
+    if act == "verify":
+        if not query:
+            return "Error: 'query' parameter (containing the secret code) is required for verification."
+        
+        # Collect all possible secret codes from memories
+        possible_codes = []
+        for k, v in memories.items():
+            if "secret_code" in k.lower() or "user_secret" in k.lower():
+                val = v if isinstance(v, str) else v.get("content")
+                if val:
+                    possible_codes.append(val.strip())
+
+        if not possible_codes:
+            return "Error: No secret code was found in memory. Please set one first or check memory keys."
+
+        clean_query = query.strip().lower()
+        matched = False
+        for code in possible_codes:
+            if clean_query == code.lower():
+                matched = True
+                break
+
+        if matched:
+            STATE["is_verified"] = True
+            return "Verification successful! User identity has been verified for this session."
+        else:
+            return "Verification failed. The provided code does not match the stored secret code."
+
+    elif act == "save":
+        if not key:
+            return "Error: 'key' is required to save a memory."
+        
+        # If not verified, block saving/updating any sensitive keys or content
+        if not is_verified:
+            if any(w in key.lower() or w in content.lower() for w in sensitive_keywords):
+                return (
+                    "[VERIFICATION REQUIRED] Access to or modification of sensitive information requires identity verification. "
+                    "Please ask the user for the secret code, and once provided, call the manage_memory tool with action=\"verify\" and the code as the query parameter."
+                )
+
+        allowed_cats = {"behaviour", "preference", "fact", "project"}
+        cat = category.lower() if category.lower() in allowed_cats else "fact"
+        memories[key] = {
+            "content": content,
+            "category": cat,
+            "updated_at": _time.strftime("%Y-%m-%dT%H:%M:%S"),
+        }
+        _save()
+
+        # Sync to Vector DB
+        try:
+            from utim_cli.vector_memory import get_user_memories_memory
+            vm = get_user_memories_memory()
+            if vm:
+                vm.add_text(
+                    text_id=key,
+                    content=content,
+                    metadata={"category": cat, "updated_at": memories[key]["updated_at"]}
+                )
+        except Exception:
+            pass
+
+        return f"Memory saved: [{cat}] '{key}'."
+
+    elif act == "read":
+        if not key:
+            return "Error: 'key' is required to read a memory."
+        
+        # If not verified, block reading if the key itself contains any sensitive keywords
+        if not is_verified:
+            if any(w in key.lower() for w in sensitive_keywords):
+                return (
+                    "[VERIFICATION REQUIRED] Access to or modification of sensitive information requires identity verification. "
+                    "Please ask the user for the secret code, and once provided, call the manage_memory tool with action=\"verify\" and the code as the query parameter."
+                )
+
+        entry = memories.get(key)
+        if not entry:
+            return f"No memory found for key '{key}'."
+        
+        # Support legacy flat-string entries
+        if isinstance(entry, str):
+            content_text = entry
+            result = f"[fact] {key}:\n{entry}"
+        else:
+            content_text = entry.get("content", "")
+            result = f"[{entry.get('category', 'fact')}] {key} (saved {entry.get('updated_at', '?')}):\n{content_text}"
+
+        # If not verified, block reading if the content contains any sensitive keywords
+        if not is_verified:
+            if any(w in content_text.lower() for w in sensitive_keywords):
+                return (
+                    "[VERIFICATION REQUIRED] Access to or modification of sensitive information requires identity verification. "
+                    "Please ask the user for the secret code, and once provided, call the manage_memory tool with action=\"verify\" and the code as the query parameter."
+                )
+        return result
+
+    elif act == "search":
+        if not query:
+            return "Error: 'query' is required for search."
+
+        # If not verified and query is sensitive, block immediately
+        if not is_verified:
+            if any(w in query.lower() for w in sensitive_keywords):
+                return (
+                    "[VERIFICATION REQUIRED] Access to or modification of sensitive information requires identity verification. "
+                    "Please ask the user for the secret code, and once provided, call the manage_memory tool with action=\"verify\" and the code as the query parameter."
+                )
+
+        # Try semantic search using ChromaDB first
+        try:
+            from utim_cli.vector_memory import get_user_memories_memory
+            vm = get_user_memories_memory()
+            if vm and vm.collection:
+                results = vm.query(query, n_results=25)
+                hits = []
+                for r in results:
+                    m_id = r.get("id")
+                    content_text = r["content"]
+                    cat = r.get("metadata", {}).get("category", "fact")
+                    
+                    if not m_id:
+                        continue
+                    
+                    # If hit is sensitive and user is not verified, block/skip
+                    if not is_verified:
+                        if any(w in m_id.lower() or w in content_text.lower() for w in sensitive_keywords):
+                            continue
+                    
+                    preview = content_text[:80].replace("\n", " ") + ("…" if len(content_text) > 80 else "")
+                    hits.append(f"[{cat}] {m_id}: {preview}")
+                    if len(hits) >= 10:
+                        break
+                if hits:
+                    return "Semantic Search results:\n" + "\n".join(hits)
+        except Exception:
+            pass
+
+        # Normalise query: lowercase, strip punctuation, expand common synonyms
+        _SYNONYMS: dict[str, list[str]] = {
+            "color":      ["colour"],
+            "colour":     ["color"],
+            "favorite":   ["favourite", "fav", "fave", "preferred"],
+            "favourite":  ["favorite", "fav", "fave", "preferred"],
+            "fav":        ["favorite", "favourite"],
+            "prefer":     ["favorite", "favourite", "like", "love", "want"],
+            "preference": ["prefer", "favorite", "favourite", "like"],
+            "secret":     ["code", "key", "password", "token"],
+            "password":   ["secret", "code", "key", "token"],
+            "code":       ["secret", "password", "key", "token"],
+            "style":      ["design", "theme", "aesthetic", "look"],
+            "design":     ["style", "theme", "aesthetic", "look"],
+            "theme":      ["style", "design", "color", "colour"],
+            "dark":       ["dark mode", "night"],
+            "explain":    ["explanation", "details", "verbose"],
+            "project":    ["app", "application", "codebase", "repo"],
+            "wife":       ["bou", "bouer", "spouse", "partner", "girlfriend", "gf", "relationship", "marriage"],
+            "bou":        ["wife", "bouer", "spouse", "partner", "girlfriend", "gf", "relationship", "marriage"],
+            "bouer":      ["wife", "bou", "spouse", "partner", "girlfriend", "gf", "relationship", "marriage"],
+            "girlfriend": ["gf", "wife", "bou", "bouer", "partner", "spouse", "relationship", "love", "fiancee"],
+            "gf":         ["girlfriend", "wife", "bou", "partner", "spouse"],
+            "partner":    ["wife", "bou", "girlfriend", "gf", "spouse"],
+            "husband":    ["spouse", "partner", "boyfriend", "bf", "relationship", "marriage", "jamai", "bor"],
+            "boyfriend":  ["bf", "husband", "partner", "spouse", "relationship", "love", "fiance"],
+            "bf":         ["boyfriend", "husband", "partner", "spouse"],
+            "jamai":      ["husband", "bor", "partner"],
+            "bor":        ["husband", "jamai", "partner"],
+            "name":       ["nam", "called", "identity"],
+            "nam":        ["name", "called"],
+        }
+        raw_tokens = query.lower().split()
+        q_tokens = [tok.strip("?,.!-()\"'[]{}*&^%$#@;:_+=|\\/") for tok in raw_tokens]
+        q_tokens = [tok for tok in q_tokens if tok]
+
+        expanded: set[str] = set(q_tokens)
+        for tok in q_tokens:
+            for syn in _SYNONYMS.get(tok, []):
+                expanded.add(syn)
+        expanded.add(query.lower())
+
+        hits = []
+        import re
+        for k, v in memories.items():
+            text = v if isinstance(v, str) else v.get("content", "")
+            cat  = "fact" if isinstance(v, str) else v.get("category", "fact")
+            haystack = (k + " " + text).lower()
+            
+            words = set(re.findall(r'[a-z0-9]+', haystack))
+            matched = False
+            for term in expanded:
+                if ' ' in term or '_' in term or '-' in term:
+                    if term in haystack:
+                        matched = True
+                        break
+                else:
+                    if term in words:
+                        matched = True
+                        break
+
+            if matched:
+                # If hit is sensitive and user is not verified, block immediately
+                if not is_verified:
+                    if any(w in k.lower() or w in text.lower() for w in sensitive_keywords):
+                        return (
+                            "[VERIFICATION REQUIRED] Access to or modification of sensitive information requires identity verification. "
+                            "Please ask the user for the secret code, and once provided, call the manage_memory tool with action=\"verify\" and the code as the query parameter."
+                        )
+                preview = text[:80].replace("\n", " ") + ("…" if len(text) > 80 else "")
+                hits.append(f"[{cat}] {k}: {preview}")
+        if not hits:
+            return f"No memories matched '{query}'."
+        return "Search results:\n" + "\n".join(hits)
+
+    elif act == "get_traits":
+        trait_cats = {"behaviour", "preference"}
+        entries = []
+        for k, v in memories.items():
+            if isinstance(v, str):
+                continue
+            if v.get("category") in trait_cats:
+                # Extra safety: filter out sensitive key/content if not verified
+                if not is_verified:
+                    content_val = v.get("content", "")
+                    if any(w in k.lower() or w in content_val.lower() for w in sensitive_keywords):
+                        continue
+                entries.append((k, v))
+        
+        entries.sort(key=lambda x: x[1].get("updated_at", ""), reverse=True)
+        
+        lines = []
+        for k, v in entries[:15]:
+            preview = v["content"][:120].replace("\n", " ")
+            lines.append(f"• [{v['category']}] {k}: {preview}")
+        if not lines:
+            return "No behavioural traits stored yet."
+        return "User traits:\n" + "\n".join(lines)
+
+    elif act == "list":
+        if not memories:
+            return "Memory is empty."
+        lines = []
+        for k, v in memories.items():
+            content_val = v if isinstance(v, str) else v.get("content", "")
+            cat = "fact" if isinstance(v, str) else v.get("category", "fact")
+            
+            # Redact previews of sensitive entries if not verified
+            is_key_sensitive = any(w in k.lower() or w in content_val.lower() for w in sensitive_keywords)
+            if is_key_sensitive and not is_verified:
+                preview = "[REDACTED - VERIFICATION REQUIRED]"
+            else:
+                preview = content_val[:60].replace("\n", " ")
+                if len(content_val) > 60:
+                    preview += "…"
+            
+            lines.append(f"- [{cat}] {k}: {preview}")
+        return "Memories (" + str(len(lines)) + " entries):\n" + "\n".join(lines)
+
+    elif act == "delete":
+        if not key:
+            return "Error: 'key' is required to delete a memory."
+        if key not in memories:
+            return f"No memory found for key '{key}'."
+
+        # If not verified, block deleting any sensitive keys
+        if not is_verified:
+            if any(w in key.lower() for w in sensitive_keywords):
+                return (
+                    "[VERIFICATION REQUIRED] Access to or modification of sensitive information requires identity verification. "
+                    "Please ask the user for the secret code, and once provided, call the manage_memory tool with action=\"verify\" and the code as the query parameter."
+                )
+
+        del memories[key]
+        _save()
+
+        # Delete from Vector DB too
+        try:
+            from utim_cli.vector_memory import get_user_memories_memory
+            vm = get_user_memories_memory()
+            if vm and vm.collection:
+                vm.collection.delete(ids=[key])
+        except Exception:
+            pass
+
+        return f"Memory deleted: '{key}'."
+
+    return f"Error: Unknown action '{action}'. Valid actions: save, read, search, get_traits, list, delete, verify."
+
+
+def analyze_image(image_path: str, prompt: str) -> str:
+    """Analyzes a local image file using a vision model."""
+    import os, base64, requests, mimetypes
+    
+    if not os.path.exists(image_path):
+        return f"Error: Image file '{image_path}' not found."
+        
+    mime_type, _ = mimetypes.guess_type(image_path)
+    if not mime_type or not mime_type.startswith("image/"):
+        # Fallback if mimetypes fails
+        ext = os.path.splitext(image_path)[1].lower()
+        if ext in ['.png', '.jpg', '.jpeg', '.webp', '.gif']:
+            mime_type = f"image/{ext[1:]}"
+            if ext == '.jpg': mime_type = "image/jpeg"
+        else:
+            return f"Error: File '{image_path}' does not appear to be a supported image format."
+
+    try:
+        with open(image_path, "rb") as f:
+            encoded_image = base64.b64encode(f.read()).decode("utf-8")
+    except Exception as e:
+        return f"Error reading image file: {e}"
+
+    from utim_cli.config import config
+    llm_key = os.getenv("OPENROUTER_API_KEY") or config.get("api_key")
+    if not llm_key:
+        return "Error: Neither UTIM API key nor OPENROUTER_API_KEY environment variable is set."
+
+    payload = {
+        "messages": [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": prompt},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": f"data:{mime_type};base64,{encoded_image}"}
+                    }
+                ]
+            }
+        ]
+    }
+
+    models_to_try = [
+        "google/gemma-4-31b-it:free",
+        "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+        "nvidia/nemotron-nano-12b-v2-vl:free",
+        "google/gemma-4-26b-a4b-it:free",
+        "nvidia/llama-nemotron-embed-vl-1b-v2:free",
+        "nvidia/llama-nemotron-rerank-vl-1b-v2:free",
+        "openrouter/free"
+    ]
+    last_err = None
+    
+    for model in models_to_try:
+        payload["model"] = model
+        model_retries = 2
+        for attempt in range(model_retries + 1):
+            try:
+                from utim_cli.client_utils import proxy_openrouter_request
+                resp = proxy_openrouter_request(json_data=payload, stream=False, timeout=60)
+                resp.raise_for_status()
+                return resp.json()["choices"][0]["message"]["content"]
+            except requests.exceptions.HTTPError as e:
+                code = e.response.status_code if e.response is not None else 0
+                if code == 429 and attempt < model_retries:
+                    import time
+                    time.sleep(5 * (attempt + 1))
+                    continue
+                last_err = e
+                break
+            except Exception as e:
+                last_err = e
+                break
+
+    return f"Error analyzing image after trying all fallback models. Last error: {last_err}"
+
+
+def is_image_mostly_black(image_path: str, threshold: float = 0.95) -> bool:
+    """Check if the image is mostly black (common output when NSFW safety filters are triggered)."""
+    try:
+        from PIL import Image
+        with Image.open(image_path) as img:
+            gray_img = img.convert("L")
+            pixels = list(gray_img.getdata())
+            # Count pixels that are zero or near-zero (e.g. intensity < 10)
+            black_pixels = sum(1 for p in pixels if p < 10)
+            ratio = black_pixels / len(pixels)
+            return ratio > threshold
+    except Exception:
+        return False
+
+
+def safe_truncate_prompt(text: str, limit: int = 799) -> str:
+    """Safely truncate prompt to character limit without cutting mid-word."""
+    if len(text) <= limit:
+        return text
+    truncated = text[:limit]
+    last_space = truncated.rfind(' ')
+    if last_space > 0:
+        return truncated[:last_space]
+    return truncated
+
+
+def generate_image(
+    prompt: str,
+    output_path: str = "",
+    width: int = None,
+    height: int = None,
+    num_inference_steps: int = None,
+    guidance_scale: float = None,
+    seed: int = None
+) -> str:
+    """Generates an image from a text prompt using NVIDIA NIM APIs.
+    
+    Tries the primary model black-forest-labs/flux.1-schnell, falling back to 
+    stabilityai/stable-diffusion-3.5-large, and stabilityai/stable-diffusion-xl.
+    """
+    import os
+    import time
+    import re
+    import pathlib
+    import requests
+    import uuid
+    import base64
+
+    from utim_cli.config import config
+    api_key = config.get("api_key")
+    nvidia_key = os.getenv("NVIDIA_API_KEY")
+    if not api_key and not nvidia_key:
+        return "Error: Neither UTIM API key nor NVIDIA_API_KEY environment variable is set. Please set one of them to generate images."
+
+    if not output_path:
+        out_dir = pathlib.Path('.utim_tmp/images')
+        out_dir.mkdir(parents=True, exist_ok=True)
+        safe_prompt = re.sub(r'[^a-zA-Z0-9_-]', '_', prompt)[:30].strip('_')
+        if not safe_prompt:
+            safe_prompt = "generated"
+        timestamp = int(time.time())
+        filename = f"{timestamp}_{safe_prompt}_{uuid.uuid4().hex[:4]}.png"
+        output_path = str(out_dir / filename)
+
+    out_file = pathlib.Path(output_path)
+    try:
+        out_file.parent.mkdir(parents=True, exist_ok=True)
+    except Exception as e:
+        return f"Error creating parent directories for output_path '{output_path}': {e}"
+
+    # 1. Agentic prompt expansion using LLM and sub-agent rules/context
+    llm_key = os.getenv("OPENROUTER_API_KEY") or api_key
+    expanded_prompt = prompt
+    if llm_key:
+        try:
+            from utim_cli.bootstrap import get_subagent_rag_context
+            subagent_rag_ctx = get_subagent_rag_context("generate_image", prompt)
+        except Exception:
+            subagent_rag_ctx = ""
+
+        # Gather workspace context for image generation
+        workspace_context = ""
+        try:
+            for f in ["README.md", "index.html", "package.json"]:
+                if os.path.exists(f):
+                    try:
+                        with open(f, "r", encoding="utf-8") as file_obj:
+                            workspace_context += f"\n- {f} Content snippet: {file_obj.read(1500)}"
+                    except Exception:
+                        pass
+        except Exception:
+            pass
+
+        system_prompt = (
+            "You are an expert Image Generation Prompt Optimizer. Your task is to expand the user's short image request "
+            "into a highly descriptive, visually rich prompt for state-of-the-art text-to-image models (like Flux or Stable Diffusion). "
+            "Describe the scene composition, style (e.g. photographic, cinematic, 3D render, vector art, flat design), lighting, colors, "
+            "key elements, background details, and atmosphere. Do not write filler introduction or metadata - return ONLY the final "
+            "rich, expanded prompt text that can be directly passed to the image generator."
+        )
+        if subagent_rag_ctx:
+            system_prompt += f"\n\nContext and Learned Rules:\n{subagent_rag_ctx}"
+        if workspace_context:
+            system_prompt += f"\n\nWorkspace/Project Details:\n{workspace_context}"
+
+        models_to_try = [
+            "liquid/lfm-2.5-1.2b-instruct:free",
+            "qwen/qwen3-coder:free",
+            "google/gemma-3-27b-it:free",
+        ]
+        for model in models_to_try:
+            try:
+                payload = {
+                    "model": model,
+                    "messages": [
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": f"Please expand this request: {prompt}"}
+                    ]
+                }
+                from utim_cli.client_utils import proxy_openrouter_request
+                resp = proxy_openrouter_request(json_data=payload, stream=False, timeout=20)
+                if resp.status_code == 200:
+                    result = resp.json()["choices"][0]["message"]["content"].strip()
+                    if result:
+                        expanded_prompt = result
+                        print(f"✨ Expanded prompt: {expanded_prompt}", flush=True)
+                        break
+            except Exception:
+                continue
+
+    # Use the expanded prompt for NVIDIA NIM payload
+    prompt = expanded_prompt
+
+    models_to_try = [
+        "black-forest-labs/flux.1-schnell",
+        "black-forest-labs/flux.2-klein-4b",
+        "black-forest-labs/flux.1-dev"
+    ]
+
+    headers = {
+        "Authorization": f"Bearer {nvidia_key}",
+        "Accept": "application/json",
+        "Content-Type": "application/json"
+    }
+
+    last_err = None
+
+    for model in models_to_try:
+        api_url = f"https://ai.api.nvidia.com/v1/genai/{model}"
+        print(f"🔄 Requesting image from NVIDIA NIM model: {model}...", flush=True)
+
+        # Ensure prompt length is safe (especially for flux.2-klein-4b which has a strict 800-char limit)
+        prompt_for_model = prompt
+        if len(prompt_for_model) > 799:
+            prompt_for_model = safe_truncate_prompt(prompt_for_model, 799)
+
+        # Build model-specific payload to avoid 422 Unprocessable Entity
+        if "stabilityai" in model:
+            # Stable Diffusion payload structure
+            payload = {
+                "text_prompts": [{"text": prompt_for_model, "weight": 1.0}]
+            }
+            if seed is not None:
+                payload["seed"] = seed
+            if width is not None:
+                payload["width"] = width
+            if height is not None:
+                payload["height"] = height
+            if num_inference_steps is not None:
+                payload["steps"] = num_inference_steps
+            if guidance_scale is not None:
+                payload["cfg_scale"] = guidance_scale
+        else:
+            # Flux payload structure (only supports prompt, width, height, seed)
+            payload = {
+                "prompt": prompt_for_model
+            }
+            if seed is not None:
+                payload["seed"] = seed
+            if width is not None:
+                payload["width"] = width
+            if height is not None:
+                payload["height"] = height
+
+        # We try making the request. If it fails with 422/400 due to parameter schema,
+        # we try a fallback with absolute minimal payload (only prompt).
+        attempts_to_make = [payload]
+        if "stabilityai" in model:
+            attempts_to_make.append({"text_prompts": [{"text": prompt_for_model, "weight": 1.0}]})
+        else:
+            attempts_to_make.append({"prompt": prompt_for_model})
+
+        for attempt_payload in attempts_to_make:
+            try:
+                # Log the prompt snippet to help trace any failures
+                sent_prompt = attempt_payload.get("prompt")
+                if not sent_prompt and "text_prompts" in attempt_payload:
+                    sent_prompt = attempt_payload["text_prompts"][0].get("text")
+                print(f"📡 Sending request to {model}... Prompt length: {len(sent_prompt) if sent_prompt else 0} chars.", flush=True)
+                
+                if api_key:
+                    from utim_cli.client_utils import get_server_url
+                    proxy_url = f"{get_server_url()}/completions/images/generations"
+                    proxy_headers = {
+                        "X-API-Key": api_key,
+                        "Content-Type": "application/json"
+                    }
+                    proxy_payload = {
+                        "prompt": sent_prompt,
+                        "model": model
+                    }
+                    if seed is not None:
+                        proxy_payload["seed"] = seed
+                    if len(attempt_payload) > 2 or ("text_prompts" in attempt_payload and len(attempt_payload) > 1):
+                        if width is not None:
+                            proxy_payload["width"] = width
+                        if height is not None:
+                            proxy_payload["height"] = height
+                        if num_inference_steps is not None:
+                            proxy_payload["steps"] = num_inference_steps
+                        if guidance_scale is not None:
+                            proxy_payload["cfg_scale"] = guidance_scale
+
+                    resp = requests.post(proxy_url, json=proxy_payload, headers=proxy_headers, timeout=120)
+                else:
+                    resp = requests.post(api_url, json=attempt_payload, headers=headers, timeout=25)
+                resp.raise_for_status()
+
+                res_json = resp.json()
+                img_b64 = None
+
+                # Extract base64 image data from NVIDIA's response structure
+                if isinstance(res_json, dict):
+                    if "artifacts" in res_json and isinstance(res_json["artifacts"], list) and len(res_json["artifacts"]) > 0:
+                        img_b64 = res_json["artifacts"][0].get("base64")
+                    elif "data" in res_json and isinstance(res_json["data"], list) and len(res_json["data"]) > 0:
+                        img_b64 = res_json["data"][0].get("b64_json") or res_json["data"][0].get("url")
+
+                if not img_b64:
+                    raise Exception(f"No image data found in response. Response: {res_json}")
+
+                # Save image bytes
+                if img_b64.startswith("http://") or img_b64.startswith("https://"):
+                    img_resp = requests.get(img_b64, timeout=60)
+                    img_resp.raise_for_status()
+                    image_bytes = img_resp.content
+                else:
+                    if "," in img_b64:
+                        img_b64 = img_b64.split(",", 1)[1]
+                    image_bytes = base64.b64decode(img_b64)
+
+                with open(out_file, "wb") as img_file:
+                    img_file.write(image_bytes)
+
+                # Check if the generated image is solid black (safety filter trigger)
+                if is_image_mostly_black(output_path):
+                    raise Exception("Generated image is solid/mostly black, likely due to NVIDIA content safety filter.")
+
+                # Return clean formatted path using file:// protocol for clickability
+                abs_path_str = str(out_file.resolve())
+                abs_path_str_formatted = abs_path_str.replace('\\', '/')
+                file_uri = f"file:///{abs_path_str_formatted.lstrip('/')}"
+                if not file_uri.startswith("file:///"):
+                    file_uri = "file:///" + file_uri.lstrip("file:/")
+
+                return f"Success: Image generated and saved to [image]({file_uri}) (local path: {abs_path_str}) using model {model}.\nExpanded prompt used: {expanded_prompt}"
+
+            except Exception as e:
+                last_err = e
+                err_str = str(e)
+                if isinstance(e, requests.exceptions.HTTPError) and e.response is not None:
+                    err_str += f" - Response body: {e.response.text}"
+                print(f"⚠️ Failed with model {model}: {err_str}", flush=True)
+
+                # If 422/400 and we had parameter fields, retry with minimal payload
+                if isinstance(e, requests.exceptions.HTTPError):
+                    status_code = e.response.status_code if e.response is not None else 0
+                    if (status_code == 422 or status_code == 400) and len(attempt_payload) > 1:
+                        print(f"🔄 Retrying model {model} with minimal prompt payload...", flush=True)
+                        continue
+                break  # try next model
+
+    return f"Error: All image generation models failed. Last error: {last_err}"
+
+
+# JSON Schema for OpenAI Tool Calling (OpenRouter format)
+UTIM_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "generate_image",
+            "description": "Generates an image from a text prompt using NVIDIA NIM APIs (primary and fallbacks). Saves the generated image locally and returns the file path.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "prompt": {
+                        "type": "string",
+                        "description": "The detailed text prompt describing the image you want to generate."
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Optional. The local file path where the generated image should be saved. If omitted, defaults to a path in .utim_tmp/images/."
+                    },
+                    "width": {
+                        "type": "integer",
+                        "description": "Optional. Width of the generated image (e.g. 1024)."
+                    },
+                    "height": {
+                        "type": "integer",
+                        "description": "Optional. Height of the generated image (e.g. 1024)."
+                    },
+                    "num_inference_steps": {
+                        "type": "integer",
+                        "description": "Optional. Number of denoising/inference steps."
+                    },
+                    "guidance_scale": {
+                        "type": "number",
+                        "description": "Optional. Guidance scale / CFG scale for generation."
+                    },
+                    "seed": {
+                        "type": "integer",
+                        "description": "Optional. Seed for random generation."
+                    }
+                },
+                "required": ["prompt"]
+            }
+        }
+    },
+
+    {
+        "type": "function",
+        "function": {
+            "name": "compress_context",
+            "description": "Proactively frees up your memory during long tasks. Call this if you have finished a major step (like reading several files) and want to compress older tool logs into a high-signal summary to avoid running out of context. Provide instructions on what facts/code strictly need to be preserved.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "preservation_rules": {
+                        "type": "string",
+                        "description": "Specific facts, constraints, or code snippets you want the compressor to absolutely preserve in the summary."
+                    }
+                },
+                "required": ["preservation_rules"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "query_codebase",
+            "description": "Acts as a local RAG. Pass a query and it will automatically search the project tree, read relevant files, and return synthesized context. Use this to 'think' about a specific part of a large project without having to memorize it all.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "What you are looking for in the codebase (e.g. 'How does authentication work?' or 'Find the CSS file for the navbar')."
+                    }
+                },
+                "required": ["query"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "manage_todos",
+            "description": "Manages the project to-do list. Use this to track progress on complex plans. Provide either a single action or a list of 'operations' to execute multiple actions in batch.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "operations": {
+                        "type": "array",
+                        "description": "A list of operations to perform in batch.",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "action": {
+                                    "type": "string",
+                                    "enum": ["add", "mark_done", "mark_pending", "delete", "list"]
+                                },
+                                "task_id": {"type": "string"},
+                                "description": {"type": "string"}
+                            },
+                            "required": ["action"]
+                        }
+                    }
+                }
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": (
+                "Reads a file's content. Large files (>250 lines) are auto-truncated — use "
+                "start_line and end_line to read specific ranges (1-indexed, inclusive). "
+                "Always read only the range you need; call multiple times to page through large files."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "filepath": {
+                        "type": "string",
+                        "description": "The absolute or relative path to the file to read."
+                    },
+                    "start_line": {
+                        "type": "integer",
+                        "description": "First line to read (1-indexed). Omit to start from the beginning."
+                    },
+                    "end_line": {
+                        "type": "integer",
+                        "description": "Last line to read (1-indexed, inclusive). Omit to read to end or up to the 250-line limit."
+                    }
+                },
+                "required": ["filepath"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "write_file",
+            "description": "Writes complete content to a file, overwriting any existing file. Use this to create or modify code.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "filepath": {
+                        "type": "string",
+                        "description": "The path to the file."
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "The full content to write to the file."
+                    }
+                },
+                "required": ["filepath", "content"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "edit_file",
+            "description": "Replaces specific strings in a file. Use this for targeted edits without rewriting the whole file. Can do a single replace or multiple replacements in batch.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "filepath": {
+                        "type": "string",
+                        "description": "The path to the file to edit."
+                    },
+                    "old_str": {
+                        "type": "string",
+                        "description": "Optional. The exact text to find and replace. Use for a single replacement."
+                    },
+                    "new_str": {
+                        "type": "string",
+                        "description": "Optional. The new text to replace the old text with. Use for a single replacement."
+                    },
+                    "replacements": {
+                        "type": "array",
+                        "description": "Optional. A list of search and replace pairs for batch updates.",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "old_str": {"type": "string", "description": "The exact unique text to find in the file."},
+                                "new_str": {"type": "string", "description": "The new text to replace it with."}
+                            },
+                            "required": ["old_str", "new_str"]
+                        }
+                    }
+                },
+                "required": ["filepath"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "run_command",
+            "description": (
+                "Executes a shell command or list of commands sequentially and returns stdout, stderr, and exit code. "
+                "On Windows the command runs via powershell.exe -NoProfile -NonInteractive; "
+                "on macOS/Linux it runs via bash -c. "
+                "Use dir_path to run the command in a specific directory (defaults to the "
+                "current working directory). "
+                "When the CLI is started with --sandbox, commands are checked by an "
+                "intelligent static analysis sandbox and risky commands are blocked unless approved."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Optional. The single shell command to execute."
+                    },
+                    "commands": {
+                        "type": "array",
+                        "description": "Optional. A list of shell commands to execute sequentially. Execution halts on the first non-zero exit code.",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "dir_path": {
+                        "type": "string",
+                        "description": (
+                            "Optional. The directory in which to run the command. "
+                            "Accepts absolute or relative paths. "
+                            "Defaults to the current working directory when omitted."
+                        )
+                    },
+                    "timeout": {
+                        "type": "integer",
+                        "description": "Optional timeout in seconds to prevent the command from hanging. Defaults to 120s."
+                    }
+                }
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "list_directory",
+            "description": "Lists the files and folders inside a given directory. Use this to explore the project structure.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "The path to the directory to list (defaults to '.' if empty)."
+                    }
+                },
+                "required": ["path"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "web_search",
+            "description": "An agentic deep research tool. It spawns a sub-agent that performs multiple searches, reads dozens of sites based on the level, and reasons over the gathered data to provide a comprehensive raw info summary.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "prompt": {
+                        "type": "string",
+                        "description": "The detailed research prompt or question."
+                    },
+                    "level": {
+                        "type": "string",
+                        "enum": ["low", "medium", "high"],
+                        "description": "The intensity of the research. Low (1-20 sites), Medium (20-80 sites), High (80-150+ sites)."
+                    }
+                },
+                "required": ["prompt", "level"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "project_res",
+            "description": "A specialized subagent for codebase analysis, architectural mapping, and understanding system-wide dependencies. FAST MODE enabled by default for quicker responses (45s timeout, smaller context, fewer model fallbacks).",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "prompt": {
+                        "type": "string",
+                        "description": "The detailed research prompt or question about the codebase."
+                    },
+                    "fast_mode": {
+                        "type": "boolean",
+                        "description": "Enable fast mode (default true) for quicker responses with smaller context and shorter timeouts."
+                    }
+                },
+                "required": ["prompt"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "plan_project",
+            "description": "An agentic tool that spawns a specialized sub-agent (design, architecture, security, etc.) to deeply reason and create a highly detailed plan for a specific part of a project. You can use this multiple times to gather different plans, then synthesize them.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "plan_part": {
+                        "type": "string",
+                        "enum": ["design", "architecture", "security", "database", "verification", "general"],
+                        "description": "The specific domain to plan."
+                    },
+                    "prompt": {
+                        "type": "string",
+                        "description": "The detailed requirements or prompt for this plan."
+                    },
+                    "context": {
+                        "type": "string",
+                        "description": "Optional. Any previous context, summaries, or other plans to inform this sub-agent."
+                    }
+                },
+                "required": ["plan_part", "prompt"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "analyze_image",
+            "description": "Analyzes a local image file using a vision model. Can describe UI mockups, extract text, or understand diagrams.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "image_path": {
+                        "type": "string",
+                        "description": "The path to the local image file (png, jpg, webp, gif)."
+                    },
+                    "prompt": {
+                        "type": "string",
+                        "description": "What to extract or analyze from the image."
+                    }
+                },
+                "required": ["image_path", "prompt"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "analyze_blast_radius",
+            "description": "Analyzes the potential impact of changes to a file by finding all dependent files. Uses the knowledge graph to identify imports, function calls, and other dependencies. Run this before modifying critical files to understand the blast radius.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "filepath": {
+                        "type": "string",
+                        "description": "The path to the file to analyze (relative or absolute)."
+                    }
+                },
+                "required": ["filepath"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "blender_create_object",
+            "description": "Create a 3-D object in Blender and save it. Currently supports MESH object creation from vertices and faces.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Identifier for the new object."
+                    },
+                    "object_type": {
+                        "type": "string",
+                        "description": "Currently only 'MESH' is supported.",
+                        "enum": ["MESH"]
+                    },
+                    "mesh_data": {
+                        "type": "object",
+                        "description": "Data for the MESH. e.g. {\"vertices\": [[x,y,z], ...], \"faces\": [[i0,i1,i2,...], ...]}.",
+                        "additionalProperties": True
+                    },
+                    "location": {
+                        "type": "array",
+                        "items": {"type": "number"},
+                        "description": "Location transforms applied after creation. Defaults to [0.0, 0.0, 0.0]."
+                    },
+                    "rotation": {
+                        "type": "array",
+                        "items": {"type": "number"},
+                        "description": "Rotation transforms applied after creation. Defaults to [0.0, 0.0, 0.0]."
+                    },
+                    "scale": {
+                        "type": "array",
+                        "items": {"type": "number"},
+                        "description": "Scale transforms applied after creation. Defaults to [1.0, 1.0, 1.0]."
+                    },
+                    "output_format": {
+                        "type": "string",
+                        "description": "Format to save the object. Can be 'blend', 'obj', or 'glb'. Defaults to 'blend'.",
+                        "enum": ["blend", "obj", "glb"]
+                    }
+                },
+                "required": ["name", "mesh_data"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "blender_agent_create_from_image",
+            "description": (
+                "Advanced 4-phase Blender agent that creates a detailed 3-D model from any image, "
+                "specialised for characters (anime, human, stylised), objects, and scenes. "
+                "Phase 0: local Pillow-based image analysis (dominant colours, brightness, resolution). "
+                "Phase 1: a vision-LLM deeply analyses the image, extracting a structured scene description "
+                "including per-part geometry hints, materials, hair style, tattoos/decals, eye style, "
+                "clothing, and lighting suggestions. "
+                "Phase 2: a code-generation LLM writes a complete procedural bpy script that builds each "
+                "part (head, hair spikes, eyes, scarf, tattoo decals, etc.), applies Principled BSDF "
+                "materials with the analysed colours, projects the source image as a UV texture, and "
+                "sets up a 3-point studio light rig. "
+                "Phase 3: the script is executed by Blender in headless mode with automatic LLM-assisted "
+                "fix-and-retry (up to 3 attempts) on failure. "
+                "Use this whenever the user provides an image and wants a 3-D object, character, or scene."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "image_path": {
+                        "type": "string",
+                        "description": "Absolute or relative path to the source image file (PNG, JPG, JPEG, WEBP, BMP)."
+                    },
+                    "name": {
+                        "type": "string",
+                        "description": "Base name for the Blender object and the exported file (no extension)."
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Directory where the exported file will be saved. Defaults to 'blender_assets/' in the cwd."
+                    },
+                    "output_format": {
+                        "type": "string",
+                        "description": "Export format: 'blend' (Blender native), 'obj' (Wavefront OBJ), 'glb' (glTF binary), 'fbx' (Autodesk FBX). Defaults to 'blend'.",
+                        "enum": ["blend", "obj", "glb", "fbx"]
+                    }
+                },
+                "required": ["image_path", "name"]
+            }
+        }
+    },
+]
+
+
+def _fast_query_codebase(query: str) -> str:
+    """Lightweight codebase search without LLM synthesis - for internal use by project_res.
+    
+    Uses internal caching to speed up repeated similar queries.
+    """
+    import os
+    import sqlite3
+    import re
+    import time
+    
+    # Simple query cache (last 5 queries, 10 second TTL)
+    if not hasattr(_fast_query_codebase, "_cache"):
+        _fast_query_codebase._cache = {}
+    
+    cache_key = query[:100].lower()  # First 100 chars as key
+    now = time.time()
+    
+    if cache_key in _fast_query_codebase._cache:
+        cached = _fast_query_codebase._cache[cache_key]
+        if now - cached["time"] < 10:  # 10 second cache
+            return cached["result"]
+    
+    db_path = ".utim_tmp/codebase_fts.db"
+    if not os.path.exists(db_path):
+        return "No codebase index found."
+    
+    try:
+        conn = sqlite3.connect(db_path)
+        cur = conn.cursor()
+        
+        # Extract keywords from query
+        words = re.findall(r"\b[A-Za-z_][A-Za-z0-9_]{3,}\b", query)
+        keywords = [w for w in words[:5] if len(w) > 2]  # Limit to 5 keywords
+        
+        if not keywords:
+            return "No searchable keywords found."
+        
+        match_query = " OR ".join('"{}"'.format(kw.replace('"', '')) for kw in keywords)
+        
+        cur.execute("SELECT path, content FROM files WHERE files MATCH ? ORDER BY rank LIMIT 5", (match_query,))
+        results = cur.fetchall()
+        conn.close()
+        
+        if not results:
+            result = f"No results for keywords: {match_query}"
+        else:
+            context = ""
+            for path, content in results:
+                if len(content) > 3000:
+                    content = content[:3000] + "\n...[truncated]"
+                context += f"\n--- File: {path} ---\n{content}\n"
+            result = context
+        
+        # Cache the result
+        _fast_query_codebase._cache[cache_key] = {"time": now, "result": result}
+        # Clean old entries
+        if len(_fast_query_codebase._cache) > 10:
+            _fast_query_codebase._cache = dict(list(_fast_query_codebase._cache.items())[-5:])
+        
+        return result
+    except Exception as e:
+        return f"Search error: {e}"
+
+
+# Cache for directory tree (valid for current session)
+_dir_tree_cache = {"timestamp": 0, "content": "", "max_depth": 0}
+
+def _get_fast_dir_tree(max_depth: int = 3) -> str:
+    """Fast directory tree generation with caching for repeated calls."""
+    import os
+    import time
+    
+    current_time = time.time()
+    # Use cache if less than 30 seconds old and depth matches
+    if _dir_tree_cache["content"] and _dir_tree_cache["max_depth"] == max_depth:
+        if current_time - _dir_tree_cache["timestamp"] < 30:
+            return _dir_tree_cache["content"]
+    
+    lines = []
+    for root, dirs, files in os.walk("."):
+        # Skip hidden and common non-source directories
+        dirs[:] = [d for d in dirs if d not in [".git", "node_modules", "dist", "build", "__pycache__", ".venv", "venv", ".utim_tmp"]]
+        depth = root.count(os.sep)
+        if depth >= max_depth:
+            dirs[:] = []  # Don't descend further
+            continue
+        rel = os.path.relpath(root)
+        if rel == ".":
+            lines.append(f"{rel}/")
+        else:
+            lines.append(f"{rel}/")
+        for f in files[:15]:  # Show more files per directory
+            lines.append(f"  {f}")
+    
+    result = "\n".join(lines[:100])  # More total output
+    # Update cache
+    _dir_tree_cache["timestamp"] = current_time
+    _dir_tree_cache["content"] = result
+    _dir_tree_cache["max_depth"] = max_depth
+    
+    return result
+
+
+def project_res(prompt: str, fast_mode: bool = True) -> str:
+    """A specialized subagent for codebase analysis, architectural mapping, and understanding system-wide dependencies.
+    
+    Enhanced for speed with optimizations:
+    - Fast mode uses lightweight context gathering (no LLM synthesis for initial search)
+    - Smaller context windows (10k chars) for faster processing  
+    - Reasonable timeouts (90s overall, 30s idle)
+    - Still maintains quality with detailed reports (1500 tokens)
+    """
+    from utim_cli.config import config
+    llm_key = os.getenv("OPENROUTER_API_KEY") or config.get("api_key")
+    if not llm_key:
+        return "Error: Neither UTIM API key nor OPENROUTER_API_KEY environment variable is set."
+
+    # Fast context gathering - skip LLM synthesis overhead
+    if fast_mode:
+        try:
+            # Try vector memory first (fastest)
+            from utim_cli.vector_memory import get_vector_memory
+            vm = get_vector_memory()
+            context_snippets = ""
+            if vm:
+                results = vm.query(prompt, n_results=5)  # More results for quality
+                for r in results:
+                    content = (r.get("content", "") or "")[:3000]  # More content
+                    context_snippets += f"\n--- File: {r.get('filepath', 'unknown')} ---\n{content}\n"
+            if not context_snippets:
+                # Fallback to FTS (no LLM call)
+                context_snippets = _fast_query_codebase(prompt)
+        except Exception:
+            context_snippets = _fast_query_codebase(prompt)
+    else:
+        try:
+            context_snippets = query_codebase(prompt)
+        except Exception as e:
+            context_snippets = f"Failed to query codebase: {e}"
+    
+    # Get directory tree with limited depth
+    try:
+        dir_tree = _get_fast_dir_tree(max_depth=2)
+    except Exception as e:
+        dir_tree = f"Failed to list directory: {e}"
+    
+    # Optimized concise prompt for speed
+    sys_prompt = (
+        "You are an expert Codebase Investigator. Analyze the provided context and "
+        "return a structured markdown report with: 1) Summary of Findings (detailed), "
+        "2) Relevant File Paths, and 3) Key Symbols/Functions to examine. "
+        "Be comprehensive and specific."
+    )
+    
+    try:
+        from utim_cli.bootstrap import get_subagent_rag_context
+        subagent_rag_ctx = get_subagent_rag_context("project_res", prompt)
+        if subagent_rag_ctx:
+            sys_prompt += f"\n\n{subagent_rag_ctx}"
+    except Exception:
+        pass
+    
+    user_content = f"Query: {prompt}\n\nDir Tree:\n{dir_tree}\n\nContext:\n{context_snippets[:10000]}"
+    
+    models_to_try = [
+        "qwen/qwen3-coder:free",
+        "poolside/laguna-xs.2:free",
+        "nvidia/nemotron-3-super-120b-a12b:free",
+        "nvidia/nemotron-3-nano-30b-a3b:free",
+        "qwen/qwen3-next-80b-a3b-instruct:free",
+        "openrouter/free"
+    ]
+    
+    last_err = None
+    
+    for model in models_to_try:
+        model_retries = 2
+        for attempt in range(model_retries + 1):
+            try:
+                payload = {
+                    "model": model,
+                    "messages": [
+                        {"role": "system", "content": sys_prompt},
+                        {"role": "user", "content": user_content}
+                    ],
+                    "stream": True,
+                    "max_tokens": 1500  # Allow detailed reports
+                }
+                from utim_cli.client_utils import proxy_openrouter_request
+                resp = proxy_openrouter_request(json_data=payload, stream=True, timeout=(10, 90))
+                resp.raise_for_status()
+                resp.encoding = "utf-8"
+    
+                report = ""
+                start_time = time.time()
+                last_token_time = start_time
+                for raw_line in resp.iter_lines(decode_unicode=True):
+                    if _cancel_event and _cancel_event.is_set():
+                        return "Error: User cancelled the investigation process."
+                    now = time.time()
+                    if now - start_time > 90:  # 90 second overall timeout
+                        raise Exception("Timeout (90s)")
+                    if now - last_token_time > 30:  # 30 second idle timeout
+                        raise Exception("Idle timeout (30s)")
+                    if not raw_line or not raw_line.startswith("data: "):
+                        continue
+                    data_str = raw_line[6:]
+                    if data_str == "[DONE]":
+                        break
+                    try:
+                        chunk = json.loads(data_str)
+                    except Exception:
+                        continue
+    
+                    if "error" in chunk:
+                        raise Exception(chunk["error"].get("message", "API Error"))
+    
+                    try:
+                        delta = chunk["choices"][0].get("delta", {})
+                        if "content" in delta and delta["content"]:
+                            report += delta["content"]
+                            last_token_time = time.time()
+                    except Exception:
+                        continue
+    
+                # Clean up thinking tags
+                report = re.sub(r"<think(?:ing)?>.*?</think(?:ing)?>", "", report, flags=re.DOTALL).strip()
+    
+                if not report:
+                    raise Exception("Empty report")
+                
+                # Save the report to disk
+                os.makedirs(".utim_tmp/research", exist_ok=True)
+                report_file = f".utim_tmp/research/investigation_{int(time.time())}.md"
+                with open(report_file, "w", encoding="utf-8") as f:
+                    f.write(report)
+                
+                return f"Codebase investigation complete. Report saved to {report_file}.\n\n### Summary\n{report[:1500]}..."
+            except requests.exceptions.HTTPError as e:
+                code = e.response.status_code if e.response is not None else 0
+                if code == 429 and attempt < model_retries:
+                    time.sleep(5 * (attempt + 1))
+                    continue
+                last_err = e
+                break
+            except Exception as e:
+                last_err = e
+                break
+
+def analyze_blast_radius(filepath: str) -> str:
+    """Analyzes the potential impact of changes to a file using the knowledge graph.
+    
+    Returns files that depend on this file (imports, function calls, etc.) to help
+    understand the blast radius before making edits.
+    """
+    try:
+        from utim_cli.knowledge_graph import get_knowledge_graph
+        kg = get_knowledge_graph()
+        
+        if kg is None:
+            return "Knowledge graph not available. Tree-sitter may not be installed."
+        
+        # Build graph if needed
+        if len(kg.entities) == 0:
+            kg.build_graph()
+        
+        # Get blast radius
+        affected_files = kg.get_blast_radius(filepath)
+        
+        if not affected_files:
+            return f"No dependents found for `{filepath}` (file may not exist in graph)."
+        
+        result = f"### Potential Impact Analysis for `{filepath}`\n\n"
+        result += f"**{len(affected_files)} file(s) may be affected by changes:**\n\n"
+        for f in affected_files:
+            result += f"- `{f}`\n"
+        
+        result += "\n**Recommendation:** Review these files before making changes to understand potential side effects."
+        return result
+    except ImportError as e:
+        return f"Knowledge graph not available: {str(e)}"
+    except Exception as e:
+        return f"Error analyzing blast radius: {str(e)}"
+
+def store_experience(category: str, content: str, priority: int = None, subagent: str = None) -> str:
+    """
+    Store learning experiences in the experiences.json file for continuous improvement.
+    
+    Args:
+        category: Type of learning (e.g., 'logic_failure', 'success_pattern', 'user_preference', 'analytical_framework')
+        content: The actual learning content or insight gained
+        priority: Optional priority score (defaults to based on category)
+        subagent: Optional subagent name to store experiences specifically for that subagent ('project_res', 'plan_project', 'web_search')
+    
+    Returns:
+        Status message indicating success or failure
+    """
+    import json
+    from datetime import datetime
+    from pathlib import Path
+    
+    try:
+        # Ensure .utim directory exists
+        utim_dir = Path('.utim')
+        utim_dir.mkdir(exist_ok=True)
+        exp_file = utim_dir / 'experiences.json'
+        
+        # Load existing experiences
+        experiences = []
+        if exp_file.exists():
+            try:
+                with open(exp_file, 'r', encoding='utf-8') as f:
+                    experiences = json.load(f)
+            except Exception:
+                experiences = []
+                
+        timestamp = datetime.now().isoformat()
+        entry = {
+            "category": category,
+            "content": content,
+            "timestamp": timestamp,
+            "subagent": subagent,
+            "priority": priority or 0
+        }
+        experiences.append(entry)
+        
+        with open(exp_file, 'w', encoding='utf-8') as f:
+            json.dump(experiences, f, indent=2)
+            
+        # Also store in vector memory if available
+        try:
+            if subagent:
+                import utim_cli.vector_memory as vm_mod
+                getter_name = f"get_{subagent}_experiences_memory"
+                getter = getattr(vm_mod, getter_name, None)
+                vm = getter() if getter else None
+            else:
+                from utim_cli.vector_memory import get_experiences_memory
+                vm = get_experiences_memory()
+                
+            if vm:
+                vm.add_text(
+                    text_id=f"exp_{timestamp}_{category}",
+                    content=content,
+                    metadata={"category": category, "timestamp": timestamp, "type": "learning"}
+                )
+        except Exception:
+            pass
+            
+        return f"[OK] Experience stored: {category}" + (f" for subagent {subagent}" if subagent else "")
+    except Exception as e:
+        return f"[ERROR] Failed to store experience: {str(e)}"
+
+def recall_experience(query: str, limit: int = 5, subagent: str = None) -> str:
+    """
+    Search the RAG intelligence database (Experiences and Skills) using keyword matches and vector DB.
+    
+    Args:
+        query: Natural language search query or keywords describing what you are looking for.
+        limit: Number of results to return (default 5).
+        subagent: Optional subagent name to recall memory specifically from that subagent ('project_res', 'plan_project', 'web_search').
+        
+    Returns:
+        Formatted string containing the top matching experiences and skills.
+    """
+    try:
+        from pathlib import Path
+        import json
+        from utim_cli.state import STATE
+        
+        results_str = []
+        utim_dir = Path('.utim')
+        exp_file = utim_dir / 'experiences.json'
+        
+        # Search experiences from experiences.json
+        if exp_file.exists():
+            try:
+                with open(exp_file, 'r', encoding='utf-8') as f:
+                    experiences = json.load(f)
+            except Exception:
+                experiences = []
+                
+            query_lower = query.lower()
+            matched_exps = []
+            for exp in experiences:
+                if subagent and exp.get("subagent") != subagent:
+                    continue
+                content = exp.get("content", "")
+                cat = exp.get("category", "")
+                if query_lower in content.lower() or query_lower in cat.lower():
+                    matched_exps.append(exp)
+            
+            # Sort by priority and timestamp
+            matched_exps.sort(key=lambda x: (x.get("priority", 0), x.get("timestamp", "")), reverse=True)
+            
+            if matched_exps:
+                results_str.append("### RELEVANT PAST EXPERIENCES ###")
+                for r in matched_exps[:limit]:
+                    results_str.append(f"- [{r['category']}] {r['content']}")
+                    if "injected_contexts" not in STATE:
+                        STATE["injected_contexts"] = []
+                    STATE["injected_contexts"].append(r['content'])
+        
+        # Search skills from .utim/skills/
+        skills_dir = utim_dir / 'skills'
+        if skills_dir.exists():
+            matched_skills = []
+            for skill_path in skills_dir.glob("**/SKILL.md"):
+                try:
+                    with open(skill_path, 'r', encoding='utf-8') as f:
+                        content = f.read()
+                    if query.lower() in content.lower():
+                        skill_name = skill_path.parent.name
+                        matched_skills.append((skill_name, content))
+                except Exception:
+                    pass
+            if matched_skills:
+                results_str.append("\n### RELEVANT CORE SKILLS / RULES ###")
+                for name, content in matched_skills[:3]:
+                    if content.startswith('---'):
+                        parts = content.split('---', 2)
+                        if len(parts) >= 3:
+                            content = parts[2].strip()
+                    results_str.append(f"- [{name.upper()}] {content[:300]}...")
+                    if "injected_contexts" not in STATE:
+                        STATE["injected_contexts"] = []
+                    STATE["injected_contexts"].append(content)
+                    
+        if not results_str:
+            return f"No relevant experiences or skills found for your query."
+            
+        return "\n".join(results_str)
+    except Exception as e:
+        return f"[ERROR] Failed to recall experience: {str(e)}"
+def compress_context(preservation_rules: str) -> str:
+    """
+    Adaptive context compression - lets the model decide how much compression it needs.
+    
+    The model can call this tool to compress its working memory when it feels
+    the context is getting too large. It provides preservation rules that guide
+    what to keep vs what to summarize.
+    """
+    return f"Context compression requested. It will be executed at the end of this turn. Preservation rules: {preservation_rules}"
+
+
+
+# ─── Blender Helper ───────────────────────────────────────────────────────
+def _blender_run_script(script_path: str, timeout: int = 120) -> str:
+    """Execute a temporary Blender Python script in headless mode.
+
+    The function builds the command using the auto‑detected Blender path
+    from ``config.BLENDER_PATH`` (or environment variable). It respects the
+    UTIM sandbox – if sandbox mode is active the exact command string is
+    auto‑approved before execution.
+    """
+    from utim_cli.config import BLENDER_PATH
+    if not BLENDER_PATH:
+        return "Error: Blender executable not found. Set UTIM_BLENDER_PATH env var or install Blender."
+
+    if os.name == "nt":
+        cmd = f'& "{BLENDER_PATH}" -b -noaudio -P "{script_path}"'
+    else:
+        cmd = f'"{BLENDER_PATH}" -b -noaudio -P "{script_path}"'
+    
+    # Auto‑approve in sandbox mode
+    if _SANDBOX_MODE and not is_command_approved(cmd):
+        approve_command(cmd)
+    # Execute via existing run_command utility
+    result = run_command(command=cmd, timeout=timeout)
+    return result
+
+# ─── Blender Create Object Tool ──────────────────────────────────────────────
+def blender_create_object(
+    name: str,
+    object_type: str = "MESH",
+    mesh_data: dict | None = None,
+    location: list[float] = None,
+    rotation: list[float] = None,
+    scale: list[float] = None,
+    output_format: str = "blend"
+) -> str:
+    """Create a 3‑D object in Blender and save it.
+
+    Parameters
+    ----------
+    name: Identifier for the new object.
+    object_type: Currently only "MESH" is supported.
+    mesh_data: ``{"vertices": [[x,y,z], …], "faces": [[i0,i1,i2,…], …]}``.
+    location, rotation, scale: Transforms applied after creation.
+    output_format: "blend", "obj", or "glb".
+    """
+    import json, pathlib, uuid, os
+    # Normalise optional transforms
+    location = location or [0.0, 0.0, 0.0]
+    rotation = rotation or [0.0, 0.0, 0.0]
+    scale = scale or [1.0, 1.0, 1.0]
+
+    # Prepare temporary script content
+    script_lines = [
+        "import bpy, json, pathlib, sys",
+        "# Clean default scene",
+        "bpy.ops.object.select_all(action='SELECT')",
+        "bpy.ops.object.delete(use_global=False)",
+    ]
+    if object_type.upper() == "MESH" and mesh_data:
+        verts = mesh_data.get('vertices', [])
+        faces = mesh_data.get('faces', [])
+        script_lines += [
+            f"verts = {json.dumps(verts)}",
+            f"faces = {json.dumps(faces)}",
+            "mesh = bpy.data.meshes.new('TempMesh')",
+            "mesh.from_pydata(verts, [], faces)",
+            "obj = bpy.data.objects.new('TempObj', mesh)",
+            "bpy.context.collection.objects.link(obj)",
+            f"obj.location = {location}",
+            f"obj.rotation_euler = {rotation}",
+            f"obj.scale = {scale}",
+        ]
+    else:
+        return "Error: Currently only MESH objects with mesh_data are supported."
+
+    # Determine output path
+    assets_dir = pathlib.Path('.utim_tmp/blender_assets').absolute()
+    assets_dir.mkdir(parents=True, exist_ok=True)
+    filename = f"{name}_{uuid.uuid4().hex[:8]}.{output_format if output_format != 'blend' else 'blend'}"
+    out_path = assets_dir / filename
+    if output_format == "blend":
+        script_lines.append(f"bpy.ops.wm.save_as_mainfile(filepath=r'{out_path}')")
+    elif output_format == "obj":
+        script_lines.append(f"bpy.ops.wm.obj_export(filepath=r'{out_path}', export_selected_objects=False)")
+    elif output_format == "glb":
+        script_lines.append(f"bpy.ops.export_scene.gltf(filepath=r'{out_path}', export_format='GLB')")
+    else:
+        return f"Error: Unsupported output_format '{output_format}'."
+
+    # Write temporary script
+    tmp_dir = pathlib.Path('.utim_tmp/blender')
+    tmp_dir.mkdir(parents=True, exist_ok=True)
+    script_path = tmp_dir / f'create_{uuid.uuid4().hex[:8]}.py'
+    with open(script_path, 'w', encoding='utf-8') as f:
+        f.write('\n'.join(script_lines))
+
+    # Run Blender
+    exec_result = _blender_run_script(str(script_path))
+
+    # Register asset in pattern store (if successful)
+    if "[exit_code: 0]" in exec_result:
+        return f"Success: Created {output_format} asset at {out_path}\n{exec_result}"
+    else:
+        return f"Error creating Blender object:\n{exec_result}"
+
+# Map tool names to actual Python functions
+TOOL_FUNCTIONS = {
+    "compress_context": compress_context,
+    "analyze_blast_radius": analyze_blast_radius,
+    "project_res":    project_res,
+    "read_file":      read_file,
+    "write_file":     write_file,
+    "edit_file":      edit_file,
+    "run_command":    run_command,
+    "list_directory": list_directory,
+    "web_search":     web_search,
+    "plan_project":   plan_project,
+    "manage_todos":   manage_todos,
+    "query_codebase": query_codebase,
+    "analyze_image":  analyze_image,
+
+    "blender_create_object": blender_create_object,
+    "blender_agent_create_from_image": blender_agent_create_from_image,
+    "generate_image": generate_image,
+}