<tools>
  <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="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="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="timeout" type="number" required="false">
        <description>Optional timeout in seconds for command execution. CAPPED AT 60 SECONDS. If not provided, uses default wait (30s). On timeout, the command keeps running and the tool returns with status 'running'. For truly long-running tasks, prefer backgrounding with '&'.</description>
      </parameter>
      <parameter name="terminal_id" type="string" required="false">
        <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:
      - 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. PERSISTENT SESSION: The terminal maintains state between commands. Environment variables,
     current directory, and running processes persist across multiple tool calls.

  2. COMMAND EXECUTION:
     - AVOID: Long pipelines, complex bash scripts, or convoluted one-liners
     - Break complex operations into multiple simple tool calls for clarity and debugging
     - For multiple commands, prefer separate tool calls over chaining with && or ;
     - Do NOT use this tool to run embedded Python via heredocs, here-strings, python -c, or ad hoc Python REPL input when python_action can be used instead
     - If the task is primarily Python code execution, data processing, HTTP automation in Python, or iterative Python scripting, use python_action because it is persistent, structured, and easier to debug
     - Use terminal_execute for actual shell work: CLI tools, package managers, file/system commands, process control, and starting or supervising services
     - Before improvising a complex workflow, payload set, protocol sequence, or tool syntax from memory, consider calling load_skill to inject the exact specialized guidance you need
     - Prefer load_skill plus the right tool over ad hoc shell experimentation when a relevant skill exists

  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
     - For daemons/servers or very long jobs, append '&' to run in background
     - 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 (max 60s cap)
     - Commands are NEVER killed on timeout - they keep running
     - After timeout, you can run new commands or check progress with empty command
     - On timeout, status is 'running'; on completion, status is 'completed'

  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>
  # Execute a simple command
  <function=terminal_execute>
  <parameter=command>ls -la</parameter>
  </function>

  <function=terminal_execute>
  <parameter=command>cd /workspace
pwd
ls -la</parameter>
  </function>

  # Run a command with custom timeout
  <function=terminal_execute>
  <parameter=command>npm install</parameter>
  <parameter=timeout>60</parameter>
  </function>

  # Check progress of running command (waits for timeout to collect output)
  <function=terminal_execute>
  <parameter=command></parameter>
  <parameter=timeout>5</parameter>
  </function>

  # Start a background service
  <function=terminal_execute>
  <parameter=command>python app.py > server.log 2>&1 &</parameter>
  </function>

  # Interact with a running process
  <function=terminal_execute>
  <parameter=command>y</parameter>
  <parameter=is_input>true</parameter>
  </function>

  # Interrupt a running process (special keys work automatically)
  <function=terminal_execute>
  <parameter=command>C-c</parameter>
  </function>

  # Send Escape key (use official tmux name)
  <function=terminal_execute>
  <parameter=command>Escape</parameter>
  <parameter=is_input>true</parameter>
  </function>

  # Use a different terminal session
  <function=terminal_execute>
  <parameter=command>python3</parameter>
  <parameter=terminal_id>python_session</parameter>
  </function>

  # 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>
</tools>
