Frontend (n8n Editor UI)
         ↓
AI Workflow Builder Service (TypeScript)
         ↓
LangGraph State Machine
         ↓
Claude Sonnet 4 (via API Proxy)
         ↓
n8n Node Type System

┌─────────────────────────────────────────────────────────────┐
│                    User Interface                            │
│  (Chat panel in n8n Editor)                                 │
└─────────────────────┬───────────────────────────────────────┘
                      │ HTTP/SSE Streaming
                      ↓
┌─────────────────────────────────────────────────────────────┐
│         AI Workflow Builder Service                          │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         LangGraph State Machine                      │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │   │
│  │  │  Agent   │→ │  Tools   │→ │ Process Ops Node │  │   │
│  │  └──────────┘  └──────────┘  └──────────────────┘  │   │
│  │       ↑              │                  │            │   │
│  │       └──────────────┴──────────────────┘            │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              7 Builder Tools                         │   │
│  │  • search_nodes      • add_nodes                     │   │
│  │  • get_node_details  • connect_nodes                 │   │
│  │  • update_node_parameters  • remove_node             │   │
│  │  • get_node_parameter                                │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         Operations Processor                         │   │
│  │  (Applies queued mutations to workflow state)        │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ↓
┌─────────────────────────────────────────────────────────────┐
│              AI Assistant SDK Proxy                          │
│  (Routes to Anthropic, handles auth, metering)              │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ↓
              Claude Sonnet 4
         (claude-sonnet-4-20250514)

packages/@n8n/ai-workflow-builder.ee/
├── src/
│   ├── chains/                    # LLM chains for specialized tasks
│   │   ├── conversation-compact.ts
│   │   ├── parameter-updater.ts
│   │   ├── workflow-name.ts
│   │   └── prompts/
│   │       ├── base/              # Core system prompts
│   │       ├── examples/          # Node-specific examples
│   │       ├── node-types/
│   │       └── parameter-types/
│   │
│   ├── tools/                     # The 7 builder tools
│   │   ├── add-node.tool.ts
│   │   ├── connect-nodes.tool.ts
│   │   ├── get-node-parameter.tool.ts
│   │   ├── node-details.tool.ts
│   │   ├── node-search.tool.ts
│   │   ├── remove-node.tool.ts
│   │   ├── update-node-parameters.tool.ts
│   │   ├── builder-tools.ts       # Tool factory
│   │   ├── engines/               # Pure business logic
│   │   ├── helpers/               # Shared utilities
│   │   ├── prompts/               # Tool-specific prompts
│   │   └── utils/                 # Data transformation
│   │
│   ├── database/
│   ├── evaluations/               # Testing framework
│   ├── errors/
│   ├── types/
│   ├── utils/
│   │   ├── operations-processor.ts  # State mutation engine
│   │   ├── stream-processor.ts     # Real-time updates
│   │   ├── tool-executor.ts        # Parallel execution
│   │   └── trim-workflow-context.ts # Token optimization
│   │
│   ├── ai-workflow-builder-agent.service.ts  # Main service
│   ├── session-manager.service.ts
│   ├── workflow-builder-agent.ts   # LangGraph workflow
│   ├── workflow-state.ts           # State definition
│   ├── llm-config.ts               # Model configurations
│   └── constants.ts
│
├── evaluations/                   # Evaluation framework
└── test/

┌──────────────────────────────────────────────────────────────┐
│ 1. USER INPUT                                                 │
│    User: "Create a workflow that fetches weather data"       │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ↓
┌──────────────────────────────────────────────────────────────┐
│ 2. FRONTEND REQUEST                                           │
│    POST /api/ai-workflow-builder/chat                        │
│    {                                                          │
│      message: "Create a workflow...",                        │
│      workflowContext: { currentWorkflow, executionData }     │
│    }                                                          │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ↓
┌──────────────────────────────────────────────────────────────┐
│ 3. SERVICE INITIALIZATION                                     │
│    AiWorkflowBuilderService.chat()                           │
│    ├─ Setup Claude Sonnet 4 via AI Assistant SDK            │
│    ├─ Initialize session checkpointer (MemorySaver)         │
│    ├─ Create WorkflowBuilderAgent with 7 tools              │
│    └─ Start LangGraph stream                                 │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ↓
┌──────────────────────────────────────────────────────────────┐
│ 4. LANGGRAPH STATE MACHINE                                    │
│                                                               │
│    START                                                      │
│      ↓                                                        │
│    ┌─────────────────┐                                       │
│    │ shouldModifyState?                                      │
│    └────┬───────┬────┘                                       │
│         │       │                                             │
│    [compact] [create_name]  [agent]                          │
│         │       │              ↓                              │
│         │       │         ┌──────────┐                       │
│         │       │         │  Agent   │ (LLM call)            │
│         │       │         │  Node    │                       │
│         │       │         └────┬─────┘                       │
│         │       │              │                              │
│         │       │         shouldContinue?                     │
│         │       │              │                              │
│         │       │         [tools] [END]                       │
│         │       │              │                              │
│         │       │         ┌──────────┐                       │
│         │       │         │  Tools   │ (parallel execution)  │
│         │       │         │  Node    │                       │
│         │       │         └────┬─────┘                       │
│         │       │              │                              │
│         │       │         ┌──────────────────┐               │
│         │       │         │ Process Ops Node │               │
│         │       │         │ (Apply mutations) │               │
│         │       │         └────┬─────────────┘               │
│         │       │              │                              │
│         │       └──────────────┴──────────┐                  │
│         └──────────────────────────────────┘                 │
│                                             ↓                 │
│                                         Back to Agent         │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ↓
┌──────────────────────────────────────────────────────────────┐
│ 5. TOOL EXECUTION (Parallel)                                  │
│                                                               │
│    Promise.all([                                             │
│      search_nodes({queries: [...]}),                         │
│      get_node_details({nodeName: "..."}),                    │
│      // More tools...                                        │
│    ])                                                         │
│                                                               │
│    Each tool returns:                                        │
│    {                                                          │
│      messages: [ToolMessage],                                │
│      workflowOperations: [Operation]                         │
│    }                                                          │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ↓
┌──────────────────────────────────────────────────────────────┐
│ 6. OPERATIONS PROCESSING                                      │
│                                                               │
│    Collected operations from all tools:                      │
│    [                                                          │
│      { type: 'addNodes', nodes: [...] },                     │
│      { type: 'mergeConnections', connections: {...} },       │
│      { type: 'updateNode', nodeId, updates: {...} }          │
│    ]                                                          │
│                                                               │
│    applyOperations(currentWorkflow, operations)              │
│    → Returns updated workflow JSON                           │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ↓
┌──────────────────────────────────────────────────────────────┐
│ 7. STREAMING RESPONSE                                         │
│                                                               │
│    Stream chunks to frontend:                                │
│    {                                                          │
│      messages: [{                                            │
│        role: "assistant",                                    │
│        type: "tool" | "message" | "workflow-updated",        │
│        text: "Adding HTTP Request node..."                   │
│      }]                                                       │
│    }                                                          │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ↓
┌──────────────────────────────────────────────────────────────┐
│ 8. FRONTEND UPDATE                                            │
│    - Updates canvas with new nodes                           │
│    - Shows progress messages in chat                         │
│    - Enables "Save Workflow" button                          │
│    - User saves via standard n8n API (POST /api/workflows)   │
└──────────────────────────────────────────────────────────────┘

// Frontend sends
POST /api/ai-workflow-builder/chat
{
  message: "Create a workflow that sends daily weather reports",
  workflowContext: {
    currentWorkflow: {
      nodes: [],
      connections: {},
      name: ""
    },
    executionSchema: [],
    executionData: null
  }
}

// AiWorkflowBuilderService.chat()
async *chat(payload: ChatPayload, user: IUser, abortSignal?: AbortSignal) {
  // 1. Setup models (Claude via AI Assistant SDK)
  const { anthropicClaude, tracingClient } = await this.setupModels(user);

  // 2. Create agent with tools
  const agent = new WorkflowBuilderAgent({
    parsedNodeTypes: this.parsedNodeTypes,
    llmSimpleTask: anthropicClaude,
    llmComplexTask: anthropicClaude,
    checkpointer: this.sessionManager.getCheckpointer(),
    tracer: tracingClient,
    instanceUrl: this.instanceUrl
  });

  // 3. Stream outputs
  for await (const output of agent.chat(payload, user.id, abortSignal)) {
    yield output;  // Streams to frontend
  }
}

// WorkflowBuilderAgent.chat()
async *chat(payload: ChatPayload, userId: string, abortSignal?: AbortSignal) {
  const workflow = this.createWorkflow();  // LangGraph

  const config: RunnableConfig = {
    configurable: {
      thread_id: `workflow-${workflowId}-user-${userId}`
    },
    signal: abortSignal
  };

  const stream = workflow.stream(
    { messages: [new HumanMessage(payload.message)] },
    { ...config, streamMode: ['updates', 'custom'] as const }
  );

  // Process and yield formatted chunks
  for await (const output of createStreamProcessor(stream)) {
    yield output;
  }
}

// executeToolsInParallel()
const toolResults = await Promise.all(
  aiMessage.tool_calls.map(async (toolCall) => {
    const tool = toolMap.get(toolCall.name);
    return await tool.invoke(toolCall.args);
  })
);

// Collect all operations
const allOperations: WorkflowOperation[] = [];
for (const update of stateUpdates) {
  if (update.workflowOperations) {
    allOperations.push(...update.workflowOperations);
  }
}

return {
  messages: allMessages,
  workflowOperations: allOperations
};

// processOperations()
export function processOperations(state: WorkflowState) {
  const { workflowJSON, workflowOperations } = state;

  if (!workflowOperations || workflowOperations.length === 0) {
    return {};
  }

  // Apply all operations sequentially
  const newWorkflow = applyOperations(workflowJSON, workflowOperations);

  return {
    workflowJSON: newWorkflow,
    workflowOperations: null  // Clear queue
  };
}

// Stream processor yields chunks
{
  messages: [{
    role: "assistant",
    type: "tool",
    toolName: "add_nodes",
    displayTitle: "Adding HTTP Request node",
    status: "in_progress"
  }]
}

// Later...
{
  messages: [{
    role: "assistant",
    type: "workflow-updated",
    codeSnippet: JSON.stringify(updatedWorkflow, null, 2)
  }]
}

// Finally...
{
  messages: [{
    role: "assistant",
    type: "message",
    text: "**⚙️ How to Setup**\n1. Configure API credentials\n..."
  }]
}

interface AiAssistantClient {
  // Authentication
  getBuilderApiProxyToken(user: IUser): Promise<{
    tokenType: string,
    accessToken: string
  }>;

  // API Proxy
  getApiProxyBaseUrl(): string;
  // Returns: "https://ai-assistant.n8n.io/api/v1"

  // Metering
  markBuilderSuccess(user: IUser, authHeaders): Promise<{
    creditsQuota: number,
    creditsClaimed: number
  }>;

  getBuilderInstanceCredits(user: IUser): Promise<{
    creditsQuota: number,
    creditsClaimed: number
  }>;
}

// Anthropic requests
baseUrl + '/anthropic'
// Routes to: https://ai-assistant.n8n.io/api/v1/anthropic

// Langsmith tracing
baseUrl + '/langsmith'
// Routes to: https://ai-assistant.n8n.io/api/v1/langsmith

1. User makes request
2. Service calls getBuilderApiProxyToken(user)
3. SDK returns JWT access token
4. Service adds Authorization header to all LLM requests
5. Proxy validates token and routes to Anthropic
6. Response streams back through proxy

const workflow = new StateGraph(WorkflowState)
  .addNode('agent', callModel)
  .addNode('tools', customToolExecutor)
  .addNode('process_operations', processOperations)
  .addNode('delete_messages', deleteMessages)
  .addNode('compact_messages', compactSession)
  .addNode('auto_compact_messages', compactSession)
  .addNode('create_workflow_name', createWorkflowName)

  // Conditional routing
  .addConditionalEdges('__start__', shouldModifyState, {
    'compact_messages': 'compact_messages',
    'auto_compact_messages': 'auto_compact_messages',
    'delete_messages': 'delete_messages',
    'create_workflow_name': 'create_workflow_name',
    'agent': 'agent'
  })

  .addConditionalEdges('agent', shouldContinue, {
    'tools': 'tools',
    [END]: END
  })

  .addEdge('tools', 'process_operations')
  .addEdge('process_operations', 'agent')
  .addEdge('compact_messages', 'agent')
  .addEdge('auto_compact_messages', 'agent')
  .addEdge('delete_messages', END)
  .addEdge('create_workflow_name', 'agent');

function shouldModifyState(state: WorkflowState) {
  const lastMessage = state.messages.findLast(m => m instanceof HumanMessage);

  if (lastMessage.content === '/compact') return 'compact_messages';
  if (lastMessage.content === '/clear') return 'delete_messages';

  // Auto-generate name for new workflows
  if (state.workflowContext?.currentWorkflow?.nodes?.length === 0
      && state.messages.length === 1) {
    return 'create_workflow_name';
  }

  // Auto-compact when token usage exceeds threshold
  if (shouldAutoCompact(state)) {
    return 'auto_compact_messages';
  }

  return 'agent';
}

function shouldContinue(state: WorkflowState) {
  const lastMessage = state.messages[state.messages.length - 1];

  if (lastMessage.tool_calls?.length) {
    return 'tools';
  }

  // Success callback
  if (this.onGenerationSuccess) {
    void Promise.resolve(this.onGenerationSuccess());
  }

  return END;
}

export const WorkflowState = Annotation.Root({
  // Conversation history
  messages: Annotation<BaseMessage[]>({
    reducer: messagesStateReducer,
    default: () => []
  }),

  // Current workflow JSON
  workflowJSON: Annotation<SimpleWorkflow>({
    reducer: (x, y) => y ?? x,
    default: () => ({ nodes: [], connections: {}, name: '' })
  }),

  // Queued operations
  workflowOperations: Annotation<WorkflowOperation[] | null>({
    reducer: operationsReducer,  // Accumulates operations
    default: () => []
  }),

  // Execution context
  workflowContext: Annotation<ChatPayload['workflowContext']>({
    reducer: (x, y) => y ?? x
  }),

  // Compressed history
  previousSummary: Annotation<string>({
    reducer: (x, y) => y ?? x,
    default: () => 'EMPTY'
  })
});

function operationsReducer(
  current: WorkflowOperation[],
  update: WorkflowOperation[]
): WorkflowOperation[] {
  if (update === null) return [];  // Clear
  if (!update || update.length === 0) return current ?? [];

  // Clear operations reset everything
  if (update.some(op => op.type === 'clear')) {
    return update.filter(op => op.type === 'clear').slice(-1);
  }

  // Otherwise, accumulate
  return [...(current ?? []), ...update];
}

class SessionManagerService {
  private checkpointer: MemorySaver;

  // Generate unique thread ID per workflow+user
  static generateThreadId(workflowId?: string, userId?: string): string {
    return workflowId
      ? `workflow-${workflowId}-user-${userId ?? Date.now()}`
      : crypto.randomUUID();
  }

  // Retrieve conversation history
  async getSessions(workflowId: string, userId: string) {
    const threadId = this.generateThreadId(workflowId, userId);
    const checkpoint = await this.checkpointer.getTuple({
      configurable: { thread_id: threadId }
    });

    if (checkpoint?.checkpoint) {
      return {
        sessionId: threadId,
        messages: formatMessages(checkpoint.checkpoint.channel_values?.messages),
        lastUpdated: checkpoint.checkpoint.ts
      };
    }

    return { sessions: [] };
  }
}

// Constants
const MAX_TOTAL_TOKENS = 200_000;        // Claude's context window
const MAX_OUTPUT_TOKENS = 16_000;         // Reserved for response
const MAX_INPUT_TOKENS = 184_000;         // 200k - 16k - 10k buffer
const DEFAULT_AUTO_COMPACT_THRESHOLD = 20_000;  // Auto-compress trigger
const MAX_WORKFLOW_LENGTH_TOKENS = 30_000;  // Workflow JSON limit
const MAX_PARAMETER_VALUE_LENGTH = 30_000;  // Single parameter limit

// Token estimation
function estimateTokenCountFromMessages(messages: BaseMessage[]): number {
  const totalChars = messages.reduce((sum, msg) => {
    return sum + JSON.stringify(msg.content).length;
  }, 0);

  return Math.ceil(totalChars / AVG_CHARS_PER_TOKEN_ANTHROPIC);
}

// Workflow trimming
function trimWorkflowJSON(workflow: SimpleWorkflow): SimpleWorkflow {
  const estimatedTokens = estimateTokens(JSON.stringify(workflow));

  if (estimatedTokens > MAX_WORKFLOW_LENGTH_TOKENS) {
    return {
      ...workflow,
      nodes: workflow.nodes.map(node => ({
        ...node,
        parameters: trimLargeParameters(node.parameters)
      }))
    };
  }

  return workflow;
}

Total Context Window: 200,000 tokens
├─ System Prompt: ~8,000 tokens (cached)
├─ Node Definitions: ~5,000 tokens (cached, varies)
├─ Workflow JSON: Up to 30,000 tokens (trimmed)
├─ Execution Data: ~2,000 tokens
├─ Previous Summary: ~1,000 tokens (after compact)
├─ Conversation History: ~20,000 tokens (trigger compact)
└─ Reserved for Output: 16,000 tokens
    Total Input: ~184,000 tokens maximum

{
  queries: Array<{
    queryType: 'name' | 'subNodeSearch',
    query?: string,
    connectionType?: NodeConnectionType
  }>
}

// Name-based search
{
  queries: [{
    queryType: "name",
    query: "http"
  }]
}

// Sub-node search
{
  queries: [{
    queryType: "subNodeSearch",
    connectionType: "ai_languageModel"
  }]
}

// Combined search
{
  queries: [
    { queryType: "name", query: "gmail" },
    { queryType: "subNodeSearch", connectionType: "ai_tool", query: "calculator" }
  ]
}

class NodeSearchEngine {
  searchByName(query: string, limit: number = 5): NodeSearchResult[] {
    const normalizedQuery = query.toLowerCase();
    const results: NodeSearchResult[] = [];

    for (const nodeType of this.nodeTypes) {
      let score = 0;

      // Exact matches (highest weight)
      if (nodeType.name.toLowerCase() === normalizedQuery) {
        score += SCORE_WEIGHTS.NAME_EXACT;  // 20
      }
      if (nodeType.displayName.toLowerCase() === normalizedQuery) {
        score += SCORE_WEIGHTS.DISPLAY_NAME_EXACT;  // 15
      }

      // Partial matches
      if (nodeType.name.toLowerCase().includes(normalizedQuery)) {
        score += SCORE_WEIGHTS.NAME_CONTAINS;  // 10
      }
      if (nodeType.displayName.toLowerCase().includes(normalizedQuery)) {
        score += SCORE_WEIGHTS.DISPLAY_NAME_CONTAINS;  // 8
      }
      if (nodeType.codex?.alias?.some(a => a.toLowerCase().includes(normalizedQuery))) {
        score += SCORE_WEIGHTS.ALIAS_CONTAINS;  // 8
      }
      if (nodeType.description?.toLowerCase().includes(normalizedQuery)) {
        score += SCORE_WEIGHTS.DESCRIPTION_CONTAINS;  // 5
      }

      if (score > 0) {
        results.push({ ...nodeType, score });
      }
    }

    return results.sort((a, b) => b.score - a.score).slice(0, limit);
  }

  searchByConnectionType(
    connectionType: NodeConnectionType,
    limit: number = 5,
    nameFilter?: string
  ): NodeSearchResult[] {
    const results: NodeSearchResult[] = [];

    for (const nodeType of this.nodeTypes) {
      let score = 0;

      // Check if node outputs this connection type
      if (Array.isArray(nodeType.outputs)) {
        if (nodeType.outputs.includes(connectionType)) {
          score += SCORE_WEIGHTS.CONNECTION_EXACT;  // 100
        }
      } else if (typeof nodeType.outputs === 'string') {
        if (nodeType.outputs.includes(connectionType)) {
          score += SCORE_WEIGHTS.CONNECTION_IN_EXPRESSION;  // 50
        }
      }

      // Apply optional name filter
      if (nameFilter && score > 0) {
        const nameScore = this.calculateNameScore(nodeType, nameFilter);
        score += nameScore;
      }

      if (score > 0) {
        results.push({ ...nodeType, score });
      }
    }

    return results.sort((a, b) => b.score - a.score).slice(0, limit);
  }
}

Found 3 nodes matching "http":
<node>
  <node_name>n8n-nodes-base.httpRequest</node_name>
  <node_description>Makes HTTP requests to URLs</node_description>
  <node_inputs>["main"]</node_inputs>
  <node_outputs>["main"]</node_outputs>
</node>
<node>
  <node_name>n8n-nodes-base.httpBinTrigger</node_name>
  <node_description>Triggers on HTTP webhooks</node_description>
  <node_inputs>[]</node_inputs>
  <node_outputs>["main"]</node_outputs>
</node>

{
  nodeName: string,           // Full type: "n8n-nodes-base.httpRequest"
  withParameters?: boolean,    // Default: false
  withConnections?: boolean    // Default: true
}

// Fast: connections only
{
  nodeName: "n8n-nodes-base.httpRequest",
  withConnections: true
}

// Complete: including parameters
{
  nodeName: "n8n-nodes-base.set",
  withParameters: true,
  withConnections: true
}

<node_details>
  <name>n8n-nodes-base.httpRequest</name>
  <display_name>HTTP Request</display_name>
  <description>Makes HTTP requests to retrieve data</description>
  <subtitle>={{ $parameter["method"] + ": " + $parameter["url"] }}</subtitle>

  <!-- Only if withParameters: true -->
  <properties>
    [
      {
        "name": "method",
        "type": "options",
        "options": [
          { "name": "GET", "value": "GET" },
          { "name": "POST", "value": "POST" },
          ...
        ],
        "default": "GET"
      },
      {
        "name": "url",
        "type": "string",
        "default": "",
        "required": true
      },
      ...
    ]
  </properties>

  <connections>
    <input>main</input>
    <output>main</output>
  </connections>
</node_details>

// AI workflow: Discovery → Details → Addition
1. search_nodes({queries: [{queryType: "name", query: "http"}]})
   → Returns: n8n-nodes-base.httpRequest

2. get_node_details({nodeName: "n8n-nodes-base.httpRequest"})
   → Understands: inputs=["main"], outputs=["main"]

3. add_nodes({
     nodeType: "n8n-nodes-base.httpRequest",
     connectionParametersReasoning: "HTTP Request has static connections",
     connectionParameters: {}
   })

{
  nodeType: string,
  name: string,
  connectionParametersReasoning: string,  // ⭐ REQUIRED
  connectionParameters: object
}

// Vector Store - Dynamic inputs based on mode
{
  nodeType: "@n8n/n8n-nodes-langchain.vectorStoreInMemory",
  name: "Store Embeddings",
  connectionParametersReasoning: "Vector Store mode determines inputs. Using 'insert' to accept document loader connections",
  connectionParameters: {
    mode: "insert"  // Enables ai_document input
  }
}

// AI Agent - Output parser support
{
  nodeType: "@n8n/n8n-nodes-langchain.agent",
  name: "Research Agent",
  connectionParametersReasoning: "AI Agent needs output parser for structured responses",
  connectionParameters: {
    hasOutputParser: true  // Adds ai_outputParser input
  }
}

// Document Loader - Text splitting mode
{
  nodeType: "@n8n/n8n-nodes-langchain.documentDefaultDataLoader",
  name: "PDF Loader",
  connectionParametersReasoning: "Document Loader with custom text splitting to accept splitter connections",
  connectionParameters: {
    textSplittingMode: "custom",  // Enables ai_textSplitter input
    dataType: "binary"  // Process files instead of JSON
  }
}

// HTTP Request - Static connections
{
  nodeType: "n8n-nodes-base.httpRequest",
  name: "Fetch Weather Data",
  connectionParametersReasoning: "HTTP Request has static inputs/outputs, no special parameters needed",
  connectionParameters: {}
}

function createNode(
  nodeType: INodeTypeDescription,
  customName: string,
  existingNodes: INode[],
  nodeTypes: INodeTypeDescription[],
  connectionParameters?: INodeParameters
): INode {
  // 1. Generate unique name
  const baseName = customName ?? nodeType.defaults?.name ?? nodeType.displayName;
  const uniqueName = generateUniqueName(baseName, existingNodes);
  // "HTTP Request" → "HTTP Request 2" if collision

  // 2. Calculate position
  const isSubNodeType = isSubNode(nodeType);
  const position = calculateNodePosition(existingNodes, isSubNodeType, nodeTypes);
  // Sub-nodes: [x, y + 200]  (below main nodes)
  // Main nodes: [lastX + 240, y]  (flow left-to-right)

  // 3. Create instance
  return {
    id: crypto.randomUUID(),
    name: uniqueName,
    type: nodeType.name,
    typeVersion: nodeType.version,
    position,
    parameters: {
      ...nodeType.defaults?.parameters,
      ...connectionParameters  // Override defaults
    }
  };
}

function calculateNodePosition(
  existingNodes: INode[],
  isSubNode: boolean,
  nodeTypes: INodeTypeDescription[]
): [number, number] {
  if (existingNodes.length === 0) {
    return [240, 300];  // First node position
  }

  if (isSubNode) {
    // Sub-nodes positioned below main flow
    const mainNodes = existingNodes.filter(n => {
      const type = nodeTypes.find(nt => nt.name === n.type);
      return !isSubNode(type);
    });

    const avgX = mainNodes.reduce((sum, n) => sum + n.position[0], 0) / mainNodes.length;
    return [avgX, 600];  // Below main nodes
  }

  // Main nodes: continue the flow
  const lastNode = existingNodes[existingNodes.length - 1];
  return [lastNode.position[0] + 240, lastNode.position[1]];
}

{
  workflowOperations: [{
    type: 'addNodes',
    nodes: [{
      id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      name: "Fetch Weather Data",
      type: "n8n-nodes-base.httpRequest",
      typeVersion: 4.2,
      position: [240, 300],
      parameters: {}  // connectionParameters merged with defaults
    }]
  }],
  messages: [
    new ToolMessage({
      content: 'Successfully added "Fetch Weather Data" (HTTP Request) with ID a1b2c3d4...',
      tool_call_id: "call_xyz"
    })
  ]
}

{
  sourceNodeId: string,        // For ai_*: should be sub-node
  targetNodeId: string,        // For ai_*: should be main node
  sourceOutputIndex?: number,  // Default: 0
  targetInputIndex?: number    // Default: 0
}

function inferConnectionType(
  sourceNode: INode,
  targetNode: INode,
  sourceNodeType: INodeTypeDescription,
  targetNodeType: INodeTypeDescription
): InferConnectionTypeResult {
  // 1. Extract possible output types from source
  const sourceOutputTypes = extractConnectionTypes(sourceNodeType.outputs);
  // ["main", "ai_tool"]

  // 2. Extract possible input types from target
  const targetInputTypes = extractConnectionTypes(targetNodeType.inputs);
  // ["main", "ai_tool", "ai_languageModel"]

  // 3. Find intersection
  const compatibleTypes = sourceOutputTypes.filter(type =>
    targetInputTypes.includes(type)
  );

  if (compatibleTypes.length === 0) {
    return {
      error: "No compatible connection types found",
      possibleTypes: { source: sourceOutputTypes, target: targetInputTypes }
    };
  }

  if (compatibleTypes.length > 1) {
    return {
      error: "Multiple connection types possible. Please specify.",
      possibleTypes: compatibleTypes
    };
  }

  const connectionType = compatibleTypes[0];

  // 4. For AI connections, validate sub-node is source
  if (connectionType.startsWith('ai_')) {
    const sourceIsSubNode = isSubNode(sourceNodeType, sourceNode);
    const targetIsSubNode = isSubNode(targetNodeType, targetNode);

    if (!sourceIsSubNode && !targetIsSubNode) {
      return { error: "AI connections require a sub-node" };
    }

    if (targetIsSubNode && !sourceIsSubNode) {
      // Wrong direction! Swap them
      return {
        connectionType,
        requiresSwap: true
      };
    }
  }

  return { connectionType };
}

function extractConnectionTypesFromExpression(expression: string): string[] {
  const types = new Set<string>();

  // Pattern 1: type: "ai_tool"
  const pattern1 = /type\s*:\s*["']([^"']+)["']/g;

  // Pattern 2: type: NodeConnectionTypes.AiTool
  const pattern2 = /type\s*:\s*NodeConnectionTypes\.(\w+)/g;

  // Pattern 3: ["main", "ai_tool"]
  const pattern3 = /\[\s*["'](\w+)["']/g;

  // Apply all patterns
  for (const pattern of [pattern1, pattern2, pattern3]) {
    let match;
    while ((match = pattern.exec(expression)) !== null) {
      types.add(match[1]);
    }
  }

  return Array.from(types);
}

// User incorrectly specifies:
connect_nodes({
  sourceNodeId: "ai-agent-123",      // Main node
  targetNodeId: "openai-model-456"   // Sub-node
})

// Tool detects:
sourceIsSubNode = false
targetIsSubNode = true
connectionType = "ai_languageModel"

// Tool auto-swaps:
actualSource = "openai-model-456"  // Sub-node becomes source
actualTarget = "ai-agent-123"      // Main node becomes target
swapped = true

// Creates correct connection:
{
  "OpenAI Chat Model": {
    "ai_languageModel": [[{
      node: "AI Agent",
      type: "ai_languageModel",
      index: 0
    }]]
  }
}

function validateConnection(
  sourceNode: INode,
  targetNode: INode,
  connectionType: string,
  nodeTypes: INodeTypeDescription[]
): ConnectionValidationResult {
  const sourceType = findNodeType(sourceNode.type, nodeTypes);
  const targetType = findNodeType(targetNode.type, nodeTypes);

  // Validate source has output type
  if (!nodeHasOutputType(sourceType, connectionType)) {
    return {
      valid: false,
      error: `Source node "${sourceNode.name}" doesn't output ${connectionType}`
    };
  }

  // Validate target accepts input type
  if (!nodeAcceptsInputType(targetType, connectionType)) {
    return {
      valid: false,
      error: `Target node "${targetNode.name}" doesn't accept ${connectionType}`
    };
  }

  return { valid: true };
}

{
  workflowOperations: [{
    type: 'mergeConnections',
    connections: {
      "OpenAI Chat Model": {
        "ai_languageModel": [[{
          node: "AI Agent",
          type: "ai_languageModel",
          index: 0
        }]]
      }
    }
  }],
  messages: [
    new ToolMessage({
      content: 'Connected "OpenAI Chat Model" to "AI Agent" via ai_languageModel (swapped for correct direction)',
      tool_call_id: "call_abc"
    })
  ]
}

{
  nodeId: string,
  changes: string[]  // Natural language instructions
}

// HTTP Request configuration
{
  nodeId: "http-node-123",
  changes: [
    "Set the URL to https://api.weather.com/v1/forecast",
    "Set method to POST",
    "Add header Content-Type with value application/json",
    "Set body to { city: {{ $json.city }} }"
  ]
}

// Set node configuration
{
  nodeId: "set-node-456",
  changes: [
    "Add field 'status' with value 'processed'",
    "Add field 'timestamp' with current date",
    "Add field 'userId' from previous HTTP Request node"
  ]
}

// Tool node with $fromAI
{
  nodeId: "gmail-tool-789",
  changes: [
    "Set sendTo to {{ $fromAI('to') }}",
    "Set subject to {{ $fromAI('subject') }}",
    "Set message to {{ $fromAI('message_html') }}"
  ]
}

async function processParameterUpdates(
  node: INode,
  nodeType: INodeTypeDescription,
  nodeId: string,
  changes: string[],
  state: WorkflowState,
  llm: BaseChatModel
): Promise<INodeParameters> {
  // 1. Extract current parameters
  const currentParameters = node.parameters;

  // 2. Build dynamic prompt
  const promptBuilder = new ParameterUpdatePromptBuilder();
  const systemPrompt = promptBuilder.buildSystemPrompt({
    nodeType: node.type,
    nodeDefinition: nodeType,
    requestedChanges: changes,
    hasResourceLocatorParams: promptBuilder.hasResourceLocatorParameters(nodeType)
  });

  // 3. Create LLM chain with structured output
  const parametersSchema = z.object({
    parameters: z.object({}).passthrough()
  });

  const chain = createParameterUpdaterChain(llm, systemPrompt);

  // 4. Invoke LLM
  const result = await chain.invoke({
    workflow_json: trimWorkflowJSON(state.workflowJSON),
    execution_data: state.workflowContext?.executionData,
    execution_schema: state.workflowContext?.executionSchema,
    node_id: nodeId,
    node_name: node.name,
    node_type: node.type,
    current_parameters: JSON.stringify(currentParameters, null, 2),
    node_definition: JSON.stringify(nodeType.properties, null, 2),
    changes: formatChangesForPrompt(changes)
  });

  // 5. Fix expression prefixes
  const fixedParameters = fixExpressionPrefixes(result.parameters);

  return fixedParameters;
}

class ParameterUpdatePromptBuilder {
  buildSystemPrompt(context: {
    nodeType: string,
    nodeDefinition: INodeTypeDescription,
    requestedChanges: string[],
    hasResourceLocatorParams: boolean
  }): string {
    let prompt = CORE_INSTRUCTIONS;

    // Add node-type-specific examples
    const nodeCategory = this.getNodeTypeCategory(context.nodeType);

    if (nodeCategory === 'set') {
      prompt += SET_NODE_EXAMPLES;
    } else if (nodeCategory === 'if') {
      prompt += IF_NODE_EXAMPLES;
    } else if (nodeCategory === 'httpRequest') {
      prompt += HTTP_REQUEST_EXAMPLES;
    } else if (nodeCategory === 'tool') {
      prompt += TOOL_NODE_EXAMPLES;
      prompt += FROMAIEXPRESSIONS;
    }

    // Add resource locator examples if needed
    if (context.hasResourceLocatorParams) {
      prompt += RESOURCE_LOCATOR_EXAMPLES;
    }

    // Add expression rules if text fields present
    if (this.hasTextFields(context.nodeDefinition)) {
      prompt += EXPRESSION_RULES;
    }

    prompt += OUTPUT_FORMAT;

    return prompt;
  }

  getNodeTypeCategory(nodeType: string): string {
    if (nodeType.includes('.set')) return 'set';
    if (nodeType.includes('.if')) return 'if';
    if (nodeType.includes('.httpRequest')) return 'httpRequest';
    if (nodeType.endsWith('Tool')) return 'tool';
    return 'generic';
  }
}

function fixExpressionPrefixes(parameters: any): any {
  if (typeof parameters === 'string') {
    // Fix common mistakes:
    // "{{ $json.field }}"  →  "={{ $json.field }}"
    // "{ $json.field }"    →  "={{ $json.field }}"

    if (parameters.match(/^\s*\{\{.*\}\}\s*$/)) {
      // Has {{ }} but missing =
      return '=' + parameters;
    }

    if (parameters.match(/^\s*\{[^{].*\}\s*$/)) {
      // Has single { } - should be {{ }}
      return '=' + parameters.replace(/^\s*\{/, '{{').replace(/\}\s*$/, '}}');
    }

    return parameters;
  }

  if (Array.isArray(parameters)) {
    return parameters.map(fixExpressionPrefixes);
  }

  if (typeof parameters === 'object' && parameters !== null) {
    const fixed: any = {};
    for (const [key, value] of Object.entries(parameters)) {
      fixed[key] = fixExpressionPrefixes(value);
    }
    return fixed;
  }

  return parameters;
}

CORE_INSTRUCTIONS:
You are an expert n8n workflow architect who updates node parameters...

SET_NODE_EXAMPLES:
### Example 1: Simple String Assignment
Current Parameters: {}
Requested Changes: Set message to "Hello World"
Expected Output:
{
  "parameters": {
    "assignments": {
      "assignments": [{
        "id": "id-1",
        "name": "message",
        "value": "Hello World",
        "type": "string"
      }]
    }
  }
}
...

CORE_INSTRUCTIONS:
...

TOOL_NODE_EXAMPLES:
### Example 1: Gmail Tool - Send Email with AI
Current Parameters: {}
Requested Changes: Let AI determine recipient, subject, and message
Expected Output:
{
  "parameters": {
    "sendTo": "={{ $fromAI('to') }}",
    "subject": "={{ $fromAI('subject') }}",
    "message": "={{ $fromAI('message_html') }}"
  }
}
...

FROMAIEXPRESSIONS:
## CRITICAL: $fromAI Expression Support
Tool nodes support special $fromAI expressions that allow AI to dynamically fill parameters...

{
  workflowOperations: [{
    type: 'updateNode',
    nodeId: "http-node-123",
    updates: {
      parameters: {
        method: "POST",
        url: "https://api.weather.com/v1/forecast",
        sendHeaders: true,
        headerParameters: {
          parameters: [{
            name: "Content-Type",
            value: "application/json"
          }]
        },
        sendBody: true,
        bodyParameters: {
          parameters: [{
            name: "city",
            value: "={{ $json.city }}"
          }]
        }
      }
    }
  }],
  messages: [
    new ToolMessage({
      content: 'Successfully updated parameters for node "HTTP Request":\n- Set URL to https://api.weather.com...',
      tool_call_id: "call_def"
    })
  ]
}

{
  nodeId: string
}

function removeNode(nodeId: string, workflow: SimpleWorkflow) {
  // 1. Count connections to be removed
  let connectionsRemoved = 0;

  // Outgoing connections
  if (workflow.connections[nodeId]) {
    for (const outputs of Object.values(workflow.connections[nodeId])) {
      if (Array.isArray(outputs)) {
        for (const conns of outputs) {
          connectionsRemoved += conns.length;
        }
      }
    }
  }

  // Incoming connections
  for (const [sourceId, nodeConns] of Object.entries(workflow.connections)) {
    for (const outputs of Object.values(nodeConns)) {
      if (Array.isArray(outputs)) {
        for (const conns of outputs) {
          connectionsRemoved += conns.filter(c => c.node === nodeId).length;
        }
      }
    }
  }

  return { connectionsRemoved };
}

// In operations-processor.ts
case 'removeNode': {
  const nodesToRemove = new Set(operation.nodeIds);

  // Filter out nodes
  result.nodes = result.nodes.filter(n => !nodesToRemove.has(n.id));

  // Clean connections
  const cleanedConnections: IConnections = {};

  for (const [sourceId, nodeConns] of Object.entries(result.connections)) {
    // Skip if source is removed
    if (nodesToRemove.has(sourceId)) continue;

    cleanedConnections[sourceId] = {};

    for (const [type, outputs] of Object.entries(nodeConns)) {
      if (Array.isArray(outputs)) {
        cleanedConnections[sourceId][type] = outputs.map(conns =>
          // Filter out connections to removed nodes
          conns.filter(c => !nodesToRemove.has(c.node))
        );
      }
    }
  }

  result.connections = cleanedConnections;
  break;
}

{
  nodeId: string,
  path: string  // Lodash path syntax
}

// Simple path
{
  nodeId: "http-node-123",
  path: "url"
}
// Returns: "https://api.example.com"

// Nested path
{
  nodeId: "http-node-123",
  path: "headerParameters.parameters[0].value"
}
// Returns: "application/json"

// Options path
{
  nodeId: "set-node-456",
  path: "options.includeOtherFields"
}
// Returns: true

import get from 'lodash/get';

function extractParameterValue(
  node: INode,
  path: string
): NodeParameterValueType | undefined {
  return get(node.parameters, path);
}

const MAX_PARAMETER_VALUE_LENGTH = 30_000;

if (formattedValue.length > MAX_PARAMETER_VALUE_LENGTH) {
  throw new ValidationError(
    `Parameter value at path "${path}" exceeds maximum length of ${MAX_PARAMETER_VALUE_LENGTH} characters`
  );
}

function trimWorkflowJSON(workflow: SimpleWorkflow): SimpleWorkflow {
  return {
    ...workflow,
    nodes: workflow.nodes.map(node => ({
      ...node,
      parameters: trimLargeParameters(node.parameters)
    }))
  };
}

function trimLargeParameters(params: any): any {
  if (typeof params === 'string' && params.length > 1000) {
    return '<value omitted - use get_node_parameter tool>';
  }
  // Recursively trim nested objects/arrays
  ...
}

// Workflow JSON shows: "body": "<value omitted - use get_node_parameter tool>"
// AI calls:
get_node_parameter({
  nodeId: "http-node-123",
  path: "body"
})
// Returns full value

type WorkflowOperation =
  | { type: 'clear' }
  | { type: 'removeNode'; nodeIds: string[] }
  | { type: 'addNodes'; nodes: INode[] }
  | { type: 'updateNode'; nodeId: string; updates: Partial<INode> }
  | { type: 'setConnections'; connections: IConnections }
  | { type: 'mergeConnections'; connections: IConnections }
  | { type: 'setName'; name: string };

export function processOperations(state: WorkflowState): Partial<WorkflowState> {
  const { workflowJSON, workflowOperations } = state;

  if (!workflowOperations || workflowOperations.length === 0) {
    return {};
  }

  // Apply all operations sequentially
  const newWorkflow = applyOperations(workflowJSON, workflowOperations);

  return {
    workflowJSON: newWorkflow,
    workflowOperations: null  // Clear queue
  };
}

export function applyOperations(
  workflow: SimpleWorkflow,
  operations: WorkflowOperation[]
): SimpleWorkflow {
  let result = {
    nodes: [...workflow.nodes],
    connections: { ...workflow.connections },
    name: workflow.name || ''
  };

  for (const operation of operations) {
    switch (operation.type) {
      case 'clear':
        result = { nodes: [], connections: {}, name: '' };
        break;

      case 'addNodes': {
        const nodeMap = new Map(result.nodes.map(n => [n.id, n]));
        operation.nodes.forEach(node => nodeMap.set(node.id, node));
        result.nodes = Array.from(nodeMap.values());
        break;
      }

      case 'updateNode': {
        result.nodes = result.nodes.map(node =>
          node.id === operation.nodeId
            ? { ...node, ...operation.updates }
            : node
        );
        break;
      }

      case 'removeNode': {
        const nodesToRemove = new Set(operation.nodeIds);
        result.nodes = result.nodes.filter(n => !nodesToRemove.has(n.id));

        // Clean connections
        const cleanedConnections: IConnections = {};
        for (const [sourceId, nodeConns] of Object.entries(result.connections)) {
          if (!nodesToRemove.has(sourceId)) {
            cleanedConnections[sourceId] = {};
            for (const [type, outputs] of Object.entries(nodeConns)) {
              if (Array.isArray(outputs)) {
                cleanedConnections[sourceId][type] = outputs.map(conns =>
                  conns.filter(c => !nodesToRemove.has(c.node))
                );
              }
            }
          }
        }
        result.connections = cleanedConnections;
        break;
      }

      case 'setConnections': {
        result.connections = operation.connections;
        break;
      }

      case 'mergeConnections': {
        for (const [sourceId, nodeConns] of Object.entries(operation.connections)) {
          if (!result.connections[sourceId]) {
            result.connections[sourceId] = nodeConns;
          } else {
            for (const [type, newOutputs] of Object.entries(nodeConns)) {
              if (!result.connections[sourceId][type]) {
                result.connections[sourceId][type] = newOutputs;
              } else {
                // Deep merge arrays, avoid duplicates
                const existing = result.connections[sourceId][type];
                if (Array.isArray(newOutputs) && Array.isArray(existing)) {
                  for (let i = 0; i < Math.max(newOutputs.length, existing.length); i++) {
                    if (!newOutputs[i]) continue;
                    if (!existing[i]) {
                      existing[i] = newOutputs[i];
                    } else {
                      // Merge connections, check duplicates
                      const existingSet = new Set(
                        existing[i].map(c => JSON.stringify(c))
                      );
                      newOutputs[i].forEach(conn => {
                        const key = JSON.stringify(conn);
                        if (!existingSet.has(key)) {
                          existing[i].push(conn);
                        }
                      });
                    }
                  }
                }
              }
            }
          }
        }
        break;
      }

      case 'setName': {
        result.name = operation.name;
        break;
      }
    }
  }

  return result;
}

┌─────────────────────────────────────────────┐
│ Agent returns 3 tool calls:                 │
│ 1. add_nodes (HTTP Request)                 │
│ 2. add_nodes (Set)                          │
│ 3. connect_nodes (HTTP → Set)               │
└──────────────────┬──────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────┐
│ executeToolsInParallel()                    │
│                                             │
│ Promise.all([                               │
│   addNodesTool.invoke({...}),  // Returns: │
│     → { workflowOperations: [{            │
│         type: 'addNodes',                  │
│         nodes: [httpNode]                  │
│       }]}                                   │
│                                             │
│   addNodesTool.invoke({...}),  // Returns: │
│     → { workflowOperations: [{            │
│         type: 'addNodes',                  │
│         nodes: [setNode]                   │
│       }]}                                   │
│                                             │
│   connectNodesTool.invoke({...}) // Returns:│
│     → { workflowOperations: [{            │
│         type: 'mergeConnections',          │
│         connections: {...}                 │
│       }]}                                   │
│ ])                                          │
└──────────────────┬──────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────┐
│ Collect all operations:                     │
│ [                                           │
│   { type: 'addNodes', nodes: [httpNode] }, │
│   { type: 'addNodes', nodes: [setNode] },  │
│   { type: 'mergeConnections', ... }        │
│ ]                                           │
└──────────────────┬──────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────┐
│ Return to LangGraph:                        │
│ {                                           │
│   messages: [ToolMessage, ...],             │
│   workflowOperations: [...]                 │
│ }                                           │
└──────────────────┬──────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────┐
│ Graph transitions to process_operations     │
│                                             │
│ applyOperations(workflow, operations)       │
│   → Processes operations sequentially       │
│   → Returns updated workflow                │
└──────────────────┬──────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────┐
│ Updated state:                              │
│ {                                           │
│   workflowJSON: { nodes: [http, set], ... }│
│   workflowOperations: null                  │
│ }                                           │
└─────────────────────────────────────────────┘

// Instead of:
function addNode(node: INode) {
  workflow.nodes.push(node);  // ❌ Direct mutation
}

// Use:
function addNode(node: INode) {
  return {
    workflowOperations: [{
      type: 'addNodes',
      nodes: [node]
    }]
  };  // ✅ Return command
}

// helpers/state.ts
export function getCurrentWorkflow(state: WorkflowState): SimpleWorkflow {
  return state.workflowJSON;
}

export function addNodeToWorkflow(node: INode): Partial<WorkflowState> {
  return {
    workflowOperations: [{ type: 'addNodes', nodes: [node] }]
  };
}

export function createAddNodeTool(nodeTypes: INodeTypeDescription[]): BuilderTool {
  const dynamicTool = tool(
    (input, config) => { /* implementation */ },
    {
      name: 'add_nodes',
      description: '...',
      schema: nodeCreationSchema
    }
  );

  return {
    tool: dynamicTool,
    toolName: 'add_nodes',
    displayTitle: 'Adding nodes'
  };
}

buildSystemPrompt(context) {
  let prompt = CORE_INSTRUCTIONS;

  if (isSetNode) prompt += SET_NODE_EXAMPLES;
  else if (isIfNode) prompt += IF_NODE_EXAMPLES;
  else if (isToolNode) prompt += TOOL_NODE_EXAMPLES;

  return prompt;
}

tool((input, config) => {
  const reporter = createProgressReporter(config);

  try {
    const validated = schema.parse(input);
    reporter.start(validated);

    // Business logic here

    reporter.complete(output);
    return createSuccessResponse(config, message, stateUpdates);
  } catch (error) {
    reporter.error(error);
    return createErrorResponse(config, error);
  }
})

reporter.start(input);      // → Frontend: "Starting..."
reporter.progress("...");   // → Frontend: "In progress..."
reporter.complete(output);  // → Frontend: "Complete!"
reporter.error(error);      // → Frontend: "Error!"

class NodeSearchEngine {
  searchByName(query, limit): NodeSearchResult[]
  searchByConnectionType(type, limit, filter): NodeSearchResult[]
}

let prompt = CORE_INSTRUCTIONS;
prompt += nodeTypeExamples;
if (hasResourceLocator) prompt += RESOURCE_LOCATOR_EXAMPLES;
if (hasTextFields) prompt += EXPRESSION_RULES;
prompt += OUTPUT_FORMAT;

const llm = new ChatAnthropic({...});
const llmWithStructure = llm.withStructuredOutput(parametersSchema);

Input → Zod Schema → Business Logic → Semantic Validation → Operations Processor

const checkpoint = await checkpointer.getTuple(config);
// Later: restore from checkpoint

class SessionManagerService {
  private checkpointer: MemorySaver;

  getCheckpointer(): MemorySaver {
    return this.checkpointer;
  }
}

isSubNode(nodeType, node) → boolean
nodeHasOutputType(nodeType, connectionType) → boolean
nodeAcceptsInputType(nodeType, connectionType) → boolean

workflowOperations: Annotation<WorkflowOperation[] | null>({
  reducer: operationsReducer,
  default: () => []  // Not null
});

Service → SDK → AI Assistant Proxy → Anthropic

const mainAgentPrompt = ChatPromptTemplate.fromMessages([
  ['system', [
    { type: 'text', text: systemPrompt },           // Cached
    { type: 'text', text: instanceUrlPrompt },
    { type: 'text', text: currentWorkflowJson },
    { type: 'text', text: currentExecutionData },
    { type: 'text', text: currentExecutionNodesSchemas },
    { type: 'text', text: responsePatterns },       // Cached
    { type: 'text', text: previousConversationSummary }  // Cached
  ]],
  ['placeholder', '{messages}']
]);

After receiving tool results, reflect on their quality and determine optimal
next steps. Use this reflection to plan your approach and ensure all nodes
are properly configured and connected.

Keep responses concise.

CRITICAL: Do NOT provide commentary between tool calls. Execute tools silently.
- NO progress messages like "Perfect!", "Now let me...", "Excellent!"
- NO descriptions of what was built or how it works
- Only respond AFTER all tools are complete

ALL tools support parallel execution, including add_nodes
- Information gathering: Call search_nodes and get_node_details in parallel
- Node creation: Add multiple nodes by calling add_nodes multiple times
- Parameter updates: Update different nodes simultaneously

1. Discovery Phase (parallel execution)
   - Search for all required node types simultaneously

2. Analysis Phase (parallel execution)
   - Get details for ALL nodes before proceeding

3. Creation Phase (parallel execution)
   - Add nodes individually by calling add_nodes for each node

4. Connection Phase (parallel execution)
   - Connect all nodes based on discovered input/output structure

5. Configuration Phase (parallel execution) - MANDATORY
   - ALWAYS configure nodes using update_node_parameters

AI sub-nodes PROVIDE capabilities, making them the SOURCE:
- OpenAI Chat Model → AI Agent [ai_languageModel]
- Calculator Tool → AI Agent [ai_tool]
- Token Splitter → Default Data Loader [ai_textSplitter]

⚠️ CRITICAL: NEVER RELY ON DEFAULT PARAMETER VALUES ⚠️

Default values are a common source of runtime failures. You MUST explicitly
configure ALL parameters that control node behavior.

CRITICAL: Always include a Workflow Configuration node at the start of every workflow.

Placement: Trigger → Workflow Configuration → First processing node

This creates a single source of truth for workflow parameters.

Tool nodes (nodes ending with "Tool") support special $fromAI expressions:

{{ $fromAI('key', 'description', 'type', defaultValue) }}

Example:
{
  "sendTo": "={{ $fromAI('to') }}",
  "subject": "={{ $fromAI('subject') }}"
}

IMPORTANT: Only provide ONE response AFTER all tool executions are complete.

Response format conditions:
- Include "**⚙️ How to Setup**" ONLY if this is the initial workflow creation
- Include "**📝 What's changed**" ONLY for non-initial modifications

const systemPrompt = `
You are an expert n8n workflow architect who updates node parameters based
on natural language instructions.

## Your Task
Update the parameters of an existing n8n node. Return the COMPLETE parameters
object with both modified and unmodified parameters.

## Reference Information
1. The original user workflow request
2. The current workflow JSON
3. The selected node's current configuration
4. The node type's parameter definitions
5. Natural language changes to apply

## Parameter Update Guidelines
1. START WITH CURRENT: If current parameters is empty {}, start with an
   empty object and add the requested parameters
2. PRESERVE EXISTING VALUES: Only modify parameters mentioned in the
   requested changes
3. CHECK FOR RESOURCELOCATOR: If a parameter is type 'resourceLocator',
   it MUST use the ResourceLocator structure
4. USE PROPER EXPRESSIONS: Follow n8n expression syntax
5. VALIDATE TYPES: Ensure parameter values match their expected types
`;

const nodeDefinitionPrompt = `
The node accepts these properties:
<node_properties_definition>
{node_definition}
</node_properties_definition>
`;

const workflowContextPrompt = `
<current_workflow_json>
{workflow_json}
</current_workflow_json>

<selected_node>
Name: {node_name}
Type: {node_type}
Current Parameters: {current_parameters}
</selected_node>

<requested_changes>
{changes}
</requested_changes>
`;

{
  type: 'text',
  text: systemPrompt,
  cache_control: { type: 'ephemeral' }  // ← Cached
}

Maximum Context: 200,000 tokens

Allocation:
├─ System Prompt: 8,000 tokens (cached)
├─ Node Definitions: 5,000 tokens (cached)
├─ Workflow JSON: 30,000 tokens (trimmed)
├─ Execution Data: 2,000 tokens
├─ Conversation History: 20,000 tokens (auto-compact)
├─ Previous Summary: 1,000 tokens (after compact)
├─ Buffer: 10,000 tokens
└─ Output Reserved: 16,000 tokens
    Total: 92,000 / 200,000 used

Remaining: 108,000 tokens for conversation growth

function trimWorkflowJSON(workflow: SimpleWorkflow): SimpleWorkflow {
  const estimatedTokens = estimateTokens(JSON.stringify(workflow));

  if (estimatedTokens <= MAX_WORKFLOW_LENGTH_TOKENS) {
    return workflow;
  }

  return {
    ...workflow,
    nodes: workflow.nodes.map(node => ({
      ...node,
      parameters: trimParameters(node.parameters)
    }))
  };
}

function trimParameters(params: any): any {
  if (typeof params === 'string' && params.length > 1000) {
    return '<value omitted - use get_node_parameter tool>';
  }

  if (Array.isArray(params)) {
    return params.map(trimParameters);
  }

  if (typeof params === 'object' && params !== null) {
    const trimmed: any = {};
    for (const [key, value] of Object.entries(params)) {
      trimmed[key] = trimParameters(value);
    }
    return trimmed;
  }

  return params;
}

function shouldAutoCompact(state: WorkflowState): boolean {
  const tokenUsage = extractLastTokenUsage(state.messages);
  const tokensUsed = tokenUsage.input_tokens + tokenUsage.output_tokens;

  return tokensUsed > DEFAULT_AUTO_COMPACT_THRESHOLD;  // 20,000
}

async function compactSession(state: WorkflowState) {
  const { messages, previousSummary } = state;

  // Call LLM to compress history
  const compacted = await conversationCompactChain(
    llm,
    messages,
    previousSummary
  );

  return {
    previousSummary: compacted.summaryPlain,
    messages: [
      ...messages.map(m => new RemoveMessage({ id: m.id })),
      new HumanMessage('Please compress the conversation history'),
      new AIMessage('Successfully compacted conversation history')
    ]
  };
}

// Sequential execution (slow)
await search_nodes();
await get_node_details();
await add_nodes();
await connect_nodes();
// Total: ~400ms

// Parallel execution (fast)
await Promise.all([
  search_nodes(),
  get_node_details(),
  add_nodes(),
  connect_nodes()
]);
// Total: ~100ms (75% faster)

User sends message: 0ms
├─ Frontend → Service: 10ms
├─ Setup LLM client: 50ms
├─ Agent initialization: 20ms
├─ First LLM call (with tools): 2000ms
│   ├─ Prompt construction: 10ms
│   ├─ API request: 50ms
│   ├─ LLM processing: 1800ms
│   └─ Response parsing: 140ms
├─ Tool execution (parallel): 100ms
│   ├─ search_nodes: 30ms
│   ├─ get_node_details: 40ms
│   └─ add_nodes: 50ms
├─ Process operations: 10ms
├─ Second LLM call (response): 1500ms
└─ Stream to frontend: 50ms
    Total: ~3740ms (~3.7 seconds)

// Base error
class WorkflowBuilderError extends Error {
  constructor(
    message: string,
    public code: string,
    public details?: Record<string, unknown>
  ) {
    super(message);
  }
}

// Specific errors
class ValidationError extends WorkflowBuilderError
class NodeNotFoundError extends WorkflowBuilderError
class NodeTypeNotFoundError extends WorkflowBuilderError
class ConnectionError extends WorkflowBuilderError
class ParameterUpdateError extends WorkflowBuilderError
class ToolExecutionError extends WorkflowBuilderError
class LLMServiceError extends WorkflowBuilderError
class WorkflowStateError extends WorkflowBuilderError

interface ToolError {
  message: string;
  code: string;
  details?: Record<string, unknown>;
}

function createErrorResponse(config: ToolRunnableConfig, error: ToolError): Command {
  return new Command({
    update: {
      messages: [
        new ToolMessage({
          content: `Error: ${error.message}`,
          tool_call_id: config.toolCall.id,
          additional_kwargs: { error: true, code: error.code }
        })
      ]
    }
  });
}

tool((input, config) => {
  const reporter = createProgressReporter(config);

  try {
    // 1. Schema validation
    const validated = schema.parse(input);

    // 2. Business logic validation
    const node = validateNodeExists(nodeId, nodes);
    if (!node) {
      throw new NodeNotFoundError(nodeId);
    }

    // 3. Semantic validation
    const validation = validateConnection(...);
    if (!validation.valid) {
      throw new ConnectionError(validation.error);
    }

    // 4. Execute
    reporter.complete(output);
    return createSuccessResponse(config, message, stateUpdates);

  } catch (error) {
    // 5. Error categorization
    if (error instanceof z.ZodError) {
      const toolError = new ValidationError('Invalid input', {
        errors: error.errors
      });
      reporter.error(toolError);
      return createErrorResponse(config, toolError);
    }

    if (error instanceof WorkflowBuilderError) {
      reporter.error(error);
      return createErrorResponse(config, error);
    }

    // 6. Unknown errors
    const toolError = new ToolExecutionError(
      error instanceof Error ? error.message : 'Unknown error'
    );
    reporter.error(toolError);
    return createErrorResponse(config, toolError);
  }
})

Input Data
    ↓
┌─────────────────────┐
│ Layer 1: Zod Schema │ ← Type checking, required fields
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ Layer 2: Business   │ ← Node exists? Type valid?
│         Logic       │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ Layer 3: Semantic   │ ← Connection compatible?
│         Rules       │   Parameter type correct?
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ Layer 4: Operations │ ← Final integrity check
│         Processor   │   during state mutation
└─────────────────────┘

// If one tool fails in parallel batch, others continue
const toolResults = await Promise.all(
  aiMessage.tool_calls.map(async (toolCall) => {
    try {
      return await tool.invoke(toolCall.args);
    } catch (error) {
      // Return ToolMessage with error instead of throwing
      return new ToolMessage({
        content: `Tool ${toolCall.name} failed: ${error.message}`,
        tool_call_id: toolCall.id,
        additional_kwargs: { error: true }
      });
    }
  })
);

// Agent sees errors and can retry or adjust approach

// Wrong direction detected → auto-swap instead of error
if (targetIsSubNode && !sourceIsSubNode) {
  return {
    valid: true,
    shouldSwap: true,
    swappedSource: targetNode,
    swappedTarget: sourceNode
  };
}

throw new ConnectionError(
  'No compatible connection types found',
  {
    sourceNode: source.name,
    targetNode: target.name,
    possibleTypes: {
      source: sourceOutputTypes,
      target: targetInputTypes
    }
  }
);

const name = customName ?? nodeType.defaults?.name ?? nodeType.displayName;

const limit = validatedInput.limit ?? 5;
const withParameters = validatedInput.withParameters ?? false;

const nodeCreationSchema = z.object({
  nodeType: z.string(),
  name: z.string(),
  connectionParametersReasoning: z.string(),
  connectionParameters: z.object({}).passthrough()
});

const nodeConnectionSchema = z.object({
  sourceNodeId: z.string(),
  targetNodeId: z.string(),
  sourceOutputIndex: z.number().optional(),
  targetInputIndex: z.number().optional()
});

try {
  const validated = schema.parse(input);
} catch (error) {
  if (error instanceof z.ZodError) {
    throw new ValidationError('Invalid input', { errors: error.errors });
  }
}

// Every request requires authenticated user
async *chat(payload: ChatPayload, user: IUser, abortSignal?: AbortSignal) {
  if (!user || !user.id) {
    throw new Error('Unauthorized');
  }

  // Get user-specific auth token
  const authHeaders = await this.getApiProxyAuthHeaders(user);

  // All LLM requests include user's JWT
  const llm = await setupModel({ authHeaders });
}

await this.client.markBuilderSuccess(user, authHeaders);
// Returns: { creditsQuota, creditsClaimed }

if (creditsClaimed >= creditsQuota) {
  throw new Error('Credit quota exceeded');
}

function fixExpressionPrefixes(parameters: any): any {
  // Prevent malicious expressions
  if (typeof parameters === 'string') {
    // Only fix n8n expression syntax, don't execute
    return fixExpressionFormat(parameters);
  }

  // Recursively sanitize nested structures
  return recursiveSanitize(parameters);
}

const MAX_AI_BUILDER_PROMPT_LENGTH = 1000;  // User input limit
const MAX_PARAMETER_VALUE_LENGTH = 30_000;   // Parameter size limit
const MAX_WORKFLOW_LENGTH_TOKENS = 30_000;   // Workflow JSON limit

// No credentials stored in workflow JSON
// Credentials managed separately by n8n core
// AI never has access to credential values

✅ Good:
1. search_nodes({queries: [{queryType: "name", query: "http"}]})
2. get_node_details({nodeName: "n8n-nodes-base.httpRequest"})
3. add_nodes({...})

❌ Bad:
1. add_nodes({nodeType: "n8n-nodes-base.httpRequest", ...})
   // Might not exist! Should search first.

✅ Good:
Promise.all([
  add_nodes({nodeType: "n8n-nodes-base.httpRequest", ...}),
  add_nodes({nodeType: "n8n-nodes-base.set", ...})
])

❌ Bad:
await add_nodes({nodeType: "n8n-nodes-base.httpRequest", ...});
await add_nodes({nodeType: "n8n-nodes-base.set", ...});
// Sequential = slower

✅ Good:
1. add_nodes({...})
2. connect_nodes({...})
3. update_node_parameters({
     nodeId: "...",
     changes: ["Set URL to https://...", "Set method to POST"]
   })

❌ Bad:
1. add_nodes({...})
2. connect_nodes({...})
// Node not configured! Will fail at runtime.

✅ Good:
{
  nodeType: "@n8n/n8n-nodes-langchain.vectorStoreInMemory",
  connectionParametersReasoning: "Vector Store mode determines inputs. Using 'insert' for document processing.",
  connectionParameters: { mode: "insert" }
}

❌ Bad:
{
  nodeType: "@n8n/n8n-nodes-langchain.vectorStoreInMemory",
  connectionParametersReasoning: "Adding vector store",
  connectionParameters: {}  // Missing critical mode parameter!
}

✅ Good:
update_node_parameters({
  nodeId: "http-123",
  changes: [
    "Set URL to https://api.example.com",
    "Set method to POST",
    "Add header Content-Type: application/json",
    "Set body to {\"key\": \"value\"}"
  ]
})

❌ Bad:
update_node_parameters({nodeId: "http-123", changes: ["Set URL..."]});
update_node_parameters({nodeId: "http-123", changes: ["Set method..."]});
update_node_parameters({nodeId: "http-123", changes: ["Add header..."]});
// Multiple LLM calls = slow and expensive

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

// Input validation
const validated = schema.parse(input);

// Business validation
const node = validateNodeExists(nodeId, nodes);

// Semantic validation
const result = validateConnection(source, target, type);

type WorkflowOperation =
  | { type: 'addNodes'; nodes: INode[] }
  | { type: 'removeNode'; nodeIds: string[] }
  | { type: 'updateNode'; nodeId: string; updates: Partial<INode> };

// TypeScript narrows type based on discriminant
function applyOperation(op: WorkflowOperation) {
  switch (op.type) {
    case 'addNodes':
      op.nodes  // ← TypeScript knows this exists
      break;
    case 'removeNode':
      op.nodeIds  // ← TypeScript knows this exists
      break;
  }
}

// ✅ Good: Pure business logic
class NodeSearchEngine {
  searchByName(query: string): NodeSearchResult[] {
    // No I/O, easily testable
  }
}

// ✅ Good: I/O wrapper
function createNodeSearchTool(nodeTypes: INodeTypeDescription[]) {
  const engine = new NodeSearchEngine(nodeTypes);

  return tool((input, config) => {
    const results = engine.searchByName(input.query);
    return createSuccessResponse(config, formatResults(results));
  });
}

class ParameterUpdatePromptBuilder {
  private prompt = '';

  addCoreInstructions() {
    this.prompt += CORE_INSTRUCTIONS;
    return this;
  }

  addNodeExamples(nodeType: string) {
    if (isSetNode(nodeType)) this.prompt += SET_NODE_EXAMPLES;
    return this;
  }

  build() {
    return this.prompt;
  }
}

const prompt = new ParameterUpdatePromptBuilder()
  .addCoreInstructions()
  .addNodeExamples(nodeType)
  .build();

// packages/@n8n/ai-workflow-builder.ee/src/ai-workflow-builder-agent.service.ts

@Service()
export class AiWorkflowBuilderService {
  async *chat(payload: ChatPayload, user: IUser, abortSignal?: AbortSignal) {
    const agent = await this.getAgent(user);

    for await (const output of agent.chat(payload, user.id, abortSignal)) {
      yield output;
    }
  }
}

// packages/@n8n/ai-workflow-builder.ee/src/workflow-builder-agent.ts

export class WorkflowBuilderAgent {
  private createWorkflow() {
    const workflow = new StateGraph(WorkflowState)
      .addNode('agent', callModel)
      .addNode('tools', customToolExecutor)
      .addNode('process_operations', processOperations)
      // ... more nodes

    return workflow.compile({ checkpointer: this.checkpointer });
  }

  async *chat(payload: ChatPayload, userId: string) {
    const workflow = this.createWorkflow();
    const stream = workflow.stream(initialState, config);

    for await (const output of createStreamProcessor(stream)) {
      yield output;
    }
  }
}

// packages/@n8n/ai-workflow-builder.ee/src/utils/operations-processor.ts

export function processOperations(state: WorkflowState) {
  const newWorkflow = applyOperations(
    state.workflowJSON,
    state.workflowOperations
  );

  return {
    workflowJSON: newWorkflow,
    workflowOperations: null
  };
}

// packages/@n8n/ai-workflow-builder.ee/src/utils/tool-executor.ts

export async function executeToolsInParallel(options: ToolExecutorOptions) {
  const toolResults = await Promise.all(
    aiMessage.tool_calls.map(toolCall => tool.invoke(toolCall.args))
  );

  // Collect all operations
  const allOperations: WorkflowOperation[] = [];
  for (const update of stateUpdates) {
    if (update.workflowOperations) {
      allOperations.push(...update.workflowOperations);
    }
  }

  return { messages: allMessages, workflowOperations: allOperations };
}

{
  "dependencies": {
    "@langchain/anthropic": "^0.3.x",
    "@langchain/core": "^0.3.x",
    "@langchain/langgraph": "^0.2.x",
    "@n8n_io/ai-assistant-sdk": "^1.15.x",
    "n8n-workflow": "workspace:*",
    "zod": "^3.23.x",
    "lodash": "^4.17.x"
  }
}

# Self-hosted mode (optional)
N8N_AI_ANTHROPIC_KEY=sk-ant-xxx

# Cloud mode (via AI Assistant SDK)
# No env vars needed - uses SDK client

enum NodeConnectionTypes {
  // Main data flow
  Main = 'main',

  // AI connections
  AiLanguageModel = 'ai_languageModel',
  AiTool = 'ai_tool',
  AiMemory = 'ai_memory',
  AiDocument = 'ai_document',
  AiVectorStore = 'ai_vectorStore',
  AiEmbedding = 'ai_embedding',
  AiOutputParser = 'ai_outputParser',
  AiTextSplitter = 'ai_textSplitter',
  AiRetriever = 'ai_retriever',
  AiChain = 'ai_chain',
  AiAgent = 'ai_agent',
  AiToolkit = 'ai_toolkit'
}

const AVG_CHARS_PER_TOKEN_ANTHROPIC = 2.5;

function estimateTokens(text: string): number {
  return Math.ceil(text.length / AVG_CHARS_PER_TOKEN_ANTHROPIC);
}

// Examples:
estimateTokens("Hello world")  // → 5 tokens
estimateTokens(JSON.stringify(workflow))  // → ~12,000 tokens for typical workflow

interface SimpleWorkflow {
  name: string;
  nodes: INode[];
  connections: IConnections;
}

interface INode {
  id: string;
  name: string;
  type: string;
  typeVersion: number;
  position: [number, number];
  parameters: INodeParameters;
  credentials?: INodeCredentials;
}

interface IConnections {
  [nodeName: string]: {
    [connectionType: string]: Array<Array<IConnection>>;
  };
}

interface IConnection {
  node: string;  // Target node name
  type: NodeConnectionType;
  index: number;  // Target input index
}

{
  "name": "Weather Workflow",
  "nodes": [
    {
      "id": "abc-123",
      "name": "Schedule Trigger",
      "type": "n8n-nodes-base.scheduleTrigger",
      "typeVersion": 1,
      "position": [240, 300],
      "parameters": {
        "rule": {
          "interval": [{ "field": "hours", "hoursInterval": 1 }]
        }
      }
    },
    {
      "id": "def-456",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [480, 300],
      "parameters": {
        "method": "GET",
        "url": "https://api.weather.com/forecast"
      }
    }
  ],
  "connections": {
    "Schedule Trigger": {
      "main": [[
        {
          "node": "HTTP Request",
          "type": "main",
          "index": 0
        }
      ]]
    }
  }
}