Merge pull request #56 from tripolskypetr/tool-action-helper

Tool action helper

Author: tripolskypetr

docs/classes/ActionSchemaService.md

@@ -0,0 +1,44 @@
+---
+title: docs/api-reference/class/ActionSchemaService
+group: docs
+---
+
+# ActionSchemaService
+
+## Constructor
+
+```ts
+constructor();
+```
+
+## Properties
+
+### loggerService
+
+```ts
+loggerService: any
+```
+
+### _actionToolNameSet
+
+```ts
+_actionToolNameSet: any
+```
+
+### register
+
+```ts
+register: (toolName: string) => void
+```
+
+Registers an action tool name in the internal Set.
+Logs the registration operation via LoggerService if GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO is true.
+
+### hasTool
+
+```ts
+hasTool: (toolName: string) => boolean
+```
+
+Checks if an action tool name exists in the internal Set.
+Logs the lookup operation via LoggerService if GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO is true.

docs/classes/ClientAgent.md

@@ -120,6 +120,7 @@ _resolveTools(): Promise<IAgentTool[]>;
 ```
 
 Resolves and combines tools from the agent's parameters and MCP tool list, ensuring no duplicate tool names.
+Ensures only one commit action tool is present in the list.
 
 ### _resolveSystemPrompt
 

docs/classes/SchemaUtils.md

@@ -16,10 +16,10 @@ constructor();
 
 ## Properties
 
-### __@PERSIST_WRITE_SYMBOL@4351
+### __@PERSIST_WRITE_SYMBOL@4419
 
 ```ts
-__@PERSIST_WRITE_SYMBOL@4351: any
+__@PERSIST_WRITE_SYMBOL@4419: any
 ```
 
 ### writeSessionMemory

docs/functions/addCommitAction.md

@@ -0,0 +1,31 @@
+---
+title: docs/api-reference/function/addCommitAction
+group: docs
+---
+
+# addCommitAction
+
+```ts
+declare function addCommitAction<T = Record<string, any>>(params: ICommitActionToolParams<T>): string;
+```
+
+Creates and registers a commit action tool for AI to execute actions (WRITE pattern).
+This implements the WRITE side of the command pattern - AI calls tool to modify system state.
+
+**Flow:**
+1. AI calls tool with parameters
+2. validateParams runs (if provided) - validates parameters and returns error message or null
+3. If validation fails:
+   - Error message is committed as tool output
+   - failureMessage is executed (or error message if failureMessage not provided)
+   - Flow stops
+4. If validation passes:
+   - executeAction runs - performs the action
+   - Action result is committed as tool output (or emptyContent if result is empty)
+   - successMessage is executed
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `params` | Configuration object for the action tool |

docs/functions/addFetchInfo.md

@@ -0,0 +1,27 @@
+---
+title: docs/api-reference/function/addFetchInfo
+group: docs
+---
+
+# addFetchInfo
+
+```ts
+declare function addFetchInfo<T = Record<string, any>>(params: IFetchInfoToolParams<T>): string;
+```
+
+Creates and registers a fetch info tool for AI to retrieve data (READ pattern).
+This implements the READ side of the command pattern - AI calls tool to get information without modifying state.
+
+**Flow:**
+1. AI calls tool with parameters
+2. validateParams runs (if provided) - validates parameters structure. Returns true if valid, false if invalid
+3. If validation fails (returns false), tool execution is blocked
+4. If validation passes, fetchContent executes - retrieves data
+5. AI receives fetched content as tool output
+6. If content is empty, emptyContent handler is called
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `params` | Configuration object for the fetch tool |

docs/index.md

@@ -85,6 +85,7 @@ group: docs
 - [PipelineValidationService](classes/PipelineValidationService.md)
 - [ExecutionValidationService](classes/ExecutionValidationService.md)
 - [NavigationSchemaService](classes/NavigationSchemaService.md)
+- [ActionSchemaService](classes/ActionSchemaService.md)
 - [OutlineSchemaService](classes/OutlineSchemaService.md)
 - [OutlineValidationService](classes/OutlineValidationService.md)
 - [RoundRobin](classes/RoundRobin.md)
@@ -107,6 +108,8 @@ group: docs
 
 - [addAgentNavigation](functions/addAgentNavigation.md)
 - [addTriageNavigation](functions/addTriageNavigation.md)
+- [addCommitAction](functions/addCommitAction.md)
+- [addFetchInfo](functions/addFetchInfo.md)
 - [addAdvisor](functions/addAdvisor.md)
 - [addAgent](functions/addAgent.md)
 - [addCompletion](functions/addCompletion.md)
@@ -331,8 +334,12 @@ group: docs
 - [IConfig](interfaces/IConfig.md)
 - [INavigateToTriageParams](interfaces/INavigateToTriageParams.md)
 - [INavigateToAgentParams](interfaces/INavigateToAgentParams.md)
+- [ICommitActionParams](interfaces/ICommitActionParams.md)
+- [IFetchInfoParams](interfaces/IFetchInfoParams.md)
 - [IAgentNavigationParams](interfaces/IAgentNavigationParams.md)
 - [ITriageNavigationParams](interfaces/ITriageNavigationParams.md)
+- [ICommitActionToolParams](interfaces/ICommitActionToolParams.md)
+- [IFetchInfoToolParams](interfaces/IFetchInfoToolParams.md)
 - [IMakeDisposeParams](interfaces/IMakeDisposeParams.md)
 - [IMakeConnectionConfig](interfaces/IMakeConnectionConfig.md)
 - [ISessionConfig](interfaces/ISessionConfig.md)

docs/interfaces/ICommitActionParams.md

@@ -0,0 +1,64 @@
+---
+title: docs/api-reference/interface/ICommitActionParams
+group: docs
+---
+
+# ICommitActionParams
+
+Configuration parameters for creating a commit action handler (WRITE pattern).
+Defines validation, action execution, and response messages for state-modifying operations.
+
+## Properties
+
+### fallback
+
+```ts
+fallback: (error: Error, clientId: string, agentName: string) => void
+```
+
+Optional function to handle errors during action execution.
+Receives the error object, client ID, and agent name.
+
+### validateParams
+
+```ts
+validateParams: (dto: { clientId: string; agentName: string; toolCalls: IToolCall[]; params: T; }) => string | Promise<string>
+```
+
+Optional function to validate action parameters.
+Returns error message string if validation fails, null if valid.
+
+### executeAction
+
+```ts
+executeAction: (params: T, clientId: string, agentName: string) => string | Promise<string>
+```
+
+Function to execute the actual action (e.g., commitAppAction).
+Called only when parameters are valid and isLast is true.
+Returns result string to commit as tool output.
+
+### emptyContent
+
+```ts
+emptyContent: (params: T, clientId: string, agentName: string) => string | Promise<string>
+```
+
+Optional function to handle when executeAction returns empty result.
+Returns message to commit as tool output.
+
+### successMessage
+
+```ts
+successMessage: string | ((params: T, clientId: string, agentName: string) => string | Promise<string>)
+```
+
+Message to execute using executeForce after successful action execution.
+
+### failureMessage
+
+```ts
+failureMessage: string | ((params: T, clientId: string, agentName: string) => string | Promise<string>)
+```
+
+Optional message to execute using executeForce when validation fails.

docs/interfaces/ICommitActionToolParams.md

@@ -0,0 +1,43 @@
+---
+title: docs/api-reference/interface/ICommitActionToolParams
+group: docs
+---
+
+# ICommitActionToolParams
+
+Parameters for configuring commit action tool (WRITE pattern).
+Creates a tool that executes actions and modifies system state.
+
+## Properties
+
+### toolName
+
+```ts
+toolName: string
+```
+
+The name of the tool to be created.
+
+### function
+
+```ts
+function: { name: string; description: string; parameters: { type: string; required: string[]; properties: { [key: string]: { type: string; description: string; enum?: string[]; }; }; }; } | ((clientId: string, agentName: string) => { ...; } | Promise<...>)
+```
+
+Tool function schema (name, description, parameters).
+
+### docNote
+
+```ts
+docNote: string
+```
+
+Optional documentation note for the tool.
+
+### isAvailable
+
+```ts
+isAvailable: (clientId: string, agentName: string, toolName: string) => boolean | Promise<boolean>
+```
+
+Optional function to determine if the tool is available.

docs/interfaces/IFetchInfoParams.md

@@ -0,0 +1,38 @@
+---
+title: docs/api-reference/interface/IFetchInfoParams
+group: docs
+---
+
+# IFetchInfoParams
+
+Configuration parameters for creating a fetch info handler (READ pattern).
+Defines the data fetching logic without modifying system state.
+
+## Properties
+
+### fallback
+
+```ts
+fallback: (error: Error, clientId: string, agentName: string) => void
+```
+
+Optional function to handle errors during fetch execution.
+Receives the error object, client ID, and agent name.
+
+### fetchContent
+
+```ts
+fetchContent: (params: T, clientId: string, agentName: string) => string | Promise<string>
+```
+
+Function to fetch the content/data to be provided to the agent.
+This is the main data retrieval logic.
+
+### emptyContent
+
+```ts
+emptyContent: (content: string, clientId: string, agentName: string, toolName: string) => string | Promise<string>
+```
+
+Optional function to handle when fetchContent returns empty result.
+Returns message to commit as tool output.

docs/interfaces/IFetchInfoToolParams.md

@@ -0,0 +1,51 @@
+---
+title: docs/api-reference/interface/IFetchInfoToolParams
+group: docs
+---
+
+# IFetchInfoToolParams
+
+Parameters for configuring fetch info tool (READ pattern).
+Creates a tool that fetches and returns data to the AI without modifying system state.
+
+## Properties
+
+### toolName
+
+```ts
+toolName: string
+```
+
+The name of the tool to be created.
+
+### function
+
+```ts
+function: { name: string; description: string; parameters: { type: string; required: string[]; properties: { [key: string]: { type: string; description: string; enum?: string[]; }; }; }; } | ((clientId: string, agentName: string) => { ...; } | Promise<...>)
+```
+
+Tool function schema (name, description, parameters).
+
+### docNote
+
+```ts
+docNote: string
+```
+
+Optional documentation note for the tool.
+
+### isAvailable
+
+```ts
+isAvailable: (clientId: string, agentName: string, toolName: string) => boolean | Promise<boolean>
+```
+
+Optional function to determine if the tool is available.
+
+### validateParams
+
+```ts
+validateParams: (dto: { clientId: string; agentName: string; toolCalls: IToolCall[]; params: T; }) => boolean | Promise<boolean>
+```
+
+Optional validation function that runs before fetchContent. Returns boolean (true if valid, false if invalid).