Package org.machanism.machai.gw.tools

package org.machanism.machai.gw.tools
Provides Ghostwriter host-side function tools that expose project-scoped automation capabilities to the Machai runtime.

The package contains concrete FunctionTools implementations used by the Ghostwriter runtime to expose file access, command execution, HTTP integration, Act orchestration, guidance processing, and project-context management through Tool-annotated methods. It also defines helper utilities for bounded logging and patch application plus lightweight exception types that communicate control-flow decisions such as task completion, process termination, episode repetition, and episode navigation.

Methods annotated with Tool are exposed as callable functional AI tools, while methods annotated with Prompt provide prompt templates for workflow-specific requests. Resource-oriented integrations, when supplied by the host, are used to retrieve project or web content under the same project-bound and security-controlled execution model.

Package overview

  • Act orchestration: ActFunctionTools loads Act metadata, executes Acts synchronously or asynchronously, and retrieves persisted Act results. ActSpecFunctionTools provides Act-specific control tools for jumping to another episode or requesting a repeat.
  • Command execution and logging: CommandFunctionTools runs validated operating-system commands, captures bounded output, persists logs, pages log content, and searches logs with regular expressions. Validation is delegated to CommandSecurityChecker, while LogBuilder manages retained output and log-file reports. CommandSpecFunctionTools exposes task and process termination controls for processors.
  • File-system operations: FileFunctionTools reads, writes, lists, and patches project files, and PatchApplier applies unified or simplified diff patches. Recursive file and directory discovery is delegated to the project-layout utilities. File operations are intended to remain within the project directory supplied by the host. The FileFunctionTools.getRelativePath(java.io.File, java.io.File, boolean) helper normalizes paths for tool responses.
  • Guidance workflows: GuidanceFunctionTools discovers files containing guidance tags, processes them with Ghostwriter guidance engines, and retrieves asynchronous processing results.
  • Project state and runtime control: ProjectContextFunctionTools stores and retrieves project-scoped context variables, while CommandSpecFunctionTools exposes tools for ending a task or terminating execution. The ActSpecFunctionTools uses MoveToEpisodeException and RepeatEpisodeException for episode navigation and repetition. Other specialized exceptions such as EndTaskException, ProcessTerminationException, DenyException allow the host to distinguish intentional control flow from ordinary failures.
  • Reusable support types: LogBuilder bounds retained output and persists command logs, while PatchApplier applies validated text patches. CommandSecurityChecker and the control-flow exception classes are deliberately small integration points that can be reused by host processors without invoking a tool facade.
  • Web integration: WebFunctionTools fetches HTML or text content and executes REST requests with configurable headers, timeouts, character sets, optional selector extraction, and Basic authentication via URL user-info or explicit request headers.

Control-flow and security contracts

DenyException reports a command rejected by the configured deny-list. The specialized exceptions EndTaskException, ProcessTerminationException, MoveToEpisodeException, and RepeatEpisodeException are intentional signals for the embedding processor; they are not ordinary application failures and should be handled according to the host's workflow policy.

Usage model

Most tools accept a project directory supplied by the host runtime and treat paths relative to that directory. Several tools also accept a Configurator so command strings, URLs, HTTP headers, Act properties, and related values can be resolved through runtime substitution before execution.

Example

Tool classes are typically discovered reflectively, but they can also be used directly by an integration host or test harness: 

 File projectDir = new File("C:/workspace/sample-project");
 Configurator configurator = ...;

 FileFunctionTools files = new FileFunctionTools();
 String readme = files.readFile(new File("README.md"), "UTF-8", projectDir);

 CommandFunctionTools commands = new CommandFunctionTools();
 Object report = commands.executeCommand("mvn -q test", null, ".", 2048, "UTF-8", projectDir, configurator);

 ProjectContextFunctionTools.put(projectDir, "lastCommandReport", report);

Tool methods return structured maps or lists when callers need status and metadata, and return strings for text-oriented operations. Methods that represent deliberate workflow transitions use the specialized exception types documented below; an embedding processor should not convert those signals into ordinary error messages.

Design notes

Implementations in this package favor project-bound path resolution, bounded output retention, explicit character-set handling, structured result payloads, and host-controlled security constraints. Because several tools can touch the file system, start subprocesses, or call external services, callers are expected to configure appropriate allow/deny policies in the embedding environment.

See Also: