Package org.machanism.machai.gw.tools


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

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

  • ActFunctionTools is the Act Functional AI Tool provider. It loads Act definitions, performs Acts synchronously or asynchronously, 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 project files and folders, reads and writes bounded 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 deny-list checks to CommandSecurityChecker and records output and timing reports through LogBuilder.
  • ProjectContextFunctionTools stores, 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