refactor(agents): split tool resolution into native and action rails (#20331)

## Summary

Splits AI agent tool resolution into two independent rails:

- **Native tools** — capabilities baked into the model SDK
(Anthropic/OpenAI `web_search`, xAI `web`/`x` provider options). Bound
by `NativeToolBinderService`, controlled by per-agent
`modelConfiguration` toggles. Opaque to Twenty — executed on the model
provider's servers.
- **Action tools** — registry-scoped tools from `ToolRegistryService`
(code interpreter, send email, record CRUD, etc.). Permission-gated via
the agent's role. Executed on Twenty's server.

Both rails merge into a single `ToolSet` at call time. When both
surfaces expose a search tool the model picks at runtime — coexistence
is intentional (relevant once Exa returns as an action, see below).

## Notable changes worth calling out

**Contract change: `AgentAsyncExecutorService.executeAgent` no longer
accepts `rolePermissionConfig`.** Workflow agents now scope exclusively
by the agent's own permission-tab role (`unionOf: [agentRoleId]`). The
previous role-merging path (caller role intersected with agent role) is
removed. No agent role → no registry tools (fail-closed by design).

**`NativeToolBinderService` relocated** from
`core-modules/tool-provider/native/` →
`metadata-modules/ai/ai-models/services/`. The binder needs SDK-package
knowledge, which lives in `ai-models`. Old location created a backwards
module dependency.

**`NATIVE_MODEL_TOOLS_BY_SDK_PACKAGE` is exhaustive over
`AiSdkPackage`** (`Record<>`, not `Partial<Record<>>`). Adding a new SDK
without thinking about native tools now fails the build. SDKs without
native tools (Bedrock, Google, Mistral, Azure, OpenAI-compatible) get
explicit `{}` entries.

**Discriminated union `kind: 'sdk-tool' | 'provider-option'`** lets one
registry describe both function tools (Anthropic/OpenAI) and runtime
sources (xAI). Follows the local `tool-provider` convention from #19321.

## Deferred to follow-ups

- **Exa web search is dropped from this PR** (along with its
`WEB_SEARCH_TOOL` permission flag and the Exa-specific gating). Exa
comes back as an **action/app tool** once apps can define permission
flags through the SDK — ongoing work in #20481.
- **xAI native search currently errors.** xAI deprecated its Live Search
API (the `web`/`x` provider-option sources this rail maps to), so xAI
returns `410` when native search is actually exercised. The code path
itself is clear — it's only hit if you test xAI native tools. Fixed
separately alongside the broader xAI model fixes.

## Conscious non-decisions

- **No "twenty-native" category.** `native` is reserved for
model/provider SDK features; everything Twenty-owned is just a
tool/action.
- **Coexistence over precedence.** No rule forcing an action search tool
to override native search (or vice-versa) — when both exist, it's the
user's choice in workflow agents and the model's choice in chat.

---------

Co-authored-by: Félix Malfait <felix.malfait@gmail.com>
Co-authored-by: Félix Malfait <felix@twenty.com>

packages/twenty-server/src/engine/core-modules/client-config/services/client-config.service.ts

@@ -2,15 +2,8 @@ import { Injectable } from '@nestjs/common';
 
 import { isNonEmptyString } from '@sniptt/guards';
 import { isDefined } from 'twenty-shared/utils';
-import { type AiSdkPackage } from 'twenty-shared/ai';
 
 import { StorageDriverType } from 'src/engine/core-modules/file-storage/interfaces/file-storage.interface';
-
-import {
-  AI_SDK_ANTHROPIC,
-  AI_SDK_BEDROCK,
-  AI_SDK_OPENAI,
-} from 'src/engine/metadata-modules/ai/ai-models/constants/ai-sdk-package.const';
 import { NodeEnvironment } from 'src/engine/core-modules/twenty-config/interfaces/node-environment.interface';
 import { SupportDriver } from 'src/engine/core-modules/twenty-config/interfaces/support.interface';
 
@@ -18,7 +11,6 @@ import { MaintenanceModeService } from 'src/engine/core-modules/admin-panel/main
 import {
   type ClientAiModelConfig,
   type ClientConfig,
-  type NativeModelCapabilities,
 } from 'src/engine/core-modules/client-config/client-config.entity';
 import { DomainServerConfigService } from 'src/engine/core-modules/domain/domain-server-config/services/domain-server-config.service';
 import { PUBLIC_FEATURE_FLAGS } from 'src/engine/core-modules/feature-flag/constants/public-feature-flag.const';
@@ -28,6 +20,7 @@ import {
   AUTO_SELECT_SMART_MODEL_ID,
 } from 'twenty-shared/constants';
 import { MODEL_FAMILY_LABELS } from 'src/engine/metadata-modules/ai/ai-models/constants/model-family-labels.const';
+import { getNativeModelCapabilities } from 'src/engine/metadata-modules/ai/ai-models/utils/get-native-model-capabilities.util';
 import { AiModelRegistryService } from 'src/engine/metadata-modules/ai/ai-models/services/ai-model-registry.service';
 
 @Injectable()
@@ -39,19 +32,6 @@ export class ClientConfigService {
     private maintenanceModeService: MaintenanceModeService,
   ) {}
 
-  private deriveNativeCapabilities(
-    sdkPackage?: AiSdkPackage,
-  ): NativeModelCapabilities | undefined {
-    switch (sdkPackage) {
-      case AI_SDK_OPENAI:
-      case AI_SDK_ANTHROPIC:
-      case AI_SDK_BEDROCK:
-        return { webSearch: true };
-      default:
-        return undefined;
-    }
-  }
-
   private isCloudflareIntegrationEnabled(): boolean {
     return (
       !!this.twentyConfigService.get('CLOUDFLARE_API_KEY') &&
@@ -97,7 +77,7 @@ export class ClientConfigService {
           sdkPackage: registeredModel.sdkPackage,
           providerName,
           providerLabel: getProviderLabel(providerName),
-          nativeCapabilities: this.deriveNativeCapabilities(
+          nativeCapabilities: getNativeModelCapabilities(
             registeredModel.sdkPackage,
           ),
           inputCostPerMillionTokens: modelConfig?.inputCostPerMillionTokens,
@@ -137,6 +117,9 @@ export class ClientConfigService {
             defaultPerformanceModel?.providerName,
           ),
           sdkPackage: defaultPerformanceModel?.sdkPackage ?? null,
+          nativeCapabilities: getNativeModelCapabilities(
+            defaultPerformanceModel?.sdkPackage,
+          ),
           inputCostPerMillionTokens:
             defaultPerformanceModelConfig?.inputCostPerMillionTokens,
           outputCostPerMillionTokens:
@@ -155,6 +138,9 @@ export class ClientConfigService {
           providerName: defaultSpeedModel?.providerName,
           providerLabel: getProviderLabel(defaultSpeedModel?.providerName),
           sdkPackage: defaultSpeedModel?.sdkPackage ?? null,
+          nativeCapabilities: getNativeModelCapabilities(
+            defaultSpeedModel?.sdkPackage,
+          ),
           inputCostPerMillionTokens:
             defaultSpeedModelConfig?.inputCostPerMillionTokens,
           outputCostPerMillionTokens:

packages/twenty-server/src/engine/core-modules/tool-provider/native/native-tool-binder.interface.ts

@@ -1,14 +0,0 @@
-import { type ToolSet } from 'ai';
-
-import { type RegisteredAiModel } from 'src/engine/metadata-modules/ai/ai-models/services/ai-model-registry.service';
-import { type NativeModelToolOptions } from 'src/engine/metadata-modules/ai/ai-models/types/native-model-tool-options.type';
-
-// Parallel to ToolProvider, not a variant of it. A binder produces SDK-native
-// tool objects (Anthropic webSearch, OpenAI webSearch, etc.) that the AI SDK
-// passes straight to the model. These tools are opaque — they can't be
-// serialized into descriptors, don't appear in the tool catalog, and aren't
-// executed by ToolExecutorService. They're merged directly into the ToolSet
-// handed to streamText.
-export interface NativeToolBinder {
-  bind(model: RegisteredAiModel, options: NativeModelToolOptions): ToolSet;
-}

packages/twenty-server/src/engine/core-modules/tool-provider/native/native-tool-binder.service.ts

@@ -1,21 +0,0 @@
-import { Injectable } from '@nestjs/common';
-
-import { type ToolSet } from 'ai';
-
-import { type NativeToolBinder } from 'src/engine/core-modules/tool-provider/native/native-tool-binder.interface';
-
-import { AiModelConfigService } from 'src/engine/metadata-modules/ai/ai-models/services/ai-model-config.service';
-import { type RegisteredAiModel } from 'src/engine/metadata-modules/ai/ai-models/services/ai-model-registry.service';
-import { type NativeModelToolOptions } from 'src/engine/metadata-modules/ai/ai-models/types/native-model-tool-options.type';
-
-@Injectable()
-export class NativeToolBinderService implements NativeToolBinder {
-  constructor(private readonly aiModelConfigService: AiModelConfigService) {}
-
-  bind(
-    model: RegisteredAiModel,
-    options: NativeModelToolOptions = {},
-  ): ToolSet {
-    return this.aiModelConfigService.getNativeModelTools(model, options);
-  }
-}

packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts

@@ -8,7 +8,6 @@ import { DashboardToolProvider } from 'src/engine/core-modules/tool-provider/pro
 import { DatabaseToolProvider } from 'src/engine/core-modules/tool-provider/providers/database-tool.provider';
 import { LogicFunctionToolProvider } from 'src/engine/core-modules/tool-provider/providers/logic-function-tool.provider';
 import { MetadataToolProvider } from 'src/engine/core-modules/tool-provider/providers/metadata-tool.provider';
-import { NativeToolBinderService } from 'src/engine/core-modules/tool-provider/native/native-tool-binder.service';
 import { NavigationMenuItemToolProvider } from 'src/engine/core-modules/tool-provider/providers/navigation-menu-item-tool.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';
@@ -73,7 +72,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
     DashboardToolProvider,
     DatabaseToolProvider,
     MetadataToolProvider,
-    NativeToolBinderService,
     NavigationMenuItemToolProvider,
     LogicFunctionToolProvider,
     ViewToolProvider,
@@ -120,6 +118,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
     },
     ToolRegistryService,
   ],
-  exports: [NativeToolBinderService, ToolRegistryService],
+  exports: [ToolRegistryService],
 })
 export class ToolProviderModule {}