♻️ refactor: introduce ToolExecutor field orthogonal to ToolSource (#13760)

Add ToolExecutor ('client' | 'server') as a new orthogonal dimension
alongside ToolSource to describe where a tool invocation is dispatched.
Thread executorMap through OperationToolSet / ResolvedToolSet / AgentState
and attach executor to the ChatToolPayload emitted in onToolsCalling.

Defaults remain empty (all server-side), so behavior is unchanged. This
is pure scaffolding to unblock subsequent work on client-side dispatch.

Also remove the unused 'plugin' value from ToolSource (no downstream
consumers branched on it; installed plugins now labeled 'mcp').

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/agent-runtime/src/types/state.ts

@@ -2,6 +2,7 @@ import type {
   ActivatedStepSkill,
   ActivatedStepTool,
   OperationToolSet,
+  ToolExecutor,
   ToolSource,
 } from '@lobechat/context-engine';
 import type {
@@ -122,6 +123,9 @@ export interface AgentState {
   stepCount: number;
 
   systemRole?: string;
+  /** Tool executor map for routing tool execution between server and client */
+  toolExecutorMap?: Record<string, ToolExecutor>;
+
   toolManifestMap: Record<string, any>;
 
   tools?: any[];

packages/context-engine/src/engine/tools/ToolResolver.ts

@@ -4,6 +4,7 @@ import type {
   OperationToolSet,
   ResolvedToolSet,
   StepToolDelta,
+  ToolExecutor,
   ToolSource,
   UniformTool,
 } from './types';
@@ -32,6 +33,7 @@ export class ToolResolver {
     // Start from operation-level snapshot (shallow copies, with safe defaults)
     const tools: UniformTool[] = [...(operationToolSet.tools ?? [])];
     const sourceMap: Record<string, ToolSource> = { ...operationToolSet.sourceMap };
+    const executorMap: Record<string, ToolExecutor> = { ...operationToolSet.executorMap };
     const enabledToolIds: string[] = [...(operationToolSet.enabledToolIds ?? [])];
 
     // Only include manifests for enabled tools to prevent injecting
@@ -57,6 +59,7 @@ export class ToolResolver {
     if (stepDelta.deactivatedToolIds?.includes('*')) {
       return {
         enabledToolIds: [],
+        executorMap,
         manifestMap, // keep manifests for ToolNameResolver
         sourceMap,
         tools: [],
@@ -75,6 +78,7 @@ export class ToolResolver {
 
     return {
       enabledToolIds: [...new Set(enabledToolIds)],
+      executorMap,
       manifestMap,
       sourceMap,
       tools: dedupedTools,

packages/context-engine/src/engine/tools/index.ts

@@ -28,6 +28,7 @@ export type {
   PluginEnableChecker,
   ResolvedToolSet,
   StepToolDelta,
+  ToolExecutor,
   ToolNameGenerator,
   ToolsEngineOptions,
   ToolsGenerationContext,

packages/context-engine/src/engine/tools/types.ts

@@ -160,7 +160,13 @@ export interface UniformTool {
 
 // ---- Tool Lifecycle Types ----
 
-export type ToolSource = 'builtin' | 'client' | 'plugin' | 'mcp' | 'klavis' | 'lobehubSkill';
+export type ToolSource = 'builtin' | 'client' | 'mcp' | 'klavis' | 'lobehubSkill';
+
+/**
+ * Where the tool is executed for a given invocation.
+ * Orthogonal to ToolSource (origin): executor describes dispatch target.
+ */
+export type ToolExecutor = 'client' | 'server';
 
 /**
  * How a tool was activated at step level
@@ -172,6 +178,7 @@ export type ActivationSource = 'active_tools' | 'mention' | 'device' | 'discover
  */
 export interface OperationToolSet {
   enabledToolIds: string[];
+  executorMap?: Record<string, ToolExecutor>;
   manifestMap: Record<string, LobeToolManifest>;
   sourceMap: Record<string, ToolSource>;
   tools: UniformTool[];
@@ -205,6 +212,7 @@ export interface StepToolDelta {
  */
 export interface ResolvedToolSet {
   enabledToolIds: string[];
+  executorMap?: Record<string, ToolExecutor>;
   manifestMap: Record<string, LobeToolManifest>;
   sourceMap: Record<string, ToolSource>;
   tools: UniformTool[];

packages/types/src/message/common/tools.ts

@@ -25,11 +25,21 @@ export interface ChatPluginPayload {
 /**
  * Tool source indicates where the tool comes from
  */
-export type ToolSource = 'builtin' | 'client' | 'plugin' | 'mcp' | 'klavis' | 'lobehubSkill';
+export type ToolSource = 'builtin' | 'client' | 'mcp' | 'klavis' | 'lobehubSkill';
+
+/**
+ * Tool executor indicates where the tool is executed for a given invocation.
+ * Orthogonal to ToolSource (origin): executor describes dispatch target.
+ */
+export type ToolExecutor = 'client' | 'server';
 
 export interface ChatToolPayload {
   apiName: string;
   arguments: string;
+  /**
+   * Tool executor: dispatch target for this invocation.
+   */
+  executor?: ToolExecutor;
   id: string;
   identifier: string;
   intervention?: ToolIntervention;

src/server/modules/AgentRuntime/RuntimeExecutors.ts

@@ -250,6 +250,7 @@ export const createRuntimeExecutors = (
     const activeDeviceId = state.metadata?.activeDeviceId;
     const operationToolSet: OperationToolSet = state.operationToolSet ?? {
       enabledToolIds: [],
+      executorMap: state.toolExecutorMap ?? {},
       manifestMap: state.toolManifestMap ?? {},
       sourceMap: state.toolSourceMap ?? {},
       tools: state.tools ?? [],
@@ -769,9 +770,10 @@ export const createRuntimeExecutors = (
               },
               onToolsCalling: async ({ toolsCalling: raw }) => {
                 const resolvedCalls = new ToolNameResolver().resolve(raw, resolved.manifestMap);
-                // Add source field from resolved sourceMap for routing tool execution
+                // Attach source (origin) and executor (dispatch target) for routing
                 const payload = resolvedCalls.map((p) => ({
                   ...p,
+                  executor: resolved.executorMap?.[p.identifier],
                   source: resolved.sourceMap[p.identifier],
                 }));
                 // log(`[${operationLogId}][toolsCalling]`, payload);

src/server/services/agentRuntime/AgentRuntimeService.ts

@@ -312,6 +312,7 @@ export class AgentRuntimeService {
         status: 'idle',
         stepCount: initialStepCount,
         // Backward-compat: resolved tool fields read by RuntimeExecutors
+        toolExecutorMap: operationToolSet.executorMap,
         toolManifestMap: operationToolSet.manifestMap,
         toolSourceMap: operationToolSet.sourceMap,
         tools: operationToolSet.tools,

src/server/services/agentRuntime/types.ts

@@ -1,5 +1,10 @@
 import { type AgentRuntimeContext, type AgentState } from '@lobechat/agent-runtime';
-import type { LobeToolManifest, OperationSkillSet, ToolSource } from '@lobechat/context-engine';
+import type {
+  LobeToolManifest,
+  OperationSkillSet,
+  ToolExecutor,
+  ToolSource,
+} from '@lobechat/context-engine';
 import { type UserInterventionConfig } from '@lobechat/types';
 
 import { type ServerUserMemoryConfig } from '@/server/modules/Mecha/ContextEngineering/types';
@@ -10,6 +15,7 @@ import { type AgentHook } from './hooks/types';
 
 export interface OperationToolSet {
   enabledToolIds?: string[];
+  executorMap?: Record<string, ToolExecutor>;
   manifestMap: Record<string, LobeToolManifest>;
   sourceMap?: Record<string, ToolSource>;
   tools?: any[];

src/server/services/aiAgent/index.ts

@@ -13,6 +13,7 @@ import { LOADING_FLAT } from '@lobechat/const';
 import type {
   AgentManagementContext,
   LobeToolManifest,
+  ToolExecutor,
   ToolSource,
 } from '@lobechat/context-engine';
 import { SkillEngine } from '@lobechat/context-engine';
@@ -455,6 +456,7 @@ export class AiAgentService {
     };
     const toolManifestMap: Record<string, any> = {};
     const toolSourceMap: Record<string, ToolSource> = {};
+    const toolExecutorMap: Record<string, ToolExecutor> = {};
     let onlineDevices: DeviceAttachment[] = [];
     let activeDeviceId: string | undefined;
     let hasAgentDocuments = false;
@@ -1141,6 +1143,7 @@ export class AiAgentService {
         stream,
         toolSet: {
           enabledToolIds: toolsResult.enabledToolIds,
+          executorMap: toolExecutorMap,
           manifestMap: toolManifestMap,
           sourceMap: toolSourceMap,
           tools,

src/store/chat/slices/plugin/actions/internals.ts

@@ -35,15 +35,14 @@ export class PluginInternalsActionImpl {
     const manifests: Record<string, ToolManifest> = {};
 
     // Track source for each identifier
-    const sourceMap: Record<string, 'builtin' | 'plugin' | 'mcp' | 'klavis' | 'lobehubSkill'> = {};
+    const sourceMap: Record<string, 'builtin' | 'mcp' | 'klavis' | 'lobehubSkill'> = {};
 
-    // Get all installed plugins
+    // Get all installed plugins (all treated as MCP now)
     const installedPlugins = pluginSelectors.installedPlugins(toolStoreState);
     for (const plugin of installedPlugins) {
       if (plugin.manifest) {
         manifests[plugin.identifier] = plugin.manifest as ToolManifest;
-        // Check if this plugin has MCP params
-        sourceMap[plugin.identifier] = plugin.customParams?.mcp ? 'mcp' : 'plugin';
+        sourceMap[plugin.identifier] = 'mcp';
       }
     }