@n8n/ai-workflow-builder 1.4.1 → 1.5.0

package/dist/tools/best-practices/scheduling.js

@@ -9,9 +9,9 @@ class SchedulingBestPractices {
 
 ## Workflow Design
 
-Structure scheduled workflows to perform focused, well-defined tasks. Use modular sub-workflows via Execute Workflow node for complex operations (database cleanup, report generation) to isolate failures and improve maintainability.
+Structure scheduled workflows to perform focused, well-defined tasks.
 
-For recurring tasks, use Schedule Trigger node with clear naming (e.g., "Daily 08:00 Trigger", "Every 6h Cron"). Document schedule purpose in workflow description.
+For recurring tasks, use Schedule Trigger node with clear naming (e.g., "Daily 08:00 Trigger", "Every 6h Cron").
 
 Prevent overlapping executions by ensuring worst-case execution time < schedule interval. For frequent schedules, implement mutex/lock mechanisms using external systems if needed.
 
@@ -29,66 +29,35 @@ Multiple schedules can be combined in single Schedule Trigger node using multipl
 
 ### One-Time Events
 
-For one-time future runs, use cron expression with exact date/time (e.g., \`0 12 22 10 *\` for Oct 22 at 12:00).
-IMPORTANT: Deactivate workflow after execution to prevent yearly recurrence.
+For event-relative scheduling, use Wait node to pause workflow until specified time/date.
 
-For event-relative scheduling, use Wait node to pause workflow until specified time/date. Workflow state persists across n8n restarts.
+Note: Cron expressions with specific dates (e.g., \`0 12 22 10 *\` for Oct 22 at 12:00) will repeat annually on that date.
 
 ### Conditional Scheduling
 
-Use IF/Switch nodes after Schedule Trigger for runtime conditions:
+PREFER conditional logic over complex cron expressions. Use IF/Switch nodes after Schedule Trigger for runtime conditions:
 - Check if today is last day of month before running monthly reports
-- Skip execution on holidays or based on external data
-- Route different tasks based on conditions
+- Skip execution on holidays by checking against a holiday list in a data table
+- Route to "weekday" vs "weekend" processing based on current day
 
-Better than complex cron expressions and provides flexibility for dynamic requirements.
+This approach is more readable and maintainable than complex cron patterns.
 
-## Time Zone Configuration
+## Time Zone Handling
 
-CRITICAL: Explicitly set timezone to avoid scheduling confusion.
-
-By default n8n will:
-- Attempts to detect local timezone at signup, defaults to GMT if unsure
-- Set instance timezone via Admin Panel
-- Override per-workflow as needed
-
-Schedule Trigger uses workflow timezone if set, otherwise instance timezone. Cron schedules automatically adjust for DST when using region timezones (Europe/London, America/New_York).
-
-WARNING: Wait node uses server system time, ignoring workflow timezone settings. Account for this when using Wait with specific clock times.
-
-## Error Handling & Monitoring
-
-Build robust error handling for unattended execution:
-- Use Error Trigger for global error workflow
-- Implement retry logic with Wait node for transient failures
-- Add email/Slack notifications for failures
-- Log timestamps with Console node to detect timing issues
-
-Monitor Executions list regularly for:
-- Expected trigger times
-- Duplicates or gaps
-- Failed executions
-- Long-running workflows
+When building scheduled workflows:
+- If user specifies a timezone, set it in the Schedule Trigger node's timezone parameter
+- If user mentions times without timezone, use the schedule as specified (instance default will apply)
+- For Wait nodes, be aware they use server system time, not workflow timezone
 
 ## Recommended Nodes
 
 ### Schedule Trigger (n8n-nodes-base.scheduleTrigger)
 
-Purpose: Primary node for running workflows on schedule
-
-Modes:
-- Interval: Simple recurring schedules via UI
-- Cron: Complex patterns via expressions
-
-Best Practices:
-- Activate workflow for schedule to work
-- Use descriptive names including schedule
-- Test with manual execution during development
-- Consider DST impacts for region timezones
+Primary node for running workflows on schedule. Supports interval mode for simple schedules and cron mode for complex patterns.
 
 ### Wait (n8n-nodes-base.wait)
 
-Purpose: Pause workflow execution until specified time
+Pause workflow execution until specified time or duration.
 
 Use Cases:
 - Delay actions relative to events
@@ -96,142 +65,54 @@ Use Cases:
 - Follow-up actions after specific duration
 
 Best Practices:
-- Use external database (PostgreSQL) for long waits
-- Avoid extremely long wait times
-- Remember Wait uses server time, not workflow timezone
-- State persists across n8n restarts
+- Use n8n Data Tables for waits longer than 24 hours (store scheduled time, check periodically)
+- Avoid wait times longer than 7 days - use a polling pattern instead
 
 ### IF (n8n-nodes-base.if)
 
-Purpose: Add conditional logic to scheduled workflows
+Add conditional logic to scheduled workflows.
 
 Use Cases:
-- Check date conditions (last day of month)
-- Skip execution based on external data
+- Check date conditions (last day of month using expression: \`{{ $now.day === $now.endOf('month').day }}\`)
+- Skip execution based on external data (e.g., holiday check)
 - Route to different actions conditionally
 
 Best Practices:
 - Enable "Convert types where required" for comparisons
-- Document condition logic clearly
-- Prefer IF nodes over complex cron expressions
+- Prefer IF nodes over complex cron expressions for readability
 
 ### Switch (n8n-nodes-base.switch)
 
-Purpose: Multiple conditional branches for complex routing
+Multiple conditional branches for complex routing.
 
 Use Cases:
-- Different actions based on day of week
-- Time-based routing within workflow
+- Different actions based on day of week (e.g., \`{{ $now.weekday }}\` returns 1-7)
+- Time-based routing (morning vs afternoon processing)
 - Multi-path conditional execution
 
-### Error Trigger (n8n-nodes-base.errorTrigger)
+### n8n Data Tables (n8n-nodes-base.n8nTables)
 
-Purpose: Global error handling for failed scheduled executions
+Purpose: Store scheduling state and pending tasks
 
 Use Cases:
-- Send notifications on workflow failure
-- Log errors to external systems
-- Implement global retry logic
+- Track last execution time for catch-up logic
+- Store list of pending one-time tasks with scheduled times
+- Implement custom scheduling queue with polling
 
 Best Practices:
-- Create dedicated error workflow
-- Include workflow name and timestamp in notifications
-- Consider severity levels for different failures
-
-### Execute Workflow (n8n-nodes-base.executeWorkflow)
-
-Purpose: Call sub-workflows for modular scheduling
-
-Use Cases:
-- Break complex scheduled tasks into modules
-- Reuse common scheduled operations
-- Isolate failures to specific components
-
-Best Practices:
-- Pass parameters for configuration
-- Handle sub-workflow errors appropriately
-- Use for maintainable, focused workflows
-
-### Database Nodes
-
-Purpose: Check pending tasks or store execution history
-
-- MySQL (n8n-nodes-base.mySql)
-- Postgres (n8n-nodes-base.postgres)
-- MongoDB (n8n-nodes-base.mongoDb)
-
-Use Cases:
-- Store list of pending one-time tasks
-- Log execution history
-- Implement custom scheduling queue
-
-Best Practices:
-- Query efficiently with proper indexes
-- Clean up old execution logs periodically
-- Use for dynamic scheduling requirements
-
-### HTTP Request (n8n-nodes-base.httpRequest)
-
-Purpose: Call external APIs or monitoring services
-
-Use Cases:
-- Send heartbeat to monitoring service
-- Check external conditions before execution
-- Trigger external scheduled jobs
-
-### Email/Slack
-
-- Email (n8n-nodes-base.emailSend)
-- Slack (n8n-nodes-base.slack)
-
-Purpose: Send notifications for scheduled workflow events
-
-Use Cases:
-- Daily report delivery
-- Failure notifications
-- Completion confirmations
+- Query efficiently with proper filters
+- Clean up completed tasks periodically
 
 ## Common Pitfalls to Avoid
 
-### Time Zone Mismatch
-
-**Problem**: Workflows run at wrong time due to incorrect timezone configuration. Schedule set for 08:00 runs at 07:00 or 09:00.
-
-**Solution**:
-- Explicitly set workflow or instance timezone
-- Verify timezone after DST changes
-- Use UTC for consistency if timezone complexity is problematic
-- Remember self-hosted defaults to America/New_York
-
-### Daylight Saving Time Issues
-
-**Problem**: Missed or duplicate executions during DST transitions. Jobs may not run or run twice when clocks change.
-
-**Solution**:
-- Use region timezones for automatic DST handling
-- Test critical schedules around DST dates
-- Consider fixed-offset timezone for year-round consistency
-- Update n8n version for latest timezone database
-
-### Duplicate Trigger Executions
-
-**Problem**: Workflows triggering multiple times at scheduled time, especially in multi-instance setups.
-
-**Solution**:
-- Upgrade to n8n ≥1.107.0 (fixes duplicate cron registrations)
-- Configure N8N_MULTI_MAIN_PROCESS=true for multi-instance setups
-- Disable and re-enable workflow if duplicates persist
-- Restart n8n process if issues occur after editing
-
 ### Missed Schedules During Downtime
 
 **Problem**: Scheduled runs missed when n8n instance is down. No automatic catch-up for missed triggers.
 
-**Solution**:
-- Ensure high availability for critical schedules
-- Design idempotent workflows that check for missed work
-- Use daily check pattern instead of exact timing when possible
-- Implement external monitoring for uptime
+**Solution**: Design idempotent workflows with catch-up logic:
+- Store last successful run timestamp in n8n Data Tables
+- On each run, check if enough time has passed since last run
+- Example: For a task that should run once per 24 hours, schedule it every 4 hours but only execute if last run was >20 hours ago
 
 ### Overlapping Executions
 
@@ -239,9 +120,8 @@ Use Cases:
 
 **Solution**:
 - Increase interval to exceed worst-case execution time
-- Implement mutex/lock using database or external system
+- Implement mutex/lock using n8n Data Tables (check/set "running" flag at start, clear at end)
 - Add execution check at workflow start
-- Configure single worker for workflow in queue mode
 
 ### Wait Node Timezone Confusion
 
@@ -249,8 +129,7 @@ Use Cases:
 
 **Solution**:
 - Account for server timezone when setting Wait times
-- Use UTC timestamps for clarity
-- Run server in target timezone if possible
+- Use relative durations (e.g., "wait 2 hours") instead of absolute times when possible
 - Prefer Schedule Trigger for timezone-aware scheduling
 
 ### First Execution Timing
@@ -258,20 +137,14 @@ Use Cases:
 **Problem**: First execution after activation doesn't match expected schedule. Activation time affects next run calculation.
 
 **Solution**:
-- Plan activation timing carefully
-- Use manual execution for immediate first run
+- Use manual execution for immediate first run if needed
 - Understand that schedule recalculates from activation moment
-- Document expected first run time
 
-### Cron Syntax Errors
+### Cron Syntax
 
-**Problem**: Invalid cron expression prevents trigger activation. Missing fields or incorrect format causes silent failures.
+n8n supports both 5-field and 6-field (with seconds) cron syntax. Use 6 fields if you want to specify seconds (e.g., prefix with 0 for seconds: \`0 0 9 * * *\` for 9 AM daily).
 
-**Solution**:
-- Use crontab.guru to validate expressions
-- Remember n8n supports 5 or 6 field syntax
-- n8n supports both 5-field and 6-field (with seconds) cron syntax; use 6 fields if you want to specify seconds (e.g., prefix with 0 for seconds: \`0 0 * * * *\`)
-- Use interval mode for simple schedules
+For simple schedules, prefer Interval mode over cron for better readability.
 `;
     getDocumentation() {
         return this.documentation;

package/dist/tools/best-practices/scheduling.js.map

@@ -1 +1 @@
-{"version":3,"file":"scheduling.js","sourceRoot":"","sources":["../../../src/tools/best-practices/scheduling.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,uBAAuB;IAC1B,SAAS,GAAG,kCAAiB,CAAC,UAAU,CAAC;IACzC,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2QjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AApRD,0DAoRC"}
+{"version":3,"file":"scheduling.js","sourceRoot":"","sources":["../../../src/tools/best-practices/scheduling.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,uBAAuB;IAC1B,SAAS,GAAG,kCAAiB,CAAC,UAAU,CAAC;IACzC,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4IjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AArJD,0DAqJC"}

package/dist/tools/builder-tools.d.ts

@@ -1,15 +1,6 @@
-import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { Logger } from '@n8n/backend-common';
 import type { INodeTypeDescription } from 'n8n-workflow';
-import type { BuilderTool, BuilderToolBase } from '../utils/stream-processor';
+import type { BuilderToolBase } from '../utils/stream-processor';
 import type { BuilderFeatureFlags } from '../workflow-builder-agent';
-export declare function getBuilderTools({ parsedNodeTypes, logger, llmComplexTask, instanceUrl, featureFlags, }: {
-    parsedNodeTypes: INodeTypeDescription[];
-    llmComplexTask: BaseChatModel;
-    logger?: Logger;
-    instanceUrl?: string;
-    featureFlags?: BuilderFeatureFlags;
-}): BuilderTool[];
 export declare function getBuilderToolsForDisplay({ nodeTypes, featureFlags, }: {
     nodeTypes: INodeTypeDescription[];
     featureFlags?: BuilderFeatureFlags;

package/dist/tools/builder-tools.js

@@ -1,36 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBuilderTools = getBuilderTools;
 exports.getBuilderToolsForDisplay = getBuilderToolsForDisplay;
 const add_node_tool_1 = require("./add-node.tool");
-const categorize_prompt_tool_1 = require("./categorize-prompt.tool");
 const connect_nodes_tool_1 = require("./connect-nodes.tool");
-const get_best_practices_tool_1 = require("./get-best-practices.tool");
+const get_documentation_tool_1 = require("./get-documentation.tool");
 const get_node_parameter_tool_1 = require("./get-node-parameter.tool");
 const get_workflow_examples_tool_1 = require("./get-workflow-examples.tool");
 const node_details_tool_1 = require("./node-details.tool");
 const node_search_tool_1 = require("./node-search.tool");
 const remove_connection_tool_1 = require("./remove-connection.tool");
 const remove_node_tool_1 = require("./remove-node.tool");
+const rename_node_tool_1 = require("./rename-node.tool");
 const update_node_parameters_tool_1 = require("./update-node-parameters.tool");
-const validate_workflow_tool_1 = require("./validate-workflow.tool");
-function getBuilderTools({ parsedNodeTypes, logger, llmComplexTask, instanceUrl, featureFlags, }) {
-    const tools = [
-        (0, categorize_prompt_tool_1.createCategorizePromptTool)(llmComplexTask, logger),
-        (0, get_best_practices_tool_1.createGetBestPracticesTool)(),
-    ];
-    if (featureFlags?.templateExamples === true) {
-        tools.push((0, get_workflow_examples_tool_1.createGetWorkflowExamplesTool)(logger));
-    }
-    tools.push((0, node_search_tool_1.createNodeSearchTool)(parsedNodeTypes), (0, node_details_tool_1.createNodeDetailsTool)(parsedNodeTypes, logger), (0, add_node_tool_1.createAddNodeTool)(parsedNodeTypes), (0, connect_nodes_tool_1.createConnectNodesTool)(parsedNodeTypes, logger), (0, remove_connection_tool_1.createRemoveConnectionTool)(logger), (0, remove_node_tool_1.createRemoveNodeTool)(logger), (0, update_node_parameters_tool_1.createUpdateNodeParametersTool)(parsedNodeTypes, llmComplexTask, logger, instanceUrl), (0, get_node_parameter_tool_1.createGetNodeParameterTool)(), (0, validate_workflow_tool_1.createValidateWorkflowTool)(parsedNodeTypes, logger));
-    return tools;
-}
+const validate_configuration_tool_1 = require("./validate-configuration.tool");
+const validate_structure_tool_1 = require("./validate-structure.tool");
 function getBuilderToolsForDisplay({ nodeTypes, featureFlags, }) {
-    const tools = [categorize_prompt_tool_1.CATEGORIZE_PROMPT_TOOL, get_best_practices_tool_1.GET_BEST_PRACTICES_TOOL];
+    const tools = [get_documentation_tool_1.GET_DOCUMENTATION_TOOL];
     if (featureFlags?.templateExamples === true) {
         tools.push(get_workflow_examples_tool_1.GET_WORKFLOW_EXAMPLES_TOOL);
     }
-    tools.push(node_search_tool_1.NODE_SEARCH_TOOL, node_details_tool_1.NODE_DETAILS_TOOL, (0, add_node_tool_1.getAddNodeToolBase)(nodeTypes), connect_nodes_tool_1.CONNECT_NODES_TOOL, remove_connection_tool_1.REMOVE_CONNECTION_TOOL, remove_node_tool_1.REMOVE_NODE_TOOL, update_node_parameters_tool_1.UPDATING_NODE_PARAMETER_TOOL, get_node_parameter_tool_1.GET_NODE_PARAMETER_TOOL, validate_workflow_tool_1.VALIDATE_WORKFLOW_TOOL);
+    tools.push(node_search_tool_1.NODE_SEARCH_TOOL, node_details_tool_1.NODE_DETAILS_TOOL, (0, add_node_tool_1.getAddNodeToolBase)(nodeTypes), connect_nodes_tool_1.CONNECT_NODES_TOOL, remove_connection_tool_1.REMOVE_CONNECTION_TOOL, remove_node_tool_1.REMOVE_NODE_TOOL, rename_node_tool_1.RENAME_NODE_TOOL, update_node_parameters_tool_1.UPDATING_NODE_PARAMETER_TOOL, get_node_parameter_tool_1.GET_NODE_PARAMETER_TOOL, validate_structure_tool_1.VALIDATE_STRUCTURE_TOOL, validate_configuration_tool_1.VALIDATE_CONFIGURATION_TOOL);
     return tools;
 }
 //# sourceMappingURL=builder-tools.js.map

package/dist/tools/builder-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"builder-tools.js","sourceRoot":"","sources":["../../src/tools/builder-tools.ts"],"names":[],"mappings":";;AA0BA,0CAsCC;AAOD,8DA6BC;AA7FD,mDAAwE;AACxE,qEAA8F;AAC9F,6DAAkF;AAClF,uEAAgG;AAChG,uEAAgG;AAChG,6EAGsC;AACtC,2DAA+E;AAC/E,yDAA4E;AAC5E,qEAA8F;AAC9F,yDAA4E;AAC5E,+EAGuC;AACvC,qEAA8F;AAE9F,SAAgB,eAAe,CAAC,EAC/B,eAAe,EACf,MAAM,EACN,cAAc,EACd,WAAW,EACX,YAAY,GAOZ;IACA,MAAM,KAAK,GAAkB;QAC5B,IAAA,mDAA0B,EAAC,cAAc,EAAE,MAAM,CAAC;QAClD,IAAA,oDAA0B,GAAE;KAC5B,CAAC;IAIF,IAAI,YAAY,EAAE,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,IAAA,0DAA6B,EAAC,MAAM,CAAC,CAAC,CAAC;IACnD,CAAC;IAGD,KAAK,CAAC,IAAI,CACT,IAAA,uCAAoB,EAAC,eAAe,CAAC,EACrC,IAAA,yCAAqB,EAAC,eAAe,EAAE,MAAM,CAAC,EAC9C,IAAA,iCAAiB,EAAC,eAAe,CAAC,EAClC,IAAA,2CAAsB,EAAC,eAAe,EAAE,MAAM,CAAC,EAC/C,IAAA,mDAA0B,EAAC,MAAM,CAAC,EAClC,IAAA,uCAAoB,EAAC,MAAM,CAAC,EAC5B,IAAA,4DAA8B,EAAC,eAAe,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,CAAC,EACpF,IAAA,oDAA0B,GAAE,EAC5B,IAAA,mDAA0B,EAAC,eAAe,EAAE,MAAM,CAAC,CACnD,CAAC;IAEF,OAAO,KAAK,CAAC;AACd,CAAC;AAOD,SAAgB,yBAAyB,CAAC,EACzC,SAAS,EACT,YAAY,GAIZ;IACA,MAAM,KAAK,GAAsB,CAAC,+CAAsB,EAAE,iDAAuB,CAAC,CAAC;IAInF,IAAI,YAAY,EAAE,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,uDAA0B,CAAC,CAAC;IACxC,CAAC;IAGD,KAAK,CAAC,IAAI,CACT,mCAAgB,EAChB,qCAAiB,EACjB,IAAA,kCAAkB,EAAC,SAAS,CAAC,EAC7B,uCAAkB,EAClB,+CAAsB,EACtB,mCAAgB,EAChB,0DAA4B,EAC5B,iDAAuB,EACvB,+CAAsB,CACtB,CAAC;IAEF,OAAO,KAAK,CAAC;AACd,CAAC"}
+{"version":3,"file":"builder-tools.js","sourceRoot":"","sources":["../../src/tools/builder-tools.ts"],"names":[],"mappings":";;AAwBA,8DA+BC;AAlDD,mDAAqD;AACrD,6DAA0D;AAC1D,qEAAkE;AAClE,uEAAoE;AACpE,6EAA0E;AAC1E,2DAAwD;AACxD,yDAAsD;AACtD,qEAAkE;AAClE,yDAAsD;AACtD,yDAAsD;AACtD,+EAA6E;AAC7E,+EAA4E;AAC5E,uEAAoE;AAOpE,SAAgB,yBAAyB,CAAC,EACzC,SAAS,EACT,YAAY,GAIZ;IACA,MAAM,KAAK,GAAsB,CAAC,+CAAsB,CAAC,CAAC;IAI1D,IAAI,YAAY,EAAE,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,uDAA0B,CAAC,CAAC;IACxC,CAAC;IAGD,KAAK,CAAC,IAAI,CACT,mCAAgB,EAChB,qCAAiB,EACjB,IAAA,kCAAkB,EAAC,SAAS,CAAC,EAC7B,uCAAkB,EAClB,+CAAsB,EACtB,mCAAgB,EAChB,mCAAgB,EAChB,0DAA4B,EAC5B,iDAAuB,EACvB,iDAAuB,EACvB,yDAA2B,CAC3B,CAAC;IAEF,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/tools/get-documentation.tool.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import type { BuilderToolBase } from '../utils/stream-processor';
+export declare const DocumentationType: {
+    readonly BEST_PRACTICES: "best_practices";
+    readonly NODE_RECOMMENDATIONS: "node_recommendations";
+};
+export declare const GET_DOCUMENTATION_TOOL: BuilderToolBase;
+export declare function createGetDocumentationTool(): {
+    toolName: string;
+    displayTitle: string;
+    getCustomDisplayTitle?: (values: Record<string, unknown>) => string;
+    tool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        requests: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"best_practices">;
+            techniques: z.ZodArray<z.ZodNativeEnum<{
+                readonly SCHEDULING: "scheduling";
+                readonly CHATBOT: "chatbot";
+                readonly FORM_INPUT: "form_input";
+                readonly SCRAPING_AND_RESEARCH: "scraping_and_research";
+                readonly MONITORING: "monitoring";
+                readonly ENRICHMENT: "enrichment";
+                readonly TRIAGE: "triage";
+                readonly CONTENT_GENERATION: "content_generation";
+                readonly DOCUMENT_PROCESSING: "document_processing";
+                readonly DATA_EXTRACTION: "data_extraction";
+                readonly DATA_ANALYSIS: "data_analysis";
+                readonly DATA_TRANSFORMATION: "data_transformation";
+                readonly DATA_PERSISTENCE: "data_persistence";
+                readonly NOTIFICATION: "notification";
+                readonly KNOWLEDGE_BASE: "knowledge_base";
+                readonly HUMAN_IN_THE_LOOP: "human_in_the_loop";
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            type: "best_practices";
+            techniques: ("scheduling" | "chatbot" | "form_input" | "scraping_and_research" | "monitoring" | "enrichment" | "triage" | "content_generation" | "document_processing" | "data_extraction" | "data_analysis" | "data_transformation" | "data_persistence" | "notification" | "knowledge_base" | "human_in_the_loop")[];
+        }, {
+            type: "best_practices";
+            techniques: ("scheduling" | "chatbot" | "form_input" | "scraping_and_research" | "monitoring" | "enrichment" | "triage" | "content_generation" | "document_processing" | "data_extraction" | "data_analysis" | "data_transformation" | "data_persistence" | "notification" | "knowledge_base" | "human_in_the_loop")[];
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"node_recommendations">;
+            categories: z.ZodArray<z.ZodNativeEnum<{
+                readonly TEXT_MANIPULATION: "text_manipulation";
+                readonly IMAGE_GENERATION: "image_generation";
+                readonly VIDEO_GENERATION: "video_generation";
+                readonly AUDIO_GENERATION: "audio_generation";
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            type: "node_recommendations";
+            categories: ("image_generation" | "text_manipulation" | "video_generation" | "audio_generation")[];
+        }, {
+            type: "node_recommendations";
+            categories: ("image_generation" | "text_manipulation" | "video_generation" | "audio_generation")[];
+        }>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        requests: ({
+            type: "best_practices";
+            techniques: ("scheduling" | "chatbot" | "form_input" | "scraping_and_research" | "monitoring" | "enrichment" | "triage" | "content_generation" | "document_processing" | "data_extraction" | "data_analysis" | "data_transformation" | "data_persistence" | "notification" | "knowledge_base" | "human_in_the_loop")[];
+        } | {
+            type: "node_recommendations";
+            categories: ("image_generation" | "text_manipulation" | "video_generation" | "audio_generation")[];
+        })[];
+    }, {
+        requests: ({
+            type: "best_practices";
+            techniques: ("scheduling" | "chatbot" | "form_input" | "scraping_and_research" | "monitoring" | "enrichment" | "triage" | "content_generation" | "document_processing" | "data_extraction" | "data_analysis" | "data_transformation" | "data_persistence" | "notification" | "knowledge_base" | "human_in_the_loop")[];
+        } | {
+            type: "node_recommendations";
+            categories: ("image_generation" | "text_manipulation" | "video_generation" | "audio_generation")[];
+        })[];
+    }>, unknown, {
+        requests: ({
+            type: "best_practices";
+            techniques: ("scheduling" | "chatbot" | "form_input" | "scraping_and_research" | "monitoring" | "enrichment" | "triage" | "content_generation" | "document_processing" | "data_extraction" | "data_analysis" | "data_transformation" | "data_persistence" | "notification" | "knowledge_base" | "human_in_the_loop")[];
+        } | {
+            type: "node_recommendations";
+            categories: ("image_generation" | "text_manipulation" | "video_generation" | "audio_generation")[];
+        })[];
+    }, import("@langchain/langgraph").Command<unknown, Record<string, unknown>, string>>;
+};

package/dist/tools/get-documentation.tool.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET_DOCUMENTATION_TOOL = exports.DocumentationType = void 0;
+exports.createGetDocumentationTool = createGetDocumentationTool;
+const tools_1 = require("@langchain/core/tools");
+const zod_1 = require("zod");
+const errors_1 = require("../errors");
+const builder_1 = require("../prompts/builder");
+const node_recommendations_1 = require("../prompts/shared/node-recommendations");
+const best_practices_1 = require("../tools/best-practices");
+const progress_1 = require("../tools/helpers/progress");
+const response_1 = require("../tools/helpers/response");
+const categorization_1 = require("../types/categorization");
+const node_recommendations_2 = require("../types/node-recommendations");
+exports.DocumentationType = {
+    BEST_PRACTICES: 'best_practices',
+    NODE_RECOMMENDATIONS: 'node_recommendations',
+};
+const bestPracticesRequestSchema = zod_1.z.object({
+    type: zod_1.z.literal(exports.DocumentationType.BEST_PRACTICES),
+    techniques: zod_1.z
+        .array(zod_1.z.nativeEnum(categorization_1.WorkflowTechnique))
+        .min(1)
+        .describe('Workflow techniques to get best practices for'),
+});
+const nodeRecommendationsRequestSchema = zod_1.z.object({
+    type: zod_1.z.literal(exports.DocumentationType.NODE_RECOMMENDATIONS),
+    categories: zod_1.z
+        .array(zod_1.z.nativeEnum(node_recommendations_2.RecommendationCategory))
+        .min(1)
+        .describe('Task categories to get node recommendations for'),
+});
+const getDocumentationSchema = zod_1.z.object({
+    requests: zod_1.z
+        .array(zod_1.z.union([bestPracticesRequestSchema, nodeRecommendationsRequestSchema]))
+        .min(1)
+        .describe('Array of documentation requests to retrieve'),
+});
+function formatBestPractices(techniques) {
+    const foundDocs = [];
+    for (const technique of techniques) {
+        const doc = best_practices_1.documentation[technique];
+        if (doc) {
+            foundDocs.push(doc.getDocumentation());
+        }
+    }
+    if (foundDocs.length === 0) {
+        return '';
+    }
+    return (0, builder_1.prompt)().section('best_practices', foundDocs.join('\n---\n')).build();
+}
+function formatCategory(category, content) {
+    return (0, builder_1.prompt)().section(category, content).build();
+}
+function formatNodeRecommendations(categories) {
+    const foundRecs = [];
+    for (const category of categories) {
+        const rec = node_recommendations_1.recommendations[category];
+        if (rec) {
+            foundRecs.push(formatCategory(category, (0, node_recommendations_1.formatRecommendation)(rec.recommendation)));
+        }
+    }
+    if (foundRecs.length === 0) {
+        return '';
+    }
+    return (0, builder_1.prompt)().section('node_recommendations', foundRecs.join('\n')).build();
+}
+exports.GET_DOCUMENTATION_TOOL = {
+    toolName: 'get_documentation',
+    displayTitle: 'Getting documentation',
+};
+function createGetDocumentationTool() {
+    const dynamicTool = (0, tools_1.tool)((input, config) => {
+        const reporter = (0, progress_1.createProgressReporter)(config, exports.GET_DOCUMENTATION_TOOL.toolName, exports.GET_DOCUMENTATION_TOOL.displayTitle);
+        try {
+            const validatedInput = getDocumentationSchema.parse(input);
+            const { requests } = validatedInput;
+            reporter.start(validatedInput);
+            reporter.progress(`Processing ${requests.length} documentation request(s)...`);
+            const results = [];
+            let bestPracticesContent;
+            const allTechniques = [];
+            for (const request of requests) {
+                if (request.type === exports.DocumentationType.BEST_PRACTICES) {
+                    const { techniques } = request;
+                    const availableDocs = techniques.filter((t) => best_practices_1.documentation[t]);
+                    if (availableDocs.length > 0) {
+                        const content = formatBestPractices(techniques);
+                        results.push(content);
+                        bestPracticesContent = content;
+                        allTechniques.push(...techniques);
+                    }
+                }
+                else {
+                    const { categories } = request;
+                    const availableRecs = categories.filter((c) => node_recommendations_1.recommendations[c]);
+                    if (availableRecs.length > 0) {
+                        results.push(formatNodeRecommendations(categories));
+                    }
+                }
+            }
+            if (results.length === 0) {
+                const message = 'No documentation available for the requested items.';
+                reporter.complete({ requests: requests.length, found: 0 });
+                return (0, response_1.createSuccessResponse)(config, message);
+            }
+            const message = results.join('\n\n');
+            reporter.complete({ requests: requests.length, found: results.length });
+            const stateUpdates = {};
+            if (bestPracticesContent) {
+                stateUpdates.bestPractices = bestPracticesContent;
+                stateUpdates.techniqueCategories = allTechniques;
+            }
+            return (0, response_1.createSuccessResponse)(config, message, Object.keys(stateUpdates).length > 0 ? stateUpdates : undefined);
+        }
+        catch (error) {
+            if (error instanceof zod_1.z.ZodError) {
+                const validationError = new errors_1.ValidationError('Invalid input parameters', {
+                    extra: { errors: error.errors },
+                });
+                reporter.error(validationError);
+                return (0, response_1.createErrorResponse)(config, validationError);
+            }
+            const toolError = new errors_1.ToolExecutionError(error instanceof Error ? error.message : 'Unknown error occurred', {
+                toolName: exports.GET_DOCUMENTATION_TOOL.toolName,
+                cause: error instanceof Error ? error : undefined,
+            });
+            reporter.error(toolError);
+            return (0, response_1.createErrorResponse)(config, toolError);
+        }
+    }, {
+        name: exports.GET_DOCUMENTATION_TOOL.toolName,
+        description: `Retrieve documentation to guide workflow building.
+
+TYPE: best_practices
+Use when you need guidance on workflow patterns and implementation.
+Requires: techniques array (workflow techniques to get practices for)
+Returns: Best practices including recommended nodes, common pitfalls, performance tips.
+
+TYPE: node_recommendations
+Use when user wants AI capabilities but doesn't specify exact nodes/providers.
+Requires: categories array (task categories to get recommendations for)
+Returns: Default node recommendations with alternatives.
+
+Do NOT use node_recommendations when:
+- User explicitly names a provider (e.g., "use Claude", "with OpenAI", "using Gemini")
+- User specifies exact node names
+
+Available techniques for best_practices:
+- trigger, loop, branch, subroutine, pagination, parallel_execution, error_handling, scheduling, rate_limiting, batch_processing, ai_agent, ai_chain, rag, data_transformation, http_request
+
+Available categories for node_recommendations:
+- text_manipulation: summarization, analysis, extraction, classification, chat
+- image_generation: generate, analyze, edit images
+- video_generation: create videos from text/images
+- audio_generation: text-to-speech, transcription, translation`,
+        schema: getDocumentationSchema,
+    });
+    return {
+        tool: dynamicTool,
+        ...exports.GET_DOCUMENTATION_TOOL,
+    };
+}
+//# sourceMappingURL=get-documentation.tool.js.map

package/dist/tools/get-documentation.tool.js.map

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

package/dist/tools/helpers/state.d.ts

@@ -12,3 +12,4 @@ export declare function removeNodesFromWorkflow(nodeIds: string[]): Partial<type
 export declare function updateNodeInWorkflow(state: typeof WorkflowState.State, nodeId: string, updates: Partial<INode>): Partial<typeof WorkflowState.State>;
 export declare function addConnectionToWorkflow(sourceNodeId: string, _targetNodeId: string, connection: IConnection): Partial<typeof WorkflowState.State>;
 export declare function removeConnectionFromWorkflow(sourceNode: string, targetNode: string, connectionType: string, sourceOutputIndex: number, targetInputIndex: number): Partial<typeof WorkflowState.State>;
+export declare function renameNodeInWorkflow(nodeId: string, oldName: string, newName: string): Partial<typeof WorkflowState.State>;