n8n/packages/@n8n/instance-ai/src/tools/index.ts

import type { ToolsInput } from '@mastra/core/agent';

import { isParseableAttachment } from '../parsers/structured-file-parser';
import type { InstanceAiContext, OrchestrationContext } from '../types';
import { createParseFileTool } from './attachments/parse-file.tool';
import { createCredentialsTool } from './credentials.tool';
import { createDataTablesTool } from './data-tables.tool';
import { createExecutionsTool } from './executions.tool';
import { createToolsFromLocalMcpServer } from './filesystem/create-tools-from-mcp-server';
import { createNodesTool } from './nodes.tool';
import { createBrowserCredentialSetupTool } from './orchestration/browser-credential-setup.tool';
import { createBuildWorkflowAgentTool } from './orchestration/build-workflow-agent.tool';
import { createCompleteCheckpointTool } from './orchestration/complete-checkpoint.tool';
import { createDelegateTool } from './orchestration/delegate.tool';
import { createPlanWithAgentTool } from './orchestration/plan-with-agent.tool';
import { createPlanTool } from './orchestration/plan.tool';
import { createReportVerificationVerdictTool } from './orchestration/report-verification-verdict.tool';
import { createVerifyBuiltWorkflowTool } from './orchestration/verify-built-workflow.tool';
import { createResearchTool } from './research.tool';
import { createAskUserTool } from './shared/ask-user.tool';
import { createTaskControlTool } from './task-control.tool';
import { createApplyWorkflowCredentialsTool } from './workflows/apply-workflow-credentials.tool';
import { createBuildWorkflowTool } from './workflows/build-workflow.tool';
import { createWorkflowsTool, type WorkflowAction } from './workflows.tool';
import { createWorkspaceTool } from './workspace.tool';

function hasParseableAttachment(context: InstanceAiContext): boolean {
	return context.currentUserAttachments?.some(isParseableAttachment) ?? false;
}

const ORCHESTRATOR_WORKFLOW_ACTIONS = [
	'list',
	'get',
	'delete',
	'unarchive',
	'setup',
	'publish',
	'unpublish',
	'list-versions',
	'get-version',
	'restore-version',
	'update-version',
] as const satisfies readonly WorkflowAction[];

/**
 * Creates all native n8n domain tools with the full action surface.
 * Agents with narrower surfaces pass explicit action lists at their wiring sites.
 */
export function createAllTools(context: InstanceAiContext): ToolsInput {
	return {
		workflows: createWorkflowsTool(context),
		executions: createExecutionsTool(context),
		credentials: createCredentialsTool(context),
		'data-tables': createDataTablesTool(context),
		workspace: createWorkspaceTool(context),
		research: createResearchTool(context),
		nodes: createNodesTool(context),
		'ask-user': createAskUserTool(),
		'build-workflow': createBuildWorkflowTool(context),
		...(context.localMcpServer ? createToolsFromLocalMcpServer(context.localMcpServer) : {}),
		...(hasParseableAttachment(context) ? { 'parse-file': createParseFileTool(context) } : {}),
	};
}

/**
 * Creates orchestrator-scoped domain tools — restricted action surfaces
 * for tools where the orchestrator should not have write/builder access.
 */
export function createOrchestratorDomainTools(context: InstanceAiContext): ToolsInput {
	return {
		workflows: createWorkflowsTool(context, {
			allowedActions: ORCHESTRATOR_WORKFLOW_ACTIONS,
		}),
		executions: createExecutionsTool(context),
		credentials: createCredentialsTool(context),
		'data-tables': createDataTablesTool(context, 'orchestrator'),
		workspace: createWorkspaceTool(context),
		research: createResearchTool(context),
		nodes: createNodesTool(context, 'orchestrator'),
		'ask-user': createAskUserTool(),
		...(context.localMcpServer ? createToolsFromLocalMcpServer(context.localMcpServer) : {}),
		...(hasParseableAttachment(context) ? { 'parse-file': createParseFileTool(context) } : {}),
	};
}

/**
 * Creates orchestration-only tools (planner, delegation, task control).
 * These tools are given to the orchestrator agent but never to sub-agents.
 */
export function createOrchestrationTools(context: OrchestrationContext) {
	return {
		plan: createPlanWithAgentTool(context),
		'create-tasks': createPlanTool(context),
		'task-control': createTaskControlTool(context),
		delegate: createDelegateTool(context),
		'build-workflow-with-agent': createBuildWorkflowAgentTool(context),
		'complete-checkpoint': createCompleteCheckpointTool(context),
		...(context.browserMcpConfig || hasGatewayBrowserTools(context)
			? {
					'browser-credential-setup': createBrowserCredentialSetupTool(context),
				}
			: {}),
		...(context.workflowTaskService
			? {
					'report-verification-verdict': createReportVerificationVerdictTool(context),
				}
			: {}),
		...(context.workflowTaskService && context.domainContext
			? {
					'verify-built-workflow': createVerifyBuiltWorkflowTool(context),
				}
			: {}),
		...(context.workflowTaskService && context.domainContext
			? {
					'apply-workflow-credentials': createApplyWorkflowCredentialsTool(context),
				}
			: {}),
	};
}

function hasGatewayBrowserTools(context: OrchestrationContext): boolean {
	return (context.localMcpServer?.getToolsByCategory('browser').length ?? 0) > 0;
}