Package org.machanism.machai.gw.tools
This package is the integration boundary between an AI provider and a
project-scoped workflow. Its FunctionTools
implementations expose annotated operations to the provider, while the
Ghostwriter processors perform the corresponding workflow work. File and
command paths are resolved against the active project directory; asynchronous
operations persist serialized results or logs below the runtime temporary
directory and return an identifier for later polling or inspection.
AI metadata
Every method annotated with
@Tool is a Functional AI
Tool. Its name, parameter descriptions, defaults, return contract, and
failure behavior are published as a callable operation. Methods annotated
with @Prompt are Prompt
Templates; they provide reusable instructions from the
mcp-prompts resource bundle. This package contains no class or method
annotated with @Resource, and therefore declares no Contextual
Resource. Package-level Javadoc has no callable parameters, return value,
or thrown exception; the @param, @return, and @throws
contracts for each public constructor and method are documented on the
declaring element.
Tool providers
ActFunctionToolsis the Act Functional AI Tool provider. It loads Act definitions, performs Acts synchronously or asynchronously, polls serialized results, and exposes the Act Prompt Template.GuidanceFunctionToolsdiscovers files containing guidance tags, processes them synchronously or in the background, polls processing reports, and exposes the guidance-processing Prompt Template.FileFunctionToolslists project files and folders, reads and writes bounded project files, and applies validated unified or simplified patches throughPatchApplier.WebFunctionToolsretrieves HTTP(S) responses or project-scopedfile:content, supports CSS selection and text rendering, and performs REST requests with headers and Basic authentication.CommandFunctionToolsexecutes project-bounded operating-system commands, captures bounded output, and provides log paging and regular-expression search. It delegates deny-list checks toCommandSecurityCheckerand records output and timing reports throughLogBuilder.ProjectContextFunctionToolsstores, retrieves, pushes, and pops project-scoped workflow state. These values are shared by Acts and episodes and are not operating-system environment variables.
Workflow control and failures
ActSpecFunctionTools is restricted
to Act processing and signals episode navigation or repetition through
MoveToEpisodeException and
RepeatEpisodeException. In contrast,
CommandSpecFunctionTools is restricted
to file-processing workflows and signals task completion or application
termination through EndTaskException and
ProcessTerminationException.
DenyException represents rejection by
command security policy rather than an ordinary command result.
Typical usage
Register the provider applicable to the active processor, then invoke the
operation exposed by its @Tool metadata. A project-relative editing
workflow may read a source file, apply a targeted patch, and run an allowed
verification command:
read_file(path: "src/main/java/Example.java") apply_patch_to_file(file: "src/main/java/Example.java", patch: patchText) run_sys_command(command: "mvn test", dir: ".")
Callers must provide values matching each operation's @Param
declarations and handle its documented return value and exceptions. Command
execution can reject unsafe input, while the control-flow exceptions above
intentionally request workflow transitions rather than indicating ordinary
tool failure. Asynchronous Act and guidance calls return a process identifier;
the corresponding result operation reports whether processing is complete.
- Author:
- Viktor Tovstyi
-
ClassDescriptionProvides function tools for managing and executing Ghostwriter Acts within a project.Provides AI-callable functional tools for episode navigation and control within an
ActProcessorcontext.Provides function tools for executing and managing system commands within a project context.Functional interface used for handling stream read failures.Auto-closeable wrapper forExecutorServiceso it can be used with try-with-resources.Functional interface used for streaming output line processing.Loads and evaluates command deny-list rules used by host-side command execution tools.Provides function tools for task and process-execution control within anAIFileProcessorworkflow.Signals that a command has failed a deny-list security check and must not be executed.Installs file-system tools into aProcessProvider.Provides function tools for discovering and processing files with guidance tags in project directories.AStringBuilder-like helper that retains only the lastmaxSizecharacters.Control-flow exception that requests navigation to a named or numbered Act episode.Applies unified and simplified search-and-replace diff patches to text files.Represents a patch hunk and its preferred zero-based starting position.Represents a parsed context, addition, or removal line in a patch hunk.Runtime control-flow exception that requests host application termination.Provides function tools for managing project-specific context variables.Runtime control-flow exception that requests repetition of the current Act episode.Provides host-side HTTP retrieval tools for aProcessProviderprovider.