strix-agent 0.1.9__py3-none-any.whl → 0.1.11__py3-none-any.whl

strix/runtime/tool_server.py

@@ -1,7 +1,15 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
 import logging
 import os
+import signal
+import sys
+from multiprocessing import Process, Queue
 from typing import Any
 
+import uvicorn
 from fastapi import Depends, FastAPI, HTTPException, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from pydantic import BaseModel, ValidationError
@@ -11,20 +19,25 @@ SANDBOX_MODE = os.getenv("STRIX_SANDBOX_MODE", "false").lower() == "true"
 if not SANDBOX_MODE:
     raise RuntimeError("Tool server should only run in sandbox mode (STRIX_SANDBOX_MODE=true)")
 
-EXPECTED_TOKEN = os.getenv("STRIX_SANDBOX_TOKEN")
-if not EXPECTED_TOKEN:
-    raise RuntimeError("STRIX_SANDBOX_TOKEN environment variable is required in sandbox mode")
+parser = argparse.ArgumentParser(description="Start Strix tool server")
+parser.add_argument("--token", required=True, help="Authentication token")
+parser.add_argument("--host", default="0.0.0.0", help="Host to bind to")  # nosec
+parser.add_argument("--port", type=int, required=True, help="Port to bind to")
+
+args = parser.parse_args()
+EXPECTED_TOKEN = args.token
 
 app = FastAPI()
-logger = logging.getLogger(__name__)
 security = HTTPBearer()
 
 security_dependency = Depends(security)
 
+agent_processes: dict[str, dict[str, Any]] = {}
+agent_queues: dict[str, dict[str, Queue[Any]]] = {}
+
 
 def verify_token(credentials: HTTPAuthorizationCredentials) -> str:
     if not credentials or credentials.scheme != "Bearer":
-        logger.warning("Authentication failed: Invalid or missing Bearer token scheme")
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="Invalid authentication scheme. Bearer token required.",
@@ -32,18 +45,17 @@ def verify_token(credentials: HTTPAuthorizationCredentials) -> str:
         )
 
     if credentials.credentials != EXPECTED_TOKEN:
-        logger.warning("Authentication failed: Invalid token provided from remote host")
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="Invalid authentication token",
             headers={"WWW-Authenticate": "Bearer"},
         )
 
-    logger.debug("Authentication successful for tool execution request")
     return credentials.credentials
 
 
 class ToolExecutionRequest(BaseModel):
+    agent_id: str
     tool_name: str
     kwargs: dict[str, Any]
 
@@ -53,45 +65,141 @@ class ToolExecutionResponse(BaseModel):
     error: str | None = None
 
 
+def agent_worker(_agent_id: str, request_queue: Queue[Any], response_queue: Queue[Any]) -> None:
+    null_handler = logging.NullHandler()
+
+    root_logger = logging.getLogger()
+    root_logger.handlers = [null_handler]
+    root_logger.setLevel(logging.CRITICAL)
+
+    from strix.tools.argument_parser import ArgumentConversionError, convert_arguments
+    from strix.tools.registry import get_tool_by_name
+
+    while True:
+        try:
+            request = request_queue.get()
+
+            if request is None:
+                break
+
+            tool_name = request["tool_name"]
+            kwargs = request["kwargs"]
+
+            try:
+                tool_func = get_tool_by_name(tool_name)
+                if not tool_func:
+                    response_queue.put({"error": f"Tool '{tool_name}' not found"})
+                    continue
+
+                converted_kwargs = convert_arguments(tool_func, kwargs)
+                result = tool_func(**converted_kwargs)
+
+                response_queue.put({"result": result})
+
+            except (ArgumentConversionError, ValidationError) as e:
+                response_queue.put({"error": f"Invalid arguments: {e}"})
+            except (RuntimeError, ValueError, ImportError) as e:
+                response_queue.put({"error": f"Tool execution error: {e}"})
+
+        except (RuntimeError, ValueError, ImportError) as e:
+            response_queue.put({"error": f"Worker error: {e}"})
+
+
+def ensure_agent_process(agent_id: str) -> tuple[Queue[Any], Queue[Any]]:
+    if agent_id not in agent_processes:
+        request_queue: Queue[Any] = Queue()
+        response_queue: Queue[Any] = Queue()
+
+        process = Process(
+            target=agent_worker, args=(agent_id, request_queue, response_queue), daemon=True
+        )
+        process.start()
+
+        agent_processes[agent_id] = {"process": process, "pid": process.pid}
+        agent_queues[agent_id] = {"request": request_queue, "response": response_queue}
+
+    return agent_queues[agent_id]["request"], agent_queues[agent_id]["response"]
+
+
 @app.post("/execute", response_model=ToolExecutionResponse)
 async def execute_tool(
     request: ToolExecutionRequest, credentials: HTTPAuthorizationCredentials = security_dependency
 ) -> ToolExecutionResponse:
     verify_token(credentials)
 
-    from strix.tools.argument_parser import ArgumentConversionError, convert_arguments
-    from strix.tools.registry import get_tool_by_name
+    request_queue, response_queue = ensure_agent_process(request.agent_id)
+
+    request_queue.put({"tool_name": request.tool_name, "kwargs": request.kwargs})
 
     try:
-        tool_func = get_tool_by_name(request.tool_name)
-        if not tool_func:
-            return ToolExecutionResponse(error=f"Tool '{request.tool_name}' not found")
+        loop = asyncio.get_event_loop()
+        response = await loop.run_in_executor(None, response_queue.get)
 
-        converted_kwargs = convert_arguments(tool_func, request.kwargs)
+        if "error" in response:
+            return ToolExecutionResponse(error=response["error"])
+        return ToolExecutionResponse(result=response.get("result"))
 
-        result = tool_func(**converted_kwargs)
+    except (RuntimeError, ValueError, OSError) as e:
+        return ToolExecutionResponse(error=f"Worker error: {e}")
 
-        return ToolExecutionResponse(result=result)
 
-    except (ArgumentConversionError, ValidationError) as e:
-        logger.warning("Invalid tool arguments: %s", e)
-        return ToolExecutionResponse(error=f"Invalid arguments: {e}")
-    except TypeError as e:
-        logger.warning("Tool execution type error: %s", e)
-        return ToolExecutionResponse(error=f"Tool execution error: {e}")
-    except ValueError as e:
-        logger.warning("Tool execution value error: %s", e)
-        return ToolExecutionResponse(error=f"Tool execution error: {e}")
-    except Exception:
-        logger.exception("Unexpected error during tool execution")
-        return ToolExecutionResponse(error="Internal server error")
+@app.post("/register_agent")
+async def register_agent(
+    agent_id: str, credentials: HTTPAuthorizationCredentials = security_dependency
+) -> dict[str, str]:
+    verify_token(credentials)
+
+    ensure_agent_process(agent_id)
+    return {"status": "registered", "agent_id": agent_id}
 
 
 @app.get("/health")
-async def health_check() -> dict[str, str]:
+async def health_check() -> dict[str, Any]:
     return {
         "status": "healthy",
         "sandbox_mode": str(SANDBOX_MODE),
         "environment": "sandbox" if SANDBOX_MODE else "main",
         "auth_configured": "true" if EXPECTED_TOKEN else "false",
+        "active_agents": len(agent_processes),
+        "agents": list(agent_processes.keys()),
     }
+
+
+def cleanup_all_agents() -> None:
+    for agent_id in list(agent_processes.keys()):
+        try:
+            agent_queues[agent_id]["request"].put(None)
+            process = agent_processes[agent_id]["process"]
+
+            process.join(timeout=1)
+
+            if process.is_alive():
+                process.terminate()
+                process.join(timeout=1)
+
+            if process.is_alive():
+                process.kill()
+
+        except (BrokenPipeError, EOFError, OSError):
+            pass
+        except (RuntimeError, ValueError) as e:
+            logging.getLogger(__name__).debug(f"Error during agent cleanup: {e}")
+
+
+def signal_handler(_signum: int, _frame: Any) -> None:
+    signal.signal(signal.SIGPIPE, signal.SIG_IGN) if hasattr(signal, "SIGPIPE") else None
+    cleanup_all_agents()
+    sys.exit(0)
+
+
+if hasattr(signal, "SIGPIPE"):
+    signal.signal(signal.SIGPIPE, signal.SIG_IGN)
+
+signal.signal(signal.SIGTERM, signal_handler)
+signal.signal(signal.SIGINT, signal_handler)
+
+if __name__ == "__main__":
+    try:
+        uvicorn.run(app, host=args.host, port=args.port, log_level="info")
+    finally:
+        cleanup_all_agents()

strix/tools/agents_graph/agents_graph_actions.py

@@ -57,10 +57,10 @@ def _run_agent_in_thread(
         - Work independently with your own approach
         - Use agent_finish when complete to report back to parent
         - You are a SPECIALIST for this specific task
-        - The previous browser, sessions, proxy history, and files in /workspace were for your
-          parent agent. Do not depend on them.
-        - You are starting with a fresh context. Fresh proxy, browser, and files.
-          Only stuff in /shared_workspace is passed to you from context.
+        - You share the same container as other agents but have your own tool server instance
+        - All agents share /workspace directory and proxy history for better collaboration
+        - You can see files created by other agents and proxy traffic from previous work
+        - Build upon previous work but focus on your specific delegated task
     </instructions>
 </agent_delegation>"""
 

strix/tools/agents_graph/agents_graph_actions_schema.xml

@@ -80,7 +80,7 @@ Only create a new agent if no existing agent is handling the specific task.</des
         <description>Whether the new agent should inherit parent's conversation history and context</description>
       </parameter>
       <parameter name="prompt_modules" type="string" required="false">
-        <description>Comma-separated list of prompt modules to use for the agent. Most agents should have at least one module in order to be useful. {{DYNAMIC_MODULES_DESCRIPTION}}</description>
+        <description>Comma-separated list of prompt modules to use for the agent (MAXIMUM 3 modules allowed). Most agents should have at least one module in order to be useful. Agents should be highly specialized - use 1-3 related vulnerability modules only. {{DYNAMIC_MODULES_DESCRIPTION}}</description>
       </parameter>
     </parameters>
     <returns type="Dict[str, Any]">
@@ -104,6 +104,22 @@ Only create a new agent if no existing agent is handling the specific task.</des
               for security vulnerabilities and bypass techniques.</parameter>
   <parameter=name>Auth Specialist</parameter>
   <parameter=prompt_modules>authentication_jwt, business_logic</parameter>
+  </function>
+
+  # Example of single-module specialization (most focused)
+  <function=create_agent>
+  <parameter=task>Perform comprehensive XSS testing including reflected, stored, and DOM-based
+              variants across all identified input points.</parameter>
+  <parameter=name>XSS Specialist</parameter>
+  <parameter=prompt_modules>xss</parameter>
+  </function>
+
+  # Example of maximum 3 related modules (borderline acceptable)
+  <function=create_agent>
+  <parameter=task>Test for server-side vulnerabilities including SSRF, XXE, and potential
+              RCE vectors in file upload and XML processing endpoints.</parameter>
+  <parameter=name>Server-Side Attack Specialist</parameter>
+  <parameter=prompt_modules>ssrf, xxe, rce</parameter>
   </function>
     </examples>
   </tool>

strix/tools/argument_parser.py

@@ -1,6 +1,7 @@
 import contextlib
 import inspect
 import json
+import types
 from collections.abc import Callable
 from typing import Any, Union, get_args, get_origin
 
@@ -48,7 +49,7 @@ def convert_arguments(func: Callable[..., Any], kwargs: dict[str, Any]) -> dict[
 
 def convert_string_to_type(value: str, param_type: Any) -> Any:
     origin = get_origin(param_type)
-    if origin is Union or origin is type(str | None):
+    if origin is Union or isinstance(param_type, types.UnionType):
         args = get_args(param_type)
         for arg_type in args:
             if arg_type is not type(None):

strix/tools/executor.py

@@ -49,7 +49,10 @@ async def _execute_tool_in_sandbox(tool_name: str, agent_state: Any, **kwargs: A
     server_url = await runtime.get_sandbox_url(agent_state.sandbox_id, tool_server_port)
     request_url = f"{server_url}/execute"
 
+    agent_id = getattr(agent_state, "agent_id", "unknown")
+
     request_data = {
+        "agent_id": agent_id,
         "tool_name": tool_name,
         "kwargs": kwargs,
     }

strix/tools/terminal/__init__.py

@@ -1,4 +1,4 @@
-from .terminal_actions import terminal_action
+from .terminal_actions import terminal_execute
 
 
-__all__ = ["terminal_action"]
+__all__ = ["terminal_execute"]

strix/tools/terminal/terminal_actions.py

@@ -1,53 +1,35 @@
-from typing import Any, Literal
+from typing import Any
 
 from strix.tools.registry import register_tool
 
 from .terminal_manager import get_terminal_manager
 
 
-TerminalAction = Literal["new_terminal", "send_input", "wait", "close"]
-
-
 @register_tool
-def terminal_action(
-    action: TerminalAction,
-    inputs: list[str] | None = None,
-    time: float | None = None,
+def terminal_execute(
+    command: str,
+    is_input: bool = False,
+    timeout: float | None = None,
     terminal_id: str | None = None,
+    no_enter: bool = False,
 ) -> dict[str, Any]:
-    def _validate_inputs(action_name: str, inputs: list[str] | None) -> None:
-        if not inputs:
-            raise ValueError(f"inputs parameter is required for {action_name} action")
-
-    def _validate_time(time_param: float | None) -> None:
-        if time_param is None:
-            raise ValueError("time parameter is required for wait action")
-
-    def _validate_action(action_name: str) -> None:
-        raise ValueError(f"Unknown action: {action_name}")
-
     manager = get_terminal_manager()
 
     try:
-        match action:
-            case "new_terminal":
-                return manager.create_terminal(terminal_id, inputs)
-
-            case "send_input":
-                _validate_inputs(action, inputs)
-                assert inputs is not None
-                return manager.send_input(terminal_id, inputs)
-
-            case "wait":
-                _validate_time(time)
-                assert time is not None
-                return manager.wait_terminal(terminal_id, time)
-
-            case "close":
-                return manager.close_terminal(terminal_id)
-
-            case _:
-                _validate_action(action)  # type: ignore[unreachable]
-
+        return manager.execute_command(
+            command=command,
+            is_input=is_input,
+            timeout=timeout,
+            terminal_id=terminal_id,
+            no_enter=no_enter,
+        )
     except (ValueError, RuntimeError) as e:
-        return {"error": str(e), "terminal_id": terminal_id, "snapshot": "", "is_running": False}
+        return {
+            "error": str(e),
+            "command": command,
+            "terminal_id": terminal_id or "default",
+            "content": "",
+            "status": "error",
+            "exit_code": None,
+            "working_dir": None,
+        }

strix/tools/terminal/terminal_actions_schema.xml

@@ -1,117 +1,142 @@
 <tools>
-  <tool name="terminal_action">
-    <description>Perform terminal actions using a terminal emulator instance. Each terminal instance
-  is PERSISTENT and remains active until explicitly closed, allowing for multi-step
-  workflows and long-running processes.</description>
+  <tool name="terminal_execute">
+    <description>Execute a bash command in a persistent terminal session. The terminal maintains state (environment variables, current directory, running processes) between commands.</description>
     <parameters>
-      <parameter name="action" type="string" required="true">
-        <description>The terminal action to perform: - new_terminal: Create a new terminal instance. This MUST be the first action   for each terminal tab. - send_input: Send keyboard input to the specified terminal. - wait: Pause execution for specified number of seconds. Can be also used to get   the current terminal state (screenshot, output, etc.) after using other tools. - close: Close the specified terminal instance. This MUST be the final action   for each terminal tab.</description>
+      <parameter name="command" type="string" required="true">
+        <description>The bash command to execute. Can be empty to check output of running commands (will wait for timeout period to collect output).
+
+        Supported special keys and sequences (based on official tmux key names):
+        - Control sequences: C-c, C-d, C-z, C-a, C-e, C-k, C-l, C-u, C-w, etc. (also ^c, ^d, etc.)
+        - Navigation keys: Up, Down, Left, Right, Home, End
+        - Page keys: PageUp, PageDown, PgUp, PgDn, PPage, NPage
+        - Function keys: F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12
+        - Special keys: Enter, Escape, Space, Tab, BTab, BSpace, DC, IC
+        - Note: Use official tmux names (BSpace not Backspace, DC not Delete, IC not Insert, Escape not Esc)
+        - Meta/Alt sequences: M-key (e.g., M-f, M-b) - tmux official modifier
+        - Shift sequences: S-key (e.g., S-F6, S-Tab, S-Left)
+        - Combined modifiers: C-S-key, C-M-key, S-M-key, etc.
+
+        Special keys work automatically - no need to set is_input=true for keys like C-c, C-d, etc.
+        These are useful for interacting with vim, emacs, REPLs, and other interactive applications.</description>
       </parameter>
-      <parameter name="inputs" type="string" required="false">
-        <description>Required for 'new_terminal' and 'send_input' actions: - List of inputs to send to terminal.   Each element in the list MUST be one of the following:   - Regular text: "hello", "world", etc.   - Literal text (not interpreted as special keys): prefix with "literal:"     e.g., "literal:Home", "literal:Escape", "literal:Enter" to send these as text   - Enter   - Space   - Backspace   - Escape: "Escape", "^[", "C-["   - Tab: "Tab"   - Arrow keys: "Left", "Right", "Up", "Down"   - Navigation: "Home", "End", "PageUp", "PageDown"   - Function keys: "F1" through "F12"   Modifier keys supported with prefixes:   - ^ or C- : Control (e.g., "^c", "C-c")   - S- : Shift (e.g., "S-F6")   - A- : Alt (e.g., "A-Home")   - Combined modifiers for arrows: "S-A-Up", "C-S-Left"   - Inputs MUST in all cases be sent as a LIST of strings, even if you are only     sending one input.   - Sending Inputs as a single string will NOT work.</description>
+      <parameter name="is_input" type="boolean" required="false">
+        <description>If true, the command is sent as input to a currently running process. If false (default), the command is executed as a new bash command.
+        Note: Special keys (C-c, C-d, etc.) automatically work when a process is running - you don't need to set is_input=true for them.
+        Use is_input=true for regular text input to running processes.</description>
       </parameter>
-      <parameter name="time" type="string" required="false">
-        <description>Required for 'wait' action. Number of seconds to pause execution. Can be fractional (e.g., 0.5 for half a second).</description>
+      <parameter name="timeout" type="number" required="false">
+        <description>Optional timeout in seconds for command execution. If not provided, uses default timeout behavior. Set to higher values for long-running commands like installations or tests. Default is 10 seconds.</description>
       </parameter>
       <parameter name="terminal_id" type="string" required="false">
-        <description>Identifier for the terminal instance. Required for all actions except the first 'new_terminal' action. Allows managing multiple concurrent terminal tabs. - For 'new_terminal': if not provided, a default terminal is created. If provided,   creates a new terminal with that ID. - For other actions: specifies which terminal instance to operate on. - Default terminal ID is "default" if not specified.</description>
+        <description>Identifier for the terminal session. Defaults to "default". Use different IDs to manage multiple concurrent terminal sessions.</description>
+      </parameter>
+      <parameter name="no_enter" type="boolean" required="false">
+        <description>If true, don't automatically add Enter/newline after the command. Useful for:
+        - Interactive prompts where you want to send keys without submitting
+        - Navigation keys in full-screen applications
+
+        Examples:
+        - terminal_execute("gg", is_input=true, no_enter=true)  # Vim: go to top
+        - terminal_execute("5j", is_input=true, no_enter=true)  # Vim: move down 5 lines
+        - terminal_execute("i", is_input=true, no_enter=true)   # Vim: insert mode</description>
       </parameter>
     </parameters>
     <returns type="Dict[str, Any]">
-      <description>Response containing: - snapshot: raw representation of current terminal state where you can see the   output of the command - terminal_id: the ID of the terminal instance that was operated on</description>
+      <description>Response containing:
+      - content: Command output
+      - exit_code: Exit code of the command (only for completed commands)
+      - command: The executed command
+      - terminal_id: The terminal session ID
+      - status: Command status ('completed' or 'running')
+      - working_dir: Current working directory after command execution</description>
     </returns>
     <notes>
   Important usage rules:
-  1. PERSISTENCE: Terminal instances remain active and maintain their state (environment
-     variables, current directory, running processes) until explicitly closed with the
-     'close' action. This allows for multi-step workflows across multiple tool calls.
-  2. MULTIPLE TERMINALS: You can run multiple terminal instances concurrently by using
-     different terminal_id values. Each terminal operates independently.
-  3. Terminal interaction MUST begin with 'new_terminal' action for each terminal instance.
-  4. Only one action can be performed per call.
-  5. Input handling:
-     - Regular text is sent as-is
-     - Literal text: prefix with "literal:" to send special key names as literal text
-     - Special keys must match supported key names
-     - Modifier combinations follow specific syntax
-     - Control can be specified as ^ or C- prefix
-     - Shift (S-) works with special keys only
-     - Alt (A-) works with any character/key
-  6. Wait action:
-      - Time is specified in seconds
-      - Can be used to wait for command completion
-      - Can be fractional (e.g., 0.5 seconds)
-      - Snapshot and output are captured after the wait
-      - You should estimate the time it will take to run the command and set the wait time accordingly.
-      - It can be from a few seconds to a few minutes, choose wisely depending on the command you are running and the task.
-  7. The terminal can operate concurrently with other tools. You may invoke
-     browser, proxy, or other tools (in separate assistant messages) while maintaining
-     active terminal sessions.
-  8. You do not need to close terminals after you are done, but you can if you want to
-     free up resources.
-  9. You MUST end the inputs list with an "Enter" if you want to run the command, as
-     it is not sent automatically.
-  10. AUTOMATIC SPACING BEHAVIOR:
-      - Consecutive regular text inputs have spaces automatically added between them
-      - This is helpful for shell commands: ["ls", "-la"] becomes "ls -la"
-      - This causes problems for compound commands: [":", "w", "q"] becomes ": w q"
-      - Use "literal:" prefix to bypass spacing: [":", "literal:wq"] becomes ":wq"
-      - Special keys (Enter, Space, etc.) and literal strings never trigger spacing
-  11. WHEN TO USE LITERAL PREFIX:
-      - Vim commands: [":", "literal:wq", "Enter"] instead of [":", "w", "q", "Enter"]
-      - Any sequence where exact character positioning matters
-      - When you need multiple characters sent as a single unit
-  12. Do NOT use terminal actions for file editing or writing. Use the replace_in_file,
-      write_to_file, or read_file tools instead.
-  13. PREFER SIMPLE COMMANDS: Avoid complex multiline commands with nested quotes or
-      complex syntax. Break down complex operations into simpler, individual commands
-      for better reliability and readability. Never send multiple commands in a single
-      input list with multiple "Enter" keys - execute one command at a time instead.
+  1. PERSISTENT SESSION: The terminal maintains state between commands. Environment variables,
+     current directory, and running processes persist across multiple tool calls.
+
+  2. COMMAND EXECUTION: Execute one command at a time. For multiple commands, chain them with
+     && or ; operators, or make separate tool calls.
+
+  3. LONG-RUNNING COMMANDS:
+     - Commands never get killed automatically - they keep running in background
+     - Set timeout to control how long to wait for output before returning
+     - Use empty command "" to check progress (waits for timeout period to collect output)
+     - Use C-c, C-d, C-z to interrupt processes (works automatically, no is_input needed)
+
+  4. TIMEOUT HANDLING:
+     - Timeout controls how long to wait before returning current output
+     - Commands are NEVER killed on timeout - they keep running
+     - After timeout, you can run new commands or check progress with empty command
+     - All commands return status "completed" - you have full control
+
+  5. MULTIPLE TERMINALS: Use different terminal_id values to run multiple concurrent sessions.
+
+  6. INTERACTIVE PROCESSES:
+     - Special keys (C-c, C-d, etc.) work automatically when a process is running
+     - Use is_input=true for regular text input to running processes like:
+       * Interactive shells, REPLs, or prompts
+       * Long-running applications waiting for input
+       * Background processes that need interaction
+     - Use no_enter=true for stuff like Vim navigation, password typing, or multi-step commands
+
+  7. WORKING DIRECTORY: The terminal tracks and returns the current working directory.
+     Use absolute paths or cd commands to change directories as needed.
+
+  8. OUTPUT HANDLING: Large outputs are automatically truncated. The tool provides
+     the most relevant parts of the output for analysis.
     </notes>
     <examples>
-  # Create new terminal with Node.js (default terminal)
-  <function=terminal_action>
-  <parameter=action>new_terminal</parameter>
-  <parameter=inputs>["node", "Enter"]</parameter>
+  # Execute a simple command
+  <function=terminal_execute>
+  <parameter=command>ls -la</parameter>
+  </function>
+
+  # Run a command with custom timeout
+  <function=terminal_execute>
+  <parameter=command>npm install</parameter>
+  <parameter=timeout>120</parameter>
+  </function>
+
+  # Check progress of running command (waits for timeout to collect output)
+  <function=terminal_execute>
+  <parameter=command></parameter>
+  <parameter=timeout>5</parameter>
   </function>
 
-  # Create a second (parallel) terminal instance for Python
-  <function=terminal_action>
-  <parameter=action>new_terminal</parameter>
-  <parameter=terminal_id>python_terminal</parameter>
-  <parameter=inputs>["python3", "Enter"]</parameter>
+  # Start a background service
+  <function=terminal_execute>
+  <parameter=command>python app.py > server.log 2>&1 &</parameter>
   </function>
 
-  # Send command to the default terminal
-  <function=terminal_action>
-  <parameter=action>send_input</parameter>
-  <parameter=inputs>["require('crypto').randomBytes(1000000).toString('hex')",
-                     "Enter"]</parameter>
+  # Interact with a running process
+  <function=terminal_execute>
+  <parameter=command>y</parameter>
+  <parameter=is_input>true</parameter>
   </function>
 
-  # Wait for previous action on default terminal
-  <function=terminal_action>
-  <parameter=action>wait</parameter>
-  <parameter=time>2.0</parameter>
+  # Interrupt a running process (special keys work automatically)
+  <function=terminal_execute>
+  <parameter=command>C-c</parameter>
   </function>
 
-  # Send multiple inputs with special keys to current terminal
-  <function=terminal_action>
-  <parameter=action>send_input</parameter>
-  <parameter=inputs>["sqlmap -u 'http://example.com/page.php?id=1' --batch", "Enter", "y",
-               "Enter", "n", "Enter", "n", "Enter"]</parameter>
+  # Send Escape key (use official tmux name)
+  <function=terminal_execute>
+  <parameter=command>Escape</parameter>
+  <parameter=is_input>true</parameter>
   </function>
 
-  # WRONG: Vim command with automatic spacing (becomes ": w q")
-  <function=terminal_action>
-  <parameter=action>send_input</parameter>
-  <parameter=inputs>[":", "w", "q", "Enter"]</parameter>
+  # Use a different terminal session
+  <function=terminal_execute>
+  <parameter=command>python3</parameter>
+  <parameter=terminal_id>python_session</parameter>
   </function>
 
-  # CORRECT: Vim command using literal prefix (becomes ":wq")
-  <function=terminal_action>
-  <parameter=action>send_input</parameter>
-  <parameter=inputs>[":", "literal:wq", "Enter"]</parameter>
+  # Send input to Python REPL in specific session
+  <function=terminal_execute>
+  <parameter=command>print("Hello World")</parameter>
+  <parameter=is_input>true</parameter>
+  <parameter=terminal_id>python_session</parameter>
   </function>
     </examples>
   </tool>