Package org.machanism.machai.gw.tools

package org.machanism.machai.gw.tools
Supplies the host-side, AI-callable tools used by the Ghostwriter runtime.

The package is the integration boundary between an AI provider and a project-scoped workflow. Implementations of FunctionTools expose annotated methods to the provider, while the processors in ActProcessor and AIFileProcessor perform the corresponding workflow work. File and command paths are resolved against the active project directory; asynchronous operations persist results under the runtime temporary directory and return an identifier for later polling.

AI metadata and tool providers

Classes or methods annotated with @Tool are Functional AI Tools. Their names, parameter descriptions, default values, return contracts, and failures are published as callable operations. Methods annotated with @Prompt are Prompt Templates; they supply reusable instructions from the mcp-prompts resource bundle. This package currently declares no classes or methods annotated with @Resource, so it provides no Contextual Resources. Package-level Javadoc has no callable parameters, return value, or thrown exception; those contracts are documented on each public constructor and method.

Functional areas

  • ActFunctionTools is the Act Functional AI Tool provider. It loads Act definitions, starts synchronous or asynchronous Act execution, polls serialized results, and exposes the Act Prompt Template.
  • GuidanceFunctionTools discovers files containing guidance tags, processes them synchronously or in the background, polls processing reports, and exposes the guidance-processing Prompt Template.
  • FileFunctionTools lists files and folders, reads and writes project files, and applies validated unified or simplified patches through PatchApplier. WebFunctionTools retrieves HTTP(S) responses or project-scoped file: content, supports CSS selection and text rendering, and performs REST requests with headers and Basic authentication.
  • CommandFunctionTools executes project-bounded operating-system commands, captures bounded output, and provides log paging and regular-expression search. It delegates policy checks to CommandSecurityChecker, whose deny-list violations produce DenyException. Command output and timing reports are maintained by LogBuilder.
  • ProjectContextFunctionTools stores, retrieves, pushes, and pops project-scoped workflow state. Values are shared by Acts and episodes but are not operating-system environment variables.
  • ActSpecFunctionTools is restricted to Act processing and signals episode navigation or repetition through MoveToEpisodeException and RepeatEpisodeException. CommandSpecFunctionTools is restricted to file-processing workflows and signals task completion or application termination through EndTaskException and ProcessTerminationException.

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. In particular, command execution can reject unsafe input, while control-flow exceptions 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