@salesforce/magen-mcp-workflow 0.0.1

package/dist/services/getInputService.js

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { AbstractService } from './abstractService.js';
+import { createGetInputMetadata, GET_INPUT_WORKFLOW_RESULT_SCHEMA, } from '../tools/utilities/index.js';
+/**
+ * Service for getting user input for a given question.
+ *
+ * This service extends AbstractService to leverage common tool execution
+ * patterns including standardized logging and result validation.
+ */
+export class GetInputService extends AbstractService {
+    toolId;
+    /**
+     * Creates a new GetInputService.
+     *
+     * @param toolExecutor - Tool executor for invoking the input tool (injectable for testing)
+     * @param logger - Logger instance (injectable for testing)
+     */
+    constructor(toolId, toolExecutor, logger) {
+        super('GetInputService', toolExecutor, logger);
+        this.toolId = toolId;
+    }
+    getInput(unfulfilledProperties) {
+        this.logger.debug('Starting input request with properties', {
+            unfulfilledProperties,
+        });
+        const metadata = createGetInputMetadata(this.toolId);
+        // Create tool invocation data
+        const toolInvocationData = {
+            llmMetadata: {
+                name: metadata.toolId,
+                description: metadata.description,
+                inputSchema: metadata.inputSchema,
+            },
+            input: {
+                propertiesRequiringInput: unfulfilledProperties,
+            },
+        };
+        // Execute tool with logging and validation
+        const validatedResult = this.executeToolWithLogging(toolInvocationData, GET_INPUT_WORKFLOW_RESULT_SCHEMA);
+        return validatedResult.userUtterance;
+    }
+}
+//# sourceMappingURL=getInputService.js.map

package/dist/services/getInputService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getInputService.js","sourceRoot":"","sources":["../../src/services/getInputService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EACL,sBAAsB,EAEtB,gCAAgC,GACjC,MAAM,6BAA6B,CAAC;AAgCrC;;;;;GAKG;AACH,MAAM,OAAO,eAAgB,SAAQ,eAAe;IAQ/B;IAPnB;;;;;OAKG;IACH,YACmB,MAAc,EAC/B,YAA2B,EAC3B,MAAe;QAEf,KAAK,CAAC,iBAAiB,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;QAJ9B,WAAM,GAAN,MAAM,CAAQ;IAKjC,CAAC;IAED,QAAQ,CAAC,qBAAyC;QAChD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE;YAC1D,qBAAqB;SACtB,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrD,8BAA8B;QAC9B,MAAM,kBAAkB,GAAkE;YACxF,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ,CAAC,MAAM;gBACrB,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,WAAW,EAAE,QAAQ,CAAC,WAAW;aAClC;YACD,KAAK,EAAE;gBACL,wBAAwB,EAAE,qBAAqB;aAChD;SACF,CAAC;QAEF,2CAA2C;QAC3C,MAAM,eAAe,GAAG,IAAI,CAAC,sBAAsB,CACjD,kBAAkB,EAClB,gCAAgC,CACjC,CAAC;QAEF,OAAO,eAAe,CAAC,aAAa,CAAC;IACvC,CAAC;CACF"}

package/dist/services/index.d.ts

@@ -0,0 +1,3 @@
+export { AbstractService } from './abstractService.js';
+export { InputExtractionService, InputExtractionServiceProvider, ExtractionResult, } from './inputExtractionService.js';
+export { GetInputService, GetInputServiceProvider, GetInputProperty } from './getInputService.js';

package/dist/services/index.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+export { AbstractService } from './abstractService.js';
+export { InputExtractionService, } from './inputExtractionService.js';
+export { GetInputService } from './getInputService.js';
+//# sourceMappingURL=index.js.map

package/dist/services/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EACL,sBAAsB,GAGvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,eAAe,EAA6C,MAAM,sBAAsB,CAAC"}

package/dist/services/inputExtractionService.d.ts

@@ -0,0 +1,46 @@
+import { ToolExecutor } from '../nodes/toolExecutor.js';
+import { AbstractService } from './abstractService.js';
+import { PropertyMetadataCollection } from '../common/propertyMetadata.js';
+import { Logger } from '../logging/logger.js';
+/**
+ * Result from property extraction containing validated properties.
+ */
+export interface ExtractionResult {
+    /** Record of extracted properties, keyed by property name */
+    extractedProperties: Record<string, unknown>;
+}
+/**
+ * Provider interface for property extraction service.
+ * This interface allows for dependency injection and testing.
+ */
+export interface InputExtractionServiceProvider {
+    /**
+     * Extracts structured properties from user input.
+     *
+     * @param userInput - Raw user input (string, object, or any format)
+     * @param properties - Collection of properties to extract with their metadata
+     * @returns ExtractionResult containing validated extracted properties
+     */
+    extractProperties(userInput: unknown, properties: PropertyMetadataCollection): ExtractionResult;
+}
+/**
+ * Service for extracting structured properties from user input.
+ *
+ * This service extends AbstractService to leverage common tool execution
+ * patterns including standardized logging and result validation.
+ */
+export declare class InputExtractionService extends AbstractService implements InputExtractionServiceProvider {
+    private readonly toolId;
+    /**
+     * Creates a new InputExtractionService.
+     *
+     * @param toolId - Tool ID for the input extraction tool
+     * @param toolExecutor - Tool executor for invoking the extraction tool (injectable for testing)
+     * @param logger - Logger instance (injectable for testing)
+     */
+    constructor(toolId: string, toolExecutor?: ToolExecutor, logger?: Logger);
+    extractProperties(userInput: unknown, properties: PropertyMetadataCollection): ExtractionResult;
+    private preparePropertiesForExtraction;
+    private preparePropertyResultsSchema;
+    private validateAndFilterResult;
+}

package/dist/services/inputExtractionService.js

@@ -0,0 +1,133 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import z from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { AbstractService } from './abstractService.js';
+import { createInputExtractionMetadata, } from '../tools/utilities/index.js';
+/**
+ * Service for extracting structured properties from user input.
+ *
+ * This service extends AbstractService to leverage common tool execution
+ * patterns including standardized logging and result validation.
+ */
+export class InputExtractionService extends AbstractService {
+    toolId;
+    /**
+     * Creates a new InputExtractionService.
+     *
+     * @param toolId - Tool ID for the input extraction tool
+     * @param toolExecutor - Tool executor for invoking the extraction tool (injectable for testing)
+     * @param logger - Logger instance (injectable for testing)
+     */
+    constructor(toolId, toolExecutor, logger) {
+        super('InputExtractionService', toolExecutor, logger);
+        this.toolId = toolId;
+    }
+    extractProperties(userInput, properties) {
+        this.logger.debug('Starting property extraction', {
+            userInput,
+            propertyCount: Object.keys(properties).length,
+        });
+        const propertiesToExtract = this.preparePropertiesForExtraction(properties);
+        const resultSchema = this.preparePropertyResultsSchema(properties);
+        const resultSchemaString = JSON.stringify(zodToJsonSchema(resultSchema));
+        const metadata = createInputExtractionMetadata(this.toolId);
+        const toolInvocationData = {
+            llmMetadata: {
+                name: metadata.toolId,
+                description: metadata.description,
+                inputSchema: metadata.inputSchema,
+            },
+            input: {
+                userUtterance: userInput,
+                propertiesToExtract,
+                resultSchema: resultSchemaString,
+            },
+        };
+        const validatedResult = this.executeToolWithLogging(toolInvocationData, resultSchema, (rawResult, schema) => this.validateAndFilterResult(rawResult, properties, schema));
+        this.logger.info('Property extraction completed', {
+            extractedCount: Object.keys(validatedResult.extractedProperties).length,
+            properties: Object.keys(validatedResult.extractedProperties),
+        });
+        return validatedResult;
+    }
+    preparePropertiesForExtraction(properties) {
+        const propertiesToExtract = [];
+        for (const [propertyName, metadata] of Object.entries(properties)) {
+            propertiesToExtract.push({
+                propertyName,
+                description: metadata.description,
+            });
+        }
+        this.logger.debug('Prepared properties for extraction', {
+            count: propertiesToExtract.length,
+            properties: propertiesToExtract.map(p => p.propertyName),
+        });
+        return propertiesToExtract;
+    }
+    preparePropertyResultsSchema(properties) {
+        const extractedPropertiesShape = {};
+        for (const [propertyName, metadata] of Object.entries(properties)) {
+            extractedPropertiesShape[propertyName] = metadata.zodType
+                .describe(metadata.description)
+                .nullable()
+                .catch((ctx) => ctx.input);
+        }
+        return z.object({ extractedProperties: z.object(extractedPropertiesShape).passthrough() });
+    }
+    validateAndFilterResult(rawResult, properties, resultSchema) {
+        const structureValidated = resultSchema.parse(rawResult);
+        const { extractedProperties } = structureValidated;
+        this.logger.debug('Validating extracted properties', {
+            extractedProperties,
+        });
+        const validatedProperties = {};
+        const invalidProperties = [];
+        for (const [propertyName, propertyValue] of Object.entries(extractedProperties)) {
+            if (propertyValue == null) {
+                this.logger.debug(`Skipping property with null/undefined value`, { propertyName });
+                continue;
+            }
+            const propertyMetadata = properties[propertyName];
+            if (!propertyMetadata) {
+                this.logger.warn(`Unknown property in extraction result`, { propertyName });
+                continue;
+            }
+            try {
+                const validatedValue = propertyMetadata.zodType.parse(propertyValue);
+                validatedProperties[propertyName] = validatedValue;
+                this.logger.debug(`Property validated successfully`, {
+                    propertyName,
+                    value: validatedValue,
+                });
+            }
+            catch (error) {
+                invalidProperties.push(propertyName);
+                if (error instanceof z.ZodError) {
+                    this.logger.debug(`Property validation failed`, {
+                        propertyName,
+                        value: propertyValue,
+                        errors: error.errors,
+                    });
+                }
+                else {
+                    const errorMsg = error instanceof Error ? error.message : String(error);
+                    this.logger.error(`Unexpected validation error for ${propertyName}: ${errorMsg}`);
+                    throw error;
+                }
+            }
+        }
+        if (invalidProperties.length > 0) {
+            this.logger.info(`Some properties failed validation`, {
+                invalidProperties,
+                validCount: Object.keys(validatedProperties).length,
+            });
+        }
+        return { extractedProperties: validatedProperties };
+    }
+}
+//# sourceMappingURL=inputExtractionService.js.map

package/dist/services/inputExtractionService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputExtractionService.js","sourceRoot":"","sources":["../../src/services/inputExtractionService.ts"],"names":[],"mappings":"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"}

package/dist/storage/wellKnownDirectory.d.ts

@@ -0,0 +1,79 @@
+import { FileSystemOperations } from '../common/fileSystem.js';
+/**
+ * Well-known directory name - hidden directory at project root
+ */
+export declare const WELL_KNOWN_DIR_NAME = ".magen";
+/**
+ * Well-known file names within the .magen directory
+ */
+export declare const WELL_KNOWN_FILES: {
+    readonly WORKFLOW_STATE_STORE_FILENAME: "workflow-state.json";
+    readonly WORKFLOW_LOGS: "workflow_logs.json";
+};
+/**
+ * Configuration for WellKnownDirectoryManager
+ */
+export interface WellKnownDirectoryConfig {
+    /** Optional project path override (defaults to PROJECT_PATH env var or home directory) */
+    projectPath?: string;
+    /** Optional filesystem operations implementation (defaults to NodeFileSystemOperations) */
+    fileSystemOperations?: FileSystemOperations;
+}
+/**
+ * Class-based well-known directory manager with dependency injection support
+ */
+export declare class WellKnownDirectoryManager {
+    private readonly fileSystemOperations;
+    private readonly baseDirPath;
+    constructor(config?: WellKnownDirectoryConfig);
+    /**
+     * Get the absolute path to the .magen directory
+     * @returns Absolute path to .magen directory
+     */
+    getWellKnownDirectoryPath(): string;
+    /**
+     * Ensure the .magen directory exists, creating it if necessary
+     * Safe to call multiple times - idempotent operation
+     *
+     * @returns Absolute path to the .magen directory
+     */
+    ensureWellKnownDirectory(): string;
+    /**
+     * Get the absolute path to a specific file within the .magen directory
+     * Ensures the directory exists before returning the path
+     *
+     * @param fileName - Name of the file within .magen directory
+     * @returns Absolute path to the specified file
+     */
+    getWellKnownFilePath(fileName: string): string;
+    /**
+     * Get the path to the workflow state database
+     * @returns Absolute path to workflow-state.json
+     */
+    getWorkflowStateStorePath(): string;
+    /**
+     * Get the path to the workflow logs file
+     * @returns Absolute path to workflow_logs.json
+     */
+    getWorkflowLogsPath(): string;
+    /**
+     * Check if the .magen directory exists
+     * @returns true if directory exists, false otherwise
+     */
+    wellKnownDirectoryExists(): boolean;
+    /**
+     * Get information about the .magen directory and its contents
+     * Useful for debugging and status reporting
+     *
+     * @returns Object with directory status and file information
+     */
+    getWellKnownDirectoryInfo(): {
+        exists: boolean;
+        path: string;
+        files: Array<{
+            name: string;
+            exists: boolean;
+            path: string;
+        }>;
+    };
+}

package/dist/storage/wellKnownDirectory.js

@@ -0,0 +1,121 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+/**
+ * Well-Known Directory Management
+ *
+ * Centralized management of the .magen well-known directory structure for the
+ * Mobile Native MCP Server. This directory contains persistent project artifacts
+ * including workflow state, logging, and other cross-session data.
+ *
+ * Directory structure:
+ * .magen/
+ * ├── workflow-state.db    # SQLite database for LangGraph workflow persistence
+ * ├── workflow_logs.json   # Structured JSON logs for workflow operations
+ * └── [future artifacts]   # Additional project artifacts as needed
+ */
+import path from 'path';
+import os from 'os';
+import { NodeFileSystemOperations } from '../common/fileSystem.js';
+/**
+ * Well-known directory name - hidden directory at project root
+ */
+export const WELL_KNOWN_DIR_NAME = '.magen';
+/**
+ * Well-known file names within the .magen directory
+ */
+export const WELL_KNOWN_FILES = {
+    WORKFLOW_STATE_STORE_FILENAME: 'workflow-state.json',
+    WORKFLOW_LOGS: 'workflow_logs.json',
+};
+/**
+ * Class-based well-known directory manager with dependency injection support
+ */
+export class WellKnownDirectoryManager {
+    fileSystemOperations;
+    baseDirPath;
+    constructor(config = {}) {
+        this.fileSystemOperations = config.fileSystemOperations ?? new NodeFileSystemOperations();
+        const baseDir = config.projectPath
+            ? path.resolve(config.projectPath)
+            : process.env.PROJECT_PATH
+                ? path.resolve(process.env.PROJECT_PATH)
+                : os.homedir();
+        this.baseDirPath = path.join(baseDir, WELL_KNOWN_DIR_NAME);
+    }
+    /**
+     * Get the absolute path to the .magen directory
+     * @returns Absolute path to .magen directory
+     */
+    getWellKnownDirectoryPath() {
+        return this.baseDirPath;
+    }
+    /**
+     * Ensure the .magen directory exists, creating it if necessary
+     * Safe to call multiple times - idempotent operation
+     *
+     * @returns Absolute path to the .magen directory
+     */
+    ensureWellKnownDirectory() {
+        if (!this.fileSystemOperations.existsSync(this.baseDirPath)) {
+            this.fileSystemOperations.mkdirSync(this.baseDirPath, { recursive: true });
+        }
+        return this.baseDirPath;
+    }
+    /**
+     * Get the absolute path to a specific file within the .magen directory
+     * Ensures the directory exists before returning the path
+     *
+     * @param fileName - Name of the file within .magen directory
+     * @returns Absolute path to the specified file
+     */
+    getWellKnownFilePath(fileName) {
+        const wellKnownDir = this.ensureWellKnownDirectory();
+        return path.join(wellKnownDir, fileName);
+    }
+    /**
+     * Get the path to the workflow state database
+     * @returns Absolute path to workflow-state.json
+     */
+    getWorkflowStateStorePath() {
+        return this.getWellKnownFilePath(WELL_KNOWN_FILES.WORKFLOW_STATE_STORE_FILENAME);
+    }
+    /**
+     * Get the path to the workflow logs file
+     * @returns Absolute path to workflow_logs.json
+     */
+    getWorkflowLogsPath() {
+        return this.getWellKnownFilePath(WELL_KNOWN_FILES.WORKFLOW_LOGS);
+    }
+    /**
+     * Check if the .magen directory exists
+     * @returns true if directory exists, false otherwise
+     */
+    wellKnownDirectoryExists() {
+        return this.fileSystemOperations.existsSync(this.baseDirPath);
+    }
+    /**
+     * Get information about the .magen directory and its contents
+     * Useful for debugging and status reporting
+     *
+     * @returns Object with directory status and file information
+     */
+    getWellKnownDirectoryInfo() {
+        const dirPath = this.getWellKnownDirectoryPath();
+        const exists = this.wellKnownDirectoryExists();
+        const files = Object.values(WELL_KNOWN_FILES).map(fileName => ({
+            name: fileName,
+            exists: exists && this.fileSystemOperations.existsSync(path.join(dirPath, fileName)),
+            path: path.join(dirPath, fileName),
+        }));
+        return {
+            exists,
+            path: dirPath,
+            files,
+        };
+    }
+}
+//# sourceMappingURL=wellKnownDirectory.js.map

package/dist/storage/wellKnownDirectory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wellKnownDirectory.js","sourceRoot":"","sources":["../../src/storage/wellKnownDirectory.ts"],"names":[],"mappings":"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"}

package/dist/tools/base/abstractTool.d.ts

@@ -0,0 +1,61 @@
+import { McpServer, ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import z from 'zod';
+import { Logger } from '../../logging/logger.js';
+import { ToolMetadata } from '../../common/metadata.js';
+/**
+ * Abstract base class for ALL MCP tools in the workflow engine
+ *
+ * Provides comprehensive functionality including:
+ * - Server instance management
+ * - Logging with component identification
+ * - Standardized registration pattern
+ * - Workflow state round-tripping support
+ * - Post-invocation instruction patterns
+ * - Shared utility methods
+ *
+ * @template TMetadata - Tool metadata type extending ToolMetadata
+ */
+export declare abstract class AbstractTool<TMetadata extends ToolMetadata<z.ZodObject<z.ZodRawShape>, z.ZodObject<z.ZodRawShape>>> {
+    protected readonly server: McpServer;
+    readonly toolMetadata: TMetadata;
+    protected readonly logger: Logger;
+    constructor(server: McpServer, toolMetadata: TMetadata, loggerComponentName?: string, logger?: Logger);
+    /**
+     * Register the tool with the MCP server
+     * @param annotations Tool annotations for MCP client hints
+     */
+    register(annotations: ToolAnnotations): void;
+    /**
+     * Abstract method that implementing tools must provide for handling requests
+     *
+     * Uses the same typing pattern as registerTool() ToolCallback<InputArgs>.
+     * @param input The input to the callback
+     * @returns The return result of the tool
+     */
+    abstract handleRequest: ToolCallback<TMetadata['inputSchema']['shape']>;
+    /**
+     * Logs tool registration information
+     * @param annotations The tool annotations
+     */
+    protected logRegistration(annotations: ToolAnnotations): void;
+    /**
+     * Logs an error that occurred during tool execution
+     * @param message A descriptive error message
+     * @param error The error object
+     * @param data Additional context data
+     */
+    protected logError(message: string, error: Error, data?: unknown): void;
+    /**
+     * Creates a child logger for a specific operation within the tool
+     * @param operationName The name of the operation
+     * @returns A child logger instance
+     */
+    protected createOperationLogger(operationName: string): Logger;
+    /**
+     * Logs workflow-specific events with enhanced context
+     * @param event The workflow event description
+     * @param data Additional workflow context data
+     */
+    protected logWorkflowEvent(event: string, data?: Record<string, unknown>): void;
+}

package/dist/tools/base/abstractTool.js

@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { createComponentLogger } from '../../logging/logger.js';
+/**
+ * Abstract base class for ALL MCP tools in the workflow engine
+ *
+ * Provides comprehensive functionality including:
+ * - Server instance management
+ * - Logging with component identification
+ * - Standardized registration pattern
+ * - Workflow state round-tripping support
+ * - Post-invocation instruction patterns
+ * - Shared utility methods
+ *
+ * @template TMetadata - Tool metadata type extending ToolMetadata
+ */
+export class AbstractTool {
+    server;
+    toolMetadata;
+    logger;
+    constructor(server, toolMetadata, loggerComponentName, logger) {
+        this.server = server;
+        this.toolMetadata = toolMetadata;
+        this.logger = logger || createComponentLogger(loggerComponentName || this.constructor.name);
+    }
+    /**
+     * Register the tool with the MCP server
+     * @param annotations Tool annotations for MCP client hints
+     */
+    register(annotations) {
+        this.logRegistration(annotations);
+        const enhancedAnnotations = {
+            ...annotations,
+            title: this.toolMetadata.title,
+        };
+        this.server.registerTool(this.toolMetadata.toolId, {
+            description: this.toolMetadata.description,
+            inputSchema: this.toolMetadata.inputSchema.shape,
+            outputSchema: this.toolMetadata.outputSchema.shape,
+            ...enhancedAnnotations,
+        }, this.handleRequest);
+    }
+    /**
+     * Logs tool registration information
+     * @param annotations The tool annotations
+     */
+    logRegistration(annotations) {
+        this.logger.info(`Registering MCP tool: ${this.toolMetadata.toolId}`, { annotations });
+    }
+    /**
+     * Logs an error that occurred during tool execution
+     * @param message A descriptive error message
+     * @param error The error object
+     * @param data Additional context data
+     */
+    logError(message, error, data) {
+        this.logger.error(message, error);
+        if (data) {
+            this.logger.debug('Error context data', data);
+        }
+    }
+    /**
+     * Creates a child logger for a specific operation within the tool
+     * @param operationName The name of the operation
+     * @returns A child logger instance
+     */
+    createOperationLogger(operationName) {
+        return this.logger.child({ operation: operationName });
+    }
+    /**
+     * Logs workflow-specific events with enhanced context
+     * @param event The workflow event description
+     * @param data Additional workflow context data
+     */
+    logWorkflowEvent(event, data) {
+        this.logger.info(event, {
+            ...(data || {}),
+            workflowTool: true,
+            toolId: this.toolMetadata.toolId,
+        });
+    }
+}
+//# sourceMappingURL=abstractTool.js.map

package/dist/tools/base/abstractTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstractTool.js","sourceRoot":"","sources":["../../../src/tools/base/abstractTool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAU,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAGxE;;;;;;;;;;;;GAYG;AACH,MAAM,OAAgB,YAAY;IAMX;IACH;IAJC,MAAM,CAAS;IAElC,YACqB,MAAiB,EACpB,YAAuB,EACvC,mBAA4B,EAC5B,MAAe;QAHI,WAAM,GAAN,MAAM,CAAW;QACpB,iBAAY,GAAZ,YAAY,CAAW;QAIvC,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAAC,mBAAmB,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAC9F,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,WAA4B;QAC1C,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;QAElC,MAAM,mBAAmB,GAAG;YAC1B,GAAG,WAAW;YACd,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK;SAC/B,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,YAAY,CACtB,IAAI,CAAC,YAAY,CAAC,MAAM,EACxB;YACE,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,WAAW;YAC1C,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK;YAChD,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,KAAK;YAClD,GAAG,mBAAmB;SACvB,EACD,IAAI,CAAC,aAAa,CACnB,CAAC;IACJ,CAAC;IAWD;;;OAGG;IACO,eAAe,CAAC,WAA4B;QACpD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;IACzF,CAAC;IAED;;;;;OAKG;IACO,QAAQ,CAAC,OAAe,EAAE,KAAY,EAAE,IAAc;QAC9D,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAClC,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED;;;;OAIG;IACO,qBAAqB,CAAC,aAAqB;QACnD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC;IACzD,CAAC;IAED;;;;OAIG;IACO,gBAAgB,CAAC,KAAa,EAAE,IAA8B;QACtE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE;YACtB,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;YACf,YAAY,EAAE,IAAI;YAClB,MAAM,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM;SACjC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/tools/base/abstractWorkflowTool.d.ts

@@ -0,0 +1,34 @@
+import z from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { AbstractTool } from './abstractTool.js';
+import { MCP_WORKFLOW_TOOL_OUTPUT_SCHEMA, WORKFLOW_TOOL_BASE_INPUT_SCHEMA, WorkflowStateData, WorkflowToolMetadata } from '../../common/metadata.js';
+import { Logger } from '../../logging/logger.js';
+/**
+ * Abstract base class for all workflow-participating tools.
+ *
+ * Workflow tools return guidance prompts that instruct the LLM to invoke the
+ * orchestrator tool next, along with the necessary workflow state data.
+ *
+ * The orchestrator tool itself extends AbstractTool directly, as it controls
+ * the workflow rather than participating in it.
+ */
+export declare abstract class AbstractWorkflowTool<TMetadata extends WorkflowToolMetadata<typeof WORKFLOW_TOOL_BASE_INPUT_SCHEMA, z.ZodObject<z.ZodRawShape>, typeof MCP_WORKFLOW_TOOL_OUTPUT_SCHEMA>> extends AbstractTool<TMetadata> {
+    protected readonly orchestratorToolId: string;
+    constructor(server: McpServer, toolMetadata: TMetadata, orchestratorToolId: string, // ID of the orchestrator managing this workflow
+    loggerComponentName?: string, logger?: Logger);
+    /**
+     * Utility method for tools to add post-invocation instructions
+     * that guide the LLM back to the orchestrator for workflow continuation.
+     *
+     * This does NOT invoke the orchestrator - it creates guidance prompts that
+     * instruct the LLM to invoke the orchestrator tool next.
+     *
+     * @param prompt The main tool response prompt
+     * @param workflowStateData Workflow state data to round-trip back to orchestrator
+     * @param resultSchema The optional result schema to format the LLM's output.
+     *                     If not provided, uses the tool's default result schema.
+     * @returns Complete prompt with post-invocation instructions
+     */
+    protected finalizeWorkflowToolOutput(prompt: string, workflowStateData: WorkflowStateData, resultSchema?: TMetadata['resultSchema'] | string): CallToolResult;
+}