Package org.machanism.machai.gw.tools

Class CommandFunctionTools

java.lang.Object

org.machanism.machai.gw.tools.CommandFunctionTools

All Implemented Interfaces:

FunctionTools

public class CommandFunctionTools
extends Object
implements FunctionTools

Provides function tools for executing and managing system commands within a project context.

This class exposes methods for:

• Securely executing system commands with controlled environment variables, working directory, output tailing, and character encoding
• Retrieving and searching command execution logs, including paginated log chunks and regular expression matches
• Resolving working directories and securely handling command input/output
• Replacing placeholders in command strings using project configuration

All command execution is subject to security checks and is logged for diagnostics. Output is captured and can be retrieved or searched after execution.

Methods in this class are typically invoked by an AI provider or workflow engine to enable dynamic, tool-augmented project automation.

Author:

Viktor Tovstyi

Constructor Summary

Constructors

Constructor	Description
CommandFunctionTools()

Method Summary

Modifier and Type	Method	Description
Object	executeCommand(String command, Map<String,String> properties, String dir, int tailResultSize, String charsetName, File projectDir, Configurator configurator)	Executes a system command using Java's ProcessBuilder for controlled and secure execution.
Object	getLogMatches(String logId, String regexp, String charsetName)	Searches a persisted command log for all substrings matching the supplied Java regular expression.
Object	getPreviousLogChunk(String logId, int tailResultSize, int currentTailOffset, String charsetName)	Retrieves the chunk of previously captured command output that immediately precedes the current tail window.
File	resolveWorkingDir(File projectDir, String dir)	Resolves a working directory relative to a canonical project directory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

CommandFunctionTools

public CommandFunctionTools()

Method Details

executeCommand

public Object executeCommand(String command,
 Map<String,String> properties,
 String dir,
 int tailResultSize,
 String charsetName,
 File projectDir,
 Configurator configurator)
                      throws IOException

Executes a system command using Java's ProcessBuilder for controlled and secure execution.

Only explicitly allowed commands can be executed for security reasons. Supports setting environment variables, working directory, output tail size, and character encoding.

Parameters:

configurator -

Throws:

IOException

getPreviousLogChunk

public Object getPreviousLogChunk(String logId,
 int tailResultSize,
 int currentTailOffset,
 String charsetName)
                           throws IOException

Retrieves the chunk of previously captured command output that immediately precedes the current tail window.

The command output is read from the persisted log file associated with the supplied logId. The returned substring starts at max(0, currentTailOffset - tailResultSize) and ends at currentTailOffset.

Throws:

IOException

getLogMatches

public Object getLogMatches(String logId,
 String regexp,
 String charsetName)

Searches a persisted command log for all substrings matching the supplied Java regular expression.

resolveWorkingDir

public File resolveWorkingDir(File projectDir,
 String dir)

Resolves a working directory relative to a canonical project directory.

Absolute paths are rejected and attempts to traverse outside the project directory are blocked.

Parameters:

projectDir - canonical project directory

dir - requested relative directory (or .)

Returns:

resolved directory, or null if invalid