@salesforce/magen-mcp-workflow 0.0.1

package/dist/nodes/toolExecutor.js

@@ -0,0 +1,19 @@
+/*
+ * 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 { interrupt } from '@langchain/langgraph';
+/**
+ * Production implementation of ToolExecutor that uses LangGraph's interrupt mechanism.
+ * This is the default implementation used in production workflows.
+ */
+/* c8 ignore start */
+export class LangGraphToolExecutor {
+    execute(toolInvocationData) {
+        return interrupt(toolInvocationData);
+    }
+}
+/* c8 ignore stop */
+//# sourceMappingURL=toolExecutor.js.map

package/dist/nodes/toolExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolExecutor.js","sourceRoot":"","sources":["../../src/nodes/toolExecutor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAiBjD;;;GAGG;AACH,qBAAqB;AACrB,MAAM,OAAO,qBAAqB;IAChC,OAAO,CAAC,kBAAqE;QAC3E,OAAO,SAAS,CAAC,kBAAkB,CAAC,CAAC;IACvC,CAAC;CACF;AACD,oBAAoB"}

package/dist/nodes/userInputExtraction/factory.d.ts

@@ -0,0 +1,42 @@
+import { StateType, StateDefinition } from '@langchain/langgraph';
+import { BaseNode } from '../abstractBaseNode.js';
+import { UserInputExtractionNodeOptions } from './node.js';
+/**
+ * Factory function to create a User Input Extraction Node
+ *
+ * This node extracts structured properties from user input using LLM-based
+ * natural language understanding. It takes raw user input and attempts to extract
+ * as many workflow properties as possible.
+ *
+ * @template TState - The state type for the workflow
+ * @param options - Configuration options for the node
+ * @returns A configured User Input Extraction Node instance
+ *
+ * @example
+ * ```typescript
+ * const MyState = Annotation.Root({
+ *   userInput: Annotation<unknown>,
+ *   platform: Annotation<string>,
+ *   projectName: Annotation<string>,
+ * });
+ *
+ * const properties = {
+ *   platform: {
+ *     zodType: z.enum(['iOS', 'Android']),
+ *     description: 'Target platform',
+ *     friendlyName: 'platform',
+ *   },
+ *   projectName: {
+ *     zodType: z.string(),
+ *     description: 'Project name',
+ *     friendlyName: 'project name',
+ *   },
+ * };
+ *
+ * const node = createUserInputExtractionNode({
+ *   requiredProperties: properties,
+ *   extractionService: myExtractionService,
+ * });
+ * ```
+ */
+export declare function createUserInputExtractionNode<TState extends StateType<StateDefinition>>(options: UserInputExtractionNodeOptions<TState>): BaseNode<TState>;

package/dist/nodes/userInputExtraction/factory.js

@@ -0,0 +1,55 @@
+/*
+ * 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 { LangGraphToolExecutor } from '../toolExecutor.js';
+import { createComponentLogger } from '../../logging/logger.js';
+import { InputExtractionService, } from '../../services/inputExtractionService.js';
+import { UserInputExtractionNode } from './node.js';
+/**
+ * Factory function to create a User Input Extraction Node
+ *
+ * This node extracts structured properties from user input using LLM-based
+ * natural language understanding. It takes raw user input and attempts to extract
+ * as many workflow properties as possible.
+ *
+ * @template TState - The state type for the workflow
+ * @param options - Configuration options for the node
+ * @returns A configured User Input Extraction Node instance
+ *
+ * @example
+ * ```typescript
+ * const MyState = Annotation.Root({
+ *   userInput: Annotation<unknown>,
+ *   platform: Annotation<string>,
+ *   projectName: Annotation<string>,
+ * });
+ *
+ * const properties = {
+ *   platform: {
+ *     zodType: z.enum(['iOS', 'Android']),
+ *     description: 'Target platform',
+ *     friendlyName: 'platform',
+ *   },
+ *   projectName: {
+ *     zodType: z.string(),
+ *     description: 'Project name',
+ *     friendlyName: 'project name',
+ *   },
+ * };
+ *
+ * const node = createUserInputExtractionNode({
+ *   requiredProperties: properties,
+ *   extractionService: myExtractionService,
+ * });
+ * ```
+ */
+export function createUserInputExtractionNode(options) {
+    const { requiredProperties, toolId, extractionService, toolExecutor = new LangGraphToolExecutor(), logger = createComponentLogger('UserInputExtractionNode'), userInputProperty, } = options;
+    // Create default service implementation if not provided
+    const service = extractionService ?? new InputExtractionService(toolId, toolExecutor, logger);
+    return new UserInputExtractionNode(service, requiredProperties, userInputProperty);
+}
+//# sourceMappingURL=factory.js.map

package/dist/nodes/userInputExtraction/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/nodes/userInputExtraction/factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EACL,sBAAsB,GAEvB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAkC,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,6BAA6B,CAC3C,OAA+C;IAE/C,MAAM,EACJ,kBAAkB,EAClB,MAAM,EACN,iBAAiB,EACjB,YAAY,GAAG,IAAI,qBAAqB,EAAE,EAC1C,MAAM,GAAG,qBAAqB,CAAC,yBAAyB,CAAC,EACzD,iBAAiB,GAClB,GAAG,OAAO,CAAC;IAEZ,wDAAwD;IACxD,MAAM,OAAO,GACX,iBAAiB,IAAI,IAAI,sBAAsB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IAEhF,OAAO,IAAI,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,CAAC,CAAC;AACrF,CAAC"}

package/dist/nodes/userInputExtraction/index.d.ts

@@ -0,0 +1,2 @@
+export * from './factory.js';
+export * from './node.js';

package/dist/nodes/userInputExtraction/index.js

@@ -0,0 +1,3 @@
+export * from './factory.js';
+export * from './node.js';
+//# sourceMappingURL=index.js.map

package/dist/nodes/userInputExtraction/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/nodes/userInputExtraction/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/nodes/userInputExtraction/node.d.ts

@@ -0,0 +1,60 @@
+import { StateType, StateDefinition } from '@langchain/langgraph';
+import { BaseNode } from '../abstractBaseNode.js';
+import { PropertyMetadataCollection } from '../../common/propertyMetadata.js';
+import { ToolExecutor } from '../toolExecutor.js';
+import { Logger } from '../../logging/logger.js';
+import { InputExtractionServiceProvider } from '../../services/inputExtractionService.js';
+/**
+ * Configuration options for creating a User Input Extraction Node
+ */
+export interface UserInputExtractionNodeOptions<TState extends StateType<StateDefinition>> {
+    /**
+     * Collection of properties that must be collected from user
+     */
+    requiredProperties: PropertyMetadataCollection;
+    /**
+     * Tool ID for the input extraction tool (e.g., 'magen-input-extraction', 'sfmobile-native-input-extraction')
+     * Required if extractionService is not provided
+     */
+    toolId: string;
+    /**
+     * Service provider for property extraction (injectable for testing)
+     * If not provided, a default implementation will be created using toolId
+     */
+    extractionService?: InputExtractionServiceProvider;
+    /**
+     * Tool executor for services (optional, defaults to LangGraphToolExecutor)
+     */
+    toolExecutor?: ToolExecutor;
+    /**
+     * Logger instance (optional, defaults to component logger)
+     */
+    logger?: Logger;
+    /**
+     * Property name in state that contains user input to extract from.
+     * Must be a valid property of TState.
+     *
+     * @example
+     *
+     * // State has a 'userInput' property
+     * createUserInputExtractionNode({
+     *   userInputProperty: 'userInput',
+     *   ...
+     * });
+     *
+     * // State has a 'currentUtterance' property
+     * createUserInputExtractionNode({
+     *   userInputProperty: 'currentUtterance',
+     *   ...
+     * });
+     *
+     */
+    userInputProperty: keyof TState;
+}
+export declare class UserInputExtractionNode<TState extends StateType<StateDefinition>> extends BaseNode<TState> {
+    private readonly extractionService;
+    private readonly requiredProperties;
+    private readonly userInputProperty;
+    constructor(extractionService: InputExtractionServiceProvider, requiredProperties: PropertyMetadataCollection, userInputProperty: keyof TState);
+    execute: (state: TState) => Partial<TState>;
+}

package/dist/nodes/userInputExtraction/node.js

@@ -0,0 +1,24 @@
+/*
+ * 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 { BaseNode } from '../abstractBaseNode.js';
+export class UserInputExtractionNode extends BaseNode {
+    extractionService;
+    requiredProperties;
+    userInputProperty;
+    constructor(extractionService, requiredProperties, userInputProperty) {
+        super('userInputExtraction');
+        this.extractionService = extractionService;
+        this.requiredProperties = requiredProperties;
+        this.userInputProperty = userInputProperty;
+    }
+    execute = (state) => {
+        const userInput = state[this.userInputProperty];
+        const result = this.extractionService.extractProperties(userInput, this.requiredProperties);
+        return result.extractedProperties;
+    };
+}
+//# sourceMappingURL=node.js.map

package/dist/nodes/userInputExtraction/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../../src/nodes/userInputExtraction/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AA2DlD,MAAM,OAAO,uBAEX,SAAQ,QAAgB;IAEL;IACA;IACA;IAHnB,YACmB,iBAAiD,EACjD,kBAA8C,EAC9C,iBAA+B;QAEhD,KAAK,CAAC,qBAAqB,CAAC,CAAC;QAJZ,sBAAiB,GAAjB,iBAAiB,CAAgC;QACjD,uBAAkB,GAAlB,kBAAkB,CAA4B;QAC9C,sBAAiB,GAAjB,iBAAiB,CAAc;IAGlD,CAAC;IAED,OAAO,GAAG,CAAC,KAAa,EAAmB,EAAE;QAC3C,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,SAAS,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC5F,OAAO,MAAM,CAAC,mBAAiD,CAAC;IAClE,CAAC,CAAC;CACH"}

package/dist/routers/checkPropertiesFulfilledRouter.d.ts

@@ -0,0 +1,74 @@
+import { StateType, StateDefinition } from '@langchain/langgraph';
+import { PropertyMetadataCollection } from '../common/propertyMetadata.js';
+import { Logger } from '../logging/logger.js';
+/**
+ * Conditional router edge to check whether all required properties have been collected.
+ *
+ * This router evaluates the workflow state to determine if all properties specified
+ * in the required properties collection have been fulfilled (are truthy). Based on
+ * this evaluation, it routes to either a "fulfilled" or "unfulfilled" node.
+ *
+ * @template TState - The state type for the workflow
+ *
+ * @example
+ * ```typescript
+ * const requiredProperties: PropertyMetadataCollection = {
+ *   platform: {
+ *     zodType: z.enum(['iOS', 'Android']),
+ *     description: 'Target platform',
+ *     friendlyName: 'platform',
+ *   },
+ *   projectName: {
+ *     zodType: z.string(),
+ *     description: 'Project name',
+ *     friendlyName: 'project name',
+ *   },
+ * };
+ *
+ * const router = new CheckPropertiesFulfilledRouter<State>(
+ *   'continueWorkflow',  // Node to route to when all properties are fulfilled
+ *   'getUserInput',      // Node to route to when properties are missing
+ *   requiredProperties
+ * );
+ *
+ * // Use in LangGraph workflow
+ * workflow.addConditionalEdges('checkProperties', router.execute);
+ * ```
+ */
+export declare class CheckPropertiesFulfilledRouter<TState extends StateType<StateDefinition>> {
+    private readonly propertiesFulfilledNodeName;
+    private readonly propertiesUnfulfilledNodeName;
+    private readonly requiredProperties;
+    private readonly logger;
+    /**
+     * Creates a new CheckPropertiesFulfilledRouter.
+     *
+     * @param propertiesFulfilledNodeName - The name of the node to route to if all properties are fulfilled
+     * @param propertiesUnfulfilledNodeName - The name of the node to route to if any property is unfulfilled
+     * @param requiredProperties - Collection of properties that must be collected from user
+     * @param logger - Optional logger instance for debugging and monitoring routing decisions.
+     *                 If not provided, a default component logger will be created.
+     */
+    constructor(propertiesFulfilledNodeName: string, propertiesUnfulfilledNodeName: string, requiredProperties: PropertyMetadataCollection, logger?: Logger);
+    /**
+     * Evaluates the state to determine the next node based on property fulfillment.
+     *
+     * This method checks each property in the required properties collection.
+     * If any property is missing or falsy, it routes to the unfulfilled node.
+     * Only if all properties are present and truthy does it route to the fulfilled node.
+     *
+     * @param state - The current workflow state
+     * @returns The name of the next node to route to
+     */
+    execute: (state: TState) => string;
+    /**
+     * Internal method to check property fulfillment status.
+     *
+     * Iterates through all required properties and checks if they exist
+     * and are truthy in the state object.
+     *
+     * @param state - The current workflow state
+     * @returns The name of the node to route to based on fulfillment status
+     */
+    private getPropertyFulfillmentStatus;
+}

package/dist/routers/checkPropertiesFulfilledRouter.js

@@ -0,0 +1,106 @@
+/*
+ * 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';
+/**
+ * Conditional router edge to check whether all required properties have been collected.
+ *
+ * This router evaluates the workflow state to determine if all properties specified
+ * in the required properties collection have been fulfilled (are truthy). Based on
+ * this evaluation, it routes to either a "fulfilled" or "unfulfilled" node.
+ *
+ * @template TState - The state type for the workflow
+ *
+ * @example
+ * ```typescript
+ * const requiredProperties: PropertyMetadataCollection = {
+ *   platform: {
+ *     zodType: z.enum(['iOS', 'Android']),
+ *     description: 'Target platform',
+ *     friendlyName: 'platform',
+ *   },
+ *   projectName: {
+ *     zodType: z.string(),
+ *     description: 'Project name',
+ *     friendlyName: 'project name',
+ *   },
+ * };
+ *
+ * const router = new CheckPropertiesFulfilledRouter<State>(
+ *   'continueWorkflow',  // Node to route to when all properties are fulfilled
+ *   'getUserInput',      // Node to route to when properties are missing
+ *   requiredProperties
+ * );
+ *
+ * // Use in LangGraph workflow
+ * workflow.addConditionalEdges('checkProperties', router.execute);
+ * ```
+ */
+export class CheckPropertiesFulfilledRouter {
+    propertiesFulfilledNodeName;
+    propertiesUnfulfilledNodeName;
+    requiredProperties;
+    logger;
+    /**
+     * Creates a new CheckPropertiesFulfilledRouter.
+     *
+     * @param propertiesFulfilledNodeName - The name of the node to route to if all properties are fulfilled
+     * @param propertiesUnfulfilledNodeName - The name of the node to route to if any property is unfulfilled
+     * @param requiredProperties - Collection of properties that must be collected from user
+     * @param logger - Optional logger instance for debugging and monitoring routing decisions.
+     *                 If not provided, a default component logger will be created.
+     */
+    constructor(propertiesFulfilledNodeName, propertiesUnfulfilledNodeName, requiredProperties, logger) {
+        this.propertiesFulfilledNodeName = propertiesFulfilledNodeName;
+        this.propertiesUnfulfilledNodeName = propertiesUnfulfilledNodeName;
+        this.requiredProperties = requiredProperties;
+        this.logger = logger || createComponentLogger('CheckPropertiesFulfilledRouter');
+    }
+    /**
+     * Evaluates the state to determine the next node based on property fulfillment.
+     *
+     * This method checks each property in the required properties collection.
+     * If any property is missing or falsy, it routes to the unfulfilled node.
+     * Only if all properties are present and truthy does it route to the fulfilled node.
+     *
+     * @param state - The current workflow state
+     * @returns The name of the next node to route to
+     */
+    execute = (state) => {
+        return this.getPropertyFulfillmentStatus(state);
+    };
+    /**
+     * Internal method to check property fulfillment status.
+     *
+     * Iterates through all required properties and checks if they exist
+     * and are truthy in the state object.
+     *
+     * @param state - The current workflow state
+     * @returns The name of the node to route to based on fulfillment status
+     */
+    getPropertyFulfillmentStatus(state) {
+        const unfulfilledProperties = [];
+        for (const propertyName of Object.keys(this.requiredProperties)) {
+            if (!state[propertyName]) {
+                unfulfilledProperties.push(propertyName);
+            }
+        }
+        if (unfulfilledProperties.length > 0) {
+            this.logger.debug('Properties not fulfilled, routing to unfulfilled node', {
+                unfulfilledProperties,
+                targetNode: this.propertiesUnfulfilledNodeName,
+                totalRequired: Object.keys(this.requiredProperties).length,
+            });
+            return this.propertiesUnfulfilledNodeName;
+        }
+        this.logger.debug('All properties fulfilled, routing to fulfilled node', {
+            targetNode: this.propertiesFulfilledNodeName,
+            totalProperties: Object.keys(this.requiredProperties).length,
+        });
+        return this.propertiesFulfilledNodeName;
+    }
+}
+//# sourceMappingURL=checkPropertiesFulfilledRouter.js.map

package/dist/routers/checkPropertiesFulfilledRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkPropertiesFulfilledRouter.js","sourceRoot":"","sources":["../../src/routers/checkPropertiesFulfilledRouter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAU,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,OAAO,8BAA8B;IACxB,2BAA2B,CAAS;IACpC,6BAA6B,CAAS;IACtC,kBAAkB,CAA6B;IAC/C,MAAM,CAAS;IAEhC;;;;;;;;OAQG;IACH,YACE,2BAAmC,EACnC,6BAAqC,EACrC,kBAA8C,EAC9C,MAAe;QAEf,IAAI,CAAC,2BAA2B,GAAG,2BAA2B,CAAC;QAC/D,IAAI,CAAC,6BAA6B,GAAG,6BAA6B,CAAC;QACnE,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAAC,gCAAgC,CAAC,CAAC;IAClF,CAAC;IAED;;;;;;;;;OASG;IACH,OAAO,GAAG,CAAC,KAAa,EAAU,EAAE;QAClC,OAAO,IAAI,CAAC,4BAA4B,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC,CAAC;IAEF;;;;;;;;OAQG;IACK,4BAA4B,CAAC,KAAa;QAChD,MAAM,qBAAqB,GAAa,EAAE,CAAC;QAE3C,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAChE,IAAI,CAAC,KAAK,CAAC,YAA4B,CAAC,EAAE,CAAC;gBACzC,qBAAqB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QAED,IAAI,qBAAqB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,uDAAuD,EAAE;gBACzE,qBAAqB;gBACrB,UAAU,EAAE,IAAI,CAAC,6BAA6B;gBAC9C,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,MAAM;aAC3D,CAAC,CAAC;YACH,OAAO,IAAI,CAAC,6BAA6B,CAAC;QAC5C,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,qDAAqD,EAAE;YACvE,UAAU,EAAE,IAAI,CAAC,2BAA2B;YAC5C,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,MAAM;SAC7D,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,2BAA2B,CAAC;IAC1C,CAAC;CACF"}

package/dist/routers/index.d.ts

@@ -0,0 +1 @@
+export { CheckPropertiesFulfilledRouter } from './checkPropertiesFulfilledRouter.js';

package/dist/routers/index.js

@@ -0,0 +1,8 @@
+/*
+ * 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 { CheckPropertiesFulfilledRouter } from './checkPropertiesFulfilledRouter.js';
+//# sourceMappingURL=index.js.map

package/dist/routers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/routers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/services/abstractService.d.ts

@@ -0,0 +1,71 @@
+import z from 'zod';
+import { MCPToolInvocationData } from '../common/metadata.js';
+import { Logger } from '../logging/logger.js';
+import { ToolExecutor } from '../nodes/toolExecutor.js';
+/**
+ * Abstract base class for services that execute MCP tools.
+ *
+ * This class provides a standardized pattern for services that need to invoke
+ * MCP tools with proper logging, error handling, and result validation. It mirrors
+ * the functionality of AbstractToolNode but is designed for service-layer components
+ * that don't participate in the LangGraph workflow state machine.
+ *
+ * Features:
+ * - Dependency injection support for ToolExecutor and Logger
+ * - Automatic component naming and logger initialization
+ * - Common tool execution pattern with comprehensive logging
+ * - Result validation using Zod schemas
+ * - Optional custom validation logic
+ *
+ * Services that extend this class should:
+ * 1. Call super() in their constructor, optionally passing toolExecutor and logger
+ * 2. Use executeToolWithLogging() to invoke tools
+ * 3. Implement their business logic around the tool invocations
+ *
+ * @example
+ * export class MyService extends AbstractService {
+ *   constructor(toolExecutor?: ToolExecutor, logger?: Logger) {
+ *     super('MyService', toolExecutor, logger);
+ *   }
+ *
+ *   doSomething(input: string): ResultType {
+ *     const toolInvocationData = { ... };
+ *     return this.executeToolWithLogging(
+ *       toolInvocationData,
+ *       MyToolResultSchema
+ *     );
+ *   }
+ * }
+ */
+export declare abstract class AbstractService {
+    protected readonly logger: Logger;
+    protected readonly componentName: string;
+    protected readonly toolExecutor: ToolExecutor;
+    /**
+     * Creates a new AbstractService.
+     *
+     * @param serviceName - Name of the service (used for logging and component identification)
+     * @param toolExecutor - Tool executor for invoking MCP tools (injectable for testing)
+     * @param logger - Logger instance (injectable for testing)
+     */
+    constructor(serviceName: string, toolExecutor?: ToolExecutor, logger?: Logger);
+    /**
+     * Protected method to execute a tool with logging and validation.
+     *
+     * By default, results are validated using the provided Zod schema's parse method.
+     * Pass a custom validator function to implement additional validation logic or
+     * transformation of the result.
+     *
+     * This method uses the common toolExecutionUtils.executeToolWithLogging function
+     * to ensure consistent behavior across all tool invocations in the codebase.
+     *
+     * @param toolInvocationData - The tool invocation data to pass to the tool executor
+     * @param resultSchema - The schema to validate the result against
+     * @param validator - Optional custom validator function
+     * @returns The validated result from the tool execution
+     *
+     * @throws {z.ZodError} If the result does not match the schema (when using default validation)
+     * @throws {Error} If tool execution fails or custom validator throws
+     */
+    protected executeToolWithLogging<TResultSchema extends z.ZodObject<z.ZodRawShape>>(toolInvocationData: MCPToolInvocationData<z.ZodObject<z.ZodRawShape>>, resultSchema: TResultSchema, validator?: (result: unknown, schema: TResultSchema) => z.infer<TResultSchema>): z.infer<TResultSchema>;
+}

package/dist/services/abstractService.js

@@ -0,0 +1,83 @@
+/*
+ * 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';
+import { LangGraphToolExecutor } from '../nodes/toolExecutor.js';
+import { executeToolWithLogging } from '../utils/toolExecutionUtils.js';
+/**
+ * Abstract base class for services that execute MCP tools.
+ *
+ * This class provides a standardized pattern for services that need to invoke
+ * MCP tools with proper logging, error handling, and result validation. It mirrors
+ * the functionality of AbstractToolNode but is designed for service-layer components
+ * that don't participate in the LangGraph workflow state machine.
+ *
+ * Features:
+ * - Dependency injection support for ToolExecutor and Logger
+ * - Automatic component naming and logger initialization
+ * - Common tool execution pattern with comprehensive logging
+ * - Result validation using Zod schemas
+ * - Optional custom validation logic
+ *
+ * Services that extend this class should:
+ * 1. Call super() in their constructor, optionally passing toolExecutor and logger
+ * 2. Use executeToolWithLogging() to invoke tools
+ * 3. Implement their business logic around the tool invocations
+ *
+ * @example
+ * export class MyService extends AbstractService {
+ *   constructor(toolExecutor?: ToolExecutor, logger?: Logger) {
+ *     super('MyService', toolExecutor, logger);
+ *   }
+ *
+ *   doSomething(input: string): ResultType {
+ *     const toolInvocationData = { ... };
+ *     return this.executeToolWithLogging(
+ *       toolInvocationData,
+ *       MyToolResultSchema
+ *     );
+ *   }
+ * }
+ */
+export class AbstractService {
+    logger;
+    componentName;
+    toolExecutor;
+    /**
+     * Creates a new AbstractService.
+     *
+     * @param serviceName - Name of the service (used for logging and component identification)
+     * @param toolExecutor - Tool executor for invoking MCP tools (injectable for testing)
+     * @param logger - Logger instance (injectable for testing)
+     */
+    constructor(serviceName, toolExecutor, logger) {
+        this.componentName = `Service:${serviceName}`;
+        this.logger = logger ?? createComponentLogger(this.componentName);
+        this.toolExecutor = toolExecutor ?? new LangGraphToolExecutor();
+    }
+    /**
+     * Protected method to execute a tool with logging and validation.
+     *
+     * By default, results are validated using the provided Zod schema's parse method.
+     * Pass a custom validator function to implement additional validation logic or
+     * transformation of the result.
+     *
+     * This method uses the common toolExecutionUtils.executeToolWithLogging function
+     * to ensure consistent behavior across all tool invocations in the codebase.
+     *
+     * @param toolInvocationData - The tool invocation data to pass to the tool executor
+     * @param resultSchema - The schema to validate the result against
+     * @param validator - Optional custom validator function
+     * @returns The validated result from the tool execution
+     *
+     * @throws {z.ZodError} If the result does not match the schema (when using default validation)
+     * @throws {Error} If tool execution fails or custom validator throws
+     */
+    executeToolWithLogging(toolInvocationData, resultSchema, validator) {
+        return executeToolWithLogging(this.toolExecutor, this.logger, toolInvocationData, resultSchema, validator);
+    }
+}
+//# sourceMappingURL=abstractService.js.map

package/dist/services/abstractService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstractService.js","sourceRoot":"","sources":["../../src/services/abstractService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAU,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAgB,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAgB,eAAe;IAChB,MAAM,CAAS;IACf,aAAa,CAAS;IACtB,YAAY,CAAe;IAE9C;;;;;;OAMG;IACH,YAAY,WAAmB,EAAE,YAA2B,EAAE,MAAe;QAC3E,IAAI,CAAC,aAAa,GAAG,WAAW,WAAW,EAAE,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAClE,IAAI,CAAC,YAAY,GAAG,YAAY,IAAI,IAAI,qBAAqB,EAAE,CAAC;IAClE,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACO,sBAAsB,CAC9B,kBAAqE,EACrE,YAA2B,EAC3B,SAA8E;QAE9E,OAAO,sBAAsB,CAC3B,IAAI,CAAC,YAAY,EACjB,IAAI,CAAC,MAAM,EACX,kBAAkB,EAClB,YAAY,EACZ,SAAS,CACV,CAAC;IACJ,CAAC;CACF"}

package/dist/services/getInputService.d.ts

@@ -0,0 +1,43 @@
+import { ToolExecutor } from '../nodes/toolExecutor.js';
+import { AbstractService } from './abstractService.js';
+import { Logger } from '../logging/logger.js';
+export interface GetInputProperty {
+    /** Property name to be collected */
+    readonly propertyName: string;
+    /** Human-readable name for display */
+    readonly friendlyName: string;
+    /** Detailed description for LLM-based extraction */
+    readonly description: string;
+    /** Optional reason why the property is unfulfilled */
+    readonly reason?: string;
+}
+/**
+ * Provider interface for user input service.
+ * This interface allows for dependency injection and testing.
+ */
+export interface GetInputServiceProvider {
+    /**
+     * Solicits user input with a given question.
+     *
+     * @param question - The question to ask the user
+     * @returns The user's response (can be any type)
+     */
+    getInput(unfulfilledProperties: GetInputProperty[]): unknown;
+}
+/**
+ * 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 declare class GetInputService extends AbstractService implements GetInputServiceProvider {
+    private readonly 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: string, toolExecutor?: ToolExecutor, logger?: Logger);
+    getInput(unfulfilledProperties: GetInputProperty[]): unknown;
+}