Skip to content

The open alternative to Salesforce, designed for AI.

Declare tools as discovered @DefineTool providers ( only delete webhook first ) (#28210)

Paul Rastoinb20ea995dbab
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/constants/define-tool-metadata-key.constant.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/constants/define-tool-metadata-key.constant.ts
new file mode 100644
index 00000000000..0f2f357782a
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/constants/define-tool-metadata-key.constant.ts
@@ -0,0 +1 @@
+export const DEFINE_TOOL_METADATA_KEY = 'DEFINE_TOOL_METADATA_KEY';
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/decorators/__tests__/define-tool.decorator.spec.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/decorators/__tests__/define-tool.decorator.spec.ts
new file mode 100644
index 00000000000..d8fcd62b7e2
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/decorators/__tests__/define-tool.decorator.spec.ts
@@ -0,0 +1,86 @@
+import { INJECTABLE_WATERMARK } from '@nestjs/common/constants';
+
+import { ToolCategory } from 'twenty-shared/ai';
+import { z } from 'zod';
+
+import { DEFINE_TOOL_METADATA_KEY } from 'src/engine/core-modules/tool-provider/constants/define-tool-metadata-key.constant';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+
+const renameWebhookInputSchema = z.object({ id: z.uuid() });
+
+const RENAME_WEBHOOK_OPTIONS = {
+ name: 'rename_webhook',
+ category: ToolCategory.WEBHOOK,
+ description: 'Rename a webhook.',
+};
+
+describe('DefineTool', () => {
+ it('should make the tool injectable and record its options', () => {
+ @DefineTool(RENAME_WEBHOOK_OPTIONS)
+ class RenameWebhookTool extends BaseTool<typeof renameWebhookInputSchema> {
+ readonly inputSchema = renameWebhookInputSchema;
+
+ async execute(): Promise<ToolOutput> {
+ return { success: true, message: 'Done' };
+ }
+ }
+
+ expect(Reflect.getMetadata(INJECTABLE_WATERMARK, RenameWebhookTool)).toBe(
+ true,
+ );
+ expect(
+ Reflect.getMetadata(DEFINE_TOOL_METADATA_KEY, RenameWebhookTool),
+ ).toEqual(RENAME_WEBHOOK_OPTIONS);
+ });
+
+ it('should only compile tools that follow the BaseTool contract', () => {
+ // @ts-expect-error DefineTool only decorates classes extending BaseTool
+ @DefineTool(RENAME_WEBHOOK_OPTIONS)
+ class NotATool {}
+
+ // @ts-expect-error matching members are not enough, the class must extend BaseTool
+ @DefineTool(RENAME_WEBHOOK_OPTIONS)
+ class LookAlikeTool {
+ readonly inputSchema = renameWebhookInputSchema;
+
+ async execute(): Promise<ToolOutput> {
+ return { success: true, message: 'Done' };
+ }
+ }
+
+ // @ts-expect-error a tool must implement execute
+ class ToolWithoutExecute extends BaseTool<typeof renameWebhookInputSchema> {
+ readonly inputSchema = renameWebhookInputSchema;
+ }
+
+ class ToolWithMismatchedInput extends BaseTool<
+ typeof renameWebhookInputSchema
+ > {
+ readonly inputSchema = renameWebhookInputSchema;
+
+ // @ts-expect-error execute input must match the inputSchema
+ async execute(input: { name: number }): Promise<ToolOutput> {
+ return { success: true, message: String(input.name) };
+ }
+ }
+
+ // @ts-expect-error tool inputs must be zod objects
+ class ToolWithScalarInput extends BaseTool<z.ZodString> {
+ readonly inputSchema = z.string();
+
+ async execute(): Promise<ToolOutput> {
+ return { success: true, message: 'Done' };
+ }
+ }
+
+ expect([
+ NotATool,
+ LookAlikeTool,
+ ToolWithoutExecute,
+ ToolWithMismatchedInput,
+ ToolWithScalarInput,
+ ]).toHaveLength(5);
+ });
+});
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/decorators/define-tool.decorator.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/decorators/define-tool.decorator.ts
new file mode 100644
index 00000000000..59985cf428a
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/decorators/define-tool.decorator.ts
@@ -0,0 +1,14 @@
+import { applyDecorators, Injectable, SetMetadata } from '@nestjs/common';
+
+import { DEFINE_TOOL_METADATA_KEY } from 'src/engine/core-modules/tool-provider/constants/define-tool-metadata-key.constant';
+import { type BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type DefineToolOptions } from 'src/engine/core-modules/tool-provider/types/define-tool-options.type';
+
+export const DefineTool =
+ (options: DefineToolOptions) =>
+ <TTool extends new (...args: never[]) => BaseTool>(target: TTool): void => {
+ applyDecorators(
+ Injectable(),
+ SetMetadata(DEFINE_TOOL_METADATA_KEY, options),
+ )(target);
+ };
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/interfaces/base-tool.interface.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/interfaces/base-tool.interface.ts
new file mode 100644
index 00000000000..95ff6e7e1d4
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/interfaces/base-tool.interface.ts
@@ -0,0 +1,16 @@
+import { type z } from 'zod';
+
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+
+export abstract class BaseTool<TInputSchema extends z.ZodObject = z.ZodObject> {
+ // Makes the type nominal: @DefineTool rejects look-alike classes that would fail instanceof at boot
+ protected readonly isBaseTool = true;
+
+ abstract readonly inputSchema: TInputSchema;
+
+ abstract execute(
+ input: z.infer<TInputSchema>,
+ context: ToolProviderContext,
+ ): Promise<ToolOutput>;
+}
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/services/defined-tool-registry.service.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/services/defined-tool-registry.service.ts
new file mode 100644
index 00000000000..fb5cc0a344d
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/services/defined-tool-registry.service.ts
@@ -0,0 +1,135 @@
+import { Inject, Injectable, type OnModuleInit } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+
+import { type ToolCategory } from 'twenty-shared/ai';
+import { isDefined } from 'twenty-shared/utils';
+
+import { DEFINE_TOOL_METADATA_KEY } from 'src/engine/core-modules/tool-provider/constants/define-tool-metadata-key.constant';
+import { TOOL_PROVIDERS } from 'src/engine/core-modules/tool-provider/constants/tool-providers.token';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type GenerateDescriptorOptions } from 'src/engine/core-modules/tool-provider/interfaces/generate-descriptor-options.type';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolProvider } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider.interface';
+import { type DefineToolOptions } from 'src/engine/core-modules/tool-provider/types/define-tool-options.type';
+import { type DefinedTool } from 'src/engine/core-modules/tool-provider/types/defined-tool.type';
+import { type ToolDescriptor } from 'src/engine/core-modules/tool-provider/types/tool-descriptor.type';
+import { type ToolIndexEntry } from 'src/engine/core-modules/tool-provider/types/tool-index-entry.type';
+import { buildInvalidToolArgumentsOutput } from 'src/engine/core-modules/tool-provider/utils/build-invalid-tool-arguments-output.util';
+import { buildToolInputJsonSchemaOrThrow } from 'src/engine/core-modules/tool-provider/utils/build-tool-input-json-schema-or-throw.util';
+import { isSnakeCaseToolName } from 'src/engine/core-modules/tool-provider/utils/is-snake-case-tool-name.util';
+import { humanizeToolName } from 'src/engine/core-modules/tool-provider/utils/tool-set-to-descriptors.util';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+
+@Injectable()
+export class DefinedToolRegistryService implements OnModuleInit {
+ private readonly definedToolsByName = new Map<string, DefinedTool>();
+
+ constructor(
+ private readonly discoveryService: DiscoveryService,
+ @Inject(TOOL_PROVIDERS)
+ private readonly providers: ToolProvider[],
+ ) {}
+
+ onModuleInit() {
+ for (const { instance, metatype } of this.discoveryService.getProviders()) {
+ if (!isDefined(metatype)) {
+ continue;
+ }
+
+ const options: DefineToolOptions | undefined = Reflect.getMetadata(
+ DEFINE_TOOL_METADATA_KEY,
+ metatype,
+ );
+
+ if (isDefined(options)) {
+ this.register(options, instance);
+ }
+ }
+ }
+
+ findDefinedTool(toolName: string): DefinedTool | undefined {
+ return this.definedToolsByName.get(toolName);
+ }
+
+ getDescriptors(
+ category: ToolCategory,
+ options?: GenerateDescriptorOptions,
+ ): (ToolIndexEntry | ToolDescriptor)[] {
+ const includeSchemas = options?.includeSchemas ?? true;
+
+ return [...this.definedToolsByName.values()]
+ .filter(
+ (definedTool) =>
+ definedTool.options.category === category &&
+ (!isDefined(options?.toolNames) ||
+ options.toolNames.has(definedTool.options.name)),
+ )
+ .map(({ options: { name, description }, inputJsonSchema }) => {
+ const entry: ToolIndexEntry = {
+ name,
+ label: humanizeToolName(name),
+ description,
+ category,
+ executionRef: { kind: 'static', toolId: name },
+ };
+
+ return includeSchemas
+ ? { ...entry, inputSchema: inputJsonSchema }
+ : entry;
+ });
+ }
+
+ async execute(
+ { options, tool }: DefinedTool,
+ args: Record<string, unknown>,
+ context: ToolProviderContext,
+ ): Promise<ToolOutput> {
+ const parsedInput = await tool.inputSchema.safeParseAsync(args);
+
+ if (!parsedInput.success) {
+ return buildInvalidToolArgumentsOutput({
+ toolName: options.name,
+ error: parsedInput.error,
+ });
+ }
+
+ return tool.execute(parsedInput.data, context);
+ }
+
+ private register(options: DefineToolOptions, instance: unknown): void {
+ const { name, category } = options;
+
+ if (!(instance instanceof BaseTool)) {
+ throw new Error(
+ `@DefineTool "${name}" must decorate a singleton provider that extends BaseTool`,
+ );
+ }
+
+ if (!isSnakeCaseToolName(name)) {
+ throw new Error(
+ `@DefineTool "${name}" must be snake_case, for example "delete_webhook"`,
+ );
+ }
+
+ if (this.definedToolsByName.has(name)) {
+ throw new Error(`@DefineTool "${name}" is declared more than once`);
+ }
+
+ if (!this.providers.some((provider) => provider.category === category)) {
+ throw new Error(
+ `@DefineTool "${name}" uses category "${category}", which no ToolProvider gates, so it would never be listed`,
+ );
+ }
+
+ const inputJsonSchema = buildToolInputJsonSchemaOrThrow({
+ toolName: name,
+ inputSchema: instance.inputSchema,
+ });
+
+ this.definedToolsByName.set(name, {
+ options,
+ tool: instance,
+ inputJsonSchema,
+ });
+ }
+}
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-executor.service.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-executor.service.ts
index 4be2c30b1eb..09342f5bbe7 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-executor.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/services/tool-executor.service.ts
@@ -22,6 +22,7 @@ import { UpdateRecordService } from 'src/engine/core-modules/record-crud/service
import { UpsertManyRecordsService } from 'src/engine/core-modules/record-crud/services/upsert-many-records.service';
import { type FindRecordsParams } from 'src/engine/core-modules/record-crud/types/find-records-params.type';
import { TOOL_PROVIDERS } from 'src/engine/core-modules/tool-provider/constants/tool-providers.token';
+import { DefinedToolRegistryService } from 'src/engine/core-modules/tool-provider/services/defined-tool-registry.service';
import { RecordFilesResolverService } from 'src/engine/core-modules/tool-provider/services/record-files-resolver.service';
import { type ToolProvider } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider.interface';
import { type ToolDescriptor } from 'src/engine/core-modules/tool-provider/types/tool-descriptor.type';
@@ -39,6 +40,7 @@ export class ToolExecutorService {
constructor(
@Inject(TOOL_PROVIDERS)
private readonly providers: ToolProvider[],
+ private readonly definedToolRegistryService: DefinedToolRegistryService,
private readonly findRecordsService: FindRecordsService,
private readonly groupByRecordsService: GroupByRecordsService,
private readonly createRecordService: CreateRecordService,
@@ -338,6 +340,18 @@ export class ToolExecutorService {
};
}
+ const definedTool = this.definedToolRegistryService.findDefinedTool(
+ descriptor.executionRef.toolId,
+ );
+
+ if (isDefined(definedTool)) {
+ return this.definedToolRegistryService.execute(
+ definedTool,
+ args,
+ context,
+ );
+ }
+
return provider.executeStaticTool(
descriptor.executionRef.toolId,
args,
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.ts
index 731bfbbac48..60aa7099ea2 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
@@ -16,6 +16,7 @@ import { ExceptionHandlerService } from 'src/engine/core-modules/exception-handl
import { TOOL_PROVIDERS } from 'src/engine/core-modules/tool-provider/constants/tool-providers.token';
import { compactToolOutput } from 'src/engine/core-modules/tool-provider/output-transforms/compact-tool-output.util';
import { normalizeToolOutputToJsonValues } from 'src/engine/core-modules/tool-provider/output-transforms/normalize-tool-output-to-json-values.util';
+import { DefinedToolRegistryService } from 'src/engine/core-modules/tool-provider/services/defined-tool-registry.service';
import { ToolExecutorService } from 'src/engine/core-modules/tool-provider/services/tool-executor.service';
import { type LearnToolsAspect } from 'src/engine/core-modules/tool-provider/tools/learn-tools.tool';
import { type ToolContext } from 'src/engine/core-modules/tool-provider/types/tool-context.type';
@@ -34,6 +35,7 @@ export class ToolRegistryService {
constructor(
@Inject(TOOL_PROVIDERS)
private readonly providers: ToolProvider[],
+ private readonly definedToolRegistryService: DefinedToolRegistryService,
private readonly toolExecutorService: ToolExecutorService,
private readonly toolOutputSpillService: ToolOutputSpillService,
private readonly exceptionHandlerService: ExceptionHandlerService,
@@ -481,11 +483,26 @@ export class ToolRegistryService {
},
},
async (span) => {
- const descriptors = await provider.generateDescriptors(
+ const providerDescriptors = await provider.generateDescriptors(
context,
options,
);
+ const descriptors = [
+ ...providerDescriptors.filter(
+ (descriptor) =>
+ !isDefined(
+ this.definedToolRegistryService.findDefinedTool(
+ descriptor.name,
+ ),
+ ),
+ ),
+ ...this.definedToolRegistryService.getDescriptors(
+ provider.category,
+ options,
+ ),
+ ];
+
span.setAttribute('tool.descriptor_count', descriptors.length);
return descriptors;
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
index 18b0adebcb6..737faae1d3d 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
@@ -1,4 +1,5 @@
import { Module } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
import { TypeOrmModule } from '@nestjs/typeorm';
import { FileEntity } from 'src/engine/core-modules/file/entities/file.entity';
@@ -17,6 +18,7 @@ import { RoleToolProvider } from 'src/engine/core-modules/tool-provider/provider
import { ViewToolProvider } from 'src/engine/core-modules/tool-provider/providers/view-tool.provider';
import { WebhookToolProvider } from 'src/engine/core-modules/tool-provider/providers/webhook-tool.provider';
import { WorkflowToolProvider } from 'src/engine/core-modules/tool-provider/providers/workflow-tool.provider';
+import { DefinedToolRegistryService } from 'src/engine/core-modules/tool-provider/services/defined-tool-registry.service';
import { RecordFilesResolverService } from 'src/engine/core-modules/tool-provider/services/record-files-resolver.service';
import { ToolExecutorService } from 'src/engine/core-modules/tool-provider/services/tool-executor.service';
import { ToolModule } from 'src/engine/core-modules/tool/tool.module';
@@ -35,7 +37,7 @@ import { ViewFieldModule } from 'src/engine/metadata-modules/view-field/view-fie
import { ViewFilterModule } from 'src/engine/metadata-modules/view-filter/view-filter.module';
import { ViewSortModule } from 'src/engine/metadata-modules/view-sort/view-sort.module';
import { ViewModule } from 'src/engine/metadata-modules/view/view.module';
-import { WebhookModule } from 'src/engine/metadata-modules/webhook/webhook.module';
+import { WebhookToolsModule } from 'src/engine/metadata-modules/webhook/tools/webhook-tools.module';
import { provideWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspace-scoped-repository/provide-workspace-scoped-repository';
import { WorkspaceCacheModule } from 'src/engine/workspace-cache/workspace-cache.module';
import { EmailingModule } from 'src/modules/emailing/emailing.module';
@@ -48,6 +50,7 @@ import { ToolRegistryService } from './services/tool-registry.service';
@Module({
imports: [
+ DiscoveryModule,
AiAgentModule,
ApplicationTranslationCatalogModule,
ToolModule,
@@ -64,7 +67,7 @@ import { ToolRegistryService } from './services/tool-registry.service';
WorkspaceCacheModule,
WorkspaceManyOrAllFlatEntityMapsCacheModule,
NavigationMenuItemModule,
- WebhookModule,
+ WebhookToolsModule,
RoleModule,
UserRoleModule,
ValidationRuleModule,
@@ -73,6 +76,7 @@ import { ToolRegistryService } from './services/tool-registry.service';
],
providers: [
ToolIndexResolver,
+ DefinedToolRegistryService,
ToolExecutorService,
RecordFilesResolverService,
provideWorkspaceScopedRepository(FileEntity),
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/types/define-tool-options.type.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/types/define-tool-options.type.ts
new file mode 100644
index 00000000000..9ffc7e7cb6c
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/types/define-tool-options.type.ts
@@ -0,0 +1,7 @@
+import { type ToolCategory } from 'twenty-shared/ai';
+
+export type DefineToolOptions = {
+ name: string;
+ category: ToolCategory;
+ description: string;
+};
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/types/defined-tool.type.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/types/defined-tool.type.ts
new file mode 100644
index 00000000000..40b7053382c
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/types/defined-tool.type.ts
@@ -0,0 +1,8 @@
+import { type BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type DefineToolOptions } from 'src/engine/core-modules/tool-provider/types/define-tool-options.type';
+
+export type DefinedTool = {
+ options: DefineToolOptions;
+ tool: BaseTool;
+ inputJsonSchema: object;
+};
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/__tests__/build-tool-input-json-schema-or-throw.util.spec.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/__tests__/build-tool-input-json-schema-or-throw.util.spec.ts
new file mode 100644
index 00000000000..cea5c451cd2
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/__tests__/build-tool-input-json-schema-or-throw.util.spec.ts
@@ -0,0 +1,37 @@
+import { z } from 'zod';
+
+import { buildToolInputJsonSchemaOrThrow } from 'src/engine/core-modules/tool-provider/utils/build-tool-input-json-schema-or-throw.util';
+
+describe('buildToolInputJsonSchemaOrThrow', () => {
+ it('should convert the input schema to JSON schema', () => {
+ expect(
+ buildToolInputJsonSchemaOrThrow({
+ toolName: 'delete_webhook',
+ inputSchema: z.object({
+ id: z.uuid().describe('The id of the webhook to delete'),
+ }),
+ }),
+ ).toEqual({
+ type: 'object',
+ properties: {
+ id: {
+ type: 'string',
+ format: 'uuid',
+ description: 'The id of the webhook to delete',
+ },
+ },
+ required: ['id'],
+ });
+ });
+
+ it('should name the tool when the schema cannot be converted', () => {
+ expect(() =>
+ buildToolInputJsonSchemaOrThrow({
+ toolName: 'schedule_webhook',
+ inputSchema: z.object({ runAt: z.date() }),
+ }),
+ ).toThrow(
+ '@DefineTool "schedule_webhook" has an inputSchema that cannot be converted to JSON schema',
+ );
+ });
+});
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/__tests__/is-snake-case-tool-name.util.spec.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/__tests__/is-snake-case-tool-name.util.spec.ts
new file mode 100644
index 00000000000..65cf99618dd
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/__tests__/is-snake-case-tool-name.util.spec.ts
@@ -0,0 +1,21 @@
+import { isSnakeCaseToolName } from 'src/engine/core-modules/tool-provider/utils/is-snake-case-tool-name.util';
+
+describe('isSnakeCaseToolName', () => {
+ it.each([['delete_webhook'], ['list_webhooks'], ['find_many_v2']])(
+ 'should accept %p',
+ (toolName) => {
+ expect(isSnakeCaseToolName(toolName)).toBe(true);
+ },
+ );
+
+ it.each([
+ ['deleteWebhook'],
+ ['Delete_webhook'],
+ ['delete-webhook'],
+ ['_delete_webhook'],
+ ['2_delete_webhook'],
+ [''],
+ ])('should refuse %p', (toolName) => {
+ expect(isSnakeCaseToolName(toolName)).toBe(false);
+ });
+});
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/build-invalid-tool-arguments-output.util.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/build-invalid-tool-arguments-output.util.ts
new file mode 100644
index 00000000000..87a99bf9f3d
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/build-invalid-tool-arguments-output.util.ts
@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+
+export const buildInvalidToolArgumentsOutput = ({
+ toolName,
+ error,
+}: {
+ toolName: string;
+ error: Error;
+}): ToolOutput => ({
+ success: false,
+ message: `Invalid arguments for ${toolName}`,
+ error: `The arguments do not match the input schema of ${toolName}: ${
+ error instanceof z.ZodError ? z.prettifyError(error) : error.message
+ }`,
+});
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/build-tool-input-json-schema-or-throw.util.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/build-tool-input-json-schema-or-throw.util.ts
new file mode 100644
index 00000000000..bd588983250
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/build-tool-input-json-schema-or-throw.util.ts
@@ -0,0 +1,19 @@
+import { type z } from 'zod';
+
+import { toToolJsonSchema } from 'src/engine/core-modules/record-crud/utils/to-tool-json-schema.util';
+
+export const buildToolInputJsonSchemaOrThrow = ({
+ toolName,
+ inputSchema,
+}: {
+ toolName: string;
+ inputSchema: z.ZodObject;
+}): object => {
+ try {
+ return toToolJsonSchema(inputSchema);
+ } catch (error) {
+ throw new Error(
+ `@DefineTool "${toolName}" has an inputSchema that cannot be converted to JSON schema: ${error instanceof Error ? error.message : String(error)}`,
+ );
+ }
+};
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/execute-tool-from-tool-set.util.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/execute-tool-from-tool-set.util.ts
index 1b6654e19c8..b94c79b0a68 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/execute-tool-from-tool-set.util.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/execute-tool-from-tool-set.util.ts
@@ -1,8 +1,8 @@
import { asSchema, type ToolExecuteFunction, type ToolSet } from 'ai';
import { type ToolCategory } from 'twenty-shared/ai';
import { isDefined } from 'twenty-shared/utils';
-import { z } from 'zod';
+import { buildInvalidToolArgumentsOutput } from 'src/engine/core-modules/tool-provider/utils/build-invalid-tool-arguments-output.util';
import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
// For providers whose tools are opaque AI-SDK ToolSet closures and so cannot dispatch by executionRef.
@@ -24,15 +24,10 @@ export const executeToolFromToolSet = async (
const validation = await asSchema(tool.inputSchema).validate?.(args);
if (isDefined(validation) && !validation.success) {
- return {
- success: false,
- message: `Invalid arguments for ${toolName}`,
- error: `The arguments do not match the input schema of ${toolName}: ${
- validation.error instanceof z.ZodError
- ? z.prettifyError(validation.error)
- : validation.error.message
- }`,
- };
+ return buildInvalidToolArgumentsOutput({
+ toolName,
+ error: validation.error,
+ });
}
// ToolSet widens execute to a union no argument satisfies; these tools take no per-tool context.
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/utils/is-snake-case-tool-name.util.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/is-snake-case-tool-name.util.ts
new file mode 100644
index 00000000000..03578c19203
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/utils/is-snake-case-tool-name.util.ts
@@ -0,0 +1,4 @@
+const SNAKE_CASE_TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+
+export const isSnakeCaseToolName = (toolName: string): boolean =>
+ SNAKE_CASE_TOOL_NAME_PATTERN.test(toolName);
diff --git a/packages/twenty-server/src/engine/metadata-modules/webhook/tools/delete-webhook.tool.ts b/packages/twenty-server/src/engine/metadata-modules/webhook/tools/delete-webhook.tool.ts
index 4b83085837b..a5dc4b4ce79 100644
--- a/packages/twenty-server/src/engine/metadata-modules/webhook/tools/delete-webhook.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/webhook/tools/delete-webhook.tool.ts
@@ -1,31 +1,40 @@
+import { ToolCategory } from 'twenty-shared/ai';
import { z } from 'zod';
-import { type WebhookToolContext } from 'src/engine/metadata-modules/webhook/tools/types/webhook-tool-context.type';
-import { type WebhookToolDependencies } from 'src/engine/metadata-modules/webhook/tools/types/webhook-tool-dependencies.type';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { WebhookService } from 'src/engine/metadata-modules/webhook/webhook.service';
-const deleteWebhookSchema = z.object({
+const deleteWebhookInputSchema = z.object({
id: z.uuid().describe('The id of the webhook to delete'),
});
-type DeleteWebhookParams = z.infer<typeof deleteWebhookSchema>;
-
-export const createDeleteWebhookTool = (
- deps: Pick<WebhookToolDependencies, 'webhookService'>,
- context: WebhookToolContext,
-) => ({
- name: 'delete_webhook' as const,
+@DefineTool({
+ name: 'delete_webhook',
+ category: ToolCategory.WEBHOOK,
description: `Delete a webhook by id. Use list_webhooks first if you don't know the id.`,
- inputSchema: deleteWebhookSchema,
- execute: async (parameters: DeleteWebhookParams) => {
- const webhook = await deps.webhookService.delete(
- parameters.id,
- context.workspaceId,
- );
+})
+export class DeleteWebhookTool extends BaseTool<
+ typeof deleteWebhookInputSchema
+> {
+ readonly inputSchema = deleteWebhookInputSchema;
+
+ constructor(private readonly webhookService: WebhookService) {
+ super();
+ }
+
+ async execute(
+ { id }: z.infer<typeof deleteWebhookInputSchema>,
+ { workspaceId }: ToolProviderContext,
+ ): Promise<ToolOutput> {
+ const webhook = await this.webhookService.delete(id, workspaceId);
return {
success: true,
message: `Webhook ${webhook.id} deleted`,
result: { deletedWebhookId: webhook.id, targetUrl: webhook.targetUrl },
};
- },
-});
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/webhook/tools/services/webhook-tool.workspace-service.ts b/packages/twenty-server/src/engine/metadata-modules/webhook/tools/services/webhook-tool.workspace-service.ts
index 807315ba318..67170a9f487 100644
--- a/packages/twenty-server/src/engine/metadata-modules/webhook/tools/services/webhook-tool.workspace-service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/webhook/tools/services/webhook-tool.workspace-service.ts
@@ -4,7 +4,6 @@ import { type ToolSet } from 'ai';
import { WebhookService } from 'src/engine/metadata-modules/webhook/webhook.service';
import { createCreateWebhookTool } from 'src/engine/metadata-modules/webhook/tools/create-webhook.tool';
-import { createDeleteWebhookTool } from 'src/engine/metadata-modules/webhook/tools/delete-webhook.tool';
import { createListWebhooksTool } from 'src/engine/metadata-modules/webhook/tools/list-webhooks.tool';
import { type WebhookToolDependencies } from 'src/engine/metadata-modules/webhook/tools/types/webhook-tool-dependencies.type';
import { createUpdateWebhookTool } from 'src/engine/metadata-modules/webhook/tools/update-webhook.tool';
@@ -23,13 +22,11 @@ export class WebhookToolWorkspaceService {
const listWebhooks = createListWebhooksTool(this.deps, context);
const createWebhook = createCreateWebhookTool(this.deps, context);
const updateWebhook = createUpdateWebhookTool(this.deps, context);
- const deleteWebhook = createDeleteWebhookTool(this.deps, context);
return {
[listWebhooks.name]: listWebhooks,
[createWebhook.name]: createWebhook,
[updateWebhook.name]: updateWebhook,
- [deleteWebhook.name]: deleteWebhook,
};
}
}
diff --git a/packages/twenty-server/src/engine/metadata-modules/webhook/tools/webhook-tools.module.ts b/packages/twenty-server/src/engine/metadata-modules/webhook/tools/webhook-tools.module.ts
new file mode 100644
index 00000000000..88227e236b8
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/webhook/tools/webhook-tools.module.ts
@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+
+import { DeleteWebhookTool } from 'src/engine/metadata-modules/webhook/tools/delete-webhook.tool';
+import { WebhookToolWorkspaceService } from 'src/engine/metadata-modules/webhook/tools/services/webhook-tool.workspace-service';
+import { WebhookModule } from 'src/engine/metadata-modules/webhook/webhook.module';
+
+@Module({
+ imports: [WebhookModule],
+ providers: [WebhookToolWorkspaceService, DeleteWebhookTool],
+ exports: [WebhookToolWorkspaceService],
+})
+export class WebhookToolsModule {}
diff --git a/packages/twenty-server/src/engine/metadata-modules/webhook/webhook.module.ts b/packages/twenty-server/src/engine/metadata-modules/webhook/webhook.module.ts
index dbf3a5ef199..ea87cbefcde 100644
--- a/packages/twenty-server/src/engine/metadata-modules/webhook/webhook.module.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/webhook/webhook.module.ts
@@ -5,7 +5,6 @@ import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata
import { FlatWebhookModule } from 'src/engine/metadata-modules/flat-webhook/flat-webhook.module';
import { PermissionsModule } from 'src/engine/metadata-modules/permissions/permissions.module';
import { WebhookController } from 'src/engine/metadata-modules/webhook/controllers/webhook.controller';
-import { WebhookToolWorkspaceService } from 'src/engine/metadata-modules/webhook/tools/services/webhook-tool.workspace-service';
import { WebhookResolver } from 'src/engine/metadata-modules/webhook/webhook.resolver';
import { WebhookService } from 'src/engine/metadata-modules/webhook/webhook.service';
import { WorkspaceCacheStorageModule } from 'src/engine/workspace-cache-storage/workspace-cache-storage.module';
@@ -22,7 +21,7 @@ import { WorkspaceMigrationModule } from 'src/engine/workspace-manager/workspace
FlatWebhookModule,
],
controllers: [WebhookController],
- providers: [WebhookService, WebhookResolver, WebhookToolWorkspaceService],
- exports: [WebhookToolWorkspaceService],
+ providers: [WebhookService, WebhookResolver],
+ exports: [WebhookService],
})
export class WebhookModule {}
diff --git a/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-webhook-tools.integration-spec.ts.snap b/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-webhook-tools.integration-spec.ts.snap
new file mode 100644
index 00000000000..1daff25b0d6
--- /dev/null
+++ b/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-webhook-tools.integration-spec.ts.snap
@@ -0,0 +1,32 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`MCP webhook tools (integration) should describe delete_webhook to the model 1`] = `
+[
+ {
+ "description": "Delete a webhook by id. Use list_webhooks first if you don't know the id.",
+ "inputSchema": {
+ "properties": {
+ "id": {
+ "description": "The id of the webhook to delete",
+ "format": "uuid",
+ "type": "string",
+ },
+ },
+ "required": [
+ "id",
+ ],
+ "type": "object",
+ },
+ "name": "delete_webhook",
+ },
+]
+`;
+
+exports[`MCP webhook tools (integration) should refuse delete_webhook with an id that is not a UUID 1`] = `
+{
+ "error": "The arguments do not match the input schema of delete_webhook: ✖ Invalid UUID
+ → at id",
+ "message": "Invalid arguments for delete_webhook",
+ "success": false,
+}
+`;
diff --git a/packages/twenty-server/test/integration/ai/suites/mcp-webhook-tools.integration-spec.ts b/packages/twenty-server/test/integration/ai/suites/mcp-webhook-tools.integration-spec.ts
new file mode 100644
index 00000000000..77fd9a2bcff
--- /dev/null
+++ b/packages/twenty-server/test/integration/ai/suites/mcp-webhook-tools.integration-spec.ts
@@ -0,0 +1,90 @@
+import { executeToolThroughMcp } from 'test/integration/ai/utils/execute-tool-through-mcp.util';
+import { callMcpTool } from 'test/integration/graphql/suites/application-role-intersection/utils/call-mcp-tool.util';
+import { jestExpectToBeDefined } from 'test/utils/jest-expect-to-be-defined.util.test';
+
+const TARGET_URL = 'https://example.com/twenty-webhook';
+
+const listWebhookIds = async (): Promise<string[]> => {
+ const output = await executeToolThroughMcp<{ webhooks: { id: string }[] }>({
+ toolName: 'list_webhooks',
+ toolArguments: {},
+ });
+
+ expect(output.success).toBe(true);
+
+ return (output.result?.webhooks ?? []).map((webhook) => webhook.id);
+};
+
+describe('MCP webhook tools (integration)', () => {
+ let webhookIdsBefore: string[];
+
+ beforeAll(async () => {
+ webhookIdsBefore = await listWebhookIds();
+ });
+
+ afterAll(async () => {
+ const leakedWebhookIds = (await listWebhookIds()).filter(
+ (id) => !webhookIdsBefore.includes(id),
+ );
+
+ for (const id of leakedWebhookIds) {
+ await executeToolThroughMcp({
+ toolName: 'delete_webhook',
+ toolArguments: { id },
+ });
+ }
+ });
+
+ it('should describe delete_webhook to the model', async () => {
+ const result = await callMcpTool({
+ toolName: 'learn_tools',
+ toolArguments: { toolNames: ['delete_webhook'] },
+ token: API_KEY_ACCESS_TOKEN,
+ });
+
+ expect(result.isError).toBe(false);
+
+ const payload = JSON.parse(result.content[0].text);
+
+ expect(payload.notFound).toEqual([]);
+ expect(payload.tools).toMatchSnapshot();
+ });
+
+ it('should delete a webhook created through create_webhook', async () => {
+ const created = await executeToolThroughMcp<{ id: string }>({
+ toolName: 'create_webhook',
+ toolArguments: {
+ targetUrl: TARGET_URL,
+ operations: [{ kind: 'record', object: 'person', event: 'created' }],
+ },
+ });
+
+ expect(created.success).toBe(true);
+
+ const webhookId = created.result?.id;
+
+ jestExpectToBeDefined(webhookId);
+ expect(await listWebhookIds()).toContain(webhookId);
+
+ const deleted = await executeToolThroughMcp({
+ toolName: 'delete_webhook',
+ toolArguments: { id: webhookId },
+ });
+
+ expect(deleted).toEqual({
+ success: true,
+ message: `Webhook ${webhookId} deleted`,
+ result: { deletedWebhookId: webhookId, targetUrl: TARGET_URL },
+ });
+ expect(await listWebhookIds()).not.toContain(webhookId);
+ });
+
+ it('should refuse delete_webhook with an id that is not a UUID', async () => {
+ const output = await executeToolThroughMcp({
+ toolName: 'delete_webhook',
+ toolArguments: { id: 'not-a-uuid' },
+ });
+
+ expect(output).toMatchSnapshot();
+ });
+});