From c84d5ce738be4f27cff3300419407b2c9d5acdfb Mon Sep 17 00:00:00 2001 From: teknium1 Date: Sun, 1 Mar 2026 16:15:05 -0800 Subject: [PATCH] refactor(terminal_tool): clarify foreground and background process usage Updated documentation within terminal_tool.py to emphasize the appropriate use of foreground and background processes. Enhanced descriptions for the timeout setting and background execution to guide users towards optimal configurations for scripts, builds, and long-running tasks. Adjusted the default timeout value from 60 to 180 seconds for improved handling of longer operations. --- tools/terminal_tool.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/tools/terminal_tool.py b/tools/terminal_tool.py index f758768eb..4f8971985 100644 --- a/tools/terminal_tool.py +++ b/tools/terminal_tool.py @@ -346,7 +346,9 @@ Do NOT use sed/awk to edit files — use patch instead. Do NOT use echo/cat heredoc to create files — use write_file instead. Reserve terminal for: builds, installs, git, processes, scripts, network, package managers, and anything that needs a shell. -Background processes: Set background=true to get a session_id, then use the 'process' tool to poll/wait/kill/write. +Foreground (default): Commands return INSTANTLY when done, even if the timeout is high. Set timeout=300 for long builds/scripts — you'll still get the result in seconds if it's fast. Prefer foreground for everything that finishes. +Background: ONLY for long-running servers, watchers, or processes that never exit. Set background=true to get a session_id, then use process(action="wait") to block until done — it returns instantly on completion, same as foreground. Use process(action="poll") only when you need a progress check without blocking. +Do NOT use background for scripts, builds, or installs — foreground with a generous timeout is always better (fewer tool calls, instant results). Working directory: Use 'workdir' for per-command cwd. PTY mode: Set pty=true for interactive CLI tools (Codex, Claude Code, Python REPL). @@ -435,7 +437,7 @@ def _get_env_config() -> Dict[str, Any]: "singularity_image": os.getenv("TERMINAL_SINGULARITY_IMAGE", f"docker://{default_image}"), "modal_image": os.getenv("TERMINAL_MODAL_IMAGE", default_image), "cwd": cwd, - "timeout": int(os.getenv("TERMINAL_TIMEOUT", "60")), + "timeout": int(os.getenv("TERMINAL_TIMEOUT", "180")), "lifetime_seconds": int(os.getenv("TERMINAL_LIFETIME_SECONDS", "300")), # SSH-specific config "ssh_host": os.getenv("TERMINAL_SSH_HOST", ""), @@ -1154,12 +1156,12 @@ TERMINAL_SCHEMA = { }, "background": { "type": "boolean", - "description": "Whether to run the command in the background (default: false)", + "description": "ONLY for servers/watchers that never exit. For scripts, builds, installs — use foreground with timeout instead (it returns instantly when done).", "default": False }, "timeout": { "type": "integer", - "description": "Command timeout in seconds (optional)", + "description": "Max seconds to wait (default: 180). Returns INSTANTLY when command finishes — set high for long tasks, you won't wait unnecessarily.", "minimum": 1 }, "workdir": {