The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
feat: add create/complete file upload action tools for MCP (#25503)
Lakshay Manchanda96609b97ae4b
diff --git a/packages/twenty-server/src/engine/api/mcp/services/mcp-instruction-builder.service.ts b/packages/twenty-server/src/engine/api/mcp/services/mcp-instruction-builder.service.tsindex 909afcf0190..b5a11febc2e 100644--- a/packages/twenty-server/src/engine/api/mcp/services/mcp-instruction-builder.service.ts+++ b/packages/twenty-server/src/engine/api/mcp/services/mcp-instruction-builder.service.ts@@ -1,8 +1,11 @@import { Injectable } from '@nestjs/common';+import { ToolCategory } from 'twenty-shared/ai';import { camelToSnakeCase } from 'twenty-shared/utils';+import { MCP_EXCLUDED_TOOL_NAMES } from 'src/engine/api/mcp/constants/mcp-excluded-tool-names.const';import { buildMcpServerInstructions } from 'src/engine/api/mcp/utils/build-mcp-server-instructions.util';+import { ToolRegistryService } from 'src/engine/core-modules/tool-provider/services/tool-registry.service';import { getDatabaseCrudToolFlatObjects } from 'src/engine/metadata-modules/ai/ai-agent/utils/get-database-crud-tool-flat-objects.util';import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';import { SkillService } from 'src/engine/metadata-modules/skill/skill.service';@@ -12,16 +15,27 @@ export class McpInstructionBuilderService {constructor(private readonly flatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,private readonly skillService: SkillService,+ private readonly toolRegistry: ToolRegistryService,) {}- async buildInstructions(workspaceId: string): Promise<string> {- const [{ flatObjectMetadataMaps }, allSkills] = await Promise.all([- this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps({- workspaceId,- flatMapsKeys: ['flatObjectMetadataMaps'],- }),- this.skillService.findAllFlatSkills(workspaceId),- ]);+ async buildInstructions({+ workspaceId,+ roleId,+ }: {+ workspaceId: string;+ roleId: string;+ }): Promise<string> {+ const [{ flatObjectMetadataMaps }, allSkills, actionToolCatalog] =+ await Promise.all([+ this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps({+ workspaceId,+ flatMapsKeys: ['flatObjectMetadataMaps'],+ }),+ this.skillService.findAllFlatSkills(workspaceId),+ this.toolRegistry.buildToolIndex(workspaceId, roleId, {+ categories: [ToolCategory.ACTION],+ }),+ ]);const objectNames = getDatabaseCrudToolFlatObjects(flatObjectMetadataMaps.byUniversalIdentifier,@@ -30,11 +44,19 @@ export class McpInstructionBuilderService {.sort().join(', ');+ const actionToolNames = actionToolCatalog+ .map((entry) => entry.name)+ .filter((name) => !MCP_EXCLUDED_TOOL_NAMES.has(name));+const skillNames =allSkills.length > 0? allSkills.map((skill) => skill.name).join(', '): undefined;- return buildMcpServerInstructions(objectNames, skillNames);+ return buildMcpServerInstructions({+ objectNames,+ actionToolNames,+ skillNames,+ });}}diff --git a/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts b/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.tsindex e4b4e870312..e60054ab116 100644--- a/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts+++ b/packages/twenty-server/src/engine/api/mcp/services/mcp-protocol.service.ts@@ -1,8 +1,8 @@import { HttpException, HttpStatus, Injectable } from '@nestjs/common';import { type ToolSet, zodSchema } from 'ai';-import { isDefined } from 'twenty-shared/utils';import { type ActorMetadata, FieldActorSource } from 'twenty-shared/types';+import { isDefined } from 'twenty-shared/utils';import { JSON_RPC_ERROR_CODE } from 'src/engine/api/mcp/constants/json-rpc-error-code.const';import { MCP_CLOSED_WORLD_READ_ONLY_TOOL_ANNOTATIONS } from 'src/engine/api/mcp/constants/mcp-closed-world-read-only-tool-annotations.const';@@ -55,8 +55,8 @@ import {import { type FlatWorkspace } from 'src/engine/core-modules/workspace/types/flat-workspace.type';import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';import { SkillService } from 'src/engine/metadata-modules/skill/skill.service';-import { WorkspaceCacheService } from 'src/engine/workspace-cache/services/workspace-cache.service';import { UserRoleService } from 'src/engine/metadata-modules/user-role/user-role.service';+import { WorkspaceCacheService } from 'src/engine/workspace-cache/services/workspace-cache.service';type McpAnnotatedTool = ToolSet[string] & {annotations: McpToolAnnotations;@@ -98,9 +98,15 @@ export class McpProtocolService {private readonly workspaceCacheService: WorkspaceCacheService,) {}- async handleInitialize(requestId: string | number, workspaceId: string) {+ async handleInitialize(+ requestId: string | number,+ { workspaceId, roleId }: { workspaceId: string; roleId: string },+ ) {const instructions =- await this.mcpInstructionBuilderService.buildInstructions(workspaceId);+ await this.mcpInstructionBuilderService.buildInstructions({+ workspaceId,+ roleId,+ });return wrapJsonRpcResponse(requestId, {result: {@@ -300,7 +306,10 @@ export class McpProtocolService {}if (method === 'initialize') {- return this.handleInitialize(id, workspace.id);+ return this.handleInitialize(id, {+ workspaceId: workspace.id,+ roleId: await this.getRoleId(workspace.id, userWorkspaceId, apiKey),+ });}if (method === 'ping') {diff --git a/packages/twenty-server/src/engine/api/mcp/utils/__tests__/build-mcp-server-instructions.util.spec.ts b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/build-mcp-server-instructions.util.spec.tsnew file mode 100644index 00000000000..65224f8b17a--- /dev/null+++ b/packages/twenty-server/src/engine/api/mcp/utils/__tests__/build-mcp-server-instructions.util.spec.ts@@ -0,0 +1,60 @@+import { buildMcpServerInstructions } from 'src/engine/api/mcp/utils/build-mcp-server-instructions.util';++const getActionLine = (instructions: string): string =>+ instructions.split('\n').find((line) => line.includes('ACTION:')) ?? '';++describe('buildMcpServerInstructions', () => {+ it('should render the ACTION line from the tools the caller can reach', () => {+ const instructions = buildMcpServerInstructions({+ objectNames: 'companies, people',+ actionToolNames: ['send_email', 'search_help_center'],+ });++ expect(getActionLine(instructions)).toContain(+ 'send_email | search_help_center',+ );+ expect(instructions).not.toContain('create_file_upload');+ expect(instructions).not.toContain('http_request');+ });++ it('should add the upload recipe only when the upload tools are reachable', () => {+ const withUpload = buildMcpServerInstructions({+ objectNames: 'companies',+ actionToolNames: ['create_file_upload', 'complete_file_upload'],+ });++ expect(withUpload).toContain('To attach a file: create_file_upload');++ const withoutUpload = buildMcpServerInstructions({+ objectNames: 'companies',+ actionToolNames: ['send_email'],+ });++ expect(withoutUpload).not.toContain('To attach a file');+ });++ it('should add the http_request guidance only when http_request is reachable', () => {+ const withHttp = buildMcpServerInstructions({+ objectNames: 'companies',+ actionToolNames: ['http_request'],+ });++ expect(withHttp).toContain('http_request is ONLY for external');++ const withoutHttp = buildMcpServerInstructions({+ objectNames: 'companies',+ actionToolNames: ['send_email'],+ });++ expect(withoutHttp).not.toContain('http_request is ONLY for external');+ });++ it('should omit the skills line when the workspace has no skills', () => {+ const instructions = buildMcpServerInstructions({+ objectNames: 'companies',+ actionToolNames: ['send_email'],+ });++ expect(instructions).not.toContain('Available skills');+ });+});diff --git a/packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts b/packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.tsindex a2a036796d3..f97e7ca3ad8 100644--- a/packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts+++ b/packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts@@ -1,8 +1,17 @@-export const buildMcpServerInstructions = (- objectNames: string,- skillNames?: string,-): string =>- [+import { settings } from 'src/engine/constants/settings';++export const buildMcpServerInstructions = ({+ objectNames,+ actionToolNames,+ skillNames,+}: {+ objectNames: string;+ actionToolNames: string[];+ skillNames?: string;+}): string => {+ const availableActionTools = new Set(actionToolNames);++ return [`You are an AI assistant for a Twenty CRM workspace.`,`Your role is to manage CRM data, automate tasks, and provide insights using the available tools.`,``,@@ -23,7 +32,7 @@ export const buildMcpServerInstructions = (` Write: create_one_{object} | create_many_{objects} | update_one_{object} | update_many_{objects} | delete_one_{object} | delete_many_{objects} | upsert_many_{objects}. Use upsert_many_{objects} instead of update_many_{objects} when each record has its own individual data.`,``,`Non-CRUD tools — use learn_tools for schemas:`,- ` ACTION: http_request | send_email | draft_email | find_connected_accounts | navigate_app | code_interpreter | search_help_center`,+ ` ACTION: ${actionToolNames.join(' | ')}`,` WORKFLOW: list_workflows | create_complete_workflow | create/update/delete_workflow_version_step | activate/deactivate_workflow_version | list_workflow_runs | get_workflow_run | get_workflow_current_version`,` METADATA: get/create/update/delete_object_metadata | get/create/update/delete_field_metadata`,` Both GET tools return system items as compact summaries by default — keep that default for listing/inspecting; only set includeFullSystemObjects / includeFullSystemFields=true when you specifically need a system item's full configuration`,@@ -70,9 +79,19 @@ export const buildMcpServerInstructions = (`Twenty primitives:`,` Favorites are navigation menu items. To favorite something, call create_navigation_menu_item with scope: 'user'.`,` A default OBJECT navigation item is auto-created with create_object_metadata — do not add another.`,- ` http_request is ONLY for external third-party APIs, never for Twenty's own data.`,+ ...(availableActionTools.has('http_request')+ ? [+ ` http_request is ONLY for external third-party APIs, never for Twenty's own data.`,+ ]+ : []),+ ...(availableActionTools.has('create_file_upload')+ ? [+ ` To attach a file: create_file_upload ({ filename, size }), PUT the bytes to uploadUrl with Content-Type contentType (max ${settings.storage.maxDirectUploadFileSize}), then complete_file_upload ({ fileId }). Use that fileId in a FILES value (create_one_attachment file: [{ fileId, label }] and the target*Id, or a FILES field on create_one_* / update_one_*) or in code_interpreter.files. update_many does not copy FILES values; update_one replaces the whole FILES list.`,+ ]+ : []),``,`On tool failure: read the error message, do not retry silently, report to user.`,`Present results as readable summaries, not raw JSON.`,`For large result sets, show count + first N records and offer to paginate.`,].join('\n');+};diff --git a/packages/twenty-server/src/engine/core-modules/file/file-upload/services/file-upload.service.ts b/packages/twenty-server/src/engine/core-modules/file/file-upload/services/file-upload.service.tsindex 3e1196d41f8..4882f375918 100644--- a/packages/twenty-server/src/engine/core-modules/file/file-upload/services/file-upload.service.ts+++ b/packages/twenty-server/src/engine/core-modules/file/file-upload/services/file-upload.service.ts@@ -16,11 +16,11 @@ import { settings } from 'src/engine/constants/settings';import { ApplicationEntity } from 'src/engine/core-modules/application/application.entity';import { ApplicationService } from 'src/engine/core-modules/application/application.service';import { FileStorageService } from 'src/engine/core-modules/file-storage/services/file-storage.service';-import { FileWithSignedUrlDTO } from 'src/engine/core-modules/file/dtos/file-with-sign-url.dto';import { FileEntity } from 'src/engine/core-modules/file/entities/file.entity';import { COMPLETE_FILE_UPLOAD_DEADLINE_MS } from 'src/engine/core-modules/file/file-upload/constants/complete-file-upload-deadline.constant';import { MAX_SANITIZABLE_SVG_BYTES } from 'src/engine/core-modules/file/file-upload/constants/max-sanitizable-svg-size.constant';import { FileUploadTargetDTO } from 'src/engine/core-modules/file/file-upload/dtos/file-upload-target.dto';+import { type CompletedFileUpload } from 'src/engine/core-modules/file/file-upload/types/completed-file-upload.type';import {FileUploadException,FileUploadExceptionCode,@@ -250,7 +250,7 @@ export class FileUploadService {}: {workspaceId: string;fileId: string;- }): Promise<FileWithSignedUrlDTO> {+ }): Promise<CompletedFileUpload> {const file = await this.findFileOrThrow({ workspaceId, fileId });const [fileFolder] = file.path.split('/');@@ -451,7 +451,7 @@ export class FileUploadService {file: FileEntity;fileFolder: FileFolder;workspaceId: string;- }): Promise<FileWithSignedUrlDTO> {+ }): Promise<CompletedFileUpload> {return {...file,url: await this.fileUrlService.signFileByIdUrl({diff --git a/packages/twenty-server/src/engine/core-modules/file/file-upload/types/completed-file-upload.type.ts b/packages/twenty-server/src/engine/core-modules/file/file-upload/types/completed-file-upload.type.tsnew file mode 100644index 00000000000..bf23209e182--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/file/file-upload/types/completed-file-upload.type.ts@@ -0,0 +1,5 @@+import { type FileWithSignedUrlDTO } from 'src/engine/core-modules/file/dtos/file-with-sign-url.dto';+import { type FileEntity } from 'src/engine/core-modules/file/entities/file.entity';++export type CompletedFileUpload = FileWithSignedUrlDTO &+ Pick<FileEntity, 'mimeType'>;diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/constants/action-tool-label.constant.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/constants/action-tool-label.constant.tsindex ea03e74e047..0b76996f57a 100644--- a/packages/twenty-server/src/engine/core-modules/tool-provider/constants/action-tool-label.constant.ts+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/constants/action-tool-label.constant.ts@@ -13,6 +13,8 @@ export const ACTION_TOOL_IDS = ['code_interpreter','navigate_app','save_campaign',+ 'create_file_upload',+ 'complete_file_upload',] as const;export type ActionToolId = (typeof ACTION_TOOL_IDS)[number];@@ -45,4 +47,10 @@ export const ACTION_TOOL_LABELS: Record<ActionToolId, ActionToolLabel> = {save_campaign: {label: i18nLabel(msg`Save Campaign`),},+ create_file_upload: {+ label: i18nLabel(msg`Create File Upload`),+ },+ complete_file_upload: {+ label: i18nLabel(msg`Complete File Upload`),+ },};diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/action-tool.provider.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/action-tool.provider.tsindex d1180aba35c..d2974180039 100644--- a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/action-tool.provider.ts+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/action-tool.provider.ts@@ -26,6 +26,8 @@ import { CodeInterpreterTool } from 'src/engine/core-modules/tool/tools/code-intimport { DraftEmailTool } from 'src/engine/core-modules/tool/tools/email-tool/draft-email-tool';import { FindConnectedAccountsTool } from 'src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool';import { SendEmailTool } from 'src/engine/core-modules/tool/tools/email-tool/send-email-tool';+import { CompleteFileUploadTool } from 'src/engine/core-modules/tool/tools/file-upload-tool/complete-file-upload-tool';+import { CreateFileUploadTool } from 'src/engine/core-modules/tool/tools/file-upload-tool/create-file-upload-tool';import { HttpTool } from 'src/engine/core-modules/tool/tools/http-tool/http-tool';import { NavigateAppTool } from 'src/engine/core-modules/tool/tools/navigate-tool/navigate-app-tool';import { ExtractJsonPathsTool } from 'src/engine/core-modules/tool/tools/output-navigation-tool/extract-json-paths-tool';@@ -49,6 +51,8 @@ export class ActionToolProvider implements ToolProvider {private readonly findConnectedAccountsTool: FindConnectedAccountsTool,private readonly createCalendarEventTool: CreateCalendarEventTool,private readonly searchHelpCenterTool: SearchHelpCenterTool,+ private readonly createFileUploadTool: CreateFileUploadTool,+ private readonly completeFileUploadTool: CompleteFileUploadTool,private readonly codeInterpreterTool: CodeInterpreterTool,private readonly navigateAppTool: NavigateAppTool,private readonly extractJsonPathsTool: ExtractJsonPathsTool,@@ -65,6 +69,8 @@ export class ActionToolProvider implements ToolProvider {['find_connected_accounts', this.findConnectedAccountsTool],['create_calendar_event', this.createCalendarEventTool],['search_help_center', this.searchHelpCenterTool],+ ['create_file_upload', this.createFileUploadTool],+ ['complete_file_upload', this.completeFileUploadTool],['code_interpreter', this.codeInterpreterTool],['navigate_app', this.navigateAppTool],['extract_json_paths', this.extractJsonPathsTool],@@ -152,6 +158,32 @@ export class ActionToolProvider implements ToolProvider {);}+ const hasUploadFilePermission =+ await this.permissionsService.hasToolPermission(+ context.rolePermissionConfig,+ context.workspaceId,+ PermissionFlagType.UPLOAD_FILE,+ );++ if (hasUploadFilePermission) {+ descriptors.push(+ this.buildDescriptor(+ 'create_file_upload',+ this.createFileUploadTool,+ includeSchemas,+ context.locale,+ ),+ );+ descriptors.push(+ this.buildDescriptor(+ 'complete_file_upload',+ this.completeFileUploadTool,+ includeSchemas,+ context.locale,+ ),+ );+ }+descriptors.push(this.buildDescriptor('search_help_center',diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.tsindex 9e29859db71..b5df4e8f859 100644--- a/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-registry.service.ts@@ -1,6 +1,7 @@import { Inject, Injectable, Logger } from '@nestjs/common';import { type ToolSet, jsonSchema } from 'ai';+import { type ToolCategory } from 'twenty-shared/ai';import { type APP_LOCALES } from 'twenty-shared/translations';import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';@@ -31,9 +32,20 @@ export class ToolRegistryService {private readonly toolOutputSpillService: ToolOutputSpillService,) {}- async getCatalog(context: ToolProviderContext): Promise<ToolIndexEntry[]> {+ async getCatalog(+ context: ToolProviderContext,+ options?: { categories?: ToolCategory[]; excludeTools?: Set<string> },+ ): Promise<ToolIndexEntry[]> {+ const categorySet = options?.categories+ ? new Set(options.categories)+ : undefined;+const results = await Promise.all(this.providers.map(async (provider) => {+ if (categorySet && !categorySet.has(provider.category)) {+ return [];+ }+if (await provider.isAvailable(context)) {return provider.generateDescriptors(context, {includeSchemas: false,@@ -44,7 +56,9 @@ export class ToolRegistryService {}),);- return results.flat();+ const excludeTools = options?.excludeTools;++ return results.flat().filter((entry) => !excludeTools?.has(entry.name));}async resolveSchemas({@@ -159,6 +173,8 @@ export class ToolRegistryService {userWorkspaceId?: string;locale?: keyof typeof APP_LOCALES;rolePermissionConfig?: RolePermissionConfig;+ categories?: ToolCategory[];+ excludeTools?: Set<string>;},): Promise<ToolIndexEntry[]> {const context = this.buildContextFromToolContext({@@ -170,7 +186,10 @@ export class ToolRegistryService {locale: options?.locale,});- return this.getCatalog(context);+ return this.getCatalog(context, {+ categories: options?.categories,+ excludeTools: options?.excludeTools,+ });}async getToolsByName(diff --git a/packages/twenty-server/src/engine/core-modules/tool/tool.module.ts b/packages/twenty-server/src/engine/core-modules/tool/tool.module.tsindex 36d481d7d35..b09e42ac386 100644--- a/packages/twenty-server/src/engine/core-modules/tool/tool.module.ts+++ b/packages/twenty-server/src/engine/core-modules/tool/tool.module.ts@@ -13,6 +13,8 @@ import { DraftEmailTool } from 'src/engine/core-modules/tool/tools/email-tool/drimport { EmailComposerService } from 'src/engine/core-modules/tool/tools/email-tool/email-composer.service';import { FindConnectedAccountsTool } from 'src/engine/core-modules/tool/tools/email-tool/find-connected-accounts-tool';import { SendEmailTool } from 'src/engine/core-modules/tool/tools/email-tool/send-email-tool';+import { CompleteFileUploadTool } from 'src/engine/core-modules/tool/tools/file-upload-tool/complete-file-upload-tool';+import { CreateFileUploadTool } from 'src/engine/core-modules/tool/tools/file-upload-tool/create-file-upload-tool';import { HttpTool } from 'src/engine/core-modules/tool/tools/http-tool/http-tool';import { NavigateAppTool } from 'src/engine/core-modules/tool/tools/navigate-tool/navigate-app-tool';import { ExtractJsonPathsTool } from 'src/engine/core-modules/tool/tools/output-navigation-tool/extract-json-paths-tool';@@ -54,6 +56,8 @@ import { provideWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspacCreateCalendarEventTool,EmailComposerService,SearchHelpCenterTool,+ CreateFileUploadTool,+ CompleteFileUploadTool,CodeInterpreterTool,NavigateAppTool,ExtractJsonPathsTool,@@ -69,6 +73,8 @@ import { provideWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspacCreateCalendarEventTool,EmailComposerService,SearchHelpCenterTool,+ CreateFileUploadTool,+ CompleteFileUploadTool,CodeInterpreterTool,NavigateAppTool,ExtractJsonPathsTool,diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/complete-file-upload-tool.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/complete-file-upload-tool.tsnew file mode 100644index 00000000000..aecc67da2fe--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/complete-file-upload-tool.ts@@ -0,0 +1,83 @@+import { Injectable, Logger } from '@nestjs/common';++import { FileUploadException } from 'src/engine/core-modules/file/file-upload/file-upload.exception';+import { FileUploadService } from 'src/engine/core-modules/file/file-upload/services/file-upload.service';+import { CompleteFileUploadToolInputZodSchema } from 'src/engine/core-modules/tool/tools/file-upload-tool/file-upload-tool.schema';+import { type ToolInput } from 'src/engine/core-modules/tool/types/tool-input.type';+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';+import { type ToolExecutionContext } from 'src/engine/core-modules/tool/types/tool-execution-context.type';+import { type Tool } from 'src/engine/core-modules/tool/types/tool.type';++@Injectable()+export class CompleteFileUploadTool implements Tool {+ private readonly logger = new Logger(CompleteFileUploadTool.name);++ description =+ 'Confirm a direct upload after the client has PUT bytes to the uploadUrl from create_file_upload. Returns a fileId for FILES fields or code_interpreter.files. Requires UPLOAD_FILE permission.';+ inputSchema = CompleteFileUploadToolInputZodSchema;++ constructor(private readonly fileUploadService: FileUploadService) {}++ async execute(+ parameters: ToolInput,+ context: ToolExecutionContext,+ ): Promise<ToolOutput> {+ const parseResult =+ CompleteFileUploadToolInputZodSchema.safeParse(parameters);++ if (!parseResult.success) {+ return {+ success: false,+ message: 'Invalid input for complete file upload',+ error: parseResult.error.issues+ .map(+ (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,+ )+ .join('; '),+ };+ }++ const { fileId } = parseResult.data;++ try {+ const completedFile = await this.fileUploadService.completeFileUpload({+ workspaceId: context.workspaceId,+ fileId,+ });++ this.logger.log(+ `Completed file upload ${completedFile.id} for workspace ${context.workspaceId}`,+ );++ return {+ success: true,+ message: 'File upload completed',+ result: {+ fileId: completedFile.id,+ path: completedFile.path,+ mimeType: completedFile.mimeType,+ size: Number(completedFile.size),+ },+ };+ } catch (error) {+ if (error instanceof FileUploadException) {+ return {+ success: false,+ message: 'Failed to complete file upload',+ error: error.message,+ };+ }++ this.logger.error(`Failed to complete file upload: ${error}`);++ return {+ success: false,+ message: 'Failed to complete file upload',+ error:+ error instanceof Error+ ? error.message+ : 'Failed to complete file upload',+ };+ }+ }+}diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/create-file-upload-tool.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/create-file-upload-tool.tsnew file mode 100644index 00000000000..68ac6ab0da1--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/create-file-upload-tool.ts@@ -0,0 +1,87 @@+import { Injectable, Logger } from '@nestjs/common';++import { FileFolder } from 'twenty-shared/types';++import { settings } from 'src/engine/constants/settings';+import { FileUploadException } from 'src/engine/core-modules/file/file-upload/file-upload.exception';+import { FileUploadService } from 'src/engine/core-modules/file/file-upload/services/file-upload.service';+import { CreateFileUploadToolInputZodSchema } from 'src/engine/core-modules/tool/tools/file-upload-tool/file-upload-tool.schema';+import { type ToolInput } from 'src/engine/core-modules/tool/types/tool-input.type';+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';+import { type ToolExecutionContext } from 'src/engine/core-modules/tool/types/tool-execution-context.type';+import { type Tool } from 'src/engine/core-modules/tool/types/tool.type';++@Injectable()+export class CreateFileUploadTool implements Tool {+ private readonly logger = new Logger(CreateFileUploadTool.name);++ description = `Create an upload URL for a file in agent-chat storage. PUT the bytes to uploadUrl with the returned Content-Type, then call complete_file_upload. Requires UPLOAD_FILE permission. Maximum size ${settings.storage.maxDirectUploadFileSize}.`;+ inputSchema = CreateFileUploadToolInputZodSchema;++ constructor(private readonly fileUploadService: FileUploadService) {}++ async execute(+ parameters: ToolInput,+ context: ToolExecutionContext,+ ): Promise<ToolOutput> {+ const parseResult =+ CreateFileUploadToolInputZodSchema.safeParse(parameters);++ if (!parseResult.success) {+ return {+ success: false,+ message: 'Invalid input for create file upload',+ error: parseResult.error.issues+ .map(+ (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,+ )+ .join('; '),+ };+ }++ const { filename, size } = parseResult.data;++ try {+ const uploadTarget = await this.fileUploadService.createFileUpload({+ workspaceId: context.workspaceId,+ filename,+ size,+ fileFolder: FileFolder.AgentChat,+ });++ this.logger.log(+ `Created file upload ${uploadTarget.fileId} (${filename}) for workspace ${context.workspaceId}`,+ );++ return {+ success: true,+ message: 'Upload URL created.',+ result: {+ fileId: uploadTarget.fileId,+ uploadUrl: uploadTarget.uploadUrl,+ contentType: uploadTarget.contentType,+ expiresAt: uploadTarget.expiresAt,+ },+ };+ } catch (error) {+ if (error instanceof FileUploadException) {+ return {+ success: false,+ message: 'Failed to create file upload',+ error: error.message,+ };+ }++ this.logger.error(`Failed to create file upload: ${error}`);++ return {+ success: false,+ message: 'Failed to create file upload',+ error:+ error instanceof Error+ ? error.message+ : 'Failed to create file upload',+ };+ }+ }+}diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/file-upload-tool.schema.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/file-upload-tool.schema.tsnew file mode 100644index 00000000000..b2f383c7a6e--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/file-upload-tool/file-upload-tool.schema.ts@@ -0,0 +1,26 @@+import { isValidUuid } from 'twenty-shared/utils';+import { z } from 'zod';++export const CreateFileUploadToolInputZodSchema = z.object({+ filename: z+ .string()+ .describe(+ 'Original filename including extension (e.g. protokol-2026-001.pdf).',+ ),+ size: z+ .number()+ .int()+ .positive()+ .describe('Exact byte length of the file being uploaded.'),+});++export const CompleteFileUploadToolInputZodSchema = z.object({+ fileId: z+ .string()+ .refine((fileId) => isValidUuid(fileId), {+ message: 'fileId must be a valid UUID',+ })+ .describe(+ 'fileId returned by create_file_upload after the bytes have been PUT to uploadUrl.',+ ),+});diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-excluded-tool-names.const.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-excluded-tool-names.const.tsindex db8dc6154ca..94f4beb8bd6 100644--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-excluded-tool-names.const.ts+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-excluded-tool-names.const.ts@@ -3,4 +3,6 @@ import { type ActionToolId } from 'src/engine/core-modules/tool-provider/constanexport const WORKFLOW_AGENT_EXCLUDED_TOOL_NAMES = ['search_help_center','navigate_app',+ 'create_file_upload',+ 'complete_file_upload',] as const satisfies readonly ActionToolId[];diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.tsindex e49a1b6b753..d795ee1b436 100644--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts@@ -44,6 +44,7 @@ import { OUTPUT_NAVIGATION_TOOL_NAMES } from 'src/engine/core-modules/tool/toolsimport { UsageOperationType } from 'src/engine/core-modules/usage/enums/usage-operation-type.enum';import { WorkspaceEntity } from 'src/engine/core-modules/workspace/workspace.entity';import { OPEN_ENDED_AGENT_REGISTRY_TOOL_CATEGORIES } from 'src/engine/metadata-modules/ai/ai-agent-execution/constants/open-ended-agent-registry-tool-categories.const';+import { WORKFLOW_AGENT_EXCLUDED_TOOL_NAMES } from 'src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-excluded-tool-names.const';import { WORKFLOW_AGENT_REGISTRY_TOOL_CATEGORIES } from 'src/engine/metadata-modules/ai/ai-agent-execution/constants/workflow-agent-registry-tool-categories.const';import { type AgentExecutionResult } from 'src/engine/metadata-modules/ai/ai-agent-execution/types/agent-execution-result.type';import { type AgentToolLoadingStrategy } from 'src/engine/metadata-modules/ai/ai-agent-execution/types/agent-tool-loading-strategy.type';@@ -172,7 +173,10 @@ export class AgentAsyncExecutorService {return this.toolRegistry.getToolsByCategories(toolProviderContext, {categories: WORKFLOW_AGENT_REGISTRY_TOOL_CATEGORIES,- excludeTools: [...OUTPUT_NAVIGATION_TOOL_NAMES],+ excludeTools: [+ ...OUTPUT_NAVIGATION_TOOL_NAMES,+ ...WORKFLOW_AGENT_EXCLUDED_TOOL_NAMES,+ ],wrapWithErrorContext: false,});}@@ -219,7 +223,10 @@ export class AgentAsyncExecutorService {const allowedCategories = new Set(OPEN_ENDED_AGENT_REGISTRY_TOOL_CATEGORIES,);- const excludedToolNames = new Set<string>(OUTPUT_NAVIGATION_TOOL_NAMES);+ const excludedToolNames = new Set<string>([+ ...OUTPUT_NAVIGATION_TOOL_NAMES,+ ...WORKFLOW_AGENT_EXCLUDED_TOOL_NAMES,+ ]);const catalog = fullCatalog.filter((entry) =>diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-excluded-tool-names.const.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-excluded-tool-names.const.tsnew file mode 100644index 00000000000..1d710633981--- /dev/null+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-excluded-tool-names.const.ts@@ -0,0 +1,4 @@+export const AI_CHAT_EXCLUDED_TOOL_NAMES = new Set([+ 'create_file_upload',+ 'complete_file_upload',+]);diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.tsindex fae956d6833..3a0d2bcfc27 100644--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts@@ -55,6 +55,7 @@ import {extractCacheCreationTokens,extractCacheCreationTokensFromSteps,} from 'src/engine/metadata-modules/ai/ai-billing/utils/extract-cache-creation-tokens.util';+import { AI_CHAT_EXCLUDED_TOOL_NAMES } from 'src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-excluded-tool-names.const';import { AI_CHAT_STREAM_FUNCTION_ID } from 'src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-stream-function-id.constant';import { AI_CHAT_TOOL_NAMES_TO_PRELOAD } from 'src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-tool-names-to-preload.const';import { AI_CHAT_WORKSPACE_SETUP_STREAM_FUNCTION_ID } from 'src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-workspace-setup-stream-function-id.constant';@@ -172,7 +173,12 @@ export class ChatExecutionService {const toolCatalog = await this.toolRegistry.buildToolIndex(workspace.id,roleId,- { userId, userWorkspaceId, locale },+ {+ userId,+ userWorkspaceId,+ locale,+ excludeTools: AI_CHAT_EXCLUDED_TOOL_NAMES,+ },);const skillCatalog = await this.skillService.findAllFlatSkills(@@ -244,6 +250,9 @@ export class ChatExecutionService {...(isWorkspaceSetupThread ? [COMPLETE_WORKSPACE_SETUP_TOOL_NAME] : []),];+ const isToolAllowed = (toolName: string) =>+ !AI_CHAT_EXCLUDED_TOOL_NAMES.has(toolName);+// ToolSet is constant for the entire conversation — no mutation.// learn_tools returns schemas as text; execute_tool dispatches via the registry.const activeTools: ToolSet = {@@ -260,12 +269,19 @@ export class ChatExecutionService {[LEARN_TOOLS_TOOL_NAME]: createLearnToolsTool(this.toolRegistry,toolContext,- { spillLargeOutput: true },+ {+ spillLargeOutput: true,+ isToolAllowed,+ },),[EXECUTE_TOOL_TOOL_NAME]: createExecuteToolTool(this.toolRegistry,toolContext,- { compactOutput: true, spillLargeOutput: true },+ {+ compactOutput: true,+ spillLargeOutput: true,+ isToolAllowed,+ },),[LOAD_SKILL_TOOL_NAME]: createLoadSkillTool((skillNames) =>diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/system-prompt-builder.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/system-prompt-builder.service.tsindex 045e7eb4f0c..58c4cbb734a 100644--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/system-prompt-builder.service.ts+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/system-prompt-builder.service.ts@@ -6,6 +6,7 @@ import { COMMON_PRELOAD_TOOLS } from 'src/engine/core-modules/tool-provider/consimport { ToolRegistryService } from 'src/engine/core-modules/tool-provider/services/tool-registry.service';import { buildToolCatalogSection } from 'src/engine/core-modules/tool-provider/utils/build-tool-catalog-section.util';import { AgentActorContextService } from 'src/engine/metadata-modules/ai/ai-agent-execution/services/agent-actor-context.service';+import { AI_CHAT_EXCLUDED_TOOL_NAMES } from 'src/engine/metadata-modules/ai/ai-chat/constants/ai-chat-excluded-tool-names.const';import { CHAT_SYSTEM_PROMPTS } from 'src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const';import { buildSkillCatalogSection } from 'src/engine/metadata-modules/ai/ai-chat/utils/build-skill-catalog-section.util';import { buildUserContextSection } from 'src/engine/metadata-modules/ai/ai-chat/utils/build-user-context-section.util';@@ -48,7 +49,11 @@ export class SystemPromptBuilderService {const toolCatalog = await this.toolRegistry.buildToolIndex(workspaceId,roleId,- { userId, userWorkspaceId },+ {+ userId,+ userWorkspaceId,+ excludeTools: AI_CHAT_EXCLUDED_TOOL_NAMES,+ },);const skillCatalog = await this.skillService.findAllFlatSkills(workspaceId);