@salesforce/magen-mcp-workflow 0.0.1

package/dist/index.js

@@ -0,0 +1,37 @@
+/*
+ * 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
+ */
+// Common - Filesystem Operations
+export { NodeFileSystemOperations } from './common/fileSystem.js';
+// Storage (Well-Known Directory)
+export { WELL_KNOWN_DIR_NAME, WELL_KNOWN_FILES, WellKnownDirectoryManager, } from './storage/wellKnownDirectory.js';
+// Logging
+export { PinoLogger, createLogger, createComponentLogger, createWorkflowLogger, } from './logging/logger.js';
+// Common Metadata
+export { WORKFLOW_STATE_DATA_SCHEMA, WORKFLOW_PROPERTY_NAMES, WORKFLOW_TOOL_BASE_INPUT_SCHEMA, MCP_WORKFLOW_TOOL_OUTPUT_SCHEMA, } from './common/metadata.js';
+// Tool Execution Infrastructure
+export { LangGraphToolExecutor } from './nodes/toolExecutor.js';
+// Tool Execution Utils
+export { executeToolWithLogging } from './utils/toolExecutionUtils.js';
+// Base Tool Classes
+export { AbstractTool, AbstractWorkflowTool } from './tools/base/index.js';
+// Utility Tools
+export { 
+// Get Input Tool
+GetInputTool, createGetInputTool, createGetInputMetadata, GET_INPUT_PROPERTY_SCHEMA, GET_INPUT_WORKFLOW_INPUT_SCHEMA, GET_INPUT_WORKFLOW_RESULT_SCHEMA, 
+// Input Extraction Tool
+InputExtractionTool, createInputExtractionTool, createInputExtractionMetadata, INPUT_EXTRACTION_WORKFLOW_INPUT_SCHEMA, INPUT_EXTRACTION_WORKFLOW_RESULT_SCHEMA, } from './tools/utilities/index.js';
+// Base Node Classes
+export { BaseNode, AbstractToolNode, createGetUserInputNode, createUserInputExtractionNode, } from './nodes/index.js';
+// Routers
+export { CheckPropertiesFulfilledRouter } from './routers/index.js';
+// Base Service Classes
+export { AbstractService } from './services/index.js';
+// Checkpointing Infrastructure
+export { JsonCheckpointSaver, WorkflowStatePersistence, WorkflowStateManager, } from './checkpointing/index.js';
+// Orchestrator Tool
+export { OrchestratorTool, createOrchestratorToolMetadata, ORCHESTRATOR_INPUT_SCHEMA, ORCHESTRATOR_OUTPUT_SCHEMA, } from './tools/orchestrator/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iCAAiC;AACjC,OAAO,EAA6B,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAE7F,iCAAiC;AACjC,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAEhB,yBAAyB,GAC1B,MAAM,iCAAiC,CAAC;AAEzC,UAAU;AACV,OAAO,EAEL,UAAU,EACV,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,kBAAkB;AAClB,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,+BAA+B,EAC/B,+BAA+B,GAMhC,MAAM,sBAAsB,CAAC;AAU9B,gCAAgC;AAChC,OAAO,EAAqB,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEnF,uBAAuB;AACvB,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE3E,gBAAgB;AAChB,OAAO;AACL,iBAAiB;AACjB,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EAItB,yBAAyB,EACzB,+BAA+B,EAC/B,gCAAgC;AAChC,wBAAwB;AACxB,mBAAmB,EACnB,yBAAyB,EACzB,6BAA6B,EAI7B,sCAAsC,EACtC,uCAAuC,GACxC,MAAM,4BAA4B,CAAC;AAEpC,oBAAoB;AACpB,OAAO,EACL,QAAQ,EACR,gBAAgB,EAChB,sBAAsB,EACtB,6BAA6B,GAG9B,MAAM,kBAAkB,CAAC;AAE1B,UAAU;AACV,OAAO,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAEpE,uBAAuB;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,+BAA+B;AAC/B,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GAGrB,MAAM,0BAA0B,CAAC;AAElC,oBAAoB;AACpB,OAAO,EACL,gBAAgB,EAChB,8BAA8B,EAK9B,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,+BAA+B,CAAC"}

package/dist/logging/logger.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Logging module for the Mobile Native MCP Server
+ *
+ * Provides a production-ready logging solution using pino with proper dependency injection
+ * support for testing and reuse across all MCP tools and facilities.
+ */
+import pino from 'pino';
+/**
+ * Logger interface for dependency injection - compatible with pino
+ * This interface allows for clean testing and consistent logging across all components
+ */
+export interface Logger {
+    info(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    error(message: string, error?: Error): void;
+    warn(message: string, data?: unknown): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+/**
+ * Pino-based logger implementation
+ * Wraps pino instances to provide our Logger interface while maintaining all pino benefits
+ */
+export declare class PinoLogger implements Logger {
+    private pinoInstance;
+    constructor(pinoInstance: pino.Logger);
+    info(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    error(message: string, error?: Error): void;
+    warn(message: string, data?: unknown): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+/**
+ * Factory function to create a logger that writes to .magen directory
+ *
+ * @param level - Log level (default: from LOG_LEVEL env var or 'info')
+ * @param options - Additional pino configuration options
+ * @returns Logger instance configured for file logging
+ */
+export declare function createLogger(level?: string, options?: pino.LoggerOptions): Logger;
+/**
+ * Create a logger for a specific MCP tool or component
+ *
+ * @param componentName - Name of the component (e.g., 'TemplateDiscovery', 'BuildTool')
+ * @param level - Log level override
+ * @returns Logger instance with component context
+ */
+export declare function createComponentLogger(componentName: string, level?: string): Logger;
+/**
+ * Create a specialized logger for workflow orchestration and MCP tool interactions
+ *
+ * @param componentName - Name of the workflow component
+ * @param level - Log level (default: 'info')
+ * @param serviceName - Service name for log metadata (default: 'mcp-workflow')
+ * @returns Logger instance configured for workflow logging with additional metadata
+ */
+export declare function createWorkflowLogger(componentName: string, level?: string, serviceName?: string): Logger;

package/dist/logging/logger.js

@@ -0,0 +1,113 @@
+/*
+ * 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
+ */
+/**
+ * Logging module for the Mobile Native MCP Server
+ *
+ * Provides a production-ready logging solution using pino with proper dependency injection
+ * support for testing and reuse across all MCP tools and facilities.
+ */
+import pino from 'pino';
+import { WellKnownDirectoryManager } from '../storage/wellKnownDirectory.js';
+/**
+ * Pino-based logger implementation
+ * Wraps pino instances to provide our Logger interface while maintaining all pino benefits
+ */
+export class PinoLogger {
+    pinoInstance;
+    constructor(pinoInstance) {
+        this.pinoInstance = pinoInstance;
+    }
+    info(message, data) {
+        if (data) {
+            this.pinoInstance.info(data, message);
+        }
+        else {
+            this.pinoInstance.info(message);
+        }
+    }
+    debug(message, data) {
+        if (data) {
+            this.pinoInstance.debug(data, message);
+        }
+        else {
+            this.pinoInstance.debug(message);
+        }
+    }
+    error(message, error) {
+        if (error) {
+            this.pinoInstance.error({ err: error }, message);
+        }
+        else {
+            this.pinoInstance.error(message);
+        }
+    }
+    warn(message, data) {
+        if (data) {
+            this.pinoInstance.warn(data, message);
+        }
+        else {
+            this.pinoInstance.warn(message);
+        }
+    }
+    child(bindings) {
+        return new PinoLogger(this.pinoInstance.child(bindings));
+    }
+}
+/**
+ * Factory function to create a logger that writes to .magen directory
+ *
+ * @param level - Log level (default: from LOG_LEVEL env var or 'info')
+ * @param options - Additional pino configuration options
+ * @returns Logger instance configured for file logging
+ */
+export function createLogger(level = process.env.LOG_LEVEL || 'info', options = {}) {
+    const wellKnownDirManager = new WellKnownDirectoryManager();
+    const logFilePath = wellKnownDirManager.getWorkflowLogsPath();
+    const pinoInstance = pino({
+        level,
+        // Use structured JSON output for file logging
+        ...options,
+    }, pino.destination({
+        dest: logFilePath,
+        sync: false, // Async logging for better performance
+    }));
+    return new PinoLogger(pinoInstance);
+}
+/**
+ * Create a logger for a specific MCP tool or component
+ *
+ * @param componentName - Name of the component (e.g., 'TemplateDiscovery', 'BuildTool')
+ * @param level - Log level override
+ * @returns Logger instance with component context
+ */
+export function createComponentLogger(componentName, level) {
+    const baseLogger = createLogger(level);
+    return baseLogger.child({ component: componentName });
+}
+/**
+ * Create a specialized logger for workflow orchestration and MCP tool interactions
+ *
+ * @param componentName - Name of the workflow component
+ * @param level - Log level (default: 'info')
+ * @param serviceName - Service name for log metadata (default: 'mcp-workflow')
+ * @returns Logger instance configured for workflow logging with additional metadata
+ */
+export function createWorkflowLogger(componentName, level, serviceName) {
+    const service = serviceName || 'mcp-workflow';
+    const baseLogger = createLogger(level, {
+        // Add workflow-specific metadata to all log entries
+        base: {
+            service,
+            logType: 'workflow',
+        },
+    });
+    return baseLogger.child({
+        component: componentName,
+        workflowSession: true,
+    });
+}
+//# sourceMappingURL=logger.js.map

package/dist/logging/logger.js.map

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

package/dist/nodes/abstractBaseNode.d.ts

@@ -0,0 +1,27 @@
+import { StateType, StateDefinition } from '@langchain/langgraph';
+/**
+ * Base class for all workflow nodes
+ *
+ * @template TState - The state type for the workflow (defaults to StateType<StateDefinition>)
+ *
+ * Example:
+ * ```
+ * const MyWorkflowState = Annotation.Root({ count: Annotation<number> });
+ * type State = typeof MyWorkflowState.State; // This is StateType<typeof MyWorkflowState.spec>
+ *
+ * class IncrementNode extends BaseNode<State> {
+ *   constructor() {
+ *     super('increment');
+ *   }
+ *
+ *   execute = (state: State) => {
+ *     return { count: state.count + 1 };
+ *   };
+ * }
+ * ```
+ */
+export declare abstract class BaseNode<TState extends StateType<StateDefinition>> {
+    readonly name: string;
+    constructor(name: string);
+    abstract execute: (state: TState) => Partial<TState>;
+}

package/dist/nodes/abstractBaseNode.js

@@ -0,0 +1,34 @@
+/*
+ * 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
+ */
+/**
+ * Base class for all workflow nodes
+ *
+ * @template TState - The state type for the workflow (defaults to StateType<StateDefinition>)
+ *
+ * Example:
+ * ```
+ * const MyWorkflowState = Annotation.Root({ count: Annotation<number> });
+ * type State = typeof MyWorkflowState.State; // This is StateType<typeof MyWorkflowState.spec>
+ *
+ * class IncrementNode extends BaseNode<State> {
+ *   constructor() {
+ *     super('increment');
+ *   }
+ *
+ *   execute = (state: State) => {
+ *     return { count: state.count + 1 };
+ *   };
+ * }
+ * ```
+ */
+export class BaseNode {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+}
+//# sourceMappingURL=abstractBaseNode.js.map

package/dist/nodes/abstractBaseNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstractBaseNode.js","sourceRoot":"","sources":["../../src/nodes/abstractBaseNode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAgB,QAAQ;IACZ,IAAI,CAAS;IAE7B,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CAGF"}

package/dist/nodes/abstractToolNode.d.ts

@@ -0,0 +1,32 @@
+import z from 'zod';
+import { StateType, StateDefinition } from '@langchain/langgraph';
+import { BaseNode } from './abstractBaseNode.js';
+import { MCPToolInvocationData } from '../common/metadata.js';
+import { Logger } from '../logging/logger.js';
+import { ToolExecutor } from './toolExecutor.js';
+/**
+ * Abstract base class for nodes that execute MCP tools
+ *
+ * @template TState - The state type for the workflow (defaults to StateType<StateDefinition>)
+ */
+export declare abstract class AbstractToolNode<TState extends StateType<StateDefinition>> extends BaseNode<TState> {
+    protected readonly logger: Logger;
+    protected readonly componentName: string;
+    protected readonly toolExecutor: ToolExecutor;
+    constructor(name: 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.
+     *
+     * 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
+     */
+    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/nodes/abstractToolNode.js

@@ -0,0 +1,44 @@
+/*
+ * 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';
+import { createComponentLogger } from '../logging/logger.js';
+import { LangGraphToolExecutor } from './toolExecutor.js';
+import { executeToolWithLogging } from '../utils/toolExecutionUtils.js';
+/**
+ * Abstract base class for nodes that execute MCP tools
+ *
+ * @template TState - The state type for the workflow (defaults to StateType<StateDefinition>)
+ */
+export class AbstractToolNode extends BaseNode {
+    logger;
+    componentName;
+    toolExecutor;
+    constructor(name, toolExecutor, logger) {
+        super(name);
+        this.componentName = `WorkflowNode:${this.constructor.name}`;
+        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.
+     *
+     * 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
+     */
+    executeToolWithLogging(toolInvocationData, resultSchema, validator) {
+        return executeToolWithLogging(this.toolExecutor, this.logger, toolInvocationData, resultSchema, validator);
+    }
+}
+//# sourceMappingURL=abstractToolNode.js.map

package/dist/nodes/abstractToolNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstractToolNode.js","sourceRoot":"","sources":["../../src/nodes/abstractToolNode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAU,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAgB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE;;;;GAIG;AACH,MAAM,OAAgB,gBAEpB,SAAQ,QAAgB;IACL,MAAM,CAAS;IACf,aAAa,CAAS;IACtB,YAAY,CAAe;IAE9C,YAAY,IAAY,EAAE,YAA2B,EAAE,MAAe;QACpE,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,aAAa,GAAG,gBAAgB,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QAC7D,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;;;;;;;;;;;;;OAaG;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/nodes/getUserInput/factory.d.ts

@@ -0,0 +1,42 @@
+import { StateType, StateDefinition } from '@langchain/langgraph';
+import { BaseNode } from '../abstractBaseNode.js';
+import { GetUserInputNodeOptions } from './node.js';
+/**
+ * Factory function to create a Get User Input Node
+ *
+ * This node requests user input for any unfulfilled required properties.
+ * It determines which properties are missing, calls the GetInputService to
+ * prompt the user, and returns the user's response.
+ *
+ * @template TState - The state type for the workflow
+ * @param options - Configuration options for the node
+ * @returns A configured Get User Input 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 = createGetUserInputNode({
+ *   requiredProperties: properties,
+ *   getInputService: myGetInputService,
+ * });
+ * ```
+ */
+export declare function createGetUserInputNode<TState extends StateType<StateDefinition>>(options: GetUserInputNodeOptions<TState>): BaseNode<TState>;

package/dist/nodes/getUserInput/factory.js

@@ -0,0 +1,64 @@
+/*
+ * 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 { GetInputService } from '../../services/getInputService.js';
+import { GetUserInputNode } from './node.js';
+/**
+ * Factory function to create a Get User Input Node
+ *
+ * This node requests user input for any unfulfilled required properties.
+ * It determines which properties are missing, calls the GetInputService to
+ * prompt the user, and returns the user's response.
+ *
+ * @template TState - The state type for the workflow
+ * @param options - Configuration options for the node
+ * @returns A configured Get User Input 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 = createGetUserInputNode({
+ *   requiredProperties: properties,
+ *   getInputService: myGetInputService,
+ * });
+ * ```
+ */
+export function createGetUserInputNode(options) {
+    const { requiredProperties, toolId, getInputService, toolExecutor = new LangGraphToolExecutor(), logger = createComponentLogger('GetUserInputNode'), isPropertyFulfilled = (state, propertyName) => {
+        const isFulfilled = !!state[propertyName];
+        if (isFulfilled) {
+            return { isFulfilled: true };
+        }
+        return {
+            isFulfilled: false,
+            reason: `Property '${propertyName}' is missing from the workflow state.`,
+        };
+    }, userInputProperty, } = options;
+    // Create default service implementation if not provided
+    const service = getInputService ?? new GetInputService(toolId, toolExecutor, logger);
+    return new GetUserInputNode(service, requiredProperties, isPropertyFulfilled, userInputProperty);
+}
+//# sourceMappingURL=factory.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/nodes/getUserInput/factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,eAAe,EAA2B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EAA2B,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAwC;IAExC,MAAM,EACJ,kBAAkB,EAClB,MAAM,EACN,eAAe,EACf,YAAY,GAAG,IAAI,qBAAqB,EAAE,EAC1C,MAAM,GAAG,qBAAqB,CAAC,kBAAkB,CAAC,EAClD,mBAAmB,GAAG,CAAC,KAAa,EAAE,YAAoB,EAA2B,EAAE;QACrF,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAC1C,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QAC/B,CAAC;QACD,OAAO;YACL,WAAW,EAAE,KAAK;YAClB,MAAM,EAAE,aAAa,YAAY,uCAAuC;SACzE,CAAC;IACJ,CAAC,EACD,iBAAiB,GAClB,GAAG,OAAO,CAAC;IAEZ,wDAAwD;IACxD,MAAM,OAAO,GACX,eAAe,IAAI,IAAI,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IAEvE,OAAO,IAAI,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,CAAC,CAAC;AACnG,CAAC"}

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

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

package/dist/nodes/getUserInput/index.js

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

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

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

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

@@ -0,0 +1,68 @@
+import { StateType, StateDefinition } from '@langchain/langgraph';
+import { BaseNode } from '../abstractBaseNode.js';
+import { PropertyMetadataCollection } from '../../common/propertyMetadata.js';
+import { IsPropertyFulfilled } from '../../common/types.js';
+import { ToolExecutor } from '../toolExecutor.js';
+import { Logger } from '../../logging/logger.js';
+import { GetInputServiceProvider } from '../../services/getInputService.js';
+/**
+ * Configuration options for creating a Get User Input Node
+ */
+export interface GetUserInputNodeOptions<TState extends StateType<StateDefinition>> {
+    /**
+     * Collection of properties that must be collected from the user
+     */
+    requiredProperties: PropertyMetadataCollection;
+    /**
+     * Tool ID for the get input tool (e.g., 'magen-get-input', 'sfmobile-native-get-input')
+     * Required if getInputService is not provided
+     */
+    toolId: string;
+    /**
+     * Service provider for getting user input (injectable for testing)
+     * If not provided, a default implementation will be created using toolId
+     */
+    getInputService?: GetInputServiceProvider;
+    /**
+     * Tool executor for services (optional, defaults to LangGraphToolExecutor)
+     */
+    toolExecutor?: ToolExecutor;
+    /**
+     * Logger instance (optional, defaults to component logger)
+     */
+    logger?: Logger;
+    /**
+     * Function to check if a property is fulfilled in the state
+     * Default: checks if property exists and is truthy
+     */
+    isPropertyFulfilled?: IsPropertyFulfilled<TState>;
+    /**
+     * Property name in state that contains user input to extract from.
+     * Must be a valid property of TState.
+     *
+     * @example
+     *
+     * // State has a 'userInput' property
+     * createGetUserInputNode({
+     *   userInputProperty: 'userInput',
+     *   ...
+     * });
+     *
+     * // State has a 'currentUtterance' property
+     * createGetUserInputNode({
+     *   userInputProperty: 'currentUtterance',
+     *   ...
+     * });
+     *
+     */
+    userInputProperty: keyof TState;
+}
+export declare class GetUserInputNode<TState extends StateType<StateDefinition>> extends BaseNode<TState> {
+    private readonly getInputService;
+    private readonly requiredProperties;
+    private readonly isPropertyFulfilled;
+    private readonly userInputProperty;
+    constructor(getInputService: GetInputServiceProvider, requiredProperties: PropertyMetadataCollection, isPropertyFulfilled: IsPropertyFulfilled<TState>, userInputProperty: keyof TState);
+    execute: (state: TState) => Partial<TState>;
+    private getUnfulfilledProperties;
+}

package/dist/nodes/getUserInput/node.js

@@ -0,0 +1,41 @@
+/*
+ * 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 GetUserInputNode extends BaseNode {
+    getInputService;
+    requiredProperties;
+    isPropertyFulfilled;
+    userInputProperty;
+    constructor(getInputService, requiredProperties, isPropertyFulfilled, userInputProperty) {
+        super('getUserInput');
+        this.getInputService = getInputService;
+        this.requiredProperties = requiredProperties;
+        this.isPropertyFulfilled = isPropertyFulfilled;
+        this.userInputProperty = userInputProperty;
+    }
+    execute = (state) => {
+        const unfulfilledProperties = this.getUnfulfilledProperties(state);
+        const userResponse = this.getInputService.getInput(unfulfilledProperties);
+        return { [this.userInputProperty]: userResponse };
+    };
+    getUnfulfilledProperties(state) {
+        const propertyArray = [];
+        for (const [propertyName, metadata] of Object.entries(this.requiredProperties)) {
+            const fulfillmentResult = this.isPropertyFulfilled(state, propertyName);
+            if (!fulfillmentResult.isFulfilled) {
+                propertyArray.push({
+                    propertyName,
+                    friendlyName: metadata.friendlyName,
+                    description: metadata.description,
+                    reason: fulfillmentResult.reason,
+                });
+            }
+        }
+        return propertyArray;
+    }
+}
+//# sourceMappingURL=node.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../../src/nodes/getUserInput/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAkElD,MAAM,OAAO,gBAA4D,SAAQ,QAAgB;IAE5E;IACA;IACA;IACA;IAJnB,YACmB,eAAwC,EACxC,kBAA8C,EAC9C,mBAAgD,EAChD,iBAA+B;QAEhD,KAAK,CAAC,cAAc,CAAC,CAAC;QALL,oBAAe,GAAf,eAAe,CAAyB;QACxC,uBAAkB,GAAlB,kBAAkB,CAA4B;QAC9C,wBAAmB,GAAnB,mBAAmB,CAA6B;QAChD,sBAAiB,GAAjB,iBAAiB,CAAc;IAGlD,CAAC;IAED,OAAO,GAAG,CAAC,KAAa,EAAmB,EAAE;QAC3C,MAAM,qBAAqB,GAAG,IAAI,CAAC,wBAAwB,CAAC,KAAK,CAAC,CAAC;QACnE,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC;QAC1E,OAAO,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,YAAY,EAAgC,CAAC;IAClF,CAAC,CAAC;IAEM,wBAAwB,CAAC,KAAa;QAC5C,MAAM,aAAa,GAAuB,EAAE,CAAC;QAC7C,KAAK,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CACnD,IAAI,CAAC,kBAAgD,CACtD,EAAE,CAAC;YACF,MAAM,iBAAiB,GAAG,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;YAExE,IAAI,CAAC,iBAAiB,CAAC,WAAW,EAAE,CAAC;gBACnC,aAAa,CAAC,IAAI,CAAC;oBACjB,YAAY;oBACZ,YAAY,EAAE,QAAQ,CAAC,YAAY;oBACnC,WAAW,EAAE,QAAQ,CAAC,WAAW;oBACjC,MAAM,EAAE,iBAAiB,CAAC,MAAM;iBACjC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,aAAa,CAAC;IACvB,CAAC;CACF"}

package/dist/nodes/index.d.ts

@@ -0,0 +1,5 @@
+export { BaseNode } from './abstractBaseNode.js';
+export { AbstractToolNode } from './abstractToolNode.js';
+export { type ToolExecutor, LangGraphToolExecutor } from './toolExecutor.js';
+export * from './getUserInput/index.js';
+export * from './userInputExtraction/index.js';

package/dist/nodes/index.js

@@ -0,0 +1,12 @@
+/*
+ * 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 { BaseNode } from './abstractBaseNode.js';
+export { AbstractToolNode } from './abstractToolNode.js';
+export { LangGraphToolExecutor } from './toolExecutor.js';
+export * from './getUserInput/index.js';
+export * from './userInputExtraction/index.js';
+//# sourceMappingURL=index.js.map

package/dist/nodes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/nodes/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAqB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC"}

package/dist/nodes/toolExecutor.d.ts

@@ -0,0 +1,22 @@
+import z from 'zod';
+import { MCPToolInvocationData } from '../common/metadata.js';
+/**
+ * Interface for tool execution mechanism.
+ * Abstracts the LangGraph interrupt mechanism to enable dependency injection and testing.
+ */
+export interface ToolExecutor {
+    /**
+     * Executes a tool by invoking the underlying mechanism (e.g., LangGraph interrupt).
+     *
+     * @param toolInvocationData The tool invocation data to pass to the execution mechanism
+     * @returns The result from the tool execution (as unknown, to be validated by caller)
+     */
+    execute(toolInvocationData: MCPToolInvocationData<z.ZodObject<z.ZodRawShape>>): unknown;
+}
+/**
+ * Production implementation of ToolExecutor that uses LangGraph's interrupt mechanism.
+ * This is the default implementation used in production workflows.
+ */
+export declare class LangGraphToolExecutor implements ToolExecutor {
+    execute(toolInvocationData: MCPToolInvocationData<z.ZodObject<z.ZodRawShape>>): unknown;
+}