Package org.machanism.machai.ai.tools

Class CommandFunctionTools

java.lang.Object

org.machanism.machai.ai.tools.CommandFunctionTools

All Implemented Interfaces:

FunctionTools

public class CommandFunctionTools
extends Object
implements FunctionTools

Installs command-execution and process-termination tools into a Genai.

The installed tools provide a controlled wrapper around ProcessBuilder to execute a host command line within a validated working directory and capture both stdout and stderr into a bounded buffer (see LimitedStringBuilder).

Security model

Command execution is intended to be restricted by the host application. This implementation supports:

• A deny-list heuristic check via CommandSecurityChecker
• Project-root confinement for the working directory (see resolveWorkingDir(File, String))

Installed tools

• run_command_line_tool – executes a command line and returns output
• terminate_process – aborts execution by throwing a CommandFunctionTools.ProcessTerminationException

Author:

Viktor Tovstyi

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	CommandFunctionTools.ProcessTerminationException	Runtime exception used by terminate_process to signal early termination to the host.

Constructor Summary

Constructors

Constructor	Description
CommandFunctionTools()

Method Summary

Modifier and Type	Method	Description
void	applyTools(Genai provider)	Registers system command and process control tools with the provided Genai.
String	executeCommand(Object[] params)	Implements the run_command_line_tool tool.
Map<String,String>	parseEnv(String envString)	Parses the env parameter string into a map of environment variables.
File	resolveWorkingDir(File projectDir, String dir)	Resolves a working directory relative to a canonical project directory.
void	setConfigurator(Configurator configurator)	Provides a configurator instance to the tool set.
String	terminateProcess(Object[] params)	Implements the terminate_process tool.
(package private) String	waitAndCollect(Process process, Future<?> stdoutFuture, Future<?> stderrFuture, LimitedStringBuilder output, String commandId)	Waits for the process to finish (up to processTimeoutSeconds) and then returns collected output.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.machanism.machai.ai.tools.FunctionTools

replace

Constructor Details

CommandFunctionTools

public CommandFunctionTools()

Method Details

applyTools

public void applyTools(Genai provider)

Registers system command and process control tools with the provided Genai.

The following tools are installed:

• run_command_line_tool – Executes a system command using Java's ProcessBuilder.
  Parameters:
  • command (string, required): The command to execute.
  • env (string, optional): Environment variables as NAME=VALUE pairs separated by newline characters (\n).
  • dir (string, optional): Working directory relative to the project directory; defaults to ..
  • tailResultSize (integer, optional): Maximum number of characters to return from captured output; defaults to DEFAULT_RESULT_TAIL_SIZE.
  • charsetName (string, optional): Character set used to decode process output; defaults to DEFAULT_CHARSET.
• terminate_process – Throws an exception to immediately terminate execution.
  Parameters:
  • message (string, optional): Exception message; defaults to "Process terminated by function tool."
  • cause (string, optional): Optional cause message; wrapped in an Exception.
  • exitCode (integer, optional): Exit code; defaults to 1.

Specified by:

applyTools in interface FunctionTools

Parameters:

provider - the provider instance to which tools will be registered

terminateProcess

public String terminateProcess(Object[] params)

Implements the terminate_process tool.

Reads message, cause, and exitCode from the supplied JsonNode and throws a CommandFunctionTools.ProcessTerminationException. This mechanism allows a tool invocation to abort the overall workflow with an explicit exit code.

Parameters:

params - tool invocation parameters (expects a single JsonNode argument)

Returns:

never returns; always throws

Throws:

CommandFunctionTools.ProcessTerminationException - always thrown to terminate execution

executeCommand

public String executeCommand(Object[] params)
                      throws IOException

Implements the run_command_line_tool tool.

Expected parameters:

1. JsonNode containing command and optional settings
2. File project working directory supplied by the provider runtime

Parameters:

params - tool arguments

Returns:

command output bounded to the configured tail size

Throws:

IOException - if the process cannot be started or I/O occurs while resolving paths

waitAndCollect

String waitAndCollect(Process process,
 Future<?> stdoutFuture,
 Future<?> stderrFuture,
 LimitedStringBuilder output,
 String commandId)
               throws InterruptedException,
TimeoutException,
ExecutionException

Waits for the process to finish (up to processTimeoutSeconds) and then returns collected output.

This method also waits briefly for stdout/stderr reader tasks to complete so that output is not lost.

Parameters:

process - process being observed

stdoutFuture - future representing the stdout reader task

stderrFuture - future representing the stderr reader task

output - bounded output buffer

commandId - id used for log correlation

Returns:

collected output, followed by an exit-code line

Throws:

InterruptedException - if the current thread is interrupted while waiting

TimeoutException - if collecting output times out

ExecutionException - if a reader task fails

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

parseEnv

public Map<String,String> parseEnv(String envString)

Parses the env parameter string into a map of environment variables.

Lines are separated by \n (or \n); empty lines and lines starting with # are ignored.

Parameters:

envString - environment string

Returns:

parsed environment variables

setConfigurator

public void setConfigurator(Configurator configurator)

Description copied from interface: FunctionTools

Provides a configurator instance to the tool set.

The default implementation does nothing.

Specified by:

setConfigurator in interface FunctionTools

Parameters:

configurator - configurator to use for runtime value resolution