zrb 1.21.31__py3-none-any.whl → 1.21.43__py3-none-any.whl

zrb/builtin/llm/chat_session_cmd.py

@@ -1,6 +1,7 @@
 import os
-import subprocess
+from typing import Callable
 
+from zrb.config.config import CFG
 from zrb.context.any_context import AnyContext
 from zrb.task.llm.workflow import get_available_workflows
 from zrb.util.cli.markdown import render_markdown
@@ -10,7 +11,8 @@ from zrb.util.cli.style import (
     stylize_error,
     stylize_faint,
 )
-from zrb.util.file import write_file
+from zrb.util.cmd.command import run_command
+from zrb.util.file import read_file, write_file
 from zrb.util.markdown import make_markdown_section
 from zrb.util.string.conversion import FALSE_STRS, TRUE_STRS, to_boolean
 
@@ -18,14 +20,20 @@ MULTILINE_START_CMD = ["/multi", "/multiline"]
 MULTILINE_END_CMD = ["/end"]
 QUIT_CMD = ["/bye", "/quit", "/q", "/exit"]
 WORKFLOW_CMD = ["/workflow", "/workflows", "/skill", "/skills", "/w"]
+RESPONSE_CMD = ["/response", "/res"]
 SAVE_CMD = ["/save", "/s"]
+LOAD_CMD = ["/load", "/l"]
 ATTACHMENT_CMD = ["/attachment", "/attachments", "/attach"]
 YOLO_CMD = ["/yolo"]
 HELP_CMD = ["/help", "/info"]
+RUN_CLI_CMD = ["/run", "/exec", "/execute", "/cmd", "/cli", "!"]
+SESSION_CMD = ["/session", "/conversation", "/convo"]
+
 ADD_SUB_CMD = ["add"]
 SET_SUB_CMD = ["set"]
 CLEAR_SUB_CMD = ["clear"]
-RUN_CLI_CMD = ["/run", "/exec", "/execute", "/cmd", "/cli", "!"]
+SAVE_SUB_CMD = ["save"]
+LOAD_SUB_CMD = ["load"]
 
 # Command display constants
 MULTILINE_START_CMD_DESC = "Start multiline input"
@@ -33,14 +41,20 @@ MULTILINE_END_CMD_DESC = "End multiline input"
 QUIT_CMD_DESC = "Quit from chat session"
 WORKFLOW_CMD_DESC = "Show active workflows"
 WORKFLOW_ADD_SUB_CMD_DESC = (
-    "Add active workflow "
-    f"(e.g., `{WORKFLOW_CMD[0]} {ADD_SUB_CMD[0]} coding,researching`)"
+    "Add active workflow " f"(e.g., `{WORKFLOW_CMD[0]} {ADD_SUB_CMD[0]} coding`)"
 )
 WORKFLOW_SET_SUB_CMD_DESC = (
-    "Set active workflows " f"(e.g., `{WORKFLOW_CMD[0]} {SET_SUB_CMD[0]} coding,`)"
+    "Set active workflows "
+    f"(e.g., `{WORKFLOW_CMD[0]} {SET_SUB_CMD[0]} coding,researching`)"
 )
 WORKFLOW_CLEAR_SUB_CMD_DESC = "Deactivate all workflows"
-SAVE_CMD_DESC = f"Save last response to a file (e.g., `{SAVE_CMD[0]} conclusion.md`)"
+RESPONSE_CMD_DESC = "Manage response"
+RESPONSE_SAVE_SUB_CMD_DESC = (
+    "Save last response to a file "
+    f"(e.g., `{RESPONSE_CMD[0]} {SAVE_SUB_CMD[0]} conclusion.md`)"
+)
+SAVE_CMD_DESC = "Save current session " f"(e.g., `{SAVE_CMD[0]} save-point`)"
+LOAD_CMD_DESC = "Load session " f"(e.g., `{LOAD_CMD[0]} save-point`)"
 ATTACHMENT_CMD_DESC = "Show current attachment"
 ATTACHMENT_ADD_SUB_CMD_DESC = (
     "Attach a file " f"(e.g., `{ATTACHMENT_CMD[0]} {ADD_SUB_CMD[0]} ./logo.png`)"
@@ -59,6 +73,7 @@ YOLO_SET_TRUE_CMD_DESC = "Activate YOLO mode for all tools"
 YOLO_SET_FALSE_CMD_DESC = "Deactivate YOLO mode for all tools"
 RUN_CLI_CMD_DESC = "Run a non-interactive CLI command"
 HELP_CMD_DESC = "Show info/help"
+SESSION_CMD_DESC = "Show current session"
 
 
 def print_current_yolo_mode(
@@ -73,7 +88,9 @@ def print_current_yolo_mode(
 
 def print_current_attachments(ctx: AnyContext, current_attachments_value: str) -> None:
     attachments_str = (
-        current_attachments_value if current_attachments_value != "" else "*Not Set*"
+        ", ".join(current_attachments_value.split(","))
+        if current_attachments_value != ""
+        else "*Not Set*"
     )
     ctx.print(render_markdown(f"📎 Current attachments: {attachments_str}"), plain=True)
     ctx.print("", plain=True)
@@ -87,7 +104,7 @@ def print_current_workflows(ctx: AnyContext, current_workflows_value: str) -> No
         else "*No Available Workflow*"
     )
     current_workflows_str = (
-        current_workflows_value
+        ", ".join(current_workflows_value.split(","))
         if current_workflows_value != ""
         else "*No Active Workflow*"
     )
@@ -105,8 +122,10 @@ def print_current_workflows(ctx: AnyContext, current_workflows_value: str) -> No
     ctx.print("", plain=True)
 
 
-def save_final_result(ctx: AnyContext, user_input: str, final_result: str) -> None:
-    save_path = get_command_param(user_input, SAVE_CMD)
+def handle_response_cmd(ctx: AnyContext, user_input: str, final_result: str) -> None:
+    if not is_command_match(user_input, RESPONSE_CMD, SAVE_SUB_CMD):
+        return
+    save_path = get_command_param(user_input, RESPONSE_CMD, SAVE_SUB_CMD)
     save_path = os.path.expanduser(save_path)
     if os.path.exists(save_path):
         ctx.print(
@@ -118,13 +137,12 @@ def save_final_result(ctx: AnyContext, user_input: str, final_result: str) -> No
     ctx.print(f"Response saved to {save_path}", plain=True)
 
 
-def run_cli_command(ctx: AnyContext, user_input: str) -> None:
+async def run_cli_command(ctx: AnyContext, user_input: str) -> None:
     command = get_command_param(user_input, RUN_CLI_CMD)
-    result = subprocess.run(
-        command,
-        shell=True,
-        capture_output=True,
-        text=True,
+    cmd_result, return_code = await run_command(
+        [CFG.DEFAULT_SHELL, "-c", command],
+        print_method=_create_faint_print(ctx),
+        timeout=3600,
     )
     ctx.print(
         render_markdown(
@@ -132,10 +150,14 @@ def run_cli_command(ctx: AnyContext, user_input: str) -> None:
                 f"`{command}`",
                 "\n".join(
                     [
-                        make_markdown_section("📤 Stdout", result.stdout, as_code=True),
-                        make_markdown_section("🚫 Stderr", result.stderr, as_code=True),
                         make_markdown_section(
-                            "🎯 Return code", f"Return Code: {result.returncode}"
+                            "📤 Stdout", cmd_result.output, as_code=True
+                        ),
+                        make_markdown_section(
+                            "🚫 Stderr", cmd_result.error, as_code=True
+                        ),
+                        make_markdown_section(
+                            "🎯 Return code", f"Return Code: {return_code}"
                         ),
                     ]
                 ),
@@ -146,8 +168,20 @@ def run_cli_command(ctx: AnyContext, user_input: str) -> None:
     ctx.print("", plain=True)
 
 
+def _create_faint_print(ctx: AnyContext) -> Callable[..., None]:
+    def print_faint(text: str):
+        ctx.print(stylize_faint(f"  {text}"), plain=True)
+
+    return print_faint
+
+
 def get_new_yolo_mode(old_yolo_mode: str | bool, user_input: str) -> str | bool:
-    new_yolo_mode = get_command_param(user_input, YOLO_CMD)
+    if not is_command_match(user_input, YOLO_CMD):
+        return old_yolo_mode
+    if is_command_match(user_input, YOLO_CMD, SET_SUB_CMD):
+        new_yolo_mode = get_command_param(user_input, YOLO_CMD, SET_SUB_CMD)
+    else:
+        new_yolo_mode = get_command_param(user_input, YOLO_CMD)
     if new_yolo_mode != "":
         if new_yolo_mode in TRUE_STRS or new_yolo_mode in FALSE_STRS:
             return to_boolean(new_yolo_mode)
@@ -189,6 +223,59 @@ def get_new_workflows(old_workflow: str, user_input: str) -> str:
     return _normalize_comma_separated_str(old_workflow)
 
 
+def handle_session(
+    ctx: AnyContext,
+    current_session_name: str | None,
+    current_start_new: bool,
+    user_input: str,
+) -> tuple[str | None, bool]:
+    if is_command_match(user_input, SAVE_CMD):
+        save_point = get_command_param(user_input, SAVE_CMD)
+        if not save_point:
+            ctx.print(render_markdown("️⚠️ Save point name is required."), plain=True)
+            return current_session_name, current_start_new
+        if not current_session_name:
+            ctx.print(
+                render_markdown(
+                    "⚠️ No active session to save. Please start a conversation first."
+                ),
+                plain=True,
+            )
+            return current_session_name, current_start_new
+        save_point_path = os.path.join(CFG.LLM_HISTORY_DIR, "save-point", save_point)
+        write_file(save_point_path, current_session_name)
+        ctx.print(
+            render_markdown(
+                f"Session saved to save-point: {save_point} ({current_session_name})"
+            ),
+            plain=True,
+        )
+        return current_session_name, current_start_new
+    if is_command_match(user_input, LOAD_CMD):
+        save_point = get_command_param(user_input, LOAD_CMD)
+        if not save_point:
+            ctx.print(render_markdown("⚠️ Save point name is required."), plain=True)
+            return current_session_name, current_start_new
+        save_point_path = os.path.join(CFG.LLM_HISTORY_DIR, "save-point", save_point)
+        if not os.path.exists(save_point_path):
+            ctx.print(
+                render_markdown(f"⚠️ Save point '{save_point}' not found."), plain=True
+            )
+            return current_session_name, current_start_new
+        current_session_name = read_file(save_point_path).strip()
+        ctx.print(
+            render_markdown(f"Loaded session: {current_session_name}"), plain=True
+        )
+        # When loading a session, we shouldn't start a new one
+        return current_session_name, False
+    if is_command_match(user_input, SESSION_CMD):
+        ctx.print(
+            render_markdown(f"Current session: {current_session_name}"), plain=True
+        )
+        return current_session_name, current_start_new
+    return current_session_name, current_start_new
+
+
 def _normalize_comma_separated_str(comma_separated_str: str) -> str:
     return ",".join(
         [
@@ -252,7 +339,13 @@ def print_commands(ctx: AnyContext):
                     WORKFLOW_SET_SUB_CMD_DESC,
                 ),
                 _show_subcommand(CLEAR_SUB_CMD[0], "", WORKFLOW_CLEAR_SUB_CMD_DESC),
-                _show_command(f"{SAVE_CMD[0]}", SAVE_CMD_DESC),
+                _show_command(SESSION_CMD[0], SESSION_CMD_DESC),
+                _show_command(SAVE_CMD[0], SAVE_CMD_DESC),
+                _show_command(LOAD_CMD[0], LOAD_CMD_DESC),
+                _show_command(RESPONSE_CMD[0], RESPONSE_CMD_DESC),
+                _show_subcommand(
+                    SAVE_SUB_CMD[0], "<file-path>", RESPONSE_SAVE_SUB_CMD_DESC
+                ),
                 _show_command(YOLO_CMD[0], YOLO_CMD_DESC),
                 _show_subcommand(SET_SUB_CMD[0], "true", YOLO_SET_TRUE_CMD_DESC),
                 _show_subcommand(SET_SUB_CMD[0], "false", YOLO_SET_FALSE_CMD_DESC),

zrb/builtin/llm/chat_trigger.py

@@ -4,7 +4,9 @@ from asyncio import StreamReader
 from typing import TYPE_CHECKING, Any, Callable, Coroutine
 
 from zrb.builtin.llm.chat_completion import get_chat_completer
+from zrb.config.llm_config import llm_config
 from zrb.context.any_context import AnyContext
+from zrb.util.git import get_current_branch
 from zrb.util.run import run_async
 
 if TYPE_CHECKING:
@@ -27,10 +29,20 @@ class LLMChatTrigger:
             self._triggers.append(single_trigger)
 
     async def wait(
-        self, reader: "PromptSession[Any] | StreamReader", ctx: AnyContext
+        self,
+        ctx: AnyContext,
+        reader: "PromptSession[Any] | StreamReader",
+        current_session_name: str | None,
+        is_first_time: bool,
     ) -> str:
         trigger_tasks = [
-            asyncio.create_task(run_async(self._read_next_line(reader, ctx)))
+            asyncio.create_task(
+                run_async(
+                    self._read_next_line(
+                        ctx, reader, current_session_name, is_first_time
+                    )
+                )
+            )
         ] + [asyncio.create_task(run_async(trigger(ctx))) for trigger in self._triggers]
         final_result: str = ""
         try:
@@ -47,22 +59,33 @@ class LLMChatTrigger:
         except asyncio.CancelledError:
             ctx.print("Task cancelled.", plain=True)
             final_result = "/bye"
+            for task in trigger_tasks:
+                task.cancel()
         except KeyboardInterrupt:
             ctx.print("KeyboardInterrupt detected. Exiting...", plain=True)
             final_result = "/bye"
+            for task in trigger_tasks:
+                task.cancel()
         return final_result
 
     async def _read_next_line(
-        self, reader: "PromptSession[Any] | StreamReader", ctx: AnyContext
+        self,
+        ctx: AnyContext,
+        reader: "PromptSession[Any] | StreamReader",
+        current_session_name: str | None,
+        is_first_time: bool,
     ) -> str:
         """Reads one line of input using the provided reader."""
         from prompt_toolkit import PromptSession
 
         try:
             if isinstance(reader, PromptSession):
-                bottom_toolbar = f"📁 Current directory: {os.getcwd()}"
+                bottom_toolbar = await self._get_bottom_toolbar(
+                    ctx, current_session_name, is_first_time
+                )
                 return await reader.prompt_async(
-                    completer=get_chat_completer(), bottom_toolbar=bottom_toolbar
+                    completer=get_chat_completer(),
+                    bottom_toolbar=bottom_toolbar,
                 )
             line_bytes = await reader.readline()
             if not line_bytes:
@@ -74,5 +97,69 @@ class LLMChatTrigger:
             ctx.print("KeyboardInterrupt detected. Exiting...", plain=True)
             return "/bye"
 
+    async def _get_bottom_toolbar(
+        self, ctx: AnyContext, current_session_name: str | None, is_first_time: bool
+    ) -> str:
+        import shutil
+
+        terminal_width = shutil.get_terminal_size().columns
+        previous_session_name = self._get_previous_session_name(
+            ctx, current_session_name, is_first_time
+        )
+        current_branch = await self._get_current_branch()
+        current_model = self._get_current_model(ctx)
+        left_text = f"📌 {os.getcwd()} ({current_branch}) | 🧠 {current_model}"
+        right_text = f"📚 Previous Session: {previous_session_name}"
+        padding = (
+            terminal_width
+            - self._get_display_width(left_text)
+            - self._get_display_width(right_text)
+            - 1
+        )
+        if padding > 0:
+            return f"{left_text}{' ' * padding}{right_text}"
+        return f"{left_text} {right_text}"
+
+    def _get_display_width(self, text: str) -> int:
+        import unicodedata
+
+        width = 0
+        for char in text:
+            eaw = unicodedata.east_asian_width(char)
+            if eaw in ("F", "W"):  # Fullwidth or Wide
+                width += 2
+            elif eaw == "A":  # Ambiguous
+                width += 1  # Usually 1 in non-East Asian contexts
+            else:  # Narrow, Halfwidth, Neutral
+                width += 1
+        return width
+
+    def _get_current_model(self, ctx: AnyContext) -> str:
+        if "model" in ctx.input and ctx.input.model:
+            return ctx.input.model
+        return str(llm_config.default_model_name)
+
+    def _get_previous_session_name(
+        self, ctx: AnyContext, current_session_name: str | None, is_first_time: bool
+    ) -> str:
+        if is_first_time:
+            start_new: bool = ctx.input.start_new
+            if (
+                not start_new
+                and "previous_session" in ctx.input
+                and ctx.input.previous_session is not None
+            ):
+                return ctx.input.previous_session
+            return "<No Session>"
+        if not current_session_name:
+            return "<No Session>"
+        return current_session_name
+
+    async def _get_current_branch(self) -> str:
+        try:
+            return await get_current_branch(os.getcwd(), print_method=lambda x: x)
+        except Exception:
+            return "<Not a git repo>"
+
 
 llm_chat_trigger = LLMChatTrigger()

zrb/builtin/llm/history.py

@@ -17,13 +17,10 @@ def read_chat_conversation(ctx: AnyContext) -> dict[str, Any] | list | None:
         return None  # Indicate no history to load
     previous_session_name = ctx.input.previous_session
     if not previous_session_name:  # Check for empty string or None
-        last_session_file_path = os.path.join(CFG.LLM_HISTORY_DIR, "last-session")
-        if os.path.isfile(last_session_file_path):
-            previous_session_name = read_file(last_session_file_path).strip()
-            if not previous_session_name:  # Handle empty last-session file
-                return None
-        else:
-            return None  # No previous session specified and no last session found
+        last_session_name = get_last_session_name()
+        if last_session_name is None:
+            return None
+        previous_session_name = last_session_name
     conversation_file_path = os.path.join(
         CFG.LLM_HISTORY_DIR, f"{previous_session_name}.json"
     )
@@ -51,6 +48,16 @@ def read_chat_conversation(ctx: AnyContext) -> dict[str, Any] | list | None:
         return None
 
 
+def get_last_session_name() -> str | None:
+    last_session_file_path = os.path.join(CFG.LLM_HISTORY_DIR, "last-session")
+    if not os.path.isfile(last_session_file_path):
+        return None
+    last_session_name = read_file(last_session_file_path).strip()
+    if not last_session_name:  # Handle empty last-session file
+        return None
+    return last_session_name
+
+
 def write_chat_conversation(ctx: AnyContext, history_data: ConversationHistory):
     """Writes the conversation history data (including context) to a session file."""
     os.makedirs(CFG.LLM_HISTORY_DIR, exist_ok=True)

zrb/builtin/llm/llm_ask.py

@@ -31,6 +31,11 @@ from zrb.builtin.llm.tool.web import (
     create_search_internet_tool,
     open_web_page,
 )
+from zrb.builtin.llm.xcom_names import (
+    LLM_ASK_ERROR_XCOM_NAME,
+    LLM_ASK_RESULT_XCOM_NAME,
+    LLM_ASK_SESSION_XCOM_NAME,
+)
 from zrb.callback.callback import Callback
 from zrb.config.config import CFG
 from zrb.config.llm_config import llm_config
@@ -40,6 +45,7 @@ from zrb.input.bool_input import BoolInput
 from zrb.input.str_input import StrInput
 from zrb.input.text_input import TextInput
 from zrb.task.base_trigger import BaseTrigger
+from zrb.task.llm.workflow import LLM_LOADED_WORKFLOW_XCOM_NAME
 from zrb.task.llm_task import LLMTask
 from zrb.util.string.conversion import to_boolean
 
@@ -99,6 +105,8 @@ def _get_default_yolo_mode(ctx: AnyContext) -> str:
 
 
 def _render_yolo_mode_input(ctx: AnyContext) -> list[str] | bool:
+    if isinstance(ctx.input.yolo, bool):
+        return ctx.input.yolo
     if ctx.input.yolo.strip() == "":
         return []
     elements = [element.strip() for element in ctx.input.yolo.split(",")]
@@ -172,9 +180,9 @@ def _get_inputs(require_message: bool = True) -> list[AnyInput | None]:
             always_prompt=False,
         ),
         TextInput(
-            "workflows",
-            description="Workflows",
-            prompt="Workflows",
+            "workflow",
+            description="Workflows (comma separated)",
+            prompt="Workflows (comma separated)",
             default=lambda ctx: ",".join(llm_config.default_workflows),
             allow_positional_parsing=False,
             always_prompt=False,
@@ -237,7 +245,7 @@ llm_ask = LLMTask(
         None if ctx.input.system_prompt.strip() == "" else ctx.input.system_prompt
     ),
     workflows=lambda ctx: (
-        None if ctx.input.workflows.strip() == "" else ctx.input.workflows.split(",")
+        None if ctx.input.workflow.strip() == "" else ctx.input.workflow.split(",")
     ),
     attachment=_render_attach_input,
     message="{ctx.input.message}",
@@ -258,9 +266,10 @@ llm_group.add_task(
         callback=Callback(
             task=llm_ask,
             input_mapping=get_llm_ask_input_mapping,
-            result_queue="ask_result",
-            error_queue="ask_error",
-            session_name_queue="ask_session_name",
+            xcom_mapping={LLM_LOADED_WORKFLOW_XCOM_NAME: LLM_LOADED_WORKFLOW_XCOM_NAME},
+            result_queue=LLM_ASK_RESULT_XCOM_NAME,
+            error_queue=LLM_ASK_ERROR_XCOM_NAME,
+            session_name_queue=LLM_ASK_SESSION_XCOM_NAME,
         ),
         retries=0,
         cli_only=True,

zrb/builtin/llm/tool/cli.py

@@ -1,5 +1,11 @@
-import subprocess
+import asyncio
 import sys
+from typing import Callable
+
+from zrb.config.config import CFG
+from zrb.context.any_context import AnyContext
+from zrb.util.cli.style import stylize_faint
+from zrb.util.cmd.command import run_command
 
 if sys.version_info >= (3, 12):
     from typing import TypedDict
@@ -15,17 +21,25 @@ class ShellCommandResult(TypedDict):
         return_code: The return code, 0 indicating no error
         stdout: Standard output
         stderr: Standard error
+        display: Combination of standard output and standard error, interlaced
     """
 
     return_code: int
     stdout: str
     stderr: str
+    display: str
 
 
-def run_shell_command(command: str, timeout: int = 30) -> ShellCommandResult:
+async def run_shell_command(
+    ctx: AnyContext, command: str, timeout: int = 30
+) -> ShellCommandResult:
     """
     Executes a non-interactive shell command on the user's machine.
 
+    **EFFICIENCY TIP:**
+    Combine multiple shell commands into a single call using `&&` or `;` to save steps.
+    Example: `mkdir new_dir && cd new_dir && touch file.txt`
+
     CRITICAL: This tool runs with user-level permissions. Explain commands that modify
         the system (e.g., `git`, `pip`) and ask for confirmation.
     IMPORTANT: Long-running processes should be run in the background (e.g., `command &`).
@@ -42,23 +56,28 @@ def run_shell_command(command: str, timeout: int = 30) -> ShellCommandResult:
         dict: return_code, stdout, and stderr.
     """
     try:
-        result = subprocess.run(
-            command,
-            shell=True,
-            capture_output=True,
-            text=True,
+        cmd_result, return_code = await run_command(
+            [CFG.DEFAULT_SHELL, "-c", command],
+            print_method=_create_faint_print(ctx),
             timeout=timeout,
         )
         return {
-            "return_code": int(result.returncode),
-            "stdout": str(result.stdout or ""),
-            "stderr": str(result.stderr or ""),
+            "return_code": return_code,
+            "stdout": cmd_result.output,
+            "stderr": cmd_result.error,
+            "display": cmd_result.display,
         }
-    except subprocess.TimeoutExpired as e:
-        stdout = e.stdout.decode() if isinstance(e.stdout, bytes) else (e.stdout or "")
-        stderr = e.stderr.decode() if isinstance(e.stderr, bytes) else (e.stderr or "")
+    except asyncio.TimeoutError:
         return {
             "return_code": 124,
-            "stdout": str(stdout),
-            "stderr": f"{stderr}\nError: Command timed out after {timeout} seconds".strip(),
+            "stdout": "",
+            "stderr": f"Command timeout after {timeout} seconds",
+            "display": f"Command timeout after {timeout} seconds",
         }
+
+
+def _create_faint_print(ctx: AnyContext) -> Callable[..., None]:
+    def print_faint(text: str):
+        ctx.print(stylize_faint(f"  {text}"), plain=True)
+
+    return print_faint

zrb/builtin/llm/tool/file.py

@@ -89,6 +89,10 @@ def list_files(
     """
     Lists files recursively up to a specified depth.
 
+    **EFFICIENCY TIP:**
+    Do NOT use this tool if you already know the file path (e.g., from the user's prompt).
+    Use `read_from_file` directly in that case. Only use this to explore directory structures.
+
     Example:
     list_files(path='src', include_hidden=False, depth=2)
 
@@ -179,6 +183,12 @@ def read_from_file(
     """
     Reads content from one or more files, optionally specifying line ranges.
 
+    **EFFICIENCY TIP:**
+    For source code or configuration files, prefer reading the **entire file** at once
+    to ensure you have full context (imports, class definitions, etc.).
+    Only use `start_line` and `end_line` for extremely large files (like logs) or
+    when you are certain only a specific section is needed.
+
     Examples:
     ```
     # Read entire content of a single file
@@ -264,8 +274,9 @@ def write_to_file(
        - CORRECT: "content": "He said \"Hello\""
        - WRONG:   "content": "He said \\"Hello\\""  <-- This breaks JSON parsing!
     2. **SIZE LIMIT:** Content MUST NOT exceed 4000 characters.
-       - Exceeding this causes truncation and EOF errors.
-       - Split larger content into multiple sequential calls (first 'w', then 'a').
+       - **STRICT PROHIBITION:** You are FORBIDDEN from writing more than 4000 characters in a single call.
+       - This is due to LLM output token limits, which will cause truncation and failure.
+       - To write larger files, you MUST split the content into multiple sequential calls (e.g., first 'w', then 'a').
 
     Examples:
     ```
@@ -553,6 +564,7 @@ async def analyze_file(
         tools=[read_from_file, search_files],
         auto_summarize=False,
         remember_history=False,
+        yolo_mode=True,
     )
     payload = json.dumps(
         {

zrb/builtin/llm/tool/search/brave.py

@@ -1,7 +1,5 @@
 from typing import Any
 
-import requests
-
 from zrb.config.config import CFG
 
 
@@ -17,6 +15,12 @@ def search_internet(
     Use this tool to find up-to-date information, answer questions about current events,
     or research topics using a search engine.
 
+    **EFFICIENCY TIP:**
+    Make your `query` specific and keyword-rich to get the best results in a single call.
+    Avoid vague queries that require follow-up searches.
+    Bad: "new python features"
+    Good: "python 3.12 new features list release date"
+
     Args:
         query (str): The natural language search query (e.g., 'Soto Madura').
             Do NOT include instructions, meta-talk, or internal reasoning.
@@ -30,6 +34,8 @@ def search_internet(
     Returns:
         dict: Summary of search results (titles, links, snippets).
     """
+    import requests
+
     if safe_search is None:
         safe_search = CFG.BRAVE_API_SAFE
     if language is None:

zrb/builtin/llm/tool/search/searxng.py

@@ -1,7 +1,5 @@
 from typing import Any
 
-import requests
-
 from zrb.config.config import CFG
 
 
@@ -17,6 +15,12 @@ def search_internet(
     Use this tool to find up-to-date information, answer questions about current events,
     or research topics using a search engine.
 
+    **EFFICIENCY TIP:**
+    Make your `query` specific and keyword-rich to get the best results in a single call.
+    Avoid vague queries that require follow-up searches.
+    Bad: "new python features"
+    Good: "python 3.12 new features list release date"
+
     Args:
         query (str): The natural language search query (e.g., 'Soto Madura').
             Do NOT include instructions, meta-talk, or internal reasoning.
@@ -30,6 +34,8 @@ def search_internet(
     Returns:
         dict: Summary of search results (titles, links, snippets).
     """
+    import requests
+
     if safe_search is None:
         safe_search = CFG.SEARXNG_SAFE
     if language is None: