fix(tool): update ToolProviderItem type to use ChatCompletionTool and adjust related logic

Author: gene9831

docs/src/tools/message.md

@@ -280,10 +280,10 @@ type ToolSource =
   | { type: 'unknown' }
 ```
 
-`ToolProviderItem` 表示可提供给模型的工具项，可以是普通 OpenAI function tool schema，也可以是带本地执行函数的 runtime tool：
+`ToolProviderItem` 表示可提供给模型的工具项，可以是普通 OpenAI tool schema，也可以是带本地执行函数的 runtime tool：
 
 ```typescript
-type ToolProviderItem = ChatCompletionFunctionTool | RuntimeTool
+type ToolProviderItem = ChatCompletionTool | RuntimeTool
 type AsyncStreamableResult<T> = Promise<T> | AsyncGenerator<T> | Promise<AsyncGenerator<T>>
 type MaybeStreamableResult<T> = T | AsyncStreamableResult<T>
 
@@ -293,6 +293,8 @@ interface RuntimeTool {
 }
 ```
 
+`toolPlugin` 会保留请求体中已有的 OpenAI `custom` tool，也允许 `getTools` / `provideTools` 返回普通 `ChatCompletionTool`。其中只有 function tool 会参与工具名去重、`toolSource` 记录和 runtime handler 路由；runtime tool 的 `tool` 字段仍需是 `ChatCompletionFunctionTool`。
+
 `ToolProvider` 是供插件扩展使用的高级协议。对于使用 `toolPlugin` 的业务代码，通常只需要通过 `getTools` 和 `callTool` 接入工具；当插件本身需要按内部状态向模型暴露工具时，再实现 `provideTools(context)`。
 
 ##### 基础示例

packages/kit/src/message/plugins/toolPlugin.ts

@@ -3,6 +3,7 @@ import {
   ChatCompletionFunctionTool,
   ChatCompletionMessageFunctionToolCall,
   ChatCompletionMessageToolCall,
+  ChatCompletionTool,
 } from 'openai/resources'
 import type { MaybePromise, MaybeStreamableResult } from '../../types'
 import type { BasePluginContext, ChatMessage, MessageEnginePlugin, MutateMessageStateFn } from '../types'
@@ -32,7 +33,7 @@ export interface RuntimeTool {
   ) => MaybeStreamableResult<string | Record<string, any>>
 }
 
-export type ToolProviderItem = ChatCompletionFunctionTool | RuntimeTool
+export type ToolProviderItem = ChatCompletionTool | RuntimeTool
 
 export interface ToolProvider {
   provideTools: (context: BasePluginContext) => MaybePromise<ToolProviderItem[]>
@@ -228,6 +229,10 @@ export const toolPlugin = (
     return toolCall.type === 'function' && 'function' in toolCall
   }
 
+  const isFunctionTool = (tool: ChatCompletionTool): tool is ChatCompletionFunctionTool => {
+    return tool.type === 'function' && 'function' in tool
+  }
+
   const isRuntimeTool = (tool: ToolProviderItem): tool is RuntimeTool => {
     return Boolean(tool && typeof tool === 'object' && 'tool' in tool && 'handler' in tool)
   }
@@ -241,7 +246,18 @@ export const toolPlugin = (
     return typeof plugin.disabled === 'function' ? plugin.disabled(context) : Boolean(plugin.disabled)
   }
 
-  const resolveTools = async (context: BasePluginContext, existingTools: ChatCompletionFunctionTool[] = []) => {
+  type ResolvedTools = {
+    tools: ChatCompletionTool[]
+    runtimeToolMap: Map<string, RuntimeTool>
+    toolSourceMap: Map<string, ToolSource>
+  }
+
+  let currentToolResolution: ResolvedTools | undefined
+
+  const resolveTools = async (
+    context: BasePluginContext,
+    existingTools: ChatCompletionTool[] = [],
+  ): Promise<ResolvedTools> => {
     const providedToolItems: Array<{ item: ToolProviderItem; source: ToolSource }> = []
 
     for (const plugin of context.plugins) {
@@ -266,7 +282,7 @@ export const toolPlugin = (
         source: { type: 'toolPlugin' as const },
       })),
     ]
-    const tools: ChatCompletionFunctionTool[] = []
+    const tools: ChatCompletionTool[] = []
     const runtimeToolMap = new Map<string, RuntimeTool>()
     const toolSourceMap = new Map<string, ToolSource>()
     const seenToolNames = new Set<string>()
@@ -283,13 +299,15 @@ export const toolPlugin = (
       seenToolNames.add(toolName)
     }
 
-    existingTools.forEach(registerToolName)
+    existingTools.filter(isFunctionTool).forEach(registerToolName)
 
     for (const { item: toolItem, source } of toolItems) {
       const tool = isRuntimeTool(toolItem) ? toolItem.tool : toolItem
 
-      registerToolName(tool)
-      toolSourceMap.set(tool.function.name, source)
+      if (isFunctionTool(tool)) {
+        registerToolName(tool)
+        toolSourceMap.set(tool.function.name, source)
+      }
 
       if (isRuntimeTool(toolItem)) {
         tools.push(toolItem.tool)
@@ -319,7 +337,9 @@ export const toolPlugin = (
       const { requestBody } = context
 
       const existingTools = Array.isArray(requestBody.tools) ? requestBody.tools : []
-      const { tools } = await resolveTools(context, existingTools)
+      const resolvedTools = await resolveTools(context, existingTools)
+      currentToolResolution = resolvedTools
+      const { tools } = resolvedTools
       if (tools && tools.length > 0) {
         requestBody.tools = existingTools.length ? [...existingTools, ...tools] : tools
       }
@@ -348,7 +368,10 @@ export const toolPlugin = (
         assistantMessage: currentMessage as AssistantMessageWithState,
       })
 
-      const { runtimeToolMap, toolSourceMap } = await resolveTools(context)
+      const { runtimeToolMap, toolSourceMap } = currentToolResolution ?? {
+        runtimeToolMap: new Map<string, RuntimeTool>(),
+        toolSourceMap: new Map<string, ToolSource>(),
+      }
 
       const toolCallPromises = currentMessage.tool_calls.map(async (toolCall) => {
         const now = Math.floor(Date.now() / 1000)
@@ -445,6 +468,7 @@ export const toolPlugin = (
       })
 
       await Promise.all(toolCallPromises)
+      currentToolResolution = undefined
       if (!abortSignal.aborted) {
         requestNext()
       }

packages/kit/src/message/test/toolPlugin.test.ts

@@ -1,4 +1,4 @@
-import type { ChatCompletion } from 'openai/resources'
+import type { ChatCompletion, ChatCompletionFunctionTool, ChatCompletionTool } from 'openai/resources'
 import { describe, expect, it, vi } from 'vitest'
 import { createNativeMessageAdapter } from '../adapters/native'
 import { createMessageEngine } from '../core/engine'
@@ -10,6 +10,11 @@ const silentDefaultPlugins = [thinkingPlugin({ disabled: true }), lengthPlugin({
 const createTestMessageEngine = (options: CreateMessageEngineOptions) =>
   createMessageEngine(createNativeMessageAdapter(), options)
 
+const isFunctionTool = (tool: ChatCompletionTool): tool is ChatCompletionFunctionTool => tool.type === 'function'
+
+const functionToolNames = (tools: ChatCompletionTool[] = []) =>
+  tools.filter(isFunctionTool).map((tool) => tool.function.name)
+
 describe('toolPlugin', () => {
   it('injects and executes runtime tools before falling back to callTool', async () => {
     const runtimeCall = vi.fn(() => ({ result: 'runtime-result' }))
@@ -35,7 +40,7 @@ describe('toolPlugin', () => {
       const hasToolResult = requestBody.messages.some((message) => message.role === 'tool')
 
       if (!hasToolResult) {
-        expect(requestBody.tools?.map((tool) => tool.function.name)).toEqual(['runtime_lookup'])
+        expect(functionToolNames(requestBody.tools)).toEqual(['runtime_lookup'])
         return {
           id: 'tool-call',
           object: 'chat.completion',
@@ -203,7 +208,7 @@ describe('toolPlugin', () => {
       const hasToolResult = requestBody.messages.some((message) => message.role === 'tool')
 
       if (!hasToolResult) {
-        expect(requestBody.tools?.map((tool) => tool.function.name)).toEqual(['provided_tool'])
+        expect(functionToolNames(requestBody.tools)).toEqual(['provided_tool'])
 
         return {
           id: 'provider-tool-call',
@@ -290,4 +295,154 @@ describe('toolPlugin', () => {
       }),
     )
   })
+
+  it('keeps runtime tool handlers stable for the tool list sent to the model', async () => {
+    const runtimeCall = vi.fn(() => 'runtime result')
+    const fallbackCall = vi.fn(() => 'fallback result')
+    const runtimeTool: RuntimeTool = {
+      tool: {
+        type: 'function',
+        function: {
+          name: 'volatile_runtime_tool',
+          description: 'Runtime tool that is only available during request preparation',
+        },
+      },
+      handler: runtimeCall,
+    }
+    let getToolsCalls = 0
+    const responseProvider = vi.fn<ResponseProvider>(async (requestBody) => {
+      const hasToolResult = requestBody.messages.some((message) => message.role === 'tool')
+
+      if (!hasToolResult) {
+        expect(functionToolNames(requestBody.tools)).toEqual(['volatile_runtime_tool'])
+
+        return {
+          id: 'volatile-tool-call',
+          object: 'chat.completion',
+          created: Math.floor(Date.now() / 1000),
+          model: 'mock',
+          choices: [
+            {
+              index: 0,
+              message: {
+                role: 'assistant',
+                content: '',
+                tool_calls: [
+                  {
+                    id: 'call-volatile',
+                    type: 'function',
+                    function: {
+                      name: 'volatile_runtime_tool',
+                      arguments: '{}',
+                    },
+                  },
+                ],
+              },
+              finish_reason: 'tool_calls',
+            },
+          ],
+        } as ChatCompletion
+      }
+
+      expect(requestBody.messages.at(-1)).toMatchObject({
+        role: 'tool',
+        tool_call_id: 'call-volatile',
+        content: 'runtime result',
+      })
+
+      return {
+        id: 'final-answer',
+        object: 'chat.completion',
+        created: Math.floor(Date.now() / 1000),
+        model: 'mock',
+        choices: [
+          {
+            index: 0,
+            message: {
+              role: 'assistant',
+              content: 'done',
+            },
+            finish_reason: 'stop',
+          },
+        ],
+      } as ChatCompletion
+    })
+
+    const engine = createTestMessageEngine({
+      plugins: [
+        ...silentDefaultPlugins,
+        toolPlugin({
+          getTools: async () => {
+            getToolsCalls++
+            return getToolsCalls === 1 ? [runtimeTool] : []
+          },
+          callTool: fallbackCall,
+        }),
+      ],
+      responseProvider,
+    })
+
+    await engine.sendMessage('call volatile tool')
+
+    expect(runtimeCall).toHaveBeenCalledOnce()
+    expect(fallbackCall).not.toHaveBeenCalled()
+  })
+
+  it('keeps custom tools already present on the request body', async () => {
+    const customTool = {
+      type: 'custom',
+      custom: {
+        name: 'custom_formatter',
+        description: 'Format with custom grammar',
+        format: {
+          type: 'grammar',
+          grammar: {
+            syntax: 'lark',
+            definition: 'start: "ok"',
+          },
+        },
+      },
+    } satisfies ChatCompletionTool
+    const responseProvider = vi.fn<ResponseProvider>(async (requestBody) => {
+      expect(requestBody.tools).toEqual([customTool])
+
+      return {
+        id: 'final-answer',
+        object: 'chat.completion',
+        created: Math.floor(Date.now() / 1000),
+        model: 'mock',
+        choices: [
+          {
+            index: 0,
+            message: {
+              role: 'assistant',
+              content: 'done',
+            },
+            finish_reason: 'stop',
+          },
+        ],
+      } as ChatCompletion
+    })
+
+    const engine = createTestMessageEngine({
+      plugins: [
+        ...silentDefaultPlugins,
+        {
+          name: 'custom-tool-plugin',
+          onBeforeRequest: (context) => {
+            context.requestBody.tools = [customTool]
+          },
+        },
+        toolPlugin({
+          getTools: async () => [],
+          callTool: async () => 'fallback',
+        }),
+      ],
+      responseProvider,
+    })
+
+    await engine.sendMessage('use custom tool')
+
+    expect(responseProvider).toHaveBeenCalledOnce()
+  })
 })

packages/kit/src/message/types.ts

@@ -2,7 +2,7 @@
 import {
   ChatCompletion,
   ChatCompletionChunk,
-  ChatCompletionFunctionTool,
+  ChatCompletionTool,
   ChatCompletionMessageParam,
   ChatCompletionMessageToolCall,
 } from 'openai/resources'
@@ -33,7 +33,7 @@ export type ChatMessage<
 
 export interface MessageRequestBody {
   messages: Array<ChatMessage>
-  tools?: Array<ChatCompletionFunctionTool>
+  tools?: Array<ChatCompletionTool>
   [key: string]: any
 }